泛宇发布试行流程
日常开发按分层验证流程执行,不在每次编辑后重复本发布流程。
本页发布门禁及 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。保留 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 镜像(处理器使用同一镜像):
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 名字相同也不能蒙混过关。
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:本地检查与线上只读快照
python3 scripts/release.py check <release-id> --local
python3 scripts/release.py check <release-id> --cluster
本地检查命令和环境约束以 fanyu-policy.json 为准。
看板稳定性门禁分别运行 race 正确性检查和显式 -race=false 的性能计时;两者均必须通过,
并发读取 2 秒门槛不变。看板浏览器门禁覆盖当前生产与质量页面的五角色、项目筛选、快照及导出,
不再把已替换的旧页面布局当成当前入口。返工浏览器夹具运行真实本地校验处理器,不能绕过源数据准入。
统一候选涉及的额外组件与待确认发布项见 组件发布计划。首版运行流程工具测试、
前端类型/构建及切片恢复定向回归,不冒充全套产品测试通过。任何失败阻断,不支持忽略开关。
命令执行结果及输出摘要写入记录,不保存或回显原始输出;排查失败时单独重跑对应命令。
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:形成可审查的计划
python3 scripts/release.py plan <release-id>
显示旧/新镜像、构建标记、目标、带宽观察值、限制与回退说明,并生成计划摘要。 核对两个部署的修改范围。计划不更新 ConfigMap、Secret、存储或网络。
部署前需要两份人工审查证据:
image-provenance:构建记录将本次源码 commit 与镜像 digest 对应,候选镜像的验证情况明确。change-safety:审查启动迁移/兼容性,检查在途切片与送检工作,确定维护窗口或安全切换方式, 并说明回退旧版本是否安全。工具不自行读取或更改业务数据库来判断任务状态。
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:本次授权后的有界变更
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:分开基础设施与业务验收
python3 scripts/release.py verify <release-id>
核对目标镜像、构建标记、rollout、配置/PVC/服务身份以及未批准的部署变化。
未 Ready 可稍后重新运行只读 verify,不重新 deploy。部署配置符合后仍为
deployed_pending_acceptance,不等于已经登录、播放、切片或送检成功。
按策略中 requiredEvidence 逐项记录验收:五角色登录及业务API、多供应商权限、标注与交付 (普通/舍弃/无效/空白)、质检/终审、切片重启恢复、视频首帧/缓冲/实际播放速度。 所有写入测试都遵循前述隔离与授权要求,不能占用生产客户任务。
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 整库或覆盖客户新增数据。首版不自动执行回退。
- 紧急修复写明“已解决 / 未解决 / 临时取舍 / 后续任务”,关联本地问题票;未验证部分仍保留, 不因上线紧急而自动验收通过。旧规格由新规则显式替代,不同时保留两份有效相反结论。
本地试运行与后续范围
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 是当时的结论,不代表按当前策略重新验证通过。需要继续发布时创建新记录。
只有尚无部署尝试的旧计划可以标记被替代:
python3 scripts/release.py supersede <old-id> --by <replacement-id> --reason '核实过的替代关系'
此命令只写本地记录:先按内容哈希备份原文,再追加替代关系,保留原状态、计划摘要、证据和事件。 之后旧计划的 check/plan/deploy/verify/evidence 均阻断。目标必须是同一集群身份的当前记录。 已经执行过、部分执行或结果未知的记录不允许这样归档,避免掩盖部署与验收缺口。
下一次发布前:核对候选代码是否包含线上修复
线上 build commit、PR 提取提交及 dev 可能不同。不可仅因某个 PR 测试通过就将其分支当作线上完整版本。 先只读保存 API、处理器及 Worker 的 Deployment 快照,核实目标身份、采样时间和真实镜像,再执行:
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 核对结果见 版本一致性盘点。
看板稳定性门禁(2026-10-26)
Fanyu 的 localChecks 新增 python3 scripts/test_dashboard_stability.py,固定使用经核实的本地
Mongo 27018 合成隔离库,包含 24000 条/来源规模、历史兼容、故障恢复和权限检查。
关键测试未执行、跳过或失败均阻断,不能以无 Mongo 时的 skip 结果发布。
上线时还需审查三个统计索引的创建授权及可选诊断字段的混合版本行为;验收同时检查真实看板
200 与快照持续更新,不能只看进程健康。接口、检查器和边界见看板持续运行说明。