wishforge aab0dc08c8 🐛 Give the local workers the proxy settings the host actually exports
PASSTHROUGH only named HTTP_PROXY/HTTPS_PROXY/NO_PROXY, but a host usually exports the
lower-case pair (and often only NO_PROXY in upper case). The executor and verifier child
processes therefore started without a proxy, and their CLI could not reach a gateway
outside this machine — it hung with nothing on stdout while the run's heartbeat window ran
out.

Both spellings now cross into the workers, kept in step with PROXY_VARIABLES.
2026-11-09 04:12:22 -08:00
..

Provisioner

为每个运行代次创建执行环境(一个 executor、一个 verifier),并为云 IDE 创建工作区。控制面的派发器通过 HTTP 调用它;它本身不访问数据库,也不持有令牌签名密钥。

后端 WF_PROVISIONER_BACKEND 用途
local local 本地开发。为每个代次在本机启动两个 worker 进程(WF_SANDBOX_MODE=host),没有隔离;只在 WF_DEPLOYMENT_MODE=development 下启动。所有工作区指向同一个本机 Theia。
kubernetes kubernetes 生产。用 kubectl --context … --namespace … 创建 Kata Job、PVC、Secret、ServiceAccount 与 NetworkPolicy,IDE 工作区为独立的 Deployment。

接口

除 GET /healthz 外,所有请求都需要 Authorization: Bearer <WF_PROVISIONER_TOKEN>。

方法与路径 请求体 说明
POST /runs {tenantId, runId, generation, executorToken, verifierToken, resourceGrant} 为该代次启动 executor 与 verifier。同一代次重复请求不会重复启动。返回 {status: "provisioned", …}。
POST /runs/release {tenantId, runId, generation, resourceGrant} 停止该代次的计算资源。返回 {status: "released", computeReleased, persistentStorageRetained},控制面收到后才归还并发名额。
POST /runs/purge 同上(使用最近一个代次的授权,允许过期) 删除该运行所有代次保留的卷(本地后端删除运行目录)。运行仍有活动的 Pod 或进程时返回 {status: "busy"},否则返回 {status: "purged", persistentStorageRetained: false}。控制面在保留期过后调用。
POST /workspaces {tenantId, projectId, workspaceId} 创建或返回工作区,{status: "ready" | "pending", upstreamUrl};local 后端另返回 lifecycle: "unmanaged"(不支持暂停/恢复)。
GET/PUT /workspaces/:id/lifecycle — 仅 kubernetes 后端:观察与调整工作区的暂停/运行状态。
GET /healthz — {status: "ok", service: "wishforge-provisioner", backend}

资源授权(resourceGrant)由 API 用 WF_RESOURCE_GRANT_SECRET 做 HMAC 签名,绑定租户、运行、代次、套餐、CPU/内存/存储与运行镜像,有效期 5 分钟。两个后端都校验签名、租户与有效期;kubernetes 后端还要求镜像在当前或上一版的允许列表内,并按授权限制资源(两个角色各一半)。

executor 与 verifier 各自只拿到自己的运行级令牌(由 API 签发、绑定代次),并使用各自独立的工作目录。

local 后端

由 npm run dev:all 启动,配置由 npm run setup:local 写入 .env.local:

