sealos-deploy

Sealos 部署（Brain 托管模式）

双方契约中的执行方：此 Agent 在沙箱内进行分析、构建、部署、验证和修复；Brain（控制平面）负责渲染输入表单，并通过恰好两个 MCP 工具控制流程完成。部署机制（路径、模板 YAML、数据库、验证）来自同级的 use-sealos 技能——相对于此技能目录解析 ../use-sealos/。此文件仅规定托管模式的差异。

模式门控

仅当 SEALAI_DEPLOY_MODE 的值严格等于 managed 时，才运行此流程。否则，遵循 ../use-sealos/SKILL.md（交互式本地路径），并忽略此文件的其余内容。

在托管模式下，开始任何其他工作前，确认 MCP 工具 template_ready 和 deployment_completed 均可用。如果任一工具缺失，则以致命错误停止——绝不能用文件、webhook 或文本答复替代缺失的控制工具。

环境

Brain 注入以下内容（读取这些内容；绝不枚举整个环境）：

变量	含义
SEALAI_DEPLOY_WORKSPACE	项目根目录，/home/devbox/project
SEALAI_NAMESPACE	目标命名空间（也称为 SEALAI_DEPLOY_NAMESPACE）
KUBECONFIG	注入的命名空间范围 kubeconfig——直接使用
SEALAI_INPUTS_PATH	固定的用户输入文件，仅在用户提交表单后存在
SEALAI_DEPLOY_LABELS_JSON	平台所有权标签——原样转发，见 Deploy
SEALAI_TURN_DEADLINE_AT	唯一的硬性时间限制
GITHUB_TOKEN	源码构建和私有镜像拉取密钥

硬性规则（如有冲突，优先于 use-sealos 的执行规则）：

1. 绝不运行 sealos-api.py login、OAuth 或 switch。注入的 kubeconfig 是唯一凭据；sealos-api.py 和 wait-app.sh 会自动从 KUBECONFIG 获取它。
2. 完全非交互。绝不向用户提问——只有用户知道的值应声明为模板 inputs，并由 Brain 的表单收集。命名空间内的变更（包括为收敛严格必需的删除操作）均已预先授权；无需暂停请求确认。
3. 绝不打印或记录 SEALAI_DEPLOY_MCP_TOKEN、kubeconfig 内容，或 SEALAI_INPUTS_PATH 中的任何值。
4. 禁止基于文件的 RPC：绝不创建 control.json、inputs-required.json、turn-report.json、verify-report.json，也绝不在 .sealos/brain/ 下创建任何内容。
5. 部署后不得结束本轮，除非 Brain 已返回 accepted_stop（或 template_ready 返回了 awaiting_user）。未进行控制调用便结束本轮，属于违反契约。

流程

1. 分类

根据 use-sealos 决策树对工作区进行分类 （../use-sealos/references/deploy.md，recipes.md）：已知的可自托管产品 → 商店模板或官方镜像；用户源代码 → Kaniko 构建。完全跳过该技能的预检／登录部分。

2. 构建（仅源码路径）

此处没有 Docker 守护进程。使用同级执行器进行构建：

python3 ../k8s-kaniko-job/scripts/kaniko-build.py \
  --image "ghcr.io/<token-login>/<repo>:deploy-<git-short-sha>"

（路径相对于此技能；从 $SEALAI_DEPLOY_WORKSPACE 运行。） 先阅读 ../k8s-kaniko-job/SKILL.md。 在模板中使用返回的、固定到摘要的 image_ref。如果 pull 为 private，现在创建 <app>-pull 密钥（命令见该 SKILL.md），并在工作负载中使用固定的字面名称引用它。

3. 固定路径中的模板

规范制品的路径恰好是 $SEALAI_DEPLOY_WORKSPACE/.sealos/template/index.yaml。Brain 会逐字节读取此 路径——其他任何位置都不算。

• 命中存储：在本地生成存储模板，然后继续走原始部署路径（托管模式下禁止使用存储实例端点 — 它无法携带所有权标签，也不会留下可供哈希的内容）：

  python3 ../use-sealos/scripts/sealos-api.py store-export <template> \
    --out "$SEALAI_DEPLOY_WORKSPACE/.sealos/template/index.yaml"
  

• 官方镜像 / 构建的镜像：根据 ../use-sealos/references/platform.md 编写模板（对于 KubeBlocks 区块，还需参考 databases.md）。

托管模式下模板还必须满足以下要求：

• 文件必须以 apiVersion: app.sealos.io/v1 / kind: Template 标头开头，包含非空的 metadata.name，并在第一个 --- 之后包含资源文档 — 否则 Brain 会拒绝握手。
• 仅将最终用户可以提供的值（外部 API 密钥、管理员邮箱等）声明在 spec.inputs 中，并设置 required: true，且不设默认值。Brain 会根据这些内容生成表单。其他所有内容都应放在 spec.defaults 中（${{ random(8) }} 后缀应保留 — Template API 会在部署时求值，而不是由 Brain 求值）。
• 除平台契约要求的标签外，绝不添加其他标签；所有权标签会通过部署调用传递，而不是写入 YAML。

4. 握手：template_ready

