Orbit Compose 部署基线

本文给出单节点部署的可重复入口，适合开发、验收和小规模生产前置环境。它把 MySQL、迁移、schema 核验和 Orbit 服务串成一条有明确失败边界的启动链路；生产多节点、数据库高可用、备份恢复和容量门禁仍按生产验收执行。

前置条件：Docker Engine、Docker Compose v2.20 或更高版本；如果使用仓库里的 Nginx 示例，需要 Nginx 1.25.1 或更高版本；正式环境还应具备镜像仓库、Secret 管理器和 HTTPS 反向代理。

1. 启动契约

deploy/docker-compose.yml 使用同一个 Orbit 镜像启动 Orbit 相关服务，并使用一个短生命周期的 MySQL 客户端服务收紧运行账号权限：

mysql 先通过 MySQL 8.4 健康检查。
migrate 使用迁移账号执行 orbit-migrate up。
grant 撤销 MySQL 初始化时给运行账号的全库权限，只保留 Orbit 运行所需的 SELECT、INSERT、UPDATE、DELETE。
verify 使用收紧后的运行账号执行 orbit-admin verify。
orbit 只有在迁移、权限收紧和核验都成功后才启动，运行账号不承担迁移职责。

迁移或核验失败时，Compose 的 service_completed_successfully 依赖会阻止 Orbit 进入流量。修复数据库或发布物后，用同一项目重新执行 docker compose up -d；不要通过删除迁移记录或手工改表来绕过核验。

Compose 文件要求显式提供数据库密码，仓库没有默认密码，也不读取隐式凭据。密码应来自部署平台的 Secret 注入，不应提交到 Git、镜像或日志。

2. 首次启动

先构建不可变镜像。正式发布时应把 ORBIT_IMAGE 换成带版本和摘要的镜像地址：

docker build \
  --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 orbit:1.0.0 .

在当前 shell 或 Secret 管理器中注入配置。以下值仅是变量示例，不是生产密码：

export ORBIT_IMAGE=orbit:1.0.0
export ORBIT_DB_NAME=orbit
export ORBIT_DB_USER=orbit_runtime
export ORBIT_DB_PASSWORD='从秘密管理器读取'
export ORBIT_DB_ROOT_PASSWORD='从秘密管理器读取'
export ORBIT_HTTP_BIND=127.0.0.1
export ORBIT_HTTP_PORT=8080

ORBIT_DB_NAME 和 ORBIT_DB_USER 仅使用字母、数字和下划线；权限收紧服务会拒绝其他字符。数据库密码由 Secret 管理器注入，建议使用字母、数字和短横线组成的随机值，避免 DSN 转义差异。

首次启动先只拉起 MySQL、迁移、权限收紧和核验：

docker compose -f deploy/docker-compose.yml up -d mysql verify
docker compose -f deploy/docker-compose.yml ps
docker compose -f deploy/docker-compose.yml logs --no-log-prefix migrate grant verify

verify 成功后，使用同一镜像和数据库连接创建初始业务资源与控制台管理员。密码通过标准输入传入，不能写在命令行参数中：

credential_dir="$(mktemp -d)"
umask 077
printf '%s\n' "$ORBIT_CONSOLE_PASSWORD" | \
  docker compose -f deploy/docker-compose.yml run --rm -T --no-deps \
    --entrypoint /usr/local/bin/orbit-admin \
    -e ORBIT_MYSQL_DSN="root:${ORBIT_DB_ROOT_PASSWORD}@tcp(mysql:3306)/${ORBIT_DB_NAME:-orbit}?parseTime=true&multiStatements=true" \
    -v "$credential_dir:/run/orbit" migrate bootstrap \
      --application platform \
      --namespace default \
      --environment production \
      --queue default \
      --worker-access \
      --schedule-access \
      --console-username "$ORBIT_CONSOLE_USERNAME" \
      --console-display-name 'Orbit 管理员' \
      --console-password-stdin \
      --output /run/orbit/credentials.json

将 credentials.json 按 Secret 文件处理，仅用于保存业务接入凭据；控制台登录使用上面创建的用户名和密码。完成安全保存后再启动服务：

export ORBIT_CONSOLE_QUEUE_ID="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["queue_id"])' "$credential_dir/credentials.json")"
docker compose -f deploy/docker-compose.yml up -d orbit
curl --fail http://127.0.0.1:"${ORBIT_HTTP_PORT:-8080}"/health/ready

如果只需业务 SDK 接入，可以省略控制台管理员；如果要创建多个管理员，使用 orbit-admin console-user create，每个账号单独审计和轮换，不共享密码。

3. 访问和域名

Orbit Console 使用当前页面的同源地址调用服务端，浏览器不需要再填写 API URL，也不需要上传凭据 JSON 才能查看控制台。直接访问 http://主机:端口/console/，未登录会跳转到 /console/login。

接入域名时，参考 deploy/nginx/orbit.conf.example，将 HTTPS 反向代理转发到 Orbit 的 8080 端口，并保留 WebSocket Upgrade/Connection 头；浏览器访问的域名就是 Console 自动使用的 API 地址。ORBIT_HTTP_BIND 控制主机监听地址，ORBIT_HTTP_PORT 控制主机映射端口；两者都不是业务域名配置。生产建议保持 ORBIT_HTTP_BIND=127.0.0.1，只允许同机 Nginx 访问。TLS 证书、域名和安全头由反向代理或入口网关管理。

修改 Nginx 配置后先执行 nginx -t，再平滑加载配置；不要在未验证证书、HTTP 到 HTTPS 跳转和 WSS 升级前切换公网流量。Nginx 不应代理 Orbit 的独立 metrics 监听，metrics 只在内部采集网络开放。

4. 日常操作与失败处理

# 查看迁移、核验和服务状态
docker compose -f deploy/docker-compose.yml ps

# 读取结构化服务日志
docker compose -f deploy/docker-compose.yml logs --tail=200 orbit

# 发布新镜像：先完成迁移和核验，再启动新服务
docker compose -f deploy/docker-compose.yml up -d verify
docker compose -f deploy/docker-compose.yml up -d orbit

# 停止服务但保留数据库卷
docker compose -f deploy/docker-compose.yml down

Compose 没有为 scratch 镜像伪造容器内 HTTP healthcheck；编排器或入口网关应调用 /health/live、/health/ready 和 /version。ready 返回 503 时摘除节点，保留原幂等键并等待数据库恢复。只有明确的废弃环境才使用 docker compose down -v，生产数据卷不得随服务停止删除。

5. 当前边界

该文件是可重复的单节点启动基线，不代表自动数据库故障切换、跨故障域多副本、备份恢复或容量目标已经验收。生产上线还需要真实 MySQL 拓扑、滚动替换、凭据轮换、备份恢复、压测和 RPO/RTO 证据；对应门槛以交付核对清单为准。

6.6 KiB Raw Blame History Unescape Escape