这份文档是给服务器上的 Codex 看的执行说明。目标是：在 Ubuntu 服务器部署当前 browser_api_proxy 项目，并额外提供一个“浏览器里可操作的远程桌面网页”，让用户可以直接在网页里完成 Flow / Doubao 账号登录。
收到任务后，先按这个顺序处理：
- 先读根目录
readme_for_ai.md - 再读
README.md - 先做部署与环境检查，不要一上来改代码
- 只有在确认现有结构无法完成目标时，才考虑改代码；改之前必须先征求用户同意
- 如果后续真的发生稳定功能改动，别忘了同步更新
readme_for_ai.md
- 在 Ubuntu 服务器上跑起当前项目
- 保留现有管理页
/ui/?tab=flow和/ui/?tab=doubao - 额外提供一个可以在浏览器里打开的远程桌面页面，让用户看到并操作服务器上的真实浏览器
- 用户点管理页里的“打开登录窗口”后，能在远程桌面页面里看到对应浏览器窗口，并手动完成登录
- 登录态只保存在服务器本地，不再依赖从 Windows 往 GitHub 同步缓存
- 当前项目自带的管理页只能调用后端接口，让服务器本地打开浏览器窗口
- 当前项目自带的管理页不能把服务器浏览器画面直接嵌进网页，也不能直接把鼠标键盘操作转发到服务器浏览器
- 所以，单独部署当前管理页还不够
- 要实现“用户在网页里直接操控登录”，必须额外加一层轻量远程桌面网页
推荐最小可行方案：
browser_api_proxy后端- 项目自带 React 管理页
- 一个轻量虚拟显示环境
- 一个轻量窗口管理器
- 一个 VNC 服务
- 一个 noVNC 网页入口
可接受的实现方向：
Xvfb+openbox+x11vnc+noVNC- 或者服务器环境里更容易落地的同类轻量组合
注意：
- 服务器只有
2 核 4G，优先轻量方案 - 不要上重型桌面环境，比如完整 GNOME / KDE，除非服务器现成已经有
- 不要为了这个任务重构业务代码
- 不要把这次目标理解成“只部署当前 React 管理页”
- 不要默认继续走“Windows 浏览器缓存 -> GitHub -> Ubuntu”这条链路
- 不要直接复用 Windows 里的
accounts.json - 不要把浏览器 profile 长期放进 Git 历史同步
- 不要前台阻塞等待长任务跑完，要后台启动并轮询检查
- 不要用假的登录成功或其他补丁绕过真实登录流程
- 当前账号注册表会记录 Windows 绝对路径，直接带到 Ubuntu 容易失效
- Chromium 持久化 profile 跨 Windows -> Linux 并不可靠
- 浏览器缓存二进制很多、变化碎，不适合长期进 Git 仓库
- 默认部署方案应当是：登录态在服务器本地生成并留在服务器本地
- 确认 Ubuntu 版本
- 确认是否有域名反代在用
- 确认当前开放端口、已有服务、磁盘空间、内存
- 确认是否能正常
apt/pip/npm下载；如果下载卡住，记得按用户偏好走代理
- 拉取当前仓库代码
- 创建并复用项目自己的 Python 虚拟环境
- 安装
requirements.txt - 安装 Playwright Chromium 到服务器本地目录
- 如果
web/dist/不存在，再进入web/执行前端依赖安装和构建 - 启动后端服务，但不要阻塞等待；要后台启动并轮询健康检查
健康检查至少验证：
/providers/flow/health/providers/doubao/health
- 让服务器自己生成本地
data/ - 让服务器自己生成本地浏览器 profile
- 不要默认从 Windows 拷贝
accounts.json - 不要默认从 GitHub 拉取 Windows 浏览器缓存来当正式方案
如果用户明确要求“先试着迁移旧缓存”：
- 把它当成可选实验，不是默认主方案
- 实验前先告诉用户这件事不稳定
目标效果：
- 用户用自己电脑打开一个网页
- 这个网页能显示服务器上的桌面 / 浏览器画面
- 用户能在网页里点、输、拖动，等同于在服务器浏览器上直接操作
实施要求：
- 选用轻量远程桌面网页方案
- 优先使用 noVNC 路线
- 远程桌面进程和后端都要后台运行
- 启动后要轮询检查端口或页面是否可访问，不能一直卡住等待
如果服务器已经有域名和反代：
- 暴露项目管理页入口
- 暴露远程桌面网页入口
如果暂时没有现成反代：
- 短期可先直接暴露端口验证
- 但上线前至少加一层访问保护
最低保护要求：
- 基本认证、独立密码、IP 白名单三者至少做一种
因为这里会直接暴露登录操作画面，不能裸奔公开。
联调时按下面顺序：
- 先打开远程桌面网页，确认能看到服务器桌面
- 再打开项目管理页
- 在 Flow 或 Doubao 账号卡片上点击“打开登录窗口”
- 回到远程桌面网页，确认服务器浏览器窗口已经出现
- 用户在远程桌面网页里手动完成登录、验证码、二次验证
- 回到管理页点击“检查登录”
- 确认
session/check状态变成ready
- 登录完成后，浏览器 profile 留在服务器本地
- 后续日常生成请求优先走无头模式以节省资源
- 但
session/init仍然是可见浏览器流程，所以远程桌面入口要保留 - 服务器规格较小，避免同时跑多个重浏览器任务
- 优先通过部署和运行环境解决问题，不要先改业务代码
- 如果必须改代码，先停下来征求用户同意
- 所有长任务都用后台方式启动，再轮询检查结果
- 读取文本文件时按 UTF-8 / GBK 容错，不要基于乱码下结论
- 安装依赖或下载资源时如果卡住，要检查并使用代理
- 不要使用 destructive git 命令
- 项目后端在 Ubuntu 服务器可正常启动
- 管理页可通过域名或端口访问
- 远程桌面网页可通过浏览器访问
- 点击“打开登录窗口”后，用户能在远程桌面网页里看到实际浏览器
- 用户能在网页里亲手完成 Flow 登录
- 用户能在网页里亲手完成 Doubao 登录
session/check能返回登录就绪- 服务重启后登录态仍然保留在服务器本地
- 管理页访问地址
- 远程桌面网页访问地址
- 后端健康检查地址
- 当前登录验证结果
- 是否已经配置开机自启
- 是否还存在需要用户亲自处理的验证码 / 二次验证步骤