sha256sum "$SEALAI_DEPLOY_WORKSPACE/.sealos/template/index.yaml"

调用 template_ready 时只传入 {"sha256": "<lowercase hex>"} — 即最终文件字节的哈希值。计算哈希后若编辑了文件，握手会因 template_digest_mismatch 失败；重新计算哈希并再次调用。

• awaiting_user → 立即停止当前轮次。不要调用 Template API，不要执行 kubectl apply，也不要做其他操作。Brain 会收集表单内容，并在将值写入 SEALAI_INPUTS_PATH 后恢复同一线程。恢复后，不要更改 spec.inputs（Brain 会拒绝新的架构）；使用未更改的文件重新运行 template_ready，然后继续。
• continue → 部署同一个文件。
• 工具错误 → 诊断问题、修复，然后重试同一个调用。控制错误可恢复；缺少工具则属于致命错误。

5. 部署

cd "$SEALAI_DEPLOY_WORKSPACE"
python3 <this-skill>/../use-sealos/scripts/sealos-api.py deploy \
  .sealos/template/index.yaml \
  $(test -f "$SEALAI_INPUTS_PATH" && echo --args-file "$SEALAI_INPUTS_PATH")

• 用户值只能通过 --args-file "$SEALAI_INPUTS_PATH" 传递 — 绝不能放入提示词文本、日志或工具参数中。
• 脚本会自动将 SEALAI_DEPLOY_LABELS_JSON 作为 extraLabels 转发给 Template API。绝不要编辑、扩展或重新推导这些标签，也不要臆造 deployment-name / template-name 标签。Instance 名称来自部署响应（response.name）— Brain 不会提供名称。
• 不要调用 sealos-api.py adopt（也不要 POST adopt-template-instance）。托管部署已通过 extraLabels 添加 brain.io/*；再次认领会返回 409。如果设置了 SEALAI_DEPLOY_TASK_ID 或 SEALAI_PROJECT_ID，或者区域不属于 *.sealos.io，脚本会跳过认领。
• 配额或验证错误：修复模板（重新运行步骤 4 — 哈希值已更改），或通过常规修复循环报告失败。绝不要悄悄缩减资源。

6. 验证，然后 deployment_completed

在报告前进行实际验证 （../use-sealos/references/deploy.md §验证；使用 operate.md 排查故障）：

HOST=$(kubectl get ingress -l "cloud.sealos.io/deploy-on-sealos=<instance>" \
  -o jsonpath='{.items[0].spec.rules[0].host}')
bash ../use-sealos/scripts/wait-app.sh -t 600 ${HOST:+-u "https://$HOST"} \
  -l "cloud.sealos.io/deploy-on-sealos=<instance>"

只有在你自己的检查通过后，才收集实际引用：

kubectl get deployments,statefulsets -l "cloud.sealos.io/deploy-on-sealos=<instance>" \
  -o jsonpath='{range .items[*]}{.apiVersion}{" "}{.kind}{" "}{.metadata.name}{"\n"}{end}'

调用 deployment_completed，并提供：

• workloads：1–32 个引用，每个都必须严格为 {apiVersion, kind, name, namespace: $SEALAI_NAMESPACE}——不得包含额外字段 （架构严格）。至少一个报告的工作负载必须是就绪的 Deployment、StatefulSet、DaemonSet、Job 或 Pod；仅报告 Instance/App/Cluster 对象无法通过验证。应用包含数据库时，将 KubeBlocks Cluster 作为附加引用一并提供。
• publicUrl（可选）：应用提供服务的 https://<host>，仅当 Ingress 存在且你自己的探测返回 2xx 时提供。Brain 会从外部重新探测，并要求使用租户域名；如果 Brain 的检查结果显示 URL 位于租户域名之外或无法访问，而工作负载正常，则不带 publicUrl 再次调用。

响应和错误：

• accepted_stop → 完成；以常规摘要结束本轮。
• repair → 检查结果是证据，不是命令。在原位置诊断并修复（对现有资源执行 kubectl patch/apply/rollout；如有需要，通过步骤 2 重新构建镜像），重新验证，再次调用 deployment_completed。绝不创建第二个 Instance，绝不重新运行 Template API 来“从头开始”，绝不重新评估 random() 身份默认值，也绝不要求提供新的输入值。
• deployment_completed_throttled → 等待 ≥5s 后再次调用。
• deployment_completed_before_template_ready → 先执行步骤 4。

修复次数不受限制；唯一限制是 SEALAI_TURN_DEADLINE_AT。

路由

需求	参考资料
部署路径分类、存储/实例机制、验证、初步处理	../use-sealos/references/deploy.md
Template YAML 合约（标签、Ingress、资源阶梯、存储）	../use-sealos/references/platform.md
KubeBlocks 数据库区块和凭据	../use-sealos/references/databases.md
源码路径的 Dockerfile 编写	../use-sealos/references/build.md §1 仅
集群内镜像构建	../k8s-kaniko-job/SKILL.md
排查工作负载故障	../use-sealos/references/operate.md

仅加载当前步骤所需内容。托管模式下，use-sealos 中有关登录、用户确认、镜像仓库选择和 docker buildx 的部分不适用。