エンジニアが実行できるトラブルシューティング手順

まず問題を特定し、最短の手順でクラウドMacを復旧します。

初回SSH接続、Xcodeツールチェーン、CI/CDランナー、ノードネットワークの確認コマンドと判断基準をまとめています。解決しない場合は、注文番号、ノード、時刻、機密情報を削除したログを添えてお問い合わせください。

コンソールから問い合わせる 初回接続の手順を見る
優先ルート
4ステップで初回接続
対象範囲
よくある6種類の作業
サポート窓口
メールとコンソールの問い合わせ
ONCEMAC SUPPORT BOARD ノードチェックリスト
診断を開始できます
A1
接続情報を確認 ホストアドレス、ユーザー名、鍵ファイル
接続
B2
ツールチェーンを確認 Xcode、CLTパス、ビルドログ
ビルド
C3
実行環境を確認 ディスク、ネットワーク、プロセス、再起動履歴
ノード
送信前に鍵、アクセストークン、完全なIPアドレスを削除してください
すばやく探す

タスクから回答を探せます。最初から読む必要はありません。

接続、Xcode、CI/CD、ストレージ、ネットワーク、更新のいずれかを選ぶと、関連する項目が表示されます。コマンド、症状、ツール名でも検索できます。

現在、6種類すべてのヘルプ項目を表示しています。

初回接続 アドレス、ユーザー名、鍵の権限、SSHコマンドを確認します。 Xcodeツールチェーン バージョン、Command Line Tools、署名環境、ログを確認します。 CI/CD連携 実行ユーザー、作業ディレクトリ、同時実行数、キャッシュ、終了コードを確認します。 ファイルと環境の移行 rsync、Git、Brewfileで再現可能な環境を構築します。 トラブルシューティング 接続、ビルド、ディスク、ネットワーク、再起動の症状を順に切り分けます。 更新と注文 コンソールで利用期間、更新履歴、請求、ノード状態を確認します。
初回利用者向け

4ステップで初回SSH接続を設定

接続情報はコンソールのインスタンス詳細ページに表示される内容を使用してください。古い問い合わせや履歴コマンドからホストアドレスを推測せず、ノード再提供後は最新情報を再コピーしてください。

  1. 01

    最新の接続情報をコピー

    コンソールのインスタンス詳細を開き、ホストアドレス、SSHユーザー名、ポート、鍵情報をコピーします。選択した注文とノードが一致することを確認してから、コマンドをローカル端末に貼り付けます。

  2. 02

    秘密鍵を管理対象ディレクトリに保存

    鍵ファイルはローカルユーザーが管理できるディレクトリに保存し、Gitリポジトリ、ビルド成果物、チームチャットには置かないでください。ファイル名は任意ですが、後続コマンドのパスと一致させます。

  3. 03

    ローカルファイル権限を制限

    macOSまたはLinuxのローカル端末で実行 chmod 600 ~/.ssh/oncemac_key。SSHで秘密鍵の権限が広すぎると表示された場合は、まず権限を修正してください。セキュリティチェックを無効にして回避しないでください。

  4. 04

    接続してノードの身元を確認

    コンソールに表示されたSSHコマンドを実行します。初回接続時はホストフィンガープリントの出所を確認し、ノードに入ったら hostname、sw_vers と whoamiを実行して、ホスト、システム、現在のユーザーを確認します。

コマンド実行の順序

まず接続とバージョンを確認し、その後に完全なビルドを開始します。

1回の診断では変更する変数を1つに絞ります。SSHセッションの安定性、Xcodeバージョンの順に確認し、最後に結果パッケージとログ付きのビルドコマンドを実行します。これにより、接続、ツールチェーン、プロジェクト自体の問題を切り分けられます。

  • 接続層SSH接続後にノード名と現在のユーザーを記録します。
  • ツール層現在有効なXcodeとDeveloperディレクトリを確認します。
  • プロジェクト層scheme、destination、終了コード、ログを保存します。
  • 自動化層機密情報を削除したfastlane出力だけを問い合わせに添付します。
once-node / build-diagnostics
SSH 
$ ssh -i ~/.ssh/oncemac_key user@host
Last login: current session
connected: once-node

