# 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`。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` 等待已有连接退出。发布脚本应按以下顺序操作：

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`、快照超时、数据库连接池等待增加、提交前事务重试/耗尽计数增长或后台批次错误，只能触发调查，不能直接改写任务、流程或审计状态。`orbit_db_transaction_retries_total` 只表示明确的 MySQL 1205/1213 提交前回调重试，`orbit_db_transaction_retry_exhausted_total` 表示该有界重试已耗尽；Commit 回执不明不会计入，必须按稳定操作身份核对原记录。指标字段、告警边界和采集安全要求见[运行指标手册](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)。