エンジニアリング問題をすばやく特定

クラウドMacヘルプセンター

注文確認からXcodeビルドまで、問題を実行可能な確認手順に分解します。まず本ページの初期診断を行い、復旧しない場合はノードID、発生時刻、マスキング済みログを添えてコンソールからチケットを送信してください。

各注文には専用のMac mini物理ノードが割り当てられ、仮想マシンではありません。ノードの利用状況と接続情報は、コンソールに表示されるリアルタイム情報を基準とします。

問題別に進む

まず範囲を選び、最短の確認パスを実行

5つの入口は、注文ライフサイクルの異なる段階に対応しています。カテゴリを切り替えると、最初に確認すべき情報、よくある原因、次の対応先が表示されます。

注文ライフサイクル

注文と納品

支払い結果の確認待ち、ノード情報が表示されない、リージョンやモデルの確認、初回接続情報の確認に適しています。

  • コンソールの注文番号、モデル、契約期間、リージョンが申込内容と一致しているか確認してください。
  • 支払い確認後、システムはノード割り当て、ヘルスチェック、接続情報の生成を順に実行します。通常の所要時間は約4分です。
  • 通常の所要時間を過ぎても接続情報が表示されない場合は、注文を繰り返し作成せず、注文番号を記録してチケットを送信してください。
クイック診断

よくある5種類の障害を初期確認

各カードは「状態を確認し、変数を絞り込み、最後に証拠を保存する」順に構成されています。一度に1つの変数だけを変更すると、どの手順で復旧したか判断できます。

ノードに接続できない

  1. コンソールでノードが正常稼働中か確認してください。
  2. アドレス、ポート、ユーザー名、接続プロトコルを順番に確認してください。
  3. 別のネットワークから同じポートをテストし、ローカル出口やファイアウォールの制限を切り分けてください。
  4. クライアントのエラー原文と発生時刻を記録し、大量のパスワードを連続して試さないでください。
リモートアクセスガイドを見る

ビルドが突然失敗する

  1. 失敗したコミット、ビルドコマンド、終了コード、最初に出た有効なエラーを記録してください。
  2. 次を実行 xcodebuild -version 現在のツールチェーンを確認します。
  3. 依存関係ロックファイル、環境変数、署名アセットに変更がないか確認してください。
  4. キャッシュの異常を確認した場合のみ該当キャッシュを削除し、最初からすべての証拠を消去しないでください。
Xcodeのトラブルシューティングへ

ディスク容量が不足している

  1. 次を使用 df -h ボリューム容量を確認します。単一のディレクトリだけを見ないでください。
  2. DerivedData、アーカイブ、シミュレータデータ、パッケージマネージャーのキャッシュを確認してください。
  3. まず再生成できるデータを削除し、その後にビルド成果物やプロジェクトファイルを処理してください。
  4. 継続的に増加するディレクトリは、パイプラインのクリーンアップルールと容量監視の対象にしてください。
安全な削除手順を見る

認証情報が無効

  1. システムログイン、SSH鍵、リポジトリトークン、署名権限のどれが無効なのかを切り分けてください。
  2. 認証情報の有効期限、ファイル権限、それを呼び出すユーザーIDを確認してください。
  3. 認証情報をローテーションしたら、パイプライン変数も更新し、古い値を取り消してください。
  4. 完全な認証情報をコマンド履歴、スクリーンショット、チケット本文に貼り付けないでください。
セキュリティと権限の説明を見る

ネットワーク遅延またはジッター

  1. 利用地域、通信事業者、ノードリージョン、問題の発生時刻を記録してください。
  2. 複数回連続してテストし、中央値を使って判断してください。1回のピーク値だけで結論を出さないでください。
  3. インタラクティブ遅延、パケット損失、大容量ファイル転送のスループットを個別に確認してください。
  4. 不要な音声・動画機能と高画質設定を無効にしてから、VNCの操作感を比較してください。
接続の最適化方法を見る
主要用語

ノード、接続、ビルドの文脈を理解する

以下の定義は本サービスでの実際の意味に基づいています。チケット送信時に用語を統一すると、問題範囲の再確認を減らせます。

