MoviePilot/docs/v3t-runtime-governance.md

# MoviePilot V3t 运行时治理

> 状态：持续维护。本文定义 `moviepilot-v3` 与 `moviepilot-v3t` 的产品边界、运行依赖分层、
> 故障恢复合同和兼容项退场门禁。具体版本以 `pyproject.toml` 与 `uv.lock` 为准。

## 1. 治理目标

MoviePilot 同一版本提供两套镜像：

- `moviepilot-v3` 使用标准 CPython 3.14，是默认稳定镜像和故障回滚基线。
- `moviepilot-v3t` 使用 CPython 3.14 free-threaded 构建，用于获得多线程 CPU 并行能力；
  Rust 能力固定启用，不能在运行时关闭。

两套镜像必须来自相同源码 revision、使用相同产品版本和同一份 `uv.lock`。V3t 不替换默认镜像，
也不在业务代码中维护一套平行实现；解释器、原生 ABI 或插件不兼容时，应切回同版本标准 V3。
正式发布按同版本制品对验收和晋升 `latest`；任一变体未通过构建、扫描或发布时，本次版本不移动
两边的 `latest`。这不会回退已经发布的标准 V3，且避免两个 `latest` 指向不同源码版本。

V3t 的目标不是让所有请求都更快。它主要改善可并行的 Python CPU 热点，同时验证主程序、原生扩展
和插件生态在 free-threaded 解释器下的正确性。启动、内存、普通 API 和数据库路径不得为获得局部
并发收益而出现不可接受的退化。

## 2. 单一依赖事实源

`pyproject.toml` 中的 `project.dependencies` 是两套镜像共享的运行依赖，ABI 敏感依赖放在两个互斥组：

- `runtime-standard`
- `runtime-free-threaded`

`tool.uv.conflicts` 保证两个组不能同时解析。Docker 的两个构建 stage 分别固定选择对应组；源码升级、
启动恢复和插件安装后的宿主恢复由 `app.runtime.dependencies.runtime_dependency_group()` 根据当前
解释器的 `Py_GIL_DISABLED` 构建标志选择 profile。

依赖选择不得改为镜像标签判断，也不得在业务模块中按包名散落 V3/V3t 分支。Dockerfile 只选择运行
profile，依赖名称、版本和 source 语义全部由 `pyproject.toml` 与 `uv.lock` 管理。

## 3. 当前原生依赖矩阵

下表中的版本用于解释当前分叉原因，不代替锁文件。版本变化后应同步更新本表的治理状态。

| 能力 | 标准 V3 | V3t | 当前处理与上游解除条件 |
| --- | --- | --- | --- |
| Python | CPython 3.14 | CPython 3.14t | 跟随同一 Python 3.14 patch 版本；升级后必须重新验证解释器 ABI、GIL 状态、启动与完整测试。 |
| `moviepilot-rust` | `cp314-abi3` | `cp314t` | 同一包版本按 wheel tag 选择；两套 ABI 和 V2 使用的 `cp311-abi3` 必须在发布链中保持独立可用。 |
| `bcrypt` | 4.x | 5.x | V3t 使用提供 free-threaded 制品的版本；当同一稳定版本同时满足两套 ABI 与密码合同后可合并约束。 |
| Brotli | 1.2.0 wheel | 同版本固定源码构建 | V3t 当前只对该 profile 使用固定上游源码。上游提供可复现的稳定 `cp314t` wheel 后，验证导入、压缩结果、并发与 GIL，再删除 source 覆盖。 |
| CRC 加速 | `crcmod-plus` 2.3.1 | `crcmod-plus` 2.3.1 | 两套镜像统一使用继续维护且兼容 `crcmod` 导入接口的实现。`oss2` 的陈旧元数据仍声明不再维护的 `crcmod`，由 uv 在解析时排除该传递依赖；宿主不在运行时映射、卸载或替插件兼容旧分发包。 |
| `lxml` | 6.1.2 | 7.0.0b1 | V3t 暂用提供目标 ABI 的预发布版本，是当前最高风险项。稳定版提供 `cp314t` wheel 后，需通过 XML、HTML、RSS、站点解析、并发和内存验证再替换。 |
| PostgreSQL 同步驱动 | `psycopg2-binary` 2.x | `psycopg[c]` 3.3.4 | 当前分叉同时受 ABI 与实测性能影响，不要求仅为版本统一而收敛。若上游能力或性能变化，必须重跑三方案 PostgreSQL A/B 后再决策。异步路径继续使用 `asyncpg`。 |
| `orjson` | 3.12.0 wheel | 同版本源码构建 | V3t 使用同一锁定版本并启用 free-threaded 构建变量。上游发布覆盖 Linux amd64/arm64 的稳定 `cp314t` wheel 后可删除本地构建要求。 |
| 中文转换 | `zhconv-rs` | `moviepilot-rust.zhconv_fast()` | 主程序统一经 `app.foundation.text.convert()`，插件统一经 SDK；不得让调用方感知后端差异。只有语义、性能、体积和 ABI 均更优时才考虑统一实现。 |
| 站点资源 | `cpython-314` | `cpython-314t` | 资源文件必须按解释器 ABI 独立构建和选取，不能让 V3t 复用普通 CPython 扩展，也不能影响 V2 的历史 ABI 制品。 |

