実行順に構成したエンジニアリングガイドです。まずデバイスとネットワークを確認し、次にXcode、署名、CI環境を調べ、最後にストレージ、アップグレード、復旧へ進みます。
接続 → 環境 → ビルド → データ
6つの入口で、本人確認、システム変更、開発ツール、自動化タスク、ネットワーク経路、注文情報を扱います。各項目で、最初に調べること、残す情報、チケットを提出するタイミングを案内します。
接続情報を取得し、ホストフィンガープリントを照合してSSHセッションを確立します。GUIを有効にする前に、基本的なネットワーク問題を切り分けます。
接続手順へ 02 / SYSTEMシステムを変更する前にデータ、バージョン、復旧用資料を保存し、ツールチェーンを検証してから長期タスク用のデバイスで作業します。
アップグレードと復旧を見る 03 / TOOLCHAIN証明書、プロビジョニングプロファイル、Keychain権限、DerivedData、ビルドログの順にXcodeの失敗原因を特定します。
Xcodeのトラブルシューティングへ 04 / RUNNERランナーのID、作業ディレクトリ、キャッシュ範囲、キーの注入方法、失敗後に再現可能なロールバック経路を確認します。
ランナー一覧を見る 05 / NETWORK有線ネットワーク、固定サンプル数、同じ時間帯で5つのノードを比較し、ローカル接続と国際ルーティングの影響を切り分けます。
遅延測定を見る 06 / ORDER注文番号とデバイスIDで問題を関連付けます。ログやチケットに完全なカード番号、秘密鍵、アカウントパスワードを記載しないでください。
チケット資料を準備ホストアドレス、ポート、認証情報を確認する前にクライアントを何度も切り替えないでください。以下の4ステップを順番に実行し、各ステップで次の検証可能な情報を得ます。
コンソールにログインし、対象注文でデバイスID、選択ノード、ホストアドレス、SSHポート、現在の認証情報を確認します。複数デバイスを並行して使う場合は、注文番号とデバイスIDを先に対応付けます。
初回接続では、クライアントに表示されたフィンガープリントをコンソールの記録と照合します。デバイス再インストール後に変化した場合は、変更履歴を確認してからローカルの古い項目を削除し、警告を無視しないでください。
ssh-keygen -R example-host
ssh -p 22 user@example-hostまず有線ネットワークからDNS、ポート、SSHをテストします。成功したらログイン時刻、出口ネットワーク、コマンドラインの応答を記録します。失敗時は完全なエラー情報を残し、「接続に失敗しました」の1行だけを抜き出さないでください。
SSHの基準が安定してから、GUIに必要なアドレス、ポート、クライアントバージョン、ローカルファイアウォールを確認します。画面が途切れる場合は、解像度、エンコード設定、ネットワーク遅延も記録します。
以下は主要都市からシンガポール、日本（東京）、韓国（ソウル）、香港、米国西部へのルート差を示します。データはノード選択の参考であり、アプリのスループット、GUIフレームレート、タスク完了時間を保証するものではありません。
| テスト元 | 通信事業者 | シンガポール | 日本（東京） | 韓国（ソウル） | 香港 | 米国西部 |
|---|---|---|---|---|---|---|
| 上海 | 中国電信 | 71 ms | 42 ms | 46 ms | 34 ms | 141 ms |
| 深圳 | 中国聯通 | 44 ms | 55 ms | 59 ms | 18 ms | 157 ms |
| 北京 | 中国移動 | 91 ms | 48 ms | 39 ms | 63 ms | 138 ms |
LANケーブルで直接接続し、大容量ファイルの同期、ビデオ会議、システムアップデートを停止します。ローカルゲートウェイとノードアドレスを連続してテストし、両方が同時に揺れる場合は、まずローカル接続を対処します。
リモート操作には、パケットロス、ジッター、上り帯域幅、クライアントのエンコードも影響します。ネットワーク問題を提出する際は、通信事業者、都市、テスト時間帯、サンプル数、traceroute結果を併記してください。
同じエラーでも、証明書の利用不可、プロファイル不一致、Keychainのアクセス権、キャッシュ汚染、ビルドパラメータの差異が原因になり得ます。まず元のログを保存し、以下の順に確認してください。
対象証明書が存在し、有効期限内で、証明書と秘密鍵が対応し、現在のビルドユーザーが読み取れることを確認します。まず署名IDを一覧表示し、すべての資料を再インポートしないでください。
security find-identity -v -p codesigning
Bundle Identifier、チームID、証明書タイプ、デバイス範囲、Capability宣言を確認します。手動署名のプロジェクトでは、設定が古いキャッシュではなく対象ファイルを指していることを確認します。
CODE_SIGN_STYLE / PROVISIONING_PROFILE_SPECIFIER
CIユーザーと対話ログインユーザーでは、Keychainの検索リストが異なる場合があります。対象Keychainのロック解除、検索パスへの追加、ビルドプロセスによる秘密鍵の読み取り許可を確認します。
security list-keychains
現在のパスと失敗したタスクを記録してから、対象プロジェクトの派生データだけを削除します。すべてのキャッシュ削除を最初に行うと、比較可能なビルド証拠を失います。
xcodebuild -showBuildSettings
完全なコマンド、Scheme、Configuration、SDK、Xcodeバージョン、終了コード、最初の失敗箇所を保存します。最後の要約行ではなく、最初の根本原因エラーを優先して確認します。
xcodebuild -version
専用の物理Macでビルドタスクを継続実行できますが、安定性はID、ディレクトリ、キャッシュ、キー、ロールバック範囲に左右されます。変更ごとに「何を変え、どう検証し、どう戻すか」を説明できる状態にします。
各デバイスに識別可能なランナー名とタグを付け、登録範囲、サービスユーザー、起動方法を記録します。複数ランナーで判別できない同じ名前を共有しないでください。
リポジトリ、ブランチ、タスク単位で独立したディレクトリを作成し、並列タスクが同じDerivedData、アーカイブ、依存関係の出力先へ書き込まないようにします。
再生成可能なキャッシュと保持必須の成果物を分けます。削除前にディレクトリ容量、最終使用時刻、タスクの所属を記録し、全削除によるコールドスタートを避けます。
キーはタスク実行時だけプロセス環境または一時Keychainに入れ、ログのエコーを無効にします。終了後は一時資料を削除し、アクセスをロックします。
ランナー、Xcode、依存関係を更新する前にバージョン記録を残します。検証に失敗したら、設定ファイル、ツールチェーンの選択、キャッシュインデックスを復元し、変更を重ねないでください。
パスには少なくともプロジェクトID、タスクID、試行回数を含めます。削除処理は今回のタスクディレクトリだけを対象にし、並列ビルドの誤削除を防ぎます。
WORK_ROOT="$HOME/ci-work"
JOB_DIR="$WORK_ROOT/$PROJECT/$RUN_ID"
mkdir -p "$JOB_DIR"ランナーバージョン、ツールチェーンバージョン、完全な終了コード、最初の根本原因ログを保存します。キャッシュヒット率とディスク空き容量もタスク概要に記録し、前後を比較できるようにします。
追加ストレージとThunderbolt 5の並列接続は、データ経路と権限範囲を変えます。フォーマット、マウントポイント変更、デバイス切断の前に、データコピーとタスク停止状態を確認してください。
重要なコード、素材、ビルド成果物、設定は少なくとも1つの独立したコピーを保持します。検証前のボリュームを唯一の保存先にしないでください。
ボリューム名、ファイルシステム、容量、デバイスID、想定マウントポイントを記録し、表示順だけで対象ディスクを判断しないでください。
ビルドまたはメディアタスクを実行するユーザーが必要なディレクトリ権限を持つことを確認します。所有権の問題を回避するために全体の権限を緩めないでください。
削除可能なテストファイルで作成、読み取り、名前変更、削除を確認してから、実際の作業ディレクトリを移行します。
各Mac、ケーブルの向き、共有ストレージ、タスクの役割を示します。上流・下流のデバイスを特定できない状態で接続を変更しないでください。
どのデバイスが書き込み、どれが読み取り専用かを決め、自動化タスクには独立したディレクトリを設定して同時上書きを防ぎます。
デバイスを1台追加するたびに接続、権限、読み書きをテストします。すべて配線してからまとめて調査しないでください。
まず書き込みとビルドタスクを停止し、キャッシュがディスクに反映されたことを確認してからボリュームをアンマウントし、経路末端からデバイスを切断します。
すべてのノードは365日継続稼働しています。macOSとツールチェーンのアップグレードはタスクの進行に合わせて変更時間を設定し、まず重要度の低いタスクで検証してから長期稼働ランナーへ展開します。
コードの状態、依存関係ロックファイル、Homebrew一覧、Xcodeパス、証明書名、Keychain一覧、ランナー設定、ディスク空き容量をエクスポートします。
プライベート設定、署名資料、ビルド成果物、プロジェクトデータを独立した場所へ移し、少なくとも1ファイルを実際に復元できることを確認します。
対象macOS、Xcode、コマンドラインツール、パッケージマネージャー、ランナー、プロジェクト依存関係の互換範囲を確認し、保持必須の旧バージョンを記録します。
CIキュー、素材処理、データ同期を停止し、作業ディレクトリ、キャッシュ、追加ストレージへ書き込むプロセスがないことを確認します。
アップグレード後、SSH、ディスク、Xcodeバージョン、証明書読み取り、依存関係復元、テスト、アーカイブ、成果物ダウンロードを順番に検証します。
最初に成功したタスクの所要時間、ログ、キャッシュ状態、ディスク空き容量を保存してから、並列タスクを段階的に戻します。キューを一度に全開放しないでください。
根本原因が明確になる前に複数のコンポーネントを連続してアップグレードすると、システム、ツールチェーン、プロジェクト設定の影響をログで切り分けられなくなります。
既存の注文に関する問題は、デバイスID、再現手順、完全なエラーコンテキストを添えてコンソールからチケットを提出してください。未注文の構成に関する質問は、専用のサポートメールでお問い合わせいただけます。
support@vmdebug.com