wishforge-ide/docs/local-k3s.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

7.1 KiB
Raw Blame History

在本地 k3s 上运行

用 Colima 起一个带 k3s 的虚拟机,把 WishForge 以 Kubernetes 方式完整跑起来:愿望由 Kubernetes provisioner 在每次运行独立的 Pod 中执行,经独立验证后合入。这是开发集群,不是生产安装(生产见 operations.md)。

与生产的差别

项目 本地 k3s 生产
部署模式 WF_DEPLOYMENT_MODE=development production
沙箱 普通 runc 容器,WF_RUN_SANDBOX_MODE=host,没有 Kata 与 bubblewrap Kata 虚拟机 + bubblewrap
Codex 的命令沙箱 起不来(runc Pod 不允许 bubblewrap 创建用户命名空间),Codex 不带它运行,时间线的「Executor started」会注明 必须可用,否则运行停在 infrastructure 等待
服务之间 集群内 HTTP(WF_ALLOW_INSECURE_HTTP=true) HTTPS 与 mTLS
登录 开发令牌,没有 OIDC;Web 是 Next.js 的开发构建 OIDC,Web 是生产构建
镜像 本地构建,推到虚拟机里的 localhost:5000 私有仓库中经审阅的镜像

每次运行的 NetworkPolicy 照常生效(k3s 自带网络策略控制器):沙箱只能访问 DNS、API(含模型代理)、Temporal 与平台 Git。模型调用经集群内 API 的运行级代理转发到你配置的网关。

前置条件

  • macOS 上的 Colima 与 kubectl(brew install colima kubectl)。
  • 虚拟机默认 6 CPU、12 GiB 内存、40 GiB 磁盘,可以用 WF_K3S_CPUS、WF_K3S_MEMORY_GIB、WF_K3S_DISK_GIB 调整。构建会占用虚拟机磁盘,build 结束时清理不再使用的镜像,构建缓存保留不超过 10 GB。
  • 一个 OpenAI 兼容的模型网关,以及它的 Key 和模型名。Codex 使用流式 /responses 与函数工具调用,不是每个模型都支持:先用 GET <网关>/v1/models 列出模型,再挑一个试。例如经 LiteLLM 的网关上,deepseek-v4-pro 可用。

所有 kubectl 与 docker 命令都显式使用 colima-wishforge 上下文。生成的密钥与镜像 digest 保存在 .wishforge/k3s/(不进 Git)。几点环境上的注意事项:

  • 当前上下文:Colima 每次启动都会把它的虚拟机设为 kubectl 与 Docker 的当前上下文。脚本从不依赖当前上下文,up 结束时会打印切回原上下文的命令,切不切由你决定。
  • 本机代理:宿主机设置了 HTTP(S)_PROXY(例如本机的 Clash)时,Colima 会把代理交给虚拟机里的 k3s 与 Docker,但不排除虚拟机自己的地址。这样 API Server 访问 kubelet 也会走代理,kubectl logs 与 exec 全部失败。up 启动虚拟机时补上 NO_PROXY(虚拟机网段 192.168.5.0/24、Pod 与 Service 网段、集群域名);不是这样启动的虚拟机,先 down 再 up。build 也把代理作为构建参数交给镜像构建(地址换成虚拟机看到的宿主机 192.168.5.2),npm、GitHub 与 open-vsx 的下载因此和宿主机走同一个代理;Docker 不把这些参数写进镜像历史与构建缓存。
  • 磁盘空间:虚拟机的磁盘是 Mac 上按需增长的文件(~/.colima/_lima/_disks/colima-wishforge),每次构建都会让它变大。Mac 的磁盘一旦写满,虚拟机里的写入就会失败,文件系统随之损坏,集群只能删除重建(colima delete --profile wishforge --data)。因此 up 在 Mac 空闲空间小于磁盘上限时拒绝创建虚拟机,build 在空闲空间不足 15 GiB 时拒绝构建;构建结束后会清理不再使用的旧镜像,并把构建缓存限制在 10 GB 以内。服务镜像先按各工作区的 package.json 安装依赖,只改源码时依赖层直接复用缓存。
  • Docker 凭据助手:脚本的 docker 命令使用 .wishforge/k3s/docker 中自己的客户端配置:沿用你的 contexts 与插件,但不带凭据助手与已保存的登录。卸载 Docker Desktop 后遗留的 credsStore: desktop 因此不会让构建失败。

