三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

Docker部署Halcyon Video：为Jellyfin构建专业3D影片元数据解决方案

发布时间：2026/8/9 12:57:02 三亩地 编程学习日记
Docker部署Halcyon Video：为Jellyfin构建专业3D影片元数据解决方案

最近在折腾家庭媒体库时，发现一个痛点：辛辛苦苦下载的3D电影，在Jellyfin、Plex这类主流媒体服务器里，要么识别混乱，要么海报墙信息缺失，播放体验大打折扣。如果你也遇到过类似问题，那么今天介绍的Halcyon Video或许就是你的解决方案。它并非一个独立的媒体服务器，而是一个专门为3D视频内容打造的“元数据商店”，能够完美地与你现有的Jellyfin、Emby或Plex集成，彻底解决3D影片的刮削、识别和展示难题。

本文将手把手带你从零开始，完成Halcyon Video的部署、配置，并集成到Jellyfin中。无论你是家庭影院爱好者，还是希望构建一个专业3D媒体库的开发者，都能从这篇实战指南中获得一套完整的、可复现的落地方案。

1. 理解Halcyon Video：它是什么，解决什么问题？

在深入部署之前，我们首先要搞清楚Halcyon Video的定位，以及它和传统媒体服务器的区别。

1.1 核心概念：元数据代理与3D视频商店

简单来说，Halcyon Video是一个专注于3D视频的元数据（Metadata）提供源。

  • 元数据是什么？对于一部电影，元数据包括：片名、简介、上映年份、导演、演员、评分、海报、背景图、预告片链接等。媒体服务器（如Jellyfin）正是依靠这些元数据来构建漂亮的海报墙和影片信息库。
  • 传统刮削器的问题：Jellyfin默认使用TMDB、TVDB等公共数据库进行刮削。但这些数据库对3D影片的支持非常薄弱。一部名为Avatar.3D.1080p.mkv的电影，很可能被错误识别为普通2D版《阿凡达》，或者干脆无法识别，导致海报墙出现一个难看的“未知影片”条目。
  • Halcyon Video的解决方案：它维护了一个专门针对3D影片的元数据库。当你的媒体服务器向它发起查询时，它会返回精确匹配的3D影片信息，包括专门为3D版本设计的海报和背景图。

关键区别：Halcyon Video本身不提供视频文件，也不负责视频转码和流媒体播放。它只提供“影片信息”。播放和存储依然由你的Jellyfin/Plex和本地NAS或硬盘来完成。

1.2 为什么需要它？3D媒体库管理的核心痛点

  1. 识别率低：文件名五花八门（3D,HSBS,HOU,MVC等），公共数据库难以匹配。
  2. 信息不准确：即使识别出来，也可能套用2D版的海报和简介，无法体现3D特色。
  3. 分类筛选困难：在媒体服务器中无法快速筛选出所有的3D影片。
  4. 播放体验割裂：需要手动选择音轨、字幕或3D模式。

Halcyon Video通过提供精准的元数据，解决了前三个问题。第四个播放问题，则需要媒体服务器和播放客户端共同配合。

2. 环境准备与部署规划

在开始安装前，请确保你已具备以下环境。本文将使用最通用的Docker部署方式，这也是官方推荐的方法。

2.1 基础环境要求

  • 操作系统：任何可以运行Docker的系统，包括：
    • Linux (Ubuntu, Debian, CentOS等)
    • Windows 10/11 (需安装Docker Desktop)
    • macOS
    • NAS系统 (群晖DSM、威联通QTS、UNRAID等，需支持Docker)
  • 容器运行时：Docker 或 Docker Compose。请确保已正确安装并启动Docker服务。
  • 现有媒体服务器：一个已安装并配置好的Jellyfin、Plex或Emby服务器。本文以Jellyfin为例进行集成。
  • 网络：服务器需要能访问互联网，以下载Docker镜像和获取元数据。

2.2 项目结构规划

在部署前，规划好你的目录结构，便于后期管理和维护。建议在你的工作目录（如/opt/media或D:\Media）下创建如下结构：

