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>
8.5 KiB
在本地 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)。
- 在工作台的项目页创建开发环境。provisioner 在
wishforge-tenant-demo中为这个项目创建 Theia 工作区:一个 Deployment、一个 PVC 和一个协作 sidecar。第一次要拉取镜像,一两分钟后就绪。 - 点「打开 IDE」,浏览器经网关进入工作区。
- 平台托管的项目第一次打开时被克隆到以项目命名的文件夹,处在
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。