docs: add operations and release runbook

README.md

@@ -96,6 +96,7 @@ SDK 独立发布门禁使用 `make sdk-check`，在 `GOWORK=off` 下检查完整
 - [HTTP / WebSocket 接口手册](docs/api/README.md)
 - [Go SDK 接入](docs/sdk/README.md)
 - [通用场景示例](docs/examples/README.md)
+- [运行与发布手册](docs/20-operations-runbook.md)
 - [设计文档总览](docs/README.md)
 
 Git 远端：`https://git.yuntuo.hk/k2safe/orbit.git`。当前在本地开发分支推进，SDK 尚未发布版本。

docs/20-operations-runbook.md

@@ -0,0 +1,114 @@
+# Orbit 运行与发布手册
+
+这份手册把当前 Orbit 的可执行运维动作串起来。它适用于通用平台部署，不包含业务项目名称、行业规则或外部副作用操作。命令中的数据库地址、凭据和端口都应由部署环境的秘密管理与网络策略注入。
+
+## 1. 发布前检查
+
+服务端不会在启动时自动修改数据库。发布人员先准备与当前版本匹配的 `orbit-migrate`、`orbit-admin` 和 `orbit`，再用迁移账户执行一次迁移；运行账户只需要服务运行所需的数据库权限。
+
+```sh
+export ORBIT_MYSQL_DSN='user:password@tcp(db.internal:3306)/orbit'
+
+./bin/orbit-migrate status
+./bin/orbit-migrate up
+./bin/orbit-admin verify
+```
+
+`verify` 必须返回 `complete=true`、当前 schema 版本、迁移账本完整、外键数量为零和固定观测索引完整。它是只读核验，不会修复脏迁移、删除数据或改变权限；具体输出见[发布前结构核验](api/operations.md)。
+
+发布前还要人工确认：备份文件可读、迁移账户和运行账户分离、目标 DSN 的 TLS/网络策略已验证、旧 SDK/Worker 的兼容范围明确。旧版本不能在新迁移未完成时继续写入不兼容结构。
+
+## 2. 启动与就绪
+
+先注入配置，再启动服务。指标监听默认关闭，生产采集应使用受保护的内部地址。
+
+```sh
+export ORBIT_HTTP_ADDR='0.0.0.0:8080'
+export ORBIT_METRICS_ADDR='127.0.0.1:9090'
+./bin/orbit
+```
+
+启动后检查两个健康端点：
+
+```sh
+curl -fsS http://127.0.0.1:8080/health/live
+curl -fsS http://127.0.0.1:8080/health/ready
+```
+
+`live` 只表示进程仍在运行；`ready` 同时核对 MySQL、迁移账本和零外键要求。收到 `503` 时停止向该节点发送新的受理、执行授权和流程推进请求，保留原幂等键并等待核对，不把网络错误当作业务失败。
+
+## 3. 滚动停止与替换
+
+Orbit 接收到 `SIGTERM` 后停止新的 Worker/Event 连接，取消后台循环，关闭 HTTP/WS 监听并在有限时间内等待已有连接退出。发布脚本应按以下顺序操作：
+
+1. 从服务发现或负载均衡中摘除目标节点，等待健康检查不再分配新流量。
+2. 向进程发送 `SIGTERM`，等待进程退出；超过发布窗口时记录进程和连接状态，再按值班策略处理。
+3. 启动同版本或已验证兼容版本的新节点，先确认 `live` 与 `ready`，再放回流量。
+4. 检查 Worker 重连、未完成租约和结果交付是否按原身份恢复；不要为不明结果生成新幂等键。
+5. 全部节点完成替换后，执行一次 `orbit-admin verify` 和只读运行快照。
+
+服务端不依赖内存状态完成恢复；持久化租约、事件、Inbox 和流程检查点由新节点继续扫描。外部业务副作用仍由接入方按任务尝试、结果证据和业务幂等规则核对。
+
+## 4. 数据库短暂不可用
+
+数据库不可用期间，readiness 应返回 `503`，而不是确认受理成功。恢复后可重复检查：
+
+```sh
+curl -i http://127.0.0.1:8080/health/ready
+ORBIT_MYSQL_DSN="$ORBIT_MYSQL_DSN" ./bin/orbit-admin verify
+ORBIT_MYSQL_DSN="$ORBIT_MYSQL_DSN" ./bin/orbit-admin observe snapshot
+```
+
+写请求在超时、连接断开或响应不明时，必须用原 `Idempotency-Key` 查询或重报；不能换键规避未知状态。可复现的单节点演练见[数据库恢复手册](api/db-recovery.md)，该演练不替代主从切换和 RPO/RTO 验收。
+
+## 5. MySQL 提升与恢复点
+
+数据库主从或集群切换由经过批准的数据库值班流程执行。Orbit 侧动作保持简单且可审计：
+
+1. 确认旧写节点已停止，避免双主写入。
+2. 由数据库值班人员确认副本复制状态、恢复点和可写状态。
+3. 更新受保护的 DSN/路由配置，启动或重启 Orbit 节点。
+4. 运行 `orbit-admin verify`，确认 schema、索引和零外键。
+5. 用原幂等键执行一条隔离核对请求，确认不会创建第二个任务。
+6. 记录故障发现时间、复制确认时间、提升时间、恢复时间和可能的外部效果，形成 RPO/RTO 证据。
+
+隔离环境的 GTID 复制与手工提升命令见[复制演练报告](reports/phase-6-mysql-replication.md)。当前演练没有自动故障探测、虚拟 IP、代理路由或零停机保证，不能直接作为生产 HA 结论。
+
+## 6. 备份与恢复
+
+同版本隔离恢复的可复现入口：
+
+```sh
+ORBIT_TEST_MYSQL_IMAGE=mysql:8.4 \
+  sh scripts/test-backup-restore.sh
+```
+
+生产恢复必须额外记录备份时间点、介质校验、恢复目标、迁移校验和、核心记录数量、权限配置、未确认交付、未知执行和外部副作用核对。脚本只验证一次性 MySQL 容器中的逻辑备份恢复，边界见[备份恢复演练](api/backup-restore.md)。
+
+## 7. 观测与故障判断
+
+启用指标时采集独立端口的 `/metrics`；未启用指标时使用只读快照：
+
+```sh
+curl -fsS http://127.0.0.1:9090/metrics
+ORBIT_MYSQL_DSN="$ORBIT_MYSQL_DSN" ./bin/orbit-admin observe snapshot
+```
+
+快照和业务指标是单节点有界样本。`truncated=true`、快照超时、数据库连接池等待增加或后台批次错误，只能触发调查，不能直接改写任务、流程或审计状态。指标字段、告警边界和采集安全要求见[运行指标手册](api/observability.md)。
+
+## 8. 事故处理原则
+
+| 现象 | 先做什么 | 保留什么证据 |
+| --- | --- | --- |
+| readiness 503 | 停止向该节点发新写入，检查数据库和迁移账本 | 请求时间、原幂等键、readiness 响应 |
+| 受理响应超时 | 用原键查询/重报，等待确定回执 | 请求体摘要、请求 ID、查询结果 |
+| Worker 断线 | 等待重连和租约核对，检查尝试历史 | session、attempt、租约代次、结果证明 |
+| 结果交付积压 | 检查订阅租约、消费者和 Inbox 去重 | delivery、event、Inbox 状态及 ACK 证据 |
+| 流程停在等待或核查 | 读取固定版本、激活、轮次和审计，再执行授权恢复 | recovery 操作键、原因、证据和版本 |
+| 数据库提升 | 先确认旧写节点已停，再切换 DSN 并核验 | 复制状态、恢复点、RPO/RTO、幂等重放结果 |
+
+任何无法证明外部效果的执行都保留为未知或待核查；不能因为租约过期、HTTP 返回错误或进程退出就推断外部副作用已撤销。
+
+## 9. 当前验收边界
+
+当前仓库已经有 Go 1.27.1、MySQL 8.4 的模块、存储、HTTP/WS、进程故障、备份恢复、短暂数据库不可用、手工 GTID 提升和历史任务 API 兼容演练。正式生产发布仍需要目标拓扑上的自动切换、复制确认窗口、跨故障域容量、备份介质、RPO/RTO、值班通知和业务外部效果验收。详见[首版交付核对清单](release-checklist.md)。

docs/README.md

@@ -19,6 +19,7 @@
 | [08 持续开发计划](08-development-plan.md) | 开发、测试回归、阶段验收与最终交付目标 |
 | [19 容量模型](19-capacity-model.md) | 企业规模到任务、流程、数据库与连接负载的推导及生产验收方法 |
 | [P7 协议兼容矩阵](reports/phase-7-compatibility.md) | 当前协议门禁、历史提交双向任务 API 演练与正式标签矩阵边界 |
+| [20 运行与发布手册](20-operations-runbook.md) | 启动、发布、滚动停止、数据库恢复、备份和事故处理 |
 | [09 可靠结果订阅](09-result-subscription-core.md) | 提交水位、冻结结果与可靠交付 |
 | [10 Weave决策与交付](10-workflow-engine-core.md) | 有限步骤决策和内部结果Inbox |
 | [11 Weave实例受理](11-workflow-admission.md) | 固定版本、初始图和首批任务事务 |