物理ノード
ワークロードを実際に実行する独立したMac miniデバイスです。チップ、メモリ、ストレージ、所在地が明確で、共有コンピューティングインスタンスではありません。
専有
契約期間中、そのノードの計算リソースは現在の注文に対応し、他のお客様のワークロードと混在してスケジューリングされません。性能と環境の境界が明確です。
VNC
macOSのグラフィカルインターフェースにアクセスするリモート表示プロトコルです。デスクトップ操作、Xcode画面の確認、システム設定の変更に適しています。
SSH
暗号化されたコマンドライン接続に使うプロトコルです。スクリプト実行、ファイル転送、runner管理、GUIを使わないトラブルシューティングに適しています。
self-hosted runner
チームが自ら管理し、コードホスティングのパイプラインに接続する実行環境です。指定したクラウドMacでタスクを実行し、ツールチェーン、キャッシュ、並列実行ポリシーをチームが管理します。
コード署名
証明書、秘密鍵、プロビジョニングプロファイルでアプリの出所と権限範囲を確認するプロセスです。関連アセットは権限を制限し、定期的にローテーションし、リポジトリに保存しないでください。
ビルドキャッシュ
依存関係、コンパイル中間成果物、ツールのダウンロード内容を再利用するデータです。ビルド時間を短縮できますが、破損または古いキャッシュは不整合の原因になります。
ノードリージョン
Mac miniが配置されているデータセンターのリージョンです。現在はシンガポール、日本(東京)、韓国(ソウル)、香港、米国東部、米国西部の6リージョンに対応しています。
納品と認証情報

注文確認から初回の安全なログインまで

通常の納品は約4分で、4つの連続した手順で構成されます。実際の利用可能状態と接続情報は、コンソールに表示されるリアルタイム情報を基準とします。

  1. 01

    注文と支払いの確認

    約1分

    モデル、契約期間、ノードリージョン、追加項目を確認します。支払い結果の確認後、注文は割り当て処理に進みます。処理を早めるために支払いを繰り返さないでください。

    保存する情報:注文番号、支払い結果ID、送信時刻。
  2. 02

    ノードの割り当て

    約1分

    システムは注文カタログに基づき、専用のMac mini物理ノードを割り当てます。2種類のモデルは、シンガポール、日本(東京)、韓国(ソウル)、香港、米国東部、米国西部から選択できます。

    確認項目:ノードID、モデル、リージョン。
  3. 03

    ノードのヘルスチェック

    約1分

    納品前に、システムの起動、ネットワーク接続、リモートアクセスサービスを確認します。すべてのノードは365日、年間を通じて稼働します。

    待機項目:コンソールのステータスが接続可能になるまで待ちます。
  4. 04

    接続情報の提供

    約1分

    コンソールにはアドレス、ポート、ユーザー名、仮の認証情報が表示されます。初回ログイン後すぐに仮パスワードを更新し、専用SSH鍵を設定して、認証情報を管理対象の鍵管理ツールに保存してください。

    完了項目:初回ログイン、パスワード更新、SSH鍵の検証。
認証情報の取り扱い

秘密鍵、完全なパスワード、完全なアクセストークンをスクリーンショット、リポジトリ、ビルドログ、チケットに含めないでください。認証情報の種類を説明する必要がある場合は、用途、作成日時、末尾の数文字だけを提示してください。

Xcodeトラブルシューティングの手順

バージョンの基準確認から再現可能なログまで

最初からすべてのキャッシュを消去したり、ツールチェーンを再インストールしたりしないでください。まずバージョンとパスを確認し、次に署名アセットを確認し、最後に範囲を限定してクリーンアップします。

01

XcodeとmacOSのバージョンを確認

グラフィカルインターフェースに表示されたバージョンを記録し、パイプラインのユーザーとしてもコマンドを実行します。ローカルの対話型ビルドは成功してrunnerだけ失敗する場合は、実行ユーザーと環境変数も比較してください。

xcodebuild -version
sw_vers
whoami
02

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

次を使用 xcode-select -p 現在の開発者ディレクトリを確認します。チームで複数バージョンを並行管理する場合は、パイプライン開始時にパスを明示的に選択し、システムのデフォルト値の変化を避けてください。

xcode-select -p
xcrun --find xcodebuild
xcrun xcodebuild -version
03

証明書とプロビジョニングプロファイルを確認