表中差异不是全部都要消除。只有临时 source 构建、预发布依赖或第三方元数据兼容适合在上游成熟后
优先退场；已由性能与产品边界证明合理的驱动或实现选择，可以继续由 profile 集中管理。

## 4. 依赖检查与自愈合同

“自愈”包含两个不同的恢复边界，不能与普通依赖校验混为一谈。

### 4.1 启动前恢复

容器启动前先导入一组后端核心依赖。导入成功时不运行 uv 同步；导入失败时才选择可用依赖源，并对
`/app` 执行锁定的项目同步。同步命令必须：

- 使用当前虚拟环境中的解释器推导 runtime profile；
- 使用 `--locked`，禁止启动时重新求解未锁定版本；
- 使用 `--inexact`，保留共享环境中的插件额外依赖；
- 只恢复主项目运行依赖，不安装项目本身或开发依赖；
- 恢复后再次执行核心导入探针，仍失败则停止后端启动并保留诊断入口。

源码更新事务中的依赖同步和失败回滚使用同一 profile 选择入口。否则 V3t 在恢复时可能被普通默认组
覆盖，得到“3.14t 解释器 + 标准原生依赖”的无效组合。

### 4.2 插件安装后的宿主恢复

插件与主程序共享虚拟环境。插件依赖安装前后都会采集宿主健康快照，只对安装后新增的异常执行补偿：

1. 优先使用安装前生成的主程序保护约束恢复被修改的包；
2. 约束不可用时，按主项目 `pyproject.toml`、`uv.lock` 和当前 runtime profile 恢复；
3. 恢复完成后重新执行依赖诊断与核心能力探针；
4. 宿主即使恢复成功，本次插件安装仍返回失败，不能把被回滚的安装报告为成功。

依赖诊断使用 `uv pip check`，项目在 `tool.uv.exclude-dependencies` 中明确排除的传递依赖不进入健康
异常集合，其余诊断按安装前后的稳定错误集合识别新增问题；这样既不会反复报告 `oss2` 对旧 `crcmod`
的陈旧元数据，也不会让既有告警遮蔽其他新增错误。核心能力
探针统一由 `app.doctor.dependencies` 执行。普通启动使用轻量模式验证 Web 栈、中文分词与转换；
镜像构建及插件安装前后使用完整模式，继续验证 ABI 敏感原生扩展、CRC C 实现、PostgreSQL C 实现及
导入后的 GIL 状态。插件允许的非核心依赖升级不要求与宿主锁文件逐版本相同，因此插件健康检查不得
用整份 `uv.lock` 强制回滚共享环境。

自愈是异常补偿，不是每次启动的常态安装流程。任何新增恢复入口都必须复用统一 profile 选择函数，
不得自己拼装默认 uv group。

## 5. GIL 与原生扩展可观测性

构建阶段必须导入并执行已知核心原生依赖，验证 V3t 在导入前、导入后和热点执行后均保持 GIL 关闭。
运行阶段还必须保留动态观测，因为构建探针无法穷举插件延迟导入的第三方扩展：

