現象からトラブルシューティング

まず問題を特定し、次の手順へ

エラー内容、ツール名、接続方法を入力してください。概念説明だけでなく、デバイスの状態、ログの場所、確認コマンド、サポート依頼に必要な情報を順番に案内します。

クイック振り分け

現在の現象に合う確認ルートを選択

最も近い現象を選び、ページの順序に沿って確認してください。ネットワークとディスクの状態を確認する前に、Xcode、依存関係、Runnerを再インストールしないでください。

デバイスに接続できない 状態、認証情報、ネットワーク、リモートデスクトップ、SSHを確認します。 アーカイブまたは署名に失敗 Xcodeのバージョン、証明書、プロビジョニングプロファイル、Keychainの権限を確認します。 ビルドタスクが実行されない Runnerのオンライン状態から、同時実行数、キャッシュ、権限、タイムアウトを確認します。 タスクが突然遅くなった リソース競合、キャッシュの肥大化、ディスク不足、ツールチェーンの異常を切り分けます。

初回接続

接続できないときは5つの確認ポイントで切り分ける

接続問題は通常、状態、認証情報、ネットワーク、クライアント設定のいずれかで発生します。順番に確認すれば、ネットワーク障害をデバイス障害と誤認せずに済みます。

01

デバイスの状態を確認

まずコンソールにログインし、インスタンスが利用可能か、注文に対応するデバイス名とノードが正しいか確認します。コンソールで利用可能と表示され、2種類の接続方法がともに失敗する場合はネットワークを確認してください。先にシステム設定を変更しないでください。

  • 注文番号、デバイス識別子、ノードを確認する。
  • 古い記録のアドレスに接続していないことを確認する。
  • コンソールの表示状態と確認時刻を記録する。
02

アクセス認証情報を確認

システムユーザー名、初期パスワード、SSH鍵を区別します。認証情報をコピーするときは前後の空白を確認してください。鍵認証に失敗したら、正しい秘密鍵とユーザー名かを確認し、異なる組み合わせを連続して試さないでください。

  • ユーザー名の大文字・小文字と入力モードを確認する。
  • 秘密鍵ファイルの権限が広すぎないか確認する。
  • 認証情報に問題がある場合はコンソールからチケットを送信する。
03

ローカルネットワークを確認

別の信頼できるネットワークに切り替えて再テストし、会社のプロキシ、VPN、出口ファイアウォール、セキュリティソフトのルールを一時的に除外します。対象アドレス、ポート、発生時刻、タイムアウト文を記録してください。

  • ドメイン解決と対象ポートを個別にテストする。
  • 家庭用ネットワークと会社ネットワークの結果を比較する。
  • 「接続に失敗しました」の4文字だけを送らない。
04

リモートデスクトップを確認

クライアントに保存されたアドレス、ユーザー名、表示設定が現在のデバイスに対応しているか確認します。画面は開くものの入力が遅い場合は、先に解像度と色品質を下げ、その後ローカルネットワークの揺らぎを確認します。

  • クライアントの古い接続記録を削除して再作成する。
  • エラー文を撮影し、機密性の高い認証情報は送らない。
  • SSHで単独接続できるか比較する。
05

SSH設定を確認

詳細出力を使い、失敗が名前解決、ハンドシェイク、認証のどの段階で起きたか確認します。ハンドシェイクできるのに認証に失敗する場合は、ユーザー名、秘密鍵、認証ファイルを重点的に確認します。接続がすぐタイムアウトする場合は、ネットワーク経路に戻って確認してください。

ssh -vvv user@host
chmod 600 ~/.ssh/id_ed25519
ssh-add -l
セキュリティ上の注意

サポート依頼にパスワード、秘密鍵、リカバリーコード、完全な支払い情報、マスキング前の証明書を送らないでください。設定を示す必要がある場合は、障害に関係する項目だけを残してください。

Xcodeと署名

バージョン、署名、アーカイブの問題を分けて検証

1回の完全なリリースタスクですべてを検証しないでください。まずツールチェーンのバージョンを確認し、テストプロジェクトで署名を検証してから、実際のプロジェクトでアーカイブログを確認します。

確認項目 検証結果
XCODE バージョンとコマンドラインツールが一致

グラフィカルインターフェースで選択したバージョン、コマンドラインのパス、プロジェクト要件が一致しているか確認します。バージョンを切り替えた後は、ターミナルとビルドプロセスを再起動してください。

xcode-select -p
CERT 証明書を現在のユーザーが読み取れる

必要な証明書と秘密鍵が完全にインポートされ、現在のログインセッションからアクセスできることを確認します。証明書名が表示されるだけで、インポート成功と判断しないでください。

security find-identity -v -p codesigning
PROFILE プロビジョニングプロファイルがターゲットと一致

アプリ識別子、チーム、機能、対象範囲を確認します。古いプロファイルを削除する前に一覧を保存し、元に戻せるようにしてください。

~/Library/MobileDevice/Provisioning Profiles
KEYCHAIN 非対話タスクにアクセス権がある

