UHD_Media_Tool/docs/plan/17-full-upgrade.md

全面升级执行记录

执行日期：2026-10-01，Asia/Shanghai。本次项目全面升级已完成，部署验收通过。 全面升级发布应用为 v0.3.8（后续整理功能已发布 v0.3.9），生产与开发 PostgreSQL 为 18.6，浏览器为 1.18.0，演示 qB 为 5.2.4；宿主与其它项目不在升级范围。下文保留隔离验证和阶段记录，并明确已退休的旧回退资源。升级前版本与官方查询证据见 版本检查，运行时决策见 ADR-004。

范围与状态

本次范围仅为 UHD Media Tool 项目依赖、项目容器及生产／开发数据库。宿主操作系统、Docker Engine、Compose、宿主 Node 和其它项目均不在此次升级范围，也不是本次剩余待办。

发布应用版本为 0.3.8。以下展示升级前基线、验证结果与最终部署状态。

范围	升级前 → 当前	隔离验证	实际部署
根 workspace 与 Pi	Pi 0.87.1 → 0.99.2；主 workspace 直接依赖更新至查询时 latest	已安装；主 deno audit 0 公告；全 workspace tsc 与 Deno check 通过，完整 CI exit 0：3264 通过、4 跳过	已部署，验收通过
Web 与构建工具	Router 7.12.0 → 8.4.0、Vite 7.3.6 → 8.3.1 等 latest	已安装并通过类型检查；完整 CI 与 web 构建通过；最终页面冒烟 83 通过、1 跳过（无订阅详情数据）	已部署，验收通过
浏览器独立依赖与镜像	camofox 1.17.0 → 1.18.0；Node 22.22.3 → 24.21.0；Camoufox beta.28 → beta.30	两套最终镜像构建 exit 0；174 个实际安装依赖 audit 0；隔离桌面与真实 BrowserService 25 项验证通过	已部署，验收通过
PostgreSQL 生产实例	16.14 → 18.6，新卷逻辑恢复	隔离演练及正式停写恢复通过；56 迁移齐全，89 表行数与内容指纹全匹配	已部署，验收通过
PostgreSQL 开发实例	16.14 → 18.6，新卷逻辑恢复	88 表行数与内容 fingerprints 全匹配	正式迁移与恢复验证完成；旧开发卷已授权清理
应用备份客户端	pg_dump/pg_restore/psql 17.11 → 18.6	最终镜像构建 exit 0；client18 / server18 隔离备份恢复 E2E 通过，含校验和、映射计数与 Agent 会话恢复	已部署，验收通过
Deno、Caddy、生产 ffprobe	2.9.7、2.11.4、9.0.2 → 保持当前已核验版本	与新镜像一起验证	已验证并部署；Caddy 固定最新 2.11.4
项目代理中继	socat 1.8.0.0 → 1.8.1.3	更新项目容器	已部署
应用 Debian 基础层	已部署 13.5 → 当前 13.7 补丁层	最终应用镜像已更新容器内 apt 最新补丁，实际 Debian 13.7	已部署，验收通过
演示 qB	5.1.2 → 5.2.4	5.2.4 候选真实 API 测试：3 通过、1 跳过	已部署 5.2.4；不升级外部用户下载器

升级前只读部署检查（历史）

本节记录迁移开始前的位置。表中保留旧卷的要求在迁移验收期间已执行；验收后用户授权清理旧版本，旧 PG16 卷现已退休删除，不能再据此回滚。

生产 Compose 项目 umt 位于 /opt/uhd_media_tool，装配 docker-compose.yml 与本机 docker-compose.override.yml。检查没有输出环境文件或容器凭证。应用、PG 与浏览器健康。

对象	当前持久化位置	升级要求
生产 PG16	umt_umt-pg-data → /var/lib/postgresql/data	保留旧卷；PG18 使用另一个明确命名的新卷
开发 PG16	umt-dev_umt-pg-data → /var/lib/postgresql/data	独立迁移，不与生产库共卷
应用数据	umt_umt-data → /data	保留备份、Agent 会话与导出；候选实例使用隔离副本
媒体目录	/opt/umt-demo/media → /media；/opt/umt-demo/downloads → /downloads	保持路径映射；隔离验证不写真实挂载
浏览器登录状态	umt_umt-camofox → /root/.camofox	保留旧卷与旧镜像回退证据；候选实例先使用隔离副本
桌面配置	浏览器另挂匿名 /config 卷	重建时记录并保持其绑定，不能只检查登录状态卷