$ xcodebuild -version
Xcode 16.x
Build version 16x

$ xcode-select -p
/Applications/Xcode.app/Contents/Developer

$ set -o pipefail
$ xcodebuild \
  -workspace App.xcworkspace \
  -scheme App \
  -destination 'generic/platform=iOS' \
  -resultBundlePath ./BuildResults.xcresult \
  build | tee build.log

** BUILD SUCCEEDED **

$ bundle exec fastlane ios build
[fastlane] resolving dependencies
[fastlane] archive completed
[fastlane] lane finished successfully
ツールチェーンの確認

Xcodeの問題をバージョン、パス、署名、ログに分けて確認します。

「ローカルではビルドできるが、ノードではできない」だけでは原因を特定できません。同じコミット、依存関係ロックファイル、scheme、destination、環境変数を照合し、両方の出力を比較してください。

XC-01

Xcodeバージョンを確認

実行 xcodebuild -version。メジャーバージョンとBuild versionを記録します。パイプラインが特定バージョンに依存する場合は、初回設定時だけでなくタスク開始時にバージョンを出力してください。

xcodebuild -version
xcrun --find simctl
swift --version
XC-02

Developerディレクトリを確認

実行 xcode-select -p でCommand Line Toolsの現在のパスを確認します。複数のXcodeを使う場合は、実行環境で DEVELOPER_DIRを明示し、対話セッションと自動化タスクが異なるパスを読み込まないようにします。

xcode-select -p
echo "$DEVELOPER_DIR"
xcrun --sdk iphoneos --show-sdk-path
XC-03

署名環境を確認

まずキーチェーンにアクセスできること、証明書名とprovisioning profileの条件が一致することを確認し、次にプロジェクトのTeam、Bundle Identifier、署名方式を確認します。問い合わせには機密情報を削除したエラー部分だけを添付し、証明書、秘密鍵、パスワードは含めないでください。

security list-keychains
security find-identity -v -p codesigning
xcodebuild -showBuildSettings
XC-04

再確認可能なログを出力

次のコマンドで set -o pipefail を使い、実際の終了状態を保持しながら tee でログに書き込みます。複雑な失敗では .xcresultを生成し、共有前にユーザー名、パス、トークン、業務データを削除してください。

set -o pipefail
xcodebuild build | tee build.log
echo "${PIPESTATUS[0]}"
自動化ランナー

CI/CD連携の前に、実行ユーザーと作業ディレクトリを固定します。

OnceMacは専用物理ノードと完全なmacOSコマンドライン環境を提供します。具体的なプラットフォーム機能、プラグイン互換性、タスク定義は、チームのリポジトリとバージョン条件で検証してください。

RUNNER / 01

GitHub Actions セルフホステッドランナー

  • ランナーサービスが使用するmacOSユーザーと、手動SSHテストのユーザーが一致するか確認します。
  • リポジトリ、組織、企業の登録範囲を確認し、タスクが誤ったラベルに割り当てられないようにします。
  • ノードに識別しやすいラベルを設定し、ワークフローで対応する runs-on 条件を明示します。
  • 非対話シェルが必要なPATH、Ruby、Homebrew、Xcodeのパスを読み取れることを確認します。
  • 同時実行タスクの開始前に、DerivedData、パッケージマネージャーのキャッシュ、ディスク容量を確認します。
RUNNER / 02

GitLab Runner

  • executorの種類、runnerラベル、保護ブランチのルール、タスクのマッチ条件を確認します。
  • LaunchAgentまたはサービスプロセスのユーザー、HOME、キーチェーンコンテキストを確認します。
  • タスクの先頭で whoami、pwd、Xcodeバージョン、空きディスク容量を出力します。
  • キャッシュキーには依存関係ロックファイルまたはツールチェーンのバージョンを含め、互換性のないキャッシュを再利用しないようにします。
  • 失敗時はjobログ、終了コード、runnerサービス状態を同時に保存します。
RUNNER / 03

