pixel_pop/UHD_Media_Tool
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: v0.3.8–v0.3.14 工作区汇总（依赖升级、整理来源、手动入库、原地入库等）

Browse Source 
生产 v0.3.8～v0.3.13 均由 8013196 加工作区修改构建部署，此前未提交；本提交补齐源码，
并含未部署的 v0.3.14 原地入库。中间各版本源码状态未保存，无法逐版拆分，详见
docs/plan/17-full-upgrade.md 与 docs/plan/18-organize-release.md。

- v0.3.8 全面升级：Deno workspace 依赖、Router 8 / Vite 8、camofox 1.18.0 / Node 24、
  PostgreSQL 18.6、备份客户端 18.6、演示 qB 5.2.4
- v0.3.9 媒体整理：分类规则、整理来源与目录快照（0059）、文件管理整理入口
- v0.3.10 手动下载与入库：独立手动下载、详情页资源下载、TMDB / Local 元数据兜底
  （metadata.resolve_organize）、正常多版本 / 一次性洗版（0060）
- v0.3.11 搜索详情与桌面黑边修复
- v0.3.12 列表分页、搜索历史、首页概况
- v0.3.13 统一整理弹窗与队列
- v0.3.14 原地入库（0061，未部署）

同批审计修复：
- 刮削入队：确认原记录存在后才删重放产生的新记录；写回 run 关联失败时保持 queued，
  由处理器补关联（对齐 MP 先登记、只在入队失败时记失败）
- 识别升级链只在结果更确定时采用，不再用 no_match 顶替原有歧义候选
- bluray_dir 资产以原盘目录本身为刮削根（MP 同做法）
- metadata.resolve_organize 登记到入库排障 Skill 与能力地图
- db/src/types.ts 按迁移重新生成；contracts 整理动作枚举顺序与数据库对齐
- 测试：原地入库用例改为直接查记录表；domain 测试模板补 version
- 前端：通知铃铛弹层与用户菜单统一样式；站点卡片共用卡头、底栏贴底、分页间距

