一键部署MoviePilotV2实现NAS全自动追剧

MoviePilotV2 自动化部署

仓库简介

NAS 上搭 MoviePilot + qB + Emby 这一套，手动部署往往要在多个容器、目录、Web 页面之间来回折腾；某宝某鱼找人代部署通常收费不低。本仓库用脚本把部署与初始化串成一条流水线，尽量做到少人工介入。

主要功能：

• 一键部署媒体栈：生成 Docker Compose、.env与目录结构，启动 MoviePilot、双 qB、Emby、ChineseSubFinder 等容器
• 组件自动初始化：依次完成 qB WebUI、Emby 媒体库、MoviePilot 下载器/规则/分类、ChineseSubFinder 配置
• 预置目录与整理规则：下载区与媒体库按类型、地区划分，MoviePilot 自动分类并整理入库
• Emby 开箱即用：批量建库、首页排序、库选项同步；挂载仅暴露最终媒体目录，不暴露下载临时目录
• 部署前检查与权限：Docker / Compose 环境校验、统一密码规则、目录权限修正

适合：新搭一套 MoviePilot V2 媒体栈、希望少手工配置的场景。旧库迁移不在本仓库范围内。目录与规则细节见下文「目录与规则速查」。

推荐顺序：§1 准备 → §3 生成目录 → §4 启容器 → §5 网页向导 → §6 写.env→ §7 init-qb → §8 init-emby → §9 init-mpv2 → §10 init-csf → §13 验证 → §15 插件（可选）

以下路径默认根目录为/volume1/media-data；Emby 媒体库默认按二级地区建库。

目录与规则速查

1. 安装脚本创建的文件夹

python3 mpv2-install.py会创建下载目录与媒体库目录（--init-mpv2还会补建部分媒体子目录）。

下载目录

媒体库目录

downloads/private、media/小电影面向非常规发行影片，所以无法自动刮削整理，需自行整理入库；也可搜索或自行实现第三方插件实现对非常规影片的刮削整理，刮削逻辑也比较简单，扫描目录，通过ffmpeg生成缩略图，有条件的通过AI，没条件的生成简单媒体信息转移入库即可。

2. Emby 媒体库与文件夹

python3 mpv2-install.py --init-emby默认创建以下媒体库（可在.env用EMBY_LIBRARY_MODE=primary切回一级建库）。

按地区拆分的库（电视节目 / 电影）

一级库（无地区子目录）

私享影库（建议单独做账号权限）

3. MoviePilot 转移规则

python3 mpv2-install.py --init-mpv2写入的整理策略摘要如下。

全局 Transfer 设置

目录规则（资源目录 → 媒体库）

每条带地区的分类均有两套规则：downloads/media（下载器监控）和downloads/manual（手动目录监控，规则名前缀手动-）。

兜底规则

不在 MoviePilot 规则内

• media/小电影：无对应转移规则
• downloads/private：不参与整理

1. 前置准备（NAS）

1.1 网络环境

部署前确认 NAS 网络环境满足：

1. 上网环境：能稳定访问 Docker Hub、GitHub、TMDB 等海外服务（镜像拉取、MoviePilot 插件/索引、刮削元数据均依赖外网）。
2. 可拉取 Docker Hub 镜像：Container Manager / Docker 已配置可用镜像源或代理，能正常docker pull（首次docker compose up需下载多个镜像）。

上网环境改造可通过nas安装openwrt虚拟机，虚拟机安装服务插件，然后将nas网关设置为虚拟机IP，这样通过旁路由方式实现上网环境改造

1.2 共享目录

先在 NAS 系统里创建 1 个共享文件夹，作为媒体数据根目录。

建议：

• 共享文件夹名：media-data
• 挂载路径：/volume1/media-data

该目录会存放：

• 下载目录：/volume1/media-data/downloads
• 最终媒体库：/volume1/media-data/media

1.3 Docker 支持

在 NAS 上确认：

1. Docker / Container Manager 可用，且当前用户可执行docker（脚本启动时会自动检查 Docker 权限与 Compose 支持）。
2. 有可执行 Python3 环境。
3. 当前用户对/volume1/docker和/volume1/media-data有读写权限。

建议目录：

/volume1/docker/media-stack /volume1/media-data

2. 脚本说明

进入脚本目录：

cd/path/to/mpv2/install

当前脚本：

• mpv2-install.py
• init-qb.py
• init-emby.py
• init-mpv2.py
• init-csf.py

插件配置文档（见 §15，需在插件市场安装后手工填写）：

插件配置/ ├── 站点认证及站点添加.md ├── ChineseSubFinder插件配置.md ├── 目录实时监控插件配置.md ├── 媒体库刮削插件配置.md └── 站点刷流插件配置.md

2.1 安装脚本参数表

mpv2-install.py常用参数如下：

注意：

