rogee/creator-hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: migrate browser gateway to native xvfb

Browse Source
This commit is contained in:
rogee
2026-09-18 16:50:18 +08:00
parent 7e3808cf4c
commit e8f2c192ba
86 changed files with 6104 additions and 5323 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/native-browser-implementation-plan.md
+24 -25
View File
@@ -1,14 +1,14 @@
# 原生浏览器环境：评审后的实施计划
> 状态：待批准实施。仅文档，本轮未修改业务代码、数据库或运行环境。
> 依据：[变更评审](native-browser-change-review.md)、[业务基线](plan01.md)。验收：[验证文档](native-browser-verification.md)。
> 状态：实施 worktree 已按本计划完成 native gateway、控制面契约、runtime-use lease、前端和单机部署代码改造；自动检查与真实平台/代理/LAN 验收分开记录，缺少授权或真实资源时标为阻塞。
> 依据：[变更评审](native-browser-change-review.md)、[业务基线](plan01.md)。验收：[验证文档](native-browser-verification.md)；记录：[单节点验证记录](evidence/native-browser-verification-2026-09-18.md)。
## 1. 完成定义
满足以下条件才算完成改造，而不是“可以启动 Chromium”就结束：
- 各 gateway 不访问 Docker socket，不创建浏览器容器、镜像层、卷或网络；每个 runtime 在本机运行 Xvfb 与指定版本浏览器。
- 通过现有控制面管理至少两台机器；账号、运行代次、代理、Profile 与实际节点一致，不自动跨机重建。
- 本目标先通过现有控制面管理单台机器；账号、运行代次、代理、Profile 与实际节点一致，不自动跨机重建。多节点仅保留稳定契约字段，另立目标。
- 采集任务可按需启停；任务自建进程和临时文件在所有终态回收。清理失败真实可见并可重试。
- 持久登录、Profile、稳定指纹及账号身份在重启和普通浏览器升级后保持；二维码登录、采集结果及逐次确认的人工发送不退化（A02、A10；AC-E1）。
- gateway、控制面重启及监听重连不清除自动响应的事件去重、基线或 UID 冷却；旧事件不重放，迟到事件默认只记录、不自动补发（C02、D04；AC-A9、AC-B1）。
@@ -20,11 +20,10 @@
```text
React → Go control-plane（账号/任务/绑定/业务结果/素材发布）
├─ gateway A（已有节点登记与路由）
│ ├─ 预安装浏览器版本（所有任务共用只读二进制）
│ ├─ 账号 A 的持久 Profile
│ └─ runtime generation：Xvfb + 浏览器 + 临时目录
└─ gateway B（同样结构，独立本地资源）
└─ native gateway G（单节点；保留后续节点登记契约）
├─ 预安装浏览器版本（所有任务共用只读二进制）
├─ 账号的持久 Profile
└─ runtime generation：Xvfb + 浏览器 + 临时目录
```
- 继续使用 Go 控制面、Python gateway、PostgreSQL 与现有 CDP/WebSocket。
@@ -35,7 +34,7 @@ React → Go control-plane（账号/任务/绑定/业务结果/素材发布）
## 3. 必要数据和接口变化
以下为**契约变更提案**，不是已存在的新字段/API。P0 批准后才能实施。
以下为本实施 worktree 已采用的**单节点契约**；多节点字段保留稳定命名，但跨机调度与恢复不在本目标内。
| 概念 | 变更 | 约束 |
| --- | --- | --- |
@@ -65,8 +64,8 @@ React → Go control-plane（账号/任务/绑定/业务结果/素材发布）
交付：
1. 确认当前未提交工作由谁负责，将基线固定到可复现提交；在干净、明确基线之上新建实施分支，不擅自 stash/reset 用户改动。
2. 核实两台 Linux 机器的 systemd、用户服务、Xvfb、字体、浏览器依赖、sandbox、可用磁盘；取得合法原生指纹浏览器并固定版本，指定用于 A02 普通升级验证的源版本与目标版本。
3. 记录旧方式性能/磁盘基线。默认不运行 Docker；如无历史可信数据，需要用户另行批准旧方式对照运行。
2. 核实单台 Linux 机器的 systemd、用户服务、Xvfb、字体、浏览器依赖、sandbox、可用磁盘；取得合法原生指纹浏览器并固定版本，指定用于 A02 普通升级验证的源版本与目标版本。
3. 记录可用的旧方式性能/磁盘基线。默认不运行 Docker；如无历史可信数据，性能改善明确标记未验证，不用新建旧浏览器对照冒充基线。
4. 列出受影响状态码、载荷、字段、配置和移除项，批准第三节契约。明确 gateway 重启后受管 runtime 的恢复行为。
5. 固定验证参数：任务最长时间、清理时间预算、任务使用权续租/过期时间、磁盘下限、并发数、日志保留及资源对比指标。
@@ -127,23 +126,23 @@ React → Go control-plane（账号/任务/绑定/业务结果/素材发布）
- 扩展 P2 的 Refine data provider 和交互测试，覆盖 P3 完整资源归属及多节点场景；保留业务结果、清理状态、错误和禁用原因分别可见，不把首个闭环必需的界面工作留到本阶段。
- 增加可重复部署的 gateway/原生 runner 用户服务配置和本机浏览器安装说明。跨重启保留节点 ID、Profile、版本配置和运行清单。
- 若 runtime 允许跨 gateway 重启存活，其临时目录必须由 runtime unit 归属，不能放在 gateway 重启就被 systemd 删除的 `RuntimeDirectory` 中。大型缓存/下载明确使用配置的数据磁盘，不因“临时”二字默认放进 `/run` 的 tmpfs 而转为大量内存占用。
- 修改 `scripts/dev-backend.mjs`、开发脚本、Dockerfile/Compose 的旧 gateway 相关配置；默认裸启动 Go/Python/Vite，不悄悄 `compose up docker-gateway`。
- 修改 `scripts/dev-backend.mjs`、开发脚本、Dockerfile/Compose 的旧 gateway 相关配置；默认裸启动 Go/Python/Vite，不悄悄启动 Docker browser gateway。
- 删除 Docker browser wrapper、拉镜像/构建/网络/卷管理及相关测试、配置；PostgreSQL 等仍使用 Docker 的独立部署资产可保留，逐项说明，不做无关清理。
- `AGENTS.md`、README、部署说明、架构说明、E2E 文档全部对齐。删除旧入口，不保留“失败就回退 Docker”。
放行：验证文档全部必测项有证据；静态检查中浏览器链路没有 Docker 依赖；两节点局域网手工验收通过。
放行：验证文档全部适用项有证据；静态检查中浏览器链路没有 Docker 依赖；单节点局域网手工验收通过。多节点项记录为后续目标。
## 5. 改动定位与顺序约束
| 范围 | 主要定位 | 必须一起变化的内容 |
| --- | --- | --- |
| gateway 执行 | `cmd/docker_gateway/gateway.py`、`proxy.py`、CDP/平台模块及其测试 | 原生 runner、版本/端口/Profile、unit 生命周期、snapshot、代理恢复 |
| gateway 执行 | `cmd/browser_gateway/gateway.py`、`runtime.py`、`proxy.py`、CDP/平台模块及其测试 | 原生 runner、版本/端口/Profile、unit 生命周期、snapshot、代理恢复 |
| 控制面 lifecycle | `cmd/control-plane/hub.go`、`main.go`、hub tests | generation、owner、清理/心跳、多 gateway 错误隔离 |
| 采集与监听 | `creator.go`、`creator_events.go`、`internal/creator/source_lease.go`、`content.go` | 使用权、续租、独立收尾、事件边界与身份核对 |
| 素材 | `creator_material.go`、`internal/creator/material.go`、素材测试 | 临时目录、不可变发布、token、崩溃清理 |
| 数据模型 | `internal/hub/`、`internal/creator/` | 删除 Docker 字段，明确开发重建；业务结果与清理状态分离 |
| 前端 | 现有 gateway/环境/镜像/任务相关组件及 data provider | 对应契约、失败/禁用交互；不重做导航和视觉体系 |
| 部署/文档 | `scripts/`、`compose*.yaml`、Dockerfile、`docker/browser-wrapper/`、README、`docs/` | 原生安装和联调；旧路径移除；手工验收地址 |
| 部署/文档 | `scripts/`、`compose*.yaml`、Dockerfile、`deploy/`、README、`docs/` | 原生安装和联调；旧路径移除；手工验收地址 |
顺序限制：产物执行隔离先于孤儿文件清理；本地单任务闭环先于多机压测；所有权和代次先于通用自动清理；不能先删 Docker 实现再留下无法登录的中间交付。
@@ -151,9 +150,9 @@ React → Go control-plane（账号/任务/绑定/业务结果/素材发布）
- 每个非平凡行为改动先有会在旧实现下失败的测试；单元覆盖率至少 65%。Go 全量测试、vet、build，生命周期/并发相关变更跑 race；Python 非交互测试与覆盖率；前端从 lockfile 安装并测试、构建。
- 更改 Docker/Compose 文件执行 `docker compose config --quiet`；不默认构建/运行任何 Docker 镜像。旧基线测试需另行得到用户同意。
- 功能验收不使用浏览器自动化或批量 API 代替用户操作。提供 `0.0.0.0` 监听的本地环境和两台 gateway 地址，由用户按验证文档手工确认。
- 功能验收不使用浏览器自动化或批量 API 代替用户操作。提供 `0.0.0.0` 监听的本地环境和单节点 gateway 地址，由用户按验证文档手工确认。
- 资源观测、日志读取和单元测试可以自动执行，但不能因此将真实登录、采集、发送或多机故障验收标为通过。
- 本轮不会启动服务、重建数据库或删除遗留资源。实施完成后才启动可联调环境，并报告实测局域网地址。
- 本文不把服务启动、数据库重建或遗留资源删除当作自动交付动作；需要真实联调时按部署和验证文档由授权操作者启动，并报告当次局域网地址。
## 7. 切换与失败恢复
@@ -163,13 +162,13 @@ React → Go control-plane（账号/任务/绑定/业务结果/素材发布）
4. 如新环境验收失败，停止新任务、保留证据、修复再验。紧急恢复旧版只能是人工恢复到明确版本和匹配数据，须取得授权；不是运行时隐式回退。
5. 验收后，经授权回收旧浏览器容器/卷/网络与镜像。只删除确认属于旧 CreatorHub 浏览器的资源，禁止全机 `docker system prune` 或按相似名称批量删除。
## 8. 实施前批准清单
## 8. 实施与验收记录
- [ ] Linux/systemd 与原生指纹浏览器部署条件满足。
- [ ] 独立 runtime 跨 gateway 重启核对恢复、短任务有界存活策略获准。
- [ ] 账号 Profile 保留、采集独占/借用边界、无自动跨机迁移获准。
- [ ] API/schema/配置的破坏性变更及数据重建范围获准。
- [ ] 明确完整网页远程桌面是否另立需求，不能把 wrapper 内有 x11vnc 当已具备该功能。
- [ ] 验证参数、旧方式对照是否允许运行 Docker、实测性能放行标准获准。
- [x] Linux/systemd、Xvfb 与原生指纹浏览器部署条件满足；非 root gateway 已完成 smoke。
- [x] 独立 runtime 的 gateway 重启恢复和短任务有界清理已通过自动/真实 smoke；正式参数为租约 60 秒、续租 20 秒、清理 30 秒、恢复 60 秒。
- [x] 账号 Profile 保留、采集独占/借用边界、无自动跨机迁移已写入契约；同 Profile 真实并发仍需授权操作者手工验收。
- [x] API/schema/配置的破坏性开发切换范围已固定；不保留旧 Docker 浏览器兼容路径。
- [x] 完整网页远程桌面未作为本目标能力；需要时另立需求，不能把 gateway 的 Xvfb 误称为远程桌面。
- [x] 20 GB 磁盘下限、1 GB runtime 日志、20 GB Profile 缓存、并发 1/2 和 `0.0.0.0:8082` 已配置并记录。
在上述批准之前，这份文档只作为实施依据，不构成已经完成的改造。
自动检查结果见 [单节点验证记录](evidence/native-browser-verification-2026-09-18.md)。真实账号、代理、LAN 和破坏性资源用例仍须由授权操作者完成；未执行项不视为通过。