企业官网建设流程全解析

MoviePilot 30分钟跑起来：NAS 媒体库自动化的部署、调优与排错全解

【免费下载链接】MoviePilotNAS媒体库自动化管理工具项目地址: https://gitcode.com/gh_mirrors/mo/MoviePilot

你的下载目录里堆满了S01E04.2160p.REMUX.IMAX这类文件名，而 Emby 或 Plex 对着它们一脸茫然——这就是 MoviePilot 要解决的麻烦。它是开源的 NAS 媒体库自动化管理工具：识别片名、规范命名、整理归档、刮削元数据、刷新媒体库，一条流水线走完。下文按"先跑起来→最少配置→调口味→排错"四个环节带你搭完，全程只需要一台 NAS 和一个终端。

值不值得装，先看它替你干了什么

这一节回答一个问题：这东西到底帮你省了什么事。

核心流程是"订阅 → 搜索 → 下载 → 整理 → 刮削 → 刷新 → 通知"，每一环都能在 Web 界面里单独开关。前后端分离（FastAPI + Vue 3），后端代码就在仓库根目录的 app/ 下。

🐳 先跑起来：Docker 或源码 CLI 二选一

这一节解决从零到打开 Web 界面这件事。官方推荐 Docker 部署；喜欢折腾、想跟最新代码的，可以走本地 CLI 源码模式。

方式一：Docker。拉取 V3 独立镜像jxxghp/moviepilot-v3（V2 与旧版镜像保持原命名），把宿主机上的配置目录挂载到容器内的/config。前端默认监听3000 端口，后端默认3001。想上 PostgreSQL 数据库，参考 docs/postgresql-setup.md；从 V2 升级过来的人先看 docs/v2-to-v3-overview.md 了解版本差异。

方式二：源码 CLI。克隆仓库后跑仓库自带的一键脚本：

git clone https://gitcode.com/gh_mirrors/mo/MoviePilot cd MoviePilot bash scripts/bootstrap-local.sh

脚本会自动检测操作系统、安装 Python 3.14+ 依赖、下载前端与站点资源，最后创建全局moviepilot命令并拉起前后端。装完先敲这三条确认状态：

moviepilot start moviepilot status moviepilot config path

注意配置目录默认放在程序目录之外：Linux 是~/.config/moviepilot，macOS 是~/Library/Application Support/MoviePilot，这样删程序不会连配置一起删掉。完成后用浏览器打开http://<NAS地址>:3000即进入管理界面。完整命令清单见 docs/cli.md。

最少配置：启动后先填这三样

这一节解决"第一次进界面先干什么"。向导模式下一次填完，moviepilot init --wizard也可以在命令行里走同样的流程。

1. 下载目录 + 媒体库目录：媒体库目录是 MoviePilot 本地能读到的路径，向导会确保它存在；下载目录按下载器内部路径原样保存，支持远程下载器和路径映射。
2. 下载器：qBittorrent、Transmission 等，填上地址与账号密码。
3. 媒体服务器：Emby、Plex、Jellyfin，填好地址后刮削完才会自动刷库。

顺带两件事：数据库默认 SQLite，规模大了可在向导里切到 PostgreSQL；如果开了 AI Agent（AI_AGENT_ENABLE），后面排错时能直接用自然语言问它。另外全功能模式必须保持API_WORKERS=1，调大数值会让插件和调度器重复启动，服务会直接拒绝运行。

让它按你的口味识别

这一节解决"识别错了"和"我想让它这么解析"两个诉求。

强制标记：对某个拿不准的文件，直接在文件名里加标签，解析器会优先采信——{tmdbid=12345}指定 TMDB 编号，{type=movie}或{type=tv}强制指定类型，Emby 风格的[tmdbid=12345]也认。解析逻辑的源码在 app/domain/metainfo.py。

自定义识别词：想替换、屏蔽标题里的某些词，或者修正季集号偏移，在 Web 界面的识别词配置里逐行填规则即可，不需要改源码。解析与应用规则实现在 app/domain/meta/words.py。

音乐库附加项：走 CLI 也能快速开关，例如moviepilot config set MUSIC_METADATA_TO_SIMPLIFIED true把元数据统一转成简体中文。所有可配项用moviepilot config keys查，单项含义用moviepilot config describe <KEY>查。

🩹 出事了：按这张表排查

页面打不开、服务起不来时，别急着删库重装——先按症状跑对应命令。

moviepilot doctor moviepilot doctor --deep moviepilot doctor --json

doctor不依赖后端存活，直接检查配置、端口、进程、最近 24 小时日志、依赖、数据库和前端资源；--fix只做白名单内的事（清理过期 runtime 文件、补齐缺失的API_TOKEN），不会动你的数据库。Docker 环境下用docker exec -it <容器名> moviepilot doctor，容器已退出时可用镜像挂载同一配置目录执行python -m app.cli doctor。详细诊断项说明在 docs/doctor.md。日志固定落在配置目录下：主日志logs/moviepilot.log，启动日志logs/moviepilot.stdout.log。

长期跑下去：三个维护习惯

部署完不是终点，这一节是三条低成本的日常动作。

• 更新：先moviepilot stop，再moviepilot update all（Docker 部署则换镜像标签重建容器）；更新前若改过源码，CLI 会列文件并询问是否清理。
• 备份：moviepilot database backup随时打一份在线一致备份，moviepilot database list查看，还原用moviepilot database restore <文件名> --confirm，还原前必须先停服务。
• 开机自启：moviepilot startup enable按操作系统注册登录自启，NAS 重启后自动接管。

如果配置了 LLM 并打开AI_AGENT_ENABLE，排错还能偷懒：moviepilot agent 帮我看看为什么没有自动整理，它会调用系统工具替你查。

现在打开终端敲一句moviepilot status，前后端都是绿灯的话，今晚新落盘的这批下载就会自己走完命名、整理、刷库全流程。一次到位的部署像一套调好的灌溉系统：水按地形自己流进每块田，你要做的只是偶尔看一眼阀门。

【免费下载链接】MoviePilotNAS媒体库自动化管理工具项目地址: https://gitcode.com/gh_mirrors/mo/MoviePilot