wishforge-ide/docs/operations.md
eust-w da1cfcea13 🔥 Remove the cloud IDE
The cluster never ran Theia or the IDE gateway, so every workspace stayed
"未配置" forever. The feature is gone instead of half-present:

- API: workspace, launch and lifecycle endpoints, the gateway identity and
  its internal routes, the dispatcher's workspace provisioning and the
  lifecycle worker. Migration 003 deletes stored workspaces and settles
  their pending outbox items.
- Provisioner: workspace provisioning and lifecycle for both backends.
- Web: the 云 IDE panel, the launch route, the start-branch picker that
  listed IDE branches, and the workspace count on usage.
- apps/ide, infra/oct, dev:ide and the CI job; IDE parts of local k3s,
  network policies, RBAC, docs and the architecture diagram.

A wish can still start from a pushed branch through the API (sourceBranch).
Plan files and stored entitlements may still carry maxWorkspaces; it is
accepted and ignored.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-11-04 12:43:02 +08:00

19 KiB
Raw Permalink Blame History

生产部署与运维

本文面向部署和运维 WishForge 的平台运维人员。本地开发见 development.md,组件与信任模型见 architecture.md。

现状说明:仓库提供了生产所需的组件、镜像目标与 Kubernetes 基线(infra/k8s/base),但它们尚未在真实集群上完成验收(Kata 执行、网络隔离、Runner 部署与回滚、OAuth 客户端接入)。上线前请按第 11 节逐项验收。

1. 生产前提

依赖 要求
Kubernetes 控制面命名空间 + 每个租户独立的运行命名空间;运行沙箱所在节点池安装 Kata(RuntimeClass),CNI 必须执行 NetworkPolicy
PostgreSQL 16 或以上,高可用并开启 PITR。迁移使用管理员连接(超级用户或带 BYPASSRLS),运行时使用 wishforge_app(非超级用户、NOBYPASSRLS)
Temporal 生产持久化存储;必须开启 mTLS。多个租户共用一个集群时,每个租户一个命名空间,并由服务端按客户端证书授权命名空间(见第 12 节)
对象存储 S3 兼容,开启 KMS 加密(S3_SSE=aws:kms),禁止公开访问
镜像仓库 私有仓库;所有镜像按 digest 引用
身份服务 OIDC(Keycloak 或企业 IdP),Web 客户端与 MCP 客户端分别注册;Web 客户端需要签发 refresh token 才能自动续期会话
密钥系统 Vault:KV v2 用于部署密钥,Transit(可选)用于 BYOK 加密
入口 Web、API 的 TLS 与域名;Runner 到 API 的 mTLS

2. 部署模式

API、平台 Git、worker、provisioner 与 Runner 都要求显式设置 WF_DEPLOYMENT_MODE,未设置时拒绝启动;Web 只在明确为 development 时才启用开发便利(开发令牌、本机 HTTP),其他情况一律按生产处理。

  • production:拒绝开发令牌与 host 沙箱证据;要求 HTTPS、模型代理、受保护验收配置与持久化产物存储;发布审批需要请求人以外的第二个人。
  • development:仅用于本机或可丢弃的测试环境。

不要依赖 NODE_ENV 推断部署模式。

3. 控制面组件与镜像

镜像从仓库根目录构建。运维提供经过审阅的不可变基础镜像(按 digest),仓库中没有可变的默认标签:

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 节

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):

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,最少需要:

配置 说明
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 存储类;单个运行的存储上限(两个角色各一半)
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:

{"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。
  • 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,运行时角色无权修改租户与套餐):

npm run tenant:create -- <租户ID> '<租户名称>' <区域> <owner 的 OIDC subject> <套餐ID> <操作人 subject>
node --import tsx scripts/tenant-admin.ts plan <租户ID> <套餐ID> <操作人 subject>
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 与单次执行资源(旧目录中的 maxWorkspaces 仍被接受,但已不起作用)。分配套餐会把限额快照写入租户,修改目录不会自动影响已有租户;降级时如果现有用量超出新限额会被拒绝。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. 交付:环境、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

    新版本先作为候选启动,健康与业务检查通过后才切流,切流后再检查稳定入口,失败时切回旧版本。刚启动的应用可能还没开始监听,刚切换的入口也可能还连着旧连接,所以这两步的检查各试 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。

  5. 高风险或生产发布需要审批,审批 24 小时内有效,过期后发布失败,继续运行会重新请求发布。

7. 监控与审计

  • /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 的运行。

8. 后台维护

API 进程内的维护循环(不依赖 Temporal)每 10 秒执行:释放已停止代次的计算资源;把代理进程已丢失、超过 15 分钟仍未结束的模型请求标记为结果未知;完成执行器两分钟内没有确认的暂停;使过期的审批与对应发布失效。每小时清理 7 天前已投递的 outbox 条目、30 天前的幂等记录,以及超过保留期的运行卷(见第 4 节)。设置 WF_DISPATCH_ENABLED=false 可在只读副本上关闭派发与维护循环。

9. 备份与恢复

scripts/backup-restore.mjs 基于导出快照做一致性备份,并能在独立的临时数据库中恢复并逐表比对摘要,不会覆盖源数据库:

node scripts/backup-restore.mjs --backup-only
node scripts/backup-restore.mjs --drill
node scripts/backup-restore.mjs --restore-verify --manifest .wishforge/backups/<备份>.manifest.json

脚本通过 --container 与 --context 指定运行 PostgreSQL 工具的容器与 Docker context,备份文件权限为 0600,不会自动删除。它只覆盖 PostgreSQL;平台 Git 仓库目录、对象存储、Vault 与 Temporal 需要各自的备份策略。生产应以托管数据库的 PITR 为主,本脚本用于恢复演练。

10. 故障处理

现象 处理
运行长时间 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 条目的认领期限过后会被其他副本重新认领

11. 上线验收

  • 在目标集群上证明 Kata 隔离、跨租户网络拒绝、Secret 不可读、资源耗尽保护与镜像 digest 准入(见 infra/k8s/README.md)。
  • 用真实账号完成 WorkBuddy 与 Codex 的 MCP OAuth 流程(见 connectors/README.md)。
  • 演练一次部署失败与回滚、一次环境解锁、一次数据库恢复。

12. 已知风险

  • Temporal 授权:平台这一侧已经做到三点:

    • 所有连接使用客户端证书;
    • 每个租户使用自己的命名空间;
    • 沙箱只拿到本租户的证书。

    还需要运维在 Temporal 服务端配置授权:用 claim mapper 把客户端证书映射为只能访问本租户命名空间的角色,例如按证书主题区分租户。否则持有任意有效证书的客户端仍能访问所有命名空间。即使配置了授权,同一租户的沙箱仍可能轮询本租户其他运行的任务队列,影响的只是该租户自己的运行;结果是否成立仍以控制面的证据为准。