- 启动收尾日志记录解释器类型和实际 GIL 状态；
- 登录后全局设置与系统环境 API 返回 `PYTHON_FREE_THREADED` 和 `PYTHON_GIL_ENABLED`，系统环境 API
  同时返回 `RUST_ACCEL_REQUIRED`；
- 插件安装或重载导致 GIL 从关闭变为开启时，日志记录对应插件归因；
- 前端在 V3t 实际启用 GIL 时显示兼容告警，正常状态不误报。

不得通过 `PYTHON_GIL=0` 或等效方式强制绕过扩展的 GIL 声明。扩展一旦使进程退化为 GIL 模式，
应保留可观测性并修复或替换依赖；无法及时处理时回退标准 V3。

## 6. 当前 A/B 基线与决策

以下数据来自同一源码 revision、相同资源限制的 arm64 候选镜像，用于确定当前架构和依赖策略。后续
上游重放、依赖更新、构建链变化或采集 schema 扩充都会使其失去“最终发布验收”资格，但不抹去已经
建立的设计结论；新的发布候选必须重跑并在本节追加或替换相应数据。

### 6.1 镜像与解释器基线

| 指标 | 标准 V3 | V3t | 结论 |
| --- | ---: | ---: | --- |
| arm64 镜像体积 | 647.5 MiB | 674.0 MiB | V3t 增加 26.5 MiB，约 4.1%；标准镜像仍处于既有 660+ MB 发布口径。 |
| 启动就绪中位数 | 6.177 s | 5.608 s | V3t 约快 9.2%，未造成启动退化；不据此承诺所有部署都会更快。 |
| 空载 working set | 274.9 MiB | 336.8 MiB | V3t 增加约 22.6%，低于 25% 验收阈值。 |
| 主工作负载 PSS | 296.4 MiB | 356.3 MiB | V3t 增加约 20.2%，属于实验镜像的明确资源成本。 |
| 32 线程纯 Python CPU 探针 | 13,143.7 ops/s | 42,583.5 ops/s | V3t 约为 3.24 倍，证明解释器并行收益；该探针不经过 Rust 开关。 |
| 32 线程直接 Rust ABI 探针 | 40,832.4 ops/s | 61,550.9 ops/s | V3t 约为 1.51 倍；两边都直接调用 Rust，仅验证原生 ABI 与并发。 |
| 普通 API 最大 p95 比例 | 基线 | 1.10x | 四个本地 API 中最大退化来自订阅列表，仍低于 1.25x 门禁。 |

同 revision 的 amd64 最终候选也已完成交叉架构验收。标准 V3 与 V3t 的本地镜像体积分别为
680.6 MiB 和 714.0 MiB，V3t 增加 33.4 MiB、约 4.9%。两者均使用 Python 3.14.7，标准 V3
保持 GIL 启用；V3t 使用 free-threaded 解释器，完整原生依赖、`psycopg` C 实现、Rust 文本能力及
`sites.cpython-314t-x86_64-linux-gnu.so` 依次加载后 GIL 始终关闭。两个镜像均以空白配置启动到
`/health/ready` 且 Docker health 为 healthy。该启动运行在 arm64 宿主的 amd64 模拟环境中，只作为
发布候选功能与 ABI 验收，不纳入性能比例。

该候选还通过了四分片全量回归（5,981 passed、3 skipped、14 subtests passed）、PostgreSQL 18.6
迁移/提交/回滚、现代插件清单、历史 `requirements.txt`、插件源码与依赖恢复以及恢复后单实例加载。
这些结果证明双 profile 方案可行；最终发布仍必须使用最新 revision 和正式不可变 digest 重跑。

### 6.2 应用热点三组

真正受产品 Rust 开关影响的应用识别热点必须分成三个对象：

| 运行方式 | 解释器 | 应用实现 | 产品语义 |
| --- | --- | --- | --- |
| V3 + Python | 标准 CPython | Python fallback | 标准镜像关闭 `RUST_ACCEL` 的兼容基线。 |
| V3 + Rust | 标准 CPython | `moviepilot-rust` | 标准镜像启用 `RUST_ACCEL` 的默认性能路径。 |
| V3t + Rust | free-threaded CPython | `moviepilot-rust` | V3t 固定路径，Rust 不允许关闭。 |