グラフィカルインターフェースではアーカイブできるのにCIで失敗する場合は、Runnerセッションが使用するKeychain、ロック解除手順、アクセス制御を重点的に確認します。

security list-keychains
ARCHIVE 最初の根本原因エラーを残す

アーカイブログから最初に発生した失敗を特定し、末尾の概要だけをコピーしないでください。ターゲット、設定、SDK、実行コマンドを記録します。

xcodebuild -showBuildSettings

CI/CDトラブルシューティングガイド

タスクが実行されないときは、まずRunner、次にタスクを確認

CI障害は、スケジューリング、実行環境、リソース、スクリプトの4層に分けて確認します。繰り返し実行するだけでは現場ログを上書きするだけで、復旧の証明にはなりません。

CI/CDの障害現象、確認順序、復旧確認
現象 優先確認項目 対応順序 復旧基準
Runnerオフライン プロセス、ネットワーク、登録情報、実行ユーザー デバイスに到達できることを確認してからサービスログを読みます。登録範囲と起動ユーザーを確認し、先に再登録しないでください。 Runnerが継続してオンラインで、最小テストタスクを1件正常に取得できる。
タスクが長時間キュー待ち タグ、同時実行上限、既存タスク タスクのタグがRunnerと一致するか確認し、終了していないプロセスや占有中の実行スロットを調べます。 新しいタスクが想定キューで取得され、古いタスクの終了状態が明確である。
キャッシュ復元に失敗 キャッシュキー、ディレクトリ権限、空きディスク 成功タスクと失敗タスクのキャッシュキーを比較し、ディレクトリ所有者を確認してから再構築可能なキャッシュを削除します。 依存関係の復元が完了し、次回タスクでも同じキャッシュ規則を再利用できる。
スクリプト権限エラー 実行権限、インタープリター、作業ディレクトリ スクリプトがリポジトリに含まれ、実行権限が保持されていることを確認します。先頭行のインタープリターと相対パスも確認してください。 Runnerユーザーの非対話セッションでスクリプトが正常に実行される。
ビルドタイムアウト 最後に動作した段階、CPU、メモリ、ディスク まず最後の有効なログを探し、プロセスの停止、リソース不足、ネットワーク依存処理の待機のどれかを判断します。 同じコミットが連続して完了し、所要時間が基準に近く、残留プロセスがない。
RUNNER BASELINE

最小ヘルスチェックタスクを1つ残す

ヘルスチェックでは作業ディレクトリ、ディスク、ツールチェーンのパス、短いテストだけを確認します。リリース認証情報を含めず、大容量キャッシュにも依存させないでください。

whoami
pwd
df -h
xcodebuild -version
git --version

性能とストレージ

3つの証拠からタスクが遅くなった理由を判断

1回遅くなっただけで、より高い構成が必要とは判断できません。アクティビティモニタ、ディスク容量、ビルドログを同時に確認し、同じプロジェクトの正常な基準と比較してください。

CPUとメモリ

1秒間の値ではなく、タスク全体の周期を観察します。CPUが長時間フル稼働でもタスクが進行していれば計算負荷です。メモリプレッシャーが上昇し続け、大量のスワップを伴う場合に限り、同時実行数やプロジェクト規模が現在の構成を超えている可能性があります。

記録
ピーク値、継続時間、同時実行タスク数
除外
残留シミュレーター、終了していないコンパイルプロセス

ディスクとキャッシュ

まずプロジェクト、依存関係、シミュレーター、アーカイブ、再構築可能なキャッシュの使用量を集計します。ディスクが容量上限に近いと、依存関係の展開、アーカイブ、ログ書き込みに異常が起きる場合があります。削除前に成果物と再構築可能なデータを区別してください。

確認
DerivedData、アーカイブ、シミュレーター、パッケージキャッシュ
検証
削除後、同じコミットを再実行

ビルドログとツールチェーン

リソース曲線が正常なのに同じスクリプト、依存関係のダウンロード、コンパイル段階で止まる場合は、バージョン変更、ネットワーク依存、スクリプトの待機条件を確認します。成功ログとの比較は、合計時間だけを見るより早くずれを特定できます。

比較
同じコミット、同じツールチェーン、同じコマンド
特定
基準から最初に明確に外れた段階
A リソースが継続的に飽和

同時実行数を下げて再テストします。所要時間が同時実行数に応じて安定して変化するなら、より高い構成を検討します。

B ディスクが容量上限に近い

再構築可能なキャッシュと古いアーカイブを削除し、タスク後のクリーンアップ規則を設定します。

C リソースは正常だが段階が停止

スクリプト、依存関係の取得元、ツールチェーンのバージョン、非対話権限を確認します。

ノードとネットワーク

販売中の4ノードを同じネットワーク記録形式で確認

NUMACSでは、シンガポール、日本（東京）、韓国（ソウル）、香港のノードを提供しています。すべてのディレクトリ構成を注文できますが、実際の利用可否はコンソールのリアルタイム表示に従います。

