UHD_Media_Tool/docs/runbook/browser.md

浏览器(camofox)与原站视图运行手册

对应 REQ v0.7 §4.4、§4.7.1–4.7.4;合同与 camofox OpenAPI 对照见 docs/design/browser-provider.md。 代码:packages/adapters/src/browser/**(适配器)、apps/server/src/modules/browser/**(会话/接管/能力)、 apps/web/app/components/browser/**(原站视图)。

当前状态:已对真实 camofox-browser v1.17.0(jo-inc,commit 389c996)容器逐项核验(§7),十项能力全部通过; 探测到其它版本 / fork 时一律显示"未核验",需按 §6 重新核验。

1. 浏览器服务从哪来

1.1 部署自带(缺省)

docker compose up -d 同时起 camofox 服务(docker-compose.yml,只在内网、不映射端口,卷 umt-camofox)。 app 的 BROWSER_PROVIDER_URL 缺省 http://camofox:9377,启动后第一次用到浏览器时登记为 camofox-env (browser_provider.config.managedBy = "env",访问凭据取 BROWSER_ACCESS_KEY / CAMOFOX_ACCESS_KEY,只在进程内,不入库), 并在后台探测一次能力。地址与凭据只能改部署配置;设置页只能改它的启用。

# .env(部署目录)
CAMOFOX_ACCESS_KEY=$(openssl rand -hex 24)     # camofox 与 app 共用
docker compose --env-file .env.deploy up -d --build
docker compose ps camofox                       # healthy 即可

上游不发布镜像。compose 缺省用的是浏览器桌面镜像 umt-browser-desktop:1.17.0(docker/browser-desktop,§8), 它从纯截图镜像 camofox-browser:1.17.0 复制 camofox,所以先构建旧镜像:docker/camofox/Dockerfile 从 git tag v1.17.0 构建(修了上游 Dockerfile 的两个问题,见文件头)。首次构建要从 GitHub 拉源码与约 630 MB 的 Camoufox 浏览器包:

git clone --depth 1 --branch v1.17.0 https://github.com/jo-inc/camofox-browser.git /tmp/camofox-src
docker build -t camofox-browser:1.17.0 --build-arg APT_MIRROR=mirrors.ustc.edu.cn \
  --build-context upstream=/tmp/camofox-src docker/camofox
# 走宿主代理时加 --network host --build-arg https_proxy=http://127.0.0.1:7890 --build-arg http_proxy=...
docker compose build camofox                    # 再构建桌面镜像(或 docker build -t umt-browser-desktop:1.17.0 docker/browser-desktop)

只要截图模式(不要桌面、省约 400 MB 常驻内存与 3 GB 磁盘):.env 里 CAMOFOX_IMAGE=camofox-browser:1.17.0,同一个卷,登录状态通用。

1.2 接自有实例

.env 里 BROWSER_PROVIDER_URL=http://<host>:9377、BROWSER_ACCESS_KEY=<它的 CAMOFOX_ACCESS_KEY>、CAMOFOX_REPLICAS=0 (不再起自带容器)。或者不设环境变量,在 设置 → 站点默认 → 浏览器服务 里"添加浏览器服务":名称、服务地址、访问凭据 (加密存凭证库,只写不回显)、启用。自有实例的版本不是 1.17.0 时能力一律显示"未核验"。

1.3 不用浏览器

CAMOFOX_REPLICAS=0 + BROWSER_ENABLED=false:camofox-env 停用,原站视图显示"没有启用的浏览器服务"。

1.4 设置页与 API

设置 → 站点默认 → 浏览器服务:列表(地址、来源、凭据是否设置、启用、健康、核验)、测试连通(探测 /health 与 /openapi.json,凭据错误显示"访问凭据不对")、编辑、删除(有未关闭会话时拒绝;camofox-env 只能停用); 点行打开的抽屉里是逐项能力表(不可用 / 未核验 / 已核验 + 说明)。

端点	说明
GET /browser/providers[?probe=true]	列表;probe=true 探测全部启用的服务并写回
POST /browser/providers	登记 {name, baseUrl, accessKey?, enabled?};camofox-env 名称保留
PATCH /browser/providers/{id}	{baseUrl?, accessKey?(null 清除), enabled?}
POST /browser/providers/{id}/probe	测试连通(停用的也可以测)
DELETE /browser/providers/{id}	删除

browser_provider.config 可调项(都可省略):

键	缺省	作用
verified	{}	逐项覆盖核验结果,如 {"takeover": false};缺省取适配器内置的真机核验表(§7,按上游版本);探测永远不会把它置 true
navigationTimeoutMs	30000	单次导航超时
maxRetries	2	导航只重试超时 / 网络 / 5xx / 503;401、白名单、控制权冲突不重试
snapshotMaxBytes	524288	快照文本上限(超出截断并标 truncated)
requestTimeoutMs	30000	其它请求超时

站点域名白名单 = 站点 base_url 的主机(含子域)+ site.config.browserDomains(字符串数组,给跳转到独立下载域的站点用)。 站点限流与快照 / 实时搜索共用同一个限流器(导航、开标签页、历史导航取令牌)。

2. 会话与控制权

• 会话按站点 / 账号隔离:profileKey = umt-site-<siteId>-acct-<accountId|anon>,同时作为 camofox userId (上游的登录状态隔离单元);browser_session.id 作 camofox sessionKey。同一 provider + profile 至多一个未关闭会话。
• 数据库为准:服务重启后按 browser_session / browser_tab 恢复适配器内存,needsSnapshot 置 true,旧元素引用全部作废。 上游回收的标签页(404 / 410)对账标 lost;整个会话的标签页都没了(camofox 重启、空闲回收)时自动重连,见 §10。
• 控制者:automation(Agent/任务)→ human(人工接管)→ automation 或 waiting;closed 终态。

事件	结果
接管 POST /browser/sessions/{id}/control/acquire	先把适配器控制者切到 human(新的自动化输入立即被拒),等该 profile 上进行中的请求收尾,再写 browser_control_lease(缺省 30 分钟)
他人已接管	409
交还 .../control/release	租约 released;会话回 automation(或 to: "waiting");needsSnapshot = true;待处理事项关闭
租约到期未交还	租约 expired,会话转 waiting(lease_expired),不自动从未知页面继续
Agent 快照看到验证码 / 二次认证 / Cloudflare 挑战	会话转 waiting(captcha / challenge),生成待处理事项(kind other,subject browser_session)
Agent browser.interact action=request_human	同上,原因 agent_request
站点停用 / 浏览器服务停用	下一次访问时会话关闭(site_disabled / provider_disabled)

HTTP 输入类端点(navigate / click / type / scroll / select / 开关标签页 / 带 target 的 download)只接受持有自己人工租约的调用者; 快照、截图、会话详情随时可读。Agent 看截图走 browser.screenshot(§3.1),敏感截图默认不进模型。

3. Agent 能力

能力	类别	说明
browser.snapshot	read	结构化快照(已脱敏);sessionId 或 siteId;清掉 needsSnapshot
browser.navigate	execute(admin)	站点域名内;没有会话时按站点打开
browser.interact	execute(admin)	click / type / select / scroll / press / request_human;登录字段用 credential 由服务端注入
browser.download	execute(organize.execute)	捕获下载 → 暂存 → 解析种子、匹配本地资源;不提交,提交用 download.plan / download.submit

execute 类需要持续授权(automation_grant)或审批。元素引用只来自最近一次快照:导航、点击、按键提交、控制权交接、 服务重启之后,旧的 eN 报 409 元素引用已失效…先重新读取页面。

3.1 视觉自动化(VIS-1)

截图作为图片交给视觉模型 → 模型给出截图上的坐标 → 服务端换算到页面并操作 → 再截图,循环。用于登录表单、勾选框 / 滑块 / 点选类挑战等快照引用够不着的页面;对应 REQ v0.7 §4.4、§10。代码:apps/server/src/modules/browser/{service,capabilities}.ts (截图、坐标、证据)、apps/server/src/modules/agent/challenge.ts(有界子流程)、packages/adapters/src/browser/image.ts(缩放编码)。

能力	类别	说明
browser.screenshot	read	截图缩到 ≤1280 像素宽(缺省 JPEG 质量 70),以 image content 交给模型;同时登记"模型坐标系"并写证据缩略图
browser.click_at	execute	{sessionId, x, y, button?}:坐标 = 最近一张截图的像素;只支持左键;返回点击后的新截图
browser.type_at	execute	{sessionId, x?, y?, text, pressEnter?}:先点再输(不给坐标 = 输入到当前焦点);账号密码仍用 browser.interact 的 credential
browser.scroll	execute	{sessionId, dx, dy} 像素,返回新截图
browser.wait	read	{sessionId, ms ≤ 5000},返回等待后的新截图
browser.solve_challenge	execute	{sessionId, goal, success, maxSteps ≤ 12, budget}:有界视觉子流程,见下

• 上游必须支持图片输入:按上游模型的 input 是否含 image 判定(内置 provider 的目录自带;自定义 openai-compatible 端点目前按纯文本处理)。 不支持时截图不发送,能力改给已脱敏的文字快照并提示;solve_challenge 直接判定需人工。fake 上游按支持图片处理。
• 坐标系:服务端对每次截图读页面视口与 DPR(evaluate),页面 CSS 像素 = 截图像素 × 视口宽 / 截图宽; 输出的 coordinates 记录截图尺寸、原始尺寸、视口、DPR(取不到时 assumed = true,按原图、DPR 1)。动作之后旧坐标系作废, 必须用新截图的坐标。点击(CF-2 起)先走 umt 插件的 POST /umt/tabs/{id}/mouse-click——Playwright page.mouse.click 发真实鼠标事件, 跨域 iframe 里的控件(Cloudflare Turnstile)和画布也点得到;插件没有这个端点(旧镜像、纯截图镜像)时退回 1.17.0 的做法: elementFromPoint 打标记再按选择器点(跨域 iframe / 画布点不到具体位置)。
• 动作前提:会话在自动化控制下(人工接管 / 等待处理中一律拒绝),当前页面主机在站点域名白名单内。
• 敏感截图:登录页地址、页面上有密码框、地址带凭据 → sensitive = true,默认不交给模型(不做像素遮蔽),改给已脱敏的文字快照; 要交给模型需要 automation_grant.action = browser.sensitive_screenshot(或 *)的持续授权,且调用时传 allowSensitive: true。
• 二次验证 / 短信 / 本人设备确认:截图时读页面文字、快照时读快照文本,命中即把会话转等待处理(原因 two_factor), 之后的自动化动作全部被拒;系统提示也要求模型立即停止。视觉子流程不能接手 two_factor 等待。
• 证据:每次截图(含动作后的截图)写 480 像素宽的 JPEG 缩略图到 DATA_DIR/tmp/evidence/<id>.jpg(0600,7 天后清理); 能力输出只给引用 evidence/<id>.jpg,随工具结果摘要进 agent_run_event。图片数据不进 JSON 文本、不进操作账本。
• 授权:click_at / type_at / scroll / solve_challenge 由 browser.interact 的持续授权覆盖(也可单独授权); 父会话白名单里有 browser.solve_challenge 即覆盖子流程用到的截图与坐标能力;授权同理,solve_challenge 通过授权后,子流程(spawn_reason = browser.solve_challenge)内的坐标动作不再单独要持续授权。坐标动作按调用区分幂等键,崩溃恢复不重放。
• 交给模型的截图参数可在 browser_provider.config 调:screenshotMaxWidth(≤1280)、screenshotFormat(jpeg / png)、 screenshotQuality(20–95)。

browser.solve_challenge 流程:

1. 会话须在自动化控制下,或因 captcha / challenge / challenge_unsolved 在等待处理(收回自动化控制,原待处理事项保留); 其它等待原因(二次验证、租约过期、Agent 请求人工)与人工接管中一律拒绝。
2. 在调用进程里起一个子 agent_run(父会话 = 调用它的 Agent 运行,spawn_reason = browser.solve_challenge; 上游与父会话相同;白名单只有截图 / 坐标点击 / 输入 / 滚动 / 等待 / browser.snapshot),一步 = 一次工具调用, maxSteps 即工具调用上限;token / 费用 / 时长按 budget(时长缺省 180 秒),用量计入父会话。
3. 子流程结束后服务端按 success(urlContains / urlChanged / textPresent / textAbsent,全部满足)读页面核实, 不信模型自述。结果:solved(关闭原待处理事项)/ needs_human(二次验证、模型最后一行写 NEEDS_HUMAN: 原因、上游不支持图片)/ exhausted(步数或预算用尽)/ failed。
4. 没成功:会话转等待处理(two_factor 或 challenge_unsolved),待处理事项的 evidence.challenge 附最近 12 张证据截图引用与子运行 ID, 返回 takeover.path = /console/sites/<siteId>?tab=origin(原站视图接管入口)。不自动重试;人可以再次调用或接管处理。

不承诺通过 Cloudflare 等挑战(REQ §4.4):上游浏览器指纹与点击方式都可能被识别,失败按上面第 4 步转人工。

4. 下载产物

• 暂存:DATA_DIR/tmp/browser-downloads/<artifactId>.bin(目录 0700、文件 0600),超过 24 小时的在下一次捕获时清理。 合同里只出现引用(bytes.ref),来源地址去掉 passkey。
• 核验:bencode 解析、infohash v1/v2、私有标记;按 source_release.infohash_v1/v2,再按下载地址 id 参数匹配本站资源。
• 提交:HTTP POST /browser/sessions/{id}/download 带 submit 时转调 POST /acquisition-plans(同一鉴权、计划、去重、 缓存阈值、授权检查);被拒时产物照常返回,note 写拒绝原因。同一会话同一 sha256 第二次捕获标 duplicate,不再提交。
• 浏览器没有媒体库写权限;提交链路下载的是站点适配器取到的种子,暂存文件只作核验证据。

5. 排障

现象	查
原站视图"没有启用的浏览器服务"	browser_provider 是否有 enabled = true 且 kind = 'camofox' 的行
412"浏览器服务认证失败" / camofox 401	访问凭据与 CAMOFOX_ACCESS_KEY 是否一致;GET /browser/providers?probe=true
502 浏览器服务不可用	camofox /health(503 = 恢复中);容器日志
409 先接管会话再操作	界面点"接管";或租约已被他人持有 / 已过期
"连接中断"	截图请求失败;看 API 日志 component: browser 的方法 / 路径 / 状态(日志不含正文与凭据)
测试连通提示"访问凭据不对"	/health 免认证所以能连上,但 /openapi.json 401:BROWSER_ACCESS_KEY 与 camofox 的 CAMOFOX_ACCESS_KEY 不一致
原站视图"浏览器已重启，正在重新连接…"	camofox 重启 / 会话空闲回收后的自动重连(§10),正常几秒内恢复
503 browser_reconnect_failed / "浏览器连接已断开"	自动重连失败,消息里是原因(camofox 没起来、POST /tabs 5xx 等);docker compose ps camofox、容器日志;恢复后点"重新连接"
409"标签页已被浏览器服务回收"	只在显式指定了已被回收的 tabId 时出现(会话里还有别的标签页活着);不指定 tabId 重试即可
重启 camofox 后要重新登录	容器是被 SIGKILL / OOM 杀掉的(docker inspect 看 OOMKilled、退出码 137):只有 SIGTERM 正常停止、会话空闲回收、关闭会话时才落盘登录状态;加大 CAMOFOX_MEM_LIMIT
设置页显示"未核验"	探测到的上游版本不在核验表里(不是 1.17.0,或 fork);按 §6 核验后在适配器 CAMOFOX_VERIFIED_RELEASES 加一行,或临时写 config.verified

6. 真实实例核验清单(REQ §4.7.4)

先固定 camofox-browser 的仓库、版本(/openapi.json 的 info.version)、启动方式与认证配置,记在本节末尾。 通过的能力登记进适配器的真机核验表 CAMOFOX_VERIFIED_RELEASES(packages/adapters/src/browser/camofox/capabilities.ts, 按上游版本,只在探测到完全相同的版本时生效,并把 verified_at 写成核验日期);个别部署要撤销某项写 browser_provider.config.verified = {"<键>": false}。不通过的保持 false,界面继续标"未核验"。 不得用另一个浏览器窗口代替后宣称通过。

自动化核验脚本:scripts/browser-verify/run.sh(临时栈 umtbr:postgres 127.0.0.1:55447、camofox 127.0.0.1:49377、 compose 网络里的 mock NexusPHP 站 mocknexus:8080;服务层在宿主进程里装配,与生产同一套代码; 阶段之间重启 / SIGKILL camofox;结果写 .browser-verify-out/results-*.json 与截图)。跑完 docker compose -p umtbr down -v。

#	项目	做法	通过标准	对应 verified 键
1	登录保持	观众 / 馒头 / HHClub / CHD 各一账号:原站视图接管登录;闲置超过 SESSION_TIMEOUT_MS 后再 browser.snapshot	不需重新登录;过期时落到登录页、loginRequired = true,而不是空列表	sessions、persistentProfile
2	截图 / 结构化快照	列表页、详情页、登录页各取 screenshot 与 snapshot	截图格式(JSON base64 还是 image/*)、尺寸与坐标一致;快照 eN 引用可点;密码框值、Cookie、passkey 不出现;大页面 offset 分页正确	screenshot、snapshot
3	列表 / 详情提取	快照 + POST /extract(属性带 x-ref)与现有 HTTP 适配器结果对比	标题、分类、副标题、促销、做种一致,原始字段不丢	extract
4	文件下载捕获	详情页点"下载"后 POST /browser/sessions/{id}/download	GET /tabs/{id}/downloads 的字段形状(filename / data / size / status)与适配器兼容;sha256 与直接 HTTP 下载一致;进暂存核验,不直写媒体库	downloadCapture
5	重启后会话	分别触发 BROWSER_IDLE_TIMEOUT_MS 回收与强制重启 camofox 容器	持久化 profile 恢复登录;旧 tabId 识别为 lost,不重放旧引用	persistentProfile、tabs
6	人与 Agent 同标签页连续操作	Agent 打开详情页 → 原站视图接管,在同一标签页点击、输入 → 交还 → Agent 重新 snapshot	人看到的是同一会话同一页面;交还后 Agent 读到人工操作后的状态;下载不重复提交	takeover、interact

核验记录:

日期	仓库 / fork	版本	启动方式 / 认证	通过项	备注
2026-09-28	jo-inc/camofox-browser	v1.17.0(389c996),Camoufox 152.0.4-beta.28	docker/camofox/Dockerfile + compose;CAMOFOX_ACCESS_KEY Bearer	十项全部	mock NexusPHP 站 + example.com;四个真实站点未测,见 §7

7. 真机核验(版本 1.17.0)

环境:camofox-browser:1.17.0 容器(本机构建,镜像 3.6 GB,空闲内存约 200 MB,打开 2 个会话后约 390 MB), CAMOFOX_ACCESS_KEY 已设置,SESSION_TIMEOUT_MS=60000、BROWSER_IDLE_TIMEOUT_MS=30000(空闲回收阶段用短超时); 目标页:testkit mock NexusPHP(观众风格,mocknexus:8080,与 camofox 同一 compose 网络)与公开静态页 https://example.com/。 浏览器服务经环境变量登记为 camofox-env。每项的原始输出见 scripts/browser-verify/run.sh 的结果文件。

#	项目	结果	实际观测
0	认证 / 探测	通过	无 Bearer 请求 401;/openapi.json info.version = 1.17.0,十项能力的端点都在
1	登录保持	通过	新 profile 打开 torrents.php → 302 到 login.php?returnto=…,loginRequired = true;人工接管登录后 Agent 直接打开受保护列表页,不再登录(站点 takelogin 只收到 1 次);Agent 用服务端凭证注入登录第二个账号也通过,快照与返回值里没有密码
2	截图 / 结构化快照	通过(修了遮蔽)	截图直接返回 image/png 二进制(不是 OpenAPI 写的 JSON base64),视口随指纹变化(实测 1433×1145、1691×867),截图像素 = 点击坐标;登录页 modelSafe = false。快照是 Playwright ARIA 格式(- textbox [e2]: 值,引用写作 [eN]),密码框与普通文本框同形且带明文值,原有按标签名的遮蔽规则抓不到 → 已修(见下);列表页 45 个引用、8.6 KB,未触发分页
3	列表 / 详情提取	通过	列表页快照含 fixture 的标题、副标题、大小、做种数(5 条中 4 条标题完整出现,1 条是站点截断显示);POST /extract 按 x-ref 取回标题;详情页取回下载链接文字。与 HTTP 适配器同源 fixture 对照,未逐字段比对促销标记
4	下载捕获	通过(修了字段名)	Agent 点详情页 .torrent 链接 → downloads 返回 {id, url, suggestedFilename, mimeType, bytes, createdAt, failure, dataBase64};sha256 与直接 HTTP 下载一致(9fcf61f7…),infohash 与站点一致并匹配到本地资源,约 2 秒;consume=true 后不再返回同一文件
5	重启后会话	通过(修了 3 处),有已知限制	SIGTERM 重启:旧标签页返回 410 browser_restarted(不是 404)→ 已按 lost 处理;登录状态恢复,Agent 再次导航在同一会话开新标签页(约 1.3 秒,含浏览器冷启动)。会话空闲回收(60 秒 + 上游 60 秒扫描周期):旧标签页 404 → lost,重新打开仍登录(约 0.4 秒)。SIGKILL:上次落盘之后的新登录丢失(需重新登录),这是上游落盘时机决定的(只在会话空闲回收、关闭、SIGTERM 停止时写),界面照常识别为登录页
6	人与 Agent 同标签页	通过(修了坐标点击与焦点输入)	Agent 打开登录页(上游 tabId T)→ 接管:自动化输入被拒(409)、只读快照允许 → 截图坐标点击用户名框 → 焦点输入 → 点密码框 → 输入 → 回车 → 交还;交还前的旧引用 e1 被拒("先重新读取页面");Agent 重新读取,仍是 tabId T,看到人工登录后的页面。后退 / 前进 / 刷新 / 滚动也在同一标签页通过。核验走原站视图调用的同一组 HTTP 端点,没有在浏览器里点原站视图界面

对接中发现并已修的差异:

1. 截图格式:1.17.0 直接返回 image/png;适配器原本两种都兼容,无需改。
2. 坐标点击:POST /click 只认 ref / selector,不接受 {x, y} → 适配器先 POST /evaluate 用 elementFromPoint 给该点元素打 data-umt-pt 标记,再按属性选择器点击(仍走上游的完整鼠标事件序列与下载守卫)。坐标处没有元素报 400。
3. 焦点输入:POST /type 缺省 mode=fill 必须带 ref/selector → 无目标时发 mode=keyboard;回车用 /press。
4. 密码框遮蔽:快照里出现带值的输入框时,经 evaluate 取页面上 input[type=password] 的当前值按字面量遮蔽; evaluate 失败时遮蔽全部输入框的值。extract 结果同样处理。
5. 下载字段:suggestedFilename、bytes(大小)、dataBase64、dataSkipped(超 maxBytes)、failure。
6. 410:浏览器重启后 5 分钟内旧标签页返回 410,与 404 同样按"标签页已不存在"对账为 lost;Agent 下一次导航在同一会话开新标签页。
7. 上游镜像:① v1.17.0 的 Dockerfile 在 npm ci 前没复制 postinstall.js,构建必然失败;② CMD sh -c "node …" 不转发 SIGTERM,docker stop/restart 等满宽限期后 SIGKILL,关机落盘不执行,重启后登录全丢(修前实测)。 docker/camofox/Dockerfile 两处都改了(exec node)。
8. 其它:关掉上游缺省开启的崩溃报告外发(CAMOFOX_CRASH_REPORT_ENABLED=false)与每次启动从 addons.mozilla.org 下载 uBlock(CAMOFOX_DISABLE_DEFAULT_ADDONS=true,内网下载失败会拖慢启动)。

userId(umt-site-<uuid>-acct-<uuid>,约 90 字符)上游原样使用(持久化目录按 SHA-256 取名),无字符限制问题; DELETE /tabs/{id} 的 userId query / body 都认;DELETE /sessions/{userId} 关闭该 profile 全部标签页并落盘。

视觉自动化(VIS-1,2026-09-29,scripts/browser-verify/vision-real.ts,只读使用现有 umt-camofox-1):打开 https://example.com/, 截图 image/png 1920×992(本次指纹的视口 1920×992、DPR 1;此前两次观测到 1600×819、1433×1145,视口随指纹变化), 缩成 1280×661 JPEG 交给模型;在缩放图上取"Learn more"链接中心 (640, 343),按服务端换算得页面 (960, 515), 与 getBoundingClientRect 的中心 (960.0, 514.8) 一致;点击后跳到 https://www.iana.org/help/example-domains,通过。 另:1.17.0 的 POST /click 在 OpenAPI 里写了 coordinates: {x, y},实测仍报 ref or selector required,坐标点击继续走 elementFromPoint。

没有核验的:四个真实站点(观众 / 馒头 / HHClub / CHD)的登录保持、Cloudflare / 验证码挑战、真实站点页面上的提取对比; 并发 1 / 2 / 4 会话的性能与资源;原站视图界面本身在浏览器里的点击体验(1.5 秒截图刷新);VNC 插件(镜像已装,未启用、未接入)。

8. 原站视图桌面模式(Selkies 远程桌面,WT-1)

方案与取舍见 docs/design/webtop-remote-browser.md。桌面镜像 = linuxserver baseimage-selkies:debiantrixie(Webtop 4.0 的底座, pixelflux + labwc Wayland 桌面 + Selkies 2.0 Web 客户端)+ camofox 1.17.0 有头运行(CAMOFOX_INTERACTIVE=desktop, MOZ_ENABLE_WAYLAND=1)。原站视图里看到的窗口就是 Agent 经 camofox API 驱动的同一个 Firefox 进程:Agent 导航,画面跟着变; 人在画面里点,Agent 下一次快照读到的就是点过之后的页面。

8.1 组成

部件	位置	说明
镜像	docker/browser-desktop/Dockerfile	底座按 digest 锁定;从 camofox-browser:1.17.0 复制 node、/app、Camoufox;补 fonts-noto-cjk-extra;可选 fcitx5(拼音 + mozc,--build-arg WITH_FCITX5=0 不装)
启动	root/etc/s6-overlay/s6-rc.d/svc-camofox	s6 服务,等 labwc 的 wayland-0 出现后以 abc 身份 exec node server.js;依赖 svc-de 与 svc-dbus(Firefox 连着 D-Bus,dbus 先停会把浏览器带走,关机落盘失败)
初始化	init-umt-desktop	由 CAMOFOX_ACCESS_KEY 派生 Selkies 控制 / 只读口令;覆盖 labwc autostart;把 /root/.camofox 交给 abc
反代	apps/server/src/modules/desktop	/api/v1/browser/desktop/{sessionId}/* → 容器 :3000(静态客户端 + api/websockets);只接受控制台会话
前端	apps/web/app/components/browser/desktop-view.tsx	原站视图 Tab:桌面可用且是安全上下文 → 桌面模式;否则截图模式并说明原因;可手动切换
自愈(INT-3 / FIX-5)	同上	打开桌面先调一次幂等 POST /browser/sessions/{id}/reconnect(iframe 直连 Selkies 不触发被动重连),等它返回后才加载桌面 iframe(期间显示「正在确认浏览器会话…」,FIX-5 起不再先连上黑屏);画面 5 秒未加载或视频流未出帧 → 每个会话自动重连一次并重建桌面连接,之后靠「重新连接」按钮
HTTPS	compose caddy(profile tls)+ docker/browser-desktop/Caddyfile	可选;已有反代终结 TLS 时不用

窗口:无标题栏、最大化铺满 1280×900(BROWSER_DESKTOP_WIDTH/HEIGHT),HARDEN_DESKTOP 去掉终端 / sudo / xdg-open, HARDEN_OPENBOX 去掉关闭按钮与右键 / 中键菜单、禁 Alt+F4 等。音频、麦克风、摄像头、手柄、文件传输、打印、命令、共享全部关闭并锁定, 剪贴板只允许文本。

8.2 鉴权与输入权限

• Selkies 端口(3000/8082)不映射到宿主,唯一入口是 app 的反代;外部 API Key 与 DEV key 一律 403。
• 口令不经浏览器:app 按请求者身份在上游请求上注入 Authorization: Basic。持有该会话 active 人工租约的本人 → 控制口令; 其他人(包括未接管的本人)→ 只读口令,Selkies 服务端丢弃只读连接的键鼠与剪贴板输入。
• 口令 = HMAC-SHA256(CAMOFOX_ACCESS_KEY, "umt-desktop/control" | "umt-desktop/view") 前 48 位 hex,app 与容器各算一遍; 没设 CAMOFOX_ACCESS_KEY 时容器用随机口令,桌面模式不可用(界面回退截图模式)。
• WebSocket 每 3 秒复查一次角色:交还 / 租约过期 / 被他人接管 / 控制台会话失效时服务端主动断开,Selkies 客户端自动重连并按新口令认证 (实测交还后 5 秒内点击已无效)。WebSocket 还要求 Origin 与 Host 同源(cookie 会话 + WS 无 CORS)。
• 反代响应带 Content-Security-Policy: frame-ancestors 'self' 与 X-Frame-Options: SAMEORIGIN,只能被本站 iframe 嵌入; 上游的 WWW-Authenticate 不外露(否则浏览器弹 Basic 登录框)。
• 只支持环境变量登记的 camofox-env(compose 自带容器);桌面地址缺省由 BROWSER_PROVIDER_URL 推出(端口换 3000), 或显式 BROWSER_DESKTOP_URL。

8.3 界面

原站视图 Tab 调 GET /api/v1/browser/desktop/{sessionId}/_status 决定模式:available(容器 3000 能连上且有访问凭据) 且 window.isSecureContext → 桌面模式(iframe);否则截图模式,顶部写原因:"桌面模式不可用:…" 或 "桌面模式需要通过 HTTPS 访问控制台"。 桌面模式顶栏:连接状态(已连接,只读 / 可操作)、当前控制者、接管 / 交还(沿用 control/acquire|release)、重新连接、截图模式、关闭会话。 「当前控制」(HH-2,两种模式共用 coords.ts controllerLabel):controller = automation 且 2 分钟内有过自动化动作(Agent 能力经 BrowserService.run 成功执行,写 recovery_state.lastAutomationAt,会话视图字段 lastAutomationAt)才显示「Agent」,说明写 「Agent 正在操作」;否则显示「自动化」,说明写「目前没有 Agent 在操作」。人工接管显示「人工接管(用户名)」,人工动作不刷新该时间。 接管后直接在画面里点和输入;中文、日文用本机输入法(Selkies 接收 composition 事件,按 Unicode 注入上屏文本); 复制粘贴用 Ctrl+C / Ctrl+V。

8.4 HTTPS

WebCodecs 视频解码与剪贴板 API 只在安全上下文(HTTPS 或 localhost)可用;用 IP / 局域网主机名经 HTTP 访问时只能用截图模式。

# 已有反代(nginx / Caddy / Traefik)终结 TLS:无需改动,WebSocket 需透传 Upgrade、读超时 ≥ 1 小时、不缓冲
# 没有反代:启用 compose 自带 Caddy
docker compose --profile tls up -d                # 自签:Caddy 内部 CA 按访问的主机名现场签发,浏览器需放行或导入根证书
docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./umt-root.crt   # 导入到客户端受信任根
# 有公网域名:.env 里 TLS_DOMAIN=media.example.com、[email protected](ACME,80/443 需可达)

TLS_PORT(缺省 443)、TLS_BIND 可改;4380 仍可直连(截图模式)。

8.5 回退

• 桌面容器起不来 / 桌面异常:.env 设 CAMOFOX_IMAGE=camofox-browser:1.17.0 后 docker compose up -d camofox,原站视图自动回到截图模式, Agent 能力不受影响(实测同一个卷,切换前后登录状态都在)。
• 只关桌面、保留镜像:不设 CAMOFOX_ACCESS_KEY 即可(桌面口令随机,app 探测为不可用)。
• 容器内输入法(本机输入法不可用时的备选):BROWSER_DESKTOP_IME=fcitx5,Ctrl+Space 切换;与本机输入法同时开会重复组字,缺省关闭。

8.6 原型核验(2026-09-29,临时栈 umtwt)

环境:本机 96 核、无 GPU(pixelflux 软件渲染 + CPU H.264);客户端 headless Chromium 145(Playwright),经 Caddy 自签 HTTPS; 上游 camofox 1.17.0 / Camoufox 152.0.4-beta.28,Selkies 2.0.0,labwc 0.8.3。脚本 apps/web/test/screenshots/webtop/{p0,verify}.mjs(截图不进 git)。

#	项	结果	观测
1	同会话	通过	camofox API 导航 example.com → iana,桌面画面同步;在桌面里点链接,API 快照 URL 变为 iana.org/domains/reserved,tabId 不变
2	中日文显示	通过	zh / ja 维基首页正文、标题栏、地址栏无豆腐块(Camoufox 自带 Noto CJK)
3	本机输入法	通过	CDP Input.imeSetComposition + insertText 模拟组字:搜索框得到「流浪地球」「進撃の巨人」(camofox evaluate 读回)
4	剪贴板	通过	本机 → 远端:写本机剪贴板,焦点回到画面后 Ctrl+V 粘贴中日文;远端 → 本机:远端 Ctrl+C 后本机 readText 读回中文
5	只读口令	通过	未接管时在画面点链接,URL 不变;接管后同一坐标点击生效;API 交还后 5 秒内再点无效
6	重启保持	通过(修了 1 处)	docker compose restart camofox 后 httpbin cookie 仍在。修前 dbus 与 camofox 并行停止,Firefox 先退出导致关机落盘失败
7	HTTP 回退	通过	经 HTTP 访问显示"桌面模式需要通过 HTTPS 访问控制台",截图模式正常;旧镜像下显示"浏览器服务没有桌面…"
8	资源	见右	容器内存:1 会话无人观看约 570–670 MB,观看约 610 MB,滚动维基首页约 730 MB;CPU:无人观看 0.3%(不编码),观看静止页 1–7%,持续滚动约 75–100%(约 1 核)
9	镜像	—	umt-browser-desktop:1.17.0 解压 6.9 GB / 压缩 2.0 GB(旧镜像 3.6 GB / 1.1 GB)

已知问题与未做:

• Firefox 工具栏里有 Playwright 的 "JUGGLER" 标识;用户可在画面里打开 about:addons、新标签页、输入任意网址——越界防护 (policies.json、context.route 白名单、交还时核对 URL,方案 §6)未做。
• 接管期间 camofox 看不到 API 请求:桌面连接期间与人工接管期间由 app 定期保活(§12,AG-4),不再被空闲回收; 浏览器里的心跳插件(方案 §5.5)不做。
• 一个桌面承载所有站点会话:持有 A 站租约的人在画面里能看到 / 操作切到前台的其它窗口;目前同一时刻一般只有一个会话窗口。
• 真实输入法(Windows 微软拼音、macOS 日文)、Firefox / Safari 客户端、真实 PT 站点未测;容器内 fcitx5 只验证能启动,未验证组字。
• 画面坐标与 camofox 截图坐标不同(桌面含 56 px 工具栏,Camoufox 伪装了 screenX / outerHeight),Agent 视觉操作继续用 camofox 截图。

9. 凭据统一:站点账号登录态 ⇄ 浏览器(BR-2)

一处管理凭据:站点账号里的 Cookie(手填,或账密自动登录得到的会话 Cookie)在打开浏览器会话时注入该站点 / 账号的 profile; 人在浏览器里登录后,登录态读回站点账号,HTTP 抓取、RSS、快照下一次就用新的。截图模式与桌面模式是同一个 camofox 进程,共用。 代码:sources-identity/service/credentials.ts(单一读写入口)、modules/browser/service.ts(prepareCookies / syncCookies)、 packages/adapters/src/browser/{cookies.ts,camofox/client.ts}、camofox 插件 docker/browser-desktop/root/opt/camofox/plugins/umt-cookies。

9.1 注入做法

camofox 1.17.0 只有 POST /sessions/:userId/cookies(导入),而且要另一个口令 CAMOFOX_API_KEY;没有读取端点。 所以桌面镜像带一个最小插件 umt-cookies(Dockerfile 把它加进 camofox.config.json 的插件清单),在访问凭据 (CAMOFOX_ACCESS_KEY)之下提供:

端点	说明
POST /umt/sessions/{userId}/cookies {cookies}	context.addCookies,并触发持久化插件立即落盘(与上游导入端点相同)
GET /umt/sessions/{userId}/cookies?urls=a,b	作用于这些地址的 Cookie:会话活着读 context.cookies(urls),否则读 profile 落盘文件
GET /umt/instance	{instanceId, startedAt}:插件加载时生成,camofox 进程重启即变(BR-3 重启检测,§10)
GET /umt/identity	固定浏览器身份的公开部分(UA / OS / 版本,BR-4,§11.1)
PUT /umt/sessions/{userId}/proxy {proxy}	该 profile 的出口:{server, username?, password?} 或 null 直连(BR-4,§11.5)
POST /umt/tabs/{tabId}/mouse-click {userId, x, y}	按视口坐标发真实鼠标事件(page.mouse.click,CF-2,§13);标签页不在回 422

适配器先走插件;插件不在(404)再试上游导入端点(CAMOFOX_API_KEY 与访问凭据相同时可用,只能写不能读);都不行 → 会话照常打开, credential.status = unsupported 并说明。profile 落盘在 /root/.camofox/profiles/<sha256(userId) 前 32 位>/storage-state.json (Playwright storageState:cookies + localStorage;sessionStorage 不保存,IndexedDB 缺省不保存),桌面镜像里目录 0700、文件 0600 (svc-camofox 设 umask 077,init-umt-desktop 对旧卷 chmod -R go-rwx)。改了镜像,需重建 umt-browser-desktop 后生效 (docker compose build camofox && docker compose up -d camofox);纯截图镜像 camofox-browser:1.17.0 不带插件,注入 / 回写都显示不支持。

打开会话(POST /browser/sessions、Agent browser.navigate 首次打开)时:

1. 匿名会话、API Key 类站点 / 账号(馒头:网页登录态与 API Key 无关)→ 不注入,not_applicable;
2. 取账号 Cookie:用户填的 + 自动登录得到的会话 Cookie,同名以会话 Cookie 为准;账密账号还没有会话 Cookie → 先走一次 refresh-login;
3. Cookie 头串转成站点主机的 host-only Cookie(路径 /,https 站点标 secure,期限 30 天——头串里没有期限,站点响应会按自己的期限覆盖), 在开第一个标签页之前写进 profile,再导航;
4. 注入了仍落在登录页 → credential.status = expired;Cookie 账号(没有密码可自动登录)转等待处理 login_required ("登录已失效:接管后在画面里登录一次,交还后全站生效"),账密账号留给 Agent 用凭证注入登录。

会话详情 credential:status、source(manual 手填 / login 自动登录 / browser 浏览器回写)、sourceAt、count(个数,不含值)、 message、syncedAt;原站视图顶栏显示"登录态:来源 · 时间"。

9.2 回写

时机	做法
人工接管交还	先按上游 GET /tabs 同步当前地址(桌面里的导航不经 API),不在登录页才读回
关闭会话	关闭前读回一次(站点 / 浏览器服务停用导致的关闭不读)
定时	会话有动作时,距上次读回(或创建)满 10 分钟,后台读回一次
refresh-login 发现 Cookie 失效	Cookie 账号:从浏览器 profile 读回(不要求会话开着,读落盘文件),与存的不同就拿它验证一次,有效才回写并标 active

读回只取作用于站点主机的、未过期的 Cookie(统计 / CDN / 第三方域名一律丢弃),剔除 Cloudflare 的 cf_clearance / __cf_bm(仅浏览器,§11.4), 与存储比较(忽略顺序),有变化才写(同时结束 UA 待切换,§11.3): Cookie 账号替换 secret_ref,账密账号替换(或新建)会话 Cookie;site_account.user_info.cookieOrigin = {source: "browser", by: "browser", at}, expired / invalid 的账号回到 unknown。来源判定:cookieOrigin.at 不早于 secret 最近写入(rotated_at,留 5 秒)才算浏览器回写, 之后再手填或自动登录会让它变回 manual / login。

安全:Cookie 值只在服务端、secret 表与浏览器服务之间传;日志只记个数;会话详情 / 能力输出 / 模型上下文里没有值;快照遮蔽照旧(§3)。

9.3 真机核验(2026-09-29)

scripts/browser-verify/cookie-real.ts:临时容器 camofox-browser:1.17.0 + 挂载 umt-cookies 插件(与用户栈同一网络、同一出口代理), 读用户栈数据库里憨憨(hhanclub)账号的手填 Cookie(5 个),注入全新 profile 后打开首页一次:HTTP 200、落在 / 不是登录页、 页面有 a[href*=logout.php](站点定义的登录成功标记)→ 已登录;插件读回 5 个、全部是 hhanclub.net 域名、包含注入的全部名字。 对真实站点只有这一次导航,未截图。

没有核验的:桌面镜像重建后的端到端(接管 → 画面里登录 → 交还回写)只在 mock 上测过;其它三站;sessionStorage / IndexedDB 登录的站点 (Cookie 注入不覆盖这类登录态)。站点账号列表里显示登录态来源待前端接 userInfo.cookieOrigin。

10. 重启恢复(BR-3)

camofox 容器重启(docker compose up -d 重建、OOM、手动 restart)后,上游的标签页全部消失:旧 tabId 返回 410 browser_restarted (或 404),GET /tabs 为空。数据库里的会话还在,app 自动把它接回来,不需要关闭重开。代码:modules/browser/service.ts (checkInstance / reconnectIfNeeded / doReconnect、run 里的自愈)、适配器 reopenSession / instanceId、 前端 components/browser/reconnect.tsx。

10.1 怎么发现

途径	做法
被动(总是生效)	任一会话操作(截图、快照、导航、点击、输入、提取、下载、视觉动作)收到 404 / 410,或适配器里已没有打开的标签页 → 按 GET /tabs 对账;会话一个活标签页都不剩 → 标 needsReconnect(trigger = tab_gone)并立即重连
主动(需要 umt 插件)	会话详情 / 操作前查实例标识(GET /umt/instance,插件不在时退回 /health 里的 instanceId / bootId / startedAt),每个浏览器服务 5 秒最多一次;和会话打开时记下的 recovery_state.instanceId 不同 → 该服务下全部未关闭会话标 needsReconnect(trigger = provider_restarted),下一次操作或原站视图触发重连

纯截图镜像 camofox-browser:1.17.0 不带插件,只有被动发现;桌面镜像(缺省)两种都有,桌面模式因此也能在不截图的情况下发现重启。

10.2 重连做什么

1. 按会话的站点 / 账号准备 Cookie(与打开会话同一套,§9.1:匿名 / API Key 类不注入;账密账号没有会话 Cookie 先 refresh-login);
2. 写进该 profile(POST /umt/sessions/{userId}/cookies),再用同一 userId / sessionKey 开新标签页;
3. 导航到会话记录的 current_url(不在站点域名内或是脱敏过的地址 → 站点首页);
4. 旧的打开中标签页标 lost,换当前标签页;needsSnapshot = true(旧元素引用作废),记 recovery_state.instanceId 与 reconnect;
5. 重试原操作一次。

同一会话并发的操作共用一次重连。控制者与租约不变:Agent 的会话仍归 Agent;人工接管中重连,租约保留,会话详情 reconnect.humanNotice = true, 原站视图提示"浏览器重启过，页面已重新加载，请核对"(表单里没提交的输入、滚动位置都没了)。

失败(camofox 还没起来、POST /tabs 5xx、浏览器服务停用等):会话保持 needsReconnect,reconnect.status = failed 记原因, 接口返回 503 browser_reconnect_failed(消息带原因,不含凭据)。之后 10 秒内的操作直接报上次的原因,不反复打上游; 显式 POST /browser/sessions/{id}/reconnect 不受这个限制。

10.3 接口与界面

端点	说明
POST /browser/sessions/{id}/reconnect	幂等:强制查一次实例标识;没标需要重连时先对账,当前标签页还活着就什么都不做;否则按 §10.2 重建。不要求接管。返回会话详情
GET /browser/sessions/{id}	多了 needsReconnect 与 reconnect {status, trigger, at, reason, humanNotice}

原站视图:截图模式收到 404 / 409(已回收)/ 503,或会话详情 needsReconnect = true → 显示"浏览器已重启，正在重新连接…", 自动调一次 reconnect,期间停掉截图轮询;成功后继续轮询;失败显示原因与"重新连接"按钮,不再每 1.5 秒刷错误(浏览器控制台只打一次 debug)。 桌面模式:同样按 needsReconnect 自动重连一次,成功(或别处触发的重连成功)后重建 Selkies 连接(iframe 重新加载)。

10.4 核验

• 自动化:apps/server/src/modules/browser/__tests__/browser-reconnect.test.ts(mock camofox restart():标签页清空、旧 tabId 410、 实例标识换新、可选丢 profile)——截图自愈并注入 Cookie、回到原地址;实例标识变化 + reconnect 幂等;接管中重连保持租约; 失败 503 与退避;前端冒烟"原站视图 → 浏览器重启后自动重连(mock)"。
• 真机:未对真实 camofox 容器重启核验。桌面镜像要重建后才有 GET /umt/instance(docker compose build camofox && docker compose up -d camofox); 重建前只有被动发现(截图 / 操作时自愈),桌面模式要等一次截图或 Agent 操作才会重连。

11. 浏览器身份、站点请求 UA 与出口(BR-4)

同一个站点账号的登录态在浏览器(camofox / Firefox)和 HTTP 端(Deno)之间互注(§9),所以两端要看起来是同一台设备: 同一个 UA、稳定的指纹、同一个出口 IP。用户决定(2026-09-30):对外伪装 Windows;全实例一套固定指纹; 浏览器与 HTTP 按站点统一出口。调研见 docs/design/browser-ua-research.md。

代码:插件 docker/browser-desktop/root/opt/camofox/plugins/umt-cookies/{index.js,identity.js}; apps/server/src/modules/sources-identity/{runtime.ts,service/user-agent.ts,service/credentials.ts,service/account.ts}; apps/server/src/modules/browser/service.ts(identityUserAgent / refreshIdentity / applyEgress);迁移 0056_browser_identity。

11.1 固定浏览器身份(插件 browser:launching)

• 首次启动:插件用 camoufox-js 的 launchOptions({ os: "windows" }) 生成一份完整指纹——BrowserForge 的 Windows Firefox 指纹(navigator / screen / 硬件)、Camoufox 的 Windows 字族表、按 Windows 取样的 WebGL(vendor / renderer / 参数)、 字体间距 / 音频 / canvas 随机种子、window.history.length、canvas 抗锯齿偏移——去掉运行期字段(humanize、locale:*、 geolocation:*、timezone、webrtc:*、addons)后落盘 /root/.camofox/umt-identity.json(compose 的持久卷 umt-camofox, 与 profile 同一个卷;属主 abc、0600)。WebGL2 开关等配套 Firefox 首选项一起存。
• 之后每次启动(容器重启、浏览器空闲 5 分钟退出后再启动):把上游随机生成的 config 里的指纹部分整份换成身份文件里的, 运行期字段仍取上游。浏览器进程日志 umt identity applied {os, fingerprintId, revision}。
• 升级:Camoufox 版本或 Firefox 主版本与文件里记的不同 → 只改 navigator.* / headers.* 里的版本号(与 camoufox-js 生成时 同一个替换规则),新版本多出的指纹字段从同 OS 新样本补齐,其余一律保留;revision + 1,fingerprintId 不变 (日志 umt identity upgraded)。站点看到的是"同一台电脑升级了 Firefox"。
• 重置(换一台"新设备",所有站点都会看到新设备):停 camofox,删 umt-identity.json,再启动。
• 开关与路径:UMT_BROWSER_IDENTITY=off 关掉(回到上游每次随机的 Linux 指纹);UMT_IDENTITY_FILE / UMT_STATE_DIR 改路径。 文件损坏会改名 .bad-<时间> 后重新生成。
• GET /umt/identity(访问凭据保护):{userAgent, os, platform, firefoxVersion, camoufoxVersion, fingerprintId, revision, schema, createdAt, updatedAt},不含指纹细节。app 存进 browser_provider.identity(加 fetchedAt):打开会话时(10 分钟内读过就不读)、 重连时、设置页探测浏览器服务时读;站点请求取它时超过 6 小时会重读,读不到 5 分钟内不再试。

Windows 伪装的一致性(camoufox-js 0.11.5 源码 + 2026-09-30 本地临时容器实测,只开本地页面):

项	结果
UA / 请求头	Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:152.0) Gecko/20100101 Firefox/152.0;HTTP User-Agent 头同值
navigator	platform = Win32、oscpu = Windows NT 10.0; Win64; x64;并发数、语言等来自同一份 Windows 指纹
WebGL	按 Windows 取样:Google Inc. (Intel) / ANGLE (Intel, Intel(R) HD Graphics 400 Direct3D11 vs_5_0 ps_5_0)(D3D11,Windows 才有)
字体	字族白名单 = Camoufox 的 Windows 字体表;字形来自 Camoufox 自带的 Windows 字体(/opt/camoufox/fonts/windows:Arial、Segoe UI、微软雅黑、宋体、等线……)。实测"微软雅黑"可用且宽度与回退字体不同,Noto / DejaVu 这类 Linux 字体不可见;中文页面以微软雅黑渲染
跨重启	重启容器后 fingerprintId、屏幕尺寸、WebGL 不变;模拟 140 → 152 升级只改了 UA 版本

发现并修正的上游问题:camoufox-js 0.11.5 把 FONTCONFIG_PATH 设成 /opt/camoufox/fontconfig/lin(不存在;Camoufox 152 的目录是 linux / macos / windows),而 fontconfig 里的字体目录写的是相对当前目录的 fonts(浏览器进程当前目录是 /opt/camofox)。 插件把 fontconfig/windows/fonts.conf 复制到临时目录、字体目录改成 /opt/camoufox/fonts 绝对路径,再指给 FONTCONFIG_PATH。

限制:渲染仍是 Linux 上的 Firefox——字体光栅化、canvas / 音频的像素级结果与真 Windows 不同(Camoufox 用固定种子加噪,稳定但不是 Windows 的真值);TLS / HTTP2 指纹是 Firefox 152 本身(与 OS 无关)。屏幕尺寸来自指纹(如 2560×1440),桌面模式窗口是 1280×900, 相当于没最大化的窗口。时区跟容器 TZ(缺省 Asia/Shanghai);语言跟指纹(缺省 en-US),要中文设 CAMOFOX_LOCALE。 指纹是进程级的:所有站点 / 账号共用这一套(用户决定;每账号一套要每账号一个浏览器进程,不做)。

11.2 站点请求 UA

站点请求的 UA 按账号解析,优先级从高到低:

来源(SiteAccount.userAgentSource)	取值	界面
manual	账号手动填的 UA(site_account.user_agent)	手动填写
pending	待切换:取得当前登录态时用的旧 UA(site_account.ua_pending,§11.3)	待切换:…
global	设置 → 站点默认 → User-Agent(settings.sites.userAgent,非空时)	使用设置里的全局 UA
browser	浏览器固定身份的 UA(browser_provider.identity.userAgent);读不到时用常量 FALLBACK_SITE_USER_AGENT(同型 Windows Firefox 152)	跟随浏览器

• 覆盖面:站点适配器(列表 / 搜索 / 详情 / 下载 .torrent / 健康检测)、RSS、账密登录、用户数据、Cookie 失效时的浏览器读回验证—— 全部经 SourcesRuntime.siteFetch:请求自己没设 UA 就补上;适配器每条请求现场按"与站点凭证同一个账号"(第一个启用、未失效、非 Passkey) 取 UA,与 Cookie 同一时刻读库,不缓存。之前适配器与 RSS 发的是 Deno 缺省 UA Deno/2.9.7,已不再出现 (测试 apps/server/test/sources-identity/user-agent.test.ts 逐条断言)。不挂站点的请求(通用 RSS)用全局 UA / 跟随浏览器。
• 设置里的 User-Agent 缺省留空 = 跟随浏览器(原缺省 Windows Chrome 140 已去掉);填了会让 HTTP 与浏览器 UA 不一致,只在确有需要时用。
• 账号"更新凭证"里的 UA 留空 = 不覆盖;Cookie 是从别的浏览器复制的、且站点校验 UA 时才填那个浏览器的 UA。
• 不在范围:TMDB、图片代理(不带凭据的公开请求)、下载器、浏览器服务本身。
• 升级 camofox 镜像(Firefox 大版本变)时:浏览器身份自动升级(§11.1),app 最迟 6 小时(或下次打开会话 / 重连)跟上; 同时把 packages/contracts/src/settings.ts 的 FALLBACK_SITE_USER_AGENT 改成新版本号。

11.3 平滑迁移(待切换)

改 UA 一般不会让 NexusPHP 的 Cookie 失效,但前置 Cloudflare / WAF 的站点可能要求重新过挑战。所以不立即给存量账号换 UA:

• 迁移 0056_browser_identity:Cookie / 账密账号(有凭证、没手动 UA)记 ua_pending = 取得当前登录态时的 UA——设置里改过全局 UA 就是那个值,否则是旧缺省 Chrome 140;API Key / Passkey 账号与网页登录态无关,直接跟随浏览器;设置里的 UA 仍是旧缺省值时删掉 (= 跟随浏览器),改过的保留为全局 UA。
• 待切换期间,这个账号的所有站点请求(包括原来发 Deno UA 的适配器 / RSS)都用旧 UA,与登录态一致。
• 切换时机(Cookie 与 UA 同一事务写,下一条站点请求两者一起生效):
  1. 重新登录:账密账号 refresh-login 走 takelogin 时用切换后的 UA,拿到会话 Cookie 后清 ua_pending;
  2. 浏览器回写 Cookie(§9.2 的交还 / 关闭 / 定时 / refresh-login 读回):浏览器是用自己的 UA 取得 / 使用这份登录态的,回写时清 ua_pending; Cookie 没变但浏览器不在登录页、正用着这份登录态,也清;
  3. 换主凭证(填新 Cookie / 新密码):新登录态,直接跟随浏览器。
• Cookie 账号如果一直不开原站视图、也不换 Cookie,会一直待切换(界面写"待切换:下次刷新登录,或在原站视图里用过后改为跟随浏览器")。 刷新登录对 Cookie 账号只校验,不切换。

11.4 Cloudflare Cookie 仅浏览器(CF-2 起有条件给 HTTP)

cf_clearance、__cf_bm(及挑战过程中的 cf_chl_*)与取得它的浏览器绑定(UA + IP + TLS 指纹),Deno 的 TLS 指纹与 Firefox 必然不同, HTTP 端拿去用多半无效还可能触发风控。所以:

• 浏览器回写账号时剔除这些 Cookie,只在 site_account.user_info.browserOnlyCookies 记名字(不含值);它们留在浏览器 profile 里照常用;
• 比较"有没有变化"时也不算它们(CF Cookie 轮换不会触发回写);refresh-login 从浏览器读回的 Cookie 同样剔除;
• 站点账号页技术信息里显示"仅浏览器使用的 Cookie";
• 用户手填的 Cookie 里带 cf_clearance 不处理(用户自己的选择)。
• CF-2 例外:站点遇 Cloudflare 挑战、浏览器过了之后,账号 UA 来源 = 跟随浏览器、浏览器 UA 与 HTTP UA 相同、两端出口相同时, cf_clearance(只有它,__cf_bm 仍不带)单独存进 site_account.user_info.cloudflare(值在 secret)并由 HTTP 带上重试 1 次, 结果按站点记 cfReuse;普通回写仍剔除它(见 sites.md「Cloudflare(CF-2)」)。

11.5 出口 IP 按站点统一

实测(本地临时容器):Firefox 会用容器的 HTTP_PROXY / HTTPS_PROXY 环境变量(Firefox 缺省"使用系统代理",Linux 下没有 GSettings 就读环境变量)。所以本机栈此前的状态是:docker-compose.override.yml 给 camofox 设了 HTTP_PROXY=http://172.17.0.1:7891, 浏览器所有站点都走代理;HTTP 端只有开了"使用代理"的站点走代理——同一账号两端出口 IP 不同。

现在(UMT_BROWSER_PROXY_MODE=site,缺省):

• 插件在启动时设 network.proxy.type = 0:浏览器不再用容器环境变量里的代理,缺省直连;
• app 在打开会话 / 重连前调 PUT /umt/sessions/{userId}/proxy:站点开了"使用代理"且设置了代理地址 → 该站点 profile 的 BrowserContext 走同一个代理(Playwright 按上下文代理,Firefox / Juggler 原生支持;URL 里的账号口令拆成 username / password); 否则 null 直连。插件把这张表存在 /root/.camofox/umt-proxies.json(0600,代理带口令时含口令),camofox 重启后照用;
• 该 profile 已有活动上下文、出口不同 → 插件先关掉它(持久化插件先落盘登录状态),下一次操作按新出口重建;
• 实测:直连 profile 访问测试域名走不到环境变量里的代理;代理 profile 的请求到了指定代理;改出口时活动上下文被重建。

限制与注意:

• 代理地址要让 app 与 camofox 两个容器都能连(如本机的 socat 中继 http://172.17.0.1:7891 可以;http://127.0.0.1:7890 在 camofox 容器里连不到)。
• 站点"使用代理"开关或代理地址改了,已打开的浏览器会话在下一次打开 / 重连时才按新出口;要立即生效就关掉会话重开。
• 匿名会话与 Agent 打开的站点会话同样按站点出口(浏览器会话都属于某个站点)。
• 旧镜像 / 插件没有出口接口:app 只记日志,浏览器照旧按环境变量出网。UMT_BROWSER_PROXY_MODE=env 可退回旧行为。
• SOCKS 代理的 DNS 解析位置未核验(HTTP 代理由代理端解析,与 Deno 的代理客户端一致)。
• 本机栈重建 camofox 后,憨憨(未开代理)的浏览器会话会从"经代理"变为直连,与 HTTP 端一致;override 里 camofox 的 HTTP_PROXY 可以留着(Firefox 不再用它),也可以删掉。

11.6 上线步骤与核验

需要重建 app(代码 + 迁移 0056)和 camofox(插件):

docker compose --env-file .env.deploy build app camofox
docker compose --env-file .env.deploy up -d app camofox
docker compose exec camofox curl -s -H "Authorization: Bearer $CAMOFOX_ACCESS_KEY" http://127.0.0.1:9377/umt/identity

camofox 镜像只有 COPY root/ / 与其后改插件清单的一层变化;前面的 apt 层与从 camofox-browser:1.17.0 复制 node / camofox / Camoufox 浏览器包的层都走构建缓存,不会重新下载 Camoufox(约 630 MB)。2026-09-30 在本机用临时标签实测:带 --build-arg APT_MIRROR=mirrors.ustc.edu.cn(与 .env.deploy 相同)时 apt / 复制层全部 CACHED,只重跑插件两层(< 1 秒)。 注意构建参数要与上次一致(用同一个 --env-file .env.deploy):不带 APT_MIRROR 构建会让 apt 层缓存失效,重新 apt 安装(浏览器包 仍从本地 camofox-browser:1.17.0 复制,不从网上下)。首次启动生成身份,之后 profile 卷里的登录状态照常可用。

核验:apps/server/test/sources-identity/user-agent.test.ts(每条出站请求的 UA、优先级、待切换、CF Cookie)、 migration-browser-identity.test.ts、apps/server/src/modules/browser/__tests__/browser-identity.test.ts(出口下发、身份存库)、 packages/adapters/src/browser/umt-plugin.test.ts(插件纯函数、适配器接口);真机:本地临时容器(--network none,只开容器内本地 页面)核验了 §11.1 表格与 §11.5 出口行为,未对真实站点发请求。

12. 会话保活(AG-4)

camofox 按 API 调用判断活动,有三道空闲回收(docker-compose.yml 的 camofox 环境变量):

回收	缺省	判据
标签页 TAB_INACTIVITY_MS	5 分钟	每 60 秒看一次标签页的 toolCalls 有没有变;没变且超过 5 分钟 → 关标签页,会话空了连会话一起关
会话 SESSION_TIMEOUT_MS	30 分钟	会话 lastAccess(大部分 /tabs/{id}/* 接口都会刷新)
浏览器 BROWSER_IDLE_TIMEOUT_MS	5 分钟	一个会话都没有之后浏览器进程退出

桌面模式里人的键鼠直接进 Selkies,原站视图截图(GET /tabs/{id}/screenshot)只刷新 lastAccess、不加 toolCalls—— 接管 5 分钟后标签页被关掉,桌面画面里的窗口消失。app 在"正在用"的会话上定期保活,代码 modules/browser/keepalive.ts、 BrowserService.keepAlive、适配器 keepAlive。

保活调用:camofox 1.17 没有 keepalive / touch 接口;GET /tabs/{id}/stats 只刷新 lastAccess,挡不住标签页回收。 用 GET /tabs/{id}/downloads?userId=…(不带 includeData / consume):只列下载元数据,不读页面、不改页面、不清下载记录, 会让 toolCalls 加一、刷新 lastAccess。只对当前标签页做,不要求控制权,不记 lastAutomationAt。

什么时候保活(进程内登记,各进程保活自己登记的):

使用方	开始	停止
桌面连接	桌面模式 WebSocket 建立(控制或只读都算,多个连接按引用计数)	全部连接断开
人工接管	control/acquire	交还(control/release)、租约过期、会话关闭
智能体会话	智能体会话里的浏览器能力调用(browser.*,含 browser.navigate 新开会话)	智能体会话不再是排队 / 运行中(结束、等待下载或等用户),或最后一次使用后 30 分钟

每 BROWSER_KEEPALIVE_MS(缺省 120000 = 2 分钟,0 = 关闭;要比 TAB_INACTIVITY_MS 短)对登记的会话各做一次; 每轮先复查登记是否还有效,没有使用方的会话不再保活,照常由 camofox 空闲回收。会话关闭(DELETE)立即撤销全部登记。

保活失败:保活走与其它动作相同的 run() 路径——浏览器重启过(实例标识变了)或标签页已被回收(404 / 410、适配器里没有打开的标签页) → 按 §10 自愈重连(注入 Cookie、同一会话新开标签页回到原地址)后在新标签页上再保活一次;重连也失败(浏览器服务不可用)只记 warn 日志 「浏览器会话保活失败」,会话照常标 needsReconnect / reconnect.status = failed,下一轮再试。

核验:apps/server/src/modules/browser/__tests__/browser-keepalive.test.ts(登记 / 引用计数 / 复查;对 mock camofox:接管期间保活、 不记自动化活动、交还后停;桌面连接期间标签页被回收 → 保活时自愈重连;智能体会话结束后停、会话关闭撤销)。真机未核验。

13. Cloudflare 挑战(CF-2)

站点 HTTP 遇挑战时由站点请求一侧(sources-identity CloudflareGate)经钩子调用浏览器模块,流程与状态见 sites.md「Cloudflare(CF-2)」。 浏览器这边:

• solveSiteChallenge({siteId, accountId, url}):该账号 profile 的自动化会话(没有就按站点打开;人工接管中 / 等人处理中不打扰)导航到 同一地址(取站点令牌)→ 用 POST /tabs/{id}/evaluate 读页面(地址、标题、outerHTML、正文样本、navigator.userAgent,适配器 pageContent)按 classifyChallengePage 分类:自动(JS 检查)/ 可点(Turnstile、「确认您是真人」)/ 真验证码(hCaptcha、reCAPTCHA、 选图、输码)→ ① 每 1.5 秒读一次,最多 15 秒 → ② 可点的派视觉子流程(browser.solve_challenge,系统发起:发起人 system:cloudflare、 trigger event、没有父会话;步数 4、时长 ≤ 120 秒、token / 费用取 agent.maxTokensPerRun / maxCostUsdPerRun;最多 2 次; 自动化总开关关闭或只读对账时不派)→ ③ 没过:会话转等待 cf_challenge,待处理事项「<站点>需要你在原站视图里过一次验证」 (视觉子流程失败留下的 challenge_unsolved 事项改成这个说法)。通过后读回 profile 里的 cf_clearance、UA 与会话出口(recovery_state.egress, 插件按站点下发出口成功才有值)。
• fetchSiteHtml({siteId, accountId, url}):同一会话导航(取站点令牌)后读 outerHTML;仍是挑战页 / 会话在人工处理 / 站点停用时不返回页面。
• 同一 profile 的过挑战与代抓在进程内串行(profile 锁);跨进程同站 30 分钟一次靠站点状态的条件更新。
• 交还会话(给自动化)时:站点在等人过验证 → 读回 cf_clearance / UA 通知站点请求继续(CloudflareGate.afterHuman),待处理事项随交还关闭。
• 插件新端点 POST /umt/tabs/{tabId}/mouse-click:click_at(与原站视图截图模式的坐标点击)都先走它。需要重建 camofox 镜像才有 (docker compose build camofox && docker compose up -d camofox,只重跑插件层);没重建时退回 elementFromPoint,Turnstile 点不到, 可点类挑战会转人工。

核验:mock camofox(cloudflare 模式:auto / interactive / captcha)见 browser-cloudflare.test.ts、umt-plugin.test.ts、E14。 插件鼠标点击的真实容器核验见下表(本地临时容器,只开本地页面,不访问真实验证页)。

日期	做法	结果
2026-09-30	临时容器 umt-cf2-camofox(镜像 umt-browser-desktop:1.17.0,只读挂载新插件目录),容器内 node 起两个本地页面:父页 localhost:8001(标题 Just a moment...)内嵌跨域 iframe localhost:8002(复选框,change 事件 isTrusted 才向父页 postMessage);适配器 openSession → pageContent → click({x, y}) → pageContent	插件路径:POST /umt/tabs/{id}/mouse-click 命中复选框,iframe 里收到可信事件,父页标题变为 passed;pageContent 读到 UA …Windows NT 10.0; Win64; x64; rv:152.0…。旧路径(elementFromPoint)只能标到 iframe 元素本身、按元素中心点击,点不到指定坐标。未访问任何外部站点,容器已删除