症状から調べる

接続とビルドの問題を検証可能な手順に分解

このガイドを最初から最後まで読む必要はありません。接続、環境、自動化、ネットワーク、ストレージから入口を選び、アドレス、権限、ツールのバージョン、ログを順に確認してください。各ステップに期待される結果を示しているので、自分で調べ続けるか、サポートチケットを送るかを判断できます。

トラブルシューティングの入口を見る コンソールからチケットを送信
6カテゴリ ドキュメントの入口
2種類 リモート接続方法
5項目 症状別の判断ルート
ドキュメント目次

今行っている作業を選択

各入口から、このページ内の具体的な確認項目に移動できます。一度に変更するのは1つの変数だけにし、変更前後のコマンド、バージョン、結果を記録することをおすすめします。

初回接続 認証情報を準備し、ホストフィンガープリントを確認して、キーを交換したうえで正しくセッションを終了します。 CONNECT 開発環境 Xcode のパス、ビルドターゲット、依存関係の解決、ログの保存先を確認します。 TOOLCHAIN 自動ビルド self-hosted runner を登録し、ラベル、同時実行数、作業ディレクトリを計画します。 RUNNER ネットワークアクセス 詳細ログを使って、アドレスの誤り、ポート到達不可、タイムアウト、認証失敗を切り分けます。 NETWORK ストレージ管理 DerivedData、キャッシュ、アーカイブ、作業ディレクトリの容量使用状況を特定します。 STORAGE トラブルシューティング 5種類の症状から判断ツリーに入り、次に検証すべき操作を確認します。 RESOLVE
トラブルシューティングの原則： Xcode のアップグレード、依存関係の交換、ネットワークの切り替え、署名設定の変更を同時に行わないでください。一度に1項目だけ変更することで、結果から本当の原因を判断できます。
リモート接続

SSH と VNC では確認手順が異なります

SSH はコマンドライン操作、自動化、ファイル転送に適しています。VNC は macOS のグラフィカルインターフェースが必要な作業向けです。どちらも、まずノードのアドレスを確認してから認証情報を検証してください。

コマンドライン

SSH 接続チェック

  1. 01
    接続情報を準備

    注文の引き渡し情報で、ホストアドレス、ポート、ユーザー名、一時アクセス方法を確認します。古いターミナル履歴から、変更されている可能性のあるアドレスをコピーしないでください。

  2. 02
    初回検証を実行

    信頼できるネットワークで詳細モードの接続を実行し、ホストフィンガープリントを確認してから続行します。フィンガープリントが引き渡し情報と一致しない場合は、直ちに中止してください。

  3. 03
    一時認証情報を交換

    自分の SSH 公開鍵を authorized_keys に登録し、新しいセッションでログインできることを確認してから、不要になった一時アクセス項目を削除します。

  4. 04
    セッションを正しく終了

    フォアグラウンドのタスクを停止し、ログが書き込まれたことを確認してから exit で終了します。リリース処理を実行中のターミナルを直接閉じないでください。

  5. 05
    アクセス異常を確認

    タイムアウトならまずネットワークとポートを確認します。接続拒否ならアドレスとサービスの状態を確認し、認証失敗ならユーザー名、キーの権限、authorized_keys を確認してください。

グラフィカルインターフェース

VNC 接続チェック

  1. 01
    クライアントとアドレスを準備

    信頼できる VNC クライアントを使用し、引き渡し情報に従ってノードのアドレスとポートを入力します。接続前に、クライアントの不要な認証情報保存機能を無効にしてください。

  2. 02
    初回画面を確認

    想定した macOS のグラフィカルインターフェースが表示されていることを確認し、地域とデバイス設定を確認します。画面に異常がある場合は、すぐにコードや証明書をインポートしないでください。

  3. 03
    アクセス認証情報を更新

    一時パスワードを交換して接続を再確立し、新しい認証情報が有効であることを確認します。完全な認証情報をチームのチャット履歴やビルドスクリプトに保存しないでください。

  4. 04
    アイドルセッションを終了

    作業を保存し、機密性の高いウィンドウを閉じてからセッションを終了します。複数人で作業する場合は、現在の利用者と実行中のグラフィカルタスクを記録してください。

  5. 05
    画面の異常を特定

    画面が真っ黒なら再接続してセッション状態を確認します。動作が重い場合は表示品質を下げてください。接続できない場合は、アドレス、ポート、ローカルネットワークに戻って確認します。

