wishforge-ide/wiki/modules/provisioner-runner-git-service.md

4.7 KiB
Raw Blame History

模块:执行环境、驻地 Runner 与平台 Git

这三个应用分别位于「执行面的两端」和「代码交接点」,共同决定愿望能否在真实环境里落地。

apps/provisioner — 执行环境

入口:apps/provisioner/main.mjs;后端实现 local.mjs 与 kubernetes.mjs;工作区 workspaces.mjs、workspace-lifecycle.mjs;发布/运行资源 run-release.mjs、run-operations.mjs、resource-grants.mjs。

后端 适用 行为
local 本地开发 为每个代次在本机启动两个 worker 进程(WF_SANDBOX_MODE=host),没有隔离;只在 WF_DEPLOYMENT_MODE=development 下启动
kubernetes 生产 用 kubectl 创建 Kata Job、PVC、Secret、ServiceAccount、NetworkPolicy;IDE 工作区为独立 Deployment

接口(全部要求 Authorization: Bearer <WF_PROVISIONER_TOKEN>,除 /healthz):

方法与路径 作用
POST /runs 为该代次启动 executor 与 verifier;同一代次重复请求不重复启动
POST /runs/release 停止计算资源;控制面收到后才归还并发名额
POST /runs/purge 删除该运行所有代次保留的卷;仍有活动进程时返回 busy
POST /workspaces 创建/返回 IDE 工作区
GET/PUT /workspaces/:id/lifecycle 仅 kubernetes 后端:暂停/恢复
GET /healthz 健康检查

资源授权:API 用 WF_RESOURCE_GRANT_SECRET 做 HMAC 签名,绑定租户、运行、代次、套餐、CPU/内存/存储与运行镜像,有效期 5 分钟。两个后端都校验签名与有效期;kubernetes 后端还要求镜像在允许列表内。这是「执行资源不能被随便要」的机制。

测试:apps/provisioner/test/local.test.mjs、kubernetes.test.mjs、workspaces.test.mjs、workspace-lifecycle.test.mjs;npm test 会跑 node --test apps/provisioner/test/*.test.mjs。

apps/runner — 驻地交付代理

入口:apps/runner/src/main.ts:15 的 main()。

  • 必需配置:WF_CONTROL_PLANE_URL、WF_RUNNER_TOKEN、WF_TENANT_ID、WF_ENVIRONMENT_ID、WF_RUNNER_PUBLIC_KEYS、WF_RUNNER_STATE_DIR;缺一项直接启动失败(main.ts:17-25)。
  • 出站拉取:apps/runner/src/runner.ts 的 OutboundRunner 轮询控制面的签名任务,目标环境不需要公网入站端口。
  • 签名校验:公钥来自控制面注册;任务内容是 Ed25519 签名报文。
  • WF_RUNNER_EXECUTE=true 才真正执行部署,默认只渲染(render() 只读)。
  • POC 采用:设置 WF_POC_PROFILE_FILE 时,必须是本地开发模式(main.ts:28-32),否则拒绝启动;同时把 profile 摘要与公网地址作为 trustedPocDelivery 传入验签,防止换个 profile 冒充。
  • 健康与日志:apps/runner/src/health.ts、log.ts。

测试:apps/runner/test/local-entry.test.ts;POC 语义由 packages/runtime/test/poc-release.test.ts 与 tests/local-poc-delivery.test.ts 覆盖。

apps/git-service — 平台 Git

入口:apps/git-service/src/main.ts;实现 service.ts。

  • 平台 Git 是裸仓库服务,按仓库范围签发短期令牌:issueGitToken / verifyGitToken(service.ts:99、:103)。
  • 推送边界由 PRE_RECEIVE_HOOK(service.ts:44)执行:令牌里写明允许的引用前缀(例如 refs/heads/ide/),越界引用被拒绝;平台自己的合入不受该前缀限制。
  • 分支列举:branchesIn(repository, prefix)(service.ts:70),供工作台列出 IDE 分支。
  • 所有推送只接受快进,不能删除分支。

测试:apps/git-service/test/hooks.test.ts(例如 :17 验证 ide/ 作用域令牌只能推 ide/ 分支)、service.test.ts。

三者如何串起来

控制面 --(HTTP + 资源授权)--> provisioner --(Kata Job)--> executor / verifier
   |                                                              |
   |<---------------- 证据 / 阶段迁移(内部接口)------------------+
   |
   +--(签名任务, 出站轮询)--> runner --(kubectl patch)--> 目标集群
   |
   +--(Git 令牌, 引用前缀)--> git-service <--- IDE / verifier 推送

关键不变式:

  1. provisioner 不访问数据库、不持有签名密钥;它只执行资源创建。
  2. runner 不接收入站连接;目标环境无需暴露端口。
  3. git-service 的令牌按引用前缀限权,IDE 令牌无法直接推目标分支。

已知边界

  • 本地 host 模式没有隔离,只能显式开启;生产部署模式下无法启动,其证据也会被拒绝(docs/requirements.md FR-D2)。
  • provisioner 的 local 后端不支持工作区暂停/恢复,返回 lifecycle: "unmanaged"。
  • 平台 Git 不是通用 Git 托管:不支持 LFS、子模块、SSH/SCP 地址。