wishforge-ide/wiki/features/integration-build-release-rollback.md

5.4 KiB
Raw Permalink Blame History

合入、构建、发布与回滚

这是流水线的后半段:integrate → build → release → accept。客户需要理解一个核心事实:运行成功(Run succeeded)与交付成功(delivered)不是同一件事。配置了交付的项目,必须走完发布并由目标环境回报证据才算闭环。

合入(integrate)

  • 合入权由租约串行化:apps/api/src/domain/integration-lease.ts:24 的 IntegrationLeases,每个项目同一时间只允许一个运行集成。
  • 推送策略是「祖先检查 + --force-with-lease」,目标分支前进了就基于最新提交重新准备候选,最多三次;规则写在 docs/reference/repository-contract.md。
  • 后端路径门禁:改动命中 codeReview.paths 且提交人权限不足时,验证通过后仍要停在 code_review,由有「审核代码」权限的人批准。批准绑定被审核的 commit 与需求版本。
  • 声明「只改前端」的愿望若改到后端文件,平台在修复轮开始前把这些文件恢复到运行开始时的内容,失败类型为 scope。

构建(build)

packages/runtime/src/build.ts:29 的 buildDockerImage 负责镜像构建,产出不可变 digest。关键不变式:构建所用 commit 必须等于已验证 commit,不一致时拒绝构建证据(docs/requirements.md FR-F3)。

发布(release)

概念 实现位置 说明
发布绑定 apps/api/src/domain/releases.ts:42 releaseBinding 把 commit、镜像 digest、架构、环境、配置版本、验证策略与证据绑定成一个摘要
发起发布 apps/api/src/domain/releases.ts:280 request 需要验证证据与构建证据
审批 apps/api/src/domain/releases.ts:435 decide 必须提交 bindingDigest;摘要不匹配即拒绝
交付查询 apps/api/src/domain/releases.ts:257 delivery 只有被接受的回执才带应用地址
回滚 apps/api/src/domain/releases.ts:662 rollback 生成新的回滚日志并签名下发

任何一项绑定内容变化(包括运维改了 POC profile)都会让审批失效,报 POC_POLICY_CHANGED 或等价的绑定校验错误。tests/local-poc-delivery.test.ts:376-386 专门覆盖「构建后改 profile → 审批被拒」。

风险计算在 packages/contracts/src/release-risk.ts:受保护路径、数据迁移、权限扩大、生产环境会提高风险,高风险发布必须人工审批,且请求人不能批准自己的发布,连接器也不能批准。

驻地交付(accept)与 POC 的真实约束

目标环境运行 apps/runner,以出站轮询拉取 Ed25519 签名任务,不需要公网入站端口。docs/reference/poc-delivery-profile.md 定义了对既有 droboticflow 命名空间的采用方式:

  • 固定 Gitea 仓库、poc 分支、API server、namespace UID、三个 Deployment UID、容器名、镜像仓库、公网地址与固定摘要的 Kaniko 执行器。
  • 只更新命名镜像与 wishforge.d-robotics.cc/* 审计注解;不重建 Service/Secret/RBAC/PVC/应用配置。
  • 更新顺序固定为 Coordinator → Worker → API。多个 Deployment 不是事务,因此跨服务协议不兼容的改动必须在发布前被策略拒绝。
  • 完成条件包括三个 rollout、精确就绪副本数、Pod 实际镜像 digest、配置指纹不变、公网健康/就绪/入口响应,以及签名发布里的业务冒烟检查。API 变更时 /api/health.buildCommit 必须等于交付的源码 SHA。
  • 日志状态只有三种终态:succeeded、rolled_back、needs_reconciliation。

这些不是文档愿景,而是被测试固化的行为:tests/local-poc-delivery.test.ts 覆盖伪造回执不置为成功(:446)、缺少匹配的组件与 HTTP 证据前运行不成功(:461)、普通 deployer 不能用通用部署证据绕过签名回执(:475)、首次交付前不能凭空回滚(:498)、回滚日志携带前一版镜像与完整基线(:506)、不兼容回滚在取锁前拒绝(:572)。

回滚的边界

回滚只改回仍由本次发布拥有的镜像,不会覆盖更新的外部镜像;它不回滚 Gitea 提交与数据库变更。配置漂移会停止自动补偿并进入对账。这与「撤销这次改动(Revert Run)」是两件不同的事:后者基于最新主干生成反向 Diff,重新走完整验证。

代码入口与测试集

关注点 入口 测试
发布绑定与审批 apps/api/src/domain/releases.ts tests/local-poc-delivery.test.ts、tests/release-risk.test.ts
Runner 队列 apps/api/src/domain/runner-broker.ts tests/local-poc-delivery.test.ts、tests/control-hardening.test.ts
签名任务 packages/runtime/src/runner.ts、packages/runtime/src/poc-runner.ts packages/runtime/test/poc-release.test.ts
POC 构建与发布 packages/runtime/src/poc-build.ts、poc-release.ts packages/runtime/test/poc-release.test.ts、tests/local-poc-delivery.test.ts
交付适配 apps/runner/src/adapters.ts apps/runner/test/local-entry.test.ts

已知边界

  • 发布审批只在 Web 控制台进行;MCP 可以发起请求,但不能代替人批准。
  • 回执里的应用地址由目标环境提供,平台不提供应用访问网关;唯一的 HTTP 例外是本地 POC 绑定的开发项目,且在生产模式被拒绝(tests/local-poc-delivery.test.ts:401-419)。