企业官网建设流程全解析

在搭建个人媒体库时，你是否遇到过这样的困扰：辛辛苦苦下载的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视频文件，但存在几个关键问题：

1. 元数据识别缺失：服务器无法自动从文件名或文件内容中识别出这是一部3D电影，更无法区分是SBS、OU还是其他3D格式。这导致在媒体库中，3D电影和2D电影看起来毫无区别。
2. 海报与信息混杂：3D版和2D版的电影会使用相同的元数据（如TMDB或TVDB的ID），导致它们在海报墙上合并为同一个条目，你无法快速筛选出哪些是3D资源。
3. 播放标签不明：在播放时，客户端（如电视上的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 = 流媒体传输引擎 + 用户管理后台。两者结合，互补短板，实现1+1>2的效果。

1.3 核心工作流程

1. 内容准备：你将所有3D电影文件（如Avatar.3D.HSBS.1080p.mkv）存放在一个独立的文件夹中。
2. Halcyon Video扫描：Halcyon Video扫描该文件夹，根据文件名（或内嵌信息）识别影片，并从其自建的3D电影数据库或TMDB等源获取元数据，关键是为每部电影打上“3D”标签并匹配专属海报。
3. 媒体服务器集成：在Plex中，你添加一个媒体库，其文件夹指向Halcyon Video生成的一个“虚拟目录”或通过Webhook方式连接。Plex从这个“目录”获取影片列表和元数据，而不直接管理原始文件。
4. 用户观影：你在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/11（Pro及以上版本）、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: - PUID=1000 # 改为你宿主机用户的UID，可用 `id -u` 命令查看 - PGID=1000 # 改为你宿主机用户的GID，可用 `id -g` 命令查看 - TZ=Asia/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。

1. 首次访问：你会看到Halcyon Video的欢迎界面，可能需要进行简单的语言选择（通常为英文）和初始配置向导。
2. 设置媒体目录：在配置向导中，它会询问媒体路径。因为我们在Docker Compose中已经将/media映射好了，所以这里通常会自动识别或需要你确认路径为/media。
3. 开始扫描：完成向导后，Halcyon Video会自动开始扫描/media目录下的所有视频文件。你可以在Web界面的“Libraries”或“Dashboard”看到扫描进度。
4. 等待元数据匹配：扫描完成后，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中添加媒体库

1. 打开Plex Web界面，进入“管理” -> “库”。
2. 点击“添加资料库”，选择“电影”。
3. 命名资料库为“3D Movies”或“Halcyon 3D”。
4. 在“添加文件夹”中，浏览并选择我们刚才创建的符号链接目录：/media/plex_libraries/3d_movies。
5. 在“高级”设置中，至关重要的一步：将“扫描器”设置为“Plex Movie Scanner”，但将“代理”设置为“Personal Media”或者“The Movie Database”。这里选择“Personal Media”可以防止Plex用TMDB的2D元数据覆盖掉Halcyon为我们准备好的3D信息。
6. 确保勾选“优先使用本地元数据”（如果使用“Personal Media”代理，这个选项可能默认生效）。
7. 完成添加。

步骤四：进行Plex扫描Plex会开始扫描新的库。由于我们使用了符号链接，Plex实际访问的还是原始文件。关键点在于：Halcyon Video在扫描匹配后，会在每个电影文件夹内生成标准的本地元数据文件，如movie.nfo,poster.jpg,fanart.jpg等。Plex的“Personal Media”扫描器会读取这些本地的.nfo和图片文件来填充库信息。

如果Halcyon没有自动生成这些文件，你可能需要在Halcyon的设置中寻找“导出元数据”或“生成NFO”等选项并启用。有些社区版或特定版本的Halcyon可能集成了此功能。

4.2 验证集成效果

1. 在Plex海报墙中找到新建的“3D Movies”库。
2. 进入该库，你应该能看到所有3D电影，并且海报、背景图、简介都应该是与3D版本相关的（例如，海报上可能带有“3D”标识）。
3. 检查电影信息。在电影详情页，你应该能看到诸如“3D”、“HSBS”、“HOU”等标签或信息被添加到概要、标签或标题中。这证明Plex成功使用了Halcyon提供的本地元数据。
4. 尝试播放一部电影。播放本身由Plex服务器处理。你需要在播放客户端（如Plex for Android TV, Plex HTPC）中，手动开启电视或投影仪的3D模式（对应SBS或OU格式）。

5. 常见问题与排查思路

在部署和使用过程中，你可能会遇到一些问题。下面是一个快速排查指南。

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 --tail=100 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海洋的淹没，以独立的、醒目的姿态出现在海报墙上，等待你下一次开启沉浸式的观影之旅。