🚀 使用 Docker Compose 部署 Jellyfin

Jellyfin 是一个完全免费且开源的媒体服务器系统，源于 Emby 3.5.2 版本的一个分支。它能让您将所有视频、音乐、图片等媒体资源集中管理，并通过网页浏览器、手机、电视等设备随时随地访问和播放。作为 Emby 和 Plex 的替代品，Jellyfin 没有任何高级付费功能或隐藏费用，所有功能完全免费使用。

📦 项目简介

Jellyfin 的核心价值在于为您打造一个完全自主控制的媒体中心。与需要付费订阅或受限于厂商服务的方案不同，Jellyfin 确保您的媒体库完全私密且由您全权掌控。

主要功能亮点： * 智能媒体库管理：自动从网络获取影片信息、海报、演员信息等元数据，构建精美的媒体墙。 * 多用户支持：创建多个账户，为不同用户设置不同的媒体库访问权限，适合家庭共享。 * 强大的转码能力：支持实时转码，确保媒体能在各种设备和网络条件下流畅播放。通过配置硬件加速，可以显著降低转码时的CPU负载。 * 全平台客户端：支持网页浏览器、iOS/Android移动端、智能电视、游戏机等多种设备。 * 插件扩展系统：可通过插件增强功能，如更多的元数据抓取源、主题界面等。

⚙️ 部署前准备

环境要求
- 已安装 Docker 和 Docker Compose（这是运行 Jellyfin 的必备条件）。
- 系统内存：建议 2GB 以上，如果开启硬件转码或同时服务多个用户，则需要更多内存。
- 磁盘空间：确保有足够空间存储媒体文件及 Jellyfin 的配置、缓存和元数据。
环境检查 在终端中执行以下命令，确认 Docker 环境正常： bash docker --version docker-compose --version
检查硬件加速支持（可选但推荐） 如果您希望使用硬件加速来提升视频转码性能，可以先检查您的显卡驱动： bash ls /dev/dri/ 如果输出类似 card0 renderD128，说明您的系统已支持硬件加速。
创建项目目录 建议创建一个独立的目录来管理 Jellyfin 的所有文件： bash mkdir -p /opt/docker/jellyfin cd /opt/docker/jellyfin

🛠️ 配置 Docker Compose

基于你提供的配置，这里是对 docker-compose.yml 文件的解读和优化说明。你将以下内容保存为 docker-compose.yml 文件即可。

networks:
  videos:
    external: true # 使用已创建的外部网络（需提前执行 docker network create videos）

#version: '3.8'
#version: "3"
services:
  jellyfin:
    image: nyanmisaka/jellyfin # 优化版镜像（支持 Intel 12代+核显加速，比官方镜像更适配国内环境）
    container_name: jellyfin  # 容器名称，便于管理
    #cap_add:
      #- SYS_NICE
    devices:  
      - /dev/dri:/dev/dri  # 挂载显卡设备（Intel 核显硬件加速必需，删除则无法硬件解码）
    #user: uid:gid
    stdin_open: true  # 保持标准输入打开（容器稳定运行必需）
    tty: true  # 分配伪终端（容器稳定运行必需）
    restart: always  # 容器退出后自动重启（开机自启）
    ports:
      - 5000:8096  # 端口映射：主机 5000 端口 → 容器 8096 端口（Web 访问与播放）
    #network_mode: 'host'
    environment:
      - PUID=1000  # 运行用户 ID（默认 1000，对应服务器普通用户，避免权限问题）
      - PGID=1000  # 运行用户组 ID（与 PUID 一致）
      #- TZ=America/New_York
      - TZ=Asia/Shanghai  # 时区（默认上海，确保时间同步）
      #- NVIDIA_VISIBLE_DEVICES=all # 可选，用于NVIDIA+Intel混合场景
      - LIBVA_DRIVER_NAME=iHD  # Intel 12代及以上处理器必需（指定核显驱动，确保硬件加速生效）
      - I965_DRM_DISABLE=1  # 禁用旧版 Intel 驱动（避免 12代+处理器驱动冲突）
    volumes:
      #- ./config:/config
      #- ./cache:/cache

      # 配置目录：保存用户设置、媒体库信息（路径需与提前创建的一致）
      - /mnt/10t/cache/jellyfin/config:/config
      # 缓存目录：保存缩略图、转码临时文件（路径需与提前创建的一致）
      - /mnt/10t/cache/jellyfin/cache:/cache
      # 媒体目录：挂载本地媒体文件（容器内路径为 /media，后续添加媒体库需选择此路径下的子目录）
      - /mnt/10t/videos:/media

    networks:
      videos:
        ipv4_address: 10.1.1.5  # 容器在 videos 网络中的固定 IP（默认即可，无需修改）
        #ipv6_address: 2001:3984:3989::10

关键配置说明：

配置项	说明与建议
`image`	你使用的是 `nyanmisaka/jellyfin`，这是一个针对 Intel 显卡优化的非官方镜像。官方镜像为 `jellyfin/jellyfin`。
`devices`	`/dev/dri` 的映射对于硬件加速至关重要。它允许容器直接访问宿主机的显卡资源。；Intel 核显硬件加速必需，删除后只能用 CPU 解码（播放 4K 会卡顿）；NVIDIA 显卡需额外添加 `NVIDIA_VISIBLE_DEVICES=all` 环境变量。
`ports`	`"5000:8096"` 将容器内的 8096 端口映射到主机的 5000 端口。你可按需修改主机端口（如 `"8096:8096"`），容器端口一般不变。
`volumes`	`/config` 的映射用于持久化 Jellyfin 的所有配置和元数据，务必确保目录正确。`/media` 映射了你的媒体库。
`environment`	`LIBVA_DRIVER_NAME=iHD` 是针对 Intel 第 12 代及更新处理器的重要设置。旧款 Intel CPU 可能需要设置为 `i965`。
LIBVA_DRIVER_NAME=iHD	仅 Intel 12 代及以上处理器需要，10/11 代处理器可改为 `LIBVA_DRIVER_NAME=i965`（否则硬件加速不生效）。

