# 本机工作空间的协作者访问 > **已停用(2026-11-02)**:WishForge 只运行在 POC 集群,Mac 本机部署及其数据已删除。现行部署、备份与恢复见 [cluster-poc-deployment.md](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` 中配置: ```dotenv 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`。使用以下命令查看本机地址、预览变更,再明确应用选择的地址: ```sh 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` 调用。已完成、正在运行或排队中的任务不接受预算修改;增加预算不会清零用量或自动扩大其他任务的额度。 ## 验证 ```sh 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 行为。