Oakmini サポート手順書

クラウドMacの問題を、特定できる状態で止める

まず問題を接続、開発環境、CI/CD、ストレージ、ネットワーク、アカウント管理のいずれかに分類し、決められた順序で状態、パラメータ、ログを確認します。Oakminiは仮想マシンではなく、専有のMac mini物理ノードを提供します。診断では、ローカル接続条件、ノード状態、プロジェクトのツールチェーンを分けて確認してください。

ホスト状態を確認 サポート依頼を準備
6 診断カテゴリ 5 提供中のノード地域 365 日間の正常稼働
クラウドMacの開発ワークスペースとターミナル接続の状態
connection-check 
$ uname -m
arm64
$ sw_vers -productVersion
macOS ready
$ ssh -v oak-node
debug1: Authentication succeeded
$ df -h /
Filesystem status: available
TRIAGE / 01

問題に合った診断ルートを選ぶ

ネットワーク、認証情報、ツールのバージョンを同時に変更しないでください。最も近い症状を選び、一度に1つの変数だけを確認し、発生時刻、操作、結果を記録します。こうすることで、1つの変更が別の問題を隠すのを防げます。

接続できない

SSHのタイムアウト、VNCの画面が映らない、認証拒否、接続直後の切断に適しています。

ホスト状態から確認

開発環境

Xcodeのパス、Homebrewパッケージ、Git設定、Fastlane、言語ランタイムのバージョン不一致に適しています。

パスとバージョン一覧を確認

CI/CD

runnerオフライン、ラベル不一致、タスク待機、キャッシュ異常、ビルド出力不足に適しています。

runnerの登録状態から確認

ストレージ

ディスク容量不足、キャッシュの増加、作業ディレクトリの混乱、ビルド成果物のエクスポート失敗に適しています。

容量、ディレクトリ、使用量を確認

ネットワーク

操作遅延、断続的なパケットロス、遅いファイル転送、特定のローカルネットワークからのみ接続できない場合に適しています。

経路と時間帯を比較

アカウント管理

注文の特定、ホスト管理権限、継続利用状態、コンソール操作結果の未反映に適しています。

注文と操作履歴から確認
ストレージ

容量を消費している場所を特定する

コマンド df -h でボリューム容量を確認し、次に du -sh でプロジェクト、ビルドキャッシュ、エクスポートディレクトリを確認します。削除前に成果物がバックアップ済みであることを確認し、不明なシステムディレクトリを直接空にしないでください。

ネットワーク

操作遅延とタスク所要時間を分けて考える

SSH接続、VNC操作、コード取得、ローカルビルドの所要時間を個別に記録します。グラフィカルインターフェースだけが遅い場合は、まずVNC画質を調整します。コマンドラインと転送にも異常がある場合は、ローカル経路とノードへの到達性を確認してください。

アカウント管理

コンソールの注文状態を基準にする

現在のログインアカウント、注文ID、選択地域、直近の操作時刻を確認します。ホスト状態、注文、管理操作はすべてコンソールで行い、サポート依頼には注文IDのみを記載し、ログイン情報は送らないでください。

CONNECTION / 02

5つの層を順に診断する

接続失敗は通常、ホスト状態、ローカルネットワーク、接続パラメータ、ファイアウォール、認証情報のいずれかで発生します。順番に確認し、前の層を通過するまで次の層を変更しないでください。

  1. 01

    コンソールでホスト状態を確認

    注文に対応するクラウドMacが接続可能な状態か確認し、ノード地域と接続情報が同じ物理ノードのものか照合します。管理操作を完了した直後なら、操作時刻と現在の状態を記録し、同じ操作を繰り返し送信しないでください。

    合格条件：ホストは正常で、注文ID、ノード地域、接続先が一致している。
  2. 02

    ネットワーク到達性を確認

    まずローカルネットワークから対象アドレスとポートにアクセスできることを確認し、別の信頼できるネットワークと比較します。オフィスネットワークだけで失敗する場合は出口ポリシーを確認し、すべてのネットワークで失敗する場合はテスト時刻、対象ポート、エラー種別を保存します。

    nc -vz HOST PORT
