276 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 泛宇发布试行流程
## Dev 主线约束(2026-11-10)
发布只使用发布时本地 `dev` 与远端 `origin/dev` 完全一致的提交,取消未合并分支紧急发布例外。先把修复合入主线、完成验证,再准备发布;不能用“提交已被 dev 包含”代替 tip 一致。日常工作与清理按[主线流程](../agents/branch-workflow.md)执行。
`prepare` 离线校验候选与两个本地引用一致;`deploy` 在访问集群前先拉取远端 `dev` 并再次校验。远端不可达、任一 dev 引用不同、候选已落后均阻断,不提供绕过开关。部署授权、镜像来源、迁移审查及业务验收要求保持原有流程。历史发布记录仍可读取与核验,未更新组件保持其原版本;后续开发可使 dev 领先于线上。
日常开发按[分层验证流程](../agents/verification.md)执行,不在每次编辑后重复本发布流程。
本页发布门禁及 `fanyu-policy.json` 保持独立;快速检查报告不能作为缺失发布证据的替代。
## 开始或恢复工作
发布、部署故障、回退、上下文恢复时先读本页。状态的权威来源是
`local-data/releases/<id>/release.json`。先运行 `python3 scripts/release.py status` 列出记录,
再用 `python3 scripts/release.py status <id>` 查看缺失证据与下一步。
历史聊天和“Pod 已 Ready”不代表业务验收完成。使用命令更新记录,保留失败和未验证项。
支持 **Fanyu 现有 API 与切片处理器的同一不可变镜像更新**,并同步容器的
`DROBOTICFLOW_BUILD_COMMIT`。可通过 `prepare --source-mode advisory|strict` 将唯一指定的
`ANNOTATION_SOURCE_VALIDATION_MODE` 一起纳入同一计划和审批;处理器先更新并就绪,再更新 API。
保留 ConfigMap、Secret、PVC、Service、其他配置、资源和副本数。
需要更改其他配置、组件或数据库时,单独设计并审查变更计划,不提供绕过参数。
2026-10-17 已部署的源索引基线也可做上述镜像更新:处理器必须精确匹配
fanyu-policy.json 引用的容量文件(2 副本、每副本 8 修订槽、4 GiB limit、
Recreate、source-index/striped/verify-existing)。校验不调整该配置;旧单处理器
配置继续按原规则检查,未知角色、资源或模式不匹配则阻断。校验器、Worker、
Coordinator 保留当前镜像;更新它们仍须单独审查与授权。
`deploy-k8s.sh` 的 Fanyu 全量 apply 入口已阻断,其他环境的原流程不变。
这是命令行防误操作流程,不是安全边界:操作者仍可以直接运行 kubectl。团队级强制执行
需后续收敛集群写权限。首版没有自动回退、自动重试、压测或自动创建测试数据。
2026-10-20 审核权限补充:发布本地检查强制运行 `test:browser:review-permissions`、
`TestReviewCannotMutateAnnotation` 及 `TestRouteSnapshot`。浏览器以可写审核意见的真实状态
验证原标注不可编辑,不得额外设置整体只读来代替;覆盖普通/专注、旧审核入口、最终验收、
历史/媒体查看、快捷键及失权手势,同时保留合法标注和审核操作的正向对照。此检查使用
本机 Vite、合成媒体和内存数据库,需要 FFmpeg 与现有 Playwright 浏览器;不访问生产。
## 授权与数据边界
- 本地 prepare/check/plan 不构成部署、PR 或客户数据写入授权。
- `check --cluster` / `verify` 只读集群资源;实际执行也须符合本次会话的环境访问授权。
- 展示 plan 后,获得用户对该计划的明确部署授权,再执行 deploy。`--approval-ref` 记录
用户消息引用,不能由代理虚构,也不是系统自动验证的授权凭据。计划变化后重新授权。
- 应用启动本身可能执行迁移,镜像更新不能保证零业务写入。部署前必须审查候选版本启动
行为,记录 change-safety 证据;有新增迁移或客户数据改写时,停止并取得精确操作授权。
- 生产业务验证默认只读。领取、保存、送检等写测试须另外批准隔离测试项目、账号和范围。
- 线上业务验证账号从 `local-data/prod-test-accounts.json`(untracked)读取;文件缺角色时向用户索取,禁止猜测或字典尝试。测试写完按用户授权范围清洗回退。
- 记录、日志、回退材料均在 Git 忽略的 local-data;不要填写凭证或复制客户正文到记录。
## 顺序与完成条件
### 1. Prepare:绑定候选版本和目标身份(离线)
使用干净、已提交的工作树;其他人的未提交改动保留在原工作树,使用隔离工作树发布。
镜像必须使用 `repository@sha256:...`,不接受可变 tag。先构建、核对镜像来源,再准备发布。
在隔离检出中用脚本构建 API 镜像(处理器使用同一镜像):
```sh
GOPROXY=https://goproxy.cn,direct scripts/release-build-api-image.sh \
ccr-29eug8s3-pub.cnc.bj.baidubce.com/fanyu/droboticflow-api <metadata-file>
```
脚本要求已跟踪文件无未提交改动,把检出 commit 和 UTC 构建时间作为
`DROBOTICFLOW_BUILD_COMMIT`/`DROBOTICFLOW_BUILD_TIME` build-arg 写进镜像,推送后从 buildx
metadata 读取 digest,输出 `IMAGE=...@sha256:...` 供 `--image` 使用。镜像里的
`DROBOTICFLOW_IMAGE_BUILD_COMMIT` 优先于部署注入的构建标记;直接运行 `docker buildx build`
而不传这两个参数时,`/api/ready` 和页面的连接诊断会显示 commit 为 `unknown`。
目标 server、context、namespace UID 从已核实的集群身份取得,不能从一次错误连接中直接认可。
工具检查 namespace UID 及 API server,namespace 名字相同也不能蒙混过关。
构建使用权威 `Dockerfile.api` 和 [固定运行依赖](api-runtime.json),不再临时生成包装 Dockerfile。
输出旁的 `.provenance.json` 记录源码、运行基础摘要和配方摘要。当前固定基础为既有已验证镜像,
复制新产物前移除旧应用;`Dockerfile.api-runtime` 提供后续专用基础的构建配方,发布它仍需单独授权。
本地/其他环境直接构建保留原有 Debian 安装路径;泛宇发布脚本只接受不可变运行基础摘要。
```sh
python3 scripts/release.py prepare --id <release-id> \
--image <registry/repository@sha256:digest> \
--kubeconfig <local-kubeconfig-path> --context <verified-context> \
--server <verified-https-api-server> --namespace-uid <verified-uid> \
--purpose '本次问题和修改范围' \
--rollback '旧镜像、兼容性结论及需要先核对的任务状态'
```
完成条件:记录有 commit、镜像摘要、策略摘要、目标身份、目的和回退说明;未访问集群。
记录绑定的是当前 checkout commit。镜像与源码的对应关系仍须独立构建记录验证。
### 2. Check:本地检查与线上只读快照
```sh
python3 scripts/release.py check <release-id> --local
python3 scripts/release.py check <release-id> --cluster
```
本地检查命令和环境约束以 [fanyu-policy.json](fanyu-policy.json) 为准。
看板稳定性门禁分别运行 race 正确性检查和显式 `-race=false` 的性能计时;两者均必须通过,
并发读取 2 秒门槛不变。看板浏览器门禁覆盖当前生产与质量页面的五角色、项目筛选、快照及导出,
不再把已替换的旧页面布局当成当前入口。返工浏览器夹具运行真实本地校验处理器,不能绕过源数据准入。
统一候选涉及的额外组件与待确认发布项见 [组件发布计划](recent-integration-components.md)。首版运行流程工具测试、
前端类型/构建及切片恢复定向回归,不冒充全套产品测试通过。任何失败阻断,不支持忽略开关。
命令执行结果、输入身份和日志摘要写入记录。本地检查的成功及失败输出先脱敏、限长,再以私有文件保存,
不会记录集群对象原文;日志路径写入记录。浏览器失败截图及 trace 使用唯一运行目录,仅限隔离合成夹具。
`check --local --reuse-successful` 仅可复用一小时内输入、安装依赖、工具、环境和日志摘要均未变的
白名单纯检查。默认重跑全部;浏览器、Mongo、性能与集群检查始终重新执行。
新增强制 `test:work-availability`,复用已有送检保护、删除/送检并发、重启恢复、权限、旧数据
Mongo 等价和 advisory 真实工作台回归。缺用例、跳过、失败、源码中途变化均不能算通过。
CI 独立作业需要 Ubuntu 24.04 runner、Mongo 8、FFmpeg 和 Playwright;远端 CI 未执行时须明确待验证。
2026-10-20 起,`build:web` 后强制运行 `test:production:boot`,实际启动生产 dist 并验证登录页、非空 root 和零运行时错误。该门禁使用本机桩 API,不连接公司;须安装 Playwright 浏览器或通过 `BROWSER_EXECUTABLE` 指定已有 Chromium。构建依赖必须按当前 lockfile 独立安装;共享依赖版本清单或带 alias 的组件夹具不能代替实际产物启动验证。
集群检查解析容器 env/envFrom/ConfigMap,核对数据库名称、会话认证、API external 模式、
处理器并发/资源、存储连接、PVC 及当前 rollout 状态。只校验 Mongo Secret 的绑定,不读取
其值;**不证明实际 Mongo 主机正确、凭证有效或视频能正常播放**,由业务证据补齐。
公网带宽作为观察项展示,不以固定数值判断并发容量充足。
完成条件:两类检查均成功、源码和策略未变化。再次 check 会废弃旧计划和证据。
### 3. Plan:形成可审查的计划
```sh
python3 scripts/release.py plan <release-id>
```
显示旧/新镜像、构建标记、目标、带宽观察值、限制与回退说明,并生成计划摘要。
核对两个部署的修改范围。计划不更新 ConfigMap、Secret、存储或网络。
新发布记录必须明确两个组件的源校验模式;未配置时禁止依赖代码默认严格模式。
现有历史记录仍按原摘要核验。严格模式切换或严格准入关键规则变化须先以 advisory 部署候选,
再由超级管理员获取 `GET /api/plugins/annotation-qa/source-readiness?scope=deployment` 的只读影响清单,
用 `check --cluster --source-readiness-file <本地私有清单>` 绑定计划。
清单必须覆盖同一数据库、命名空间、线上构建及旧数据截止配置,一小时内完整生成,所有条目均可准入;
组织/项目局部清单、本地夹具、缺项、阻断条目、过期或内容变更均不允许启用严格模式。
清单不补验、不排队、不改标注,也不是源数据校验证书。它是时间点盘点,不会冻结业务数据;
`change-safety` 必须说明盘点至切换期间的新任务和在途变更如何受控,不满足时保持 advisory。
当前模式不因获取清单而变化。详细边界见[可靠性防护](../operations/reliability-guardrails.md)。
部署前需要两份人工审查证据:
- `image-provenance`:构建记录将本次源码 commit 与镜像 digest 对应,候选镜像的验证情况明确。
- `change-safety`:审查启动迁移/兼容性,检查在途切片与送检工作,确定维护窗口或安全切换方式,
并说明回退旧版本是否安全。工具不自行读取或更改业务数据库来判断任务状态。
```sh
python3 scripts/release.py evidence <release-id> --check image-provenance \
--result passed --file <local-evidence-file> --note '构建和镜像核对结论'
python3 scripts/release.py evidence <release-id> --check change-safety \
--result passed --file <local-evidence-file> --note '迁移、在途任务及回退核对结论'
```
证据保存文件路径、SHA256、时间和计划摘要。工具验证文件未变,**不自动判断内容是否真实充分**。
人工证据应明确环境、版本、步骤、实际结果、限制和审查人;不能把空模板标记为 passed。
### 4. Deploy:本次授权后的有界变更
```sh
python3 scripts/release.py deploy <release-id> \
--confirm-plan <plan-hash> --approval-ref <user-message-reference>
```
部署前再次核对源码、策略、证据及线上快照,集群预检超过一小时需重做。每次 patch 前重新
核对两个部署及关联配置;用 UID/resourceVersion 条件更新镜像与构建标记。
写请求发送前先落盘 intent。任何超时或中断按结果未知处理;不重复发、不自动回滚。
两个 Deployment 不是事务,也没有跨主机锁。中间失败可能只更新一个组件,必须 verify
核对实际状态再制定恢复计划。JSON 条件更新防止覆盖同一资源的并发修改,但不能保证跨资源
原子性;正式部署应使用团队约定的维护窗口,后续可增加服务端发布锁。
处理器先更新,完整 rollout 并核对候选镜像与构建标记后才更新 API,避免旧处理器接到
无法理解的新持久任务载荷。等待失败保留已确认的处理器 patch,API 不更新;按部分发布
处理,先只读 verify,不重复 deploy、不自动回退。计划展示此固定顺序。
完成条件:仅代表 patch 已确认,状态仍为 `deployed_pending_verification`。
### 5. Verify:分开基础设施与业务验收
```sh
python3 scripts/release.py verify <release-id>
```
核对目标镜像、构建标记、rollout、配置/PVC/服务身份以及未批准的部署变化。
未 Ready 可稍后重新运行只读 verify,不重新 deploy。部署配置符合后仍为
`deployed_pending_acceptance`,不等于已经登录、播放、切片或送检成功。
按策略中 requiredEvidence 逐项记录验收:五角色登录及业务API、多供应商权限、标注与交付
(普通/舍弃/无效/空白)、质检/终审、切片重启恢复、视频首帧/缓冲/实际播放速度。
所有写入测试都遵循前述隔离与授权要求,不能占用生产客户任务。
```sh
python3 scripts/release.py evidence <release-id> --check video-playback \
--result passed --file <local-evidence-file> --note '角色、并发、网络和播放实测结果'
python3 scripts/release.py verify <release-id>
```
完成条件:基础设施复核通过且所有必需证据有效,才进入 `accepted_with_evidence`(包含人工
证据的验收),不是“全自动端到端通过”。未测填 unverified,失败填 failed,不得代填通过。
## 故障、回退和紧急修复
- `status` 显示最后一步、写请求状态、缺失证据和 checkout。换上下文后先运行它。
- 源码/策略变化重新 prepare;部署前同事更新了线上,重新 check/plan 并取得新授权。
- `outcome_unknown` 或 `deploying`:先 verify,不能再次 deploy 同一记录。部分更新不能靠
修改 JSON 清掉历史;保存调查记录并制定新的恢复计划。
- 回退须新的明确授权,核对当前版本与数据兼容性,生成条件式变更。禁止直接 apply 旧完整
Deployment、restore 整库或覆盖客户新增数据。首版不自动执行回退。
- 紧急修复写明“已解决 / 未解决 / 临时取舍 / 后续任务”,关联本地问题票;未验证部分仍保留,
不因上线紧急而自动验收通过。旧规格由新规则显式替代,不同时保留两份有效相反结论。
## 本地试运行与后续范围
```sh
python3 -m unittest discover -s tests/release -p 'test_*.py'
python3 scripts/release.py --help
```
测试使用模拟 Kubernetes,不连接集群、不创建账号或任务。覆盖数据库/认证/处理器回归、
陈旧计划、同事更新、部分失败、证据失效、锁冲突和 legacy 入口阻断。
后续再扩展:服务端部署互斥、OCI provenance 自动核对、隔离环境真实业务验收、受审查的配置
变更及回退执行器。试行阶段避免把这些未实现能力写成已有保证。
## 历史记录与被替代计划
`status` 对未使用当前结构的历史记录提供只读视图,不补造缺失的 plan、审批或验收证据。
`recordFormat=historical-readonly/incomplete-readonly` 时不能执行 check/plan/deploy/verify/evidence;
历史 `recordedState` 是当时的结论,不代表按当前策略重新验证通过。需要继续发布时创建新记录。
只有**尚无部署尝试**的旧计划可以标记被替代:
```sh
python3 scripts/release.py supersede <old-id> --by <replacement-id> --reason '核实过的替代关系'
```
此命令只写本地记录:先按内容哈希备份原文,再追加替代关系,保留原状态、计划摘要、证据和事件。
之后旧计划的 check/plan/deploy/verify/evidence 均阻断。目标必须是同一集群身份的当前记录。
已经执行过、部分执行或结果未知的记录不允许这样归档,避免掩盖部署与验收缺口。
## 下一次发布前:核对候选代码是否包含线上修复
线上 build commit、PR 提取提交及 dev 可能不同。不可仅因某个 PR 测试通过就将其分支当作线上完整版本。
先只读保存 API、处理器及 Worker 的 Deployment 快照,核实目标身份、采样时间和真实镜像,再执行:
```sh
python3 scripts/release_source_audit.py --snapshot <fresh-deployments.json> \
--candidate <candidate-ref> --output <source-audit.json>
```
该命令离线比较三个组件的源码来源;缺少提交或分支分叉时退出 2,输出需要核对的代码文件。
分叉的 PR 分支须先将遗漏修复整合到完整候选,或者逐项审查差异与兼容性并保留证据,不能把
cherry-pick 提交哈希不同简单当成修复丢失,也不能把 patch-id 相同当成功能兼容证明。
祖先关系完整只证明历史来源,仍须审查删除/覆盖改动和运行回归。审查结果纳入本次 change-safety 证据。
这是发布前的人工核对步骤,**没有新增团队级发布锁或自动语义兼容检查**。
2026-09-29 核对结果见 [版本一致性盘点](source-consistency-20260929.md)。
## 看板稳定性门禁(2026-10-26)
Fanyu 的 localChecks 新增 `python3 scripts/test_dashboard_stability.py`,固定使用经核实的本地
Mongo 27018 合成隔离库,包含 24000 条/来源规模、历史兼容、故障恢复和权限检查。
关键测试未执行、跳过或失败均阻断,不能以无 Mongo 时的 skip 结果发布。
上线时还需审查三个统计索引的创建授权及可选诊断字段的混合版本行为;验收同时检查真实看板
200 与快照持续更新,不能只看进程健康。接口、检查器和边界见[看板持续运行说明](../dashboard-stability.zh-CN.md)。
### 旧任务限界过渡配置
`ANNOTATION_LEGACY_SOURCE_CUTOFF` 默认未设置,保持严格完整源准入。经 2026-11-11 用户明确授权的过渡配置必须在 API/切片处理器上精确一致,发布快照记录该非秘密值,格式或组件不一致阻断。配置变更仍不属于 release.py 的镜像更新范围,须单列实际部署 UID、原值、新值、顺序和回退影响并批准;不能通过修改工具扩大自动发布权限。业务范围见源校验 ADR。此过渡发布保留现用 Worker 与校验器,删除人员后台接管开关继续关闭,不启动全量补验。
### 作业优先发布配置
2026-11-11 用户批准的作业优先模式为 `ANNOTATION_SOURCE_VALIDATION_MODE=advisory`。API 与切片处理器必须一致;缺失默认严格,未知值或组件不一致阻断发布。该配置必须单列审批,旧镜像不认识此变量时不会提前放宽。只切镜像而不启用配置不能恢复本轮作业。基础作业索引与完整源证书独立,Worker 消费的源索引修订协议不变;不启动批量补验。移除 advisory 前重新盘点,避免恢复全量校验阻断,详见[作业优先恢复](../operations/annotation-work-availability.md)。