跳转到内容
模式进程依赖适用场景
API + Worker 一体1 个 serverPostgreSQL,Redis 可选本地开发、PoC、单机部署
API + Controller + Sandbox 分离1 个 server --api-only + 1 个 controller + N 个 sandbox-hosted workerPostgreSQL + Redis生产环境、需要独立控制面与 sandbox 扩缩容
Legacy 单 Workspace1 个 server --workspace <path>PostgreSQL,Redis 可选旧脚本兼容与内部测试

tip 不确定选哪个?企业 / 平台部署先用「一体模式」跑通,个人本地使用优先选择 OAP daemon + oah tui。Legacy 单 Workspace 模式只保留给旧脚本。

部署时建议始终按下面这条关系理解:

  • workspace 是项目与能力边界
  • worker 是执行角色
  • sandbox 是 worker 的宿主环境

在 split 部署里,通常不是“一个 workspace 对应一个进程”,而是“一个 sandbox 内的 standalone worker 按容量承载一个或多个活跃 workspace”。


三个终端,最简路径:

Terminal window
# 终端 1 — 本地整套服务(PostgreSQL + Redis + MinIO + oah-api + oah-controller + oah-compose-scaler + oah-sandbox)
export OPENAI_API_KEY=sk-...
pnpm local:up
# 终端 3 — WebUI
pnpm dev:web
# 可选 — 终端 TUI
pnpm dev:cli -- --base-url http://127.0.0.1:8787 tui

pnpm local:up 默认使用 OAH_HOME(再 fallback 到 ~/.openagentharness),缺少配置时会从 template/deploy-root 初始化 config/server.docker.yaml、runtime 和默认模型文件。只有需要独立管理团队/部署资产根目录时,再设置 OAH_DEPLOY_ROOT 并复制模板。

WebUI 默认地址:http://localhost:5174

TUI 连接同一个本地 API:http://127.0.0.1:8787

info 首次运行前先执行 pnpm install 安装依赖。

info 本地 API token 是可选保护项,OAP daemon 和 Docker split stack 使用同一套规则:默认不要求 token;设置 OAH_LOCAL_API_TOKEN,或设置 OAH_LOCAL_API_AUTH=1 让启动器生成/复用 ${OAH_HOME:-$HOME/.openagentharness}/run/token 后,非 public API 请求需要 Authorization: Bearer <token>。示例:

Terminal window
export OAH_LOCAL_API_AUTH=1
pnpm local:up
TOKEN="$(cat "${OAH_HOME:-$HOME/.openagentharness}/run/token")"
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8787/api/v1/workspaces
pnpm dev:cli -- --base-url http://127.0.0.1:8787 --token "$TOKEN" tui

/healthz、/readyz、/metrics、/api/v1/system/profile 保持公开,方便健康检查和客户端识别服务形态。

info 本地 split stack 默认让 active workspace copy 落在 oah-sandbox,并通过对象存储 backing store flush 回 OSS/MinIO。oah-api 只负责 API 入口和路由,不再挂载持久 workspace volume。


适用于模拟生产或真实生产环境。需要 Redis。

Terminal window
# 终端 1 — 本地基础设施
docker compose -f docker-compose.local.yml up -d postgres redis minio
# 终端 2 — API(oah-api,不内嵌 Worker)
pnpm exec tsx --tsconfig ./apps/server/tsconfig.json ./apps/server/src/index.ts -- --config ./server.example.yaml --api-only
# 终端 3 — Controller(oah-controller)
pnpm exec tsx --tsconfig ./apps/controller/tsconfig.json ./apps/controller/src/index.ts -- --config ./server.example.yaml
# 终端 4 — Standalone worker(通常跑在 oah-sandbox,可启动多个实例)
pnpm exec tsx --tsconfig ./apps/server/tsconfig.json ./apps/server/src/worker.ts -- --config ./server.example.yaml
# 终端 5 — WebUI
pnpm dev:web
# 可选 — 终端 TUI
pnpm dev:cli -- --base-url http://127.0.0.1:8787 tui

oah-api 只负责 HTTP 请求与 owner 路由;oah-controller 负责控制面;standalone worker 通常运行在 oah-sandbox 或 E2B sandbox 内,消费 Redis 队列并执行 Run。

