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.
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 会运行这些测试。