Operations, development and architecture docs, the reference pages and the component READMEs were rewritten against the code: every documented variable exists, and the settings operators need (runtime image, Git service, listen addresses, Runner targets, single-tenant gateway and provisioner bindings) are documented. Gaps the docs used to present as working are now stated as such: IDE workspaces do not clone the project yet (FR-H2), and in Kubernetes mode dependency installs and image builds have no network path until an egress proxy and builder access exist. The Kubernetes README describes what the provisioner creates, what the Runner needs in a target namespace, and the cluster acceptance that is still outstanding. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
按工作区隔离的 OCT 协作
本目录提供协作服务的启动器(start-isolated.mjs)与策略扩展使用的地址前缀适配器(client-factory.cjs)。每个工作区运行一个独立的 Open Collaboration Tools(OCT)0.3.1 进程,房间注册表与签名密钥不在工作区之间共享。身份以 WishForge 网关会话为准;OCT 的 user 显示名只是未经校验的展示文本,不代表租户身份或权限。
与上游实现相关的约束
以下行为来自固定版本的 Theia 1.76.0 与 OCT 0.3.1 源码,适配器据此设计:
- OCT 服务的 HTTP 路由都在根路径(
/api/meta、/api/login/*、/api/session/*),没有 basepath 选项;Socket.IO 使用默认的/socket.io/路径,独立的/websocket服务在上游被注释掉,所以只支持 Socket.IO 传输。 - 上游的 Socket.IO 传输调用
io(url)时不传path,会把 URL 路径当作命名空间;Theia 的登录表单也会把绝对端点解析到源站根路径、丢掉工作区前缀。适配器因此显式设置 Socket.IO 路径为/workspaces/<id>/collaboration/socket.io,并把登录端点改写为相对的api/login/simple,不允许任意 OAuth 地址。 - 上游默认使用固定的开发签名密钥且 JWT 不过期。
start-isolated.mjs为每个进程生成随机密钥、JWT 8 小时过期,只开启显示名登录(OCT_ACTIVATE_SIMPLE_LOGIN=true)。服务重启后旧的房间凭据失效,需要重新创建或加入房间。它还绕开了 OCT 0.3.1 命令行parseInt端口参数的问题。 - Theia 使用的协议 0.3.0 与服务端 0.3.1 兼容(0.x 系列按主次版本号校验)。
源码位置:OCT 服务、显示名登录、凭据管理、协议连接、Theia 协作贡献。
网关与客户端约定
API 的工作区授权结果给出可信的上游地址:
{
"tenantId": "tenant-id",
"projectId": "project-id",
"workspaceId": "workspace-id",
"role": "developer",
"upstreamUrl": "http://workspace-service:3000",
"collaborationUpstreamUrl": "http://workspace-service:8100"
}
只有 provisioner 能设置这些上游,公开调用方不能指定 OCT 地址。网关对 /workspaces/<id>/collaboration/ 下的每个 HTTP 请求与 WebSocket 升级都要求 edit 权限,去掉前缀后转发到该工作区的 collaborationUpstreamUrl;保留 x-oct-* 协议头,去掉平台的 bearer 令牌与 Cookie,并定期复核已升级的连接。viewer 不能进入协作。
Theia 后端收到 WF_COLLABORATION_GATEWAY_URL=https://ide.example/workspaces/<id>/collaboration/。客户端适配器要求该地址与浏览器同源且属于当前工作区;初次握手使用轮询(便于携带 OCT 请求头),之后升级为 WebSocket。
运行
每个工作区一个协作进程,配置 WF_WORKSPACE_ID、WF_TENANT_ID、WF_OCT_PORT=8100、WF_OCT_HOST=0.0.0.0 与 WISHFORGE_GATEWAY_ENFORCED=true。在 Kubernetes 中放在工作区的 Kata Pod 内,8100 端口只允许网关访问,不对外暴露 Ingress;不需要工作区卷,根文件系统可以只读,去掉 Linux capability 并禁止提权。本机只在回环地址监听时可以使用默认的 WF_OCT_HOST=127.0.0.1。
docker build -t wishforge/oct-workspace:0.3.1-wf1 apps/ide/collaboration
infra/compose.yaml 中共享的开发 OCT 容器只用于协议检查,不承载工作区的房间。
测试
node --test apps/ide/collaboration/test/client-factory.test.cjs
WF_OCT_INTEGRATION=1 node --test --test-force-exit apps/ide/collaboration/test/isolated-oct.test.mjs
第二个测试需要 Docker:启动两个只监听回环地址的 OCT 容器,经真实的网关、不透明会话、固定版本的协议客户端、Socket.IO 加密与 Yjs 文档,验证主客双向编辑收敛、viewer 被拒绝、其他工作区的 Cookie 与复制的邀请被拒绝、跨实例 JWT 被拒绝,以及撤销权限后连接被关闭。其中控制面的授权接口是测试替身,因此它验证的是协议与路由,不是生产 OIDC 或 Kata 环境。Node 测试中 Engine.IO 在 withCredentials=true 时会替换手工注入的 Cookie,所以测试把它设为 false;浏览器客户端保持 true,依赖网关真实的 HttpOnly Cookie。
OCT 0.3.1 的房间只保存在内存中,不支持持久化的房间恢复。