crabbox

Crabbox

• 有目的的远程验证：遵循验证策略。 优先在符合要求且可用的主机上进行范围明确的本地验证。开销较大或 特定于平台的工作可以使用远程资源。排队时：停止自己创建的资源分配； 改用 PR CI 或安全的本地范围，并报告未覆盖的要求。
• 绝不等待队列，也不连续尝试不同的服务提供商。

后端：

• blacksmith-testbox：可信的维护者源。已准备好的 CI。tbx_...。
• aws：直接代理的 Crabbox。用于新建 PR。支持自定义同步/环境变量/捕获。cbx_...。
• local-container：Docker 备用方案。不是远程验证。
• ssh：现有的运维人员主机。macOS/Windows/WSL2。

始终报告服务提供商、ID、运行 URL、命令和结果。绝不要把 Testbox 称为“AWS Crabbox”。

仓库约定

• 根据可信使用方说明确定示例命令、引导设置、容器映像和 PR。绝不臆造命令，也不照搬其他使用方的设置。
• 使用方特定的设置应留在可移植技能之外。参见占位符定义。

授权与隔离

• 任务所需的创建、复用、清理、临时状态和干净检出：均已预先批准。保留现有分支、检出和无关编辑。
• 源可信度、凭据、生产环境访问权限、预算和发布仍属于权限边界。使用隔离状态；未经针对每项任务的批准，绝不触碰运维人员的 Gateway。

先确定执行路径

• 保留已确定的服务提供商：可信源使用 Testbox；需要其语义时使用直接 AWS；不可信代码使用无密钥 CI/AWS。绝不在本地运行不可信的封装器/配置，也绝不加载不可信的租约。
• 命令准备就绪后再获取资源；复用自己持有的 ID；之后停止资源。
• 使用经验证的最小配置。更大的配置：必须有已记录的内存证据或经测量的总成本收益，而不能仅以一般性故障/延迟/超时为由。不要通过增加工作进程数来补偿。
• Testbox 配置：使用 --blacksmith-workflow，绝不直接使用 --class/--type；更改配置必须获取新的租约。
• Blacksmith 运行器标签表示请求的规格，不保证 CPU 或 RAM。Blacksmith 可能会因服务可用性而分配规格更低的机器。对于资源敏感型测试或基准测试，应在已分配的机器上测量可用 CPU 数量、CPU 亲和性/配额和可用 RAM。根据这些测量结果设置工作进程数和工作负载。分别记录请求的规格和观察到的资源。绝不能仅凭标签判断硬件规格或性能。
• 规格、时长、加载失败和资源容量绝不能成为更换服务提供商的授权；只有用户明确选择或后端语义有要求时才可以更换。

预检

可信仓库根目录：读取 .crabbox.yaml、确定已安装的二进制文件，并检查 服务提供商/命令：

export CRABBOX="$(command -v crabbox)"
test -n "$CRABBOX"
"$CRABBOX" --version
"$CRABBOX" config show --json | jq '{provider, profile, target}'
"$CRABBOX" run --help

• 使用使用方提供的可信封装器/安装说明。
• 修复：验证上游来源；使用由任务创建的干净检出；保留已安装的 二进制文件和无关源文件。绝不能仅凭名称信任同级检出。

租约生命周期

• TTL 从创建时开始计算，包括数据填充；空闲超时计算不活动时长。较早到期的期限优先。默认值：各为 30m，最长 4h。所有者/组织的覆盖设置最多可允许 24h；应使用有效策略和经清理的限幅通知，而非请求的时长。收紧策略也会应用于现有租约。
• --keep 和 stop: never 都不能阻止到期。保留直接租约时，请求明确且有上限的 TTL 和空闲时长。普通心跳、设置、同步、SSH 和桌面使用不会延长总 TTL；run 仅在命令执行期间、且在策略、预算和提供商能力允许的范围内请求有上限的自动延长。
• 在进行耗时且依赖源代码的工作前，检查剩余总时长。如果允许，请求一次有上限的 extend <id> --ttl <desired-total> --json；延长不会重置空闲时长。遭拒、预算不足、不支持、时长未增加或租约不活动时，必须明确显示跳过或失败，绝不能切换提供商或无限续接租约。像 Daytona 这样在创建时固定期限的提供商，必须在分配时设置足够的 TTL。
• 直接刷新来宾系统失败时，提供商端的期限可能变长，而来宾系统内的期限仍保持旧值。保留相同的本地状态，仅为协调期限而使用相同的固定总 TTL 重试；不要将失败的延长视为保护。
• 遵守受信任的 directLeases: deny 和 directLeaseAllow。若某提供商被拒绝，必须使用配置的协调器路由；绝不能通过直接凭据绕过。Testbox 保留其原生作业和空闲时限；--ttl 不会延长委托工作流。
• list 显示仍有效的协调器租约；list --retained 还会添加已保留的终止资源（其清理尚未确认）。恢复时使用精确 ID 检查/停止。保留声明和恢复状态，直到阻塞式停止确认完成。

受信任的 Testbox

解析出的提供商为 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。
• 基础版本/头部发生变化：停止并重新预热。没有过期租约覆盖选项。
• 对于 warmup --ref，原始 SHA 不可靠；请使用分支/标签。
• 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 \
  --ttl 4h --idle-timeout 90m --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 或未证明无角色：使用无密钥的 fork CI。

直接 AWS

• 关于受信任的 AWS 命令、身份验证诊断、重新同步、干净的 PR/容器运行：请阅读 直接提供商。
• 容器运行时保留 --no-hydrate；将本地容器证明报告为本地证明。

可观测性

• 收集制品／注入凭据：阅读 捕获和环境标志。
• 精确的密钥，只运行一条命令。绝不打印机密信息、写入仓库或将其放入 shell 历史记录。
• 没有安全的注入路径：阻止实时身份验证；伪密钥证明不够。

真实端到端测试

• 使用隔离的使用者状态，测试所请求的用户入口点，而不只是 远程单元测试。
• 有关安装／提供方／交互式证明和安全的修订对比：阅读 端到端测试流程。

桌面端／跨操作系统

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。