接続診断ログ

SSH の詳細ログを読み、何度も再試行しない

詳細モードでは、接続がネットワーク、フィンガープリント、認証のどの段階で停止したかを確認できます。以下のアドレスは例示用です。実際の接続情報は注文の引き渡し内容に従ってください。

support-check · ssh diagnostic 
$ ssh -v -p 22 build@203.0.113.24
OpenSSH: reading configuration data
debug1: Connecting to 203.0.113.24 port 22
debug1: Connection established
debug1: identity file ~/.ssh/id_ed25519 type 3

The authenticity of host cannot be established.
ED25519 key fingerprint is SHA256:verify-with-delivery-record
Continue connecting only after fingerprint verification.

debug1: Server host key accepted
debug1: Offering public key: ~/.ssh/id_ed25519
debug1: Authentication succeeded (publickey)
Connected to the dedicated physical Mac node

$ sw_vers
ProductName: macOS

$ exit
Connection closed.
TIMEOUT

Connecting のまま長時間停止する

まず、正常に動作すると確認できているネットワークに切り替え、アドレスとポートが正しいか確認します。複数のネットワークでタイムアウトする場合は、発生時刻、ローカルの出口環境、完全なログを記録してください。

FINGERPRINT

ホストフィンガープリントが記録と一致しない

接続を中止し、ローカルの既知のホスト記録を削除して再試行しないでください。まず注文のノードと引き渡し情報を確認し、変更理由をチケットで確認してください。

AUTH

ネットワークは接続できるが認証に失敗する

ユーザー名、秘密鍵のパス、ファイル権限、公開鍵が authorized_keys に完全に登録されているかを確認します。ログを提出する際はキーの内容を隠し、認証段階の情報だけを残してください。

開発ツールチェーン

まず Xcode の選択を固定し、次にプロジェクトのエラーを確認する

ビルドマシンで最も起こりやすい環境差異は、コマンドラインツールのパス、ターゲット名、依存関係の状態、署名変数の不一致から生じます。まずマシンレベルを検証し、その後プロジェクトレベルを確認してください。

XCODE

コマンドラインツールの選択を確認

実行 xcode-select -p で現在のパスを確認し、次に xcodebuild -version でバージョンを確認します。バージョンを切り替えたらターミナルを開き直し、後続タスクで一貫した環境を使えるようにします。

期待値：パスとバージョンが一致
TARGET

利用可能なターゲットを一覧表示

まず xcodebuild -listを実行し、workspace、project、scheme、configuration の名前を確認してから、正確な名前を自動化コマンドに記述します。

期待値：ターゲットを一覧表示できる
SIGNING

署名変数とプロジェクト設定を分離

ビルドに必要な変数が現在のセッションに存在するか確認し、機密値をリポジトリに書き込まないでください。変数の存在だけを出力し、ログに完全な内容を表示しないでください。

期待値：変数が存在し、漏えいしない
LOGS

ビルド記録を完全に保存

各タスクについて、コマンド、開始時刻、終了コード、ビルドログ、成果物のパスを保存します。失敗時は最初のエラー周辺のコンテキストも残し、末尾の概要だけをコピーしないでください。

期待値：失敗を再現できる
自動ビルド

self-hosted runner を識別・分離し、正しく登録解除する

