OpenRath Agent Server生产部署完全指南：从Docker到Kubernetes

OpenRath 是一个 PyTorch 风格的开源多智能体（multi-agent）、多会话（multi-session）Agent 框架，v2.0.0 起它从可组合的 Python 框架升级为面向生产的持久化执行运行时：Python 定义编译为不可变执行计划，Agent Server 在 PostgreSQL、Redis、S3 兼容存储之上提供 HTTP + SSE 服务。本文将从 Docker Compose 单机部署讲到 Kubernetes 高可用集群部署，手把手带你完成 OpenRath Agent Server 生产部署，覆盖数据库迁移、令牌授权、健康检查与故障处置全流程。

看懂部署架构：OpenRath 生产栈的 5 个角色

部署前先看这张生产架构图，它把整个部署拆成三层：🏗️

• 定义与编译层：@step / @router 标注的 Workflow 编译为不可变执行计划（Execution Plan）；
• 持久执行层：Agent Server 暴露 HTTP + SSE 接口，Run → Event → Checkpoint 逐级落盘，配合 Effect Ledger（幂等副作用台账）与 Interrupt（人工审批中断）；
• 生产数据层：PostgreSQL 是唯一事实来源，Redis 仅做可选的信号加速，S3 兼容对象存储保存工件。

落到部署物上，就是 5 个容器角色（定义在 deploy/compose/compose.yaml）：

角色	入口命令	职责
migrate	openrath-migrate	一次性执行 PostgreSQL 模式迁移
api	openrath-server	提供 HTTP API 与健康检查，监听 8000 端口
worker	openrath-worker	以租约 + 围栏机制执行 Run，防止僵尸进程写入
postgres	PostgreSQL 17	Run / Event / Checkpoint 的持久化存储
redis / minio	（可选 profile）	信号加速 / 工件存储

所有角色复用同一个镜像，由 docker/Dockerfile 多阶段构建：基于 python:3.12-slim、非 root 用户（UID 10001）运行，运行时文件系统只读，安全加固开箱即用。

Docker Compose 三步快速部署

第 1 步：克隆代码并构建镜像

git clone https://gitcode.com/gh_mirrors/op/OpenRath
cd OpenRath
docker compose -f deploy/compose/compose.yaml build

Compose 文件会自动以仓库根目录为构建上下文调用 docker/Dockerfile，产物镜像为 openrath:2.0.0。

第 2 步：配置 4 个必填环境变量

export POSTGRES_PASSWORD='<你的数据库密码>'
export OPENRATH_TOKEN='<一个足够长的随机令牌>'
export OPENRATH_TENANT_ID='default'        # 可选，默认 default

令牌不能写 * 通配符，参考应用要求显式的动作授权列表（Compose 中已给出默认的 OPENRATH_GRANTS）。

第 3 步：启动服务并验证健康检查

# 基础部署（postgres + migrate + api + worker）
docker compose -f deploy/compose/compose.yaml up -d

# 追加启用 Redis（signals）与 MinIO（artifacts）
docker compose -f deploy/compose/compose.yaml --profile signals --profile artifacts up -d

# 验证就绪探针
curl -fsS http://localhost:8000/health/ready

启动顺序由 Compose 自动编排：先等 PostgreSQL 健康 → 跑完 migrate → 再拉起 api 与 worker，api 自带 /health/ready 健康检查（10 秒间隔、6 次重试）。

OpenRath 核心环境变量速查

变量	默认值	说明
OPENRATH_POSTGRES_DSN	—（必填）	PostgreSQL 连接串，运行时账号只需 DML 权限
OPENRATH_TOKEN	—（必填）	Agent Server 静态令牌，携带显式 action 授权
OPENRATH_GRANTS	参考应用内置	逗号分隔的授权清单，拒绝 * 通配
OPENRATH_TENANT_ID	default	租户标识，对象访问按租户/项目隔离
OPENRATH_APP	—	ASGI 应用引用，形如 reference_app:app
OPENRATH_EMBEDDED_WORKER	true	生产部署建议 false，用独立 worker 横向扩缩
OPENRATH_DB_SCHEMA	openrath	PostgreSQL schema 名称
OPENRATH_PORT	8000	HTTP 监听端口

完整端点契约可查阅自动生成的 deploy/docs/openapi-v2.json，包括 /v1/sessions、/v1/runs、/v1/runs/{run_id}/stream（SSE 流）等。

用 Kubernetes 扩展到集群

官方生产清单 deploy/kubernetes/openrath.yaml 是一份"即取即用"的高可用模板，内含 9 类资源：

1. migrate Job：部署前一次性执行 openrath-migrate，独立 ServiceAccount，失败重试 3 次；
2. api Deployment：2 副本，三级探针（startupProbe → livenessProbe / readinessProbe 分别打 /health/live 与 /health/ready），HPA 按 70% CPU 在 2~10 副本间自动伸缩，缩容带 300 秒稳定窗口防抖；
3. worker Deployment：2 副本执行 Run，readiness 探针直接跑 openrath-migrate --check 校验 schema，preStop 挂起 5 秒让在途租约优雅过期；
4. Service：80 → 8000 端口转发；
5. PodDisruptionBudget：minAvailable: 1，节点维护时保证至少一个副本在线；
6. NetworkPolicy：默认拒绝出入流量，出站仅放行 DNS 与标注了 openrath.io/data-plane=allowed 数据面的 5432/6379/9000/443 端口；
7. 两个只挂载了必要权限的 ServiceAccount（automountServiceAccountToken: false）。

