本地 Docker Compose 联调环境
一套长期保留数据的 Orbit + MySQL 测试环境。项目名固定为 orbit-test，本机端口 18080；复用基础 Compose，本目录补充镜像构建、跨服务网络和持久归档卷。
启动
此部署工具随 main 分支交付；使用当前 main 代码，SDK 仍可固定 v0.1.1。需要 Docker Desktop / Docker Compose、Python 3；首次构建镜像需要访问构建依赖。从 Orbit 仓库根目录执行：
./scripts/orbit-local.py up
脚本创建随机数据库密码和管理员密码，构建镜像，依次完成 MySQL 健康检查、前向迁移、运行账号权限收紧、结构核验、管理员/测试身份初始化及服务启动。成功后还检查 readiness 和实际 SDK 队列权限。
启动状态：
./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，参见消费手册 |
| 就绪检查 | /health/ready |
| 管理员 | admin |
| 管理员密码 | 本机 .local/compose-test/admin.password |
浏览器直接账号密码登录，自动使用同源地址，不需要上传凭据 JSON。MySQL 仅在环境内部网络开放，业务服务通过 Orbit API 接入。
为其他应用分配独立配置
登录后打开侧栏「应用接入」，新建应用并选择能力，成功后复制/下载该应用的 .env。详情可以随时查看队列、权限和有效期。页面平滑换证默认保留旧 Token 7 天，过渡期内新旧 Token 均按各自有效期核验，原任务和订阅保持不变；全部服务切换并收尾后才可提前结束过渡。完整 Token 仅在生成时显示，未保存时可点「Token 在哪里查看？」；过渡期不能再次换证，点击「查看原因」可打开说明。
host.env / docker.env 是初始 local-testing 应用的联调身份；独立应用应使用页面分配的自己的配置。应用接入管理只授权 admin，无需创建多角色。详细操作和恢复手册。
本机业务服务
初始化生成 .local/compose-test/host.env，包含：
ORBIT_URL=http://127.0.0.1:18080
ORBIT_TOKEN=自动生成的真实令牌
ORBIT_NAMESPACE_ID=自动生成的命名空间ID
ORBIT_QUEUE_ID=自动生成的队列ID
在仓库根目录加载，再启动自己的服务：
set -a
. ./.local/compose-test/host.env
set +a
# 在当前环境中启动你的业务进程
这些变量由业务配置代码读取，再传给 SDK；SDK 本身不自动加载 env 文件：
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、HTTP 接入例子。业务处理器由接入服务注册运行；平台不会自动执行业务代码。
其他 Docker Compose 服务
在业务 Compose 中接入共享网络，并引用本机生成的 docker.env。将下方路径换为本机 Orbit 仓库的绝对路径；这份文件含真实令牌，不提交到业务 Git。
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 时，从仓库根目录执行：
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 与断线重报。刷新控制台即可查看真实数据。短示例每次产生新测试记录，不是长期业务消费者。
日常命令与持久化
./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 读取，脚本隔离其他项目的同名环境变量。可查看原始配置：基础文件 + 本地覆盖。脚本不提供删卷命令；需手工管理时务必固定 Compose 项目 orbit-test 和同一份配置。
凭据和权限
新建 SDK 凭据默认长期有效（省略 expires_at）；旧环境保留原策略，可在应用接入页「调整有效期」且不改变 Token。启动输出读取数据库当前有效期。凭据拥有此测试命名空间的任务、Worker、调度、订阅、流程及恢复权限；这是联调身份，正式环境按角色收窄。凭据到期/撤销后不会自动重新初始化或重置历史，按轮换手册处理。
管理员密码、数据库密码、SDK Token 均保存在 .local/compose-test 下的私密文件；目录权限 0700、文件权限 0600，Git 和 Docker 构建上下文都排除这些文件。需要其他服务读取时分发 host.env / docker.env，不要给业务服务数据库管理员配置。