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。

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

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

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

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

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

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

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

2. 迁移、核验和启动

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

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:v0.1.1 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，不是认证凭据。控制台登录使用数据库中的管理员账号，会话建立后服务端按账号绑定的业务凭据读取统计和任务；浏览器不需要填写 API 地址或上传凭据 JSON。多队列部署可以省略此变量，管理员在控制台内选择有权限的队列范围。首次管理员通过 orbit-admin bootstrap 创建，后续账号使用 orbit-admin console-user create 创建。

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

3. 探针和监听边界

负载均衡或编排器使用：

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

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

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

4. 发布验收

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

5.2 KiB Raw Blame History Unescape Escape

Orbit 容器发布说明

1. 构建

2. 迁移、核验和启动

3. 探针和监听边界

4. 发布验收

5.2 KiB

Raw Blame History