依赖升级证据只提交摘要文件，registry-snapshot.json 移至 .local/（SHA-256 记于文档）。

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
rootandClaude Opus 5.5 committed 2026-10-02 15:47:17 +08:00
1 parent 8013196e3f
commit ceb66f8c77
265 files changed
+17751 -2483
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/runbook/browser.md
+50 -24
View File
@@ -4,44 +4,50 @@
代码:`packages/adapters/src/browser/**`(适配器)、`apps/server/src/modules/browser/**`(会话/接管/能力)、
`apps/web/app/components/browser/**`(原站视图)。
> 当前状态:已对真实 camofox-browser **v1.17.0**(jo-inc,commit `389c996`)容器逐项核验(§7),十项能力全部通过;
> 当前版本:**v1.18.0**(jo-inc,commit `f94c81b`)已重新核验原有十项能力,六阶段 25 项检查和隔离重启验证通过(§16)。
> §7 等带日期的 v1.17.0 验收表保留历史证据;
> 探测到其它版本 / fork 时一律显示"未核验",需按 §6 重新核验。
## 1. 浏览器服务从哪来
### 1.1 部署自带(缺省)
`docker compose up -d` 同时起 `camofox` 服务(`docker-compose.yml`,只在内网、不映射端口,卷 `umt-camofox`)。
当前部署配置使用 `.env.deploy`。首次启动前,先完成本节下方的基础镜像构建;已有镜像时再执行启停命令。
`docker compose --env-file .env.deploy 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`,只在进程内,不入库),
并在后台探测一次能力。地址与凭据只能改部署配置;设置页只能改它的启用。
```sh
# .env(部署目录)
# .env.deploy(部署目录)
CAMOFOX_ACCESS_KEY=$(openssl rand -hex 24) # camofox 与 app 共用
docker compose --env-file .env.deploy up -d --build
docker compose ps camofox # healthy 即可
docker compose --env-file .env.deploy 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`
上游不发布镜像。compose 缺省用的是**浏览器桌面镜像** `umt-browser-desktop:1.18.0`(`docker/browser-desktop`,§8),
当前默认版本为 1.18.0,构建补丁、锁文件和 Playwright 1.60 协议兼容例外见 [镜像说明](../../docker/camofox/README.md)。以下旧日期的验收表保留历史版本。
它从纯截图镜像 `camofox-browser:1.18.0` 复制 camofox,所以**先构建基础镜像**:`docker/camofox/Dockerfile` 从 git tag `v1.18.0`
构建(修了上游 Dockerfile 的两个问题,见文件头)。首次构建要从 GitHub 拉源码与约 630 MB 的 Camoufox 浏览器包:
```sh
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 \
git clone --depth 1 --branch v1.18.0 https://github.com/jo-inc/camofox-browser.git /tmp/camofox-src
git -C /tmp/camofox-src rev-parse HEAD # 必须为 f94c81babf4bfd44cdd4bd46e1f2e1fb1d91c753
docker build -t camofox-browser:1.18.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)
docker compose --env-file .env.deploy build camofox # 再构建桌面镜像(或 docker build -t umt-browser-desktop:1.18.0 docker/browser-desktop)
```
只要截图模式(不要桌面、省约 400 MB 常驻内存与 3 GB 磁盘):`.env` 里 `CAMOFOX_IMAGE=camofox-browser:1.17.0`,同一个卷,登录状态通用。
只要截图模式(不要桌面、省约 400 MB 常驻内存与 3 GB 磁盘):`.env.deploy` 里 `CAMOFOX_IMAGE=camofox-browser:1.18.0`,同一个卷,登录状态通用。
### 1.2 接自有实例
`.env` 里 `BROWSER_PROVIDER_URL=http://<host>:9377`、`BROWSER_ACCESS_KEY=<它的 CAMOFOX_ACCESS_KEY>`、`CAMOFOX_REPLICAS=0`
`.env.deploy` 里 `BROWSER_PROVIDER_URL=http://<host>:9377`、`BROWSER_ACCESS_KEY=<它的 CAMOFOX_ACCESS_KEY>`、`CAMOFOX_REPLICAS=0`
(不再起自带容器)。或者不设环境变量,在 **设置 → 站点默认 → 浏览器服务** 里"添加浏览器服务":名称、服务地址、访问凭据
(加密存凭证库,只写不回显)、启用。自有实例的版本不是 1.17.0 时能力一律显示"未核验"。
(加密存凭证库,只写不回显)、启用。自有实例的版本不是 1.18.0 时能力一律显示"未核验"。
### 1.3 不用浏览器
@@ -127,7 +133,7 @@ execute 类需要持续授权(`automation_grant`)或审批。元素引用只来
- **坐标系**:服务端对每次截图读页面视口与 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 的做法:
**跨域 iframe 里的控件(Cloudflare Turnstile)和画布也点得到**;插件没有这个端点(旧镜像、纯截图镜像)时退回 1.18.0 的做法:
`elementFromPoint` 打标记再按选择器点(跨域 iframe / 画布点不到具体位置)。
- **动作前提**:会话在自动化控制下(人工接管 / 等待处理中一律拒绝),当前页面主机在站点域名白名单内。
- **敏感截图**:登录页地址、页面上有密码框、地址带凭据 → `sensitive = true`,默认不交给模型(不做像素遮蔽),改给已脱敏的文字快照;
@@ -156,7 +162,12 @@ execute 类需要持续授权(`automation_grant`)或审批。元素引用只来
不承诺通过 Cloudflare 等挑战(REQ §4.4):上游浏览器指纹与点击方式都可能被识别,失败按上面第 4 步转人工。
## 4. 下载产物
## 4. 详情页下载与下载产物
本轮源码新增：进入站点资源详情页后，在串流／截图窗口外点「下载当前资源」，解析当前详情并用默认下载器和目录提交。点「下载选项」可选择下载器、保存目录与一次性洗版。未识别资源会提示确认继续下载，整理阶段再补全元数据；不用点击源站下载按钮，也不用先建立订阅或本地搜索索引。此变更已于 2026-10-01 随 v0.3.10 部署，迁移 `0060` 已执行。
`POST /browser/sessions/{id}/resource {tabId?}` 返回登记后的资源与详情地址。默认读取唯一可见的已登记标签页，能发现上游登记的 popup；无法确定当前标签时明确报错，不提交旧页。显式 `tabId` 读取指定标签。下面的文件捕获接口仍保留给已有 Agent 流程使用。
- 暂存:`DATA_DIR/tmp/browser-downloads/<artifactId>.bin`(目录 0700、文件 0600),超过 24 小时的在下一次捕获时清理。
合同里只出现引用(`bytes.ref`),来源地址去掉 passkey。
@@ -176,10 +187,10 @@ execute 类需要持续授权(`automation_grant`)或审批。元素引用只来
| "连接中断" | 截图请求失败;看 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`、容器日志;恢复后点"重新连接" |
| 503 `browser_reconnect_failed` / "浏览器连接已断开" | 自动重连失败,消息里是原因(camofox 没起来、`POST /tabs` 5xx 等);`docker compose --env-file .env.deploy 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` |
| 设置页显示"未核验" | 探测到的上游版本不在核验表里(不是 1.18.0,或 fork);按 §6 核验后在适配器 `CAMOFOX_VERIFIED_RELEASES` 加一行,或临时写 `config.verified` |
## 6. 真实实例核验清单(REQ §4.7.4)
@@ -191,7 +202,7 @@ execute 类需要持续授权(`automation_grant`)或审批。元素引用只来
自动化核验脚本:`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`。
阶段之间重启 / SIGKILL camofox;结果写 `.browser-verify-out/results-*.json` 与截图)。跑完 `docker compose --env-file .env.deploy -p umtbr down -v`。
| # | 项目 | 做法 | 通过标准 | 对应 verified 键 |
| --- | --- | --- | --- | --- |
@@ -206,7 +217,7 @@ compose 网络里的 mock NexusPHP 站 `mocknexus:8080`;服务层在宿主进程
| 日期 | 仓库 / 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 |
| 2026-09-28 | jo-inc/camofox-browser | v1.18.0(`f94c81b`),Camoufox 152.0.4-beta.28 | `docker/camofox/Dockerfile` + compose;`CAMOFOX_ACCESS_KEY` Bearer | 十项全部 | mock NexusPHP 站 + example.com;四个真实站点未测,见 §7 |
## 7. 真机核验(版本 1.17.0)
@@ -272,7 +283,7 @@ pixelflux + labwc Wayland 桌面 + Selkies 2.0 Web 客户端)+ camofox 1.17.0 **
| 自愈(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,
窗口:由内置 `/defaults/umt-labwc.xml` 设为无服务端装饰、最大化铺满 1280×900(`BROWSER_DESKTOP_WIDTH/HEIGHT`),`HARDEN_DESKTOP` 去掉终端 / sudo / xdg-open,
`HARDEN_OPENBOX` 去掉关闭按钮与右键 / 中键菜单、禁 Alt+F4 等。音频、麦克风、摄像头、手柄、文件传输、打印、命令、共享全部关闭并锁定,
剪贴板只允许文本。
@@ -303,21 +314,23 @@ pixelflux + labwc Wayland 桌面 + Selkies 2.0 Web 客户端)+ camofox 1.17.0 **
### 8.4 HTTPS
当前测试部署于 2026-10-01 将 **4380 改为 Caddy 自签 HTTPS**，访问 `https://服务器地址:4380`，原 443 HTTPS 入口保留。首次访问需在浏览器继续接受内部 CA 证书。app 的 HTTP 调试映射为 `127.0.0.1:4381`，容器间仍使用 `app:4380`。管理员登录、6 个页面加载与 Chromium `isSecureContext` 检查通过。此映射写在本机 `docker-compose.override.yml`，应用监听参数写入 `.env.deploy`。
WebCodecs 视频解码与剪贴板 API 只在安全上下文(HTTPS 或 `localhost`)可用;用 IP / 局域网主机名经 HTTP 访问时只能用截图模式。
```sh
# 已有反代(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 需可达)
docker compose --env-file .env.deploy --profile tls up -d # 自签:Caddy 内部 CA 按访问的主机名现场签发,浏览器需放行或导入根证书
docker compose --env-file .env.deploy cp caddy:/data/caddy/pki/authorities/local/root.crt ./umt-root.crt # 导入到客户端受信任根
# 有公网域名:.env.deploy 里 TLS_DOMAIN=media.example.com、[email protected](ACME,80/443 需可达)
```
`TLS_PORT`(缺省 443)、`TLS_BIND` 可改;4380 仍可直连(截图模式)。
`TLS_PORT`(缺省 443)、`TLS_BIND` 可改；标准 Compose 可通过 app 的 `UMT_PORT` 保留 HTTP 直连。本机已将 4380 用于 HTTPS，HTTP 调试改为 `127.0.0.1:4381`。
### 8.5 回退
- 桌面容器起不来 / 桌面异常:`.env` 设 `CAMOFOX_IMAGE=camofox-browser:1.17.0` 后 `docker compose up -d camofox`,原站视图自动回到截图模式,
- 桌面容器起不来 / 桌面异常:`.env.deploy` 设 `CAMOFOX_IMAGE=camofox-browser:1.17.0` 后 `docker compose --env-file .env.deploy up -d camofox`,原站视图自动回到截图模式,
Agent 能力不受影响(实测同一个卷,切换前后登录状态都在)。
- 只关桌面、保留镜像:不设 `CAMOFOX_ACCESS_KEY` 即可(桌面口令随机,app 探测为不可用)。
- 容器内输入法(本机输入法不可用时的备选):`BROWSER_DESKTOP_IME=fcitx5`,Ctrl+Space 切换;与本机输入法同时开会重复组字,缺省关闭。
@@ -674,3 +687,16 @@ camofox 按 **API 调用**判断活动,有三道空闲回收(`docker-compose.yml
| 日期 | 做法 | 结果 |
| --- | --- | --- |
| 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 元素本身、按元素中心点击,点不到指定坐标。未访问任何外部站点,容器已删除 |
## 16 2026-10-01 的 1.18 升级复测
当前默认桌面镜像为 `umt-browser-desktop:1.18.0`,基础镜像 `camofox-browser:1.18.0` 锁定上游 `f94c81babf4bfd44cdd4bd46e1f2e1fb1d91c753`。Node 24.21.0、Camoufox 152.0.4-beta.30、camoufox-js 0.12.0;Playwright 保持官方协议可兼容的 1.60.0,原因和独立锁见 [构建说明](../../docker/camofox/README.md)。
用生产 profile 与桌面配置的独立副本验证了鉴权、原身份保持、Cookie 正常重启落盘、上下文/页面、evaluate、快照、PNG、选择器与可信坐标点击、profile 隔离。现有真实 BrowserService/Agent 能力核验脚本 `scripts/browser-verify/verify.ts` 的 setup/a/b/idle/c/d 共 25 项严格通过,包含登录、脱敏、提取、下载文件哈希及资源关联、正常重启与空闲回收自动重连、旧引用拒绝、SIGKILL 未落盘登录丢失识别。适配器能力表现已登记 1.18.0 的原十项能力,未知版本不继承核验结果。
完整执行与恢复/清理状态见 [升级记录](../plan/17-full-upgrade.md),机器可读结果见 [验证证据](../plan/evidence/2026-10-01-dependencies/upgrade-verification.json)。这些检查不增加真实 PT 挑战、ARM64 或精确 URL 恢复的验收声明。SIGKILL/OOM 后仅能使用上次落盘状态的限制继续保留。
### 桌面上下黑边排查记录
2026-10-01 已修复底座初始化脚本生成无效 labwc XML 的问题；部署镜像为 `umt-browser-desktop:1.18.0-umt.1`。初始化在 `init-selkies-config` 完成后写入完整 XML，浏览器窗口自动最大化。实际视频尺寸与前端 iframe 同为 1280×900；前后串流截图确认上下黑边消失。若需要调整桌面尺寸，可改 `BROWSER_DESKTOP_WIDTH/HEIGHT`，不要以拉伸或裁剪视频修正窗口布局。证据见 [发布记录](../plan/18-organize-release.md#v0311-搜索详情与桌面黑边修复)。