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

20 KiB
Raw Blame History

本机许愿服务运行说明

已停用(2026-11-02):WishForge 只运行在 POC 集群,Mac 本机部署及其数据已删除。现行部署、备份与恢复见 cluster-poc-deployment.md;本文仅作历史记录。

本机运行 WishForge 网页、控制面、Claude CLI 和发布 Runner。用户通过网页登录后提交愿望;项目固定接入 Gitea 的 longtao.wu/droboticflow 仓库 poc 分支,目标环境为既有 POC。Claude 修改独立工作区,受保护检查通过后由交付流程处理 Git 提交和发布。

后台运行

入口为 /Users/d-robotics/workSpace/wishforge-ide/scripts/local-poc-service.mjs。不带参数只读取状态。以下命令需在本机已登录的 macOS 用户下执行,无需 sudo:

node scripts/local-poc-service.mjs status
node scripts/local-poc-service.mjs doctor
node scripts/local-poc-service.mjs install
node scripts/local-poc-service.mjs stop
node scripts/local-poc-service.mjs start

install 写入当前用户的 ~/Library/LaunchAgents/cc.d-robotics.wishforge.local-poc.plist,注册并启动服务。重复执行会保留正在运行的相同配置。stop 禁用并卸载这个 LaunchAgent,防止 KeepAlive 立即重启;start 重新启用。更新配置后的重启使用先 stop、再 start;脚本或 LaunchAgent 内容变化时使用先 stop、再 install。停止前应让当前发布完成,避免中断正在进行的集群更新;中断后的任务按控制面状态和发布回执恢复。

首次切换到后台服务时,先由原启动终端正常结束本任务的前台 scripts/dev.mjs 与 Runner,再执行 install。不要使用 pkill node、按端口批量杀进程或停止 Colima。已有依赖服务继续运行;本脚本不启动、停止或重建 Docker、Colima、数据库和 Temporal。

stop 会等待 launchd 完成注销,并确认停止前记录的 supervisor、platform、Runner 进程已退出。只有 stopCompleted=true 才返回成功;如果仍处于 SIGTERMed、子进程尚未退出或无法读取进程状态,它最多等待约 45 秒后返回非零状态及诊断。遇到这种情况先重新检查 status,不要立即接着构建或启动,也不要通过批量杀进程绕过检查。

监督进程只启动两个直接子进程:scripts/dev.mjs 与 node --env-file=.wishforge/local-poc/runner.env --import tsx apps/runner/src/main.ts。前者自行读取根目录 .env.local;后者只获得最小系统环境和独立 runner.env。Runner 不继承根目录 API、数据库或模型凭据。子进程退出后整个本任务服务组退出,由 launchd 在节流间隔后重新启动。停止仅处理该 LaunchAgent 及它创建的子进程。

入口与登录

本机入口为 http://localhost:3000;同一可达局域网的其他设备使用 http://本机局域网IP:3000。是否跨网可达由现有路由和防火墙决定。当前部署另有经批准的 Cloudflare 临时 HTTPS 隧道,地址以维护者提供的链接和私有入口白名单为准;它只代理 Web,不公开内部 API。

本机管理员的登录凭据保存在 .wishforge/local-access.json,只允许本机当前用户读取(0600)。文件含用户名、密码和会话签名材料,不应上传到 Gitea、放入网页静态目录或复制到日志。文件不存在时可运行 node scripts/setup-local-access.mjs 创建;重复运行保留已有凭据。.env.local 的 WF_LOCAL_ACCESS_FILE 指向该文件的绝对路径。

其他人用个人账号登录:本机管理员(或已有的管理员账号)在网页「成员与权限」页创建账号、分配账户类型和项目范围,并把只显示一次的初始密码交给对方。账号保存在控制面数据库中(只存 scrypt 哈希);网页登录时向控制面核对密码,之后以本机令牌加上该账号和密码版本调用控制面,控制面按账号当前权限授权。停用账号立即生效;重置密码会让该账号已登录的会话失效。更换 local-access.json 的会话签名材料会让所有人的会话失效。

