CrabBox 遠端測試箱 是做什麼的？
- 審慎遠端證明：遵循證明政策。 優先使用合格且可用主機上的有界本機證明。昂貴或 平台特定的工作可採用遠端資源。已佇列：停止自己擁有的租用； 改用 PR CI 或安全的本機範圍，並回報未涵蓋的需求。
- 絕不等待佇列或鏈結供應商備援。
後端：
blacksmith-testbox：受信任維護者來源。已準備 CI。tbx_...。aws：直接經紀的 Crabbox。全新 PR。自訂同步/環境/擷取。cbx_...。local-container：Docker 備援。非遠端證明。ssh：現有操作者主機。macOS/Windows/WSL2。
務必回報供應商、ID、執行 URL、指令、結果。絕不將 Testbox 稱爲「AWS Crabbox」。
儲存庫合約
- 根據受信任消費者指示，解析範例指令、引導程式、容器映像、PR。絕不自行發明指令或複製其他消費者的設定。
- 消費者專屬設定需保留在可攜式技能之外。請參閱預留位置定義。
授權與隔離
- 任務所需之建立、重複使用、清理、暫時狀態、乾淨簽出：已預先核准。保留現有分支、簽出、無關編輯。
- 來源信任、憑證、正式環境存取、預算、發佈仍是權限界限。隔離狀態；未經每項任務核准，絕不觸碰操作者閘道。
優先路由
- 保留已解析的供應商：Testbox 用於受信任來源；當 AWS 語意必要時直接使用 AWS；無機密 CI/AWS 用於不信任程式碼。絕不於本機執行不信任的包裝器/設定，或灌入不信任的租用。
- 在指令就緒時取得；重複使用已擁有的 ID；完成後停止。
- 最小已證明設定檔。較大設定檔：需要記錄的記憶體證據或測量到的總成本效益，而非一般的失敗/延遲/逾時。不要以提高工作者數量來補償。
- Testbox 大小設定：
--blacksmith-workflow，絕不直接使用--class/--type；設定檔變更需要全新租用。 - 大小、持續時間、灌入失敗、容量絕不能授權覆寫供應商；必須有明確的使用者選擇或必要的後端語意。
預檢
受信任儲存庫根目錄：讀取 .crabbox.yaml，解析已安裝的二進位檔，檢查供應商/指令：
export CRABBOX="$(command -v crabbox)"
test -n "$CRABBOX"
"$CRABBOX" --version
"$CRABBOX" config show --json | jq '{provider, profile, target}'
"$CRABBOX" run --help
- 使用消費者的受信任包裝器/安裝指示。
- 修復：驗證上游；使用乾淨的任務自有簽出；保留已安裝的二進位檔 + 無關來源。切勿僅憑名稱信任兄弟簽出。
受信任的 Testbox
已解析的供應商 = Testbox（或明確要求）：指令保留它。僅在明確覆寫時才加上 --provider blacksmith-testbox：
"$CRABBOX" run --timing-json -- CI=1 <check-command>
多個指令：預熱一次，儲存 ID，重複使用，停止。
"$CRABBOX" warmup --keep --timing-json
"$CRABBOX" run --id <tbx_id> --timing-json -- <check-command>
"$CRABBOX" stop <tbx_id>
規則：
- 一個租用，一個作用中的指令。執行期間不得同步或回收。
- 偏好
bash -c；登入設定檔可能變更目錄。在執行 shell 中， 確認實際簽出 + 預期的來源/修補；HEAD 本身 ≠ 髒同步證明。 遵循消費者記錄的灌入 shell 合約。 - 原生 Testbox 會執行自己的同步，包括重複使用的
--id執行。絕不依賴--no-sync作為遠端基準：Blacksmith 沒有原生繞過方式；已釋出的 Crabbox 版本可能靜默忽略此旗標。未經變更的有意重新執行 ≠ 例外。 --reclaim僅用於明確的簽出路徑擁有權轉移。- 基礎/頂端變更：停止；重新預熱。無過期租用覆寫。
- 原始 SHA 對於
warmup --ref不可靠；請使用分支/標籤。 blacksmith testbox list會隱藏狀態。使用list --all或status --id <tbx_id>。- Testbox 狀態/停止：
--id。狀態無--json。 - 委派供應商拒絕
--fresh-pr、--full-resync、--script*、--env-helper、擷取/下載旗標。
Blacksmith 目錄下載
遞迴下載 + 必要的遠端結尾斜線： 目錄下載。
不信任的 AWS
- 乾淨的受信任預設分支簽出。已安裝受信任的 Crabbox 二進位檔。
- 每個經審查的完整 HEAD SHA 使用全新租用。無執行個體角色、Tailscale、灌入。
- 僅轉送
CI。在--fresh-pr旁上傳受信任的引導程式。
cd <clean-trusted-default-branch-checkout>
env -u CRABBOX_AWS_INSTANCE_PROFILE \
"$CRABBOX" config show --json | \
jq -e '.aws.instanceProfile == ""' >/dev/null
env -u CRABBOX_AWS_INSTANCE_PROFILE \
-u CRABBOX_TAILSCALE \
-u CRABBOX_TAILSCALE_AUTH_KEY \
-u CRABBOX_TAILSCALE_AUTH_KEY_ENV \
-u CRABBOX_TAILSCALE_EXIT_NODE \
-u CRABBOX_TAILSCALE_EXIT_NODE_ALLOW_LAN_ACCESS \
-u CRABBOX_TAILSCALE_HOSTNAME_TEMPLATE \
-u CRABBOX_TAILSCALE_TAGS \
"$CRABBOX" warmup \
--provider aws --network public --tailscale=false \
--tailscale-exit-node= \
--tailscale-exit-node-allow-lan-access=false \
--keep --timing-json
"$CRABBOX" inspect --provider aws --id <cbx_id> --json | \
jq -e '.network == "public" and .tailscale == null' >/dev/null
env -u CRABBOX_AWS_INSTANCE_PROFILE \
CRABBOX_ENV_ALLOW=CI \
"$CRABBOX" run \
--provider aws --id <cbx_id> \
--fresh-pr <owner/repo#number> \
--no-hydrate --timing-json \
--script <trusted-bootstrap-script> -- \
<expected_full_head_sha> <check-command>
env -u CRABBOX_AWS_INSTANCE_PROFILE \
"$CRABBOX" stop --provider aws <cbx_id>
- 受信任的引導程式必須證明 IMDSv2 IAM 憑證回傳 404；驗證 SHA；
移除執行階段注入變數；鎖定工具鏈；在安裝/測試前隔離
HOME。 - 變更 HEAD：全新租用。缺少遠端 PR 或無角色證明：無機密分支 CI。
直接 AWS
- 受信任的 AWS 指令、認證診斷、重新同步、乾淨的 PR/容器執行：請參閱 直接供應商。
- 容器執行時保留
--no-hydrate；將本機容器證明回報為本機。
可觀測性
- 收集成品/注入憑證：請參閱 擷取與環境旗標。
- 確切的金鑰，一個指令。絕不輸出密碼、寫入儲存庫，或放入 shell 歷史記錄。
- 無安全注入路徑：即時認證被封鎖；假金鑰證明不足。
真實 E2E
- 使用隔離的消費者狀態來練習要求的使用者進入點，而不僅是遠端單元測試。
- 對於安裝/供應商/互動式證明 + 安全的修訂版比較：請參閱 E2E 程序。
桌面 / 跨作業系統
SSH 目標、付費 macOS 預檢、WebVNC、應用程式交接驗證：請參閱 桌面與跨作業系統指令。
故障分類
識別包裝器、供應商、灌入、同步、SSH 或指令失敗：
"$CRABBOX" doctor
"$CRABBOX" status --id <id>
"$CRABBOX" inspect --id <id> --json
"$CRABBOX" logs <run_id>
"$CRABBOX" results <run_id>
blacksmith testbox list --all
blacksmith testbox status --id <tbx_id>
- 已佇列容量：停止自己擁有的租用；遵循證明政策。無重試風暴 或切換供應商。
- 過期同步：
--debug --timing-json，然後對直接供應商使用一次--full-resync。 - 在聚焦重新執行前，讀取失敗階段/JUnit。損壞的包裝器：使用已安裝的 CLI 在同一供應商上診斷；透過消費者的受信任路徑更新。
- 僅停止自己擁有的 ID；
stop不接受--timing-json。