creator-hub/docs/native-browser-implementation-plan.md

原生浏览器环境：评审后的实施计划

状态：待批准实施。仅文档，本轮未修改业务代码、数据库或运行环境。 依据：变更评审、业务基线。验收：验证文档。

1. 完成定义

满足以下条件才算完成改造，而不是“可以启动 Chromium”就结束：

• 各 gateway 不访问 Docker socket，不创建浏览器容器、镜像层、卷或网络；每个 runtime 在本机运行 Xvfb 与指定版本浏览器。
• 通过现有控制面管理至少两台机器；账号、运行代次、代理、Profile 与实际节点一致，不自动跨机重建。
• 采集任务可按需启停；任务自建进程和临时文件在所有终态回收。清理失败真实可见并可重试。
• 持久登录、Profile、稳定指纹及账号身份在重启和普通浏览器升级后保持；二维码登录、采集结果及逐次确认的人工发送不退化（A02、A10；AC-E1）。
• gateway、控制面重启及监听重连不清除自动响应的事件去重、基线或 UID 冷却；旧事件不重放，迟到事件默认只记录、不自动补发（C02、D04；AC-A9、AC-B1）。
• HTTP、HTTPS、SOCKS4、SOCKS5 及协议支持的认证配置逐项验证实际浏览器出口、认证失败和网络失败，失败不得直连（A09、B03、D05；AC-E3）。
• 控制面本机的素材临时文件同样受执行归属和清理约束；旧任务不能覆盖新产物。
• 旧 Docker 浏览器路径彻底删除；构建/测试达标，局域网环境可供用户手工验收，资源对比有实际记录。

2. 保持简单的目标结构

React → Go control-plane（账号/任务/绑定/业务结果/素材发布）
                   ├─ gateway A（已有节点登记与路由）
                   │   ├─ 预安装浏览器版本（所有任务共用只读二进制）
                   │   ├─ 账号 A 的持久 Profile
                   │   └─ runtime generation：Xvfb + 浏览器 + 临时目录
                   └─ gateway B（同样结构，独立本地资源）

• 继续使用 Go 控制面、Python gateway、PostgreSQL 与现有 CDP/WebSocket。
• 用 Linux/systemd transient unit 管理每个运行实例；gateway 使用 Python 标准库调用明确的进程管理操作。固定的 runner 仅启动 Xvfb、浏览器和批准的桌面组件，不是可执行任意命令的接口。
• 一 runtime 一 Xvfb，按需启动，不设浏览器池、不预热空闲实例。
• 不为 Docker/原生模式保留可切换后端。实施分支可以暂时有未发布的中间步骤，但交付只保留原生路径。
• 先完成“单机账号登录 → 抖音采集 → 资源释放”最小完整流程，再扩展为多机与全部业务回归。

3. 必要数据和接口变化

以下为契约变更提案，不是已存在的新字段/API。P0 批准后才能实施。

概念	变更	约束
gateway	保留节点登记、显示名称与 Endpoint；新增持久稳定节点身份/能力	仍有关联资源时不得把旧节点改指新机器；无自动迁移
browser version	删除镜像拉取/构建语义，改为预安装浏览器版本及可用状态	每台 gateway 核对实际版本、指纹参数与路径；缺失时明确报错
environment	保留稳定账号环境、指纹与绑定；版本字段去除 image 语义	环境定义不等于正在运行的浏览器，元数据创建不应提前占用进程
runtime	用节点身份 + environment + generation 代替 container/network ID	状态、清理、事件和代理绑定均核对代次；不能只用 PID
profile	原 Docker volume 改为 gateway 依据内部 ID 生成的持久目录	单 Profile 独占打开；任何任务请求都不能指定任意删除路径
task use/lease	复用现有任务与 lease 表/模式，增加 runtime 使用目的、所有权和期限	source lease 不等于 runtime lease；长任务须续租，暂停等待不提前分配浏览器
cleanup	业务状态与 cleanup 状态分别记录，并保存资源 owner 与最后错误	成功且待清理不等于业务失败；不得借清理重试重复采集/发送
material artifact	每次执行独有临时目录与不可变产物路径，DB 按执行 token 发布引用	发布结果未知时查询事实后再删；清理不能删除已被正式引用的文件
gateway create/delete	保留显式创建、启动、停止、回收动作，替换 Docker 载荷	重复创建使用同一 generation；响应丢失时查询同代次，不能直接换 ID 重开

