rootandClaude Opus 5.5
ceb66f8c77
生产 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]>
87 lines
12 KiB
Markdown
87 lines
12 KiB
Markdown
# 全面升级执行记录
|
||
|
||
执行日期：2026-10-01，Asia/Shanghai。**本次项目全面升级已完成，部署验收通过。** 全面升级发布应用为 v0.3.8（后续整理功能已发布 [v0.3.9](18-organize-release.md)），生产与开发 PostgreSQL 为 18.6，浏览器为 1.18.0，演示 qB 为 5.2.4；宿主与其它项目不在升级范围。下文保留隔离验证和阶段记录，并明确已退休的旧回退资源。升级前版本与官方查询证据见 [版本检查](16-dependency-version-review.md)，运行时决策见 [ADR-004](../adr/ADR-004-deno-runtime.md)。
|
||
|
||
## 范围与状态
|
||
|
||
本次范围仅为 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 启动。[官方镜像说明](https://hub.docker.com/_/postgres)
|
||
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 节](14-engineering-review.md)，本次没有业务修复。
|
||
|
||
开发 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 一致。
|
||
|
||
执行证据：[版本与锁文件](evidence/2026-10-01-dependencies/upgrade-locks-and-direct-versions.json)、[验证汇总](evidence/2026-10-01-dependencies/upgrade-verification.json)、[最终部署容器](evidence/2026-10-01-dependencies/deployed-containers.json)、[授权清理记录](evidence/2026-10-01-dependencies/upgrade-cleanup.json)。
|
||
|
||
## 验收后的授权清理与当前恢复路径
|
||
|
||
用户在验收通过后明确授权：“确认没问题的话，老的备份和老的版本都可以干掉的”。已清理 5 个隔离容器、8 个卷（2 个旧 PG16 卷及 6 个隔离卷）、14 个旧镜像标签，以及旧数据归档、PG16 dump、旧环境配置与回退脚本。旧备份 `20260929T103808Z` 和最终停写阶段备份 `20261001T072253Z` 也已删除。`uhd-media-tool:latest` 已指向新的 v0.3.8 镜像。
|
||
|
||
当前仅保留上述新版生产和开发 PG18 备份作为恢复依据。其它项目仍使用的共享 `postgres:16-alpine` 镜像保留；宿主服务和其它项目未升级。旧镜像／旧 PG16 卷回退路径已退休，发生故障时应使用新版备份恢复 PG18。
|
||
|
||
本次依赖、容器与数据库升级及部署验收完成；已有业务和工程问题仍以 [工程化检查](14-engineering-review.md) 与 MP02–MP14 的待办为准，本次没有继续功能开发，也不据此宣称全部业务无缺陷。
|