WebUI 和 TUI 都只通过 oah-api 访问系统能力;TUI 更适合在服务器或本地 shell 内快速切换 workspace/session、查看流式输出。

仓库现在提供了一套最小可运行的 K8S split deployment 骨架:

使用方式:

如果是在本地或轻量 Kubernetes 集群里先跑完整依赖栈,可以直接使用通用本地 K8S overlay:

Terminal window
scripts/deploy-local-kubernetes.sh apply
scripts/deploy-local-kubernetes.sh port-forward

这会应用 deploy/local-kubernetes 下的 Kustomize overlay,包含 PostgreSQL、Redis、MinIO、oah-api、oah-controller 和 oah-sandbox。它不依赖 OrbStack 专属能力;kind、minikube、OrbStack 等本地集群只要能访问这些镜像即可使用。

清理:

Terminal window
scripts/deploy-local-kubernetes.sh delete

如果你已经有外部 PostgreSQL / Redis / 对象存储,只想套用基础 split deployment,则使用基础 manifests:

Terminal window
kubectl apply -f ./deploy/kubernetes/namespace.yaml
kubectl apply -f ./deploy/kubernetes/storage-secret.example.yaml
kubectl apply -f ./deploy/kubernetes/configmap.example.yaml
kubectl apply -f ./deploy/kubernetes/controller-rbac.yaml
kubectl apply -f ./deploy/kubernetes/api-server.yaml
kubectl apply -f ./deploy/kubernetes/worker.yaml
kubectl apply -f ./deploy/kubernetes/controller.yaml

或者直接走 Helm chart:

Terminal window
helm upgrade --install oah ./deploy/charts/open-agent-harness \
--namespace open-agent-harness \
--create-namespace \
--set image.repository=ghcr.io/open-agent-harness/open-agent-harness \
--set image.tag=latest

如果不想从零拼 values,也可以直接从内置环境样例起步:

Terminal window
helm upgrade --install oah ./deploy/charts/open-agent-harness \
--namespace open-agent-harness \
--create-namespace \
-f ./deploy/charts/open-agent-harness/examples/staging.values.yaml

如果已经进入 production-like 演练阶段,建议直接叠这层 hardening overlay:

Terminal window
helm upgrade --install oah ./deploy/charts/open-agent-harness \
--namespace open-agent-harness \
--create-namespace \
-f ./deploy/charts/open-agent-harness/examples/prod.values.yaml \
-f ./deploy/charts/open-agent-harness/examples/prod-hardening.values.yaml

如果要把 K8S 相关材料按使用顺序看,建议走这条线:

  1. deploy.md
  2. deploy/charts/open-agent-harness/README.md
  3. prod-hardening.values.yaml
  4. k8s-compose-reuse-matrix.md
  5. k8s-rollout-checklist.md
  6. k8s-operations-runbook.md

如果要发布正式镜像,仓库现在也提供了一条最小 GHCR 发布链路:

Terminal window
git push origin master

说明:

  • .github/workflows/publish-image.yml 会在 master 和 v* tag 上构建生产 Dockerfile
  • 默认发布到 ghcr.io/<repo-owner>/open-agent-harness
  • 如需改成别的包名,可在 GitHub 仓库变量里设置 OAH_IMAGE_NAME
  • 如果要与仓库当前示例 manifests/chart 默认值保持一致,可把 OAH_IMAGE_NAME 设为 open-agent-harness/open-agent-harness

