認証情報は現在のノードに対応しているか
ユーザー名、鍵、接続パスワードが現在の注文のものか確認し、終了した注文の接続情報を再利用しないでください。鍵ファイルの権限や、コピー時に空白・改行が加わっていないかも確認します。
作業復旧への道筋
接続確認からビルドログまで、手順に沿って問題を特定
iOS、macOS、CI/CD、Apple Siliconの検証環境向けトラブルシューティングガイドです。まずノードとネットワークを確認し、次にツールチェーンとジョブログを調べて、複数の変数を同時に変更しないようにします。
5
段階の接続チェック
4
種類のビルドトラブル
6
提供中のノード
実行票
まず現状を保存し、一つずつ切り分ける
READY
A01
ノード情報を確認
リージョン、ホストアドレス、接続方式、注文ステータス
01
A02
ローカル経路を検証
DNS、ポート、ファイアウォール、パケットロス、ジッター
02
A03
ツールチェーンを絞り込む
Xcode、SDK、依存関係、署名、テスト
03
A04
最小限の証拠を提出
発生時刻、再現手順、ログ、影響範囲
04
パスワード、秘密鍵、リカバリーコードは送信しないでください
SUPPORT / NODE
初回接続
4ステップで初回接続を完了
コンソールには現在の注文に対応するノード情報が表示されます。項目をコピーする際は元の形式を保ち、アドレス、ユーザー名、ポートを推測で入力しないでください。
-
01
ノード項目を確認
コンソールにログインし、注文、リージョン、ホストアドレス、ユーザー名、許可された接続方式を確認します。ノードはシンガポール、日本（東京）、韓国（ソウル）、香港、米国東部、米国西部のいずれかにあります。
-
02
ローカルネットワークを確認
社内ネットワークが対象ポートを遮断していないことを確認し、経路を書き換える一時プロキシを停止します。有線、無線など各ネットワークでの接続結果を個別に記録してください。
-
03
接続方式を選択
コマンドライン、ファイル同期、自動化タスクにはSSHを優先し、macOSのGUIが必要な場合はVNCを使用します。初回テストでは接続方式を一つに絞り、結果が干渉しないようにします。
-
04
ベースラインを検証
ログイン後、システムバージョン、ディスク空き容量、Xcodeのパス、現在のネットワーク時刻を記録します。まず最小構成のプロジェクトを実行し、その後に完全なプロジェクトとビルドキャッシュを移行します。
初回ログインでは基本経路だけを確認
接続が安定していると確認する前に、プロジェクトを一括アップロードしたり、システム設定を変更したり、CI runnerを登録したりしないでください。再現可能なベースライン結果を先に保存します。
接続診断
SSHとVNCを決められた順番で切り分ける
接続に失敗したら、認証情報からネットワークの外側へ順に確認します。各ステップでは条件を一つだけ変更し、コマンド出力やエラーメッセージを保存してください。
ポートはローカルから到達できるか
コンソールに表示されたポートで接続テストを実行します。タイムアウトは通常ネットワーク経路を示し、即時拒否は対象に到達できているもののサービスまたはポートが一致していない可能性を示します。
ローカルファイアウォールが遮断していないか
端末セキュリティソフト、企業の出口ポリシー、ルーターのルールを確認します。既知の正常な別ネットワークで再テストすると、ローカル制限とノード側の問題をすばやく切り分けられます。
ネットワーク経路は安定しているか
遅延、ジッター、パケットロスを記録し、1回のpingだけで判断しないでください。VNCは連続したジッターの影響を受けやすく、SSHビルドもダウンロード接続のリセットで中断することがあります。
ノードの状態は正常か
コンソールに戻り、インスタンスと注文の状態を確認します。複数のネットワークから接続できず、認証情報にも問題がなければ、発生時刻とエラー原文を保存してノード障害チケットを送信します。
ツールチェーン確認
Xcodeの問題はバージョン選択を確認してからプロジェクトを調べる
同じコミットでも、ツールチェーンが違えば結果が変わることがあります。システム環境とプロジェクトの依存関係を分けて検証し、障害がノード、ツールチェーン、リポジトリ設定のどこにあるかを判断します。
バージョンとパス
- 実行
xcodebuild -versionして、Xcodeとビルドのバージョンを記録します。 - 実行
xcode-select -pして、Command Line Toolsが想定したディレクトリを指していることを確認します。 - スクリプトに古いXcodeのパスがハードコードされていないか確認します。
SDKと依存関係
- scheme、destination、SDK名が存在することを確認します。
- Swift Package、CocoaPods、その他のプロジェクト依存関係を再解決します。
- ロックファイル、依存関係の取得元、ダウンロード失敗時の具体的なアドレス種別を比較します。
署名環境
- ビルド設定が読み込む署名用変数が存在するか確認します。
- CIプロセスが必要な素材にアクセスでき、内容をログへ書き込まないことを確認します。
- 署名失敗とコンパイル失敗を分けて再実行し、終了コードを記録します。
BASELINE
推奨する最小環境スナップショット
sw_vers
xcodebuild -version
xcode-select -p
df -h
自動化連携
self-hosted runnerを管理下の実行環境として扱う
runnerの登録に成功しても、ワークフローが安全かつ再現可能になったとは限りません。実行範囲、作業ディレクトリ、認証情報、同時実行ポリシーを同時に整備する必要があります。
実行環境を登録してラベル付け
プロジェクトまたは組織が発行した短期登録情報を使用し、チップ、リージョン、用途を示すラベルを設定します。登録後はローカルの一時コマンド履歴を削除してください。
成果物：runner名とラベル一覧実行範囲を制限
信頼できるリポジトリ、保護ブランチ、明示的なワークフローからの呼び出しだけを許可します。外部コントリビューションが起点のタスクは審査を経由し、未知のスクリプトにノード権限を直接与えないでください。
成果物：リポジトリとブランチの認可ルール作業ディレクトリをクリーンアップ
タスクの前後に一時ファイル、派生データ、不要なキャッシュを処理します。キャッシュを残す場合はキー、取得元、無効化条件を記録し、古い成果物が新しいビルドに影響しないようにします。
成果物：クリーンアップスクリプトとキャッシュ戦略アクセス認証情報をローテーション
トークン、SSH鍵、署名素材は管理された鍵運用プロセスに入れます。メンバーの離脱、リポジトリ権限の変更、異常ログの発生時には直ちに無効化して再発行します。
成果物：認証情報の責任者とローテーション記録
ログの切り分け
最初の有効なエラーからビルド障害の種類を判断する
ログ末尾の一般的な終了コードだけを切り取らないでください。完全なログを保存し、最初にエラーが現れた位置から上へ読み返して、対象、コマンド、依存関係の前後関係を確認します。
| 障害カテゴリ | 一般的なログの兆候 | 最初に確認 | チケットに添付する内容 |
|---|---|---|---|
| 依存関係の解決 | パッケージのバージョン競合、リポジトリ取得失敗、ロックファイルの不一致 | ロックファイル、依存関係の取得元、キャッシュキー、ネットワーク取得結果 | 依存関係の管理方式、失敗したパッケージ名、最初のエラー箇所 |
| 署名設定 | 証明書の照合失敗、権限を利用できない、設定変数の欠落 | scheme、ビルド設定、鍵の注入フロー | 機密情報を除去したエラー原文とビルド対象 |
| テスト失敗 | アサーション失敗、シミュレーター環境の差異、テストのタイムアウト | 失敗したテストケース、destination、並列パラメーター、再試行結果 | テストケース名、終了コード、再現コマンド |
| ネットワーク経由の取得 | 接続リセット、名前解決失敗、ダウンロードタイムアウト | 同じアドレスへの再試行、DNS、プロキシ、出口経路 | 発生時刻、対象の種類、ネットワークテスト結果 |
01
完全な元ログを保存
02
最初の有効なエラーを特定
03
最小コマンドで単独再現
04
認証情報を削除して抜粋を提出
データ運用
プロジェクト、キャッシュ、追加SSDを分けて管理
容量を増やすだけでは、データ分類やバックアップの代わりになりません。まず保存必須のデータを定義し、同期、キャッシュ、移行の方法を決めます。
プロジェクトを同期
ソースコードはまずリポジトリで同期し、大容量バイナリや非公開依存関係は管理されたストレージ運用に置きます。初回移行後、コミットハッシュ、サブモジュール、ロックファイルを比較します。
- ソースコードと設定を分けて確認
- 大容量ファイルの同期方法を記録
- 移行後に最小ビルドを実行
キャッシュをクリーンアップ
DerivedData、パッケージキャッシュ、runnerの作業ディレクトリは再現性に影響することがあります。削除前にディレクトリ容量とキャッシュキーを記録し、削除後にビルド時間とエラーの変化を比較します。
- まずディスク空き容量を確認
- 再生成できるデータだけを削除
- 同時実行タスクが同じキャッシュを変更しないようにする
追加SSDの利用範囲
追加SSDは、より広い作業領域が必要なプロジェクト、キャッシュ、データセットに使用します。正式運用の前に、マウントポイント、読み書きパス、タスク権限を確認してください。
- データの保存先を明確にする
- 増加速度と残容量を監視
- 移行前にファイルの完全性を検証
移行前に必要なコピーをユーザー側で保管
プロジェクトデータ、署名素材、認証情報、ビルド成果物はチームの方針に沿ってバックアップしてください。利用期間の終了前に移行を完了し、コピーを読み取れることを確認します。ノード上の1つだけのコピーを長期アーカイブと見なさないでください。
チケット用証拠セット
1回の送信で切り分けに必要な情報をそろえる
サポート依頼が具体的であるほど、再現と特定にすぐ着手できます。まず影響を説明し、次にタイムラインと最小限のログを提示してください。秘密情報は一切送信しないでください。
依頼テンプレート
項目をコピーして事実を記入
CASE
- ノードのリージョン
- シンガポール、日本（東京）、韓国（ソウル）、香港、米国東部、米国西部
- 発生時刻
- 現地時刻とタイムゾーンを記載し、問題が継続しているか断続的かを説明
- 再現手順
- ログイン、コマンド実行、エラー発生までを実際の順番で記載
- ログ抜粋
- 最初の有効なエラー、終了コード、前後の必要なコンテキストを含める
- 影響範囲
- 単一タスク、単一メンバー、すべてのビルド、ノード全体への接続
- 実施済みの確認
- ネットワーク変更、コマンドの再試行、キャッシュ削除など、実行した操作と結果を列挙
送信してはいけない情報
パスワード、秘密鍵、リカバリーコード、完全なトークン、署名素材、完全な支払い情報。ログに秘密情報が含まれる場合は、明確なマスキング表示に置き換えるか削除してください。
既存の注文に関連付ける
コンソールにログインしてチケットを作成し、該当する注文を選択すると、サポート担当者が正しいノードとサービス履歴を確認しやすくなります。
コンソールにログインしてチケットを作成
エスカレーション手順
問題の種類に応じた対応キューへ進む
接続断、ノード障害、請求に関する質問では必要な証拠が異なります。適切な分類を選び、同じスレッドに資料を追加して、コンテキストが分断されないようにしてください。
認証情報は正しいのにSSHまたはVNCを確立できない
ローカルネットワークの種類、対象ポートのテスト結果、エラー原文、発生時刻を添付してください。別のネットワークで復旧した場合も、2回のテストの違いを記載します。
分類：接続とアクセス複数のタスクが同時に失敗する、またはノードの状態が異常
影響範囲、最後に正常だった時刻、インスタンスの状態、最小再現コマンドを説明します。連続再起動や設定の一括変更で元の状態を上書きしないでください。
分類：ノード稼働注文期間、追加項目、支払い記録の確認が必要
注文ID、請求期間、関連する追加項目、問題の内容を提示します。すべての注文は米ドル（USD）で決済されます。チケットには完全な支払い情報を送信しないでください。
分類：注文と請求
同じスレッドで継続的に追跡
コンソールでチケットを追跡
進捗、追加の質問、最終結論はすべてコンソールの該当チケットで更新します。新しいログを追加する際は、取得時刻と今回の変更内容を明記して、前後の結果を比較できるようにしてください。
ノード情報を準備して、再現可能なトラブルシューティングを始める
新規注文では2種類の構成と6つのノードから選択できます。既存注文の問題は、コンソールにログインして関連チケットを送信してください。