状态与错误语义

• 区分浏览器就绪与账号可执行：CDP/页面就绪后即可进入人工登录；未登录时显示待登录，而不是永久“正在启动”。只有代理和实际账号身份确认后才允许采集/写操作；身份不一致立即拒绝写操作。
• gateway 不可达、响应丢失、写入结果不确定时，记录未知/待核对，不自动重试平台写操作。
• 明确区分校验失败、Profile 占用/代次冲突、节点/依赖不可用与服务内部错误。P0 列出当前状态码及预期变化并批准；不在实现中悄悄改为 200。
• 删除已经不存在的同代次资源应可重复执行；针对旧代次的删除不得作用于新实例。
• 去除 container_id、Docker 网络及 image 字段会影响 API、UI 和测试。采用受控的破坏性开发切换，不增加兼容字段、双写或迁移回填。
• 数据重建不等于可以删除用户 Profile/素材。实际删除与重新登录名单须在执行前取得授权。

4. 阶段与放行条件

P0：前置条件和变更契约（不改业务行为）

交付：

1. 确认当前未提交工作由谁负责，将基线固定到可复现提交；在干净、明确基线之上新建实施分支，不擅自 stash/reset 用户改动。
2. 核实两台 Linux 机器的 systemd、用户服务、Xvfb、字体、浏览器依赖、sandbox、可用磁盘；取得合法原生指纹浏览器并固定版本，指定用于 A02 普通升级验证的源版本与目标版本。
3. 记录旧方式性能/磁盘基线。默认不运行 Docker；如无历史可信数据，需要用户另行批准旧方式对照运行。
4. 列出受影响状态码、载荷、字段、配置和移除项，批准第三节契约。明确 gateway 重启后受管 runtime 的恢复行为。
5. 固定验证参数：任务最长时间、清理时间预算、任务使用权续租/过期时间、磁盘下限、并发数、日志保留及资源对比指标。

放行：没有原生浏览器、必要指纹参数不被支持、sandbox 无法启用、没有批准破坏性契约时，停在此阶段并给出明确缺口；不得偷偷切到普通 Chromium、--no-sandbox 或旧 Docker。

P1：gateway 原生生命周期（与 P2 组成第一个端到端切片）

先写失败测试，再实现：

• 提取并保留现有与 Docker 无关的代理、CDP、页面动作；将 gateway 包和测试从 Docker 命名改为浏览器领域命名，建议目标路径 cmd/browser_gateway/。
• 原生启动输入校验在创建目录/进程之前完成：节点、环境、代次、浏览器版本、Profile、代理绑定及必要资源容量。
• 创建前落盘运行意图；用 runtime 专属 unit/临时目录启动 Xvfb 和浏览器，分配不冲突的 display 与端口。Profile 独占不能只靠控制面内存锁。
• 默认不继承 --no-sandbox；浏览器与 gateway 以非 root 身份运行。具体 sandbox 模式由目标二进制/发行版证明。
• 创建失败逆序回收已经创建的资源；停止为有界的优雅退出、OS 终止与目录清理。
• 短任务有自我终止上限，runtime 独立于 gateway 进程存活但不永久失管；长期会话在 gateway 重启后核对 unit/目录/代理与代次，不随意接管别的 CDP。
• gateway snapshot/health 返回实际 runtime 与待清理信息；“进程在”不能冒充浏览器可用。

最小检查：创建/就绪/停止、部分启动失败、并发分配、Profile 冲突、重复清理、旧代次删除、gateway 重启识别、未知资源拒绝删除；四类代理及支持的认证配置分别覆盖连接成功、认证失败和网络失败，不直连。实际浏览器证据按 A09/B03/D05 另行手工验收。