• --password与--moviepilot-password/--qb-media-password/--qb-brush-password/--csf-password互斥。
• 所有脚本管理的密码（含--postgres-password/--redis-password）统一规则：仅英文大小写、数字及!@#%-*（不支持_、$等符号）；校验逻辑见password_utils.py。
• --init-qb、--init-emby、--init-mpv2、--init-csf前需先docker compose up -d，且容器处于运行状态。
• --init-mpv2前需先完成--init-qb和--init-emby，且.env中QB_INITIALED=true、EMBY_INITIALED=true。
• NAS 上建议用root执行安装脚本，以便正确设置目录所有者（PUID/PGID）；非 root 时可能只能改权限、不能chown。

2.2--github-token说明

MoviePilot 安装插件、拉取 GitHub 上的规则/资源时会访问 GitHub API。未配置 Token 时容易触发匿名 API 限流，表现为插件市场加载失败、索引更新超时等。

获取方式: GitHub → Settings → Developer settings → Personal access tokens → 生成classictoken；勾选public_repo（只读公开仓库一般够用）
可以通过–github-token将token写入.env文件，由脚本自行填充到moviepilot设置中，也可自行在moviepilot中设置

示例：

# 初次安装时一并写入python3 mpv2-install.py--password'YourStrongPassword'--github-token'ghp_xxxxxxxx'# 已安装后补写：编辑 .env 增加 GITHUB_TOKEN=...，再重新初始化 MoviePilotpython3 mpv2-install.py --init-mpv2

2.3--host-ip说明

--host-ip只在**--init-qb/--init-emby/--init-mpv2**时使用；初次生成目录（§3）不需要。

脚本在宿主机上通过「NAS 局域网 IP + 端口映射」访问各服务 API，与容器内 Docker 网络地址（如qb-media:7097）不同。

未指定设备内网IP时，脚本会自行探测并输出探测结果，如果探测失败请通过–host-ip指定

注意：--host-ip只影响初始化脚本怎么连 API；MoviePilot 连接 qB/Emby 走的是 Docker 内网地址（.env里MP_QB_MEDIA_HOST=http://qb-media:7097等），与--host-ip无关。

3. 一键生成目录与 compose

执行初始化（会生成目录、.env、docker-compose.yml）：

# 方式1：统一设置 qb-media、qb-brush、MoviePilot 的密码；用户名统一为admin（推荐）；python3 mpv2-install.py--password'YourStrongPassword'# 方式2：用户名统一为admin，分别设置密码python3 mpv2-install.py\--moviepilot-user admin\--moviepilot-password'MpPassword'\--qb-media-password'QbMediaPassword'\--qb-brush-password'QbBrushPassword'

如需指定路径：

python3 mpv2-install.py\--stack-dir /volume1/docker/media-stack\--data-dir /volume1/media-data\--moviepilot-user admin\--moviepilot-password'MpPassword'\--qb-media-password'QbMediaPassword'\--qb-brush-password'QbBrushPassword'

说明：

• --password只统一设置密码，用户名统一为 admin；同时写入 CSF 密码。
• MoviePilot 用户名通过--moviepilot-user设置（默认admin）。
• --password不能和--moviepilot-password/--qb-media-password/--qb-brush-password/--csf-password同时使用；所有密码参数均须符合统一字符规则（A-Za-z0-9!@#%-*）。
• 首次安装若计划使用插件市场，可加上--github-token（见 §2.2）。

4. 启动容器

cd/volume1/docker/media-stackdockercompose up-d

启动后服务包括：

5. 首次网页初始化

只需要对emby做webui的手动初始化；

5.1 Emby

先内网打开http://NAS-IP:7096Emby webui 网页 选择语言等完成首次向导并创建管理员账号：

6. 配置.env关键项

编辑：

/volume1/docker/media-stack/.env

在--init-emby之前，必须写入 Emby 管理员账号和密码（§5.1 向导里创建的）：

EMBY_USER=admin EMBY_PASSWORD=EmbyPassword

7. 初始化 qB

容器运行中执行：

python3 mpv2-install.py --init-qb

说明：

• 首次启动从容器日志读取 qB 临时密码并完成 WebUI 初始化。
• 若日志中已无临时密码，会回退使用.env中的QB_MEDIA_PASSWORD/QB_BRUSH_PASSWORD；能登录则视为已初始化，只更新配置、不改密码。

完成后会写入：

QB_INITIALED=true QB_MEDIA_API_KEY=... QB_BRUSH_API_KEY=...

8. 初始化 Emby 媒体库与 API Key

确认.env已配置EMBY_USER、EMBY_PASSWORD后执行：

python3 mpv2-install.py --init-emby

脚本会按固定顺序创建二级媒体库，并为所有 Emby 用户写入首页排序：

真人电影{地区} → 真人剧集{地区} → 动漫电影{地区} → 动漫剧集{地区} → 综艺{地区} → 纪录片{地区} → 私享影库{地区} → 短剧 → 小电影

地区顺序：大陆 → 港澳台 → 日韩 → 欧美 → 东南亚 → 其他地区（可通过.env的EMBY_REGIONS调整列表，排序仍按此优先级）。

同时会为脚本管理的全部媒体库同步LibraryOptions（新建与已存在库均适用）：

