108 lines
5.7 KiB
Markdown
108 lines
5.7 KiB
Markdown
# 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=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` 只是占位符，不是平台依赖。
|
||
|
||
构建完成后先保存发布物身份清单：
|
||
|
||
```sh
|
||
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. 迁移、核验和启动
|
||
|
||
迁移与服务使用同一镜像但分开执行；迁移账户和运行账户由数据库权限策略隔离。以下命令只展示容器契约，凭据必须来自秘密管理：
|
||
|
||
```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: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. 探针和监听边界
|
||
|
||
负载均衡或编排器使用：
|
||
|
||
```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 接入。
|
||
|
||
### 管理员 Token 保管文件
|
||
|
||
启用 `ORBIT_CONSOLE_APPLICATION_ADMIN` 的部署必须通过 `ORBIT_CREDENTIAL_KEY_FILE` 指定 JSON 密钥环。将文件以只读卷或编排器 secret 挂载，并赋予容器 UID 65532 读取权限；不要写入镜像。所有节点与管理 CLI 共用密钥环。字段、升级顺序、备份和主密钥轮替见[接入信息部署](api/console-applications.md#8-部署-token-保管)。本地 Compose 自动创建和复用该文件。
|