《micro-one-api 拆解》第 31 篇 代码核对:
v0.41.0/372391f(2026-11-12) 主要改动:B3/N2/N4 与 v0.41.0 重新发版门禁,2026-10-30 至 11-12 主要来源:B3 冻结契约、B3/MinIO/N2/B4/N4 runbook、v0.38.0/v0.39.0/v0.41.0 release note
0. 21.184 秒只是导入,不是恢复结论
11 月 9 日,我用一份真实生产归档在一个独立空环境里恢复。MySQL/Redis 都是相同镜像,恢复目标使用独立 Compose 项目和空卷。解密后的数据是 299,837,819 字节,9 个 schema、24 个归档文件;恢复后 88 张有数据表的 INSERT 内容逐表与原库相同。
恢复导入耗时 21.184 秒。
这个数字很容易被写成“生产恢复 21 秒”。但它后面还有一段更长的核对:从独立下载开始,到镜像准备、环境配置重试、启动真实 owner、检查 Token、渠道密钥、MFA、钱包和预扣,整段是 732.110 秒,约 12 分 12 秒。21.184 秒只是归档倒进数据库的时间;恢复是不是可信,取决于恢复出来的系统还能不能按原来的权限和业务语义工作。
B3 把控制面、worker 和产物做出来,N2 把真实生产归档恢复到隔离环境。再往后,B4/N4 补的是用户运营和公告,v0.41.0 重新发版则把发布门禁本身的失误暴露出来。这几件事放在一篇里,是因为它们都在回答同一个问题:我说“完成”时,究竟已经越过了哪道门。
1. 备份与发布通道的来源
这一篇跨了三层:B3 是工程能力,N2 是真实生产归档恢复,B4/N4 是用户运营旅程,最后一段是发布门禁。每个结论都要能找到对应的来源,不能把 B3 的隔离夹具、N2 的生产恢复和 v0.41.0 的 CI 结果拼成一个“整体通过”。
| 主题 | 契约 / 计划 | 实施与证据 | 关键提交 |
|---|---|---|---|
| B3 管理化备份 | docs/design/b3-managed-backup-contract-2026-10-30.md、docs/releases/release-v0.38.0.md |
docs/runbooks/b3-managed-backup-acceptance-2026-10-30.md、docs/runbooks/b3-minio-enablement-2026-11-01.md |
14f58fec、6a0e19ca |
| N2 异机恢复 | docs/design/next-stage-plan-2026-11-08.md |
docs/runbooks/n2-offsite-recovery-2026-11-09.md、docs/runbooks/evidence/n2-offsite-recovery-2026-11-09.json |
4d82ea30、66709a1b、a874a563 |
| B4 用户运营 | docs/design/b4-user-operations-contract-2026-11-02.md、docs/releases/release-v0.39.0.md |
docs/runbooks/b4-user-operations-acceptance-2026-11-02.md |
377e9028 |
| N4 公告 / 模型可用性 | docs/design/next-stage-plan-2026-11-08.md |
docs/runbooks/n4-announcements-acceptance-2026-11-12.md、docs/runbooks/evidence/n4-announcements-acceptance-2026-11-12.json |
72792e8f |
| v0.41.0 重发 | docs/releases/release-v0.41.0.md |
两个 CI run、Release E2E、docs/runbooks/c1-passkey-acceptance-2026-11-12.md |
a1c2593d、5eb2ece7、c03ab6a8、aee6cc05 |
B3 的工程验收是 10 月 30 日,MinIO/worker 接通是 11 月 1 日,首个生产备份和隔离恢复是 11 月 9 日,第二个实际日槽是 11 月 10 日。它们每一步都在扩大证据面,但并不意味着前面一步已经完成了后面一步。
2. B3 先解决“谁来备份”和“谁来证明”
原来的备份问题是能力缺一块,不是缺一个 cron。控制面、任务回执、worker 状态、审计、存储凭据和恢复索引分散在不同地方,最后就会出现“文件传上去了,但不知道它对应哪个时刻、哪个配置、哪个镜像”。
B3 的职责切得很硬:
| 角色 | 能做什么 | 不能做什么 |
|---|---|---|
admin-api |
策略、任务回执、worker 状态、append-only 审计,控制表在 oneapi_admin |
不接触制品凭据,不直接执行 dump |
host backup-worker |
host + MySQL 双锁、stop-the-world 一致性、age 加密、S3 条件写入、恢复和保留策略 | 不把权限注入 admin-api |
| 私有对象存储 | 只接受限定前缀的条件写入,匿名访问拒绝 | 不是唯一恢复索引,不负责业务语义 |
| IAM + step-up | admin.backups 全局执行点,写操作要求新鲜证明 |
读状态不需要写证明 |
迁移 147 建四张控制表:backup_policies、backup_jobs、backup_events、backup_worker_state,默认策略是 Enabled=false、worker 状态 offline。这台机器上真正执行备份的是 host worker,不在 Admin 进程里。worker 配置覆盖 9 个应用 schema 和 19 个恢复配置文件,每次快照重新读取在线 Compose 和镜像清单,不保存一份可能过期的展开配置。
恢复材料不是只有一份加密 SQL。worker 还保留外部恢复索引、receipt、归档时间点、镜像清单和配置引用;age 私钥只在维护者开发机,公钥进 worker。归档写 S3 使用条件不覆盖写入,避免两个任务同时写同一个对象时后一个悄悄覆盖前一个。
任务状态不是数据库里随便留一个字符串,它直接决定能不能说“可恢复”:
| 状态 | 含义 | 后续动作 |
|---|---|---|
| queued | 持久接收,尚未执行 | 只能由同一 leader 认领;同一时间最多一个手动任务在排队或运行 |
| running | leader 已认领并冻结策略 | 有运行超时;worker 启动时先恢复服务,再把旧 running 标为 uncertain |
| succeeded | 加密对象、私有性、读回摘要、外部 receipt、服务恢复全部通过 | 才进入可选恢复目录 |
| failed | 明确失败,没有承诺可恢复对象 | 保留证据,可重新发起独立新任务 |
| uncertain | worker 中断、上传结果不明或服务恢复不完整 | 不自动重放原任务,必须先核对对象和 receipt |
保留策略只清理当前存储命名空间里超出数量的 succeeded,始终至少留两份;failed/uncertain 不自动删除。更换 bucket/prefix 也不删除旧对象,旧命名空间要独立核对后处理。这条规则比“定时删七份之外”麻烦,但它避免一个状态不确定的备份被清理任务顺手删掉。
B3 的一致性边界也很具体:
- 先拿 host 锁,再拿 MySQL 锁,两个锁都拿到才进入停写;
- 停写期间记录所有实际 writer,包括 profile 中默认隐藏的
channel-account-ops-worker; - 实际运行服务不在备份模型里时,在任何停写前拒绝;
- 备份成功后原 writer 和 Redis 必须恢复,健康接口重新通过;
- 恢复目标必须空 MySQL、空 Redis、Redis AOF 关闭,只允许存储和恢复容器运行;
- 归档先校验 receipt、age EOF、manifest、全部文件哈希和 schema 集合,再开始导入。
工程验收使用隔离 MySQL/Redis/S3 和一个小型 21,010,991 字节夹具。备份 2.151 秒,恢复导入 2.371 秒,下载到 owner 核对完成 3.027 秒。它还核对了原 API Token、MFA 解密、渠道密钥、钱包、未结算预扣重复认领和重复释放。这些秒数只说明夹具链路,不拿来推生产容量。
3. 控制面 200 与 worker ready,不是“有备份”
11 月 1 日接 MinIO 时,两个管理 GET 一直返回 503。根因不是备份逻辑,而是实际 admin-api 没有设置 BACKUP_CONTROL_ENABLED,线上 Compose 也没有透传;开启以后,Admin 运行账号又缺四张 147 控制表的权限,SQL 报 SELECT command denied。两处修完,接口才从 503 变成 200。
接着又发现三个拓扑问题:
channel-account-ops-worker实际写 SQL,却不在备份 Writers 里;默认compose config还会隐藏它的 profile。worker 现在展开全部 profile,发现实际运行服务不在模型里,就在停写前拒绝。- worker 的策略表权限模板只有 SELECT,调度领取任务用
SELECT ... FOR UPDATE会被 MySQL 拒绝。模板补成 SELECT + UPDATE。 - 没有对象存储和 host worker。MinIO 在独立 Compose 项目里,只绑
127.0.0.1:9000,Console 关闭;bucket 私有,worker 账号只限micro-one-api/production/*,与管理员凭据分离。
最后 worker 为 ready,两个 GET 为 200,catalog 和一次空跑成功。定时策略仍然关闭,任务数为 0。
这组检查只能证明控制面、存储权限和空闲调度链路可用。我在 runbook 里专门写了:ready 不是已有成功备份,也不是恢复 SLA。这个区别后来在 N2 里变成了真实的生产数据。
4. N2:先证明备份能被独立恢复,再打开每天任务
11 月 9 日的第一份生产全量备份名为 n2-production-20261109-first,12:19:33–12:20:48,75 秒,32,667,974 字节。原 MySQL/Redis 容器恢复后 ID 和镜像都没有变。
恢复环境做了几件“不图省事”的事:
- 异机存储独立放在
/opt/micro-one-api-backup,HTTPS 证书校验,防火墙只允许生产来源,匿名访问拒绝; - 开发机经 SSH 隧道直接访问异机 S3,
catalog/fetch不连接生产控制库; - 恢复使用相同 MySQL/Redis 镜像、独立 Compose 项目和空卷;
- 解密后 299,837,819 字节,9 个 schema、24 个归档文件;
- 88 张有数据表逐表比较 INSERT 内容,0 差异;
- 19 条原 Token 记录、3 份真实渠道凭据、原加密密钥和 MFA 隔离流程分别核对;
- 在恢复副本上创建 100 quota 预扣,重复认领和释放后精确回到原值。
备份覆盖了控制面、配置文件和密钥,但恢复出来的历史 running 任务被标记为 uncertain,没有在恢复环境里重新跑备份。恢复环境也没有启动业务服务和上游调用,避免把隔离验收变成一次真实流量。
恢复后的 owner 核对分成四层:
| 层 | 核对内容 | 证据边界 |
|---|---|---|
| SQL | 88 张有数据表 INSERT 内容逐表相同 | 数据内容一致,不等于恢复环境能启动业务 |
| 身份 | 19 条 Token、原管理员会话、隔离 API Key | 没有重放用户原 API Key 明文 |
| 配置密钥 | JWT、Token hash、MFA、渠道密钥逐项一致 | 不保存秘密值,不在恢复环境调用真实渠道 |
| 资金 | 钱包、原正金额 reserved、预扣幂等与释放 | 复制的预扣只写隔离副本 |
随后策略从 revision 1 更新到 revision 2:
{"enabled":true,"interval_hours":24,"retain":7,"rpo_hours":24,"rto_minutes":60}
调度按 UTC 日槽,启用后立即执行当前槽,以后对应北京时间每天 08:00。首个日槽 73 秒成功,Docker die/start 事件跨度 27.106 秒;首次手动任务只保留了采样,停写上界为 45 秒,两种测量不能混写成同一精度。11 月 10 日第二个日槽成功,实际观察 2/2,整份归档 31.674 MiB,摘要一致。
本轮 26 小时观察窗内重建的最大备份年龄是 19h21m31s,符合 24 小时目标,但 24 小时周期没有给执行和上传留余量。我没有把它升格成长期 SLA,只把持续运行留在运维跟踪里。
日槽过程中还抓到一个只在 MySQL 出现的 409。xdb 统一开启 clientFoundRows,no-op upsert 也返回 1;原来的 Claim 把这个 1 当成“刚插入新任务”,随后对已完成的同槽任务执行 queued→running CAS,自然冲突。修复保留全局连接设置,在 policy 的 FOR UPDATE 锁内先查日槽,已存在就空闲返回,只为新槽插入。SQLite/MySQL/PostgreSQL 共 9 项边界回归,覆盖成功、失败、不确定、连续轮询和下一槽领取。只跑 SQLite 不会暴露这个语义差异。
5. B4/N4:用户侧的空状态也要有证据
B4 的来源是 docs/design/b4-user-operations-contract-2026-11-02.md。它做的是用户运营包:用户自己的模型可用状态、定向/定时/到期公告、版本化已读,以及管理员公告管理。它新增 Admin 148 四张表迁移,权限是 admin.content,不把公告写进渠道配置。
契约里先限制了三件事:
- 用户只看到本人可用模型和聚合状态,不返回渠道名称、ID、数量、上游供应商或故障详情;
- 用户分组使用 Identity 当前默认路由组 ID,不接受浏览器声明、IAM 角色或 Token 分组;
- 模型状态是路由配置快照,最长 15 秒缓存,不代表实时健康、并发余量或账户余额。
公告状态是 draft/published/archived。立即发布时由 owner 冻结实际发布时间,没有后台定时任务,读时按 owner 时间判断;到期后列表消失,但记录保留。保存使用 revision 条件更新,创建 revision=0,修改必须带当前 revision 和至少三个字符的原因,保存和审计同事务。任何编辑增加 revision,旧已读不覆盖新版本。
工程侧最关键的不是页面,而是矩阵:哪些用户能看到、公告什么时候进入列表、已读回执如何版本化、公告归档后是否还能读、普通用户访问管理接口是否 403。N4 用临时用户把这条旅程走完:
- draft 对普通用户不可见;
- 发布后,非目标用户不可见;
- 指定 group 公告只对角色的组成员可见;
publish_at未到不可见,到时间后自动出现;- 到期后从列表消失;
- 编辑让 revision 从 1 到 2,过期 revision 返回 409 CAS 冲突;
- 已读回执成功,归档后列表不可见;
- 用户模型可用性返回 6 个模型名,不泄露渠道和上游。
测试公告 5 条,及 reads/events/targets、临时用户、IAM 角色、MFA 配置都清理了。这里仍然只是我的受控测试用户,不是真实用户反馈。
N4 过程中还遇到一个很实际的部署差异:保存公告要求 HTTP PUT,busybox wget 不支持,只能用 nc 发原生 HTTP/1.1。另一个临时 MFA secret 因为登录 challenge 需要 Redis,返回了 503,随后清除恢复。它们不是业务缺陷,但如果不写进验收记录,下一个人会重复踩。
6. v0.41.0 重新发版:门禁挡下的不是“格式问题”
v0.41.0 本来要发布的是 Passkey 和 /v1/rerank。第一次发布后,develop 的两次 CI 都在 Backend / Check Go formatting 失败:challenge.go 的 import 顺序不符合 gofmt。
这件事表面上只是格式。但该步骤位于 Backend job 首位,后面 test、race、architecture、RBAC 和生成文件校验都没有执行。一个格式错误把后面所有门禁一起短路,发布流水线看起来只失败了一项,实际证据覆盖已经缩到零。
修格式的同时,passkey 的 anti-enumeration 回归又发现了上一节说的 user-0 诱饵错误。它和格式问题一起修,补了 biz 回归和 24576 字节边界测试。
第二次重新发版,Release 的 E2E gate 又失败:登录页新增“使用通行密钥登录”按钮后,web/e2e/admin-smoke.spec.ts 里的 getByRole('button', { name: '登录' }) 同时匹配新按钮和提交按钮,Playwright strict mode 直接报错。修复是把 locator 改成 exact: true,本地 chrome / mobile-chrome 两个用例 2/2 通过。
最终 v0.41.0 用同一版本号重新发布,覆盖原 tag 和同名镜像。这个决定有代价:已经按旧 tag 部署的环境不会自动滚动更新,必须显式重新部署。发布文档也校正了 /v1/rerank 的 8 MiB 预算、identity_passkey 表名和 passkey_enabled 的全局能力语义。
| 门禁事件 | 暴露的问题 | 最后怎么处理 |
|---|---|---|
| Backend format | import 顺序错误短路后续所有 Backend 校验 | gofmt 修复,补跑完整门禁 |
| Passkey anti-enumeration | user 0 诱饵在 complete 阶段错误形状不同 | 在 IAM 查询前返回 ErrMFAInvalid,补回归 |
| Release E2E | 新按钮导致 strict-mode locator 冲突 | locator 改 exact: true,桌面/移动复跑 |
| 发布文档 | rerank 预算、表名、开关语义写错 | 校正 release note / CHANGELOG / README |
重新发版不是“CI 一次绿了就行”。同名 tag 被覆盖,镜像和源码摘要、线上实际部署的 identity-service 摘要、回滚锚点都要重新对。identity-service 热更新后 running、restarts=0,GET /api/user/security 仍是 401,passkey begin/complete 在未配置 RP 时返回 503 MFA_UNAVAILABLE。这些都是功能暗开关和鉴权边界,不是真实 passkey 设备验收。
7. 哪些门已经过了
| 问题 | 已拿到的证据 | 仍然空着 |
|---|---|---|
| 备份任务能不能完成 | 首次生产 75 秒、日槽 73 秒、两份归档、2/2 调度 | 24h 周期长期执行余量 |
| 备份能不能恢复 | 299,837,819 字节、88 表一致、owner 业务核对、21.184 秒导入 | 生产覆盖恢复和切流 SLA |
| 恢复后的原系统还能不能用 | Token、渠道密钥、MFA、钱包和预扣都在隔离副本核对 | 真实用户会话/真实业务流量 |
| 用户运营能不能走通 | N4 公告生命周期、定向、定时、到期、已读、模型可用性 | 真实用户旅程 |
| 发布流水线能不能挡住错误 | format、race、architecture、RBAC、Release E2E 和同名重发流程 | 后续每次发布仍要重新跑,不继承本轮绿灯 |
21.184 秒这个数字我保留了,因为它确实是一次真实恢复导入。但它只是一条证据,不是标题之外的结论。能把一份归档倒进去,不等于能在事故里恢复服务;能恢复服务,也不等于长期备份目标已经持续满足。
下一篇回到请求入口:Gemini 原生入站和 /v1/rerank 加进来以后,为什么 [DONE] 之前还要先结账。
代码与阅读入口
| 想核对的内容 | 仓库入口 |
|---|---|
| 控制面、审计、策略与 worker 状态 | app/admin/internal/server/backup.go、app/admin/internal/service/backup.go、migrations/147_create_managed_backups.sql、docs/design/b3-managed-backup-contract-2026-10-30.md |
| 双锁、停写、归档、恢复、S3 | domain/backup/data/host_lock.go、domain/backup/data/runner.go、domain/backup/data/archive.go、domain/backup/data/restore.go、domain/backup/data/s3.go、domain/backup/data/worker.go |
| B3 契约与恢复流程 | domain/backup/README.md、deployments/backup/README.md、deployments/backup/worker.example.json |
| 同槽 409 回归 | domain/backup/data/backup_test.go、scripts/test-managed-backup-control.sh |
| 公告与用户运营 | app/admin/internal/biz/announcement.go、app/admin/internal/data/announcement.go、migrations/148_create_announcements.sql、docs/design/b4-user-operations-contract-2026-11-02.md |
| 发布门禁与 E2E | web/e2e/admin-smoke.spec.ts、.github/workflows/ci.yml、.github/workflows/release.yml |
| 验收记录 | docs/runbooks/b3-managed-backup-acceptance-2026-10-30.md、docs/runbooks/b3-minio-enablement-2026-11-01.md、docs/runbooks/n2-offsite-recovery-2026-11-09.md、docs/runbooks/b4-user-operations-acceptance-2026-11-02.md、docs/runbooks/n4-announcements-acceptance-2026-11-12.md |
| 版本边界 | docs/releases/release-v0.38.0.md、docs/releases/release-v0.39.0.md、docs/releases/release-v0.40.0.md、docs/releases/release-v0.41.0.md |
上一篇是第 30 篇:四笔闲时请求与计费证据;下一篇是第 32 篇:新入口与结算边界。