/opt/media/ ├── halcyon/ # Halcyon Video 相关文件 │ ├── config/ # 挂载卷，用于持久化配置 │ └── docker-compose.yml # 部署文件 ├── jellyfin/ # Jellyfin 相关文件（如果也用Docker部署） │ ├── config/ │ ├── cache/ │ └── docker-compose.yml └── library/ # 你的媒体库根目录 ├── Movies-3D/ # 专门存放3D电影的文件夹 └── Movies-2D/

注意：library/Movies-3D/这个路径非常重要，后续在Jellyfin和Halcyon的配置中都会用到。

3. 使用Docker Compose部署Halcyon Video

我们采用Docker Compose来部署，这是管理容器应用最清晰、最可复现的方式。

3.1 创建部署配置文件

在你的halcyon目录下，创建docker-compose.yml文件。

version: '3.8' services: halcyon: image: ghcr.io/halcyon-video/halcyon:latest container_name: halcyon-video restart: unless-stopped ports: - "7878:7878" # Halcyon Web UI 管理端口 environment: - PUID=1000 # 改为你宿主机的用户ID，用于权限管理 - PGID=1000 # 改为你宿主机的组ID - TZ=Asia/Shanghai # 设置时区 volumes: - ./config:/config # 持久化配置目录 - /path/to/your/library/Movies-3D:/media:ro # 关键！只读挂载你的3D媒体库 networks: - media-network # 自定义网络，便于与Jellyfin通信 networks: media-network: driver: bridge

配置参数详解：

  1. image: 指定使用的镜像，ghcr.io是GitHub容器仓库。
  2. ports: 将容器内部的7878端口映射到宿主机的7878端口。你可以通过http://你的服务器IP:7878访问Halcyon的管理界面。
  3. environment:
    • PUID/PGID:必须修改。在Linux上，可以通过id $USER命令查看你的UID和GID。设置正确的权限可以避免容器内程序无法读写挂载目录的问题。
    • TZ: 设置正确的时区，保证日志时间准确。
  4. volumes:
    • ./config:/config: 将当前目录下的config文件夹映射到容器内，用于保存数据库和配置，实现数据持久化。
    • /path/to/your/library/Movies-3D:/media:ro:这是核心配置。将你宿主机上存放3D电影的绝对路径，以只读(ro)方式映射到容器内的/media目录。Halcyon会扫描这个目录来识别影片。
  5. networks: 创建一个名为media-network的桥接网络。如果你也将Jellyfin部署在Docker中，并加入同一网络，容器间可以通过服务名（如jellyfin）直接通信，无需暴露端口到宿主机，更安全。

3.2 启动Halcyon Video服务

在包含docker-compose.yml文件的目录下，执行以下命令：

# 创建持久化配置目录 mkdir -p config # 启动服务（-d 表示后台运行） docker-compose up -d

启动后，使用以下命令查看日志，确认服务运行正常：

docker-compose logs -f halcyon

如果看到类似Halcyon is running on http://0.0.0.0:7878的日志，说明启动成功。

现在，打开浏览器，访问http://你的服务器IP:7878，你应该能看到Halcyon Video的Web管理界面。首次访问可能需要简单设置，但通常无需额外配置即可使用。

4. 配置Jellyfin使用Halcyon Video元数据

Halcyon部署好后，下一步是让它为Jellyfin服务。我们需要在Jellyfin中将Halcyon添加为一个“元数据插件”。

4.1 获取Halcyon的插件清单URL

