HolyArrs对接Plex、Jellyfin、Emby:媒体服务器实时同步完整指南
HolyArrs对接Plex、Jellyfin、Emby:媒体服务器实时同步完整指南
HolyArrs 是一个自托管的多媒体下载管理工具,它能把新下载的电影、剧集和音乐实时同步到 Plex、Jellyfin 或 Emby 媒体服务器——导入、改名、删除文件后,HolyArrs 会自动通知媒体服务器重新扫描对应文件夹,你不再需要等待下一次完整扫描,内容即刻出现在播放列表里。
为什么需要实时同步媒体服务器?
平时使用媒体服务器时,你可能遇到过这种情况:
- 下载完一部电影,打开 Plex 却看不到,只能手动触发扫描媒体库;
- 重命名整个剧集文件夹后,服务器里的条目全部丢失;
- 删掉了文件,媒体库里却还挂着一条“幽灵记录”。
HolyArrs 的媒体服务器对接功能(源码见 app/backend/internal/mediaservers/)正是为解决这些问题设计的:每次导入、改名或删除文件后,它自动通知服务器刷新受影响的文件夹,而不是整库扫描,速度快、负担小。
连接前准备工作清单
在开始之前,请确认以下 3 个条件:
| 准备项 | 说明 |
|---|---|
| ✅ 网络可达 | 运行 HolyArrs 的机器能访问媒体服务器的地址(浏览器能打开即可) |
| ✅ 凭据就绪 | Plex 需要 Token,Jellyfin / Emby 需要 API Key(在服务器 Dashboard → API keys 中创建) |
| ✅ 路径清楚 | 知道媒体服务器视角下的媒体文件夹路径;如果服务器跑在 Docker 里,要用容器内的路径 |
📌 常用端口参考:Plex
32400,Jellyfin / Emby8096。
一键添加媒体服务器:4步配置
操作入口在 Settings > Media servers,完整官方说明见 docs/library/media-servers.md:
- 打开 Settings > Media servers,选择 Add a media server;
- 填写 Name(每个服务器需唯一,最长 80 字符);
- 选择 Kind:Plex、Jellyfin 或 Emby(⚠️ 保存后不可更改);
- 填写 Address(如
http://192.168.1.10:32400),粘贴 Plex token 或 API key,点击 Save; - 在新卡片上点击 Test——看到 Plex 的媒体库列表,或 Jellyfin / Emby 的服务器名称和版本号,说明对接成功。🎉
凭据(token / key)会被加密存储且不再明文显示。留空输入框即表示保留原凭据;如果修改了服务器地址,则必须重新粘贴一次,防止凭据被误发到别的服务器。
关键选项详解:触发时机、路径映射、局域网
添加完成后,HolyArrs 提供 4 个实用选项,按需调整:
更新它之后(Update it after)
勾选希望媒体服务器感知的变化类型,新建服务器时默认 3 项全开:
- An import:导入新文件后通知
- A rename:重命名后通知
- A delete:文件真正从磁盘删除后通知(仅移走不算)
路径映射(Paths)
⚠️ 这是 Docker 环境下最常见的坑。如果 HolyArrs 和媒体服务器看到的文件路径不同(例如 HolyArrs 是 /movies,Plex 容器里是 /media/movies),扫描将找不到新内容。此时在 HolyArrs path 和 Same folder on the server 中分别填入两侧路径(两个框必须同时填写或同时留空)。路径方案详见 docs/start/folders.md 与 docs/library/folders.md。
可达局域网(Reach the local network)
默认开启,因为媒体服务器几乎总在家里。如果服务器部署在公网,建议关闭。无论开关如何,HolyArrs 都绝不会主动访问链路本地地址或云元数据地址(防 SSRF 设计,实现见 app/backend/internal/mediaservers/address_policy_test.go)。
发送更新(Send updates)
关闭可暂停某个服务器而无需删除它,卡片上会显示 Off。
如何验证对接是否生效
对接状态有三处可查:
- 卡片状态:每张服务器卡片显示最近一次检查时间或最后的错误信息;
- 历史记录:每次通知都会写入 History,显示为 Told the media server about it(已通知)或 Could not reach the media server(未能触达,附原因),见 docs/downloads/history.md;
- 健康检查:Health 页面逐一列出每个媒体服务器及其状态,见 docs/run/health.md。
常见问题快速排查
遇到同步失败?对照下表快速定位:
| 现象 / 报错 | 解决方法 |
|---|---|
| “the server turned down the token” | 点击 Change,粘贴新的 token 或 key |
| “the server did not answer” | 检查地址和端口,确认 HolyArrs 能访问该机器 |
| “the server is on the local network, which it may not reach” | 打开 Reach the local network |
| “the server has no movie, TV or music library” | 先在 Plex 中建立媒体库,再测试 |
| “type the token again when the server address changes” | 修改过地址,重新粘贴 token 并保存 |
| “give both sides of the path map, or neither” | 路径映射两个框同填或同空 |
| 服务器在扫描但看不到新内容 | 两侧路径不一致,设置路径映射 |
进阶:底层是怎么工作的?
HolyArrs 不会每改一个文件就发一次请求——它会等待 10 秒,把这段时间内所有变更的文件夹汇总后一次性发送,因此“重命名整部剧集”只触发一次更新。
各服务器收到的通知内容不同:
| 服务器 | HolyArrs 发送的内容 |
|---|---|
| Plex | 定位包含该文件夹的电影 / 剧集 / 音乐库,只扫描那个文件夹;若没有库包含它,则扫描该类型的所有库 |
| Jellyfin | 变更(新建 / 修改 / 删除)的文件夹清单 + 一次媒体库刷新 |
| Emby | 变更的文件夹清单 |
超时保护:对服务器的请求 20 秒超时,Test 按钮 30 秒超时。
相关 API 路由(/api/v1/media-servers)定义在 app/backend/internal/mediaservers/routes.go,数据结构见 app/backend/internal/mediaservers/types.go。
小结
- 在 Settings > Media servers 中添加服务器,4 步完成 Plex / Jellyfin / Emby 对接;
- 测试通过后,导入、改名、删除都会实时同步到媒体服务器;
- Docker 用户记得配置路径映射,这是同步失败的头号原因;
- 用 History 和 Health 页面随时核对同步状态。
配置完成后,你的下载工作流就形成了闭环:HolyArrs 负责找资源、下文件、整理入库,Plex / Jellyfin / Emby 负责播放,中间无需任何手动操作。🍿