ssh -vvv USER@HOST
    合格条件：ポートに到達でき、ハンドシェイク前にタイムアウトしない。
  3. 03

    SSHまたはVNCのパラメータを逐語的に確認

    ホストアドレス、ポート、ユーザー名、接続方式が現在の注文情報に基づくものか確認します。SSH設定のエイリアスがポートや鍵のパスを上書きする場合があるため、詳細ログで最終的なパラメータを確認します。VNCでは対象アドレス、表示設定、クライアントに保存された古い記録を確認してください。

    ssh -G oak-node
ssh -v USER@HOST -p PORT
    合格条件：クライアントの実際のパラメータがコンソールの情報と完全に一致している。
  4. 04

    ローカルファイアウォールとセキュリティポリシーを確認

    一時的なテストの前に既存ルールを記録します。ターミナル、SSHクライアント、VNCクライアントが接続を開始できるか、企業ネットワークが対象ポートを制限していないか確認します。診断のためにローカル保護機能全体を長時間無効にしないでください。

    合格条件：対象プログラムとポートに明確な送信許可があり、代替ネットワークでも同じ結果になる。
  5. 05

    認証情報が有効か確認

    「ネットワークタイムアウト」と「認証拒否」を区別します。前者はパスワード変更で解決すべきではありません。後者では、ユーザー名、鍵ファイル、ファイル権限、最近の認証情報変更の有無を確認します。サポート依頼には認証エラーの文面だけを添付し、パスワードや秘密鍵の内容は送らないでください。

    chmod 600 ~/.ssh/id_ed25519
ssh-add -l
    合格条件：ハンドシェイクが完了し、認証に成功してmacOSのコマンドラインまたはGUIに接続できる。
最小限の証拠：注文ID、ノード地域、発生時刻とタイムゾーン、接続方式、クライアントのエラー原文、確認済みの手順。ログからユーザー名以外の機密情報を削除し、ホスト認証情報、鍵、トークンをマスキングします。
TOOLCHAIN / 03

バージョン、パス、プロジェクト結果で開発環境を確認

「インストール済み」と「パイプラインが使用中」は同じではありません。ツールチェーンの診断では、実行ファイルのパス、バージョン、現在のシェル環境、プロジェクトが実際に呼び出した結果を同時に記録します。

ツール まず確認する項目 推奨コマンド よくある差異
Xcode 現在のDeveloperディレクトリ、バージョン、SDK一覧 xcode-select -p
xcodebuild -version		 コマンドラインが別のXcodeを参照し、プロジェクトが必要とするSDKが現在のバージョンにない
Homebrew バイナリのパス、パッケージ一覧、診断結果 brew --prefix
brew doctor		 シェルが正しいパスを読み込まず、移行後のパッケージ一覧とローカル環境が一致しない
Git バージョン、リモートURL、リポジトリ権限、ユーザー設定 git --version
git remote -v		 runnerと対話型シェルで異なる認証情報または作業ディレクトリを使用している
Fastlane 呼び出し元、依存関係の固定、lane、環境変数名 bundle exec fastlane --version グローバル版を直接呼び出し、プロジェクトの依存関係ファイルに従って実行していない
言語ランタイム インタプリタのパス、バージョンマネージャー、プロジェクト固定バージョン which ruby
which node		 対話型シェルと非対話タスクで異なる初期化ファイルを読み込んでいる
環境ベースライン

機械可読な一覧を保存する

macOSバージョン、チップアーキテクチャ、Xcodeバージョン、Homebrewパッケージ一覧、Gitバージョン、言語ランタイムを記録します。アップグレードでは一度に主要コンポーネントを1つだけ変更し、前後に一覧を保存します。

パス管理

タスクが実際に参照するPATHを確認する

ローカルターミナルでは実行できるのにrunnerで失敗する場合、 echo "$PATH"、which 、バージョンコマンドを一時的な診断ステップに書き込みます。確認後は不要な環境出力を削除し、ログに機密変数が出ないようにします。

再現可能な確認

最小構成のプロジェクトで再現する

