HH-738: add constrained browser container control (#4)

2026-08-27 18:07:34 +08:00
parent 8aa194b264
commit 4b054d6f04
16 changed files with 1925 additions and 1 deletions
@@ -0,0 +1,43 @@
+# 浏览器容器控制面
+
+## 技术选型
+
+- 前端：React + Vite。阶段 A 只有一个运行环境页面，不引入路由、状态库或组件库。
+- 后端：Go 标准库模块化单体。控制面提供同源 API 和静态文件，受限网关单独封装 Docker Engine API。
+- 数据：本任务不引入业务数据库；Docker 容器标签是运行态事实，Profile 使用命名卷持久化。账号、任务和审计实体仍按产品规划在后续阶段落入 Postgres。
+- 部署：Docker Compose 启动控制面和受限网关；浏览器容器由网关动态创建。
+
+## 调用链与契约
+
+```text
+React ── /api/browsers ──> control-plane ── /v1/browsers ──> docker-gateway ──> docker.sock
+                                                                    │
+                                                                    └─> browser container
+```
+
+`POST /api/browsers` 接受 `{name, seed}` 并创建后启动；`GET /api/browsers` 列出受管容器；`POST /api/browsers/{name}/start|stop` 改变状态；`DELETE /api/browsers/{name}` 仅回收容器，保留 Profile 数据卷。名称唯一约束由 Docker 容器名保证，重复创建返回冲突；启停接受 Docker 的幂等响应，不自动重试未知结果。
+
+## docker.sock 安全边界
+
+将 socket 以只读文件挂载**不会**限制 Docker API 的写操作；拥有 socket 等价于拥有宿主机 root 权限。因此：
+
+- 只有 `docker-gateway` 挂载 socket，控制面和浏览器容器均不可见；网关只加入 control 网络，浏览器不能连接网关；
+- 网关只暴露四个面向领域的路由，不提供通用 Docker 代理；
+- 镜像、命令、网络、挂载和资源限制均由网关固定，外部输入只有受校验的名称和数字 seed；
+- 启停和删除前必须同时匹配固定名称前缀及 `io.creatorhub.managed`、`io.creatorhub.runtime-id` 标签；
+- 动态容器使用只读根文件系统、非 root 镜像、全部 capability drop、`no-new-privileges`、CPU/内存/PID 限制，且无宿主机端口和目录挂载；
+- 控制面只绑定 `127.0.0.1`，控制网络为固定名称的 Compose internal 网络；浏览器 bridge 关闭 ICC，阻止运行时直接互访，并按 ownership、role、driver、Internal 和完整 options 失败关闭校验，且拒绝复用 control 网络；
+- `BROWSER_IMAGE` 必须是固定 tag，拒绝 `latest`。
+
+网关自身一旦被攻破，socket 仍允许接管宿主机；应用内校验不能消除这个平台级风险。进入共享或生产环境前，应把浏览器调度迁到独立 Docker daemon/VM，或使用宿主机 Docker authorization plugin 做第二层强制授权，不应把 socket 暴露给公网服务。
+
+## 运行
+
+Docker socket 的 GID 因宿主机而异：
+
+```bash
+docker pull git.ipao.vip/rogee/fingerprint-chromium:148.0.7778.215
+DOCKER_GID=$(stat -c %g /var/run/docker.sock) docker compose up --build
+```
+
+打开 <http://127.0.0.1:8080>。默认浏览器镜像固定为 `git.ipao.vip/rogee/fingerprint-chromium:148.0.7778.215`，可通过 `BROWSER_IMAGE` 改为其他已审核的固定 tag。阶段 A 网络默认失败关闭且不能访问外网；后续授权沙箱必须先设计受管出口，再调整 `browser` 网络。