生产数据库已应用 56 条迁移，最新 0058_scrape_record。检查时现有备份目录为 /data/backups/20260929T103808Z，manifest 声明服务端 16.14、pg_dump 17.11；初始只读检查只确认该历史备份存在和版本；随后主代理已将生产 dump 恢复到隔离 PG18，但尚未确认所用 dump 与该历史目录是同一份。切换前需生成新的停写备份。宿主数据所在文件系统约有 1023 GiB 可用，不代替目标数据大小与峰值空间核算。

PostgreSQL 16 → 18 执行与回滚边界（迁移阶段历史）

以下步骤描述验收前的迁移与回退安排，已完成迁移。旧镜像、旧 PG16 卷及旧回退脚本已在最终验收后按用户授权删除；当前仅支持用保留的新版 PG18 备份恢复 PG18，不再承诺第 6 步的旧卷回退。

1. 保存旧应用镜像 ID、Compose 配置及 PG16 镜像 ID；保留原主密钥并避免写入文档。确认数据库、Agent 会话、映射清单备份和校验和完整。
2. 在隔离 PG18 新卷演练逻辑恢复；核对表、扩展、迁移、映射行数以及任务引擎 schema，运行 PG18 集成与编译产物检查。候选应用关闭自动化并避免连接真实下载器、模型与站点。
3. 正式切换前停止应用写入，再生成最终一致的数据库及会话备份。恢复到新的 PG18 卷，保留原 PG16 卷不变；新应用先以只读对账状态启动，确认迁移、健康、映射、凭证和挂载后再决定恢复自动化。
4. PG18 官方镜像默认 PGDATA=/var/lib/postgresql/18/docker，卷应挂在 /var/lib/postgresql，不能将 PG16 数据目录直接交给 PG18 启动。官方镜像说明
5. 升级应用镜像内备份工具到 18 客户端，避免 17 版 pg_dump 无法备份 18 服务端。恢复脚本当前过滤 SET transaction_timeout 以兼容旧服务端，更新说明并分别验证旧备份恢复与新库备份。
6. 如切换验收失败，停止新应用和 PG18，恢复旧配置、旧镜像与 PG16 原卷。此回滚返回最终切换备份时点；PG18 上线后产生的新写入不能自动落回旧卷，需另行处理，不能承诺零数据损失的降级。

不得用 compose down -v、卷 prune 或覆盖旧数据目录完成迁移。最终部署镜像和清理对象见文末 JSON 证据。

范围外检查说明

前期只读检查曾记录宿主版本、软件路径及共享 Docker daemon 上的其它项目；这些检查用于确认项目容器变更的边界，不构成本次宿主升级计划。此次未升级或重启宿主服务，也不更新其它项目。

安装与验证进展

依赖安装首次因 Deno 2.9 默认 24 小时 minimumDependencyAge 拒绝刚发布的 Biome 等包。按用户全面升级至最新的明确要求，本次安装使用一次性 --minimum-dependency-age=0；不写入永久禁用配置，依赖仍精确锁定。这是安装策略例外，不代表依赖已通过安全审计或兼容检查。主代理已拉取 postgres:18.6-alpine，并完成隔离库恢复；生产迁移现已完成。qB 适配器已有 5.2 的 HTTP 204 登录与 QBT_SID 测试，旧 override 的“只能 5.1.2”注释待同步纠正。

主 workspace 共 58 个外部直接依赖已安装；除 @types/node 保持官方 24.x 最新 24.19.0，其余更新至查询时 latest。主 deno audit 为 0 公告，不涵盖浏览器独立 lock、系统包或实际业务兼容。全 workspace tsc 与 Deno check 通过。首次完整 CI 停在根 deno.json 格式错误，修复后完整 CI exit 0，3264 通过、4 跳过；主 npm 安全审计为 0 公告。最终应用镜像 uhd-media-tool:v0.3.8 构建 exit 0，镜像 ID 为 sha256:6f4f73d8ea53057cdf5bf4aa2904a360ea953adb1270a7b9f783a757b7e70559，已正式部署并验收通过。最终页面冒烟 83 通过、1 跳过，跳过原因为没有订阅详情数据。

