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

64 lines
6.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 本机工作空间的协作者访问
> **已停用(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 行为。