125 lines
7.7 KiB
Markdown
125 lines
7.7 KiB
Markdown
# Orbit 运行与发布手册
|
||
|
||
这份手册把当前 Orbit 的可执行运维动作串起来。它适用于通用平台部署，不包含业务项目名称、行业规则或外部副作用操作。命令中的数据库地址、凭据和端口都应由部署环境的秘密管理与网络策略注入。
|
||
|
||
## 1. 发布前检查
|
||
|
||
仓库内的可重复门禁可以一次执行：
|
||
|
||
```sh
|
||
make release-local-check
|
||
```
|
||
|
||
该命令覆盖服务端/SDK/独立示例的竞态测试、静态检查、构建、当前协议门禁和文档链接检查，并验证 SDK 不依赖服务端或数据库包。它不会替代 `make integration` 的真实 MySQL 回归，也不会替代目标拓扑的容量、故障切换、RPO/RTO 和生产审批。
|
||
|
||
服务端不会在启动时自动修改数据库。发布人员先准备与当前版本匹配的 `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` 时停止向该节点发送新的受理、执行授权和流程推进请求，保留原幂等键并等待核对，不把网络错误当作业务失败。
|
||
|
||
后台调度默认每秒检查 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`。调优必须和数据库锁等待、连接池、积压及恢复窗口一起记录，不能只提高批量或缩短间隔来掩盖容量不足。
|
||
|
||
## 3. 滚动停止与替换
|
||
|
||
Orbit 接收到 `SIGTERM` 后停止新的 Worker/Event 连接，先将 readiness 置为 `503`，再取消后台循环、关闭 HTTP/WS 监听，并按 `ORBIT_SHUTDOWN_TIMEOUT` 等待已有连接退出。发布脚本应按以下顺序操作：
|
||
|
||
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)。
|