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

6.1 KiB
Raw Permalink Blame History

本机工作空间的协作者访问

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

本机模式面向获准的可信操作者。网页可监听局域网地址;控制 API、数据库、Temporal、Provisioner 等服务仍监听本机回环地址。平台在服务端验证本机管理员或个人账号登录后,以对应身份调用控制 API;个人账号还携带账号 ID 和密码版本,由控制面按当前权限授权。浏览器收不到控制 API 凭据。

配置与启动

运行 node scripts/setup-local-access.mjs,默认生成 .wishforge/local-access.json。文件由当前用户持有,权限为 0600,含随机管理员密码及独立会话密钥。生成器仅输出文件路径,重复运行保留原文件。管理员在本机私下读取其中的 username、password;不要将该文件提交仓库或粘贴到日志中。

在根目录私有 .env.local 中配置:

WF_LOCAL_ACCESS=true
WF_LOCAL_ACCESS_FILE=/absolute/path/to/wishforge-ide/.wishforge/local-access.json
WF_LOCAL_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://192.168.1.20:3000
WF_WEB_HOST=0.0.0.0
WF_WEB_PORT=3000
WF_WEB_SERVE_MODE=production

将示例地址替换为本机实际局域网地址。白名单必须是完整、精确的 HTTP(S) origin,不含路径或结尾斜杠。先执行 npm run local:build,再执行 npm run dev:all 启动。构建脚本加载根目录本机配置,但只将 Web 所需变量传给 Next。WF_WEB_SERVE_MODE=production 使用构建好的 Next 应用,避免开发热更新影响持续运行;控制 API 和执行服务仍使用显式 development 配置。本机会话验证独立于 Node 的开发模式,生产 Web 不会放行匿名 dev token。

代码变更后先停止旧 Web,再重新构建和启动。环境变更后也需要重启 Web;已运行的进程不会自动继承新环境。直接运行 Next 时必须传入这些 WF_LOCAL_* 变量。开发服务器(省略 WF_WEB_SERVE_MODE)只能监听回环地址:它会把源码映射与热更新通道交给任何访问者,启动器因此拒绝让它监听局域网地址。

切换局域网后恢复入口

IP 变化时,旧地址不可达,而新地址尚未获准会返回 403。使用以下命令查看本机地址、预览变更,再明确应用选择的地址:

npm run local:network
npm run local:network -- --address 192.168.1.20
npm run local:network -- --address 192.168.1.20 --apply

地址必须是当前网卡实际持有的 RFC1918 IPv4。工具只替换相同端口的旧 HTTP 局域网地址,保留回环及其他已有入口;不添加通配符,不修改登录凭据,不创建公网入口。默认只预览;--apply 将原配置备份到忽略提交的 .wishforge/local-poc/network-backups/,权限 0600,然后原子更新根目录 .env.local。其他配置保留不变。应用后重启服务,并用新地址登录、刷新项目列表验证。npm run local:doctor 可检查网络与服务状态,诊断不会自动授权新地址。

所有入口包括页面、API、事件流、交付文件均经过本机会话检查。登录页、框架静态资源和站点图标允许未登录访问。/api/session 未登录返回 401,因此本机模式的启动探活使用 /login。

登录与退出

协作者通过局域网或经批准的 HTTPS 入口访问,使用管理员在「成员与权限」页创建的个人账号登录,并只授予所需项目与操作权限。不要共享本机管理员账号。登录会话为加密、HttpOnly、SameSite=Strict 的 cookie,1 小时到期;HTTPS 入口额外设置 Secure,退出会清除会话 cookie。

本机管理员密码是 256 位随机值;个人账号使用各自的随机初始密码。登录限流用于限制 scrypt 校验开销。15 分钟内错误超过 8 次后,密码校验在全局范围内每 2 秒最多一次,而不是锁定 15 分钟,局域网中其他设备输错密码不会把管理员锁在外面。限流不信任客户端提供的转发 IP,状态存在当前 Web 进程内,进程重启会清空。更换凭据文件(尤其 passwordHash 或 sessionSecret)会使旧会话失效。所有写入请求必须携带与访问入口完全一致的 Origin;未在白名单的 Host 或跨站请求被拒绝。

局域网 HTTP 会在网络上传输登录凭据,访问范围应限于受信任网络。若需要互联网访问,使用已批准的 HTTPS 入口,并将该 HTTPS origin 加入白名单;公网隧道、DNS、防火墙和端口转发不由此配置自动创建。代理必须保留正确的 Host,并与 Next 的 HTTP(S) origin 配置一致。

未启用 WF_LOCAL_ACCESS 时保留原有 OIDC 登录逻辑。开发启动器只在开启本机鉴权且使用生产构建时绑定非回环地址;绑定到具体地址时,启动探活也访问该地址。

同一次运行调整预算

运行进入等待或暂停后,human Owner/Admin 可在运行详情展开“调整预算”,修改 Token、时间或修复轮次上限。平台保留已有用量和执行时间,校验每次运行上限及租户剩余额度,并记录旧值、新值和操作者。保存预算不会恢复执行,确认后仍需点击“继续”。未结算的模型请求需要先完成对账。

对应接口为 PATCH /v1/runs/:id/budget,请求体可包含 maxTokens、maxMinutes、maxRepairRounds 的一个或多个字段,必须提供 Idempotency-Key。浏览器通过受保护的 /api/runs/:id/budget 调用。已完成、正在运行或排队中的任务不接受预算修改;增加预算不会清零用量或自动扩大其他任务的额度。

验证

npx vitest run apps/web/src/lib/auth.test.ts apps/web/src/lib/local-access.test.ts
npm run typecheck -w @wishforge/web

覆盖凭据权限、密码校验、会话过期与轮换、dev token 隔离、Host/Origin 校验、未登录 API 保护、静态资源访问、全局登录限流及原有 OIDC 行为。