部署步骤：

# 1. 基于示例创建两个 Secret（切勿提交真实值）
#    openrath-runtime：OPENRATH_POSTGRES_DSN + OPENRATH_TOKEN
kubectl apply -f deploy/kubernetes/secret.example.yaml

# 2. 应用完整清单（migrate Job 会先于流量运行）
kubectl apply -f deploy/kubernetes/openrath.yaml

# 3. 观察滚动发布与健康状态
kubectl rollout status deployment/openrath
kubectl get pods -l app.kubernetes.io/name=openrath

两点硬性要求来自 deploy/docs/operations-v2.md：

• 镜像必须从审查 tag 替换为 image@sha256:... 摘要，不要部署可变的 latest；
• 数据面组件（PostgreSQL / Redis / S3 / HTTPS 出口网关）所在命名空间必须打上 openrath.io/data-plane=allowed 标签，否则出站策略会 fail closed。

数据库模式迁移：上线前最关键一步

PostgresRunStore 默认不自动迁移，模式变更必须作为独立操作执行（CLI 实现见 src/rath/server/cli.py）：

openrath-migrate            # 应用增量迁移
openrath-migrate --check    # 只校验不变更，可作为就绪探针

• 迁移 SQL 位于 src/rath/runtime/migrations/postgres/，v2.0.0 内的变更全部为追加式（additive）：先回滚应用 Pod，再在回滚窗口结束后保留新增列/表；
• 运行时身份（API、worker）不需要 DDL 权限，只需 DML 权限，迁移由 DDL 身份的 Job 独立完成；
• 若要从 v1 JSONL 会话迁移历史数据，使用 scripts/migrate_v1_to_v2.py：先 dry-run 生成清点报告，审核 invalid / partial 条目后再加 --apply 正式导入。注意 v1 会话只作为不可恢复的历史记录导入，不会变成可续跑的 v2 Run，完整流程见 deploy/docs/migration-v2.md。

安全要点：令牌授权与审计日志

• 最小授权：Agent Server 令牌携带显式 action 授权（如 run.create、interrupt.decide），认证通过≠有权限，所有 Run/Session/Interrupt 操作还会二次校验租户与项目范围，跨作用域对象一律返回"未找到"以隐藏存在性；
• 密钥管理：Secret 模板见 deploy/kubernetes/secret.example.yaml，生产环境应接入你的密钥管理器而非明文提交；
• 审计闭环：参考应用通过 StructuredAuditSink 将脱敏后的 JSONL 审计记录输出到 stdout，生产运维必须为其配置采集、留存、访问控制与投递告警；
• 授权模型与威胁建模细节见 deploy/docs/api-governance-v2.md 与 deploy/docs/threat-model-v2.md。

工具执行同样被隔离在类型化后端边界之后——local 与 OpenSandbox 后端在会话放置模型下可互换，这也是 worker 可以安全横向扩展的前提：

生产运维：健康检查与故障处置

两个健康端点是运维的抓手：

• GET /health/live：进程存活（liveness）；
• GET /health/ready：就绪探针，PostgreSQL 不可用时返回 503，自动停止接收新 Run。

官方 runbook（摘自 deploy/docs/operations-v2.md）覆盖五类典型故障：

故障	关键动作
PostgreSQL 不可用	停止接收新 Run，恢复连接后校验 schema 与租约，绝不能用 Redis 顶替状态
Redis 不可用	Run 依然持久，保留轮询降级，仅告警信号延迟
Worker 终止/卡死	确认租约过期，触发孤儿调和，校验 fencing token 递增，陈旧 worker 的下一次提交必须失败
队列积压	先确认 PostgreSQL 连接容量再扩副本，对高负载租户限流
工件存储不可用	保持 Run/Checkpoint 持久，恢复后校验 SHA-256 再续跑

另外建议每季度做一次备份恢复演练：在隔离环境恢复 PostgreSQL 与工件，跑 openrath-migrate --check，并验证非幂等模糊调用仍停留在 NEEDS_REVIEW 状态。

常见部署踩坑清单 ⚠️

1. 不要部署 latest：以 tag 引用的清单只是模板，发布证据必须是不可变的镜像摘要；
2. /v1 HTTP 契约仍是 Beta：稳定错误码与字段需兼容性评审后才会提升，客户端要做好兼容（见 deploy/docs/known-limitations-v2.md）；
3. 同步步骤不能声明抢占式超时：Python 线程无法被安全抢占，需要 deadline 时改用 async step 或隔离执行器；
4. Redis 不是状态库：它只加速唤醒/取消/流式延迟，丢失后回落到 PostgreSQL 轮询；
5. 静态令牌只是示例：reference_app 是部署样例，生产需接入自己的身份提供方、TLS 入口与审计采集器。

总结

OpenRath Agent Server 的生产部署路径已经非常清晰：

阶段	关键产物 / 命令
单机验证	deploy/compose/compose.yaml + 4 个必填环境变量
数据库就绪	openrath-migrate / openrath-migrate --check
集群扩展	deploy/kubernetes/openrath.yaml（HPA + PDB + 网络策略）
安全与运维	显式授权令牌 + 审计采集 + 故障 runbook

从 Compose 到 Kubernetes，只需替换清单与镜像来源，同一份 Docker 镜像即可平滑升级。掌握本文的 5 个角色、3 层存储与故障处置清单，你就能把 OpenRath 多智能体运行时稳稳地跑在生产环境里。🚀