# Orbit 容器发布说明

本文定义通用 Orbit 镜像的构建内容、启动契约和探针语义。镜像不包含业务 Worker、行业规则或数据库；数据库连接、凭据和 TLS 参数由部署环境注入。

## 1. 构建

根目录的 `Dockerfile` 使用仓库声明的 Go 1.27.1 构建三个可执行文件：

- `/usr/local/bin/orbit`：HTTP、Worker/Event WebSocket 和后台恢复进程。
- `/usr/local/bin/orbit-migrate`：显式执行迁移；服务启动不会自动改库。
- `/usr/local/bin/orbit-admin`：结构核验、凭据初始化和只读运维命令。

构建阶段关闭 CGO 并使用 `-trimpath`，运行阶段为无 shell 的最小镜像，以减少运行时写入面。镜像保留系统 CA 证书，允许通过受保护 DSN 使用 MySQL TLS。

```sh
docker build --platform linux/amd64 -t registry.example/orbit:dev .
docker image inspect registry.example/orbit:dev --format '{{.Id}}'
```

生产发布应把标签绑定到不可变提交和镜像摘要，并在目标架构重新构建或执行等价的交叉构建核验。构建时可注入版本身份：

```sh
docker build --platform linux/amd64 \
  --build-arg VERSION=1.0.0 \
  --build-arg REVISION="$(git rev-parse HEAD)" \
  --build-arg BUILD_TIME="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -t registry.example/orbit:1.0.0 .
```

镜像同时写入 OCI `org.opencontainers.image.version`、`org.opencontainers.image.revision` 和 `org.opencontainers.image.created` 标签；可以先核对标签，再在节点启动后通过 `GET /version` 核对进程实际使用的值。`registry.example` 只是占位符，不是平台依赖。

构建完成后先保存发布物身份清单：

```sh
docker run --rm --entrypoint /usr/local/bin/orbit-admin \
  registry.example/orbit:1.0.0 release manifest > orbit-release-manifest.json
```

清单把当前构建身份、协议版本和内置迁移校验和固定下来；部署前再用 `orbit-admin verify` 对目标数据库逐项核对。两者不一致时停止发布，不通过人工修改清单来“对齐”。

## 2. 迁移、核验和启动

迁移与服务使用同一镜像但分开执行；迁移账户和运行账户由数据库权限策略隔离。以下命令只展示容器契约，凭据必须来自秘密管理：

```sh
export ORBIT_MYSQL_DSN='user:password@tcp(db.internal:3306)/orbit'

docker run --rm \
  --env ORBIT_MYSQL_DSN \
  --entrypoint /usr/local/bin/orbit-migrate \
  registry.example/orbit:dev up

docker run --rm \
  --env ORBIT_MYSQL_DSN \
  --entrypoint /usr/local/bin/orbit-admin \
  registry.example/orbit:dev verify

# 发布候选还应带上同一镜像生成的身份清单；不一致时停止发布。
docker run --rm \
  --env ORBIT_MYSQL_DSN \
  --entrypoint /usr/local/bin/orbit-admin \
  -v "$PWD/orbit-release-manifest.json:/run/orbit-release-manifest.json:ro" \
  registry.example/orbit:1.0.0 verify --manifest /run/orbit-release-manifest.json

docker run --rm \
  --env ORBIT_MYSQL_DSN \
  --env ORBIT_HTTP_ADDR=0.0.0.0:8080 \
  --env ORBIT_CONSOLE_QUEUE_ID=queue_xxx \
  --env ORBIT_RUNTIME_BATCH_LIMIT=100 \
  --env ORBIT_WORKFLOW_TICK_INTERVAL=1s \
  --env ORBIT_SCHEDULE_TICK_INTERVAL=1s \
  --env ORBIT_RECOVERY_TICK_INTERVAL=2s \
  --env ORBIT_SHUTDOWN_TIMEOUT=10s \
  --env ORBIT_WORKER_CONNECTION_LIMIT=128 \
  --env ORBIT_EVENT_CONNECTION_LIMIT=128 \
  --env ORBIT_DISPATCH_WORKERS=4 \
  --env ORBIT_DISPATCH_CAPACITY=128 \
  --env ORBIT_METRICS_ADDR=127.0.0.1:9090 \
  --publish 8080:8080 \
  registry.example/orbit:dev
```

`ORBIT_CONSOLE_QUEUE_ID` 是控制台的可选默认队列范围，只用于打开 `/console/` 时预填队列 ID，不是认证凭据。服务端仍要求业务请求携带有权限的 Bearer Token；多队列部署可以省略此变量，改为在浏览器选择凭据 JSON，由其中的 `queue_id` 自动填充。

生产编排应先完成迁移和 `verify`，再启动新节点。服务收到 `SIGTERM` 后停止接收新连接并在有限窗口内关闭 HTTP、WebSocket 和后台循环；编排器的终止宽限期必须覆盖该窗口。启动后才能把节点加入流量池。

## 3. 探针和监听边界

负载均衡或编排器使用：

```text
GET /health/live   进程存活
GET /health/ready  MySQL、迁移账本及零外键检查
GET /version       版本、提交和协议身份
```

`ready` 返回 `503` 时应摘除节点并保留原幂等键；不能把数据库连接失败解释为业务失败。metrics 监听由 `ORBIT_METRICS_ADDR` 单独启用，默认关闭，不应通过公共业务入口暴露。

镜像内没有 shell 和调试工具，故障定位依赖结构化日志、健康响应、受保护指标和 `orbit-admin observe snapshot`。不要在容器中执行迁移回滚、删除历史事件或修改审计数据。

## 4. 发布验收

镜像构建通过只证明发布物可复现，不等于生产高可用。发布候选仍需按[交付核对清单](release-checklist.md)完成真实 MySQL 回归、滚动替换、复制切换、容量、备份恢复和 RPO/RTO 验收。业务 Worker 继续独立部署，通过 HTTP/WebSocket SDK 接入。