runner の登録で重要なのは、最初のタスクを成功させることだけではありません。後続タスクがどのノードのどのディレクトリで実行されるかを把握でき、無効化時に登録関係を整理できる状態にすることが重要です。

  1. 01

    登録前に実行IDを確認

    専用の実行IDと作業ディレクトリを作成し、そのIDでリポジトリの読み取りとビルドディレクトリへの書き込みができることを確認します。ただし、ビルドに関係のない管理権限は標準で付与しないでください。

    検証：同じIDで手動タスクを完了できる
  2. 02

    実際の能力をラベルで表す

    ラベルには地域、チップファミリー、Xcode のメジャーバージョン、用途を記述します。「最新」「最速」のように時間とともに不正確になるラベルは使わないでください。

    検証：スケジュール条件が対象ノードに一意に一致する
  3. 03

    作業ディレクトリを分離

    リポジトリやパイプラインごとに独立したサブディレクトリを使い、キャッシュディレクトリは分けて管理します。タスク終了後に一時ファイルを削除しますが、再利用が必要で出所が明確なキャッシュは残してください。

    検証：2つのタスクが互いの成果物を上書きしない
  4. 04

    同時実行と競合を制限

    まずは1タスクで実行し、CPU、メモリ、ディスク、ビルド時間を観察してから同時実行数を増やすか判断します。グラフィカルタスクと大規模ビルドを記録なしに同時実行しないでください。

    検証：ピーク時にスワップ領域が継続的に増加しない
  5. 05

    無効化時に完全に登録解除

    まず新しいタスクの受け付けを停止し、現在のタスクが完了するのを待ちます。その後、自動化プラットフォームから runner の登録を解除し、登録トークンと不要になった作業ディレクトリを削除します。

    検証：古いラベルがタスクを受け付けない
同じ作業ディレクトリを複数の同時実行タスクに割り当てないでください。 依存関係キャッシュ、DerivedData、アーカイブ、一時的な署名ファイルが互いに上書きされ、一見ランダムなビルド失敗を引き起こすことがあります。
用語集

まず8つの用語の意味を統一

チケットとチームのドキュメントで同じ用語を使うと、ネットワーク、デバイス、セッション、ビルドツールを混同して説明するのを防げます。

物理ノード
macOS を実際に実行するハードウェアデバイス。BookaMac の注文は物理 Mac mini に対応しており、抽象化された共有コンピューティングインスタンスではありません。
専有
レンタル期間中、注文に応じて1人の顧客がそのデバイスを使用し、同じ物理マシンのワークロードを他の顧客と共有しません。
クラウド Mac
リモートノードにあり、ネットワーク経由でアクセスできる Mac。利用場所とアクセス方法を示す言葉であり、仮想マシンを意味するものではありません。
VNC
macOS のグラフィカルインターフェースをリモートで表示・操作する接続方式。ウィンドウ、表示、対話操作が必要なタスクに適しています。
SSH
暗号化されたコマンドライン接続方式。スクリプトの実行、ファイル転送、ビルドタスクの管理、診断ログの収集に適しています。
self-hosted runner
チームが自ら登録・管理する自動タスク実行環境。指定された専有物理 Mac ノード上でタスクを実行します。
ビルドキャッシュ
繰り返しのダウンロードやコンパイルを減らすために保存する中間データ。タスクを高速化できますが、バージョン変更による環境差異の原因にもなります。
プロビジョニングプロファイル
リリースやテストで使う署名設定用の資材の1つ。プロジェクトの権限に従って管理し、環境の引き継ぎや利用終了時に削除してください。
症状別の判断ツリー

目に見える現象から次の確認へ進む

最も近い症状をまず開いてください。1つの確認項目を完了してから次へ進み、結果を記録せずに途中の手順を飛ばさないでください。

ノードに接続できない：最初に何を確認すべき？
  1. アドレスを確認：現在の注文の引き渡し情報から、ホストアドレス、ポート、ユーザー名をもう一度コピーします。
  2. タイムアウトと拒否を区別：タイムアウトなら通常はまずローカルネットワークまたは経路を確認し、即時に拒否される場合はアドレス、ポート、接続方法を確認します。
  3. 詳細ログを開く：を使って、 ssh -v ネットワーク接続が確立したか、フィンガープリント検証を通過したか、認証がどの段階で止まったかを確認します。
  4. 信頼できる別のネットワークで再テスト：結果が変わった場合は、2つのネットワーク環境を記録し、「たまに接続できる」とだけ報告しないでください。
  5. サポートへエスカレーション：複数のネットワークで失敗する場合は、注文ID、地域、時刻、機密情報を隠した詳細ログを添えてチケットを送信します。
