我 NAS 上跑 MoviePilot 大概有大半年了, 一开始是 v1, 后来 v2 出了之后按官方说法”重新设计”, 直接重装了一套。最近 v2.15.0 (7/23) 和 v2.15.1 (7/26) 接连发了, 我趁着周末滚了一下版本, 顺手把这一两年的折腾写一下, 给同样在 NAS 上跑 MP 的人当个升级参考。
不过提前说清楚: 这篇文章不涉及具体 PT 认证站、订阅工具、IP 段那些, 只讲 v2 升级到 v2.15 这一路上我自己踩过的几个坑, 以及 v2.15 我比较看重的三个新东西。NAS 媒体库自动化本身是个有合规模板的事, 自己能用就行, 别上面对照着来就行。
从 v1 到 v2: 配置文件不兼容, 数据库也得重做
v2 出来的时候我心里其实有点抗拒——”我 v1 跑得好好的为什么要重装”。但官方在 README 里写得很明白: V1 停止功能更新, V2 用独立镜像, 配置和数据库都不向前兼容。所以无论你 v1 装没装过, v2 都要重新配置。
我最后是这么干的: 先把 v1 容器停掉, /config 整个目录备份到一个单独路径, 然后 v2 拉了 jxxghp/moviepilot-v2:latest 镜像, 全新建了个空目录当 config, 不要去复用 v1 的配置。v2 第一次启动会生成一份干净模板, 在 WebUI 里把下载器、媒体库、消息推送这些基础项配好, 业务才真的能跑起来。
这一步我栽过一次: 我图省事直接把 v1 的 user.db 复制过去, 结果 v2 启动直接报 schema 错, 折腾半天才意识到两张表结构不一样, 老老实实删了重新建。如果你跟我一样懒得读 changelog, 这里能省你 20 分钟。
还有个事: v2 第一次启动完, WebUI 默认 3000 端口, 初始管理员密码只会从启动日志里输出一次, 错过了就去 /config 目录删 user.db 重启。密码输出很不起眼, 在一堆 INFO log 里面, 我当时是 docker logs -f 一路翻才找到的。
v2 跟 v1 在结构上最不一样的两件事
第一是前后端分离: 后端是 FastAPI, 前端是 Vue 3, 部署时用两个端口, 官方默认 3000 (Web) 和 3001 (API)。这意味着如果你有反向代理, 需要分别代理这两个端口, 或者直接 host 网络模式让 MP 内部 nginx 自管。我自己图省事用了 host 网络, 缺点就是端口和宿主机共享, 需要自己确保不冲突。
第二是数据源和媒体服务器之间, 引入了一个”统一媒体来源身份”的概念。以前 v1 时代, 一个资源从订阅、搜索、下载到入库, 不同环节用的是不同 ID (BT 种子 ID、TMDB ID、豆瓣 ID 混着用), 经常出现”明明搜到了却入不了库”或者”重复订阅”的尴尬。v2.15 这次专门发了个 PR (#6129) 把这条链路统一, 引入 explicit media ids, 文件刮削不再靠”启发式猜”, 看起来顺多了。
但说真的, 我用下来的感受是 v2 上手比 v1 陡峭一些, 主要是 WebUI 把订阅/搜索/整理/插件这些全拆开了, 第一次进去会找不到东西在哪。习惯之后其实效率是更高的, 缺点是默认中文 UI 的措辞, 有些比英文还难懂, 比如”识别增强”和”二次识别”我在 v1 时代都没搞明白, v2 文档里写了但要细看。
v2.15 我升级时比较关心的三件事
v2.15.0 (7/23) 和 v2.15.1 (7/26) 间隔三天, 体量都不算大, 但我盯着的三块改进基本都到位了, 顺手画了张图给自己备忘:
第一个是 AI Agent + Skills。v2 本身自带智能体能力, 配好模型后你能在 WebUI 直接用自然语言说”帮我订阅最近三个月的科幻剧, 分辨率 1080p 起”, 它会自己跑完整套流程。但 v2.15 把这块正式从内部能力升级成了”可以被外部 agent 调用的 Skills 集”, 仓库里多了个 skills/ 目录, 官方推荐用法是 npx skills add https://github.com/jxxghp/MoviePilot 把 MP 的操作能力装到你自己的 Claude / Cursor 里。这对那些本地跑模型的人特别有用——你的 agent 不再是”只能聊天”, 是能直接动你的媒体库。
第二个是 MCP 端点。v2.15.0 把 MP 的能力也通过 Model Context Protocol 暴露出来了, 路径是 /api/v1/mcp, 鉴权走 API_TOKEN (跟 WebUI 共用)。我用 Claude Desktop 连了一次, 工具列表里能搜到搜索/订阅/下载/整理/媒体刷新这些, 大致能聊个大概。对, 这跟 Skills 是两个不同入口, Skills 是给 agent 主动”用” MP, MCP 是给 MP 主动”接” agent——我没完全想清楚什么场景该用哪个, 但同时存在说明官方在两条路之间还没下注。
第三个是 Btrfs FSID 去重。这个比较冷门, 是 v2.15.0 里的 PR #6141, 显式 opt-in, 不开就没影响。原理是 Btrfs 文件系统有个 FSID 特性, 可以在不创建硬链接的情况下, 让两个路径共享同一份物理数据——区别于硬链接, 你修改副本不影响原文件, 原文件继续做种也没问题。这对 PT 用户应该算是个好消息, 但前提是你的媒体库所在盘必须是 Btrfs 格式, ext4 / xfs 不可用。我自己是 ext4, 所以这块只能看着眼馋。
升级的时候我踩了哪些坑
第一坑是 MOVIEPILOT_AUTO_UPDATE 这个环境变量。如果你设成 true 或 dev, 容器每次重启都会去拉最新版。我一开始为了省心设了 release, 结果某次重启直接跳了两个小版本, 配置文件 schema 不一致, 启动失败。改回 false 自己手动滚版本, 反而更稳。文档说 release 是”只滚 release tag”, 但实操上还是会有让你 surprised 的时候。
第二坑是代理配置。MP 很多资源站 (themoviedb 之类的元数据) 在国内访问不畅, PROXY_HOST 必须填, 但只支持 http(s)://ip:port 或 socks5://user:pass@host:port 两种格式, 不支持 pac:// 或 file://。我一开始想偷懒用 PAC 文件路径, 启动后一直在重试, 翻 issue 才意识到这个限制。最后老老实实填了个 socks5 代理就 OK 了。注意: 代理填错不影响启动, 但订阅/搜索会一直卡在 timeout, 日志里只能看到 ConnectionError, 这个错比较隐蔽。
第三坑是插件和 PostgreSQL 兼容。MP 默认 SQLite, 但如果你想给 v2 切到 PostgreSQL (官方有 docs/postgresql-setup.md 写流程), 部分插件在 v2.15 之前对 PG 的布尔字段写入有类型错误 (issue 里修复记录是 v2.15.0 之前的 PR #5979 修过一波)。我装了几个社区插件, PG 模式下有一两个会报”期望 boolean 拿到 integer”, 当时直接退回 SQLite 就好了。如果你打算用 PG, 建议先装齐插件再切换, 别反过来。
插件生态: 300+ 真的够用, 但要挑
官方数据是 300+ 插件 (官网首页写的是这个数, 没去严格数), 覆盖下载器 (qBittorrent/Transmission/rTorrent)、媒体服务器 (Plex/Emby/Jellyfin)、元数据源 (TMDB/豆瓣/AniList/Fanart)、消息渠道 (微信/QQ/Telegram/Slack/Discord) 这几大类。我自己的组合是 qB + Emby + TMDB + Telegram 推送, 没踩过什么坑, 订阅→下载→整理→通知这条链路跑得很顺。
插件市场按分类浏览, 一键装不用重启, 这个体验比 v1 进步明显。但插件质量参差, 有些是”作者弃坑”的状态, 装上能用但不会跟进 MP 主版本, 升 MP 的时候这些插件就容易炸。我的建议是只用官方推荐的几个核心插件 + 自己确实需要的, 别看到 300+ 就装 50 个, 维护成本比省事大。
我现在怎么看 MoviePilot
说点主观的: v2 比 v1 在架构上更现代, 但学习曲线更陡。我不太推荐纯小白一上来就 v2, 除非你愿意读文档。v1 的好处是简单粗暴, 配置文件直接编辑, 出了问题 grep 一下日志就能定位。v2 把一切都收进 WebUI 之后, 排障反而更依赖 GUI 操作, 偶尔会有”我知道有 bug 但找不到入口改”的情况。
v2.15 这次的几个改动 (统一媒体来源身份、AniList 集成、显式媒体 ID 刮削、MCP/Skills 暴露) 我觉得方向是对的, 但对老用户来说更像是”修复”而不是”颠覆”。Btrfs FSID 去重和 AI Agent 这两个能力是真正有想象力的, 但前者受文件系统限制, 后者需要你有一个能稳定调用的模型, 都不算开箱即用。
我的结论: 如果你已经在 v2.14.x 上跑得很顺, v2.15.1 这次升级值得做, 改动幅度不大, 主要修 bug + 加几个有意思的入口; 但如果你的 MP 只是个下载器调度器, 没怎么用 WebUI 也没接 agent, 那这次升级的体感不强, 等下一个 v2.16 再看也行。
对了, 官方在 README 里特别强调了一句”请勿在任何国内平台宣传该项目”, 所以我这边写的是技术向, 不发资源站清单也不发认证教程, 单纯讲工具和升级过程。