署名証明書が期限切れでなく、ビルドユーザーが秘密鍵を読み取れ、プロビジョニングプロファイルがターゲット識別子と一致することを確認してください。自動署名が失敗した場合は、まず元のエラーを保存し、キーチェーン権限とパイプライン変数を確認します。

security find-identity -v -p codesigning
ls -la ~/Library/MobileDevice/Provisioning\ Profiles
04

DerivedDataを範囲指定でクリーンアップ

まず現在のプロジェクトに対応するディレクトリだけを削除し、すべてのプロジェクトキャッシュを一括消去しないでください。削除前にディスク使用量と失敗ログを記録し、原因が本当にキャッシュか判断できるようにします。

du -sh ~/Library/Developer/Xcode/DerivedData
find ~/Library/Developer/Xcode/DerivedData -maxdepth 1 -type d
05

xcodebuildログを収集

完全なコマンド、終了コード、最初に出た有効なエラーを保存してください。チケット送信前にリポジトリトークン、署名秘密情報、ユーザーパス、内部アドレスを削除します。ただし最後の1行だけを抜き出さないでください。

set -o pipefail
xcodebuild test 2>&1 | tee build.log
printf "exit=%s\n" "$?"
サポート依頼の書き方

サポートエンジニアが直接再現できる情報を提供

完全な依頼とは、すべてのデータをアップロードすることではありません。明確な時系列、影響範囲、マスキング済みの技術的証拠を提供することが目的です。

チケット本文の推奨構成

ノードID
コンソールから正確な識別子をコピーし、独自のデバイス名で代用しないでください。
発生時刻
日付、タイムゾーン、開始時刻、最後に正常だった時刻を明記してください。
ノードリージョン
注文に記載されたリージョンを入力し、現在地の都市だけを記入しないでください。
影響範囲
単一コマンド、1つのパイプライン、すべての接続、チーム全体のどれに影響しているか説明してください。
再現手順
実際に実行した順序で、コマンド、入力、期待結果、実際の結果を列挙してください。
実施済みの確認
操作と結果を項目ごとに記載し、「すべて試した」だけで済ませないでください。

ログのマスキングルール

  • アクセストークン、パスワード、秘密鍵の内容を明確なマスキング表示に置き換えてください。
  • リポジトリアドレスはプラットフォームの種類を残し、組織名、プロジェクト名、認証パラメータを削除してください。
  • ユーザーディレクトリは一般的なパスに置き換え、相対ディレクトリの階層は残してください。
  • 証明書の問題では、名前、有効期限、エラー情報を提示できますが、秘密鍵は送信しないでください。
  • 支払いの問題では注文番号と結果IDを提示し、完全な決済情報は送信しないでください。
  • スクリーンショットを撮る前に、ターミナル履歴、メニューバー、ファイル名、通知内容を確認してください。
アップロード禁止

秘密鍵、完全なログイン認証情報、完全なアクセストークン、マスキングされていない環境変数、機密パラメータを含む設定ファイル。

いつセルフチェックを中止して、すぐにチケットを送信すべきですか?

不審な認証情報の利用、ホストフィンガープリントの予期しない変更、ノードステータスと実際の接続性の明らかな不一致、または操作によって証拠をさらに損なう可能性がある場合は、繰り返し試行を停止して直ちにコンソールからチケットを送信してください。

ノード操作で注文の所有確認が必要なのはなぜですか?

アクセスのリセット、ノード状態の変更、機密設定の処理は専有物理ノードに影響します。サポートチームはログインセッション、注文番号、権限関係を確認し、権限のない担当者によるノード操作の依頼を防ぐ必要があります。

接続とビルドが同時に失敗した場合、チケットは1件にまとめるべきですか?

同じ時間帯に発生し、同一ノードの状態が原因である可能性がある場合は、1件のチケットに接続とビルドの証拠を分けて記載できます。発生時刻、ノード、担当範囲が異なる場合は、個別に送信して追跡しやすくしてください。

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

診断結果を添えて追跡可能な依頼を送信

既存の注文、ノード接続、ビルド障害、請求に関する問題は、まずコンソールのチケットから送信してください。導入前の評価、チーム導入、安全性に関する報告は、問い合わせページから support@hexvm.com を利用できます。ノード操作には注文の所有確認が必要です。