wishforge-ide/docs/local-k3s.md
eust-w 71cc6de5e2 fix: keep the local cluster from filling the Mac's disk
Repeated builds grew the VM's disk to 63 GB, until the Mac's disk was
full. Writes inside the VM then failed and its file systems broke.

- The service image installed dependencies after copying every source
  file, so each source change rebuilt a 750 MB layer, five images at a
  time. It now installs from the workspace manifests first, and a test
  keeps every workspace listed.
- The VM's disk defaults to 40 GiB instead of 80.
- `up` refuses to create the VM when the Mac has less free space than
  that, and `build` refuses below 15 GiB free.
- After building, superseded images are pruned and the build cache is
  capped at 10 GB.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 08:03:41 +08:00

8.5 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 是生产构建
IDE 网关在 localhost 上经 HTTP 访问;工作区是普通 runc Pod 网关使用 HTTPS 公网域名;工作区在 Kata 节点池
镜像 本地构建,推到虚拟机里的 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 调整。全部镜像(含 Theia)构建一次约占 10–15 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 与 IDE(Theia 工作区、IDE 网关、协作服务)镜像并推送。第一次需要二三十分钟,主要花在 Theia 的依赖安装与构建上:

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 与 4400)错开,两者可以同时运行。端口被占用时 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

IDE

IDE 网关随 deploy 一起部署,web 同时把它转发到 http://localhost:3101(端口可用 WF_K3S_IDE_PORT 修改,改后重新 deploy)。

  1. 在工作台的项目页创建开发环境。provisioner 在 wishforge-tenant-demo 中为这个项目创建 Theia 工作区:一个 Deployment、一个 PVC 和一个协作 sidecar。第一次要拉取镜像,一两分钟后就绪。
  2. 点「打开 IDE」,浏览器经网关进入工作区。
  3. 平台托管的项目第一次打开时被克隆到以项目命名的文件夹,处在 ide/work 分支。提交后 git push,再在项目页从这个分支提交愿望,验证通过后它会合入目标分支,详见 apps/ide/README.md。
  • 工作区只能经网关访问:它的网络策略只放行带 workspace-gateway 标签的网关 Pod,出站只允许 DNS 与平台 Git。
  • 30 分钟没有连接时工作区自动暂停(缩容到 0,文件保留在 PVC 中),在项目页可以恢复。
  • 本地集群里平台 Git 与网关走 HTTP,provisioner 只在开发部署且 WF_ALLOW_INSECURE_HTTP=true 时接受;生产要求 HTTPS。

排查

  • kubectl --context colima-wishforge --namespace wishforge-control logs deployment/api 查看 API;provisioner、worker-coordinator 同理。
  • 沙箱 Job 在 wishforge-tenant-demo 命名空间,名称形如 wf-<哈希>-executor / -verifier;IDE 工作区也在这里,名称形如 wf-ide-<哈希>。运行进入等待或结束后,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。