Halcyon充当了一个符合Jellyfin插件规范的元数据源。我们需要在Jellyfin后台添加这个源。

  1. 打开Halcyon的Web UI (http://服务器IP:7878)。
  2. 在界面中（通常在Settings或Info页面），找到名为Plugin Manifest URL的地址。这个地址通常格式为：http://你的服务器IP:7878/plugin。
    • 重要：如果Jellyfin和Halcyon不在同一台机器或同一个Docker网络内，这里的IP必须使用Jellyfin能访问到的地址（如公网IP或内网IP）。如果它们在同一个Docker自定义网络（如前面定义的media-network）中，则可以使用容器名作为主机名，如http://halcyon-video:7878/plugin。

4.2 在Jellyfin中添加元数据插件

  1. 以管理员身份登录你的Jellyfin控制台 (http://你的Jellyfin服务器IP:8096)。
  2. 点击左上角菜单 →控制台。
  3. 在左侧菜单中，进入“插件”→“存储库”。
  4. 点击右上角的“+”号按钮。
  5. 在弹出的窗口中，将刚才获取的Plugin Manifest URL粘贴到“清单URL”输入框中，名称可以填写“Halcyon Video”。
  6. 点击“确定”保存。

保存后，Jellyfin会自动从该URL获取插件信息。稍等片刻，你会在“插件”目录下的“元数据”分类中，看到名为“Halcyon”的插件。点击它，然后点击“安装”。

4.3 配置媒体库使用Halcyon插件

插件安装成功后，需要为你存放3D电影的媒体库启用它。

  1. 在Jellyfin控制台，进入“媒体库”。
  2. 找到你存放3D电影的媒体库（例如名为“3D电影”的库）。点击这个媒体库名称进入编辑页面。
  3. 找到“元数据下载器”设置区域。
  4. 你会看到“电影元数据下载器”列表。确保“Halcyon”被勾选，并且将其拖拽到列表的最顶部。这意味着Jellyfin会优先使用Halcyon来识别影片。
    • （可选）可以取消勾选其他下载器（如TMDB），避免冲突，但对于Halcyon未识别的影片，可以保留其他下载器作为后备。
  5. 找到“图像获取器”设置区域。
  6. 同样，确保“Halcyon”被勾选并置于优先位置。
  7. 滚动到页面底部，点击“保存”。

4.4 触发元数据刷新

配置完成后，Jellyfin不会立即为所有已有影片重新刮削。你需要手动触发。

  1. 回到Jellyfin主页，进入你的3D电影媒体库。
  2. 点击右上角的“···”三个点菜单。
  3. 选择“刷新元数据”。
  4. 在弹出的对话框中，建议选择：
    • 扫描模式：“替换所有元数据”
    • 图像模式：“替换所有图像”
    • 勾选“同时刷新所有项目的互联网图像”
  5. 点击“确定”。

Jellyfin将开始扫描该库中的所有文件，并向Halcyon发起查询。你可以在Jellyfin的“控制台” → “计划任务”中查看刷新进度。

5. 实战效果与文件命名规范

5.1 查看刮削效果

刷新完成后，再次浏览你的3D电影库。理想情况下，你会发现：

  • 之前无法识别的3D影片现在有了正确的海报和详细信息。
  • 影片标题和简介可能更符合3D版本的特征（例如，注明是“3D版本”）。
  • 在影片详情页，可能会看到Halcyon提供的特定3D标签或信息。

成功的关键在于文件命名。Halcyon和Jellyfin主要通过文件名来匹配影片。

5.2 推荐的3D视频文件命名规范

为了让识别更精准，请遵循以下命名约定。假设电影是《阿凡达》(2009)：

  • 基本格式：电影名 (年份).3D.扩展名
  • 推荐命名示例：
    • Avatar (2009).3D.mkv
    • Avatar (2009).3D.HSBS.1080p.mkv(标明是左右半宽格式)
    • Avatar (2009).3D.HOU.1080p.mkv(标明是上下格式)
    • Avatar (2009).3D.MVC.1080p.mkv(标明是蓝光原盘MVC格式)

核心是包含(年份)和.3D.这个关键标识符。HSBS、HOU、MVC等是3D格式的常见缩写，有助于Halcyon提供更精确的元数据。

你可以使用批量重命名工具（如renamer、Advanced Renamer或tmdb-renamer脚本）来统一规范你的3D影片库。

6. 常见问题与排查思路 (FAQ)

在集成和使用过程中，你可能会遇到一些问题。以下是常见问题的排查指南。

问题现象可能原因排查思路与解决方案
Jellyfin无法安装Halcyon插件1. 网络问题，无法访问Halcyon的URL。
2. Halcyon服务未运行。
3. URL填写错误。		1. 在Jellyfin服务器上，用curl http://halcyon-ip:7878/plugin测试能否访问。返回XML即正常。
2. 检查Halcyon容器状态：docker-compose ps。
3. 确认URL末尾有/plugin。
插件已安装，但刷新后无效果1. Halcyon插件未在媒体库中启用或优先级不高。
2. 文件命名不规范，无法匹配。
3. Halcyon数据库中暂无此影片元数据。		1. 检查媒体库设置，确保Halcyon下载器已勾选且排在第一位。
2. 按照第5.2节规范重命名文件，尤其是(年份)和.3D.。
3. Halcyon社区驱动，影片可能未被收录。可尝试在Halcyon UI中手动匹配或向社区提交请求。
日志出现“the media could not be loaded, either because the server or network failed”1.此错误常出现在客户端播放时，与Halcyon元数据无关。
2. Jellyfin服务器转码或直接播放失败。		1.重点排查播放环节：检查视频编码格式、音轨是否被客户端支持。
2. 检查Jellyfin服务器资源（CPU、内存）是否充足。
3. 尝试在Jellyfin控制台降低转码质量或使用“直接播放”。
4. 检查网络连接是否稳定。
Halcyon Web UI 无法访问1. 防火墙/安全组未开放7878端口。
2. Docker端口映射错误。
3. 容器启动失败。		1. 检查宿主机防火墙规则：sudo ufw status(Ubuntu)。
2. 检查docker-compose.yml中端口映射"7878:7878"是否正确。
3. 查看容器日志：docker-compose logs halcyon，寻找错误信息。
部分影片识别为2D版本Halcyon元数据优先级可能被其他插件覆盖，或匹配不精确。1. 在Jellyfin媒体库设置中，禁用其他电影元数据下载器，只保留Halcyon，然后单独刷新该影片。
2. 在影片详情页点击“编辑元数据”，手动从Halcyon源中选择正确条目。
Docker容器权限错误（无法扫描/media）宿主机挂载目录的权限与容器内PUID/PGID不匹配。1. 确认docker-compose.yml中PUID/PGID是否为宿主机上有权访问媒体目录的用户。
2. 检查媒体目录（如/path/to/your/library/Movies-3D）的权限：ls -la /path/to/your/library/。
3. 可尝试将目录权限改为755：chmod -R 755 /path/to/your/library/Movies-3D。

7. 最佳实践与高级配置建议

为了让你的3D媒体库更完善、更易维护，可以参考以下建议。

7.1 媒体库结构优化

  • 分离2D与3D库：在Jellyfin中创建两个独立的电影媒体库，一个指向Movies-2D，一个指向Movies-3D。这样管理清晰，也便于应用不同的元数据策略。
  • 标准化命名流程：建立一套固定的命名规则，并使用工具自动化。例如，所有新下载的3D影片先放入一个“待处理”文件夹，运行命名脚本后，再移入正式的Movies-3D库。

7.2 Halcyon与Jellyfin的维护

  • 定期更新：Halcyon镜像和Jellyfin插件会持续更新。建议定期执行以下命令更新Halcyon：
    cd /path/to/your/halcyon docker-compose pull docker-compose up -d
  • 备份配置：定期备份你的docker-compose.yml文件和Halcyon的config目录。整个halcyon文件夹打包备份即可。
  • 监控日志：如果遇到识别问题，首先查看Halcyon和Jellyfin的日志。Halcyon日志可通过Web UI的日志页面或docker-compose logs查看。

7.3 提升播放体验

  • 客户端选择：播放3D影片，推荐使用能原生支持3D格式的客户端，如Kodi（配合Jellyfin插件）、Infuse(Apple TV) 或一些智能电视上的专业播放器。它们通常能更好地处理3D信号输出。
  • 服务器性能：如果需要进行3D转码（例如将MVC格式转为SBS），对服务器CPU要求较高。确保你的Jellyfin服务器有足够的性能储备，否则尽量让客户端直接播放原片。
  • 网络配置：如果服务器和播放设备不在同一局域网，确保网络带宽足够流畅传输可能高达50-80GB的蓝光3D原盘文件。

通过以上步骤，你应该已经成功搭建了一个由Halcyon Video提供专业元数据、Jellyfin负责管理和播放的3D家庭影院系统。这套组合拳解决了3D影片管理中最头疼的识别和展示问题，让你的媒体库真正变得整洁而专业。

编程学习 学习日记 实战经验
← 返回列表