rogee/creator-hub
1
0
Fork 0
Code Issues Pull Requests Actions 1 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-verification.md
+36 -35
View File
@@ -1,16 +1,17 @@
# 原生浏览器环境：验证与手工验收
> **当前状态：仅验证计划，下面所有功能、故障、性能用例均未执行。**
> 本轮未构建镜像、启动服务、操作真实账号、终止进程或删除数据。
> 方案：[变更评审](native-browser-change-review.md)；阶段：[实施计划](native-browser-implementation-plan.md)。
> **当前状态：单节点代码改造与自动检查通过；真实平台、代理、LAN 和资源验收仍须由授权操作者手工完成。**
> 已完成 native gateway、控制面契约、runtime-use lease、Compose/P4 文档和本地单元测试；本文件只记录可复现的验收步骤，不把测试替身当作真实平台证据。
> 方案：[变更评审](native-browser-change-review.md)；阶段：[实施计划](native-browser-implementation-plan.md)；当次记录：[单节点验证记录](evidence/native-browser-verification-2026-09-18.md)。
## 1. 验证边界
- 开发者负责单元/契约检查、构建和启动可联调环境；真实功能由用户手工验证，不使用浏览器自动化或脚本代点网页。
- 读取日志、目录占用、进程/端口和系统指标可以使用命令。自动测试中的替身只证明代码行为，不能证明平台登录、监听、发送或真实代理能力。
- 默认不构建/运行 Docker。旧方式对照、旧资源删除、故障注入必须单独取得用户同意。
- 默认不构建/运行 Docker；Compose 仅可作为 PostgreSQL 独立依赖。旧方式对照、资源删除和故障注入必须单独取得用户同意。
- 测试专用账号、Profile、gateway、数据目录及出口；不能强杀用户正在使用的长期账号或清空全机 Docker 资源。
- 任何结果使用“未执行 / 通过 / 失败 / 阻塞”，不得把文档中的期望填成实际结果。
- 若被测 Chrome 由用户的 `chrome.service` 管理，验证只能通过其已开放的 CDP 连接执行只读/交互检查，不得停止、启动、替换或接管该实例；这类结果不能替代 native gateway 的 runtime 生命周期、控制面持久化和资源清理验收。
## 2. 前置条件和记录表
@@ -19,21 +20,21 @@
| 项目 | 必填记录 |
| --- | --- |
| 软件基线 | Git 提交、未提交改动清单、Go/Python/Node/systemd/Xvfb/浏览器版本 |
| 机器 | 控制面 C、gateway A、gateway B 的稳定节点 ID、IP、CPU、内存、磁盘、发行版 |
| 机器 | 单节点控制面 C 与 native gateway G 的稳定节点 ID、IP、CPU、内存、磁盘、发行版 |
| 账号 | 专用采集账号、自有监听账号；预期平台 UID，勿记录密码/Cookie |
| 浏览器 | 原生发行物来源、许可证、校验值、支持的指纹参数和 sandbox 证据；A02 普通升级的已安装源版本/目标版本 |
| 路径 | 各机器 Profile 根目录、runtime 根目录、运行清单、日志、控制面素材目录 |
| 网络 | A/B 各节点的 HTTP/HTTPS/SOCKS4/SOCKS5 测试出口、协议支持的认证配置、预期出口 IP、CDP 可用情况；只记录配置标识，不记录密码 |
| 网络 | 单节点的 HTTP/HTTPS/SOCKS4/SOCKS5 测试出口、协议支持的认证配置、预期出口 IP、CDP 可用情况；只记录配置标识，不记录密码 |
| 操作许可 | 是否允许旧 Docker 对照、普通浏览器升级、gateway/控制面重启、任务取消、磁盘故障和测试数据删除；C02/D04 自动响应的测试策略、可控互动/接收账号及授权范围，A10 人工发送另行逐次确认 |
| 时限 | task 最大执行时间、续租间隔/过期时间、清理预算 `T_cleanup`、恢复预算 `T_recover` |
| 资源预算 | 并发数、最低可用磁盘、日志上限；启动 p50/p95 和总内存目标，Profile 缓存预算 |
| 时限 | task 最大执行时间、续租间隔 20 秒、租约 60 秒、清理预算 30 秒、恢复预算 60 秒 |
| 资源预算 | 并发数 1/2、最低可用磁盘 20 GB、日志上限 1 GB；启动 p50/p95 和总内存目标，Profile 缓存预算 20 GB |
| 证据位置 | 独立于 runtime 清理目录的本地证据目录，不提交账号敏感数据 |
建议首轮使用并发 1 和 2、短任务正常清理预算 30 秒、服务恢复预算 60 秒；这些是待批准的测试参数，不是已实现默认配置。复杂平台采集的最大时长单独确定，不能因为清理预算而强行截断正常业务。
首轮使用并发 1 和 2、短任务正常清理预算 30 秒、服务恢复预算 60 秒。复杂平台采集的最大时长单独确定，不能因为清理预算而强行截断正常业务。
## 3. 开发者检查命令
以下是**实施完成后的命令**，不是本轮执行记录。gateway 重命名为 `cmd/browser_gateway/` 后才使用该路径；最终脚本需与实际交付一致，不允许测试目录为空仍算通过。
以下命令是交付检查命令；执行结果另记在证据文件，不把未运行的命令当作通过。
### Go
@@ -53,10 +54,10 @@ go tool cover -func=/tmp/creatorhub-go.cover
```bash
python3 -m venv .venv-gateway
.venv-gateway/bin/python -m pip install -r requirements-gateway-dev.lock
.venv-gateway/bin/python -m unittest discover -s cmd/browser_gateway -p 'test_*.py'
.venv-gateway/bin/python -m unittest discover -s cmd/browser_gateway -t cmd -p 'test_*.py'
.venv-gateway/bin/python -m coverage erase
.venv-gateway/bin/python -m coverage run --source=cmd/browser_gateway \
-m unittest discover -s cmd/browser_gateway -p 'test_*.py'
.venv-gateway/bin/python -m coverage run --source=cmd/browser_gateway --branch \
-m unittest discover -s cmd/browser_gateway -t cmd -p 'test_*.py'
.venv-gateway/bin/python -m coverage report --omit='*/test_*.py' --fail-under=65
```
@@ -79,22 +80,22 @@ npm --prefix web run build
docker compose config --quiet
```
仅在改动 Docker/Compose 时做配置校验，不执行 build/up；有保留的独立开发 Compose 文件时也逐份验证。另行检查浏览器 runtime 路径已无 DockerClient/socket、容器/镜像/卷/网络创建、容器 wrapper 入口、旧 image 字段和“原生失败回退 Docker”；PostgreSQL 的独立部署配置不算漏删。
仅在改动 Compose 时做配置校验，不执行 build/up；保留的 PostgreSQL 开发 Compose 文件也逐份验证。另行检查浏览器 runtime 路径已无 DockerClient/socket、容器/镜像/卷/网络创建、容器 wrapper 入口、旧 image 字段和“原生失败回退 Docker”；PostgreSQL 的独立部署配置不算漏删。
## 4. 联调启动与访问
### 当前可确认的设置
### 已交付设置
- Go 使用 `LISTEN_ADDR`；联调须设置 `0.0.0.0:8082`。
- Vite 当前 `/api` 代理到 `127.0.0.1:8082`，端口 5173。Vite 必须加 `--host 0.0.0.0`，不能只给 localhost 地址。
- Python gateway 使用 `LISTEN_ADDR`，多机控制测试可采用各节点 `0.0.0.0:8081`；现有凭据约束保持不变。
- 当前 `scripts/dev-backend.mjs` 会启动 Compose 依赖，因此在 P4 替换之前，**不能把现有 `pnpm dev` 当作已支持原生 gateway 的命令。**
- native Python gateway 使用 `LISTEN_ADDR=0.0.0.0:8081`，由非 root systemd user service 运行；稳定 `node_id` 从配置或主机身份加载。
- `scripts/dev-backend.mjs` 只启动 PostgreSQL 并检查 `NATIVE_GATEWAY_ENDPOINT`，不会启动浏览器容器。
### 实施完成后
### 单节点执行步骤
1. 按最终交付的原生安装说明，在 A/B 安装同一已确认浏览器、Xvfb 和 gateway 用户服务。服务名建议固定为 `creatorhub-gateway.service`；它目前尚未交付。
1. 按部署说明在单节点安装已确认浏览器、Xvfb 和 `creatorhub-browser-gateway.service`。
2. 使用已有、经验证的 PostgreSQL 与凭据配置。不要重新生成现有主密钥；不要把秘密值粘贴到验收报告。
3. 按交付脚本启动 A/B 的原生 gateway；在控制面登记真实 A/B 地址，并核对返回的节点身份。
3. 按交付脚本启动单节点 native gateway；在控制面登记真实地址，并核对 `/v1/info` 返回的稳定节点身份。
4. 启动控制面及前端：
```bash
@@ -104,9 +105,9 @@ LISTEN_ADDR=0.0.0.0:8082 go run ./cmd/control-plane
npm --prefix web run dev -- --host 0.0.0.0
```
命令启动后，用 `ip -brief -4 addr` 记录当次实际局域网 IP。用户在另一台设备访问 `http://<C-IP>:5173`；开发者可查看 `http://<C-IP>:8082/healthz`。报告列出 A/B 的实际 Endpoint。
命令启动后，用 `ip -brief -4 addr` 记录当次实际局域网 IP。用户在另一台设备访问 `http://<C-IP>:5173`；开发者可查看 `http://<C-IP>:8082/healthz`。报告列出单节点 gateway 的实际 Endpoint。
本轮宿主机曾观察到 `10.1.1.104`，只可作为候选地址，**没有服务已启动的含义**；实施当天重新核实，不预先宣称该地址可用。
历史观察到的地址不构成可用性证据；实施当天必须重新核实 IP、监听地址和防火墙。
## 5. 手工功能与清理矩阵
@@ -116,7 +117,7 @@ npm --prefix web run dev -- --host 0.0.0.0
| ID | 手工步骤 | 通过条件 |
| --- | --- | --- |
| A01 | 在无 Docker daemon/socket 可用的测试节点创建账号环境，选择原生版本，启动 | 正确 Xvfb/浏览器就绪；未登录时可进入人工登录，不永久停在“正在启动”；无镜像下载、容器、卷、Docker 网络操作 |
| A01 | 在 gateway 节点确认 Docker daemon/socket 不参与运行，创建账号环境，选择已安装 native 版本并启动 | 正确 Xvfb/浏览器就绪；未登录时可进入人工登录，不永久停在“正在启动”；无镜像下载、容器、卷或 Docker 浏览器网络操作 |
| A02 | 人工完成二维码登录，记录账号、Profile 标识和指纹；先关闭再启动，再停止并从界面普通升级至另一已安装且获准的版本后启动 | 两个子项均保持原 Profile、指纹和登录身份，无意外重新登录；升级后实际浏览器版本等于所选目标版本，不通过重建环境/重新登录冒充保持（AC-E1） |
| A03 | 浏览器停止时，从界面启动一次竞品账号采集，等待结束 | 自动创建任务 runtime，结果保存；`T_cleanup` 内进程、display、端口和临时文件释放 |
| A04 | 连续采集作品/评论/线索，再打开结果查看 | 数据完整且仍可读；不能因 runtime 清理丢失业务结果或已发布素材 |
@@ -127,9 +128,9 @@ npm --prefix web run dev -- --host 0.0.0.0
| A09 | 按下方代理矩阵分别配置四类代理及其支持的认证配置，改变代理或账号绑定后启动采集 | 每个配置下实际浏览器出口、代理版本、指纹时区/语言等正确；身份不符时拒绝动作；不能用单一无认证代理的成功代替其他配置（AC-E3） |
| A10 | 仅在用户准备真实接收账号并逐次确认时验证人工回复/私信 | 保持原有确认与身份核对；重复结果不触发重复发送，不确定状态不冒充成功 |
A02 验证的是原生环境内的普通版本升级，不是首次 Docker 切换或 Profile 迁移；缺少获准版本时标为阻塞。
A02 验证的是 native 环境内的普通版本升级，不是 Profile 迁移；缺少获准版本时标为阻塞。
代理矩阵适用于 A09/B03/D05：A/B 每台节点分别列出 HTTP、HTTPS、SOCKS4、SOCKS5，按协议允许的配置验证无认证（如支持）及支持的认证方式；A09/D05 记录成功与实际浏览器出口，B03 记录认证失败（适用时）与网络失败，均不得静默直连或轮换出口。协议本身不支持的认证项说明依据，不作为通过项；缺少测试代理、凭据或尚未实现的承诺能力标为阻塞，不能免测。证据不得包含密码/Cookie。
代理矩阵适用于 A09/B03：单节点分别列出 HTTP、HTTPS、SOCKS4、SOCKS5，按协议允许的配置验证无认证（如支持）及支持的认证方式；A09 记录成功与实际浏览器出口，B03 记录认证失败（适用时）与网络失败，均不得静默直连或轮换出口。协议本身不支持的认证项说明依据，不作为通过项；缺少测试代理、凭据或尚未实现的承诺能力标为阻塞，不能免测。证据不得包含密码/Cookie。
A10 不能由脚本自动发送，也不能因为只修改 runtime 就免除必要回归；人工逐次确认不能代替 C02/D04 的自动策略验收。
@@ -139,7 +140,7 @@ A10 不能由脚本自动发送，也不能因为只修改 runtime 就免除必
| --- | --- | --- |
| B01 | 任务运行中点击取消 | 业务不永久 running；独立清理继续，`T_cleanup` 内完成或明确待清理 |
| B02 | 让测试任务超过已批准最大时长 | 超时可见；lease 释放，任务进程/目录回收，不能继续后台写入 |
| B03 | 按代理矩阵逐节点、逐协议分别制造认证失败（协议支持时）和网络失败；另测无效浏览器依赖启动 | 每个适用子项明确失败，无静默直连或出口轮换；已创建的 Xvfb/端口/临时目录逆序回收（AC-E3） |
| B03 | 按代理矩阵逐协议分别制造认证失败（协议支持时）和网络失败；另测无效浏览器路径启动 | 每个适用子项明确失败，无静默直连或出口轮换；已创建的 Xvfb/端口/临时目录逆序回收（AC-E3） |
| B04 | 经授权终止该测试 runtime 的浏览器，另测 Xvfb 退出 | 任务失败可见；其余子进程终止；其他 runtime 不受影响 |
| B05 | 对测试专用目录制造无法删除条件后结束任务 | 显示“业务结果 + 清理失败”，保留可追溯记录；恢复条件后重试只清资源，不重跑业务 |
| B06 | 测试磁盘低于启动阈值；用隔离测试盘验证写满 | 启动前拒绝或运行中明确失败；不删除登录资料/正式素材腾空间；收尾状态可靠 |
@@ -169,16 +170,16 @@ C02/D04 必测恢复子项：
C05/B09 的精确竞态先用确定性单元测试证明；真机无法可重复制造时标记该子项未执行，不能用“人工未复现”替代回归测试。测试不得添加面向生产的任意执行接口。
### D. 多机控制
### D. 多机控制（后续目标，全部未执行）
| ID | 步骤 | 通过条件 |
| --- | --- | --- |
| D01 | A/B 各创建合法唯一环境，分别启动；停止/清理一侧并观察另一侧 | 按稳定节点和代次执行，不误清另一机器；节点间资源 ID 碰撞另用契约测试覆盖，不为测试放松名称唯一性 |
| D02 | A 失联，B 正常采集/续租/监听 | B 不被 A 的超时拖住；A 显示不可达，不把 A 的账号迁到 B |
| D03 | A 仍有 Profile、运行实例或待清理资源时，尝试把登记地址改成 B | 明确阻止改变机器归属；旧 cleanup 目标仍是 A |
| D04 | A 恢复，旧停止响应/事件迟到，期间已有新代次；按 C02 恢复子项核对既有自动响应与冷却记录 | 旧响应不能关闭/污染新实例；事件和身份边界重新确认；原 UID 冷却保留，重复旧事件及迟到事件不触发额外动作，B 的记录与正常监听不受影响（AC-A9、AC-B1） |
| D05 | A/B 配置不同出口，按代理矩阵逐节点检查四类代理及支持的认证配置下目标浏览器的实际出网 | 各适用配置均有对应 gateway 的浏览器出口证据，不能只显示控制面测得 IP；失败子项与 B03 对照，无直连或轮换（AC-E3） |
| D06 | B 未安装账号指定浏览器版本 | 明确显示不可用，不自动换普通 Chromium、其他版本或另一节点 |
| D01 | 后续目标：两台节点各创建合法唯一环境，分别启动；停止/清理一侧并观察另一侧 | 本目标不执行；保留稳定节点和代数字段，后续目标按契约验收 |
| D02 | 后续目标：一台节点失联，另一台正常采集/续租/监听 | 本目标不执行；不得以单节点重启替代跨机证据 |
| D03 | 后续目标：带 Profile、运行实例或待清理资源时改变机器归属 | 本目标不执行；不得删除原节点资源 |
| D04 | 后续目标：跨节点恢复时旧响应/事件迟到且已有新代次 | 本目标不执行；单节点旧代次保护由 C07 和自动测试覆盖 |
| D05 | 后续目标：多节点配置不同出口并按代理矩阵核验 | 本目标不执行；单节点代理适用项在 A09/B03 验收 |
| D06 | 后续目标：另一节点未安装账号指定浏览器版本 | 本目标不执行；单节点版本缺失在 A01/B03 验收 |
抖音先完成全部适用用例；小红书按相同生命周期复验。尚未实现的平台能力记为阻塞，不用 Mock、轮询或另一平台成功代替。
@@ -187,10 +188,10 @@ C05/B09 的精确竞态先用确定性单元测试证明；真机无法可重复
### 6.1 测量方法
1. 固定机器、浏览器版本、指纹、账号、代理、任务内容、并发和依赖状态；除生命周期方式外尽量保持一致。不要拿不同浏览器或不同网络的结果相减。
2. 冷启动指本次机器/服务启动后的第一次浏览器启动，和后续热启动分开记录；不擅自全机清理 page cache。安装、镜像拉取或下载浏览器耗时另列，不混入日常任务启动。
2. 冷启动指本次机器/服务启动后的第一次浏览器启动，和后续热启动分开记录；不擅自全机清理 page cache。安装或下载浏览器耗时另列，不混入日常任务启动。
3. 每种方式在并发 1 下至少 20 次有效启动，并在并发 2 下至少 10 组。按相同节奏执行，遵守平台限制。遇验证码/限流单独记录，不删去异常后只展示好看的数值。
4. 时间从用户启动请求被接收到 CDP+代理+账号就绪；另外记录完整任务、终止到资源清理完成耗时。不能只测进程创建或 Xvfb 启动时间。
5. 内存统计整个 runtime 的浏览器子进程、Xvfb、可选桌面，以及 gateway 增量；旧方案同样统计完整进程树及 Docker/代理相关增量。优先使用 cgroup 峰值或一致口径的 PSS；RSS 合计会重复计算共享页，必须注明。
5. 内存统计整个 runtime 的浏览器子进程、Xvfb、可选桌面，以及 gateway 增量；如有获准的旧基线，旧方案也必须按完整进程树和代理增量的同一口径统计。优先使用 cgroup 峰值或一致口径的 PSS；RSS 合计会重复计算共享页，必须注明。
6. 记录每轮之前、业务结束、清理完成三个时刻：活跃进程/unit、端口、runtime/Profile/日志/素材字节数。使用 `ps`、`ss`、`systemctl show`、`du -sb` 等只读工具；共享内存和 X socket 也须核对。
7. 原生路径连续完成至少 30 个短任务，覆盖取消和失败；再观察一轮长期监听与采集并行。平台受限时可用明确标识的本地测试页面单独测生命周期，但不得拿它替代真实平台功能验收。