注意：关于镜像选择，请知晓你使用的 nyanmisaka/jellyfin 并非官方镜像。若追求稳定性和官方支持，可考虑改用 jellyfin/jellyfin:latest。

🚀 启动与验证

启动服务 在 docker-compose.yml 文件所在目录执行： bash docker-compose up -d 此命令会拉取镜像并在后台启动容器。
检查服务状态 bash docker-compose ps 如果看到 jellyfin 容器的状态为 Up，说明服务已成功启动。
查看实时日志（可选） 如果遇到问题，可以通过以下命令查看容器日志来排查： bash docker-compose logs -f jellyfin
访问 Web 界面 打开浏览器，访问 http://你的服务器IP:5000。
- 如果一切正常，你将看到 Jellyfin 的初始化界面。

⚙️ 基础配置与使用

初始化设置
- 语言选择：在欢迎页面选择 "简体中文"。
- 创建管理员账户：设置你的用户名和密码（例如配置中提示的 admin / Clxr20）。
- 添加媒体库：这是核心步骤。
  - 点击"添加媒体库"，选择内容类型（电影、电视节目等）。
  - 在"文件夹"选项中，点击"添加文件夹"，此处应填写容器内的媒体文件夹路径。根据你的配置，例如 /media。请务必使用容器内路径，而非宿主机路径。
  - 建议为电影、电视剧、音乐等不同类型的内容分别创建媒体库，并选择对应的元数据语言（如"中文"）。
配置硬件加速（提升性能关键）
- 进入 Emby 管理后台 "控制台" -> "播放" -> "转码"。
- 在 "硬件加速" 下拉菜单中，根据你的显卡选择：
  - Intel 核显：选择 "Intel QuickSync (QSV)"。
  - AMD 显卡：选择 "VAAPI"。
  - NVIDIA 显卡：选择 "NVIDIA NVENC"。
- 开启 "启用硬件解码" 和 "启用硬件编码"。
设置元数据抓取（让媒体库更美观）
- 在媒体库设置中，配置元数据抓取语言为"中文"。
- 常用的元数据抓取器包括 "The Movie Database" 和 "The Open Movie Database"。
配置远程访问（可选）
- 如果你有公网 IP 和域名，可考虑配置 HTTPS 安全访问。
- 也可通过内网穿透工具实现外网访问。

🔒 维护与管理

服务管理：
- 停止服务：docker-compose down
- 重启服务：docker-compose restart
- 查看服务状态：docker-compose ps
数据备份：
- 定期备份 docker-compose.yml 文件以及映射的 /config 目录（在你的配置中是 /mnt/10t/cache/jellyfin/config），这里包含了所有 Jellyfin 的配置、用户数据和元数据。
版本更新： bash # 进入 docker-compose.yml 所在目录 docker-compose down docker-compose pull # 拉取最新镜像 docker-compose up -d # 可选：清理无用镜像 docker image prune
日志维护：
- 如果遇到活动日志清理任务失败，可能是SQLite数据库文件损坏，可以尝试手动清理或重建数据库。
- 服务器重启后若出现数据库只读错误，可能与 Playback Reporting 插件有关，可尝试暂时禁用该插件。

🐛 常见问题排查 (FAQ)

问题现象	可能原因与解决方法
无法访问 Web 界面	1. 检查防火墙/安全组是否放行 5000 端口。 2. 确认容器运行正常：`docker-compose ps`。 3. 查看日志：`docker-compose logs jellyfin`。
媒体库扫描不到文件	1. 检查卷映射：确认宿主机媒体目录（如 `/mnt/10t/videos`）存在且有媒体文件。 2. 检查容器内路径：在添加媒体库时，务必使用容器内路径（如 `/media`）。 3. 检查权限：容器内进程（根据 `PUID`/`PGID`）需要对宿主机挂载的目录有读取权限。
硬件加速不工作或转码失败	1. 确认 `devices` 配置正确，且宿主机 `/dev/dri` 设备存在。 2. 对于 Intel 12 代 CPU，确保设置了 `LIBVA_DRIVER_NAME=iHD`。 3. 在 Jellyfin 转码设置中正确选择硬件加速类型。
元数据（海报、简介）刮削失败	1. 检查网络连接，特别是 DNS 设置。可尝试在容器内修改 hosts 文件，将元数据网站（如 `api.themoviedb.org`）解析到可用 IP。 2. 在媒体库设置中尝试更换元数据下载器。
中文界面或字幕显示异常	1. 确保在初始化时选择了"简体中文"。 2. 对于中文字幕显示问题，可以安装中文字体到容器内，并在 Jellyfin 的"播放"设置中指定备用字体路径。

💡 提示：如果遇到插件兼容性问题导致服务异常，可以进入 Jellyfin 的插件目录，暂时移除有问题的插件文件，然后重启服务。

希望这份教程能帮助你顺利完成 Jellyfin 的部署，享受打造私人影音世界的乐趣！