ビルド失敗：Xcode、プロジェクト、依存関係のどれが原因？
  1. バージョンを固定：次の出力を記録します： xcode-select -p と xcodebuild -version 。
  2. ターゲットを一覧表示：scheme、configuration、workspace、project の名前が実際に存在することを確認します。
  3. 最初のエラーを探す：ログから最初に明確に示されたエラーを特定し、最終的な失敗概要から逆算して推測しないでください。
  4. 依存関係を検証：プロジェクトファイルを変更せず、ロックファイルに従って依存関係を再解決し、結果を比較します。
  5. 範囲を絞る：最小ターゲットを単独でビルドし、失敗が環境、プロジェクト設定、特定モジュールのいずれに属するかを判断します。
ディスク容量不足：まず確認すべきディレクトリは？
  1. 全体の使用量を確認：を使って df -h ボリューム全体の空き容量を確認し、単一のプロジェクトディレクトリだけを見ないでください。
  2. 大きなディレクトリを特定：DerivedData、アーカイブ、シミュレータデータ、依存関係キャッシュ、runner の作業ディレクトリを確認します。
  3. キャッシュと成果物を区別：キャッシュは再生成できますが、納品物と診断ログは先にアーカイブしてから削除してください。
  4. 実行中のタスクを停止：削除前に、ビルドが対象ディレクトリへ書き込み中でないことを確認し、壊れた中間状態を避けます。
  5. 増加元を再確認：削除後の次回タスクで増えた容量を観察し、継続的に増加している本当のディレクトリを特定します。
証明書やプロビジョニングプロファイルの異常：無闇な再インストールを避けるには？
  1. エラーの原文を記録：見つからない、期限切れ、権限不足、設定不一致を区別します。
  2. ビルドターゲットを確認：現在の scheme、configuration、署名設定が想定したプロジェクトのものか確認します。
  3. キーチェーンの権限を確認：ビルドを実行するIDが必要な資材にアクセスできることを確認し、無関係な権限を追加しないでください。
  4. プロビジョニングプロファイルを確認：ファイルが現在のタスク要件と一致することを確認し、区別しにくい古いバージョンを複数残さないでください。
  5. 機密資材を保護：チケットにはエラー、名称、必要なメタデータだけを記載し、秘密鍵や完全な認証情報を送信しないでください。
接続やビルドの速度が変動する：問題箇所を判断するには？
  1. 時間範囲を示す：開始時刻、終了時刻、継続しているかどうかを記録し、「最近遅い」だけを説明にしないでください。
  2. 分けて測定：リモート画面、ファイル転送、依存関係のダウンロード、ローカルビルドをそれぞれ観察し、1つの速度評価にまとめないでください。
  3. 同時実行タスクを確認：他のビルド、インデックス作成、トランスコード、モデル処理タスクが同時にリソースを使用していないか確認します。
  4. ネットワークを比較：異なる信頼できるネットワークで同じ操作を再テストし、ローカル経路とリモートタスクの負荷を区別します。
  5. サンプルを保存：地域、時刻、コマンドの所要時間、機密情報を隠したログを提出し、同じ条件で再確認できるようにします。
サポートへの問い合わせ

すぐに調査を始められるチケットに必要な情報

まず事実を整理してから、コンソール経由で送信してください。完全なコンテキストをまとめるほうが、断片的なスクリーンショットを何度も追加するより、通常は早く問題を特定できます。

01

注文ID

必要な注文IDだけを記載し、支払い情報やその他の無関係な情報は送信しないでください。

02

ノードの地域

シンガポール、日本（東京）、韓国（ソウル）、香港のいずれかと、実際の接続方法を記載します。

03

発生時刻

タイムゾーン、初回発生時刻、継続時間、安定して再現できるかどうかを明記します。

04

機密情報を隠したログ

コマンド、終了コード、エラーのコンテキストを残し、トークン、パスワード、秘密鍵、完全な認証情報を隠します。

ドキュメントで再現してから、証拠をチケットに添付

コンソールでは既存の注文を確認し、技術サポートチケットを送信できます。構成を選んでいる段階なら、2種類の専有物理 Mac mini の仕様と適したワークフローを比較できます。

コンソールへ移動 構成を比較