• 元数据/图片语言：zh-CN，国家：CN
• 实时监控：开
• 字幕下载语言：chi、zho；不随媒体保存外挂字幕（由 CSF 处理）
• 私享影库 / 小电影：启用成人元数据（EnableAdultMetadata）

完成后会写入：

EMBY_INITIALED=true EMBY_API_KEY=... # 若脚本自动创建成功

9. 初始化 MoviePilot（下载器/媒体服务器/目录规则）

确保.env里QB_INITIALED=true且EMBY_INITIALED=true后执行：

python3 mpv2-install.py --init-mpv2

完成后建议重启 MoviePilot，使category.yaml生效：

dockerrestart mpv2-moviepilot

10. 初始化 ChineseSubFinder（字幕）

建议在--init-emby完成后执行（需.env中已有EMBY_API_KEY）。脚本会写入chinesesubfinder/config/ChineseSubFinderSettings.json，跳过 Web 向导，并配置：

• WebUI 账号（CSF_USER/CSF_PASSWORD）
• API Key（CSF_API_KEY，供 MoviePilot 插件调用）
• 电影 / 连续剧扫描目录（容器内/media/...）
• Emby 联动：从 Emby 拉取近期入库视频并自动补字幕

python3 mpv2-install.py --init-csf --csf-user admin --csf-password'YourCsfPassword'

也可与安装时统一密码：

python3 mpv2-install.py --init-csf--password'YourStrongPassword'

脚本固定写入以下项（不通过.env配置）：

• 电影目录：/media/真人电影、/media/动漫电影、/media/小电影、/media/私享影库
• 连续剧目录：/media/真人剧集、/media/动漫剧集、/media/综艺、/media/纪录片、/media/短剧
• Emby 联动：启用，http://emby:8096，路径映射{DATA_DIR}/media→/media
• API Key：启用，写入.env的CSF_API_KEY
• 目录扫描间隔：@every 6h

.env会写入：CSF_USER、CSF_PASSWORD、CSF_API_KEY、CSF_INITIALED=true（EMBY_API_KEY由--init-emby写入）。

完成后会重启mpv2-chinesesubfinder。WebUI：http://NAS-IP:7035。

新入库补字幕依赖Emby API 联动 + 定时扫目录，无需 MoviePilot 额外插件。若希望在整理完成瞬间也触发补字幕，可安装 MoviePilot「ChineseSubFinder」插件，见 插件配置/ChineseSubFinder插件配置.md。

11. 目录与挂载规则核对

详细目录、Emby 库、MoviePilot 规则见文首「目录与规则速查」。此处仅列挂载要点：

挂载原则：

1. MoviePilot、qB 可访问/volume1/media-data。
2. Emby 只映射/volume1/media-data/media（看不到downloads）。
3. ChineseSubFinder 只处理/media（对应/volume1/media-data/media）。

12. 常用访问端口

CookieCloud（MoviePilot 内置，浏览器插件同步 PT Cookie）：

http://NAS-IP:9443/cookiecloud/

13. 验证清单

1. docker compose ps全部容器Up。
2. MoviePilot 能连接 qB 与 Emby。
3. Emby 只看到最终媒体目录，不看到downloads。
4. 订阅下载进入downloads/media，整理后进入media对应分类目录。
5. qB-media 分类media/manual/private路径正确。
6. 私享影库、小电影库在 Emby 中已创建；私享影库已对普通账号隐藏权限。
7. ChineseSubFinder WebUI 可登录，CSF_INITIALED=true，.env含CSF_API_KEY，Emby 联动已启用。

14. 常用维护命令

停止：

python3 mpv2-install.py--stop

清理（会删除 compose 配置、服务数据目录、downloads下内容；**media媒体库需手动输入 Y 才删除**）：

python3 mpv2-install.py--clean

重建后重新启动：

python3 mpv2-install.pycd/volume1/docker/media-stackdockercompose up-d

15. MoviePilot 推荐插件（可选）

脚本不会自动安装插件。建议完成 §9 init-mpv2、§10 init-csf 且 §13 验证通过后，先按 站点认证及站点添加.md 完成 PT 站点配置，再按需安装下列插件并参照插件配置/目录文档填写。

建议安装顺序：

1. 完成 §9 init-mpv2，§10 init-csf，§13 验证日常下载与整理正常 2. 配置 PT 站点 → 按 插件配置/站点认证及站点添加.md（认证、添加站点、RSS、订阅） 3. （可选）整理完成立刻补字幕 → 安装「ChineseSubFinder」插件，按 插件配置/ChineseSubFinder插件配置.md 配置 4. 需要手动整理 → 安装「目录实时监控」，按 插件配置/目录实时监控插件配置.md 配置 5. 需要刷流保种 → 安装「站点刷流」，按 插件配置/站点刷流插件配置.md 配置 6. 历史媒体缺元数据 → 临时安装/启用「媒体库刮削」，按 插件配置/媒体库刮削插件配置.md 手动执行一次

注意：插件配置与脚本生成的目录/转移规则一致；不要监控downloads/brush或最终media根目录，避免重复整理。