Jenkinsノード

  • agentの起動方式、作業ディレクトリ、ノードラベルがPipeline条件に合っていることを確認します。
  • Jenkins実行ユーザーがリポジトリ、ビルドディレクトリ、必要なキーチェーンを読み取れるか確認します。
  • Xcodeの選択、依存関係のインストール、ビルドコマンドを監査可能なPipelineに記述します。
  • 同じ物理ノード上の同時実行エージェント数を制限し、ディスクとメモリの競合を防ぎます。
  • アーカイブ前にworkspaceサイズ、ビルド結果のパス、クリーンアップ方針を記録します。
再現可能な移行

ファイルを移行し、監査できない古い環境はコピーしません。

Git、ロックファイル、Brewfileからツールチェーンを再構築し、必要な作業ディレクトリとキャッシュだけを移行します。古いユーザー環境をディレクトリごとコピーすると、古い設定、絶対パス、機密資格情報まで新しいノードに持ち込まれます。

MIGRATION MANIFEST 環境移行チェックリスト
ソースコード Gitでクローンしコミットハッシュを確認 未コミットの秘密情報を含む古いワークツリーはコピーしない
システムツール Brewfileで宣言的に復元 復元後にバージョンとPATHを再確認
プロジェクトファイル rsyncで差分転送 キャッシュ、ログ、資格情報ディレクトリを明示的に除外
ビルドキャッシュ ツールチェーンのバージョンに応じて選択的に移行 バージョン変更時は再生成を優先

rsyncで作業ディレクトリを移行

まずドライランでコピー・削除対象を確認してから正式に同期します。宛先パスでの削除は、必ず操作者が確認してください。

rsync -avhn \
  --exclude '.git' \
  --exclude 'DerivedData' \
  ./Project/ user@host:~/Project/

Gitでコードの状態を固定

ソースノードでブランチ、コミットハッシュ、未コミットの変更を記録します。新しいノードでクローン後にハッシュを照合してから依存関係を復元し、バージョン管理の代わりにアーカイブを使わないでください。

git status --short
git rev-parse HEAD
git clone repository-url
git checkout commit-hash

Brewfileでツールを再構築

エクスポート前に一覧を確認し、不要なソフトウェアを削除します。復元後は各コマンドのバージョンを検証し、インストールコマンドが成功しただけで環境が利用可能だと判断しないでください。

brew bundle dump --file Brewfile
brew bundle check --file Brewfile
brew bundle install --file Brewfile
移行前に機密資格情報を個別確認

SSH秘密鍵、リポジトリトークン、署名情報、環境変数ファイル、サービスキーをプロジェクトディレクトリごと一括コピーしないでください。新しいノードの最小権限を確認し、チームが承認した安全な手順で再設定します。

最短の障害対応ルート

確認可能な条件を先に除外し、完全な状況を添えて問い合わせます。

次の5種類の問題は、「症状を確認、最小コマンドを実行、結果を記録、効果のない変更を止める」の順で対応します。該当項目を開くとチェックリストを確認できます。

接続できない SSHのタイムアウト、接続拒否、鍵認証の失敗
  1. 現在のインスタンス詳細からホストアドレス、ポート、ユーザー名を再コピーし、古い注文情報を使っていないことを確認します。
  2. 実行 chmod 600 でローカル秘密鍵の権限を確認し、コマンド内の鍵パスが存在することを確認します。
  3. 次を使用 ssh -vvv で接続段階を取得します。問い合わせ前に完全なアドレス、ユーザー名、鍵パスの個人情報を削除してください。
  4. 別の信頼できるネットワークに切り替えて再テストし、ローカル側の出口制限とノード接続問題を切り分けます。
  5. 問い合わせには注文番号、ノード、発生時刻、エラー種別、機密情報を削除したデバッグ末尾を添付します。
ビルド失敗 xcodebuild、依存関係の解決、署名段階で終了
  1. コミットハッシュ、scheme、destination、Xcodeバージョン、Developerディレクトリを記録します。
  2. 依存関係解決、コンパイル、テスト、署名、アーカイブの失敗を明確に区別します。
  3. 次を使用 set -o pipefail で実際の終了コードを保持し、 .xcresult または完全なログを書き出します。
  4. 依存関係の更新、Xcodeの切り替え、全キャッシュの削除を同時に行わず、1回に1つだけ変更してください。
  5. 問い合わせには最初の重要エラー前後のログを添付し、リポジトリトークン、署名情報、業務データを削除します。