SG十分

シンガポール

東南アジアおよび周辺ネットワークからの接続に適しています。診断時は、ローカル通信事業者、対象アドレス、接続方法、発生時刻を記録してください。

シンガポールノードを選択
JP十分

日本（東京）

接続異常時はリモートデスクトップとSSHを個別にテストし、特定のローカルネットワークだけで問題が起きるかを記載してください。

日本ノードを選択
KR十分

韓国（ソウル）

ネットワーク問題を送る際は、タイムアウトまたは切断の時間帯と、同じデバイスを別ネットワークで再テストした結果を添えてください。

韓国ノードを選択
HK十分

香港

操作遅延が急に変化した場合は、対象アドレス、使用プロトコル、クライアントバージョン、その時に実行中だったタスクを記録してください。

香港ノードを選択
ネットワークチケットの記録

検証可能なネットワークレポートに含める情報

発生時刻とタイムゾーン、使用ノード、対象アドレス、使用プロトコル、ローカルネットワークの種類、エラー全文、ネットワーク変更後の再テスト結果を同時に提供してください。診断コマンドを実行した場合は、マスキング済みのテキスト結果を提出し、スクリーンショットの一部の数値だけを送らないでください。

  • 時刻：分単位まで正確にし、タイムゾーンを記載
  • 経路：ローカルネットワーク、対象アドレス、ポート
  • 結果：タイムアウト、拒否、認証失敗、切断
  • 比較：別ネットワークまたは別の接続方法での結果

請求と利用期間

まず注文期間、次に支払い記録を確認

デバイスは日単位、週単位、月単位、四半期単位でレンタルできます。注文金額はすべて米ドル（USD）で決済され、期間と構成は注文記録に従います。

DAY

日単位

短期検証、臨時ビルド、移行リハーサルに適しています。請求について問い合わせる際は、注文開始時刻とデバイス識別子を記載してください。

WEEK

週単位

連続したスプリントやバージョン受け入れに適しています。確認時は、暦週と注文の実際の期間を混同しないでください。

MONTH

月単位

安定した開発と継続的インテグレーションのワークフローに適しています。構成を変更する前に必要なデータをエクスポートし、移行計画を確認してください。

QUARTER

四半期単位

継続的なプロジェクトと固定Runnerに適しています。チームは認証情報のローテーション、バックアップ、タスク引き継ぎの手順を事前に記録してください。

送信前の最終確認

トラブルシューティングを振り出しに戻さないために

以下の情報がそろっているかで、サポート担当者がすぐに再現と特定に入れるか、基本情報の追加確認が必要かが決まります。

リモートデスクトップとSSHの両方に失敗した場合、まず何を送ればよいですか？

まずコンソールでデバイスの状態を確認し、注文番号、ノード、発生時刻とタイムゾーン、対象アドレス、2種類の接続方法のエラー全文、ローカルネットワークを変更した後の再テスト結果を送ってください。パスワードや秘密鍵は送らないでください。

Xcodeのビルドに失敗したら、すぐにツールチェーンを再インストールすべきですか？

おすすめしません。まず最初の根本原因エラー、Xcodeバージョン、コマンドラインツールのパス、プロジェクト設定、直近の変更を保存してください。再インストールは現場の状態を変え、原因特定に役立つバージョン差分やログを削除する可能性があります。

Runnerがオフラインのとき、再登録が最も早い方法ですか？

まずデバイス接続、Runnerプロセス、実行ユーザー、サービスログを確認してください。登録情報が破損または失効していることを確認できた場合にのみ再登録します。そうしないと新旧のRunner記録が同時に存在し、スケジューリング問題の判断が難しくなります。

ログはどのようにマスキングすればよいですか？

時刻、コマンド、エラーコード、ツールバージョン、障害に関係するパス構造は残し、ユーザー名、リポジトリアドレス、アクセストークン、証明書内容、秘密鍵、業務データを置き換えてください。マスキング後にもう一度読み返し、文脈が再現に十分か確認します。

緊急のビルド障害を早く調査に回すには？

件名にビルド障害と記載し、注文番号、ノード、発生時刻、再現手順、期待結果、実際の結果、マスキング済みログを提供してください。依頼は情報の充実度に応じて処理されます。状況が詳しいほど追加確認を減らせます。

有人サポートへのエスカレーション

実行可能なチケットに状況を整理

注文番号、ノード、発生時刻とタイムゾーン、再現手順、期待結果、実際の結果、試した操作、マスキング済みログを準備してください。注文済みの場合はコンソールからチケットを送信できます。購入前の相談、ノード選定、請求に関する質問は support@numacs.com にも送信できます。

  • パスワード、秘密鍵、リカバリーコード、完全な支払い情報は送らないでください。
  • 緊急のビルド障害には、再現可能な証拠と最初の根本原因エラーを必ず添付してください。
  • 最後に正常動作した時刻と、障害前の構成変更を記載してください。
コンソールにログインしてチケットを送信 連絡時の要件を確認