当前六个交替样本的中位耗时分别为 `0.068769s`、`0.035339s`、`0.035511s`，三组业务结果校验和
一致。标准 V3 启用 Rust 后耗时约为 Python fallback 的 `0.514x`；V3t 固定 Rust 路径约为标准 V3
Rust 路径的 `1.005x`，即慢约 0.5%，仍低于 1.25x 门禁。解释器探针的并发收益不能抵销产品路径
退化，因此两组比例必须继续独立验收。

### 6.3 PostgreSQL 三方案

三组使用同一 PostgreSQL 18.6、相同 SQL 和六轮全排列顺序，以标准 V3 + `psycopg2` 为 1.00 倍基线：

| 方案 | 单连接查询吞吐 | 16 线程查询吞吐 | 批量事务写耗时 |
| --- | ---: | ---: | ---: |
| V3 + `psycopg2` | 1.00x | 1.00x | 1.00x |
| V3 + `psycopg3 binary` | 0.946x | 0.367x | 0.094x |
| V3t + `psycopg3 C` | 0.931x | 1.258x | 0.096x |

因此标准 V3 保留 `psycopg2`，V3t 为满足 free-threaded ABI 使用 `psycopg3 C`。`psycopg3` 的批量
事务写明显更快，但查询吞吐没有形成全面优势；当前不为统一驱动扩大数据库重构。18 个当前镜像样本
均通过驱动实现、GIL、SQL 结果、长事务并行和样本完整性门禁。三种制品内嵌的 libpq 分别为 17.9、
18.0 和 18.6，性能差异不能全部归因于 Python 驱动。未来驱动或应用访问模式变化
时，必须重跑真实短事务、批量写、连接池、长事务和迁移场景，不能只用单项微基准改写结论。

### 6.4 环境检查成本

`uv sync --check --locked --offline --inexact` 适合验证镜像构建、开发环境和锁定项目能否复现，
不用于覆盖插件允许的非核心依赖升级。真正恢复可能访问包索引，耗时仍受缺失制品、缓存命中、网络和
原生构建影响，不能用检查耗时推断用户故障恢复时长。

当前公共 A/B schema 2 已记录完整安装包集合及哈希、全部原生 distribution 和 wheel tag、导入前后
GIL、working set、RSS/PSS/USS、API p50/p95、SQLite 同步/异步结果和 1/8/16/32 线程热点。两套镜像
各安装 174 个包；V3t 的 16 个核心原生模块在同一进程依次导入后，GIL 始终保持关闭。

### 6.5 冷启动、插件恢复与宿主自愈

空白配置卷首次启动需要下载 CloakBrowser 内核。该场景可能接近用户报告的“两分钟启动”，主要瓶颈
是持久浏览器缓存未命中和下载网络，不是插件初始化；缓存命中后的普通重启不重复下载。

现代 `pyproject.toml` 插件（`boltons==25.0.0`）与历史 `requirements.txt` 插件
（`humanize==4.15.0`）均已在 V3t 真实容器中验收。首次运行从快照恢复两个源码目录耗时 1.60ms，
联网安装依赖及激活耗时 4.64s；优雅关停后使用同一不可变镜像和持久 `/config` 断网重建，源码恢复
耗时 1.95ms，仅从持久 uv 缓存恢复依赖及激活耗时 1.56s。两轮各插件都只产生一条实例初始化记录，
最终 API 状态均为 `active`、无 pending/failed，且没有启用 GIL。该结果证明插件源码恢复不应被依赖
下载阻塞，依赖未就绪的插件可以在 Web 可用后渐进加载。

删除一个主程序核心依赖后重启，启动前探针能触发锁定自愈，`--inexact` 保留插件额外依赖；恢复后
插件仍为单实例 `active`，V3t GIL 仍关闭。该路径的价值是让受污染共享环境能够恢复启动，不是性能
优化；它只在核心导入失败时执行，正常重启不会承担这段解析成本。

## 7. 上游能力的渐进式接入

