MoviePilot 部署教程：3 次关键设置，一次配好 NAS 媒体库自动整理
【免费下载链接】MoviePilotNAS媒体库自动化管理工具项目地址: https://gitcode.com/gh_mirrors/mo/MoviePilot
MoviePilot 是一款面向 NAS 的媒体库自动化管理工具：新下载的资源它负责识别、重命名、归档，并同步元数据到 Emby、Jellyfin、Plex 等媒体服务器。对想做 NAS 媒体库管理、又讨厌手动整理的人来说，这篇文章给出从安装到命名规则一次配好的完整路径。
它替你干了什么
整理环节。你手动做的流程是：下载完种子，打开文件管理器，逐个改文件名、建目录、搬进对应位置。有了 MoviePilot，整理这一步自动发生——资源下载完成后它按你设定的规则重命名并归档，你只在通知里看到一条"已整理"。
刷新环节。你手动做的是：整理完到 Emby 里点"扫描媒体库"，然后盯着进度条。MoviePilot 在整理完成后自动触发媒体服务器刷新，库里的海报和剧集信息直接出现。
追更环节。你手动做的是：每周打开站点看订阅的资源有没有更新，手动下载。MoviePilot 的定时订阅刷新会在后台跑，更新了就按规则下载、整理、入库，全程不用你管。
识别环节。资源名里那些[2160p][IMAX Enhanced][Remux]之类的标记，MoviePilot 的识别引擎会逐项解析，相当于一个会自己对片单的馆员：它能分辨导演剪辑版、重制版等特殊版本，并据此生成正确的文件名，而不是把整段标记糊在标题后面。
按你的情况选一条部署路
三种常见处境，最短路径各不相同，各选一条即可。
全新 NAS，从零开始
官方推荐 Docker 部署：一条 compose 拉起jxxghp/moviepilot-v3镜像，映射好配置目录、下载目录和媒体目录，首次打开网页时创建管理员账号和 API Key，整个过程不需要碰命令行。Docker 环境的 Compose 示例与环境变量，以官方 Wiki 的 Docker 文档为准。
已有杂乱媒体库，想先跑起来再整理
适合用本地 CLI 源码模式。一键安装命令单独放这里，它会自动检测系统、装好 git/curl/Python 3.14+、克隆仓库、安装依赖并创建全局moviepilot命令：
curl -fsSL https://raw.githubusercontent.com/jxxghp/MoviePilot/v3/scripts/bootstrap-local.sh | bash装完执行moviepilot status确认前后端都在运行，然后进 Web 界面把已有目录挂上，批量整理放到空闲时段分批做（后面会讲）。完整命令列表见 docs/cli.md。
媒体主要放 AList、网盘或远端挂载
部署方式与上面相同，区别在目录挂载环节：MoviePilot 的存储层除本地目录外，还支持 AList、rclone、SMB 和 U115，对应实现都在 app/modules/filemanager/storages/。把网盘目录作为媒体库目录挂进来，识别和命名规则与本地盘一致，只是文件读写走网盘协议，大批量整理时速度要预期低一些。
装完后的三次关键设置
装完只是起点，真正让 Media 库跑起来的只有三次设置。
第 1 次：确认 Web 入口与端口
Docker 部署把容器端口映射到宿主机后，浏览器访问http://<NAS_IP>:端口即可；首次打开按提示创建超级管理员和 API Token。CLI 模式下安装脚本默认已启动服务，moviepilot logs里能看到前后端各自的启动日志。端口被占用时改映射即可，无需改程序本身。
第 2 次：添加媒体目录与下载目录
向导或"设置 → 目录"里分别填两类路径：下载目录是下载器放资源的地方，媒体库目录是整理后的成品存放地。两者映射好，下载-整理链路才闭合。已有媒体库的用户可以把旧目录直接挂为媒体库，让 MoviePilot 在识别时按来源与编号建立媒体身份，避免同名影片互相串号。
第 3 次：命名规则
规则编辑器在设置页，电影、剧集、动漫分别配置。一个覆盖三项的最小环境变量配置示例（Docker 场景，变量写法见官方 Wiki）：
# .env 最小配置 PORT=3000 DOWNLOAD=/volume1/Downloads MEDIA_PATH=/volume1/Media # 命名规则建议在 Web 界面规则编辑器中配置，可实时预览效果命名变量沿用历史写法，升级版本不用重写全部规则，这一点在 docs/v2-to-v3-overview.md 里有说明。
命名规则模板怎么写
模板的本质是"变量 + 固定分隔符"。下面三个是稳妥的起点，每个后面说清楚它实际生成什么。
电影：
{title} ({year}) [resolution codec]/movie.nfo生成的效果：媒体库/电影/流浪地球 (2023) [2160p]/流浪地球 (2023).mkv——一部电影一个目录，目录和文件名都带年份，同名不同年的影片不会混在一起。
剧集：
{title}/Season {season:02}/{title} - S{season:02}E{episode:02} - {episode_title}生成的效果：媒体库/电视剧/绝命毒师/Season 01/绝命毒师 - S01E01 - 灰冰.mkv——季目录按两位数编号排序，文件名带集名，媒体服务器的集数匹配成功率最高。
动漫：
{title} [{year}]/第{season:02}话/{title} - {season:02}x{episode:02}生成的效果：媒体库/动漫/进击的巨人/第01话/进击的巨人 - 01x01.mkv——用"话"而不是"集"，符合动漫观看习惯，也避开部分服务器对SxxEyy格式的误判。
保存前用编辑器里的预览功能输一个真实资源名验证一遍，比整理完再回滚省事得多。
三个最容易踩的坑
现象：资源下载完却停在下载目录，没有进媒体库。多半是下载目录或媒体目录没在设置里正确填写，或两个目录指向了同一位置。进设置页核对路径映射，确认下载目录指向下载器实际写入的位置（容器内路径与宿主机路径要对应），媒体目录指向成品库，然后对滞留资源执行一次手动整理。
现象：文件整理进库了，媒体服务器里看不到或没有海报。多半是整理后没触发刷新，或 NFO 元数据没生成。先确认媒体服务器配置指向的是整理后的媒体库根目录而不是下载目录，然后手动扫描一次媒体库；若 NFO 缺失，检查刮削设置并让 MoviePilot 重新刮削该目录。
现象：订阅资源反复下载失败。多半是站点 cookie 失效或资源已失效。MoviePilot 会记录失败原因和下次重试时间，在订阅管理里看具体是哪一步失败；cookie 类问题去站点重新登录获取，资源失效则等待下一轮订阅刷新自动替换。CLI 模式下moviepilot doctor可以顺手体检一遍运行环境。
媒体库大了以后怎么提速
先说一个前提：MoviePilot V3 的元数据解析等重活由moviepilot_rust扩展加速，随依赖一起安装；如果前端"高级设置 - 实验室"里的 Rust 开关是灰的，说明扩展没加载成功，moviepilot install deps重装一次再看。
分批是最有效的策略：几千部影片不要一次全量整理，按"电影一批、剧集一批、动漫一批"来，每批之间让媒体服务器完成刷新再开始下一批。整理窗口放在 NAS 空闲时段，避免与刮削、同步任务抢 IO。
整理期间重点看这几个文件，都在配置目录的logs/下（moviepilot config path可查位置）：
moviepilot status # 服务是否都活着 tail -f <Config Dir>/logs/moviepilot.log # 主日志：整理/刮削错误 tail -f <Config Dir>/logs/moviepilot.stdout.log # 后端启动期问题 tail -f <Config Dir>/logs/moviepilot.frontend.stdout.log # 前端异常更细的排障入口在 docs/doctor.md 和 docs/cli.md，Docker 部署的完整配置则以官方 Wiki 为准。
把下载目录、媒体目录和命名规则这三处核对无误后，MoviePilot 的基本工作就闭环了。现在可以打开 Web 界面的"设置 → 目录"页检查一遍映射，或跑一条moviepilot status确认服务在线。
【免费下载链接】MoviePilotNAS媒体库自动化管理工具项目地址: https://gitcode.com/gh_mirrors/mo/MoviePilot
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