步骤

启动带 k3s 的虚拟机和本地镜像仓库:

node scripts/k3s-local.mjs up

构建 API、worker、平台 Git、provisioner 与 Web 镜像并推送。第一次要下载基础镜像并安装依赖,耗时较长:

node scripts/k3s-local.mjs build

部署(WF_OPENAI_BASE_URL 为空时使用 OpenAI 官方接口):

WF_OPENAI_BASE_URL=https://<网关>/v1 WF_CODEX_DEFAULT_MODEL=<模型> node scripts/k3s-local.mjs deploy

把网关的 Key 保存为租户的 Codex 凭据(Key 经标准输入传入 API Pod,不出现在命令行参数里):

WF_TEST_MODEL_API_KEY=<Key> node scripts/k3s-local.mjs model

跑一个冒烟愿望:创建项目,配置验证命令,提交「创建 greeting.txt」的愿望,并跟踪到结束:

node scripts/k3s-local.mjs smoke

查看平台与沙箱 Pod:

node scripts/k3s-local.mjs status

停止虚拟机(数据保留,up 会恢复):

node scripts/k3s-local.mjs down

工作台

Web 工作台随 deploy 一起部署在集群里,由它在集群内调用 API。把它转发到本机(保持运行,Ctrl-C 停止转发):

node scripts/k3s-local.mjs web

然后打开 http://localhost:3100,地址要完全一致:工作台只接受来自部署时登记的地址(WF_PUBLIC_URL)的修改请求,换成 127.0.0.1 打开,提交愿望等操作会被拒绝。端口与本地开发环境(npm run dev:all 的 3000)错开,两者可以同时运行。端口被占用时 web 会直接报错,用 WF_K3S_WEB_PORT=<端口> 重新执行 deploy,web 就转发到新端口。每次 deploy 都会换掉 Web 的 Pod,端口转发随之断开,需要再执行一次 web。

集群里的 Web 是 Next.js 的开发构建(镜像构建参数 WEB_BUILD=development)。本地没有 OIDC,每个访问者都以开发令牌的身份登录。这种登录方式只存在于开发构建中,生产镜像是生产构建,不带它。

Temporal 控制台:

kubectl --context colima-wishforge --namespace wishforge-control port-forward service/temporal 8233:8233

排查

  • kubectl --context colima-wishforge --namespace wishforge-control logs deployment/api 查看 API;provisioner、worker-coordinator 同理。
  • 沙箱 Job 在 wishforge-tenant-demo 命名空间,名称形如 wf-<哈希>-executor / -verifier。运行进入等待或结束后,Job 会被释放,要看它的日志得趁运行还在进行。
  • 运行时间线(smoke 的输出,或 GET /v1/runs/<id>/events)记录 Agent 执行的每条命令及其退出码,模型请求经代理记账。
  • up 在下载 k3s 时失败(GitHub 的下载偶尔中断):直接重新执行 up,它会先停下装了一半的虚拟机再重新启动。
  • 改了设置(例如换模型)只需重新 deploy:读取设置与密钥的 Pod 带着它们的摘要,摘要变了就会滚动更新。
  • 改了代码后重新执行 build 与 deploy;新的运行会使用新的 worker 镜像。只改了个别服务时可以只重建它们,例如 node scripts/k3s-local.mjs build web(可选 runtime、worker、git-storage、provisioner、web),其余镜像沿用上次的 digest。