当前这套骨架已经包含:

  • oah-api、oah-sandbox、oah-controller 三个独立 Deployment
  • oah-api 不需要挂载 workspace volume;oah-sandbox 才承载 writable active workspace copy,推荐配合对象存储 backing store 做 idle / drain flush
  • controller 额外暴露一个 ClusterIP Service,提供 /healthz、/readyz、/snapshot、/metrics
  • controller 使用 Kubernetes Lease 做 leader election
  • controller 通过 Kubernetes workload /scale 子资源改写 oah-sandbox 副本数,并已支持通过 label_selector 自动发现目标 Deployment / StatefulSet
  • server.yaml 示例已把 sandbox.provider 设为 self_hosted,并通过 oah-sandbox-internal headless service 路由到 sandbox 内 worker
  • 默认 sandbox fleet 保留 warm_empty_count: 1 个空 sandbox;ownerless workspace 会先复用 CPU、内存和磁盘均低于阈值的已有 sandbox,任一资源超过阈值后才落到空 sandbox
  • K8S 默认不再使用小规模演示上限;sandbox.fleet.max_count 和 workers.standalone.max_replicas 设为 10000,实际扩容边界交给集群资源、quota、HPA/Cluster Autoscaler 和你自己的容量策略控制
  • controller-rbac.yaml 当前已包含 leases、deployments、deployments/scale、statefulsets 和 statefulsets/scale 所需权限,能够覆盖 leader election、label selector 发现和副本数改写
  • 默认已经允许在安全前提满足时自动缩容;真正的缩容护栏由 controller 对 standalone worker /healthz 的动态探测决定
  • standalone worker 收到退出信号后会先进入 drain,使 readiness 先摘除,再等待当前 run 自然结束
  • drain 开始时会优先 flush + evict 空闲 workspace 副本,并阻止新的 object-store materialization 启动
  • 三个 Deployment 现在都显式声明了 rollout 策略;oah-api / oah-sandbox 使用 maxUnavailable: 0,oah-sandbox 还额外保留更长的 terminationGracePeriodSeconds 用于 drain 收敛
  • controller Service 默认带 prometheus.io/* annotations,便于最小化接入 scrape;更完整的 ServiceMonitor/Prometheus Operator 对接仍建议在生产 overlays/Helm 中补充
  • 仓库额外提供 controller-servicemonitor.example.yaml 作为 Prometheus Operator 接入示例,默认不纳入 kustomization.yaml
  • 现在也提供一个可直接使用的 Prometheus Operator kustomization: deploy/kustomization.yaml 它会在基础 deploy/kubernetes 骨架之上额外包含 deploy/controller-servicemonitor.yaml 和 deploy/controller-prometheusrule.yaml,可直接通过 kubectl apply -k ./deploy 启用 controller 的 ServiceMonitor 与基础告警规则
  • 现在也提供了最小 Helm chart,可把 split deployment、RBAC、ConfigMap 和可选 ServiceMonitor 一起交给 Helm 管理
  • chart 现在还可选生成:
    • PrometheusRule
    • Grafana dashboard ConfigMap
    • controller / worker / api ingress NetworkPolicy
  • Helm chart 当前还已支持复用已有 ConfigMap、为 oah-sandbox 切换到现有 PVC、以及给三个组件分别配置 resources / securityContext / envFrom / scheduling
  • 生产环境应启用对象存储 backing store,并显式配置 worker.workspaceVolume、ephemeral-storage、worker.diskReadiness.threshold 和 worker.workspacePolicy.*;完整检查项见 docs/production-readiness.md
  • Helm chart 现在还支持 PodDisruptionBudget、topologySpreadConstraints、priorityClassName、NetworkPolicy,并可直接为 oah-api 生成 Ingress
  • chart 目录下现在还已附带 dev / staging / prod 三套 values 样例,便于按环境起步而不是手写所有参数
  • 现在也提供了生产 Dockerfile 与最小 GHCR 发布 workflow,K8S manifests/chart 不再只是假定“外部已有镜像”
  • GHCR workflow 现在还会产出 sbom/provenance,并通过 Cosign 做 keyless signing

当前建议额外遵循这几条 K8S 部署契约:

  • oah-controller 多副本时,必须开启 leader_election.type=kubernetes
  • oah-controller 的 scale_target.kubernetes.label_selector 必须只命中当前 release 的同类型 oah-sandbox workload
  • oah-sandbox 的 terminationGracePeriodSeconds 要大于 worker drain 超时
  • oah-sandbox 需要在 preStop 里先触发本地 drain,再等待短暂缓冲时间,让 /readyz 先摘除
  • controller 对 scale target 的观测应区分:
    • 请求已接受
    • rollout 进行中
    • rollout 已 ready
    • 平台调用失败

推荐关系:

  • worker.drain.timeoutMs < terminationGracePeriodSeconds * 1000
  • preStop 只负责“尽快进入 draining”,不要在 hook 里做长时间阻塞逻辑
  • 若 worker 需要在超时后恢复未完成 run,优先使用 requeue_running 之类的显式策略,而不是等 K8S 强杀
  • 若要收紧 Pod ingress 面,建议从 deploy/kubernetes/networkpolicy.example.yaml 或 chart 的 networkPolicy.enabled=true 起步;当前基线默认只收紧 ingress,不默认限制 egress
  • 若要进一步收紧出口白名单,建议从 deploy/charts/open-agent-harness/examples/strict-egress.values.yaml 或 deploy/kubernetes/networkpolicy.strict-egress.example.yaml 起步,再替换:
    • Kubernetes API CIDR
    • Redis / Postgres Pod labels
    • 对象存储 / 模型运行时的真实 CIDR 或 egress gateway 网段
  • 如果要按上线节奏收口,建议顺序是:
    • staging.values.yaml
    • prod.values.yaml
    • prod.values.yaml + prod-hardening.values.yaml
    • 最后按 docs/k8s-rollout-checklist.md 做 staging / production gate

该模式只作为旧脚本和内部测试的兼容入口。个人本地使用请优先选择 OAP daemon 与 oah tui。

Terminal window
pnpm exec tsx --tsconfig ./apps/server/tsconfig.json ./apps/server/src/index.ts -- \
--workspace /absolute/path/to/workspace \
--model-dir /absolute/path/to/models \
--default-model openai-default

可选参数:

参数说明
--tool-dir <path>公共 tool 目录
--skill-dir <path>公共 skill 目录
--host <addr>监听地址,默认 127.0.0.1
--port <num>监听端口,默认 8787

warning 单 Workspace 模式下,workspace 管理接口(POST /workspaces、DELETE /workspaces/:id 等)会被禁用。


服务启动后,用以下端点验证状态:

端点用途正常响应
GET /healthz进程存活检查{ "status": "ok" }
GET /readyz就绪检查(含依赖){ "status": "ready" },未就绪返回 503
Terminal window
curl http://127.0.0.1:8787/healthz
curl http://127.0.0.1:8787/readyz

额外确认项:

  • 服务日志中打印了当前运行模式(API + embedded worker / API only / standalone worker)
  • 发送消息后 Run 能从 queued 推进到执行
  • 分离部署时 Worker 日志中有队列消费记录

变量说明示例
DATABASE_URLPostgreSQL 连接串postgres://oah:oah@127.0.0.1:5432/open_agent_harness
REDIS_URLRedis 连接串redis://127.0.0.1:6379
OAH_WEB_PROXY_TARGET前端代理目标(后端地址不是默认时使用)http://127.0.0.1:8787
OAH_DOCKER_HOST_ALIAS容器内访问宿主机服务时使用的主机名host.docker.internal
OAH_DOCKER_BUILD_BASE_IMAGE本地 Compose 构建 Node builder 基础镜像node:24-alpine
OAH_DOCKER_RUNTIME_BASE_IMAGE本地 Compose runtime 基础镜像alpine:3.22
OAH_DOCKER_RUST_BASE_IMAGE本地 Compose native helper Rust builder 基础镜像rust:1.95-alpine

在 server.yaml 中通过 ${env.DATABASE_URL} 语法引用环境变量。

如果 OAH 本身运行在 Docker 容器里,而 HTTP MCP Server 跑在宿主机本地:

  • MCP 配置仍可写 http://127.0.0.1:PORT/... 或 http://localhost:PORT/...
  • OAH 会在容器内自动改写为宿主机可访问地址
  • 默认使用 host.docker.internal
  • 如有需要可通过 OAH_DOCKER_HOST_ALIAS 覆盖

本地 docker-compose.local.yml 已为 oah-api、oah-controller、oah-compose-scaler、oah-sandbox 注入 host.docker.internal:host-gateway,因此 Linux 环境下也能直接使用该别名。

pnpm local:up 会优先预拉 Alpine 系基础镜像,并把 Node builder、runtime、Rust native builder 三类 build arg 都传给 Compose。若需要手动覆盖,请同时设置 OAH_DOCKER_BUILD_BASE_IMAGE、OAH_DOCKER_RUNTIME_BASE_IMAGE、OAH_DOCKER_RUST_BASE_IMAGE;只覆盖前两个不会影响 native Rust build stage。

本地开发使用 docker-compose.local.yml 启动的容器时,默认连接串为:

storage:
postgres_url: postgres://oah:oah@127.0.0.1:5432/open_agent_harness
redis_url: redis://127.0.0.1:6379