在搭建个人媒体库时你是否遇到过这样的困扰辛辛苦苦下载的3D电影无论是SBS左右格式还是OU上下格式在Plex、Jellyfin或Emby等主流媒体服务器中都无法被正确识别为3D影片只能当作普通2D电影播放完全无法享受沉浸式的3D观影体验或者你精心整理的3D视频资源在媒体库中显得杂乱无章缺乏统一的海报墙和信息展示如果你正为此烦恼那么Halcyon Video或许就是你一直在寻找的解决方案。它并非一个独立的媒体服务器而是一个专为3D视频打造的“智能商店”或“信息中心”能够完美地与你现有的Plex、Jellyfin、Emby等media server协同工作。本文将为你完整拆解Halcyon Video的核心概念、部署步骤、配置方法以及如何与你的媒体服务器无缝集成让你轻松构建一个美观、易用且能正确识别3D内容的个人影院系统。1. 背景与核心概念为什么需要Halcyon Video在深入实操之前我们首先要理解Halcyon Video解决了什么痛点以及它是如何工作的。1.1 主流媒体服务器的3D支持现状目前Plex、Jellyfin和Emby等媒体服务器对3D视频的原生支持非常有限。它们通常能播放3D视频文件但存在几个关键问题元数据识别缺失服务器无法自动从文件名或文件内容中识别出这是一部3D电影更无法区分是SBS、OU还是其他3D格式。这导致在媒体库中3D电影和2D电影看起来毫无区别。海报与信息混杂3D版和2D版的电影会使用相同的元数据如TMDB或TVDB的ID导致它们在海报墙上合并为同一个条目你无法快速筛选出哪些是3D资源。播放标签不明在播放时客户端如电视上的Plex App无法自动提示用户“这是一部3D电影”用户需要手动切换电视或投影仪的3D模式体验割裂。1.2 Halcyon Video是什么Halcyon Video将自己定位为一个“3D视频商店”。它的核心功能不是流媒体传输而是3D视频的元数据管理和内容聚合。对于媒体服务器Halcyon Video充当一个“特殊的媒体库”或“元数据代理”。它运行在后台持续扫描你指定的3D电影文件夹并为其生成专属的、高精度的元数据包括专门标注了3D属性的海报、背景图、简介等。对于用户你在Plex等服务器中会看到一个名为“Halcyon Video”的独立媒体库。点进去就是一个纯粹由3D电影组成的、海报墙精美、信息完整的专属影院。点击播放时影片会通过你的主媒体服务器Plex等进行流媒体传输享受所有原有的硬件转码、用户管理等功能。简单说Halcyon Video 3D专属元数据引擎 前端展示界面而Plex/Jellyfin/Emby 流媒体传输引擎 用户管理后台。两者结合互补短板实现112的效果。1.3 核心工作流程内容准备你将所有3D电影文件如Avatar.3D.HSBS.1080p.mkv存放在一个独立的文件夹中。Halcyon Video扫描Halcyon Video扫描该文件夹根据文件名或内嵌信息识别影片并从其自建的3D电影数据库或TMDB等源获取元数据关键是为每部电影打上“3D”标签并匹配专属海报。媒体服务器集成在Plex中你添加一个媒体库其文件夹指向Halcyon Video生成的一个“虚拟目录”或通过Webhook方式连接。Plex从这个“目录”获取影片列表和元数据而不直接管理原始文件。用户观影你在Plex的海报墙中找到“Halcyon Video”库浏览并播放3D电影。Plex负责流媒体传输到你的电视、手机等客户端。2. 环境准备与部署说明Halcyon Video通常以Docker容器的方式运行这是最推荐且最便捷的部署方式。下面我们以最常见的Linux服务器如Ubuntu为例演示完整部署过程。Windows用户可通过Docker Desktop实现类似操作。2.1 系统与环境要求操作系统任何支持Docker的Linux发行版如Ubuntu 20.04/22.04 LTS, Debian, CentOS 7/8、Windows 10/11Pro及以上版本、macOS。Docker Docker Compose必须预先安装。这是运行Halcyon Video的基石。磁盘空间除了存放3D电影本身的空间Halcyon Video的元数据缓存需要额外几百MB空间。网络服务器需要能访问互联网以下载容器镜像和获取在线元数据。2.2 安装Docker与Docker Compose如果你的系统还没有安装Docker请先执行以下命令以Ubuntu为例# 1. 卸载旧版本如有 sudo apt-get remove docker docker-engine docker.io containerd runc # 2. 更新包索引并安装依赖 sudo apt-get update sudo apt-get install ca-certificates curl gnupg lsb-release # 3. 添加Docker官方GPG密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 4. 设置稳定版仓库 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 5. 安装Docker引擎 sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin # 6. 验证安装 sudo docker run hello-world安装成功后docker --version和docker compose version命令应能正常显示版本信息。2.3 规划目录结构清晰的目录结构是管理媒体服务器的好习惯。建议按如下方式规划/media ├── movies_2d/ # 你的2D电影库 ├── tvshows/ # 电视剧库 └── movies_3d/ # 【重要】专门存放3D电影的文件夹 ├── Avatar (2009)/ │ └── Avatar.3D.HSBS.1080p.mkv ├── Gravity (2013)/ │ └── Gravity.3D.HSBS.1080p.mkv └── ...请提前将你的3D电影文件整理到movies_3d目录下并尽量使用规范的命名这有助于Halcyon Video更准确地识别。推荐命名格式电影名 (年份).3D.格式.分辨率.扩展名例如Dredd (2012).3D.HSBS.1080p.mkv。3. 使用Docker Compose部署Halcyon Video我们使用Docker Compose来定义和运行Halcyon Video服务这样可以方便地管理容器配置。3.1 创建Docker Compose配置文件在你的服务器上选择一个合适的目录例如~/halcyon创建docker-compose.yml文件。mkdir ~/halcyon cd ~/halcyon nano docker-compose.yml将以下配置内容粘贴到文件中。请务必根据你的实际路径修改volumes部分的映射。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 # 改为你宿主机用户的UID可用 id -u 命令查看 - PGID1000 # 改为你宿主机用户的GID可用 id -g 命令查看 - TZAsia/Shanghai # 设置时区 volumes: # 将宿主机上的3D电影目录映射到容器内的 /media 目录 - /media/movies_3d:/media:ro # Halcyon的配置和数据缓存目录持久化保存 - ./config:/config networks: - halcyon-net networks: halcyon-net: driver: bridge关键配置解释image: 指定Halcyon Video的官方容器镜像。ports: 将容器内部的7878端口映射到宿主机的7878端口。你可以通过http://你的服务器IP:7878访问Halcyon的管理界面。environment:PUID/PGID: 确保容器内进程以正确的用户权限运行避免生成的文件所有者是root导致后续管理困难。TZ: 设置正确的时区这对日志时间戳和计划任务很重要。volumes:/media/movies_3d:/media:ro:这是核心映射。将你存放3D电影的宿主机目录只读(ro)映射到容器内的/media。Halcyon会扫描这个目录。./config:/config: 将当前目录下的config文件夹映射到容器用于保存Halcyon的数据库、设置和缓存。即使容器删除数据也不会丢失。networks: 创建一个独立的Docker网络为后续可能的多容器互联做准备。3.2 启动Halcyon Video服务保存docker-compose.yml文件后在同一个目录下执行启动命令# 启动服务-d 表示后台运行 docker compose up -d首次运行会从网络拉取镜像可能需要几分钟。拉取完成后容器会自动启动。使用以下命令检查容器状态和日志# 查看容器运行状态 docker compose ps # 查看实时日志确认启动过程无报错 docker compose logs -f halcyon当在日志中看到类似Halcyon is running on http://0.0.0.0:7878的信息时说明启动成功。3.3 访问Web界面并进行初始设置打开浏览器访问http://你的服务器IP地址:7878。首次访问你会看到Halcyon Video的欢迎界面可能需要进行简单的语言选择通常为英文和初始配置向导。设置媒体目录在配置向导中它会询问媒体路径。因为我们在Docker Compose中已经将/media映射好了所以这里通常会自动识别或需要你确认路径为/media。开始扫描完成向导后Halcyon Video会自动开始扫描/media目录下的所有视频文件。你可以在Web界面的“Libraries”或“Dashboard”看到扫描进度。等待元数据匹配扫描完成后Halcyon会根据文件名尝试从TMDB等数据源匹配电影信息并专门寻找和标记3D版本。这个过程可能需要一些时间取决于电影数量和网络速度。至此Halcyon Video本身已经部署完成。但它目前只是一个独立的3D电影信息库。接下来我们需要让它与Plex或Jellyfin/Emby联动起来。4. 与Plex媒体服务器集成实战这里以Plex为例Jellyfin和Emby的集成思路类似都是将Halcyon Video作为一个“外部源”或通过“插件/Webhook”方式接入。4.1 在Plex中添加Halcyon Video库Plex本身无法直接读取Halcyon的数据库。常见的集成方式是通过“Plex Agent”或“Webhook”。但Halcyon Video更主流和优雅的集成方式是作为一个“Plex Companion Library”或者利用“Plex Webhook”和“第三方工具”如plex_3d_manager来同步。然而对于大多数用户最简单直接的方法是让Plex直接扫描Halcyon Video生成的结构化文件夹和元数据文件。但Halcyon默认不直接修改原文件。因此我们需要采用另一种广泛使用的方案使用符号链接Symbolic Link和本地元数据。步骤一在Halcyon中启用“本地元数据资产”生成虽然Halcyon Web UI可能没有直接开关但它的设计是与媒体服务器共享元数据。确保Halcyon扫描匹配完成电影信息完整。步骤二创建符号链接到Plex媒体库目录假设你的Plex电影库路径是/media/movies_plex。我们不移动原文件而是为Halcyon管理下的3D电影创建符号链接。# 假设Halcyon扫描后在 /media/movies_3d 下的电影都已整理好如放在以电影名命名的子文件夹 # 我们创建一个统一的3D电影符号链接目录给Plex mkdir -p /media/plex_libraries/3d_movies # 遍历3D电影原文件夹创建符号链接 # 注意这里假设你的3D电影都在 /media/movies_3d 的子文件夹中 for movie_dir in /media/movies_3d/*/; do movie_name$(basename $movie_dir) ln -s $movie_dir /media/plex_libraries/3d_movies/$movie_name done这样/media/plex_libraries/3d_movies目录下就包含了所有指向原始3D电影的符号链接。步骤三在Plex中添加媒体库打开Plex Web界面进入“管理” - “库”。点击“添加资料库”选择“电影”。命名资料库为“3D Movies”或“Halcyon 3D”。在“添加文件夹”中浏览并选择我们刚才创建的符号链接目录/media/plex_libraries/3d_movies。在“高级”设置中至关重要的一步将“扫描器”设置为“Plex Movie Scanner”但将“代理”设置为“Personal Media”或者“The Movie Database”。这里选择“Personal Media”可以防止Plex用TMDB的2D元数据覆盖掉Halcyon为我们准备好的3D信息。确保勾选“优先使用本地元数据”如果使用“Personal Media”代理这个选项可能默认生效。完成添加。步骤四进行Plex扫描Plex会开始扫描新的库。由于我们使用了符号链接Plex实际访问的还是原始文件。关键点在于Halcyon Video在扫描匹配后会在每个电影文件夹内生成标准的本地元数据文件如movie.nfo,poster.jpg,fanart.jpg等。Plex的“Personal Media”扫描器会读取这些本地的.nfo和图片文件来填充库信息。如果Halcyon没有自动生成这些文件你可能需要在Halcyon的设置中寻找“导出元数据”或“生成NFO”等选项并启用。有些社区版或特定版本的Halcyon可能集成了此功能。4.2 验证集成效果在Plex海报墙中找到新建的“3D Movies”库。进入该库你应该能看到所有3D电影并且海报、背景图、简介都应该是与3D版本相关的例如海报上可能带有“3D”标识。检查电影信息。在电影详情页你应该能看到诸如“3D”、“HSBS”、“HOU”等标签或信息被添加到概要、标签或标题中。这证明Plex成功使用了Halcyon提供的本地元数据。尝试播放一部电影。播放本身由Plex服务器处理。你需要在播放客户端如Plex for Android TV, Plex HTPC中手动开启电视或投影仪的3D模式对应SBS或OU格式。5. 常见问题与排查思路在部署和使用过程中你可能会遇到一些问题。下面是一个快速排查指南。问题现象可能原因解决思路访问http://IP:7878无响应1. 防火墙未开放7878端口。2. Docker容器未成功运行。3. 端口被占用。1. 检查服务器防火墙规则sudo ufw status。2. 运行docker compose ps和docker compose logs halcyon查看容器状态和日志。3. 运行 sudo netstat -tlnpHalcyon扫描不到电影1. Docker卷映射路径错误。2. 文件权限问题容器内用户无法读取宿主目录。3. 视频文件格式不被支持。1. 检查docker-compose.yml中volumes映射的宿主机路径是否正确特别是/media/movies_3d。2. 确保宿主机目录的权限允许Docker容器用户PUID/PGID指定读取。可尝试sudo chmod -R 755 /media/movies_3d。3. 确认视频文件是常见格式mkv, mp4, avi等。电影匹配错误或元数据缺失1. 电影文件名不规范无法识别。2. 网络问题无法访问TMDB等元数据源。3. Halcyon内置数据库未收录该3D版本。1. 按照推荐格式重命名文件电影名 (年份).扩展名。可以尝试使用tmdbid-{TMDB_ID}的方式强制指定如Dredd (2012) {tmdbid-49049}.mkv。2. 检查服务器网络确保可以访问api.themoviedb.org。3. 在Halcyon Web UI中手动搜索并匹配。Plex库中不显示3D标签或海报1. Plex未使用本地元数据。2. Halcyon未生成本地NFO/图片文件。3. Plex扫描器/代理设置错误。1. 确认Plex电影库的“代理”设置为“Personal Media”。2. 检查电影文件夹内是否有movie.nfo,poster.jpg等文件。若无需在Halcyon设置中启用NFO导出功能或寻找相关插件/脚本。3. 在Plex库的“高级”设置中勾选“优先使用本地元数据”。然后对库进行“刷新所有元数据”操作。播放时提示“the media could not be loaded, either because the server or network failed”这是一个通用网络/服务器错误与Halcyon无关通常出现在Plex客户端。1. Plex服务器离线或未授权。2. 客户端网络无法连接到Plex服务器。3. 媒体文件损坏或权限不足。4. 转码失败特别是当客户端要求转码而服务器性能不足时。1. 检查Plex服务器是否正在运行并通过http://PLEX_SERVER_IP:32400/web验证能否访问Web界面。2. 检查客户端网络尝试在同一个局域网内播放。3. 直接在Plex服务器上测试播放该文件排除文件损坏问题。检查文件权限。4. 在Plex Web播放设置中将“视频质量”改为“原始质量”或“最大”避免转码。查看Plex服务器控制台日志获取具体错误信息。6. 最佳实践与进阶优化为了让你的3D媒体库更稳定、更高效可以参考以下建议6.1 文件命名与目录组织规范统一的命名是自动化管理的灵魂。强烈建议使用标准化工具使用文件重命名工具如FileBot、tinyMediaManager或Radarr针对电影。这些工具可以自动根据电影名和年份从TMDB抓取信息并重命名文件和文件夹为规范格式。Radarr集成你可以将Radarr的根目录设置为/media/movies_3d让它自动管理3D电影的下载、重命名和移动。然后在Radarr中设置一个独立的“3D电影”标签或列表便于管理。命名包含3D信息在电影文件夹名或文件名中保留3D格式信息例如Gravity (2013) [3D HSBS]。虽然Halcyon主要靠元数据但这对于人工排查非常有用。6.2 Halcyon Video的维护定期更新Halcyon Video的Docker镜像可能会更新修复Bug或增加新功能。定期执行以下命令进行更新cd ~/halcyon docker compose pull docker compose up -d备份配置你映射的./config目录包含了所有设置和缓存。定期备份这个目录可以在系统迁移或容器重建时快速恢复。监控日志如果遇到问题首先查看日志docker compose logs --tail100 halcyon。关注其中的错误(ERROR)和警告(WARN)信息。6.3 Plex播放优化直接播放为了获得最佳的3D效果和减轻服务器负担应尽量让客户端“直接播放”Direct Play/Stream避免转码。确保你的客户端设备如Shield TV, 智能电视支持视频和音频的原生解码。音频兼容性3D电影常包含高清音频轨如DTS-HD MA, TrueHD。如果客户端不支持Plex会尝试转码音频这通常比视频转码轻松。但若遇到播放问题可以考虑在Plex中设置音频转码规则或使用MKVToolNix等工具为电影添加一条兼容性更好的AC3或AAC音轨。客户端设置在电视等客户端的Plex App设置中将“本地质量”和“远程质量”都设置为“最大”或“原始质量”强制直接播放。6.4 探索替代集成方案如果上述符号链接方案对你来说不够自动化可以探索社区提供的更紧密的集成方案Plex 3D Manager Scripts寻找社区开发的Python或Shell脚本这些脚本可以监控Halcyon的数据库变化然后自动调用Plex API更新特定的库或项目实现更动态的同步。Webhook研究Halcyon是否支持Webhook当扫描到新电影时自动通知一个自定义服务该服务再触发Plex的局部扫描。Jellyfin/Emby的本地NFO支持Jellyfin和Emby对本地NFO文件的支持通常比Plex更直接和强大。如果你主要使用它们集成过程可能会更顺畅只需在Halcyon中开启NFO导出然后在Jellyfin/Emby中添加媒体库时选择正确的NFO读取器即可。部署Halcyon Video并成功与Plex集成意味着你为珍贵的3D电影资源找到了一个完美的“家”。它不仅解决了分类和识别的问题更通过精美的元数据展示提升了整个媒体库的观赏价值。从规划目录、部署容器到配置集成、排查故障这个过程本身也是对Docker和媒体服务器架构的一次深入实践。遇到问题时的排查思路如检查权限、验证网络、分析日志都是运维工作中的通用技能。现在你的3D电影终于可以摆脱2D海洋的淹没以独立的、醒目的姿态出现在海报墙上等待你下一次开启沉浸式的观影之旅。