Files
UHD_Media_Tool/docs/plan/16-dependency-version-review.md
T
rootandClaude Opus 5.5 ceb66f8c77 feat: v0.3.8–v0.3.14 工作区汇总(依赖升级、整理来源、手动入库、原地入库等)
生产 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]>
2026-10-02 15:47:17 +08:00

146 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 依赖与程序版本检查
> 本文保存升级前的检查与候选建议。用户随后要求全面升级,实际修改、验证与部署状态统一见 [全面升级执行记录](17-full-upgrade.md);下文“没有执行升级”对应检查阶段。
检查日期:2026-10-01;业务代码基线:`8013196e3f5e6a8c4ea0cd26cf77294a82a13ddd`/`v0.3.7`。本轮只读检查声明、锁文件、实际程序版本和官方发布信息,并保存文档与证据。没有安装新依赖、更新锁文件、重建镜像、迁移数据库或变更部署。
结论:应先处理安全补丁和运行环境维护,再分别评估 PostgreSQL 18、Pi 原生 MCP 和构建工具的大版本变更。建议将 **PostgreSQL 18.6 列为数据库迁移目标**;16.15 是迁移前的同分支补丁选项。**Pi 0.99.2 已有可复用的 MCP 客户端 SDK**,应评估接入;它与当前对外 MCP 服务端承担不同职责。Caddy 已是当前最新版本,是否保留取决于部署是否已有 HTTPS 网关。
## 1 检查范围与证据
| 范围 | 本轮覆盖 | 证据/限制 |
| --- | --- | --- |
| 主 workspace 直接 npm 依赖 | 58 个不同包,逐包查询官方 npm registry;19 个锁定版本不同于 latest,39 个相同 | [完整直接依赖表](evidence/2026-10-01-dependencies/direct-dependencies.csv),包含声明、实际锁定、latest 与建议 |
| 主 workspace 间接 npm 依赖 | `deno.lock` 648 个 npm 实例、633 个不同包名,逐包查询;191 个包名存在不同于 latest 的锁定版本 | [完整锁定依赖表](evidence/2026-10-01-dependencies/locked-npm.csv);不同版本不等于漏洞,不强制覆盖所有传递依赖 |
| JSR | `@std/path` 1.1.6、`@std/internal` 1.0.14,均与查询时最新相同 | [补充元数据](evidence/2026-10-01-dependencies/additional-metadata.json) |
| 安全公告 | 主锁文件 `deno audit`;已部署浏览器独立 package-lock 的生产依赖 `npm audit --omit=dev` | [主项目审计](evidence/2026-10-01-dependencies/workspace-audit.txt)、[浏览器审计](evidence/2026-10-01-dependencies/browser-audit.json);公告命中仍需判断使用路径 |
| 实际运行环境 | 应用、数据库、浏览器和可选入口容器;宿主 Docker/Compose/Node/FFprobe;默认下载器演示实例 | 实际版本见第 3 节。外部用户自建的下载器、Emby 和其它主机未做全面资产扫描 |
| 浏览器独立依赖 | 6 个直接 npm 包逐个查询,独立 lock 做生产依赖安全审计;上游 1.18.0 manifest 对照 | 不属于主 workspace 的 58/633 统计;浏览器全部传递包没有逐个做新旧版本查询 |
| 系统组件 | Debian 发行版、Python、Selkies/pixelflux/labwc 与浏览器基础镜像摘要 | 未做全量 dpkg 包清单与系统 CVE 扫描,不能据此声称所有系统包均为最新或无漏洞 |
| 历史 spike 和参考源码 | 额外查询部分 spike 工具版本,识别其独立作用域 | `spikes/` 不属于生产 workspace;`spikes/movieclaw-src/repo` 是参考源码,不把其依赖计作正在发布的程序 |
完整 registry 查询快照、查询时间与源码提交保存在本地 `.local/evidence/2026-10-01-dependencies/registry-snapshot.json`(约 240 KB,未进 git;SHA-256 `4ca6c78ecc62f881e2219d6068fdb9e9e48c1b47d79c57ab40e32cc107edd948`)。版本结论是这个检查时点的快照,后续执行升级应重新查询。锁文件 SHA-256:`f4c517c88acac3656ce94bfe6f6e19daf5410c4187624f46110c41cf29e200a0`。
`deno outdated --recursive --no-lock --node-modules-dir=manual` 在允许联网后及加入 `--reload=npm:` 后都列出 12 个包;逐包官方 registry 查询发现 19 个。本轮没有查明这 7 个差异的工具原因,不能简单认定刷新缓存即可解决。报告采用逐包 registry 版本,并用 Pi 等官方发布记录交叉核对;工具结果差异继续保留为检查限制。
## 2 直接依赖的更新建议
下表列出 19 个不同于 latest 的直接依赖。建议版本是后续隔离验证的候选,尚未执行安装或兼容验收。完整 58 个包见证据 CSV。
| 包 | 当前锁定 | 查询时 latest | 建议 |
| --- | --- | --- | --- |
| `@biomejs/biome` | 2.5.14 | 2.5.15 | 补丁候选;检查格式/lint 变化 |
| `@earendil-works/pi-agent-core` | 0.87.1 | 0.99.2 | 与 pi-ai 同步评估;会话、工具与嵌入接口回归 |
| `@earendil-works/pi-ai` | 0.87.1 | 0.99.2 | provider、模型、OAuth、流与取消回归 |
| `@modelcontextprotocol/sdk` | 1.30.1 | 1.31.0 | 同主版本候选;对外鉴权、工具、错误和流式连接回归 |
| `@simplewebauthn/server` | 13.3.3 | 14.0.3 | 与 browser 配套评估;存量凭据、注册、登录和恢复入口 |
| `@simplewebauthn/browser` | 13.3.0 | 14.0.0 | 配套大版本变更,不混入普通补丁批次 |
| `@types/node` | 24.19.0 | 26.6.3 | 保持 Node 24 兼容目标,另核对 24.x 补丁;不直接追 26 |
| `fast-xml-parser` | 5.11.1 | 5.11.2 | 补丁候选;RSS、XML 与 NFO 固定样本 |
| `hono` | 4.13.9 | 4.13.12 | 补丁候选;API、静态回退、鉴权与流式接口 |
| `pg` | 8.23.0 | 8.23.1 | 补丁候选;连接、迁移、事务与任务恢复 |
| `typebox` | 1.3.27 | 1.3.34 | 同主版本候选;Agent 工具 schema |
| `vitest` | 5.0.2 | 5.0.3 | 补丁候选;PG 集成实际执行与跳过清单 |
| `react-router` | 7.12.0 | 8.4.0 | **先验证 7.18.4 安全修复**;8.4.0 单独迁移 |
| `@react-router/dev` | 7.12.0 | 8.4.0 | 与另外两个包统一 7.18.4;检查 peer 和构建 |
| `@react-router/node` | 7.12.0 | 8.4.0 | 统一 7.18.4;保留编译所需作用域检查 |
| `lucide-react` | 0.576.0 | 1.49.0 | 图标导出和视觉变更独立评估 |
| `react-day-picker` | 10.0.1 | 10.0.2 | 补丁候选;日期、时区和日历样本 |
| `vite-tsconfig-paths` | 5.1.4 | 6.1.1 | 配合构建工具链评估 |
| `vite` | 7.3.6 | 8.3.1 | 大版本构建迁移;单独核对 Rolldown/Oxc、插件和 Deno 执行 |
已经与 registry latest 相同的依赖包括:TypeScript 7.0.2、OpenWorkflow 0.10.1、React/React DOM 19.3.0、Zod 4.6.5、Kysely 0.29.6、postgres 3.4.9、主项目 playwright-core 1.63.0、Pino 10.3.1、Tailwind 4.3.3 等。声明里的旧范围下限不等于正在运行旧版本,应以 lock 实际解析结果判断。官方 npm 元数据快照见上文本地 registry-snapshot.json
### 2.1 安全审计的实际意义
主项目审计命中 **13 条 React Router 公告:6 high、6 moderate、1 low,0 critical**。完整公告 ID、受影响范围和链接保存在审计证据中。当前 [React Router 配置](../../apps/web/react-router.config.ts) 为 Framework SPA(`ssr: false`),生产由 [Hono 静态托管](../../apps/server/src/http/static.ts) 返回构建文件和 `index.html`,没有部署 React Router SSR/single-fetch/RSC 服务端处理器。
其中 9 条依赖服务端 SSR、single-fetch、manifest 或 RSC 路径,本轮没有发现对应生产调用路径;不能将审计里的 6 条 high 直接表述成 6 个可利用的线上漏洞。3 条客户端导航公告仍需检查不可信 URL,`ssr:false` 不能排除它们。登录 `safeNext` 有过滤,但不能据此宣称任意编码路径都已验收。另 1 条涉及构建时 prerender 的 Location HTML 注入;SPA 构建仍有根预渲染,但当前没有发现外部输入驱动根 loader 重定向的触发路径。本轮没有复现利用。
建议三个 Router 包先统一到 7.18.4,再做 URL/跳转、构建和页面冒烟。该版本包含本轮公告所需的修复;但 `@react-router/dev` 和 `@react-router/node` 的 TypeScript peer 声明为 `^5.1.0 || ^6.0.0`,本项目是 7.0.2,**候选仍需验证,不能称无兼容风险**。来源:[7.18.4 发布](https://github.com/remix-run/react-router/releases/tag/[email protected])、[7.x changelog](https://reactrouter.com/7.18.4/start/changelog)、[SPA 官方说明](https://reactrouter.com/how-to/spa)。
浏览器独立生产 lock 审计命中 **5 个受影响包、16 个不同公告 URL**,npm 聚合严重性是 2 个 high 包、3 个 moderate 包。包为 `adm-zip` 0.6.0、`brace-expansion` 5.0.9、`fast-uri` 3.1.7、`hono` 4.13.5、`ip-address` 10.4.0。包数、公告数与主项目审计的统计单位不同,不相加成「18 条漏洞」。浏览器里的 Hono 与主应用 Hono 是两个独立版本。
应沿浏览器下载/解压、请求解析和可访问入口核对公告条件,再在候选镜像重跑 audit。上游 1.18.0 的 manifest 仍含 `hono:4.13.5` override 等旧约束,不能承诺只更新 camofox tag 就清除全部命中;npm 的聚合 `fixAvailable:true` 也不能替代每条公告修复范围核对。[浏览器审计与原始公告链接](evidence/2026-10-01-dependencies/browser-audit.json)
## 3 程序和镜像版本
| 程序/环境 | 本次实际版本 | 官方查询结果 | 建议 |
| --- | --- | --- | --- |
| 项目应用 | v0.3.7 | 本项目发布基线 | 是否发布新版本取决于验收,不是依赖 latest |
| Deno(宿主/构建) | 2.9.7 | 2.9.7 | 保持 |
| PostgreSQL(部署/开发) | 16.14 | 稳定主版本 18.6;16 分支 16.15 | 18.6 作为迁移目标;耗时较长时先安排 16.15 补丁 |
| 应用 pg_dump 客户端 | 17.11 | 17 分支 17.11;18 分支 18.6 | 升 PG 18 时必须一并升客户端 |
| Caddy(可选 TLS) | 2.11.4 | 2.11.4 | 保持,按入口部署决定是否启用 |
| camofox-browser | 1.17.0 | 1.18.0 | 候选镜像验证后更新,重新审计独立 lock |
| Camoufox 浏览器二进制 | 152.0.4-beta.28 | 152.0.4-beta.30 | 仍是 beta;配套验证,不当作稳定版自动切换 |
| 浏览器 Node | 22.22.3 | 22 LTS:22.23.3 | 同 LTS 补丁候选,随镜像重建验收 |
| 宿主 Node(非应用主运行时) | 24.15.0 | 24 LTS:24.21.0;Current:26.10.0 | 选 24 LTS 补丁,不因 latest 跳 26 |
| 生产 FFprobe/FFmpeg | 9.0.2 | 稳定 9.0.2 | 保持 |
| 宿主 FFprobe | 7.1.3 | 7.1 分支 7.1.5 | 同分支补丁候选,区别于生产容器工具 |
| 默认 qB 演示实例 | 5.1.2 | 5.2.4 | 先核对 API、标签、暂停/删除和多实例隔离;不替用户外部 qB 升级 |
| Docker Engine(宿主) | 29.2.1 | 29.8.2 | 单列宿主维护窗口,涉及其它项目;核对安全发布说明 |
| Docker Compose(宿主) | 5.0.2 | 5.5.1 | 随宿主维护验证 compose 行为 |
| containerd/runc(宿主) | 2.2.1/1.3.4 | 2.4.1/1.5.2 | 跟随选定 Docker 发行包兼容组合,不单独替换二进制 |
| Debian(应用镜像) | 13.5 | 13.7 | 重建候选层并更新发行版补丁,验证工具和权限 |
| Debian(浏览器桌面镜像) | 13.7 | 13.7 | 发行版一致;仍需判断实际包补丁与镜像构建日期 |
| Python(宿主/浏览器) | 3.13.5 | 上游 3.13.16;稳定主版本 3.14.8 | Debian 管理的软件随发行包更新,不能仅凭上游版本判定系统补丁缺失 |
| Selkies/pixelflux | 2.0.0/2.1.0 | 2.0.0/2.1.0 | 保持,随桌面基础镜像验证 |
| labwc(桌面基础镜像) | 0.9.7-dirty | 上游 0.20.2 | vendor 定制构建,跟随基础镜像,不直接替换 |
| socat(开发转发容器) | 1.8.0.0 | 官方最新未完成核验 | 官方查询超时/证书错误,记录未知;开发辅助,不冒充生产主依赖 |
版本来源:[PostgreSQL 支持表](https://www.postgresql.org/support/versioning/)、[Node 官方发行索引](https://nodejs.org/dist/index.json)、[FFmpeg 下载与版本](https://ffmpeg.org/download.html)、[Debian 新闻](https://www.debian.org/News/)、[Python 发行列表](https://www.python.org/downloads/)、[PyPI Selkies](https://pypi.org/project/selkies/)、[PyPI pixelflux](https://pypi.org/project/pixelflux/)。其余上游 GitHub 发布标签、URL 和日期见本地查询快照 registry-snapshot.json 及[补充快照](evidence/2026-10-01-dependencies/additional-metadata.json)。
桌面基础镜像 `ghcr.io/linuxserver/baseimage-selkies:debiantrixie` 当前配置固定摘要 `sha256:f3ca0b10e923a603941a996ea1c3356b9527cc53163259f4e836f61fd4523e12`;本轮远端 manifest 查询仍为同一摘要。该镜像没有可用的 GitHub release/latest 记录,不能把 release API 的 404 当作已过期。供应方说明基础镜像更新可能破坏兼容,应按镜像组合验收。[供应方说明](https://github.com/linuxserver/docker-baseimage-selkies)
应用与部分服务的 `debian:trixie-slim`、`postgres:16-alpine`、`caddy:2-alpine` 等是可移动标签。实际运行版本由已经构建/拉取的镜像决定;修改 tag 或再次构建都应记录摘要与源码来源,不以配置文字直接证明部署已经更新。
### 3.1 PostgreSQL 18 的迁移边界
PG 18 已是正式稳定分支,当前 18.6。16 仍受支持到 2028-11-09,因此 16.15 是有效的过渡补丁,不能将「最新 16」表述为「最新 PostgreSQL」。本轮没有找到必须永久停留在 16 的业务约束,也没有执行 PG 18 兼容验证。[官方版本策略](https://www.postgresql.org/support/versioning/)
当前 [生产 compose](../../docker-compose.yml) 使用 `postgres:16-alpine`,卷挂载 `/var/lib/postgresql/data`。官方 PG 18 镜像默认 `PGDATA` 改为 `/var/lib/postgresql/18/docker`,声明卷改为 `/var/lib/postgresql`;升级需一起核对卷、目录和权限。PG 大版本不能直接复用原数据目录,需要导出/恢复或经过验证的 `pg_upgrade` 方案。[官方镜像 PGDATA 说明](https://github.com/docker-library/docs/blob/master/postgres/README.md#pgdata)
应用现有 `pg_dump` 是 17.11,不能导出 PG 18 服务端;更新数据库时须同步升备份/恢复客户端至 18.x,并确认脚本调用实际新版本。[pg_dump 官方说明](https://www.postgresql.org/docs/current/app-pgdump.html)
候选验收至少包括:独立 PG 18 实例从当前备份恢复;56 个迁移后的业务和 OpenWorkflow schema 核对;真实 PG 集成测试;旧任务、outbox 和操作账本的一致性;备份再次导出和恢复;回滚时使用原 PG 16 数据/快照。不能将「容器健康」作为数据库迁移完成证据。16.15 的补丁升级也应阅读[发布说明](https://www.postgresql.org/docs/release/16.15/),按实际扩展和配置判断是否有额外步骤。
### 3.2 Pi 原生 MCP 的作用
本项目当前嵌入 `pi-agent-core`/`pi-ai` 0.87.1。官方 0.99.2 已提供 MCP 客户端能力,包括 stdio、Streamable HTTP、OAuth、工具发现和调用。新版还发布独立 `@earendil-works/pi-mcp` 和 `@earendil-works/pi-codemode` 0.99.2;官方 Agent 示例说明可以将其包装成 `AgentTool`,进入工具调用钩子。它不只限于命令行产品,可以评估在本项目嵌入层复用。[官方 MCP 文档](https://github.com/earendil-works/pi/blob/v0.99.2/packages/coding-agent/docs/mcp.md)、[Agent SDK 说明](https://github.com/earendil-works/pi/blob/v0.99.2/packages/agent/README.md#mcp-and-codemode)
本轮读取官方 0.99.2 发布 tarball 的声明文件,确认顶层仍导出 `AgentHarness`,没有依据认定必须重写整个 Agent 接入。其它方法签名、会话兼容、provider 导出和 Deno 行为仍未实际编译/运行验证。两个新 SDK 声明 Node `>=22.19.0`,项目主运行时是 Deno,不能用 Node engines 达标代替 Deno 验收。
当前 [MCP 模块](../../apps/server/src/modules/mcp) 是**服务端**:对外提供本项目能力,并复用 API Key 鉴权、审批、幂等与审计。Pi 原生模块是**客户端**:让内部 Agent 调用外部 MCP 服务。应保留对外服务端;若接入客户端,需定义外部工具如何经过已有权限/审批和审计,避免仅升级包版本就默认开放所有外部工具。新版能力的存在也不证明当前项目已经接入它。
### 3.3 Caddy 当前负责什么
当前 [Caddyfile](../../docker/browser-desktop/Caddyfile) 和 compose 中的 `tls` profile 表明,它是可选 HTTPS 入口:证书、TLS、zstd/gzip 压缩,以及向 `app:4380` 的反向代理。`flush_interval -1` 配合代理保持 Agent SSE 和桌面 WebSocket 的流式传输。默认使用内部 CA;设置域名和 issuer 后可以配置 ACME,实际公网条件仍需符合部署配置。
请求链路为「用户浏览器 → Caddy HTTPS → 应用 4380」;桌面路径再由应用鉴权、会话与租约检查后代理到 Selkies 3000。桌面视频 WebCodecs 与剪贴板要求 HTTPS 或 localhost 的安全上下文,因此入口 TLS 有具体用途。Caddy 不承担 Agent 执行、数据库访问或浏览器会话授权。
已有 Nginx/Traefik/统一 Caddy HTTPS 网关时,可由现有入口提供证书和转发,本项目无需另启 Caddy profile;应验证 SSE、WebSocket 和安全上下文仍正常。当前 Caddy 2.11.4 已是查询时最新,无需为了版本检查更新。
### 3.4 浏览器依赖的独立组合
| 包 | 部署 lock | latest | 边界 |
| --- | --- | --- | --- |
| better-sqlite3 | 13.0.1 | 13.0.3 | 原生模块,随 Node 与镜像重建 |
| camoufox-js | 0.11.5 | 0.12.0 | 新版 peer `playwright-core <1.61.0`,与现有 1.62.1 冲突,不能单独更新 |
| express | 5.2.1 | 5.2.1 | 保持 |
| playwright-core | 1.62.1 | 1.63.0 | 配套浏览器与 camoufox-js 验证 |
| prom-client | 15.1.3 | 15.1.3 | 保持 |
| swagger-jsdoc | 6.3.0 | 6.3.0 | 保持 |
camofox 1.18.0 manifest 的直接依赖仍固定 camoufox-js 0.11.5;更新服务版本并不意味着自动更新这个包到 0.12.0。该发布含 Docker postinstall 等调整,应重新检查本地 Docker 补丁是否仍适用,再验证 Cookie 登录、挑战页、页面操作、人工接管、交还、重启、下载捕获和权限。[1.18.0 官方发布](https://github.com/jo-inc/camofox-browser/releases/tag/v1.18.0)
## 4 建议的处理顺序与验收
1. **安全补丁与候选镜像**:三个 Router 包统一 7.18.4;复核浏览器 audit 并验证 1.18.0 候选;若 PG 18 迁移需较长时间,先安排 16.15。主项目其它补丁包可在同一明确范围内更新,重新生成 lock 并跑现有 CI,确认 PG 测试实际执行,再跑有固定数据的页面冒烟。
2. **PG 18.6 专项**:数据库、18.x 客户端、卷结构、隔离恢复与回滚一起处理,形成可审阅迁移方案,再进入部署。
3. **Pi 0.99.2 与原生 MCP 专项**:先验证原有 Agent 接口和会话,再决定外部 MCP 客户端所需场景;复用已有授权、审批与审计;真实模型验证仍按独立范围进行。
4. **宿主运行环境维护**:Docker/Compose/发行版与 Node 补丁单列维护窗口,核对受影响的其它项目与镜像启动,不混在业务依赖安装中。
5. **其它大版本**:Vite 8/Router 8、Passkey 14 和图标等分别评估价值与兼容;当前没有证据要求全部同时迁移。
本轮完成版本与公告核对,**没有完成候选升级验收**。此前 CI 通过仍只对应现有版本。版本工作与 [MoviePilot v3 逐项业务对照](15-moviepilot-v3-comparison.md) 并行准备,不改变对照表中 02 至 14 尚待核对的状态;恢复问题也不能因依赖更新自动视为解决。