diff --git a/Makefile b/Makefile index f5a571f..12272e4 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ GO ?= go -.PHONY: fmt test vet build image integration console-e2e mysql-replication mysql-compatibility sdk-check protocol-check docs-check schedule-backlog release-manifest release-local-check +.PHONY: fmt test vet build image integration console-e2e compose-check mysql-replication mysql-compatibility sdk-check protocol-check docs-check schedule-backlog release-manifest release-local-check fmt: $(GO) fmt ./... cd sdk/go && $(GO) fmt ./... @@ -35,6 +35,12 @@ integration: console-e2e: ./scripts/test-console-e2e.sh +compose-check: + @test -n "$${ORBIT_DB_USER:-}" || (echo 'ORBIT_DB_USER is required' >&2; exit 1) + @test -n "$${ORBIT_DB_PASSWORD:-}" || (echo 'ORBIT_DB_PASSWORD is required' >&2; exit 1) + @test -n "$${ORBIT_DB_ROOT_PASSWORD:-}" || (echo 'ORBIT_DB_ROOT_PASSWORD is required' >&2; exit 1) + @docker compose -f deploy/docker-compose.yml config >/dev/null + mysql-replication: ./scripts/test-mysql-replication.sh diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml new file mode 100644 index 0000000..3fc23a5 --- /dev/null +++ b/deploy/docker-compose.yml @@ -0,0 +1,95 @@ +name: orbit + +services: + mysql: + image: mysql:8.4 + restart: unless-stopped + environment: + MYSQL_DATABASE: ${ORBIT_DB_NAME:-orbit} + MYSQL_USER: ${ORBIT_DB_USER:?ORBIT_DB_USER is required} + MYSQL_PASSWORD: ${ORBIT_DB_PASSWORD:?ORBIT_DB_PASSWORD is required} + MYSQL_ROOT_PASSWORD: ${ORBIT_DB_ROOT_PASSWORD:?ORBIT_DB_ROOT_PASSWORD is required} + volumes: + - orbit-mysql:/var/lib/mysql + healthcheck: + test: + - CMD-SHELL + - MYSQL_PWD="$${MYSQL_ROOT_PASSWORD}" mysqladmin ping -h 127.0.0.1 -uroot --silent + interval: 5s + timeout: 5s + retries: 30 + start_period: 20s + + migrate: + image: ${ORBIT_IMAGE:-orbit:dev} + restart: "no" + depends_on: + mysql: + condition: service_healthy + entrypoint: ["/usr/local/bin/orbit-migrate"] + command: ["up"] + environment: + ORBIT_MYSQL_DSN: "root:${ORBIT_DB_ROOT_PASSWORD}@tcp(mysql:3306)/${ORBIT_DB_NAME:-orbit}?parseTime=true&multiStatements=true" + + grant: + image: mysql:8.4 + restart: "no" + depends_on: + mysql: + condition: service_healthy + entrypoint: ["/bin/sh", "-ec"] + command: + - | + case "$${ORBIT_DB_NAME}" in *[!A-Za-z0-9_]*|'') echo 'ORBIT_DB_NAME must contain only letters, numbers and underscores' >&2; exit 2;; esac + case "$${ORBIT_DB_USER}" in *[!A-Za-z0-9_]*|'') echo 'ORBIT_DB_USER must contain only letters, numbers and underscores' >&2; exit 2;; esac + MYSQL_PWD="$${MYSQL_ROOT_PASSWORD}" mysql --protocol=tcp -h mysql -uroot \ + -e "REVOKE ALL PRIVILEGES, GRANT OPTION FROM '$${ORBIT_DB_USER}'@'%'; \ + GRANT SELECT, INSERT, UPDATE, DELETE ON \`$${ORBIT_DB_NAME}\`.* TO '$${ORBIT_DB_USER}'@'%'; \ + FLUSH PRIVILEGES;" + environment: + MYSQL_ROOT_PASSWORD: ${ORBIT_DB_ROOT_PASSWORD:?ORBIT_DB_ROOT_PASSWORD is required} + ORBIT_DB_NAME: ${ORBIT_DB_NAME:-orbit} + ORBIT_DB_USER: ${ORBIT_DB_USER:?ORBIT_DB_USER is required} + + verify: + image: ${ORBIT_IMAGE:-orbit:dev} + restart: "no" + depends_on: + migrate: + condition: service_completed_successfully + grant: + condition: service_completed_successfully + entrypoint: ["/usr/local/bin/orbit-admin"] + command: ["verify"] + environment: + ORBIT_MYSQL_DSN: "${ORBIT_DB_USER}:${ORBIT_DB_PASSWORD}@tcp(mysql:3306)/${ORBIT_DB_NAME:-orbit}?parseTime=true&multiStatements=true" + + orbit: + image: ${ORBIT_IMAGE:-orbit:dev} + restart: unless-stopped + init: true + depends_on: + verify: + condition: service_completed_successfully + environment: + ORBIT_HTTP_ADDR: 0.0.0.0:8080 + ORBIT_MYSQL_DSN: "${ORBIT_DB_USER}:${ORBIT_DB_PASSWORD}@tcp(mysql:3306)/${ORBIT_DB_NAME:-orbit}?parseTime=true&multiStatements=true" + ORBIT_DB_MAX_OPEN: ${ORBIT_DB_MAX_OPEN:-20} + ORBIT_DB_MAX_IDLE: ${ORBIT_DB_MAX_IDLE:-5} + ORBIT_WORKFLOW_TICK_INTERVAL: ${ORBIT_WORKFLOW_TICK_INTERVAL:-1s} + ORBIT_SCHEDULE_TICK_INTERVAL: ${ORBIT_SCHEDULE_TICK_INTERVAL:-1s} + ORBIT_RECOVERY_TICK_INTERVAL: ${ORBIT_RECOVERY_TICK_INTERVAL:-2s} + ORBIT_RUNTIME_BATCH_LIMIT: ${ORBIT_RUNTIME_BATCH_LIMIT:-100} + ORBIT_SHUTDOWN_TIMEOUT: ${ORBIT_SHUTDOWN_TIMEOUT:-10s} + ORBIT_WORKER_CONNECTION_LIMIT: ${ORBIT_WORKER_CONNECTION_LIMIT:-128} + ORBIT_EVENT_CONNECTION_LIMIT: ${ORBIT_EVENT_CONNECTION_LIMIT:-128} + ORBIT_DISPATCH_WORKERS: ${ORBIT_DISPATCH_WORKERS:-4} + ORBIT_DISPATCH_CAPACITY: ${ORBIT_DISPATCH_CAPACITY:-128} + ORBIT_CONSOLE_QUEUE_ID: ${ORBIT_CONSOLE_QUEUE_ID:-} + ORBIT_METRICS_ADDR: ${ORBIT_METRICS_ADDR:-} + ports: + - "${ORBIT_HTTP_PORT:-8080}:8080" + stop_grace_period: 30s + +volumes: + orbit-mysql: diff --git a/docs/08-development-plan.md b/docs/08-development-plan.md index b2bee09..d8313ee 100644 --- a/docs/08-development-plan.md +++ b/docs/08-development-plan.md @@ -1,6 +1,6 @@ # Orbit 持续开发与回归计划 -更新：2026-09-21。此计划对应持续开发目标，由开发过程同步维护。数据库已按用户要求采用无外键设计，迁移 000008 移除历史外键，关联一致性由服务端事务保证。 +更新：2026-09-22。此计划对应持续开发目标，由开发过程同步维护。数据库已按用户要求采用无外键设计，迁移 000008 移除历史外键，关联一致性由服务端事务保证。 ## 1. 最终交付目标 @@ -48,6 +48,8 @@ 新增 `make console-e2e` 作为首次部署闭环门禁：在一次性 MySQL 和 Docker Orbit 中从空库迁移、初始化控制台管理员，完成登录、受保护页面、WS Worker 成功执行、明确失败重试、定时任务、控制台任务读取和登出后的 401 校验，证据见[首次部署与控制台任务闭环](reports/phase-8-console-e2e.md)。该门禁证明功能链路可重复，不替代目标生产拓扑、容量和 RPO/RTO 验收。 +新增 `deploy/docker-compose.yml` 作为单节点可部署基线：MySQL 健康检查通过后依次执行迁移和 `orbit-admin verify`，核验成功才启动 Orbit；`make compose-check` 提供不泄露密码的静态配置门禁，首次管理员初始化和域名/同源访问说明见[Compose 部署基线](22-compose-deployment.md)，实际正常启动与失败阻断证据见[Compose 部署基线验证](reports/phase-9-compose-deployment.md)。该基线不替代生产数据库高可用、正式 Secret、容量、备份和 RPO/RTO 验收。 + ## 2. 持续推进方式 每个阶段按以下顺序推进： diff --git a/docs/21-container-deployment.md b/docs/21-container-deployment.md index d10bc5e..8bf110f 100644 --- a/docs/21-container-deployment.md +++ b/docs/21-container-deployment.md @@ -80,7 +80,7 @@ docker run --rm \ registry.example/orbit:dev ``` -`ORBIT_CONSOLE_QUEUE_ID` 是控制台的可选默认队列范围，只用于打开 `/console/` 时预填队列 ID，不是认证凭据。服务端仍要求业务请求携带有权限的 Bearer Token；多队列部署可以省略此变量，改为在浏览器选择凭据 JSON，由其中的 `queue_id` 自动填充。 +`ORBIT_CONSOLE_QUEUE_ID` 是控制台的可选默认队列范围，只用于打开 `/console/` 时预填队列 ID，不是认证凭据。控制台登录使用数据库中的管理员账号，会话建立后服务端按账号绑定的业务凭据读取统计和任务；浏览器不需要填写 API 地址或上传凭据 JSON。多队列部署可以省略此变量，管理员在控制台内选择有权限的队列范围。首次管理员通过 `orbit-admin bootstrap` 创建，后续账号使用 `orbit-admin console-user create` 创建。 生产编排应先完成迁移和 `verify`，再启动新节点。服务收到 `SIGTERM` 后停止接收新连接并在有限窗口内关闭 HTTP、WebSocket 和后台循环；编排器的终止宽限期必须覆盖该窗口。启动后才能把节点加入流量池。 diff --git a/docs/22-compose-deployment.md b/docs/22-compose-deployment.md new file mode 100644 index 0000000..945bf78 --- /dev/null +++ b/docs/22-compose-deployment.md @@ -0,0 +1,113 @@ +# Orbit Compose 部署基线 + +本文给出单节点部署的可重复入口，适合开发、验收和小规模生产前置环境。它把 MySQL、迁移、schema 核验和 Orbit 服务串成一条有明确失败边界的启动链路；生产多节点、数据库高可用、备份恢复和容量门禁仍按[生产验收](05-production-acceptance.md)执行。 + +前置条件：Docker Engine、Docker Compose v2.20 或更高版本；正式环境还应具备镜像仓库、Secret 管理器和 HTTPS 反向代理。 + +## 1. 启动契约 + +`deploy/docker-compose.yml` 使用同一个 Orbit 镜像启动 Orbit 相关服务，并使用一个短生命周期的 MySQL 客户端服务收紧运行账号权限： + +1. `mysql` 先通过 MySQL 8.4 健康检查。 +2. `migrate` 使用迁移账号执行 `orbit-migrate up`。 +3. `grant` 撤销 MySQL 初始化时给运行账号的全库权限，只保留 Orbit 运行所需的 `SELECT`、`INSERT`、`UPDATE`、`DELETE`。 +4. `verify` 使用收紧后的运行账号执行 `orbit-admin verify`。 +5. `orbit` 只有在迁移、权限收紧和核验都成功后才启动，运行账号不承担迁移职责。 + +迁移或核验失败时，Compose 的 `service_completed_successfully` 依赖会阻止 Orbit 进入流量。修复数据库或发布物后，用同一项目重新执行 `docker compose up -d`；不要通过删除迁移记录或手工改表来绕过核验。 + +Compose 文件要求显式提供数据库密码，仓库没有默认密码，也不读取隐式凭据。密码应来自部署平台的 Secret 注入，不应提交到 Git、镜像或日志。 + +## 2. 首次启动 + +先构建不可变镜像。正式发布时应把 `ORBIT_IMAGE` 换成带版本和摘要的镜像地址： + +```sh +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 管理器中注入配置。以下值仅是变量示例，不是生产密码： + +```sh +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_PORT=8080 +``` + +`ORBIT_DB_NAME` 和 `ORBIT_DB_USER` 仅使用字母、数字和下划线；权限收紧服务会拒绝其他字符。数据库密码由 Secret 管理器注入，建议使用字母、数字和短横线组成的随机值，避免 DSN 转义差异。 + +首次启动先只拉起 MySQL、迁移、权限收紧和核验： + +```sh +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` 成功后，使用同一镜像和数据库连接创建初始业务资源与控制台管理员。密码通过标准输入传入，不能写在命令行参数中： + +```sh +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 文件处理，仅用于保存业务接入凭据；控制台登录使用上面创建的用户名和密码。完成安全保存后再启动服务： + +```sh +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`。 + +接入域名时，将 HTTPS 反向代理转发到 Orbit 的 `8080` 端口，并保留 WebSocket Upgrade/Connection 头；浏览器访问的域名就是 Console 自动使用的 API 地址。`ORBIT_HTTP_PORT` 只控制主机映射端口，不是业务域名配置。TLS 证书、域名和安全头由反向代理或入口网关管理。 + +## 4. 日常操作与失败处理 + +```sh +# 查看迁移、核验和服务状态 +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 证据；对应门槛以[交付核对清单](release-checklist.md)为准。 diff --git a/docs/README.md b/docs/README.md index a820b09..493e4ae 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,8 +21,10 @@ | [P7 协议兼容矩阵](reports/phase-7-compatibility.md) | 当前协议门禁、历史提交双向任务 API 演练与正式标签矩阵边界 | | [P7 Console 真实链路回归](reports/phase-7-console-e2e.md) | 真实 MySQL、Worker、流程、结果订阅与控制台读取闭环 | | [首次部署与控制台任务闭环](reports/phase-8-console-e2e.md) | 从空库初始化管理员、Docker 启动、控制台登录、WS Worker、重试和定时任务 | +| [Compose 部署基线验证](reports/phase-9-compose-deployment.md) | MySQL、迁移、核验、Orbit 启动顺序及失败门禁 | | [20 运行与发布手册](20-operations-runbook.md) | 启动、发布、滚动停止、数据库恢复、备份和事故处理 | | [21 容器发布说明](21-container-deployment.md) | 最小镜像、迁移/核验/启动顺序、探针和发布边界 | +| [22 Compose 部署基线](22-compose-deployment.md) | MySQL、迁移、核验、Orbit 服务和首次管理员初始化的可重复启动链路 | | [09 可靠结果订阅](09-result-subscription-core.md) | 提交水位、冻结结果与可靠交付 | | [10 Weave决策与交付](10-workflow-engine-core.md) | 有限步骤决策和内部结果Inbox | | [11 Weave实例受理](11-workflow-admission.md) | 固定版本、初始图和首批任务事务 | diff --git a/docs/reports/phase-9-compose-deployment.md b/docs/reports/phase-9-compose-deployment.md new file mode 100644 index 0000000..de8379a --- /dev/null +++ b/docs/reports/phase-9-compose-deployment.md @@ -0,0 +1,57 @@ +# Compose 部署基线验证 + +验证日期：2026-09-22 +验证范围：MySQL 健康检查、迁移、运行账号权限收紧、schema 核验、Orbit 启动、就绪探针和核验失败门禁。 +验证环境：Docker Desktop、MySQL 8.4、当前 `orbit:dev` 镜像。 + +## 已通过 + +### 静态配置门禁 + +使用临时数据库用户名、密码和镜像标签执行： + +```sh +docker compose -f deploy/docker-compose.yml config +``` + +结果：Compose 配置成功展开，五个服务的依赖条件、健康检查、数据卷、端口和运行时 DSN 均可解析；密码没有写入仓库。 + +同时通过： + +```sh +git diff --check +make docs-check +``` + +### 正常启动链路 + +在一次性 MySQL 8.4 和临时数据库卷中执行 Compose 服务链。当前开发机已有大量 Docker 自定义网络，地址池不足，因此本次测试只在临时覆盖文件中把容器放到 Docker 默认 `bridge` 网络并添加链接；生产 Compose 文件仍使用标准项目隔离网络，服务依赖语义没有改变。 + +验证顺序和结果： + +1. `mysql` 通过 `mysqladmin ping` 健康检查。 +2. `migrate` 使用 root 迁移连接完成当前迁移。 +3. `grant` 撤销运行账号的额外数据库权限，仅保留运行所需的 DML 权限。 +4. `verify` 使用运行账号完成 `orbit-admin verify`。 +5. `orbit` 在前述一次性服务成功后启动。 +6. `GET /health/ready` 返回成功。 + +最后输出： + +```text +compose-e2e=passed readiness=ok grant=ok +``` + +### 失败门禁 + +第二次使用临时 MySQL，故意让 `verify` 使用错误的运行账号密码。迁移成功后，`verify` 以退出码 1 结束，Compose 报告： + +```text +service "verify" didn't complete successfully: exit 1 +``` + +Orbit 没有进入运行状态，证明 schema 核验失败不会把未核验节点拉入流量。 + +## 尚未由本报告关闭的事项 + +本报告只证明单节点 Compose 的启动顺序和失败边界，不代表生产高可用。数据库自动切换、跨故障域多节点、正式 Secret 注入、反向代理 TLS、备份恢复、容量余量和 RPO/RTO 仍按[生产验收总清单](../05-production-acceptance.md)逐项留证。首次管理员和控制台任务闭环的真实证据见[phase-8 控制台闭环](phase-8-console-e2e.md)。