GithubBackup/MoviePilot
1
0
Fork 0
mirror of https://github.com/jxxghp/MoviePilot.git synced 2026-09-09 01:16:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add v2 to v3 overview

Browse Source
This commit is contained in:
jxxghp
2026-08-30 10:13:10 +08:00
parent 9146c75941
commit 2e1a7f5d84
2 changed files with 545 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+1
View File
@@ -30,6 +30,7 @@
推荐优先使用 Docker 部署。V3 使用独立镜像 `jxxghp/moviepilot-v3`，V2 和旧版镜像保持原命名。Compose 示例、环境变量、目录映射和升级方式以官方 Wiki 为准： 推荐优先使用 Docker 部署。V3 使用独立镜像 `jxxghp/moviepilot-v3`，V2 和旧版镜像保持原命名。Compose 示例、环境变量、目录映射和升级方式以官方 Wiki 为准：
- 官方 Wiki：https://wiki.movie-pilot.org - 官方 Wiki：https://wiki.movie-pilot.org
- V2 到 V3 版本变化总览：[docs/v2-to-v3-overview.md](docs/v2-to-v3-overview.md)
- PostgreSQL 部署说明：[docs/postgresql-setup.md](docs/postgresql-setup.md) - PostgreSQL 部署说明：[docs/postgresql-setup.md](docs/postgresql-setup.md)
也可以使用本地 CLI 以源码模式安装和管理 MoviePilot： 也可以使用本地 CLI 以源码模式安装和管理 MoviePilot：
docs/v2-to-v3-overview.md
+544
View File
@@ -0,0 +1,544 @@
# MoviePilot V2 到 V3 版本变化总览
> 面向 MoviePilot 使用用户、部署维护者和插件使用者。
>
> 本文以 **V2.15.6** 与 **V3.0.0** 为主要对比基准，内容同步至 **2026-08-30**。
> V3 仍会持续迭代，具体安装参数、镜像标签和操作命令请以官方 Wiki 的最新说明为准。
## 1. 先说结论：V3 不只是一次界面升级
MoviePilot V3 保留了 V2 已经成熟的影视自动化主流程，包括搜索、订阅、下载、整理、刮削、媒体库刷新和通知。在此基础上，V3 主要完成了四件事：
1. **把音乐纳入完整自动化流程**：支持歌曲、专辑和艺术家的搜索、订阅、下载、整理、标签刮削、封面与歌词处理。
2. **统一媒体与扩展体系**：电影、电视剧、动漫、音乐以及插件提供的数据源，开始使用统一的媒体身份和扩展接口。
3. **重构后台运行架构**：数据库事务、后台任务、事件、插件、定时任务和启动关闭流程更明确，降低任务丢失、重复执行和升级失败的风险。
4. **建立独立的 V3 发布链路**：后端、前端、插件、Rust 加速和站点资源都拥有清晰的 V3 边界，可以分别升级和验证。
对普通用户来说，最直观的变化是“多了音乐、备份、AList、钉钉、插件分身等能力”；更重要但不容易直接看到的变化，是订阅、整理、通知和插件运行比 V2 更容易恢复、更容易排障，也更适合后续继续扩展。
## 2. V2 与 V3 快速对比
| 对比项 | V2 | V3 | 用户影响 |
| --- | --- | --- | --- |
| 核心媒体类型 | 以电影、电视剧、动漫为主 | 影视能力继续保留，音乐成为并列媒体类型 | 可以用同一套搜索、下载和整理体系管理音乐资源 |
| 媒体身份 | 常按 `tmdbid`、`doubanid` 等来源字段分别处理 | 统一为“媒体来源 + 来源内 ID” | 同名资源、多数据源和插件数据源更容易正确区分 |
| 音乐能力 | 没有完整音乐自动化链路 | 支持歌曲、专辑、艺术家、订阅、整理、标签、封面和歌词 | 从“影视自动化”扩展为“影视 + 音乐自动化” |
| 搜索与识别 | 不同元数据来源之间存在较多来源专用处理 | 支持多来源识别、来源转换和插件扩展来源 | 搜索入口更统一，来源选择更灵活 |
| 下载与整理 | 影视流程成熟 | 增加音乐质量、专辑整理、未识别资源确认、失败聚合等能力 | 异常任务更容易人工接管，通知噪声更少 |
| 插件 | 以历史目录和宿主内部导入为主 | 增加 V3 专用索引、稳定 SDK、虚拟分身和来源绑定 | 旧插件尽量兼容，新插件更稳定、更易多实例运行 |
| 站点资源 | 使用 V2 资源包 | 使用独立 `resources.v3` 和 `user.sites.v3.bin` | V2/V3 站点规则互不覆盖，资源可以独立更新 |
| 数据库 | 支持 SQLite/PostgreSQL | 增加迁移前备份、备份管理、恢复校验和可靠事件记录 | 大版本升级与故障恢复更安全 |
| 后台任务 | 部分任务依赖进程内执行时机 | 重要业务结果通过可靠事件和恢复机制处理 | 重启或瞬时故障后更不容易漏通知、漏收尾 |
| 首次安装 | 依赖环境变量和设置向导初始化 | 首次打开网页创建管理员和 API Key | 初始密码不再需要出现在日志或部署文件中 |
| 运行环境 | V2 运行时与依赖体系 | Python 3.14、锁定依赖、独立 Rust 包，可选 V3t | 环境更统一，性能能力和兼容边界更清楚 |
| 前端 | Vue 3 管理界面 | 保留技术基础，增加音乐页、备份管理、插件分身、更新提示等 | 学习成本较低，但功能入口明显增多 |
## 3. 用户可以直接感知的新功能与改进
### 3.1 音乐自动化成为正式能力
音乐是 V3 最明显的大功能。它不是单独挂在旁边的小工具，而是接入了 MoviePilot 原有的自动化主流程：
```text
搜索歌曲、专辑或艺术家
↓
选择音乐元数据
↓
搜索站点音乐资源
↓
手动下载或创建订阅
↓
下载完成后读取音频标签和技术参数
↓
按音乐命名规则整理文件
↓
写入标签、封面和歌词
↓
由 Navidrome、Emby、Jellyfin、Plex 等媒体软件扫描播放
```
主要能力包括：
- 按歌曲、专辑、艺术家搜索音乐元数据。
- 识别 MusicBrainz、TheAudioDB、豆瓣音乐等来源。
- 搜索 PT 站点中的音乐分类，包括音乐专站和综合站点的音乐分区。
- 创建歌曲或专辑订阅，并复用原有的订阅刷新与下载流程。
- 读取 MP3、FLAC、M4A 等音频文件的标题、艺术家、专辑、曲序、碟号、年份、ISRC、码率、采样率和位深等信息。
- 按“艺术家/专辑/曲目”的独立格式整理音乐目录。
- 刮削并写入音频标签和内嵌封面。
- 迁移已有旁挂歌词，并按质量选择逐字歌词、逐行歌词或纯文本歌词。
- 为音乐设置独立的质量规则、优先级规则和封面代理。
- 在首页统计、搜索、探索、订阅、历史和缓存管理中展示音乐数据。
需要特别说明：MoviePilot V3 **不是音乐播放器或音乐媒体库**。它负责找到、下载、识别和整理音乐；播放、歌单、艺术家库和本地收听历史仍由专业媒体服务器负责。
### 3.2 媒体来源不再被 TMDB 等固定字段限制
V2 的许多流程会分别携带 TMDB、豆瓣、Bangumi、AniList 等 ID。这样做在来源较少时很直观，但来源增加后容易出现以下问题：
- 同一个数字 ID 在不同来源中代表不同内容。
- 影视、动漫、音乐各自发展出不同的参数和判断分支。
- 插件想增加新元数据来源时，需要修改更多宿主逻辑。
V3 将通用媒体身份统一为：
```text
媒体来源 media_source + 来源内 ID media_id
```
例如，`douban + 1295644` 和 `themoviedb + 550` 会被明确视为两个不同来源中的身份，不再只比较裸数字。
这项变化带来的用户收益包括：
- 搜索、订阅、下载、整理、历史和媒体服务器事件可以使用同一套身份规则。
- 全局搜索可以选择多个元数据来源。
- 系统可以在不同来源之间转换身份，并保留主来源。
- IMDb 成为原生媒体来源之一。
- 插件可以注册新的影视或音乐数据源，并进入来源选择器、搜索、详情、订阅和刮削流程。
- 同名、同年、来源不同的内容更不容易发生误匹配。
原有的自定义识别词和文件重命名变量仍保留历史写法，普通用户不需要因此重写全部规则。
### 3.3 搜索、下载和整理流程更容易处理异常情况
V3 对日常高频操作做了多项增强：
- 搜索站点可以按电影、电视剧、音乐等媒体类型进行筛选。
- 搜索结果会记住用户选择的排序方式。
- 添加下载时可以更明确地选择媒体类型和元数据来源。
- 无法自动识别的资源不再只能失败退出，可以由用户确认媒体信息后继续下载。
- 下载失败冷却信息会记录失败原因和下次重试时间，并支持定期清理。
- 整理失败通知可以按媒体聚合，避免同一内容的多个文件连续刷屏。
- 对无响应的 FUSE/远端挂载增加隔离，减少目录监控或整理线程被长期卡住的情况。
- 音乐和影视共用主要任务框架，但会根据媒体类型选择不同的识别、质量和整理规则。
### 3.4 AI Agent 从“能调用工具”向“可控的自动化助手”演进
V2 已经具备 Agent、MCP 和工具调用能力。V3 没有另起一套智能体，而是在原有基础上重点加强了可控性、可靠性和音乐支持：
- Agent 可以参与音乐搜索、识别、订阅、下载和整理。
- Web 端支持全屏助手，Telegram 等消息渠道可展示更丰富的 Agent 消息。
- 定时 Agent 任务会记录运行历史，重启后避免重复执行同一计划。
- 工具身份、权限和调用合同更加严格。
- 读取敏感设置时需要宿主二次确认，避免模型直接获取密钥。
- 长对话增加上下文压缩、预算观测、取消传播和异常恢复。
- 文件修改等高影响工具有更明确的调用边界。
- Agent、MCP、OpenAI 兼容接口和 Anthropic 兼容接口各自保持对应协议，不被普通 REST 包装破坏。
这些改进的核心不是“让 Agent 拥有无限权限”，而是让它在明确授权和可追踪的边界内完成更多任务。
### 3.5 插件支持虚拟分身和来源管理
V3 插件系统新增了更完整的实例与来源概念。
**虚拟插件分身**表示同一份插件源码可以创建多个运行实例，每个实例拥有独立的配置、数据、事件绑定、API 和定时服务。常见用途包括：
- 同一个通知或同步插件连接多个账号。
- 同一种能力分别服务不同目录、站点或媒体库。
- 不复制插件源码，也能保持各实例配置隔离。
V3 还增加了插件来源身份、可信来源准入、安装记录和换源能力：
- 系统可以记录插件来自哪个市场或仓库。
- 插件更新时可以判断当前安装来源。
- 前端可以绑定或切换插件来源。
- 插件安装失败或依赖变更后更容易恢复。
- 原生依赖需要重启生效时，前端会给出明确提示。
### 3.6 新增 AList、钉钉和更完整的运维入口
除音乐外，V3 还增加或完善了多项独立能力：
- 新增 AList 存储类型。
- 新增钉钉机器人通知渠道。
- 增加数据库备份策略、备份列表、校验、下载和恢复管理界面。
- 数据库结构迁移前可以自动创建备份。
- 增加数据保留期限设置，便于控制历史记录和可靠事件占用。
- 系统页面增加分阶段版本更新提示，避免后台静默更新后用户不知道是否需要重启。
- Doctor 诊断可以给出数据库备份和恢复建议。
- 首页、服务、缓存、日志、工作流和用户管理页面补充了更完整的状态与错误处理。
### 3.7 首次安装改为网页初始化管理员
V3 全新安装时，如果数据库中还没有用户，首次打开 Web 页面会进入初始化页面：
1. 创建超级管理员用户名。
2. 设置并确认密码。
3. 生成并保存 API Key。
4. 完成初始化后进入登录页。
这意味着全新部署不再需要把初始管理员密码和 API Key 写进 Compose 环境变量，也不会在启动日志中输出初始密码。
从 V2 升级的用户如果数据库中已经存在账号，会继续使用原账号，不会重新进入初始化流程。
## 4. 前端变化：保留熟悉的操作方式，增加 V3 专属入口
V3 前端仍然基于 Vue 3、Vuetify 3 和 Vite，并不是推倒重写。因此，大部分导航、卡片、对话框和设置方式仍与 V2 一脉相承。
主要变化包括：
- 新增音乐首页、音乐搜索、歌曲详情、专辑详情和艺术家详情页面。
- 搜索、订阅、探索、推荐、整理、缓存和历史页面支持音乐实体。
- 新增数据库备份管理面板。
- 插件市场支持虚拟分身、来源绑定和换源。
- 新增首次初始化页面，移除原来体量较大的全功能设置向导。
- AI 助手支持全屏显示和受保护操作交互。
- 工作流卡片和编辑器主题更简洁，动态动作配置与异常恢复更稳定。
- 下载、整理和传输进度信息的层级更清楚。
- 增加更新提示、连接状态探测和离线状态处理，服务重启时减少重复报错。
- 玻璃、透明等主题效果继续优化，并更新跨平台 PWA 图标。
- 大量核心页面增加自动化测试，降低接口调整后出现空白页或错误提示刷屏的概率。
从架构上看，前端最重要的变化不是框架升级，而是统一了媒体身份、普通 API 响应、插件实例作用域和后台刷新生命周期，使新增来源、插件分身和音乐页面不必各自实现一套特殊逻辑。
## 5. 后端架构变化：为什么 V3 更适合继续扩展
本节会出现少量技术名词，但重点解释它们对使用者意味着什么。
### 5.1 从历史大目录重构为职责清晰的分层结构
V2 中大量公共能力集中在 `core`、`helper`、`utils` 等历史目录。随着插件、Agent、音乐和多数据源增加，同一个目录中容易混合业务规则、网络请求、数据库、文件操作和运行时状态。
V3 将主程序重新划分为以下职责：
| 层次 | 通俗解释 |
| --- | --- |
| Domain | 不依赖数据库和网络的媒体识别、命名、身份等纯业务规则 |
| Application | “识别一部媒体”“保存一条订阅”等具体应用能力 |
| Chain | 把搜索、下载、整理、通知等多个能力串成完整流程 |
| Module | 下载器、媒体服务器、元数据源、通知渠道等可替换实现 |
| Adapter | HTTP、Redis、文件系统、浏览器、Rust、外部服务等技术连接 |
| DB Oper/Adapter | 数据表访问、事务和持久化实现 |
| Runtime | 配置、事件、日志、缓存、任务、插件和调度器的进程级管理 |
| Startup | 统一决定各组件如何创建、启动、重载和关闭 |
| SDK/Compat | 给新插件提供稳定入口，并为旧插件保留精确兼容映射 |
用户不会直接操作这些目录，但这项重构会影响：
- 一个模块故障时更容易定位属于网络、数据库、插件还是业务流程。
- 测试可以隔离外部服务，不必依赖真实站点或真实下载器。
- 新增存储、通知、元数据来源时不必修改所有调用方。
- 旧插件可以通过兼容层继续运行，新插件不需要依赖频繁变化的内部目录。
### 5.2 数据库事务改为“由完整业务流程负责”
V2 的部分数据操作会在较底层的方法中自行创建会话并提交。多个操作组合在一起时，可能出现“前一半已经写入，后一半失败”的情况。
V3 更强调：
- 数据模型只描述数据，不自行决定何时提交。
- 一个完整业务操作拥有一个明确的事务边界。
- 数据库成功提交后，才触发通知、事件或其它外部动作。
- 同步和异步数据库访问使用各自明确的执行路径。
对用户来说，这会减少订阅已创建但通知丢失、部分状态已更新但页面仍异常等不一致情况。
### 5.3 重要后台结果进入可靠事件队列
如果程序在“数据库已经保存，但通知或后续动作还没执行”时重启，单纯依赖内存任务可能造成遗漏。V3 为重要业务结果增加了可靠事件记录，也就是架构中的 Outbox。
当前用于增强可靠性的场景包括订阅完成、订阅删除、订阅报告、下载与整理结果、通知等。处理成功后记录才会结束；进程重启后，未完成的工作可以继续恢复。
这不是无限重试队列，也不能替代下载器自身的任务系统，但它能明显缩小“刚好在关键时刻重启”造成的状态缺口。
### 5.4 启动、重载和关闭顺序统一管理
V3 使用统一的启动组合入口管理数据库、缓存、模块、插件、调度器、目录监控、消息渠道、工作流和 Agent。关闭时按反向顺序释放资源。
这样做主要解决：
- 插件或定时任务过早启动，数据库和缓存还没准备好。
- 重载后重复注册任务、事件或 API。
- 容器停止时线程、连接和后台队列没有完成收尾。
- 不同启动方式使用不同的初始化逻辑。
V3 仍建议给容器保留足够的停止宽限时间，让后台任务和模块完成收尾。
### 5.5 API 返回格式更统一
V3 的普通 JSON REST API 统一使用以下结构：
```json
{
"success": true,
"message": "",
"data": {}
}
```
其中：
- `success` 表示操作是否成功。
- `message` 用于用户可读的状态或错误信息。
- `data` 保存真正的业务数据。
文件下载、图片、SSE、OAuth2、MCP、OpenAI 和 Anthropic 等标准协议接口继续保持原生格式。插件自有 API 也可以选择自己的明确返回模型，不会被宿主强制重复包装。
普通用户通常不会直接感知这项变化，但它减少了前端和插件把提示文字误当成业务数据的情况。
### 5.6 运行环境升级到 Python 3.14，并将 Rust 独立发布
V3 默认运行时升级到 Python 3.14 和较新的基础系统环境，主程序依赖由 `uv.lock` 锁定。相同版本在开发、测试和镜像构建中更容易得到一致结果。
Rust 加速不再由主仓临时编译，而是作为独立的 `moviepilot-rust` 包发布。它主要加速：
- 影视和音乐标题解析。
- 站点索引结果解析。
- RSS/Atom 解析。
- 资源过滤和表达式处理。
- 中文转换等高频文本操作。
标准 `moviepilot-v3` 使用 CPython 3.14，是默认稳定镜像。V3 还提供可选的 `moviepilot-v3t` 自由线程运行时，用于提升适合多线程并行的工作负载；V3t 要求 Rust 加速和原生依赖完整兼容，不建议普通用户仅为追求版本号而切换。
## 6. 插件体系变化与兼容性
### 6.1 V3 默认尽量兼容 V2 插件
V3 保留了精确的旧导入兼容层。未使用 V3 已变更合同的 V2 插件，通常可以继续运行，不需要开发者仅为了“声明支持 V3”复制一份代码。
以下类型的插件更可能需要 V3 专用版本：
- 直接读写 `tmdbid`、`doubanid` 等旧媒体身份字段。
- 直接访问 MoviePilot 数据模型或自行管理数据库会话。
- 调用已经调整职责的识别、搜索、音乐或刮削 Chain。
- 通过 HTTP 调用宿主 API，并从旧的顶层字段读取业务数据。
- 需要使用音乐、多数据源、虚拟分身或 V3t。
### 6.2 V3 插件拥有独立目录和市场索引
官方插件仓库同时保留多个代际：
```text
plugins/ + package.json 历史插件
plugins.v2/ + package.v2.json V2 专用插件
plugins.v3/ + package.v3.json V3 专用插件
```
V3 专用插件会提高主版本号，并明确最低系统版本和运行时兼容性。这样可以避免修复 V3 合同时误伤仍在使用 V2 的用户。
### 6.3 新插件优先使用稳定 SDK
V3 为插件整理了网络、缓存、日志、媒体、配置、事件、服务、数据库备份和调度等稳定 SDK。旧的 `app.core`、`app.helper`、`app.utils` 路径只通过白名单兼容，不再作为新插件的推荐入口。
这意味着宿主内部继续重构时，按 SDK 开发的插件更不容易因为文件移动而失效。
### 6.4 插件依赖保护更严格
插件和主程序仍运行在同一个 Python 环境中。V3 会检查插件声明的依赖，拒绝会降级或覆盖 MoviePilot 核心依赖的安装要求。
这会让部分依赖声明不规范的旧插件更早暴露问题，但可以避免“安装一个插件后整个主程序无法启动”的更大故障。
## 7. 站点资源与构建体系变化
### 7.1 V3 使用独立站点资源通道
V3 不再读取 V2 的站点索引包，而是使用：
```text
MoviePilot-Resources/resources.v3/
├── user.sites.v3.bin
└── sites.*.so / sites.*.pyd
```
- `user.sites.v3.bin` 保存站点搜索、分类和字段解析规则。
- `sites.*.so/.pyd` 保存按平台和 Python ABI 构建的站点认证能力。
- 运行时统一安装到主程序的 `app/application/site/` 目录。
- V2 与 V3 使用不同资源清单，不会互相覆盖。
### 7.2 站点资源从源文件到用户设备的发布链路
```text
MoviePilot-Build
站点 YAML、认证配置、解析源码、资源版本
↓ 自动构建与测试
MoviePilot-Resources/resources.v3
V3 索引包、各平台认证扩展、package.v3.json
↓ Docker 构建或运行时资源更新
MoviePilot/app/application/site
当前实例实际加载的站点资源
```
这条链路让“站点页面改版”与“主程序功能发布”可以分开处理。很多站点选择器或分类修复只需要更新资源包，不必等待整个后端发版。
### 7.3 V3 站点资源重点增加和延续了哪些能力
- 站点分类增加 `music` 等 V3 媒体类别。
- 多个 API 站点可以直接搜索音乐资源。
- 音乐专站与综合站点的音乐分区使用同一套分类规则。
- 继续支持并扩展 API Key、Token 等站点认证方式。
- 后端用户数据解析器可以自动探测 Gazelle、NexusPHP 等站点变种。
- 解析模板支持更完整的标题、文件名、标签和可选字段回退。
- 构建产物覆盖 Linux、Windows、macOS、x86_64、Arm64，以及 V3t 所需的 Python 3.14t ABI。
- 站点采集器可以生成脱敏样本，维护者可通过自动化流程匹配模板并创建待审核的适配 PR。
### 7.4 用户遇到站点问题时应如何判断
如果站点能打开但搜索不到正确分类，建议按以下顺序排查：
1. 在“设置 → 关于”确认加载的是 V3 站点资源。
2. 确认资源文件名为 `user.sites.v3.bin`。
3. 更新站点资源后重试，不要只升级前端。
4. 检查 Cookie、User-Agent、代理和站点限流设置。
5. 如果只有某个站点异常，优先判断该站点页面或 API 是否改版。
站点 Cookie、代理和限流仍由 MoviePilot 配置；资源包只负责公开的解析与分类规则。
## 8. 数据库、备份与升级边界
### 8.1 从 V2 升级到 V3 不需要手工搬迁用户数据
V3 可以继续使用 V2 的：
- `/config` 配置目录。
- SQLite 数据库。
- PostgreSQL 数据库。
- 已安装且未使用变更合同的插件。
这里的“不需要迁移”是指用户不需要另建数据库、导出再导入，也不需要更换配置目录。V3 首次启动时仍会自动执行数据库结构升级，因此升级前必须备份。
### 8.2 V3 增加迁移前自动备份和备份管理
V3 可以在数据库迁移前创建备份，并在 Web 页面中管理备份记录。备份能力包括版本信息、完整性校验、下载和离线恢复支持。
这不能替代 NAS、虚拟机或数据库服务器自身的定期备份，但可以为应用升级增加一层更接近 MoviePilot 数据结构的保护。
### 8.3 向前兼容不等于可以直接换回 V2
V2 数据库可以由 V3 自动向前升级，但 V3 写入新结构后，不能只把镜像改回 V2。原因包括：
- 通用媒体身份已经改为 `media_source + media_id`。
- V2 仍会读取的部分来源专用字段会在 V3 迁移中删除。
- V3 新增音乐、Agent、可靠事件、插件安装等表或字段。
- 部分 V3 数据无法完整转换成 V2 能理解的结构。
需要回退时，应优先恢复升级前的完整备份。确实要使用升级后的数据库回退，必须在仍运行 V3 代码时执行官方提供的 Alembic 降级，再切换 V2 镜像；不要手工修改 `alembic_version`。
### 8.4 SQLite 与 PostgreSQL 的定位
V3 仍支持 SQLite 和 PostgreSQL：
- 小型、单用户或轻负载实例可以继续使用 SQLite。
- 任务多、并发高、历史数据量大或重视数据库级备份的实例更适合 PostgreSQL。
- V3 优化了 SQLite 到 PostgreSQL 的可选转换流程，但这与 V2 升级 V3 是两件事。
## 9. 部署与升级方式的变化
### 9.1 Docker 镜像
V3 使用独立镜像：
```text
jxxghp/moviepilot-v3:latest
```
标准 V3 是普通用户的默认选择。自由线程版本使用独立的 V3t 镜像，只有在确认插件和原生依赖兼容时才建议使用。
从 V2 切换时，不能只在 V2 容器中点击“重启升级”。应先把 Compose 中的镜像改为 V3 镜像，再拉取并重建容器，同时继续映射原 V2 的配置目录。
典型流程是：
```bash
docker compose pull moviepilot
docker compose up --force-recreate -d moviepilot
```
执行前请确认 Compose 文件中的 `moviepilot` 服务已经指向 V3 镜像。
### 9.2 本地源码与 CLI
V3 本地运行要求 Python 3.14+，优先使用项目 `.venv` 和锁定依赖。CLI 安装会同步：
- V3 后端源码。
- V3 前端发布包。
- `resources.v3` 站点资源。
- 与当前运行时匹配的 Rust 和原生依赖。
如果本地源码存在未提交修改，更新命令会停止，避免覆盖用户代码。
## 10. 升级前后的建议检查清单
### 10.1 升级前
- 备份完整 `/config` 目录。
- SQLite 用户单独确认 `user.db` 已复制且可以读取。
- PostgreSQL 用户执行并验证 `pg_dump`。
- 记录当前 V2 镜像标签、数据库类型和目录映射。
- 查看关键插件是否已有 V3 专用版本或明确兼容说明。
- 特别检查直接访问媒体 ID、数据库或宿主 API 的插件。
- 确认宿主平台可以运行 V3 对应架构的镜像。
### 10.2 首次启动后
- 确认原账号可以登录，订阅、站点、目录和下载器配置仍在。
- 检查数据库迁移日志和备份记录。
- 在“设置 → 关于”确认后端、前端和站点资源均为 V3。
- 手动执行一次站点测试和影视搜索。
- 选择一个已知资源测试下载与整理。
- 检查通知渠道和媒体服务器刷新。
- 逐个启用或验证关键插件，留意旧导入、依赖冲突和 V3 合同提示。
- 准备使用音乐时，先测试一个专辑或单曲，再扩大订阅范围。
### 10.3 发现异常时
- 不要立即删除旧备份。
- 不要直接修改数据库版本号。
- 先确认问题属于后端、前端、插件还是站点资源。
- 页面异常时同时检查后端 API 日志，不要只清浏览器缓存。
- 单站点异常时优先更新 V3 资源包。
- 插件异常时先停用该插件验证主程序，不要直接覆盖插件数据目录。
- 数据库迁移失败时保留当前日志、数据库和镜像版本，按官方恢复说明处理。
## 11. 哪些用户最适合升级 V3
建议优先升级：
- 希望统一管理影视与音乐下载整理的用户。
- 使用多个元数据来源，或希望插件扩展新来源的用户。
- 插件较多，希望使用虚拟分身、来源绑定和依赖保护的用户。
- 重视数据库备份、任务恢复和长期稳定运行的用户。
- 希望使用 AList、钉钉机器人、增强 Agent 或新站点资源的用户。
建议先评估再升级：
- 高度依赖私有插件，且插件直接访问宿主数据库或内部目录。
- 使用自定义镜像、旧 Python 环境或自行编译原生扩展。
- 没有可验证备份，且无法接受停机排查。
- 必须随时无损切回 V2，但尚未准备数据库降级或备份恢复方案。
## 12. V3 当前仍不负责什么
为了避免对大版本能力产生误解，以下功能不属于当前 V3 核心范围：
- 内置电影、电视剧或音乐播放器。
- 完整音乐媒体库、歌单管理和跨服务器歌单同步。
- 替代 qBittorrent、Transmission、Navidrome、Emby、Jellyfin 或 Plex。
- 自动保证所有历史私有插件无需适配。
- 在没有备份的情况下保证 V3 数据无损回退到 V2。
- 仅通过升级前端解决后端、资源包或数据库问题。
## 13. 各仓库在 V3 中分别负责什么
| 仓库 | V3 职责 |
| --- | --- |
| MoviePilot | 后端、数据库、插件宿主、Agent、工作流、API 和运行时 |
| MoviePilot-Frontend | Web 界面、音乐页面、插件 UI、仪表盘和模块联邦组件加载 |
| MoviePilot-Plugins | 官方插件源码、V1/V2/V3 市场索引、图标、测试和发布 |
| MoviePilot-Build | 站点 YAML、认证配置、资源版本和构建流程 |
| MoviePilot-Resources | `resources.v3` 站点索引、认证扩展和资源清单 |
| MoviePilot-Rust | 标题、索引、RSS、过滤和文本处理的 Rust 加速包 |
| MoviePilot-Wiki | 面向用户的安装、升级、配置和故障处理说明 |
## 14. 延伸阅读
- [V3 后端架构设计](architecture-overview.md)
- [V3 与 V3t 运行时边界](v3t-runtime-governance.md)
- [本地 CLI 使用说明](cli.md)
- [Doctor 诊断说明](doctor.md)
- [PostgreSQL 部署说明](postgresql-setup.md)
- [MCP API 说明](mcp-api.md)
- [MoviePilot 官方 Wiki](https://wiki.movie-pilot.org)
- [V3 插件开发与迁移文档](https://github.com/jxxghp/MoviePilot-Plugins/tree/main/docs)
---
本文是大版本能力和架构变化总览，不替代具体版本的 Release Notes。后续 V3 小版本新增功能时，应在保持 V2/V3 核心边界准确的前提下更新本文，并同步标注更新时间。