Detect actual service and Runner readiness, restore LAN access after network changes, protect production web builds with rollback, honor cancellation during executor startup, and show truthful cached-data and credential states.
5.3 KiB
本机工作空间的协作者访问
本机模式面向获准的可信操作者。网页可监听局域网地址;控制 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。
连续 8 次错误密码会触发全局 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 行为。