# 本地 Docker Compose 联调环境

一套长期保留数据的 Orbit + MySQL 测试环境。项目名固定为 `orbit-test`，本机端口 `18080`；复用[基础 Compose](../docker-compose.yml)，本目录补充镜像构建、跨服务网络和持久归档卷。

## 启动

此部署工具随 `main` 分支交付；使用当前 main 代码，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 会立即使旧 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`，不要给业务服务数据库管理员配置。