まず依存関係を解決し、次にクリーンビルドを1回実行し、最後に成果物のパスと終了コードを確認します。最小プロジェクトでは成功し、業務プロジェクトで失敗する場合は、プロジェクト設定、依存関係の固定、スクリプト権限に戻って確認します。

BASELINE COMMANDS

環境スナップショットコマンド

以下の出力で基本的なバージョン記録を作成できます。サポート依頼を送る前に、ディレクトリ内のプロジェクト名や機密パラメータを削除してください。

uname -m
sw_vers
xcode-select -p
xcodebuild -version
brew --prefix
git --version
which ruby
which node
df -h /
CI/CD / 04

runnerのオンライン状態から個別タスクのログまで確認

CI/CDの問題は、「受け付けたか」「作業ディレクトリに入ったか」「権限を得たか」「依存関係を解決できたか」「ビルドを完了したか」の順に判断します。最終的な失敗メッセージだけで結論を出さないでください。

01

Runner登録

runnerサービスが稼働し、登録状態が有効で、コンソールにオンラインと表示されていることを確認します。再起動前に最終オンライン時刻と直近の成功タスクを記録します。

  • runner名と対象プロジェクトを確認
  • サービスプロセスと起動ユーザーを確認
  • システム再起動後に自動復旧するか確認
02

タグの一致

runnerがオンラインなのにタスクが長時間待機する場合、タスク要求のタグとrunnerの実際のタグを比較します。タグに大文字・小文字、空白、アーキテクチャの違いがあると、タスクを取得できない場合があります。

  • 明確なApple Siliconタグを1つ残す
  • 無効になった古いタグを削除
  • 対象ブランチでこのrunnerを使用できるか確認
03

権限と作業ディレクトリ

runnerユーザーがリポジトリ、キャッシュ、成果物の各ディレクトリに必要な権限を持つことを確認します。すべてのディレクトリの権限を広げて、特定パスの設定ミスを隠さないでください。

  • タスクの実行ユーザーを記録
  • スクリプトに実行権限があるか確認
  • 一時ディレクトリでファイルを作成・削除できるか確認
04

キャッシュと並列実行

キャッシュが無効な場合は、古いキャッシュを読み込まない比較タスクを1回実行します。並列タスクが互いのファイルを上書きする場合は、各タスクに専用の作業ディレクトリを割り当て、Oak CoreまたはOak Forgeのメモリとストレージがタスク規模に合っているか確認します。

  • キャッシュキーと依存関係ロックファイルのバージョンを記録
  • 共有キャッシュとタスク作業ディレクトリを区別
  • 単一タスクと並列タスクの結果を比較
05

ログと終了コード

タスク開始時刻、runner名、コミット識別子、主要ツールのバージョン、失敗ステップ、終了コード、末尾ログを保存します。再現可能な失敗なら最短の再現手順を記録し、断続的な失敗なら少なくとも成功時と失敗時を1回ずつ比較できるようにします。

  • 重要な段階の開始・終了時刻を出力
  • ビルドログとテストレポートを成果物として保存
  • アップロード前にトークン、鍵、署名関連データを削除

タスクがずっと待機中

まずrunnerのオンライン状態、プロジェクト権限、タグを確認します。この段階ではタスクがビルドに入っていないため、キャッシュを削除しないでください。

タスク開始直後に失敗

作業ディレクトリ、スクリプト権限、シェル初期化、ツールパスを優先して確認します。対話型ターミナルとrunnerの環境変数を比較します。

依存関係のインストールが不安定

ロックファイル、キャッシュキー、空き容量、ネットワークダウンロードログを確認します。クリーンキャッシュで比較タスクを1回実行し、元の証拠を連続して上書きしないでください。

並列実行時だけ失敗

メモリ使用量、共有ディレクトリの書き込み競合、ポート競合、一時ファイル名を確認します。まず並列数を下げて検証し、その後にタスク分割や設定の変更を判断します。

GLOSSARY-MINI / 05

サポート依頼でよく使う8つの用語

用語を統一すると、確認の往復を減らせます。問題を説明するときは、「サーバーが使えない」ではなく「東京ノードへのSSH接続がタイムアウトする」のように、具体的な対象を示してください。