ディスク容量不足 ビルド中断、アーカイブ失敗、作業ディレクトリの継続的な増加
  1. 実行 df -h でボリュームの空き容量を確認し、 du -sh でワークスペース、DerivedData、アーカイブ、依存関係キャッシュを特定します。
  2. ログ、テスト結果、過去の成果物に明確な保持期間があるか確認し、ユーザーディレクトリ全体を直接削除しないでください。
  3. クリーンアップ前に必要なビルド成果物を保存し、対象ディレクトリを実行中のタスクが使用していないことを確認します。
  4. 長期的な容量が標準SSDを超える場合は、プランの+1TB SSDまたは+2TB SSD追加オプションを検討できます。
  5. 問い合わせにはディスク使用量の概要、増加したディレクトリ、失敗したタスクの時刻を記載し、プロジェクトのソースファイルはアップロードしないでください。
ネットワークの不安定 SSHの遅延、依存関係のダウンロード失敗、リポジトリ接続の不安定
  1. ローカルからノードまでと、ノードから対象リポジトリまたは依存関係ソースまでの症状を分けて記録し、2つの経路を1つの結論にまとめないでください。
  2. 継続的に測定する場合は、測定場所、通信事業者、ノード、コマンド、サンプル数を記録します。1回のpingでは継続的な品質を判断できません。
  3. DNS解決、プロキシ環境変数、Gitリモート、パッケージマネージャーのソースがチーム設定と一致するか確認します。
  4. 別の信頼できるローカルネットワークで比較し、ローカルWi-Fiや出口ポリシーをノード異常と誤認しないようにします。
  5. 問い合わせには発生時間帯、対象種別、失敗率、機密情報を削除した出力を添付します。
ノードの再起動 セッション切断、サービス未復旧、ランナーのオフライン
  1. まずコンソールで現在のノード状態を確認し、電源操作を繰り返し送信しないでください。
  2. 接続復旧後に実行 uptimeで起動時刻と問題発生時刻が一致するか確認します。
  3. セルフホステッドランナー、GitLab Runner、Jenkins agentの起動方式と現在のサービス状態を確認します。
  4. ビルドワークスペースが完全か確認し、未完了タスクの成果物を再検証します。状態が不明なアーカイブをそのまま使用しないでください。
  5. 問い合わせには注文番号、ノード、発生時刻、再起動前後の症状、復旧が必要なサービス名を記載します。
サポート

一度の送信で十分な情報を伝え、確認の往復を減らします。

既存の注文、ノード状態、更新に関する問題は、コンソールから問い合わせてください。未注文の構成や利用範囲についてはメールでご相談いただけます。連絡先メールアドレスは support@oncemac.com のみです。

SUPPORT PACKET 問い合わせ情報パック
01

注文とノード

注文番号、構成名、ノードのリージョンを記載し、支払い情報や請求書全体は送らないでください。

02

発生時刻

タイムゾーン、初回発生時刻、最終再現時刻、問題が継続しているかを記載します。

03

再現手順

実行コマンド、期待結果、実際の結果、終了コードを列挙し、「使えない」とだけ書かないでください。

04

機密情報を削除したログ

エラーの前後関係を残し、鍵、トークン、パスワード、完全なIP、署名情報、業務データを削除します。

05

実施済みの確認

確認済みのネットワーク、バージョン、パス、ディスク、再試行結果を記載し、効果のない手順の繰り返しを避けます。

既存の注文

コンソールから問い合わせる

ノード接続、ビルド異常、請求、更新、注文状態の問題に適しています。問い合わせはログインアカウントに紐づくため、インスタンスの状況を確認しやすくなります。

コンソールへ移動
購入前・一般相談

必要事項を記載したメールを送る

用途、対象ノード、Xcodeバージョン、同時ビルド数、ストレージ要件、利用開始希望時刻を記載してください。

support@oncemac.com
専用物理Mac miniノード

新しいノードが必要なら、構成と利用期間を選択してください。

OnceMacでは、販売中の3段階の構成と6つのノードを提供し、365日いつでも稼働しています。すべての注文は米ドルで決済され、コンソールから注文、ノード、問い合わせを一元管理できます。

クラウドMacを今すぐレンタル チームに相談する