网络切换导致本机 IP 改变时:

  1. 使用系统网络设置或 ipconfig getifaddr en0 确认当前接口地址;使用其他接口时查询相应接口。
  2. 更新 .env.local 中 WF_LOCAL_ALLOWED_ORIGINS,保留需要的 http://localhost:3000、http://127.0.0.1:3000,将局域网地址更新为完整的 http://IP:3000。不使用通配符。
  3. 确认 WF_WEB_HOST=0.0.0.0、WF_LOCAL_ACCESS=true,停止并重新启动后台服务。
  4. 从另一台设备打开新地址并实际登录、刷新项目列表,确认网络和会话都可用。

网页使用 WF_WEB_SERVE_MODE=production 时,先确认没有执行中的愿望或发布,再运行 node scripts/local-poc-service.mjs stop,随后运行 node scripts/build-local-web.mjs,最后运行 node scripts/local-poc-service.mjs start。构建工具在 LaunchAgent 已注册或网页端口仍有进程监听时会拒绝构建;它不依赖登录页是否返回 200 来判断端口是否占用。

离线构建前,工具将当前 .next 保存到私有 .wishforge/local-poc/web-builds/previous-<id>。编译失败或产物不完整时自动还原上一版;成功时保留上一版并将路径写入 .wishforge/local-poc/last-web-build.json,同时删除更早的备份:只再多留一份更早的版本和最近一份失败版本,每份 50 至 200 MB,删除的目录记在回执的 prunedBuilds 中。若新版本上线后检查失败,先停止服务,再按回执中的确切路径还原上一版 .next;保留新版本目录供排查。这个备份只覆盖网页构建产物,服务端源码和数据库变化需要分别核对。构建锁位于 .wishforge/local-poc/web-build.lock;异常断电后先确认记录的构建进程已结束并检查备份,再处理残留锁。

start 和 install 会等待网页、API、数据库、provisioner、Git 服务及 Runner 就绪,最长约 90 秒;超时返回非零状态并输出具体诊断,已启动的进程继续保留以便排查。这个等待不代替登录后的业务验收。WF_WEB_SERVE_MODE 只决定 Next.js 使用预构建网页,控制面的本机运行模式仍为 WF_DEPLOYMENT_MODE=development。

配置与日志

  • .env.local:本机控制面和网页配置,0600。
  • .wishforge/local-poc/runner.env:Runner 独立配置,0600。
  • .wishforge/local-poc/ 下的 POC profile、签名公钥和执行回执:由交付流程维护,避免在运行任务中修改绑定。
  • .wishforge/local-poc/logs/platform.log、runner.log、supervisor.log:目录 0700、文件 0600。每个文件达到 5 MiB 时轮转,保留 3 个历史文件。runner.log 每行是一条带时间的 JSON,记录每个发布任务的开始、结果和耗时,以及发布时的重试,不含任务内容或凭据。
  • .wishforge/local-poc/service-state.json:监督进程和直接子进程状态;status 以 launchd 实时状态为准,不用陈旧 PID 杀进程。

status 只输出 launchd 进程状态、匹配当前 supervisor 的子进程 PID 和日志位置。doctor 进一步读取实际 HTTP 就绪状态及服务身份、网页构建产物、Runner 健康快照和 LAN 入口配置,并只读检查 POC 运行在本机之外依赖的东西(dependencies,不调用模型、不部署):集群 API 是否应答;poc 分支能否分别按构建读取的方式和集成推送所用的 SSH 登录读到;公网应用报告的构建提交,以及它是否就是分支的最新提交(不是时说明有人推送了还没有运行部署的提交);Claude CLI 能否启动;运行目录所在磁盘是否还有 5 GB 以上。任何一项不可用时状态为 degraded。start 等待就绪时不做这些检查。Runner 必须是当前 supervisor 的存活子进程,且健康快照来自相同 PID、具有成功认证轮询证据,才会显示 ready;执行任务时显示 busy,旧版 Runner 没有快照时显示 unverified。快照每 10 秒更新到独立 Runner 状态目录的 health.json,不含参数、环境变量或任务内容;写快照失败不会取消部署。

