wishforge-ide/docs/operations.md
eust-w 821c059081 🐛 Give a blue-green candidate and a fresh switch time to settle
The Compose and Kubernetes adapters checked a candidate once. A
container that had started but did not listen yet made the request
throw, and the deployment was reported as of unknown state, to be
reconciled by hand; one stray error from the stable entry right after
the switch rolled a healthy release back.

The candidate checks and the checks after the switch are now repeated,
six attempts two to ten seconds apart, as the POC's already were, and
the Runner logs each repeat. A candidate that never answers is
reported as not switched, with the previous release still serving.
A missing address or missing checks are reported at once instead of
being asked again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 17:41:47 +08:00

236 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 生产部署与运维
本文面向部署和运维 WishForge 的平台运维人员。本地开发见 [development.md](development.md),组件与信任模型见 [architecture.md](architecture.md)。
> 现状说明:仓库提供了生产所需的组件、镜像目标与 Kubernetes 基线(`infra/k8s/base`),但它们**尚未在真实集群上完成验收**(Kata 执行、网络隔离、Runner 部署与回滚、OAuth 客户端接入)。上线前请按第 12 节逐项验收。
## 1. 生产前提
| 依赖 | 要求 |
|---|---|
| Kubernetes | 控制面命名空间 + 每个租户独立的运行/工作区命名空间;运行沙箱与 IDE 工作区所在节点池安装 Kata(`RuntimeClass`),CNI 必须执行 NetworkPolicy |
| PostgreSQL | 16 或以上,高可用并开启 PITR。迁移使用管理员连接(超级用户或带 `BYPASSRLS`),运行时使用 `wishforge_app`(非超级用户、`NOBYPASSRLS`) |
| Temporal | 生产持久化存储;必须开启 mTLS。多个租户共用一个集群时,每个租户一个命名空间,并由服务端按客户端证书授权命名空间(见第 13 节) |
| 对象存储 | S3 兼容,开启 KMS 加密(`S3_SSE=aws:kms`),禁止公开访问 |
| 镜像仓库 | 私有仓库;所有镜像按 digest 引用 |
| 身份服务 | OIDC(Keycloak 或企业 IdP),Web 客户端与 MCP 客户端分别注册;Web 客户端需要签发 refresh token 才能自动续期会话 |
| 密钥系统 | Vault:KV v2 用于部署密钥,Transit(可选)用于 BYOK 加密 |
| 入口 | Web、API、IDE 网关的 TLS 与域名;Runner 到 API 的 mTLS |
## 2. 部署模式
API、平台 Git、worker、provisioner 与 Runner 都要求显式设置 `WF_DEPLOYMENT_MODE`,未设置时拒绝启动;Web 与 IDE 网关只在明确为 `development` 时才启用开发便利(开发令牌、本机 HTTP),其他情况一律按生产处理。
- `production`:拒绝开发令牌与 `host` 沙箱证据;要求 HTTPS、模型代理、受保护验收配置与持久化产物存储;发布审批需要请求人以外的第二个人。
- `development`:仅用于本机或可丢弃的测试环境。
不要依赖 `NODE_ENV` 推断部署模式。
## 3. 控制面组件与镜像
镜像从仓库根目录构建。运维提供经过审阅的不可变基础镜像(按 digest),仓库中没有可变的默认标签:
```bash
docker build --file infra/images/runtime.Dockerfile --target worker --build-arg NODE_IMAGE="$NODE_IMAGE" --build-arg DOCKER_CLI_IMAGE="$DOCKER_CLI_IMAGE" --tag "$WORKER_IMAGE" .
```
| 组件 | 镜像目标 | 副本 | 关键配置 |
|---|---|---|---|
| API | `runtime.Dockerfile` 的 `runtime` | 可多副本(outbox 用 `SKIP LOCKED` 认领) | `WF_DEPLOYMENT_MODE`、`DATABASE_URL`、`OIDC_ISSUER`、`OIDC_AUDIENCE`、`WF_WEB_CLIENT_ID`、`WF_PUBLIC_URL`、`WF_API_PUBLIC_URL`、`WF_INTERNAL_TOKEN_KEY`、`WF_RESOURCE_GRANT_SECRET`、`WF_DISPATCH_TENANTS`、`TEMPORAL_ADDRESS`、`TEMPORAL_NAMESPACE` 或 `TEMPORAL_NAMESPACE_PREFIX`、`TEMPORAL_TLS_*`、`S3_*`、`WF_RUNNER_SIGNING_KEY_FILE` |
| Web | `web` | 可多副本 | `WF_DEPLOYMENT_MODE`、`WF_API_URL`、`WF_PUBLIC_URL`(HTTPS)、`OIDC_ISSUER`、`OIDC_CLIENT_ID`、`OIDC_CLIENT_SECRET`、`WF_SESSION_SECRET` |
| 平台 Git | `git-storage` | 1(仓库根目录在持久卷上) | `WF_DEPLOYMENT_MODE`、`WF_GIT_ROOT`、`WF_GIT_ADMIN_TOKEN`、`WF_GIT_TOKEN_SECRET`、`WF_GIT_PUBLIC_BASE_URL`、`WF_GIT_HOST`/`WF_GIT_PORT`(默认 `127.0.0.1:4504`,集群内监听 `0.0.0.0`) |
| coordinator worker | `worker`,`WF_WORKER_ROLE=coordinator` | 可多副本 | `WF_WORKER_TOKEN`、`WF_CONTROL_PLANE_URL`、`TEMPORAL_ADDRESS`、`TEMPORAL_NAMESPACE` 或 `TEMPORAL_NAMESPACE_PREFIX` 加 `WF_DISPATCH_TENANTS`、`TEMPORAL_TLS_*` |
| deployer worker | `worker`,`WF_WORKER_ROLE=deployer` | 可多副本 | `WF_DEPLOYER_TOKEN`、`WF_CONTROL_PLANE_URL`,Temporal 配置同 coordinator |
| provisioner | `provisioner`(另需 `KUBECTL_IMAGE`) | 每个租户命名空间 1 个 | 见第 4 节 |
| IDE 网关 | `apps/ide/Dockerfile` 的 `gateway` | 每个租户 1 个 | 见第 6 节 |
| Theia 工作区 | `apps/ide/Dockerfile` 的 `theia` 目标 | 每个工作区 1 个,由 provisioner 创建 | 见 [apps/ide/README.md](../apps/ide/README.md) |
API 的其他配置:
- `WF_OPENAI_BASE_URL`:模型代理的上游,默认 `https://api.openai.com/v1`。可以换成 OpenAI 兼容的模型网关(需支持 Responses 接口),同时把 `WF_PROVIDER_PROXY_ALLOWED_MODELS` 与 `WF_CODEX_DEFAULT_MODEL` 设为网关提供的模型。
- `WF_RUN_WORKER_IMAGE`:签入资源授权的运行镜像 digest,必须与 provisioner 的 `WF_RUN_WORKER_IMAGE` 相同;生产中未配置时派发失败(`RUNTIME_IMAGE_UNCONFIGURED`)。运行在第一次派发时固定镜像,之后的代次沿用。
- `WF_GIT_SERVICE_URL`、`WF_GIT_ADMIN_TOKEN`:平台 Git 的内部地址与管理令牌(与平台 Git 的 `WF_GIT_ADMIN_TOKEN` 相同),用于创建仓库与签发仓库令牌。
- `WF_DEFAULT_EXECUTION_CPU_MILLI`、`WF_DEFAULT_EXECUTION_MEMORY_MIB`、`WF_DEFAULT_EXECUTION_STORAGE_MIB`:单个运行默认申请的资源(默认 2000m、4096 MiB、10240 MiB),不超过套餐上限。
- `WF_PLAN_CATALOG_FILE`、`WF_OPERATOR_SUBJECTS`:见第 5 节;`WF_REGION`:工作台显示的部署区域。
Temporal 连接:
- `TEMPORAL_TLS_CERT`、`TEMPORAL_TLS_KEY`(客户端证书)、可选的 `TEMPORAL_TLS_CA` 与 `TEMPORAL_TLS_SERVER_NAME`。生产中没有客户端证书时,API 与所有 worker 拒绝启动。
- `TEMPORAL_NAMESPACE_PREFIX` 让每个租户使用自己的命名空间 `<前缀><租户>`。这些命名空间需要预先注册;coordinator 与 deployer 会轮询 `WF_DISPATCH_TENANTS` 中每个租户的命名空间。生产中派发多个租户而没有设置前缀时,API 与这些 worker 拒绝启动。
静态服务令牌只能调用各自角色需要的接口:coordinator(`WF_WORKER_TOKEN`)只能读运行状态、记录等待与请求修复;deployer(`WF_DEPLOYER_TOKEN`)只能为已构建的运行取得租约并请求发布。executor 与 verifier 只使用 API 为每个运行代次签发的令牌。
数据库迁移在发布新版本前执行一次。在 `runtime` 镜像中运行(开发环境用 `npm run db:migrate`):
```bash
node dist/api/migrate.mjs
```
迁移文件位于 `apps/api/src/db/migrations/`,按版本号执行并连同校验和记录在 `schema_migrations` 中:已应用的版本不会重复执行,已应用的文件如果被修改,迁移会报错停止(应新增迁移修正)。它同时创建或更新 `wishforge_app` 角色(密码取自 `WF_DATABASE_APP_PASSWORD`),运行事件与用量账本对应用只允许追加。
## 4. 执行环境(Kubernetes provisioner)
provisioner 为每个运行代次创建两个 Kata Job(executor 与 verifier)及各自的 PVC、能力 Secret、不挂载令牌的 ServiceAccount,以及一条 NetworkPolicy。完整说明与变量见 [apps/provisioner/README.md](../apps/provisioner/README.md),最少需要:
| 配置 | 说明 |
|---|---|
| `WF_DEPLOYMENT_MODE=production`、`WF_PROVISIONER_BACKEND=kubernetes` | 生产模式与 Kubernetes 后端 |
| `WF_PROVISIONER_HOST`、`WF_PROVISIONER_PORT` | 监听地址(默认 `127.0.0.1:4450`,集群内监听 `0.0.0.0`) |
| `WF_PROVISIONER_TOKEN` | API 调用 provisioner 的服务令牌(至少 32 字符),与 API 的 `WF_PROVISIONER_TOKEN` 相同 |
| `WF_TENANT_ID` | 该 provisioner 服务的唯一租户 |
| `WF_KUBE_CONTEXT`、`WF_KUBE_NAMESPACE` | 目标集群上下文与该租户的运行命名空间 |
| `WF_RUN_WORKER_IMAGE` | worker 镜像(必须是 `@sha256:` digest);`WF_RUN_PREVIOUS_IMAGES` 列出仍允许继续运行的旧镜像 |
| `WF_RUN_STORAGE_CLASS`、`WF_RUN_STORAGE_SIZE` | PVC 存储类;单个运行的存储上限(两个角色各一半)与 IDE 工作区卷的大小 |
| `WF_CONTROL_PLANE_URL`、`WF_CONTROL_NAMESPACE` | 沙箱访问 API 的 HTTPS 地址与控制面命名空间 |
| `WF_GIT_SERVICE_PORT` | 平台 Git 服务端口(默认 4504) |
| `WF_RESOURCE_GRANT_SECRET` | 与 API 共享的资源授权签名密钥 |
| `TEMPORAL_ADDRESS`、`TEMPORAL_NAMESPACE` | Temporal 地址(`host:port`)与该租户的命名空间 |
| `WF_RUN_TEMPORAL_TLS_SECRET` | 租户命名空间中 `kubernetes.io/tls` 类型的 Secret(`tls.crt`、`tls.key`、`ca.crt`),挂载给 executor 与 verifier 作为 Temporal 客户端证书;生产必填 |
API 侧用 `WF_PROVISIONER_URL`、`WF_PROVISIONER_TOKEN`(单租户;派发多个租户时用 `WF_PROVISIONER_TENANT_ID` 指定它服务的租户)或 `WF_PROVISIONER_TARGETS_FILE`(多租户)找到 provisioner:
```json
{"schemaVersion":1,"tenants":{"tenant-a":{"url":"https://provisioner-a.internal","tokenEnv":"WF_TENANT_A_PROVISIONER_TOKEN"}}}
```
文件存在时,未列出的租户没有执行环境,不会回退到全局配置。
- 网络策略只放行 DNS、控制面 API(含模型代理)、Temporal 与平台 Git。
- **依赖安装**:配置 `WF_RUN_INSTALL_PROXY_URL` 后,经运维提供的出站代理访问包仓库。代理 Pod 带 `wishforge.io/component: egress-proxy` 标签,默认在控制面命名空间(`WF_RUN_INSTALL_PROXY_NAMESPACE`)。每次运行的策略放行到它的连接,安装命令通过 `HTTP(S)_PROXY` 使用它,验证命令仍然没有网络。代理负责 URL/IP 白名单、防 DNS 重绑定与屏蔽元数据地址。
- 运行代次结束后(成功、取消、等待或被新代次取代),API 请求释放:provisioner 停止该代次的 Job,确认停止后删除其 Secret、ServiceAccount 与 NetworkPolicy。PVC 保留用于排查。释放超过 `WF_RUN_STORAGE_RETENTION_HOURS`(默认 168 小时,设为 0 则一直保留)后,API 的维护循环每小时请求 provisioner 删除该运行所有代次的 PVC(`POST /runs/purge`),运行仍有活动 Pod 时不会删除。检查点保存在控制面,继续运行不需要这些卷。
- verifier 镜像中需要安装 bubblewrap(`WF_VERIFIER_BWRAP`,默认 `/usr/bin/bwrap`);受保护验收脚本放在 `/usr/local/lib/wishforge-verification/` 下并由 root 拥有,详见 [reference/verification-profiles.md](reference/verification-profiles.md)。
- Kata 客户机必须允许非特权用户命名空间:verifier 的 bubblewrap 和 Codex 自带的命令沙箱(同样是 bubblewrap)都依赖它。executor 启动 Codex 前会探测;不满足时运行停在 `infrastructure` 等待(`PROVIDER_SANDBOX_UNAVAILABLE`),不会在没有命令沙箱的情况下运行。上线前在目标节点池上跑一次运行来验收。
- **镜像构建**:由 verifier 在运维提供的远程构建器上完成,不要把宿主机 Docker socket 挂进任何 worker。
- `WF_VERIFIER_DOCKER_HOST`(`tcp://主机:端口`)是 Docker 兼容的构建守护进程,Pod 带 `wishforge.io/component: image-builder` 标签,默认在控制面命名空间(`WF_VERIFIER_BUILDER_NAMESPACE`)。
- `WF_VERIFIER_DOCKER_TLS_SECRET` 是它的客户端证书(`ca.pem`、`cert.pem`、`key.pem`),生产必填。
- `WF_VERIFIER_DOCKER_CONFIG_SECRET` 是推送镜像的仓库凭据。
- 每个代次额外有一条只作用于 verifier Pod 的策略,放行到构建器的连接,executor 连不到构建器。
## 5. 租户、套餐与配额
租户、套餐与成员由运维通过命令行管理(使用 `DATABASE_ADMIN_URL`,运行时角色无权修改租户与套餐):
```bash
npm run tenant:create -- <租户ID> '<租户名称>' <区域> <owner 的 OIDC subject> <套餐ID> <操作人 subject>
```
```bash
node --import tsx scripts/tenant-admin.ts plan <租户ID> <套餐ID> <操作人 subject>
```
```bash
node --import tsx scripts/tenant-admin.ts member <租户ID> <成员 subject> <角色> <操作人 subject>
```
最后的操作人 subject 可以省略,改用 `WF_OPERATOR_SUBJECT`;它必须列在 `WF_OPERATOR_SUBJECTS` 中。
套餐目录由 `WF_PLAN_CATALOG_FILE` 指定(格式见 `infra/plans/catalog.example.json`),限定成员数、项目数、工作区数、并发运行数、月度 token 与单次执行资源。分配套餐会把限额快照写入租户,修改目录不会自动影响已有租户;降级时如果现有用量超出新限额会被拒绝。`WF_OPERATOR_SUBJECTS` 列出可在 API 中执行运维操作(邀请成员、对账资源)的平台运维账号。
- 派发运行前,API 原子地占用一个执行名额并签发 5 分钟有效的资源授权(绑定租户、运行、代次、套餐版本、CPU/内存/存储与运行镜像),provisioner 校验授权后才创建资源。
- 月度 token 配额只计入排队或执行中的运行(以及有未结算模型请求的运行)的剩余预算;暂停、等待与结束的运行不占用,继续时重新计入。
- 用量:`GET /v1/usage` 返回本月 token 与执行时长,`GET /v1/usage/lines?period=YYYY-MM` 返回明细,`GET /v1/usage/export?period=YYYY-MM` 导出 CSV。模型费用由服务商直接向租户结算,平台不计价。
## 6. IDE 工作区与网关
每个租户运行一个 IDE 网关(`apps/ide/gateway`),它是浏览器访问 Theia 的唯一入口。用 `WF_WORKSPACE_GATEWAY_TARGETS_FILE` 为每个租户配置网关(单租户也可以用 `WF_WORKSPACE_GATEWAY_BASE`、`WF_WORKSPACE_GATEWAY_TOKEN`、`WF_IDE_PUBLIC_URL`,派发多个租户时用 `WF_WORKSPACE_GATEWAY_TENANT_ID` 指定租户):
```json
{"schemaVersion":1,"tenants":{"alpha":{"internalUrl":"https://alpha-ide.internal","publicUrl":"https://alpha.ide.example.com","tokenEnv":"WF_ALPHA_GATEWAY_TOKEN"}}}
```
- `internalUrl` 是 API 调用网关的地址,`publicUrl` 是浏览器访问的地址。不同租户必须使用不同的公网域名与令牌。
- 网关进程配置 `WF_DEPLOYMENT_MODE`、`WF_TENANT_ID`、`WF_WORKSPACE_GATEWAY_TOKEN`(与映射中 `tokenEnv` 的值相同)、`WF_API_URL`、`WF_IDE_PUBLIC_URL`(HTTPS)、`WF_IDE_ALLOWED_SERVICE_NAMESPACE`(工作区 Service 所在命名空间)。
- 启动流程:Web → API `POST /v1/workspaces/:id/launch` → 网关签发 30 秒一次性启动码 → 浏览器兑换为会话 Cookie。会话空闲 15 分钟失效;使用中(包括打开的 WebSocket)自动续期,最长 12 小时。
- 网关对每个请求与 WebSocket 向 API 复核权限(会话建立后按已授权的用户复核),撤销成员资格后立即断开连接。
provisioner 用 `WF_THEIA_IMAGE`(digest)创建工作区;配置 `WF_OCT_WORKSPACE_IMAGE` 与 `WF_IDE_PUBLIC_URL` 后每个工作区带一个协作 sidecar。
平台托管仓库的工作区在第一次打开时克隆项目,并切换到 `ide/work` 分支。网关在会话期间不断为它申请 15 分钟的仓库令牌,这个令牌只能推送 `ide/` 开头的分支,由平台 Git 的 pre-receive 钩子执行。人们推送后,从该分支提交愿望,由它验证并合入目标分支。为此需要:
- 工作区 Pod 能访问平台 Git:provisioner 会为每个工作区放行,控制面一侧见 [infra/k8s](../infra/k8s/README.md) 的 `workspaces-to-git`;
- 项目的 `repositoryUrl`(`WF_GIT_PUBLIC_BASE_URL`)对工作区可达;
- API 配置了 `WF_GIT_SERVICE_URL` 与 `WF_GIT_ADMIN_TOKEN`。
外部仓库不克隆。
工作区生命周期:用户可以在项目页暂停与恢复工作区;30 分钟没有活动且网关上没有打开的连接时自动暂停(`WF_WORKSPACE_AUTO_SLEEP=false` 可关闭)。暂停把工作区 Deployment 缩容到 0,文件保留在 PVC 中;未保存的编辑器内容会丢失。
多人协作需要为每个工作区部署独立的 OCT 实例,见 [apps/ide/collaboration/README.md](../apps/ide/collaboration/README.md)。
## 7. 交付:环境、Runner 与部署密钥
1. 租户管理员在「环境」页创建环境(Compose / Kubernetes / 平台托管 Kubernetes),然后注册 Runner,得到一次性显示的 Runner 令牌。
2. 在目标环境部署 `apps/runner`(`runner` 镜像目标),配置 `WF_DEPLOYMENT_MODE`、`WF_CONTROL_PLANE_URL`、`WF_TENANT_ID`、`WF_ENVIRONMENT_ID`、`WF_RUNNER_TOKEN`、`WF_RUNNER_PUBLIC_KEYS`(平台签名公钥)以及 mTLS 证书 `WF_RUNNER_CERT`/`WF_RUNNER_KEY`/`WF_RUNNER_CA`。Runner 默认只做演练,设置 `WF_RUNNER_EXECUTE=true` 后才真正部署。
Runner 还需要 `WF_RUNNER_STATE_DIR`(持久化任务状态的目录)以及目标的蓝绿配置,缺少任何一项时部署结果为 `unconfigured`:
| 目标 | 配置 |
|---|---|
| Compose | `WF_COMPOSE_DIRECTORY`、`WF_COMPOSE_PROJECT`、`WF_HEALTH_URL`(稳定入口)、`WF_CANDIDATE_HEALTH_URL_TEMPLATE`(含 `{port}`)、Caddy 的 `WF_CADDY_ADMIN_URL`、`WF_CADDY_PROXY_CONFIG_PATH`(以 `/config/` 开头)与 `WF_CADDY_DIAL_HOST`;可选 `WF_DOCKER_CONTEXT`、`WF_DEPLOYMENT_DOCKER_CONFIG`(拉取镜像的凭据) |
| Kubernetes | `WF_KUBE_CONTEXT`、`WF_KUBE_NAMESPACE`、`WF_HEALTH_URL`、`WF_CANDIDATE_HEALTH_URL_TEMPLATE`(含 `{service}`,可含 `{namespace}`);所需权限见 [infra/k8s/README.md](../infra/k8s/README.md#部署目标) |
新版本先作为候选启动,健康与业务检查通过后才切流,切流后再检查稳定入口,失败时切回旧版本。刚启动的应用可能还没开始监听,刚切换的入口也可能还连着旧连接,所以这两步的检查各试 6 次,间隔 2 至 10 秒,每次重试都写进 Runner 日志。候选始终没有应答时不切流,旧版本继续服务。
3. API 使用 `WF_RUNNER_SIGNING_KEY_FILE`(Ed25519 私钥,`WF_RUNNER_SIGNING_KEY_ID` 为密钥 ID)签名部署任务。
4. 部署密钥通过 Vault KV v2 按固定版本注入,配置与映射文件格式见 [reference/deployment-secrets.md](reference/deployment-secrets.md)。
5. 高风险或生产发布需要审批,审批 24 小时内有效,过期后发布失败,继续运行会重新请求发布。
## 8. 监控与审计
- `/health`:进程存活;`/readyz`:数据库可用。
- `/metrics`:Prometheus 格式,需要 `Authorization: Bearer $WF_METRICS_TOKEN`;未配置令牌时该路由不存在。指标按路由模板聚合,不包含资源 ID、提示词或凭据。
- 配置 `OTEL_EXPORTER_OTLP_ENDPOINT` 后导出请求 trace。
- 审计:`audit_events` 记录每次实体变更与操作者——Web 与 MCP 操作记为真实用户,模型代理的变更记为 `provider-proxy`,后台循环记为 `platform`。应用角色只能读取。
- 建议告警:API 5xx 比例、请求延迟、派发积压(未投递的 outbox 条目数与最老条目年龄)、处于 `ambiguous_execution`/`deployment` 等待超过 1 小时的运行、资源分配为 `unknown` 的运行。
## 9. 后台维护
API 进程内的维护循环(不依赖 Temporal)每 10 秒执行:释放已停止代次的计算资源;把代理进程已丢失、超过 15 分钟仍未结束的模型请求标记为结果未知;完成执行器两分钟内没有确认的暂停;使过期的审批与对应发布失效。每小时清理 7 天前已投递的 outbox 条目、30 天前的幂等记录,以及超过保留期的运行卷(见第 4 节)。设置 `WF_DISPATCH_ENABLED=false` 可在只读副本上关闭派发与维护循环。
## 10. 备份与恢复
`scripts/backup-restore.mjs` 基于导出快照做一致性备份,并能在独立的临时数据库中恢复并逐表比对摘要,不会覆盖源数据库:
```bash
node scripts/backup-restore.mjs --backup-only
```
```bash
node scripts/backup-restore.mjs --drill
```
```bash
node scripts/backup-restore.mjs --restore-verify --manifest .wishforge/backups/<备份>.manifest.json
```
脚本通过 `--container` 与 `--context` 指定运行 PostgreSQL 工具的容器与 Docker context,备份文件权限为 0600,不会自动删除。它只覆盖 PostgreSQL;平台 Git 仓库目录、对象存储、Vault 与 Temporal 需要各自的备份策略。生产应以托管数据库的 PITR 为主,本脚本用于恢复演练。
## 11. 故障处理
| 现象 | 处理 |
|---|---|
| 运行长时间 `waiting: sandbox_provisioner` | 检查 provisioner 健康与日志;恢复后派发器自动重试 |
| 运行 `waiting: worker_unavailable` | 执行进程没有在 5 分钟内接手;确认 provisioner 与 Temporal 正常后点击「继续」,系统以新的代次重新派发 |
| 运行 `waiting: ambiguous_execution` | 查看运行事件中最后一次外部操作;确认无副作用后点击「继续」,或取消 |
| 模型请求结果未知(`PROVIDER_REQUEST_IN_FLIGHT`) | `GET /v1/runs/:id/provider-requests` 找到状态为 `unknown` 的请求,owner/admin 调用 `POST /v1/runs/:id/provider-requests/reconcile`,body 为 `{"requestId": …, "usageTokens": …}`;不知道实际用量时省略 `usageTokens`,按预留额度结算 |
| 部署失败后无法再次发布 | Runner 报告明确失败(旧版本仍在服务)时环境锁自动释放;结果未知时先让 Runner 执行 `reconcile` 读回,仍无法确定时,owner/admin 在目标环境确认该版本没有在服务后,在环境页「核对后解锁」(`POST /v1/environments/:id/unlock`,body 为 `{"releaseId": …}`) |
| 资源分配 `unknown` 占用并发名额 | 确认 provisioner 已清理该代次资源后,平台运维调用 `POST /v1/admin/executions/:runId/reconcile` 释放名额 |
| 派发积压 | 检查 Temporal 与 provisioner 可用性;outbox 条目的认领期限过后会被其他副本重新认领 |
## 12. 上线验收
- 在目标集群上证明 Kata 隔离、跨租户网络拒绝、Secret 不可读、资源耗尽保护与镜像 digest 准入(见 [infra/k8s/README.md](../infra/k8s/README.md))。
- 用真实账号完成 WorkBuddy 与 Codex 的 MCP OAuth 流程(见 [connectors/README.md](../connectors/README.md))。
- 演练一次部署失败与回滚、一次环境解锁、一次数据库恢复。
## 13. 已知风险
- **Temporal 授权**:平台这一侧已经做到三点:
- 所有连接使用客户端证书;
- 每个租户使用自己的命名空间;
- 沙箱只拿到本租户的证书。
还需要运维在 Temporal 服务端配置授权:用 claim mapper 把客户端证书映射为只能访问本租户命名空间的角色,例如按证书主题区分租户。否则持有任意有效证书的客户端仍能访问所有命名空间。即使配置了授权,同一租户的沙箱仍可能轮询本租户其他运行的任务队列,影响的只是该租户自己的运行;结果是否成立仍以控制面的证据为准。
- **IDE 同 UID**:Theia 后端与用户终端以同一用户运行,同一工作区内的协作者之间没有隔离。
- **IDE 推送者不留痕**:平台不记录是谁推送了 `ide/` 分支,提交身份可以自行修改。这些改动进入目标分支前一定经过验证,但作者归属只能参考提交信息。
- **OCT 房间不持久**:协作服务重启后需要重新创建房间。