Pi 初次测试因 TypeSafe provider 与 OpenAI 原生 ChatGPT OAuth 新增导致旧计数断言过期，合同已随升级更新为 42 providers / 9 OAuth，并纳入上述通过的完整 CI。另对 35 份旧 Pi JSONL 会话完成兼容检查并通过。Pi 提供独立的 @earendil-works/pi-mcp 客户端 SDK,本次升级 pi-agent-core 不会自动接入外部 MCP 工具；该功能拓展不属于本次依赖升级交付。

qB 5.2.4 候选的真实 API 兼容测试 3 通过、1 跳过；该结果不代表用户 PT 下载全链路已经验收，演示实例随后已正式切换并完成旧密文凭据连接验证。

浏览器采用 camoufox-js 0.12 与 Playwright 1.60.0 的兼容组合：上游协议对 viewport.isMobile 有限制，不能简单提升该独立 Playwright 至主 workspace 的 1.63.0。这是浏览器独立依赖的协议兼容例外，主 workspace 的 Playwright 不降级；已结合实际镜像与安装依赖审计验证。浏览器目标 Node 改为 24.21.0。

浏览器最终纯截图镜像 1.18.0（ID 前缀 92ea962）和桌面镜像（ID 前缀 eb6c8e）均构建 exit 0。实际安装的 174 个依赖安全审计 0 公告；MCP SDK 1.31 initialize 与原生 SQLite 3.53.4 检查通过。此处 MCP initialize 验证浏览器依赖兼容，不表示应用智能体新增外部 MCP 工具入口。

生产浏览器 profiles/config 的独立副本完成重启前、重启及重启后隔离检查，授权、固定身份保持、cookies、PNG、可信鼠标与 profile 隔离均通过。实际 BrowserService 的 setup / a / b / idle / c / d 六阶段 25 项通过，1.18 的原 10 项能力已登记；相关回归 14 个文件、100 个测试以及登记相关 19 个测试通过。SIGKILL 后最近一次落盘以来的新登录会丢失，验证确认能明确识别，不能据此宣称无损恢复。URL 恢复证据缺口见 工程化检查第 6 节，本次没有业务修复。

开发 PG16 → 18.6 正式迁移已完成，88 表行数与内容 fingerprints 全匹配，旧开发卷在验收期间保留，随后按用户授权清理。client18 / server18 隔离备份恢复 E2E 的校验和、映射计数与 Agent 会话恢复通过。生产停写备份及 PG18 迁移完成，89 表的源库与恢复库行数、内容 fingerprints 全一致，56 条迁移齐全。原主密钥与全部非数据库持久挂载（包括浏览器匿名 /config）完全一致；旧密文凭据通过新版应用成功连接 qB 5.2.4。API、IO worker 和 Agent worker 均以 UID 10001 存活，HTTP / HTTPS 健康，映射计数吻合，验收期间 error 级日志为 0。源库只读对账设置原为 false，迁移验证后已恢复 false，应用正常重启且健康。最终发布镜像的页面冒烟再次通过：83 通过、1 跳过。

新版生产备份 /data/backups/20261001T072536Z 已在隔离 PG18 完成恢复，校验和、映射计数、89 表一致；35 个 Agent 会话文件逐字节 hash 一致。新版开发备份 .local/backups/dev-pg18-20261001.dump 也完成隔离恢复，88 表 fingerprints 一致。

执行证据：版本与锁文件、验证汇总、最终部署容器、授权清理记录。

验收后的授权清理与当前恢复路径

用户在验收通过后明确授权：“确认没问题的话，老的备份和老的版本都可以干掉的”。已清理 5 个隔离容器、8 个卷（2 个旧 PG16 卷及 6 个隔离卷）、14 个旧镜像标签，以及旧数据归档、PG16 dump、旧环境配置与回退脚本。旧备份 20260929T103808Z 和最终停写阶段备份 20261001T072253Z 也已删除。uhd-media-tool:latest 已指向新的 v0.3.8 镜像。

当前仅保留上述新版生产和开发 PG18 备份作为恢复依据。其它项目仍使用的共享 postgres:16-alpine 镜像保留；宿主服务和其它项目未升级。旧镜像／旧 PG16 卷回退路径已退休，发生故障时应使用新版备份恢复 PG18。

本次依赖、容器与数据库升级及部署验收完成；已有业务和工程问题仍以 工程化检查 与 MP02–MP14 的待办为准，本次没有继续功能开发，也不据此宣称全部业务无缺陷。