Split Deployment Skeleton
Section titled “Split Deployment Skeleton”本文描述当前代码基线下的 split deployment 骨架,也就是把 oah-api 与 oah-sandbox 拆成独立进程/Pod 时,仓库内各入口的真实职责。
本文档中的正式控制面术语统一使用 Controller。当前主要保留的是少量 legacy env var / metric / chart values 兼容项,而不是新的主命名。
apps/serveroah-api入口- 可运行在
api_only或api_embedded_worker模式 - 在 split 部署里,建议使用
--api-only,作为最小化 API 面
apps/worker- standalone worker 入口,通常运行在
oah-sandbox内 - 复用
apps/server里的共享 runtime 装配逻辑 - 只暴露 internal-only HTTP surface 和健康探针
- standalone worker 入口,通常运行在
controlleroah-controller独立控制面入口- 当前负责读取 Redis queue / worker registry 并计算
desiredReplicas - 当前已可通过可插拔
scale target把目标副本数 reconcile 到 Kubernetes workload/scale - 当前已支持通过
label_selector自动发现要缩放的oah-sandboxDeployment / StatefulSet - 当前已可通过 Kubernetes Lease 完成 leader election,仅由 leader 实例执行 reconcile
- 当前已通过 worker
/healthz动态 gating 控制自动缩容 - 当前已暴露
/healthz、/readyz、/snapshot、/metricsobservability 面
仓库根目录当前提供了更清晰的 split-mode 脚本:
pnpm dev:server- 启动
oah-api - 默认走
api_only
- 启动
pnpm dev:worker- 启动 standalone worker,供
oah-sandbox使用
- 启动 standalone worker,供
pnpm start:server- 以构建产物启动
oah-api - 默认走
api_only
- 以构建产物启动
pnpm start:worker- 以构建产物启动 standalone worker
保留兼容入口:
apps/server/src/index.tsoah-api可执行入口
apps/server/src/worker.ts- standalone worker 可执行入口
apps/server/src/engine-entry.ts- 当前共享的
oah-api/ standalone worker 装配入口
- 当前共享的
Worker 约束
Section titled “Worker 约束”standalone worker 当前默认承担这些职责:
- 消费 Redis queued runs
- materialize object-storage workspace 到本地缓存目录
- 通过 workspace ownership lease 发布
ownerWorkerId - 当配置了
OAH_INTERNAL_BASE_URL时,发布ownerBaseUrl - 承接来自 API server 的 owner-worker 文件代理
当前 worker 不负责:
- worker 副本数决策
- leader election
- history mirror sync
worker Pod 侧至少需要保证这些目录可用:
paths.workspace_dir- managed live workspace 根目录
paths.runtime_state_dir- worker 运行时私有状态根目录
- 放置 sqlite shadow state、archives 和遗留 materialization 状态
当 workspace externalRef 指向对象存储时,还需要:
object_storage.*配置- 供 worker 本地缓存和 flush 使用的可写临时盘
推荐显式配置:
OAH_INTERNAL_BASE_URL- 用于发布 worker 可达的 internal base url
- API server 会据此把 workspace 文件请求 proxy 到 owner worker
当前 split skeleton 已经具备:
oah-api与 standalone worker 的独立 app 包边界- owner-worker 文件代理
- worker internal-only HTTP surface
controller的 Kubernetes leader election + workload/scalereconcilecontroller的独立 Service 与基础 metrics/health observability 面controller的 Prometheus OperatorServiceMonitor示例清单deploy/根目录下的 Prometheus Operator kustomization,可直接kubectl apply -k ./deploy启用ServiceMonitordeploy/kubernetes下的最小 Deployment / Service / RBAC 骨架deploy/charts/open-agent-harness下的最小 Helm chart,可统一管理 split deployment、RBAC、ConfigMap 与可选ServiceMonitor- Helm chart 当前也已支持 existing ConfigMap、
oah-sandboxPVC workspace volume,以及 per-component resources / securityContext / envFrom / scheduling 参数 - Helm chart 当前还已支持
PodDisruptionBudget、topologySpreadConstraints、priorityClassName与oah-apiIngress - chart 当前也已附带
dev / staging / prod三套 values 样例,作为多环境起步基线 - 仓库根目录下的生产
Dockerfile与 GHCR 发布 workflow - GHCR workflow 当前也已补上
sbom/provenance与 Cosign keyless signing - Deployment rollout 策略现在已经显式写入 manifests,而不是依赖 K8S 默认值
- worker runtime 收到退出信号后的基础 drain 生命周期
- workspace materialization 在 drain 期间的 idle flush / eviction 收敛
当前仍未完成:
- 若还要继续深化,主要会是更细粒度的组织内部多环境 values/overlay 约定,而不是平台能力缺口
Kubernetes 运行契约
Section titled “Kubernetes 运行契约”当前 split skeleton 在 Kubernetes 上推荐按下面这组契约运行:
oah-api- 只暴露外部 API 面
- 不直接承担 standalone worker drain 生命周期
oah-controller- 负责 backlog / worker registry / placement 观测
- 通过
scale_target.kubernetes作用到oah-sandbox - 多副本时通过 Lease 保证只有 leader 执行 reconcile
oah-sandbox- 在 Pod 终止前先进入
draining /readyz在 drain 开始后应立即转为503- 只在 drain 超时后才走 run recovery / requeue 策略
- 在 Pod 终止前先进入
当前 K8S scale target 的结果语义也应这样理解:
accepted- scale 请求已经被 API 接受,但目标 Deployment spec 还没完全收敛
progressing- 目标 Deployment 已指向新副本数,但 rollout 还没 ready
ready- 目标 Deployment 的 rollout 已达到 ready 状态
blocked- controller 策略当前阻止缩容
error- selector、权限、超时、K8S API 错误等导致 reconcile 失败
这组语义的意义在于:
- controller log / snapshot / metrics 不再只回答“有没有 patch 成功”
- 还会回答“容量是不是已经真正 ready”