149 lines
8.5 KiB
Markdown
149 lines
8.5 KiB
Markdown
# 本地 Docker Compose 联调环境
|
||
|
||
一套长期保留数据的 Orbit + MySQL 测试环境。项目名固定为 `orbit-test`，本机端口 `18080`；复用[基础 Compose](../docker-compose.yml)，本目录补充镜像构建、跨服务网络和持久归档卷。
|
||
|
||
## 启动
|
||
|
||
此部署工具随 `main` 分支交付；使用当前 main 代码，新接入建议固定 SDK v0.1.2；既有 SDK v0.1.1 可继续使用原接口。需要 Docker Desktop / Docker Compose、Python 3；首次构建镜像需要访问构建依赖。从 Orbit 仓库根目录执行：
|
||
|
||
```sh
|
||
./scripts/orbit-local.py up
|
||
```
|
||
|
||
脚本创建随机数据库密码和管理员密码，构建镜像，依次完成 MySQL 健康检查、前向迁移、运行账号权限收紧、结构核验、管理员/测试身份初始化及服务启动。成功后还检查 readiness 和实际 SDK 队列权限。
|
||
|
||
启动状态：
|
||
|
||
```sh
|
||
./scripts/orbit-local.py status
|
||
```
|
||
|
||
`mysql` 和 `orbit` 长期运行；`migrate`、`grant`、`verify`、`archive-init` 显示 `Exited (0)` 是一次性初始化成功。
|
||
|
||
## 控制台与接入地址
|
||
|
||
| 用途 | 地址/配置 |
|
||
| --- | --- |
|
||
| 本机控制台 | <http://127.0.0.1:18080/console/> |
|
||
| 本机 API / SDK baseURL | `http://127.0.0.1:18080` |
|
||
| Docker 网络 | `orbit-test-services` |
|
||
| 同网络容器 API / SDK baseURL | `http://orbit-test:8080` |
|
||
| Worker WebSocket | 上述主机的 `/v1/worker/connect`；SDK 自动处理升级与鉴权 |
|
||
| 结果通知 | 使用 SDK 持久订阅 + EventConsumer，参见[消费手册](../../docs/sdk/event-consumer.md) |
|
||
| 就绪检查 | `/health/ready` |
|
||
| 管理员 | `admin` |
|
||
| 管理员密码 | 本机 `.local/compose-test/admin.password` |
|
||
|
||
浏览器直接账号密码登录，自动使用同源地址，不需要上传凭据 JSON。MySQL 仅在环境内部网络开放，业务服务通过 Orbit API 接入。
|
||
|
||
## 为其他应用分配独立配置
|
||
|
||
登录后打开侧栏「应用接入」，新建应用并选择能力，成功后复制/下载该应用的 `.env`。详情可以随时查看队列、权限和有效期。页面平滑换证默认保留旧 Token 7 天，过渡期内新旧 Token 均按各自有效期核验，原任务和订阅保持不变；全部服务切换并收尾后才可提前结束过渡。管理员可以随时「查看接入信息」「复制接入配置」或下载 orbit.env，过渡期也可以获取当前新 Token。旧凭据仅有摘要时先导入已保存的当前 Token，保留现有有效期和业务身份。
|
||
|
||
`host.env` / `docker.env` 是初始 local-testing 应用的联调身份；独立应用应使用页面分配的自己的配置。应用接入管理只授权 `admin`，无需创建多角色。[详细操作和恢复手册](../../docs/api/console-applications.md)。
|
||
|
||
## 本机业务服务
|
||
|
||
初始化生成 `.local/compose-test/host.env`，包含：
|
||
|
||
```text
|
||
ORBIT_URL=http://127.0.0.1:18080
|
||
ORBIT_TOKEN=自动生成的真实令牌
|
||
ORBIT_NAMESPACE_ID=自动生成的命名空间ID
|
||
ORBIT_QUEUE_ID=自动生成的队列ID
|
||
```
|
||
|
||
在仓库根目录加载，再启动自己的服务：
|
||
|
||
```sh
|
||
set -a
|
||
. ./.local/compose-test/host.env
|
||
set +a
|
||
# 在当前环境中启动你的业务进程
|
||
```
|
||
|
||
这些变量由业务配置代码读取，再传给 SDK；SDK 本身不自动加载 env 文件：
|
||
|
||
```go
|
||
client, err := orbit.NewClient(os.Getenv("ORBIT_URL"), orbit.Options{
|
||
Token: os.Getenv("ORBIT_TOKEN"),
|
||
})
|
||
if err != nil { return err }
|
||
queueID := os.Getenv("ORBIT_QUEUE_ID")
|
||
```
|
||
|
||
SDK 安装、任务处理器和完整服务见[根 README](../../README.md#sdk-怎么调用)、[HTTP 接入例子](../../examples/http-service/README.md)。业务处理器由接入服务注册运行；平台不会自动执行业务代码。
|
||
|
||
## 其他 Docker Compose 服务
|
||
|
||
在业务 Compose 中接入共享网络，并引用本机生成的 `docker.env`。将下方路径换为本机 Orbit 仓库的绝对路径；这份文件含真实令牌，不提交到业务 Git。
|
||
|
||
```yaml
|
||
services:
|
||
app:
|
||
# 这里保留业务服务自己的 image/build、ports 等配置
|
||
env_file:
|
||
- /absolute/path/to/orbit/.local/compose-test/docker.env
|
||
networks:
|
||
- default
|
||
- orbit-test
|
||
|
||
networks:
|
||
orbit-test:
|
||
external: true
|
||
name: orbit-test-services
|
||
```
|
||
|
||
业务服务读取到的 `ORBIT_URL` 为 `http://orbit-test:8080`，HTTP 和 WebSocket 都通过共享网络访问；Docker 内不要把 `127.0.0.1:18080` 当成宿主机地址。先启动 Orbit 环境，再启动业务 Compose。
|
||
|
||
如果仅临时联调一个已运行容器，可以执行 `docker network connect orbit-test-services <业务容器名>`，并在该业务服务配置中设置上述 URL 和凭据；容器重建后应采用 Compose 声明网络。
|
||
|
||
## 运行示例与看数据
|
||
|
||
宿主机有 Go 1.27.1 时，从仓库根目录执行：
|
||
|
||
```sh
|
||
export ORBIT_URL=http://127.0.0.1:18080
|
||
export ORBIT_CREDENTIALS_FILE="$PWD/.local/compose-test/sdk.credentials.json"
|
||
cd examples
|
||
go run ./worker
|
||
go run ./schedules
|
||
go run ./workflow
|
||
go run ./event-protocol
|
||
```
|
||
|
||
Worker 返回三条 `SUCCEEDED`；计划示例实际执行后暂停；流程示例完成并行、信号和审计核对；事件示例验证通知、ACK 与断线重报。刷新控制台即可查看真实数据。短示例每次产生新测试记录，不是长期业务消费者。
|
||
|
||
## 日常命令与持久化
|
||
|
||
```sh
|
||
./scripts/orbit-local.py logs # 默认显示 Orbit 最近 100 行
|
||
./scripts/orbit-local.py logs mysql # 数据库日志
|
||
./scripts/orbit-local.py restart # 只重启 Orbit，等到 ready
|
||
./scripts/orbit-local.py stop # 停止本环境的 Orbit 和 MySQL
|
||
./scripts/orbit-local.py start # 启动已有容器，等到 ready
|
||
./scripts/orbit-local.py up # 初次部署/重建镜像与容器；复用原密码和身份
|
||
```
|
||
|
||
数据库卷为 `orbit-test_orbit-mysql`，归档卷为 `orbit-test_orbit-archives`，容器配置 `restart: unless-stopped`。停止、重启、重新构建都保留数据。私密配置目录 `.local/compose-test` 也要保留；仅留下卷而丢失密码文件不能当成全新安装。
|
||
|
||
归档卷预算 1 GiB，归档计划和保留策略通过控制台配置，默认不自动开启计划；目前导出保留源数据。不要为腾空间删除数据库卷。
|
||
|
||
默认使用 `10.253.240.0/24` 内部网络和 `10.253.241.0/24` 服务网络，避免占用已耗尽的 Docker 默认子网池。如与本机已有网络冲突，在私密 `compose.env` 中设置 `ORBIT_TEST_BACKEND_SUBNET`、`ORBIT_TEST_SERVICES_SUBNET` 后首次启动；已有网络需要先协调连接服务后再调整。
|
||
|
||
配置统一从 `.local/compose-test/compose.env` 读取，脚本隔离其他项目的同名环境变量。可查看原始配置：[基础文件](../docker-compose.yml) + [本地覆盖](compose.yml)。脚本不提供删卷命令；需手工管理时务必固定 Compose 项目 `orbit-test` 和同一份配置。
|
||
|
||
## 凭据和权限
|
||
|
||
新建 SDK 凭据默认长期有效（省略 `expires_at`）；旧环境保留原策略，可在应用接入页「调整有效期」且不改变 Token。启动输出读取数据库当前有效期。凭据拥有此测试命名空间的任务、Worker、调度、订阅、流程及恢复权限；这是联调身份，正式环境按角色收窄。凭据到期/撤销后不会自动重新初始化或重置历史，按[轮换手册](../../docs/api/authentication.md)处理。
|
||
|
||
管理员密码、数据库密码、SDK Token 均保存在 `.local/compose-test` 下的私密文件；目录权限 0700、文件权限 0600，Git 和 Docker 构建上下文都排除这些文件。需要其他服务读取时分发 `host.env` / `docker.env`，不要给业务服务数据库管理员配置。
|
||
|
||
### Token 保管密钥
|
||
|
||
`up` 自动生成 `.local/compose-test/credential-keys.json`（0600），重复部署复用它。初始化容器将文件放入 `orbit-keys` 卷，供 Orbit 的 65532 用户只读访问；bootstrap/凭据管理 CLI 使用同一源文件。已经启用后发现文件丢失会停止部署，要求恢复原文件，不能生成替代密钥。
|
||
|
||
备份数据库时单独备份该文件，不提交 Git；不要删除 `orbit-keys` 卷。密钥环、生产多节点部署、旧凭据导入和主密钥变更见[应用接入接口文档](../../docs/api/console-applications.md#8-部署-token-保管)。本地升级会保留原管理员和所有应用身份，历史 Token 需要经管理员导入补齐。
|
||
|
||
资源退役入口及结清规则见[通用资源退役](../../docs/api/resource-retirement.md)。多队列时先明确选择目标，浏览器按命名空间记忆选择；退役队列不再可导出为新接入配置，历史查询仍开放。
|