发布物身份清单

orbit-admin release manifest 不连接数据库，输出当前二进制内置的构建身份、协议版本和完整迁移名称/校验和。它用于在构建阶段冻结发布证据；输出不含 DSN、凭据、迁移 SQL 或业务数据。

docker run --rm --entrypoint /usr/local/bin/orbit-admin registry.example/orbit:1.0.0 release manifest > orbit-release-manifest.json
# 本地工作区也可执行：
make release-manifest > orbit-release-manifest.json

清单中的 build.revision 应与源码提交和镜像 OCI revision 标签一致，schema 应与部署前 orbit-admin verify 返回的迁移账本逐项一致。清单只证明发布物声明的身份，不能证明目标数据库已切换、备份可恢复或目标拓扑满足 RPO/RTO。

示例结构：

{
  "manifest_version": 1,
  "build": {
    "version": "1.0.0",
    "revision": "<immutable-commit>",
    "built_at": "2026-09-20T00:00:00Z",
    "go_version": "go1.27.1",
    "http_protocol_version": "1",
    "worker_protocol_version": "1",
    "event_protocol_version": "1",
    "workflow_schema_version": 1
  },
  "schema": {
    "current_version": 30,
    "migration_count": 30,
    "migrations": [
      {"version": 1, "name": "000001_initial.up.sql", "checksum": "<sha256>"}
    ]
  }
}

发布前结构核验

orbit-admin verify 是只读的发布、迁移和恢复前置检查。它不会执行迁移、修复脏账本、删除数据或修改权限；数据库账户通过 ORBIT_MYSQL_DSN 注入，建议使用受限只读账户。

ORBIT_MYSQL_DSN='user:password@tcp(127.0.0.1:3306)/orbit' \
  go run ./cmd/orbit-admin verify

成功时输出类似：

{"schema_version":31,"migration_count":31,"foreign_key_count":0,"required_index_count":6,"complete":true}

complete=true 表示当前二进制的迁移账本、Orbit 表零外键，以及 000026–000028 的六个有界观测索引均满足要求。需要同时核对发布物身份时，传入保存的清单：

ORBIT_MYSQL_DSN='user:password@tcp(127.0.0.1:3306)/orbit' \
  go run ./cmd/orbit-admin verify --manifest orbit-release-manifest.json

--manifest 会在连接数据库前比较清单与当前管理二进制的构建身份、协议版本和迁移校验和；不一致立即失败。命令不会证明备份可恢复、复制已确认、业务副作用已核对或生产 RPO/RTO 达标；这些仍需隔离环境恢复演练和真实拓扑验收。失败时会先输出不含 DSN/密钥的检查结果，再以非零状态退出。

发布流程应先停止不兼容的旧写入节点，在隔离环境和目标维护窗口应用 orbit-migrate up，随后执行 orbit-admin verify；只有输出完整且人工核对备份、权限、连接路由后才启动新版本。verify 不是运行时协调器，多个节点可并发读取，但不能替代一次性迁移锁。

2. 只读运行快照

需要在没有开启指标监听时查看平台积压趋势，可执行：

ORBIT_MYSQL_DSN='user:password@tcp(127.0.0.1:3306)/orbit' \
  go run ./cmd/orbit-admin observe snapshot

命令只执行固定索引上的只读查询，输出 snapshot、sample_limit、event_window_seconds 和 scope。任务、交付、流程、Inbox按固定状态分别采样，每个状态最多10000条；事件和阶段耗时只看最近5分钟。达到上限时 snapshot.truncated=true，计数只能解释为本节点有界样本，不能作为全局精确数量。命令不接受租户、状态或表名参数，也不执行修复、归档、删除和权限变更。

示例：

{"snapshot":{"task_states":{"WAITING":0,"LEASED":0,"RUNNING":0,"NEEDS_REVIEW":0,"SUCCEEDED":0,"FAILED":0,"CANCELLED":0},"task_oldest_age_seconds":0,"delivery_states":{"PENDING":0,"LEASED":0,"ACKED":0,"EXPIRED":0},"delivery_oldest_age_seconds":0,"workflow_states":{"RUNNING":0,"WAITING":0,"CANCELLING":0,"NEEDS_REVIEW":0,"SUCCEEDED":0,"FAILED":0,"CANCELLED":0},"workflow_oldest_age_seconds":0,"inbox_states":{"PENDING":0,"LEASED":0,"PROCESSED":0,"QUARANTINED":0},"inbox_oldest_age_seconds":0,"truncated":false,"recent_events":{},"task_terminal_latency_seconds":0,"task_terminal_latency_max_seconds":0,"workflow_terminal_latency_seconds":0,"workflow_terminal_latency_max_seconds":0,"task_accept_to_start_latency_seconds":0,"task_accept_to_start_latency_max_seconds":0,"task_accept_to_terminal_latency_seconds":0,"task_accept_to_terminal_latency_max_seconds":0,"workflow_start_to_terminal_latency_seconds":0,"workflow_start_to_terminal_latency_max_seconds":0},"sample_limit":10000,"event_window_seconds":300,"scope":"single database node; bounded sample, not a global exact count"}

它与 /metrics 共享同一有界读取实现，但不会改变指标注册器或业务状态；遇到数据库超时会返回非零状态，调用方应保留上一次成功快照并排查数据库。

文件归档与离线核验

orbit-admin retention archive / verify-archive 提供持久文件作业、原目录续跑及摘要链核验。读取命名空间需显式指定已保存策略版本，每个新批次记录独立作业审计，源记录不删除；离线核验无需数据库。

周期归档部署、持久卷及故障处理见周期归档管理；需 Schema 31，默认关闭后台归档执行器。

5.3 KiB Raw Blame History Unescape Escape

发布物身份清单

发布前结构核验

2. 只读运行快照

文件归档与离线核验

5.3 KiB

Raw Blame History