最近在折腾家庭媒体库时发现一个痛点辛辛苦苦下载的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媒体库管理的核心痛点识别率低文件名五花八门3D,HSBS,HOU,MVC等公共数据库难以匹配。信息不准确即使识别出来也可能套用2D版的海报和简介无法体现3D特色。分类筛选困难在媒体服务器中无法快速筛选出所有的3D影片。播放体验割裂需要手动选择音轨、字幕或3D模式。Halcyon Video通过提供精准的元数据解决了前三个问题。第四个播放问题则需要媒体服务器和播放客户端共同配合。2. 环境准备与部署规划在开始安装前请确保你已具备以下环境。本文将使用最通用的Docker部署方式这也是官方推荐的方法。2.1 基础环境要求操作系统任何可以运行Docker的系统包括Linux (Ubuntu, Debian, CentOS等)Windows 10/11 (需安装Docker Desktop)macOSNAS系统 (群晖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: - PUID1000 # 改为你宿主机的用户ID用于权限管理 - PGID1000 # 改为你宿主机的组ID - TZAsia/Shanghai # 设置时区 volumes: - ./config:/config # 持久化配置目录 - /path/to/your/library/Movies-3D:/media:ro # 关键只读挂载你的3D媒体库 networks: - media-network # 自定义网络便于与Jellyfin通信 networks: media-network: driver: bridge配置参数详解image: 指定使用的镜像ghcr.io是GitHub容器仓库。ports: 将容器内部的7878端口映射到宿主机的7878端口。你可以通过http://你的服务器IP:7878访问Halcyon的管理界面。environment:PUID/PGID:必须修改。在Linux上可以通过id $USER命令查看你的UID和GID。设置正确的权限可以避免容器内程序无法读写挂载目录的问题。TZ: 设置正确的时区保证日志时间准确。volumes:./config:/config: 将当前目录下的config文件夹映射到容器内用于保存数据库和配置实现数据持久化。/path/to/your/library/Movies-3D:/media:ro:这是核心配置。将你宿主机上存放3D电影的绝对路径以只读(ro)方式映射到容器内的/media目录。Halcyon会扫描这个目录来识别影片。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的插件清单URLHalcyon充当了一个符合Jellyfin插件规范的元数据源。我们需要在Jellyfin后台添加这个源。打开Halcyon的Web UI (http://服务器IP:7878)。在界面中通常在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中添加元数据插件以管理员身份登录你的Jellyfin控制台 (http://你的Jellyfin服务器IP:8096)。点击左上角菜单 →控制台。在左侧菜单中进入“插件”→“存储库”。点击右上角的“”号按钮。在弹出的窗口中将刚才获取的Plugin Manifest URL粘贴到“清单URL”输入框中名称可以填写“Halcyon Video”。点击“确定”保存。保存后Jellyfin会自动从该URL获取插件信息。稍等片刻你会在“插件”目录下的“元数据”分类中看到名为“Halcyon”的插件。点击它然后点击“安装”。4.3 配置媒体库使用Halcyon插件插件安装成功后需要为你存放3D电影的媒体库启用它。在Jellyfin控制台进入“媒体库”。找到你存放3D电影的媒体库例如名为“3D电影”的库。点击这个媒体库名称进入编辑页面。找到“元数据下载器”设置区域。你会看到“电影元数据下载器”列表。确保“Halcyon”被勾选并且将其拖拽到列表的最顶部。这意味着Jellyfin会优先使用Halcyon来识别影片。可选可以取消勾选其他下载器如TMDB避免冲突但对于Halcyon未识别的影片可以保留其他下载器作为后备。找到“图像获取器”设置区域。同样确保“Halcyon”被勾选并置于优先位置。滚动到页面底部点击“保存”。4.4 触发元数据刷新配置完成后Jellyfin不会立即为所有已有影片重新刮削。你需要手动触发。回到Jellyfin主页进入你的3D电影媒体库。点击右上角的“···”三个点菜单。选择“刷新元数据”。在弹出的对话框中建议选择扫描模式“替换所有元数据”图像模式“替换所有图像”勾选“同时刷新所有项目的互联网图像”点击“确定”。Jellyfin将开始扫描该库中的所有文件并向Halcyon发起查询。你可以在Jellyfin的“控制台” → “计划任务”中查看刷新进度。5. 实战效果与文件命名规范5.1 查看刮削效果刷新完成后再次浏览你的3D电影库。理想情况下你会发现之前无法识别的3D影片现在有了正确的海报和详细信息。影片标题和简介可能更符合3D版本的特征例如注明是“3D版本”。在影片详情页可能会看到Halcyon提供的特定3D标签或信息。成功的关键在于文件命名。Halcyon和Jellyfin主要通过文件名来匹配影片。5.2 推荐的3D视频文件命名规范为了让识别更精准请遵循以下命名约定。假设电影是《阿凡达》(2009)基本格式电影名 (年份).3D.扩展名推荐命名示例Avatar (2009).3D.mkvAvatar (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. 可尝试将目录权限改为755chmod -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插件会持续更新。建议定期执行以下命令更新Halcyoncd /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影片管理中最头疼的识别和展示问题让你的媒体库真正变得整洁而专业。