wishforge-ide/docs/local-browser-access.md
eust-w 87e01adb36 🔒 Space out local sign-in checks instead of locking out, and keep the dev server off the LAN
- Eight wrong passwords from anywhere on the network locked the only
  local administrator out for fifteen minutes, again and again. The
  password is 256 random bits, so the limit only has to bound the
  scrypt work: after eight failures, checks are spaced two seconds
  apart, globally, and a burst cannot run them at once.
- The launcher let the Next.js development server listen on the LAN,
  handing every visitor its source maps and hot-reload channel. Only
  the production build may now listen beyond loopback. A listener
  bound to one address is also checked for readiness there, and the
  banner shows the configured port.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 19:33:30 +08:00

5.7 KiB
Raw Blame History

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

本机模式面向获准的可信操作者。网页可监听局域网地址;控制 API、数据库、Temporal、Provisioner 等服务仍监听本机回环地址。平台在服务端验证本机管理员登录后,才会向控制 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、事件流、IDE 启动、交付文件均经过本机会话检查。登录页、框架静态资源和站点图标允许未登录访问。/api/session 未登录返回 401,因此本机模式的启动探活使用 /login。

登录与退出

协作者访问 http://本机局域网地址:3000,使用本机生成的管理员账号和密码登录。该身份拥有当前本机工作空间的操作权限;它不是多用户权限系统。登录会话为加密、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 与 IDE 保护、静态资源访问、全局登录限流及原有 OIDC 行为。