变量 说明
WF_PROVISIONER_BACKEND=local 选择本地后端
WF_PROVISIONER_TOKEN API 调用本服务的令牌(至少 32 字符)
WF_TENANT_ID 本服务的唯一租户(本地为 demo)
WF_RESOURCE_GRANT_SECRET 与 API 共享的资源授权签名密钥
WF_LOCAL_RUN_ROOT 运行目录,默认 ~/.local/share/wishforge/runs,必须位于 WishForge 源码目录之外;每个代次为 <租户>/<运行>/<代次>/{executor,verifier}
WF_LOCAL_IDE_URL 本机 Theia 地址(npm run dev:ide 启动在 http://127.0.0.1:4300/);能访问时工作区才变为 ready
WF_CONTROL_PLANE_URL、TEMPORAL_ADDRESS、TEMPORAL_NAMESPACE 传给 worker 进程

worker 进程只继承 PATH、HOME、LANG、TMPDIR、代理变量、WF_GIT_ALLOW_LOCAL_HTTP、WF_CODEBUDDY_BIN、WF_CLAUDE_BIN、WF_DOCKER_CONFIG 与 Temporal 的 TLS 设置,拿不到数据库、签名密钥等其他配置。代次结束后进程被停止,目录保留在磁盘上便于排查,保留期过后由控制面清理(同 POST /runs/purge)。provisioner 重启时会停止它启动的进程;仍在进行的运行会在 5 分钟后进入 worker_unavailable 等待,点击「继续」即可用新的代次重新执行。

kubernetes 后端

变量 说明
WF_PROVISIONER_BACKEND=kubernetes 选择 Kubernetes 后端
WF_PROVISIONER_TOKEN、WF_TENANT_ID、WF_RESOURCE_GRANT_SECRET 同上
WF_PROVISIONER_HOST、WF_PROVISIONER_PORT 监听地址,默认 127.0.0.1:4450;集群内需要监听 0.0.0.0
WF_KUBE_CONTEXT、WF_KUBE_NAMESPACE 目标集群上下文与该租户预先创建的命名空间
WF_RUN_WORKER_IMAGE worker 镜像,必须是 仓库/镜像@sha256:…
WF_RUN_PREVIOUS_IMAGES 可选,仍允许运行的上一版镜像(逗号分隔)
WF_RUN_STORAGE_CLASS PVC 存储类
WF_RUN_STORAGE_SIZE 单个运行的存储上限(两个角色各一半)与 IDE 工作区卷的大小,默认 10Gi
WF_CONTROL_PLANE_URL API 的 HTTPS 地址
WF_CONTROL_NAMESPACE 控制面命名空间(网络策略放行其中的 API、Temporal 与平台 Git)
WF_GIT_SERVICE_PORT 平台 Git 服务端口,默认 4504
TEMPORAL_ADDRESS、TEMPORAL_NAMESPACE Temporal 地址(host:port)与该租户的命名空间
WF_RUN_TEMPORAL_TLS_SECRET 租户命名空间中的 kubernetes.io/tls Secret(tls.crt、tls.key、ca.crt),以 /run/temporal 只读挂载给 executor 与 verifier,作为 Temporal 客户端证书;WF_DEPLOYMENT_MODE=production 时必填
WF_KATA_RUNTIME_CLASS 默认 wishforge-kata
WF_RUN_MAX_SECONDS Job 的最长运行时间,60–10800 秒,默认 3600
WF_RUN_CPU_MILLI_CAP、WF_RUN_MEMORY_MIB_CAP 单个运行的资源上限
WF_VERIFIER_DOCKER_CONFIG_SECRET 可选,仅 verifier 挂载的镜像仓库凭据(DOCKER_CONFIG)
WF_VERIFIER_DOCKER_HOST、WF_VERIFIER_DOCKER_TLS_SECRET、WF_VERIFIER_BUILDER_NAMESPACE 可选,远程构建器(tcp://主机:端口,Pod 标签 wishforge.io/component: image-builder)及其 TLS 客户端证书(ca.pem、cert.pem、key.pem,生产必填)和所在命名空间(默认控制面命名空间);只有 verifier 能连到它
WF_RUN_INSTALL_PROXY_URL、WF_RUN_INSTALL_PROXY_NAMESPACE 可选,依赖安装使用的出站代理(http(s)://主机:端口,Pod 标签 wishforge.io/component: egress-proxy)及其命名空间(默认控制面命名空间)
WF_THEIA_IMAGE IDE 工作区镜像(apps/ide/Dockerfile 默认目标),必须是 digest 引用
WF_OCT_WORKSPACE_IMAGE、WF_IDE_PUBLIC_URL 可选,协作 sidecar 镜像(digest)与网关的公开 HTTPS 源站(与网关的 WF_IDE_PUBLIC_URL 相同);WF_OCT_WORKSPACE_IMAGE 配置后工作区启用协作。本地开发集群(WF_ALLOW_INSECURE_HTTP=true)中网关地址与工作区的平台 Git 地址可以是 HTTP

每个代次创建:两个 RWO PVC、两个能力 Secret(各含一个角色的令牌)、两个不挂载令牌的 ServiceAccount、两个 Kata Job(backoffLimit: 0,非 root,只读根文件系统,丢弃全部 capability)以及一条 NetworkPolicy。新代次开始前只删除同一运行的旧 Job。POST /runs/release 删除属于该代次标签的 Job,Pod 全部结束后再删除该代次的 Secret、ServiceAccount 与 NetworkPolicy。PVC 保留用于排查,保留期过后由控制面通过 POST /runs/purge 按运行标签删除。

每个 IDE 工作区创建一个 PVC、一个 Kata Deployment(Theia,可选 OCT sidecar)、一个 Service 与一条 NetworkPolicy(只允许控制面中 wishforge.io/component: workspace-gateway 的 Pod 访问 3000/8100 端口,出站只有 DNS)。所需的 RBAC 与命名空间基线见 infra/k8s。

请求带 repositoryUrl(API 只为平台托管仓库发送,地址必须是 HTTPS 的 /git/<租户>/<项目>.git)时:

  • Theia 收到 WISHFORGE_GIT_REMOTE,只接受这个仓库的凭据;
  • 内存卷挂载为 WISHFORGE_GIT_CREDENTIAL_DIR(/run/wishforge/git),令牌只存在这里;
  • 网络策略额外放行控制面中 wishforge.io/component: git-storage 的 Pod(WF_GIT_SERVICE_PORT)。

克隆与凭据的投递见 apps/ide/README.md。

网络策略只放行 DNS、控制面 API(含模型代理)、Temporal 与平台 Git 服务(WF_GIT_SERVICE_PORT,默认 4504,Pod 标签 wishforge.io/component: git-storage)。配置了出站代理与构建器时,再分别放行它们:代理给两个角色,构建器只给 verifier(单独的 <前缀>-builder 策略,释放时一并删除)。代理与构建器本身由运维提供(见 operations.md)。

测试

node --test apps/provisioner/test/*.test.mjs

测试覆盖两个后端的请求校验、资源授权、渲染出的 Kubernetes 资源与本地进程的环境隔离(使用伪造的 kubectl 与子进程),不连接真实集群。npm test 会运行这些测试。