
> 《micro-one-api 拆解》第 31 篇
> 代码核对：`v0.41.0` / `372391f`

---

## 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：

```json
{"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` |


《micro-one-api 拆解》第 31 篇 代码核对：v0.41.0 / 372391f

21 秒导入完一份备份，我仍然没敢写「可以恢复」

后端

micro-one-api v0.41.0真实生产归档恢复验证：299,837,819字节数据导入耗时21.184秒，88张数据表逐表一致，Token/渠道密钥/MFA/钱包预扣全量核对通过；首次备份75秒，日槽任务2/2成功。发布门禁暴露gofmt短路、E2E定位器冲突等问题，重发版覆盖旧tag，恢复与发布证据链完整可追溯。

访问管理

代码解释

对象存储

PostgreSQL

数据库

防火墙

容器

路由

SQLite

GitHub

Redis

MySQL

JSON

腾讯云双十一大促

apigw

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

micro-one-api v0.41.0真实生产归档恢复验证：299,837,819字节数据导入耗时21.184秒，88张数据表逐表一致，Token/渠道密钥/MFA/钱包预扣全量核对通过；首次备份75秒，日槽任务2/2成功。发布门禁暴露gofmt短路、E2E定位器冲突等问题，重发版覆盖旧tag，恢复与发布证据链完整...

21 秒导入完一份备份，我仍然没敢写「可以恢复」-腾讯云开发者社区-腾讯云

21 秒导入完一份备份，我仍然没敢写「可以恢复」

21 秒导入完一份备份，我仍然没敢写「可以恢复」

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