LAN 检查默认排除 VPN 接口,只需要一个当前可用且已授权的地址。它还通过 loopback 请求携带该地址的 Host 头,检测“磁盘配置已更新,但旧网页进程仍拒绝新地址”的状态。此检查不会自动授权地址,也不证明其他设备已能通过路由和防火墙访问。doctor 只读取状态,不领取 Runner 任务,不调用模型或执行部署。

排查时先看 supervisor.log 的启动/退出记录,再看对应服务日志。持续重启通常意味着依赖服务、构建产物、环境文件或权限未满足。请修复原因后再启动,不要复制完整环境文件到聊天或工单。

飞书通知(可选)

在 .env.local 中设置 WF_FEISHU_WEBHOOK_URL(飞书群自定义机器人的 webhook,必须是 https://open.feishu.cn/open-apis/bot/v2/hook/...)后重启服务,控制面会把待审批的发布、待审核的代码、需要人处理的运行、完成的运行和失败或回滚的发布推送到该群。可选:WF_FEISHU_WEBHOOK_SECRET(机器人开启签名校验时的密钥)、WF_FEISHU_MENTIONS(待审批与待审核消息要 @ 的 open_id,逗号分隔)、WF_NOTIFY_WEB_URL(消息按钮链接的网页地址,默认取 WF_LOCAL_ALLOWED_ORIGINS 的第一个)。webhook 与密钥都是凭据,不要复制到聊天或工单;发送失败时 platform.log 记录飞书返回的错误码,不含地址。每条消息只发一次(已发送的记录保存在数据库),只补发 30 分钟内的状态变化。

验证和电脑睡眠

本地执行目录默认是 ~/.local/share/wishforge/runs。不要把 WF_LOCAL_RUN_ROOT 放在 WishForge 源码目录下;Node/TypeScript 会沿父目录查找 node_modules,使项目意外继承平台的类型定义。本地 provisioner 会拒绝这种嵌套配置。

旧配置从 .wishforge/runs 迁移时,等待当前代次停止,在 .env.local 中把 WF_LOCAL_RUN_ROOT 改为仓库外的绝对路径,再重启本机服务。不要移动、删除或复用旧代次目录;它们保留作为恢复资料。已有运行通过控制面已持久化的 checkpoint 在新目录还原,已完成实现的运行应继续验证,不必重新调用模型。只有 setup-local-poc.ts 的明确 POC 配置流程会更新该设置;通用 setup-local.mjs 保留已存在的配置,需要操作人主动迁移。

受保护的项目安装、检查入口是 scripts/poc-project-check.mjs install|verify,项目设置使用该文件的绝对路径。它固定运行依赖安装、TypeScript 检查、前端测试、前端构建和 Go 测试,共享 .wishforge/poc-check-cache/ 缓存,不调用仓库部署或真实环境验收脚本。线上 POC 健康和发布版本须另行检查,不能以本地测试通过替代。

LaunchAgent 随当前用户登录运行,退出登录后停止;电脑关机或进入系统睡眠时,本机网页及任务执行不可用。需要持续接收愿望时保持电脑供电,并在系统设置中选择合适的睡眠策略。本脚本不修改睡眠设置,也不创建 Codex 定时任务。唤醒后检查 status、网页登录和依赖服务,运行中的愿望以控制面记录为准继续处理。

让 Claude 在沙箱中执行命令(可选)

默认情况下 Claude 只有文件工具,检查全部由受保护的验证流程执行。打开下面的设置后,Claude 可以在 Claude Code 自带的命令沙箱中构建和测试:命令没有网络(本机端口也不行),只能写工作区和运行目录下的临时目录,读不到用户主目录与 WishForge 目录(工作区和下面放行的模块缓存除外),也看不到模型凭据。受保护的验证流程照常执行,仍是唯一的判定依据。

  1. 确认没有执行中的愿望,运行检查。它会进行一次小的真实模型调用,逐项检查网络、本机端口、工作区外的读写、凭据、其他进程的环境与钥匙串都被挡住:

    node --env-file=.env.local --import tsx scripts/check-claude-command-sandbox.ts
    

    「钥匙串」一项通常显示 warn:Claude Code 的 macOS 沙箱固定允许访问系统安全服务,命令可以查询登录钥匙串,信任 security 工具的条目(例如经 security 命令保存凭据的工具写入的条目)可以被读取,其他条目会弹出授权提示,看到这类提示应拒绝。不能接受时不要打开此设置,或改用单独的 macOS 用户运行本机服务。

  2. 全部通过后,在 .env.local 中加入下面的设置(<仓库> 换成本仓库的绝对路径)。Go 模块缓存由受保护的安装流程写入,这里只放行读取:

    WF_CLAUDE_COMMAND_SANDBOX=true
    WF_CLAUDE_COMMAND_READ_PATHS=<仓库>/.wishforge/poc-check-cache/go/pkg/mod
    WF_CLAUDE_COMMAND_ENV='{"GOMODCACHE":"<仓库>/.wishforge/poc-check-cache/go/pkg/mod","GOFLAGS":"-mod=readonly","GOPROXY":"off","GOTOOLCHAIN":"local","GOWORK":"off"}'
    
  3. 先 stop 再 start 后台服务。之后运行的时间线在「Executor started」处注明命令是否在沙箱中运行;沙箱不能启动时自动退回只有文件工具。删掉 WF_CLAUDE_COMMAND_SANDBOX 并重启即可关闭。

让受保护检查在沙箱中运行(可选)

本机服务以 host 模式运行:受保护的安装与检查默认直接以当前用户执行,而它们运行的是 Agent 写或改过的代码,比如一个测试就能读取主目录里的密钥或访问网络。打开下面的设置后,检查与依赖安装改在 macOS 自带的沙箱(Seatbelt)中运行:

  • 读不到主目录里的文件内容,只能读工作区和下面放行的路径(文件是否存在等元数据仍然可见,路径才能正常解析);
  • 只能写工作区、下面放行的缓存,以及每条命令独享并在结束后删除的临时目录,任何时候都不能写工作区的 .git;
  • 只有依赖安装能联网;检查没有网络,打开 WF_HOST_CHECK_LOOPBACK 后可以使用本机回环端口;
  • 平台自己的服务端口(API、Temporal 及其网页、数据库、对象存储、provisioner、Git 服务、网页控制台)在任何情况下都连不上,启动时按 .env.local 中的地址自动列出,也可以用 WF_HOST_CHECK_BLOCKED_PORTS 补充;
  • 检查时钥匙串服务不应答。
  1. 确认没有执行中的愿望,运行检查。它不调用模型,也不部署:先逐项确认上面这些限制在这台机器上生效,再在沙箱里对最近一次构建的 droboticflow 源码运行 POC 的安装和全部检查:

    node --env-file=.env.local --import tsx scripts/check-host-check-sandbox.ts
    
  2. 全部通过后,在 .env.local 中加入下面的设置(<仓库> 换成本仓库的绝对路径)。droboticflow 的 Go 测试会在本机起临时服务,并写入 /tmp/workspace:

    WF_HOST_CHECK_SANDBOX=true
    WF_HOST_CHECK_READ_PATHS=<仓库>/scripts/poc-project-check.mjs
    WF_HOST_CHECK_WRITE_PATHS=<仓库>/.wishforge/poc-check-cache:/tmp/workspace
    WF_HOST_CHECK_LOOPBACK=true
    
  3. 先 stop 再 start 后台服务。之后的验证证据带有 checkSandbox: seatbelt;沙箱不能启动时运行停在「基础设施」等待,不会当作检查失败。删掉 WF_HOST_CHECK_SANDBOX 并重启即可关闭。

它只隔离检查与安装:Agent 由各自的执行器沙箱约束,执行器和验证器进程本身仍以当前用户运行。打开回环后,检查也能连到本机上其他未封锁的端口。

本机实验套餐由 operator CLI 管理:node --import tsx scripts/configure-local-poc-plan.ts 20000000 设置每月 2000 万计量 Token 和单并发;这不购买模型额度或扣款。单并发时后提交的愿望显示为「排队中」,前一个运行结束或停下等待后,几秒内开始。单次愿望默认 100 万 Token,包含 CLI 缓存读取。CLI 最终计量在回合结束时上报;被暂停、取消或超时打断的会话没有总量,改按它已收到的每次模型响应估算计入,时间线标为估算。超预算会阻止后续执行并保留检查点,不能视为供应商逐请求实时硬上限。

本机到 POC 集群 API 的连接不稳定时(例如经 Wi‑Fi 或企业网络客户端),构建与发布会自动重试没有得到应答的请求:读取最多试 6 次,间隔 2 至 30 秒;上传源码失败会重传,解压可安全重复;rollout status 断开后在发布时限内接着观察;发布后的公网检查(健康、就绪、首页、API 的构建提交和受保护业务检查)也各试 6 次,间隔 2 至 10 秒,因为滚动更新刚结束时公网入口可能还连到正在退出的旧 Pod。每次重试都有记录:构建时写进运行时间线,发布时写进 runner.log。连接中断超过这些重试时,运行仍停在「基础设施」等待,网络恢复后在网页上继续即可。可以用 kubectl --kubeconfig <POC kubeconfig> --request-timeout=5s get --raw /readyz 反复探测这条链路。

每次 POC 构建的记录在 ~/.local/share/wishforge/poc/builds/<发布>/:构建与发布清单、各组件的构建日志,以及上传给集群的源码包(约 30 MB)。构建成功后,其他构建中超过一小时的源码包会被删除,记录和日志保留;最新的源码包供 scripts/check-host-check-sandbox.ts 使用。

有人直接改 poc 分支或 POC 集群时

  • 运行实现期间有人推了 poc:合入时 Claude 的提交合并到最新的 poc 上,合并结果重新跑一遍受保护检查后才推送;冲突按修复轮处理。
  • 推到 poc 的提交让受保护检查失败时:合入的合并结果检查失败后,会再单独检查不带本次改动的 poc 和运行的起点。确认是之后推送的提交弄坏了 poc,运行停在「目标分支自身未通过检查」等待,不让 Claude 去改别人的代码,也不消耗修复轮数;修好 poc 后点「继续」,运行把已验证的改动合并到最新的 poc 上并重新检查。这些对照检查每次约 2.5 分钟,只在合并结果失败时才跑。
  • 运行合入之后有人推了 poc:构建照常进行,构建的是这个运行合入的提交,时间线会说明 poc 已经前进;更新的提交由之后的运行部署。只有 poc 被强推、不再包含这个提交时,运行才停在「仓库」等待(POC_SOURCE_REWRITTEN),这时取消运行,需要的话重新提交愿望。不要强推 poc:进行中的运行合入时会把删掉的提交重新带回来。
  • 发布的风险按这次要替换的组件当前运行的代码到这次发布之间的全部变化计算,直接推到 poc 的改动同样会触发审批(迁移、鉴权、Dockerfile、依赖等);沿用原镜像的组件这次不变,不计入。
  • 每次发布在 Deployment 上记下组件镜像构建自哪个提交和镜像本身。构建前按这些记录逐个判断:worker、coordinator 运行的代码与本次源码之间只有网页文件不同时沿用原镜像,否则重新构建。没有记录、记录已被回滚覆盖、或镜像被人用 kubectl set image 改过的组件视为来源不明:会重新构建,并且这次发布必须人工审批、不自动回滚。用 tag 而不是摘要部署的镜像同样视为来源不明(发布记录里的 expectedImages 可以是同一镜像仓库的 tag,images 仍只能是摘要);既不是 tag 也不是摘要、或不属于该组件镜像仓库的镜像,构建会停下并说明是哪个组件。
  • 因此升级到这个版本后的第一次 POC 发布会重建全部三个组件,并等待一次人工审批:此前 WishForge 只重建过 api,worker 和 coordinator 仍运行接入 POC 之前的镜像。