8.6 KiB
Orbit 运行与发布手册
这份手册把当前 Orbit 的可执行运维动作串起来。它适用于通用平台部署，不包含业务项目名称、行业规则或外部副作用操作。命令中的数据库地址、凭据和端口都应由部署环境的秘密管理与网络策略注入。
1. 发布前检查
仓库内的可重复门禁可以一次执行：
make release-local-check
该命令覆盖服务端/SDK/独立示例的竞态测试、静态检查、构建、当前协议门禁和文档链接检查，并验证 SDK 不依赖服务端或数据库包。它不会替代 make integration 的真实 MySQL 回归，也不会替代目标拓扑的容量、故障切换、RPO/RTO 和生产审批。
服务端不会在启动时自动修改数据库。发布人员先准备与当前版本匹配的 orbit-migrate、orbit-admin 和 orbit，再用迁移账户执行一次迁移；运行账户只需要服务运行所需的数据库权限。
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 版本、迁移账本完整、外键数量为零和固定观测索引完整。它是只读核验，不会修复脏迁移、删除数据或改变权限；具体输出见发布前结构核验。
发布前还要人工确认：备份文件可读、迁移账户和运行账户分离、目标 DSN 的 TLS/网络策略已验证、旧 SDK/Worker 的兼容范围明确。旧版本不能在新迁移未完成时继续写入不兼容结构。
2. 启动与就绪
先注入配置，再启动服务。指标监听默认关闭，生产采集应使用受保护的内部地址。
export ORBIT_HTTP_ADDR='0.0.0.0:8080'
export ORBIT_METRICS_ADDR='127.0.0.1:9090'
./bin/orbit
启动后检查两个健康端点：
curl -fsS http://127.0.0.1:8080/health/live
curl -fsS http://127.0.0.1:8080/health/ready
live 只表示进程仍在运行；ready 同时核对 MySQL、迁移账本和零外键要求。收到 503 时停止向该节点发送新的受理、执行授权和流程推进请求，保留原幂等键并等待核对，不把网络错误当作业务失败。
后台调度默认每秒检查 Weave 和计划、每两秒执行一次执行恢复，每批最多处理100条持久化候选。容量验证后可以通过 ORBIT_WORKFLOW_TICK_INTERVAL、ORBIT_SCHEDULE_TICK_INTERVAL、ORBIT_RECOVERY_TICK_INTERVAL 和 ORBIT_RUNTIME_BATCH_LIMIT 调整；间隔只允许 100ms 到 1m，批量只允许 1 到 100。ORBIT_SHUTDOWN_TIMEOUT 控制 SIGTERM 后的排空和优雅关闭窗口，允许 1s 到 5m，默认 10s。Worker/Event WebSocket 连接上限分别由 ORBIT_WORKER_CONNECTION_LIMIT、ORBIT_EVENT_CONNECTION_LIMIT 控制，范围 1 到 4096；每个 Hub 的数据库领取协程和有界内存排队由 ORBIT_DISPATCH_WORKERS、ORBIT_DISPATCH_CAPACITY 控制，范围分别为 1 到 256、1 到 65536。数据库事务对提交前的 1205/1213 只做最多两次短退避重试，提交回执不明绝不自动重放；因此仍必须保留稳定幂等键并核对原操作。参数只影响单节点内存和领取并发，真实授权、租约和配额仍由 MySQL 决定。调优必须和数据库锁等待、连接池、积压及恢复窗口一起记录，不能只提高批量或缩短间隔来掩盖容量不足。
3. 滚动停止与替换
Orbit 接收到 SIGTERM 后停止新的 Worker/Event 连接，先将 readiness 置为 503，再取消后台循环、关闭 HTTP/WS 监听，并按 ORBIT_SHUTDOWN_TIMEOUT 等待已有连接退出。发布脚本应按以下顺序操作：
- 从服务发现或负载均衡中摘除目标节点，等待健康检查不再分配新流量。
- 向进程发送
SIGTERM，等待进程退出；超过发布窗口时记录进程和连接状态，再按值班策略处理。 - 启动同版本或已验证兼容版本的新节点，先确认
live与ready，再放回流量。 - 检查 Worker 重连、未完成租约和结果交付是否按原身份恢复；不要为不明结果生成新幂等键。
- 全部节点完成替换后，执行一次
orbit-admin verify和只读运行快照。
服务端不依赖内存状态完成恢复；持久化租约、事件、Inbox 和流程检查点由新节点继续扫描。外部业务副作用仍由接入方按任务尝试、结果证据和业务幂等规则核对。
4. 数据库短暂不可用
数据库不可用期间，readiness 应返回 503，而不是确认受理成功。恢复后可重复检查：
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 查询或重报；不能换键规避未知状态。可复现的单节点演练见数据库恢复手册，该演练不替代主从切换和 RPO/RTO 验收。
5. MySQL 提升与恢复点
数据库主从或集群切换由经过批准的数据库值班流程执行。Orbit 侧动作保持简单且可审计：
- 确认旧写节点已停止，避免双主写入。
- 由数据库值班人员确认副本复制状态、恢复点和可写状态。
- 更新受保护的 DSN/路由配置，启动或重启 Orbit 节点。
- 运行
orbit-admin verify，确认 schema、索引和零外键。 - 用原幂等键执行一条隔离核对请求，确认不会创建第二个任务。
- 记录故障发现时间、复制确认时间、提升时间、恢复时间和可能的外部效果，形成 RPO/RTO 证据。
隔离环境的 GTID 复制与手工提升命令见复制演练报告。当前演练没有自动故障探测、虚拟 IP、代理路由或零停机保证，不能直接作为生产 HA 结论。
6. 备份与恢复
同版本隔离恢复的可复现入口：
ORBIT_TEST_MYSQL_IMAGE=mysql:8.4 \
sh scripts/test-backup-restore.sh
生产恢复必须额外记录备份时间点、介质校验、恢复目标、迁移校验和、核心记录数量、权限配置、未确认交付、未知执行和外部副作用核对。脚本只验证一次性 MySQL 容器中的逻辑备份恢复，边界见备份恢复演练。
7. 观测与故障判断
启用指标时采集独立端口的 /metrics；未启用指标时使用只读快照：
curl -fsS http://127.0.0.1:9090/metrics
ORBIT_MYSQL_DSN="$ORBIT_MYSQL_DSN" ./bin/orbit-admin observe snapshot
快照和业务指标是单节点有界样本。truncated=true、快照超时、数据库连接池等待增加、提交前事务重试/耗尽计数增长或后台批次错误，只能触发调查，不能直接改写任务、流程或审计状态。orbit_db_transaction_retries_total 只表示明确的 MySQL 1205/1213 提交前回调重试，orbit_db_transaction_retry_exhausted_total 表示该有界重试已耗尽；Commit 回执不明不会计入，必须按稳定操作身份核对原记录。指标字段、告警边界和采集安全要求见运行指标手册。
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、值班通知和业务外部效果验收。详见首版交付核对清单。