第三方上游发布新版本或新 wheel 后，按以下顺序处理，不能看到文件名包含 `cp314t` 就直接删除本地兼容：

1. **确认制品**：稳定版本覆盖 Linux amd64/arm64，wheel tag 与解释器 ABI 匹配；源码构建路线还要固定
   可审计的源版本和构建工具链。
2. **建立候选锁**：只修改对应 runtime group 或 source，更新单一 `uv.lock`，确认标准与 free-threaded
   两套 profile 均可 `uv sync --locked` 重建。
3. **验证原生合同**：导入、核心功能、错误边界、首次初始化和 1/8/16/32 线程并发结果一致；V3t
   在每个阶段保持 GIL 关闭。
4. **验证恢复链**：覆盖启动前恢复、源码更新与回滚、现代插件清单、历史 `requirements.txt` 和插件
   安装后宿主恢复，确认 profile 不串组且插件额外依赖不被裁剪。
5. **执行同 revision A/B**：先证明标准 V3 修改前后无可重复退化，再比较同一 revision、同一资源限制
   和不可变镜像 digest 的 V3/V3t。至少保留镜像体积、启动、RSS/PSS/USS、API p50/p95、SQLite、
   PostgreSQL 和 CPU 热点原始样本。
6. **完成双架构验收**：amd64、arm64 的构建、漏洞扫描、启动和核心功能均通过后，才发布候选制品。
7. **删除临时处理**：同一变更中移除不再需要的 source、版本分叉或排除规则，并更新本表、锁文件、
   构建探针和回归测试；不要永久保留失效的兼容分支。

公共 A/B 基线为 `scripts/perf/free_threaded_ab.py`，使用方法和输出合同见
[`scripts/perf/README.md`](../scripts/perf/README.md)。正式验收原始数据应按发布候选独立留存，PR 只提交
可复用脚本和维护者可判断的汇总结论。

## 8. 插件生态边界

- 插件不得直接依赖 V3/V3t 的内部实现选择，应使用 `app.sdk` 暴露的文本、网络和运行时能力。
- 插件直接导入 `zhconv_rs` 等标准 V3 专属包时，V3t 可以明确判定为不兼容；宿主不伪造第三方模块。
- 插件若自行声明不再维护的 `crcmod`，必须由插件迁移到 `crcmod-plus`；宿主不映射分发包、不增加插件
  特判，也不在运行期卸载插件声明的依赖。
- 插件携带原生 wheel 时必须匹配当前解释器和平台 ABI。缺少 `cp314` 或 `cp314t` 制品属于插件依赖
  兼容问题，不通过宿主插件 ID 特判绕过。
- 插件安装后若使 V3t 重新启用 GIL，功能可能仍可运行，但该进程已经失去 free-threaded 产品语义，
  必须告警并引导用户升级插件、移除依赖或切回标准 V3。

V3 `3.0.0` 的依赖集合随镜像交付。相同版本 Tag 的 `release` 自动更新只执行版本比较，不下载源码或
同步依赖；用户必须拉取并重建容器后才会使用新镜像内的锁定环境。`/app` 与 `/opt/venv` 不属于标准
持久化卷，非标准挂载和 `dev` 自动更新不属于正式镜像迁移合同。

## 9. 变更检查表

修改 Python patch 版本、runtime group、原生依赖、Rust 制品、资源 ABI 或双镜像构建链时，至少确认：

- [ ] `pyproject.toml` 与 `uv.lock` 同步，两个互斥 profile 均能锁定重建。
- [ ] 标准 V3 依赖集合、性能、体积和功能没有因 V3t 改动退化。
- [ ] V3t 核心原生扩展导入及并发执行后 GIL 仍关闭。
- [ ] amd64、arm64 的 Python、Rust 和站点资源 ABI 匹配。
- [ ] SQLite、PostgreSQL、插件安装/恢复、源码升级/回滚和启动自愈通过。
- [ ] 动态 GIL API、启动日志、插件归因和前端告警保持一致。
- [ ] 安全扫描结果已按实际安装制品、利用面和上游修复状态审计。
- [ ] 上游已成熟的临时兼容已删除，仍保留的例外在本文有明确解除条件。