放行：单节点不需要 Docker daemon/socket 可完成真实人工登录和停止再开，账号仍保持登录；gateway 单元覆盖率至少 65%。

P2：控制面连接原生 runtime（首个可用闭环）

先测试控制面与 gateway 的成功、校验、失败、冲突、响应丢失路径，再改：

• hub.go 的创建、启动、停止、状态核对和 cleanup-pending 改用 generation/owner；删除容器和网络代次依赖。
• internal/hub/store.go、相关查询与 schema 改为原生版本/运行模型；开发数据库受控重建，不回填旧容器字段。
• 继续复用既有多 gateway 登记、路由和心跳；核对稳定机器身份。节点 Endpoint 的更换不能改写既存 cleanup 的目的地。
• 代理服务不再依赖 Docker IP/网络，仍保留代理绑定代次和失败可见性；从目标 gateway 的实际浏览器路径验证出口。
• 登录二维码、账号身份快照、恢复事件订阅全部使用新 runtime 身份；不能随运行代次变化清空业务事件去重、基线和已占用 UID 冷却。先用确定性测试覆盖重启/重连、冷却内新事件、冷却到期旧事件及迟到事件不补发；真实平台按 C02/D04 验收。
• 接入停止后的普通浏览器版本升级，复用原 Profile 与稳定指纹；启动后核对实际版本及账号身份，不通过新建环境或重置账号资料实现升级。
• 同阶段交付首个闭环所需的 Refine data provider 适配、已安装版本选择/普通升级、登录、显式启停与采集入口；环境页区分定义与运行状态，任务页分别展示业务结果、清理状态和明确错误，不只写日志。覆盖节点不可达、版本缺失、Profile 占用、待清理及禁用状态的交互测试，不推迟至 P4。
• 本阶段即接入最小任务归属：仅对空闲专用采集账号申请独占使用权，自动创建、执行并用独立有界上下文回收；创建前登记资源 owner，正常/失败都释放。借入长期会话、多任务续租和素材崩溃恢复在 P3 完成，不以无归属的临时启动代码作为中间方案。
• 一台 gateway 的不可达不能阻塞其他节点的续租/状态更新；在现有机制上做有界隔离，不增加第二套 scheduler。

放行：一台 gateway 上从界面完成“手工登录 → 按需采集一个指定账号 → 正确存储结果 → 释放本任务 runtime/临时文件 → 再次启动无需重新登录”。停止、清理及失败状态从界面可见；按 A02 验证普通升级后实际版本切换且 Profile、指纹、登录身份保持。新运行身份下自动响应去重/冷却的确定性回归检查通过；C02/D04 的真实平台恢复与多机证据在 P4 最终放行前补齐，不能用代码检查标记手工用例通过。

P3：采集任务和素材的完整资源归属

这是本次磁盘问题的根本修复，不只做 finally：

1. 任务分配在实际执行前申请使用权，标明任务自建 runtime 或借入已有会话。优先使用专用采集账号；Profile 被监听/人工登录占用时明确等待或冲突，不抢占。
2. 对 source/素材执行 lease 续租，执行 token 覆盖写结果、发布产物和清理。旧 lease 到期的执行不得提交/覆盖新执行结果。
3. 成功、失败、取消、超时均走独立有界清理上下文；取消后的业务收尾同样不能用已取消 context，避免永久 running。
4. 控制面与每台 gateway 各清理自己创建的文件。任务临时资源登记不使用跨机任意路径删除接口。
5. 素材写本次执行独有的目录；结果不可变发布与 DB token 检查构成同一业务提交边界。先防止旧执行覆盖新文件，再增加孤儿文件清理。
6. 业务完成和 cleanup 完成分别保存。失败记录有错误、次数和下次重试；周期核对只处理本节点受管残留，不按文件年龄扫整个目录。
7. 缓存尽可能落到 runtime 目录；持久 Profile 离线清理经过版本验证的缓存白名单。诊断日志有明确上限；正式素材不属于临时清理。
8. 活跃监听/人工会话与任务页面分别持有使用权。最后一个短任务退出可以结束其自建 runtime，但不能结束仍有合法长期持有者的 runtime；不引入无限空闲复用池。