クラウドMac
ネットワーク経由でリモート利用するmacOS開発環境。GUI、コマンドライン、ビルドタスク、自動化ワークフローに利用できます。
物理ノード
実際に設置されたMac miniデバイス。Oakminiのサービスは専有物理マシンで提供され、同じコンピューティングインスタンスを仮想マシンに分割して複数ユーザーに提供するものではありません。
専有
注文期間中、該当ユーザーが対応する物理ノードのリソースを使用すること。ビルドの並列実行、キャッシュ、ツールのバージョンを管理しやすくなります。
VNC
macOSのグラフィカルインターフェースにアクセスするリモート接続方式。画質、解像度、ローカル経路が操作感に影響します。
SSH
コマンドラインへ安全にアクセスする接続方式。ホストアドレス、ポート、ユーザー名、有効な認証情報が必要です。
self-hosted runner
ユーザーが管理する環境に配置されたCI実行プログラム。タスクを取得し、作業ディレクトリに入り、ビルドスクリプトを実行します。
ビルドキャッシュ
ダウンロードやコンパイルの重複を減らすために保存する中間データ。キャッシュキー、依存関係のバージョン、作業ディレクトリが一致しないと誤った結果になる場合があります。
ノード地域
物理ノードが所在する地域。現在提供している地域はシンガポール、日本（東京）、韓国（ソウル）、香港、米国西部のみです。
REQUEST / 06

そのまま再現できるサポート依頼を送る

Oakminiの連絡方法は、ログイン後にコンソールからチケットを送るか、support@oakmini.comへメールを送るかの2つだけです。既存の注文、ホスト状態、継続中の診断に関する内容はチケットを優先し、購入前の相談やコンソールに入れない場合はメールを利用できます。

必須項目

問題のコンテキスト

  • 注文ID：注文を特定できるIDのみを記載し、支払い情報は送らないでください。
  • ノード地域：シンガポール、日本（東京）、韓国（ソウル）、香港、米国西部。
  • 発生時刻：日付、正確な時刻、タイムゾーン、再現可能かどうかを記載します。
  • 接続またはタスクの種類：SSH、VNC、Xcodeビルド、runnerタスク、コンソール操作。
  • 再現手順：実行順に番号を付け、期待した結果と実際の結果を記載します。
  • マスキング済みログ：エラー原文、終了コード、関連コンテキストを残し、機密項目を削除します。
添付禁止

機密情報をチケットやメールに含めない

  • アカウントパスワード サポート診断にパスワードの原文は必要ありません。
  • 秘密鍵またはアクセストークン 鍵の種類やエラー情報は提供できますが、鍵の内容は提供しないでください。
  • 署名証明書の原文 証明書の用途、有効状態、エラーだけを説明し、完全な証明書をアップロードしないでください。
  • 支払い情報 注文IDと取引状態のみを提供し、カードやウォレットの機密データは送らないでください。
  • マスキング前のプロジェクトログ リポジトリURL、環境変数、顧客データ、内部パスを先に削除してください。
COPYABLE STRUCTURE

サポート依頼のテンプレート

各項目を記入し、不明な項目には「未確認」と書いて推測しないでください。複数回試行した場合は、時系列で列挙します。

件名：注文ID / 問題カテゴリ / ノード地域
発生時刻とタイムゾーン：
接続方式またはタスクの種類：
期待した結果：
実際の結果：
再現手順：
1.
2.
3.
完了した診断：
エラー原文と終了コード：
マスキング済みログの添付説明：
コンソールにログインしてチケットを送る support@oakmini.comへメールを送る
コンソール / 07

ホスト状態、注文、管理操作はすべてコンソールで行う

サポートページでは診断手順、コマンド、情報の準備方法を案内します。実際の注文、継続利用、注文確認、ホスト状態の確認、クラウドMacの管理はすべてコンソールで行います。すべてのノードは365日、正常に稼働しています。状態と実際の接続結果が一致しない場合は、時刻を記録してチケットを送信してください。

コンソール：注文とホスト管理 サポートページ：診断と証拠の準備 チケットまたはメール：スタッフによるサポート
クラウドMacを管理 初回接続ガイドを見る