HolyArrs对接Plex、Jellyfin、Emby:媒体服务器实时同步完整指南

原创2026-11-13 19:12:521,924 阅读

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 / Emby 8096。

一键添加媒体服务器:4步配置

操作入口在 Settings > Media servers,完整官方说明见 docs/library/media-servers.md:

  1. 打开 Settings > Media servers,选择 Add a media server;
  2. 填写 Name(每个服务器需唯一,最长 80 字符);
  3. 选择 Kind:Plex、Jellyfin 或 Emby(⚠️ 保存后不可更改);
  4. 填写 Address(如 http://192.168.1.10:32400),粘贴 Plex token 或 API key,点击 Save;
  5. 在新卡片上点击 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。

如何验证对接是否生效

对接状态有三处可查:

  1. 卡片状态:每张服务器卡片显示最近一次检查时间或最后的错误信息;
  2. 历史记录:每次通知都会写入 History,显示为 Told the media server about it(已通知)或 Could not reach the media server(未能触达,附原因),见 docs/downloads/history.md;
  3. 健康检查: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 负责播放,中间无需任何手动操作。🍿

登录后查看全文
HolyArrs