最小检查：所有业务终态、采集超十分钟仍有效续租、旧 token 迟到、数据库提交结果未知、控制面强杀、gateway 强杀、磁盘满、删除失败、两任务同 Profile、监听与采集并行、另一机器同名环境。

放行：每种终态均有资源前后清单；正式素材/登录信息不受影响；残留可解释且有界，失败不隐瞒。

P4：界面、部署与清理旧路径

• 在 P2 已可用的版本选择/普通升级、启停及任务状态界面上，完成浏览器版本管理与各节点可用情况展示；移除无效的镜像拉取、构建、容器/网络操作。
• 扩展 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。
• 删除 Docker browser wrapper、拉镜像/构建/网络/卷管理及相关测试、配置；PostgreSQL 等仍使用 Docker 的独立部署资产可保留，逐项说明，不做无关清理。
• AGENTS.md、README、部署说明、架构说明、E2E 文档全部对齐。删除旧入口，不保留“失败就回退 Docker”。

放行：验证文档全部必测项有证据；静态检查中浏览器链路没有 Docker 依赖；两节点局域网手工验收通过。

5. 改动定位与顺序约束

范围	主要定位	必须一起变化的内容
gateway 执行	cmd/docker_gateway/gateway.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/	原生安装和联调；旧路径移除；手工验收地址

顺序限制：产物执行隔离先于孤儿文件清理；本地单任务闭环先于多机压测；所有权和代次先于通用自动清理；不能先删 Docker 实现再留下无法登录的中间交付。

6. 验证及交付方式

• 每个非平凡行为改动先有会在旧实现下失败的测试；单元覆盖率至少 65%。Go 全量测试、vet、build，生命周期/并发相关变更跑 race；Python 非交互测试与覆盖率；前端从 lockfile 安装并测试、构建。
• 更改 Docker/Compose 文件执行 docker compose config --quiet；不默认构建/运行任何 Docker 镜像。旧基线测试需另行得到用户同意。
• 功能验收不使用浏览器自动化或批量 API 代替用户操作。提供 0.0.0.0 监听的本地环境和两台 gateway 地址，由用户按验证文档手工确认。
• 资源观测、日志读取和单元测试可以自动执行，但不能因此将真实登录、采集、发送或多机故障验收标为通过。
• 本轮不会启动服务、重建数据库或删除遗留资源。实施完成后才启动可联调环境，并报告实测局域网地址。

7. 切换与失败恢复

1. 经用户确认冻结旧运行、记录账号/节点/版本与需要保留的资料。旧 Docker 卷、用户 Profile、数据库及素材都不能未经授权删除。
2. 原生环境使用全新开发数据可重新登录；不在应用里实现旧 Docker Profile 迁移或双读。若要求保留既有登录，单独确认一次性受控操作及浏览器版本一致性。
3. 停止旧浏览器执行后才能启用新路径，不能让同账号新旧环境同时工作。
4. 如新环境验收失败，停止新任务、保留证据、修复再验。紧急恢复旧版只能是人工恢复到明确版本和匹配数据，须取得授权；不是运行时隐式回退。
5. 验收后，经授权回收旧浏览器容器/卷/网络与镜像。只删除确认属于旧 CreatorHub 浏览器的资源，禁止全机 docker system prune 或按相似名称批量删除。

8. 实施前批准清单

• Linux/systemd 与原生指纹浏览器部署条件满足。
• 独立 runtime 跨 gateway 重启核对恢复、短任务有界存活策略获准。
• 账号 Profile 保留、采集独占/借用边界、无自动跨机迁移获准。
• API/schema/配置的破坏性变更及数据重建范围获准。
• 明确完整网页远程桌面是否另立需求，不能把 wrapper 内有 x11vnc 当已具备该功能。
• 验证参数、旧方式对照是否允许运行 Docker、实测性能放行标准获准。

在上述批准之前，这份文档只作为实施依据，不构成已经完成的改造。