如何一步一步地使用 Docker 安装 Jellyfin

使用 Docker 安装 Jellyfin 它可以让您将兼容的电脑、家用服务器或NAS变成一个私人平台，用于播放电影、电视节目、音乐和照片。文件始终由您掌控，您可以通过电视、手机、网络浏览器和其他兼容设备访问它们。

Docker 将 Jellyfin 及其依赖项保存在同一个容器中，从而简化了安装、维护和更新。但是，配置、缓存和元数据必须存储在单独的容器中。 持续性体积 这样，当容器重新创建时，它们就不会消失。

本指南使用 使用 Docker Compose 的 Ubuntu 服务器 以及官方的 Jellyfin 镜像。虽然安装命令和权限管理可能有所不同，但该方法也适用于其他 Linux 发行版。

使用 Docker 安装 Jellyfin 需要哪些条件

开始之前，您需要以下组件：

• 一台运行兼容Linux发行版的服务器或计算机。
• Docker Engine 和 Docker Compose 插件。
• 服务器的静态 IP 地址或 DHCP 保留地址。
• 足够的空间用于配置、缓存和临时转码。
• 对存储多媒体文件的文件夹具有读取权限。
• 稳定的网络连接，最好是通过以太网。

容器化安装官方上是面向 Linux 的。虽然 Docker Desktop 允许在 Windows 和 macOS 上运行容器，但 Jellyfin 警告说，某些功能，尤其是…… 硬件加速转码它们在这些系统上可能无法正常运行。

Jellyfin服务器需要哪些硬件？

需求主要取决于播放类型，而非库的大小。当客户端设备支持文件的格式、编解码器、音频、字幕和比特率时，Jellyfin 就可以使用。 直接播放在这种情况下，服务器几乎不需要处理视频，可以在配置一般的设备上运行。

当 Jellyfin 需要实时转换内容时，工作负载会增加。这可能是由于编解码器不兼容、需要嵌入字幕、比特率过高或需要将 HDR 转换为 SDR 等原因造成的。因此，没有一种固定的核心数或内存容量能够满足所有用户的需求。

对于多个同时转码进程，建议使用支持 Quick Sync 的集成式 Intel GPU、支持 NVENC 的 NVIDIA GPU 或某些 AMD 型号。如果您希望……，还应考虑上传带宽。 在家外也能访问 Jellyfin.

如果您仍在选择硬件和存储设备，请考虑您需要的是专用电脑、迷你电脑还是…… 家庭 NAS.

如何在 Ubuntu 服务器上安装 Docker Engine

首先，更新系统软件包：

sudo apt update
sudo apt upgrade -y

安装必要的工具并添加官方 Docker 密钥：

sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

接下来，配置官方软件仓库：

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

安装 Docker Engine 和 Compose 插件：

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

检查这两个组件是否都可用：

sudo docker run --rm hello-world
sudo docker compose version

您也可以选择将用户添加到该组。 docker 执行命令时 sudo:

sudo usermod -aG docker "$USER"

请注销并重新登录以使更改生效。请记住这一点。 加入 docker 用户组将获得与管理员相同的权限。 关于系统。请勿添加不受信任的用户。

如何准备持久文件夹

创建一个专用文件夹，用于存放合成文件、配置文件和缓存文件：

sudo mkdir -p /opt/jellyfin/config
sudo mkdir -p /opt/jellyfin/cache
sudo chown -R "$(id -u)":"$(id -g)" /opt/jellyfin
cd /opt/jellyfin

媒体文件夹可以位于不同的驱动器上。以下是一个简单的结构：

/srv/media/
├── peliculas/
├── series/
└── musica/

使用这些路线并非强制性的。重要的是要区分…… 主机服务器上的现有路径 以及 Jellyfin 稍后将在容器内看到的路径。

获取将要运行 Jellyfin 的用户的 UID 和 GID：

id -u
id -g

创建一个名为 .env 之内 /opt/jellyfin 并保存所获得的值：

JELLYFIN_UID=1000
JELLYFIN_GID=1000

替换 1000 根据您系统的实际值，该用户应该能够读取所有多媒体目录并写入文件夹。 config y cache.

如何配置 Jellyfin Docker Compose 文件

创建文件 /opt/jellyfin/docker-compose.yml 使用以下配置：

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    user: "${JELLYFIN_UID}:${JELLYFIN_GID}"
    ports:
      - "8096:8096/tcp"
      - "7359:7359/udp"
    volumes:
      - type: bind
        source: ./config
        target: /config
      - type: bind
        source: ./cache
        target: /cache
      - type: bind
        source: /srv/media/peliculas
        target: /media/peliculas
        read_only: true
      - type: bind
        source: /srv/media/series
        target: /media/series
        read_only: true
      - type: bind
        source: /srv/media/musica
        target: /media/musica
        read_only: true
    restart: unless-stopped

港口 8096/TCP 它提供对 Web 界面的访问。端口 7359/UDP 它用于本地网络内的自动发现，如果您不需要此功能，可以将其删除。

多媒体文件以如下方式挂载： 只读这可以降低意外修改的风险，但也会阻止 Jellyfin 将 NFO 文件、图像或其他数据写入媒体文件。如果您想使用这些功能，请移除此功能。 read_only: true 仅保存在必要的文件夹中。

启动服务前请检查语法：

docker compose config

如果命令没有显示任何错误，则下载镜像并启动容器：

docker compose pull
docker compose up -d

查看其状态并查看记录：

docker compose ps
docker compose logs -f jellyfin

按 Ctrl+C 退出日志视图而不停止容器。

如何完成初始设置

在网络上的任意一台计算机上打开浏览器，然后输入：

http://IP_DEL_SERVIDOR:8096

初始设置向导允许您选择语言、创建管理员帐户并添加库。请使用强密码，并将此帐户仅用于管理任务。

添加媒体文件夹时，必须选择 内部容器路线:

• /media/peliculas
• /media/series
• /media/musica

不许进入 /srv/media/peliculas因为该路径仅存在于主机系统上。在容器内部，它已被分配给 /media/peliculas.

为每种类型的内容选择特定的库类型。避免将电影、电视剧和音乐混放在同一个库中。如果需要配置名称、元数据提供程序和文件夹结构，请参阅相关说明。 在 Jellyfin 中添加和整理电影和电视节目.

如何启用英特尔快速同步加速

在兼容的英特尔系统上，首先检查渲染设备是否存在：

ls -l /dev/dri/

它通常会以如下形式出现： /dev/dri/renderD128获取组标识符 render:

getent group render | cut -d: -f3

将结果添加到文件中 .env:

JELLYFIN_RENDER_GID=122

值 122 这只是一个示例。然后将这些代码添加到服务中。 jellyfin 来自 Compose 文件：

    group_add:
      - "${JELLYFIN_RENDER_GID}"
    devices:
      - /dev/dri/renderD128:/dev/dri/renderD128

重新创建容器并验证 Jellyfin 是否可以检测到 GPU：

docker compose up -d
docker exec -it jellyfin /usr/lib/jellyfin-ffmpeg/vainfo

进入 控制面板 > 播放 > 转码选择 Intel Quick Sync 或 VA-API，并仅启用与您的硬件兼容的编解码器。

仅仅将设备添加到容器中并不会自动启用加速。建议播放一个需要转码的文件，并检查 FFmpeg 日志以验证 GPU 是否正常工作。

如何使用NVIDIA GPU

官方 Jellyfin 镜像不包含 NVIDIA 专有驱动程序。您必须同时在主机上安装该驱动程序和镜像。 NVIDIA 容器工具包.

然后将其添加到 Jellyfin 服务中：

    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

重新创建容器并验证卡片是否可见：

docker compose up -d
docker exec -it jellyfin nvidia-smi

最后，选择 NVENC 在转码设置中。除非您确切知道要使用哪个设备，否则请勿将此设置与英特尔的设置一起使用。

如何设置存储在 NAS 上的音乐库。

如果文件位于 NAS 或 Samba 资源上，最稳定的方法是先在 Ubuntu 中挂载网络资源，然后使用绑定挂载将该路径传递给容器。

安装 CIFS 支架并创建安装点：

sudo apt install -y cifs-utils
sudo mkdir -p /mnt/media

将 NAS 凭据保存在只有管理员才能访问的文件中并使用 /etc/fstab 重启后保持挂载点不变。然后将路径添加到 Compose 文件中：

      - type: bind
        source: /mnt/media
        target: /media/nas
        read_only: true

如果 Jellyfin 检测到文件夹但显示为空，请检查资源权限、挂载时使用的 UID 和 GID，以及所有父目录的执行权限。您可以在指南中找到有关此配置的详细说明。 家用NAS存储.

如何从家外访问 Jellyfin

请勿直接在互联网上公开端口 8096。Jellyfin 的文档建议使用 VPN 或在服务器前面放置一个带有 HTTPS 的反向代理。

使用 Tailscale 之类的 VPN 可以让您访问私有网络，而无需直接暴露 Jellyfin。您还可以使用 Caddy、Nginx 或 Traefik 作为反向代理。

Caddy 可以自动获取和续订 TLS 证书，但这通常要求域名指向您的公网 IP 地址，并且 80 和 443 端口可以访问服务器。因此， 反向代理并不一定意味着无需打开端口即可访问。.

如果你想避免传统的公众曝光，请看如何操作 无需打开端口即可从室外访问 Jellyfin.

为了通过单点登录集中管理用户，您还可以 与 Jellyfin 建立真正的联系首先你必须 使用 Docker 安装 Authentik 并仔细配置组和权限。

如何使用 Docker 更新 Jellyfin

更新之前，请先创建备份。 控制面板 > 备份当前版本的 Jellyfin 允许您在服务器仍在运行时生成副本，但最好在没有用户正在玩游戏或进行扫描时执行此操作。

然后更新镜像并重新创建容器：

cd /opt/jellyfin
docker compose pull
docker compose up -d

更新后请查看日志：

docker compose logs --tail=100 jellyfin

持久数据将保留在文件夹中。 config y cache然而，某些版本会对数据库应用迁移，并且 Jellyfin没有降解机制如果需要恢复到以前的版本，则需要恢复兼容的备份。

使用 Docker 安装 Jellyfin 时常见的错误

容器不断重启。

执行 docker compose logs jellyfin 并检查文件夹权限 config y cacheUID 和 GID 定义于 .env 他们必须持有书面许可。

图书馆似乎空无一人。

验证主机路径是否存在，卷是否已正确挂载，以及容器用户可以浏览和读取其所有目录。在 Jellyfin 中，您必须选择内部路径，例如： /media/peliculas.

扫描文件时权限被拒绝

不要通过应用权限来解决问题。 777检查所有者、所属组以及读取和执行权限。如果您使用的是 NAS，还要检查用于挂载资源的设置。

端口 8096 无法打开

可能还有其他进程正在使用该端口。请使用以下命令进行检查：

sudo ss -ltnp | grep 8096

如果端口繁忙，请停止相应的服务或更改映射中的左侧端口。 8097:8096.

GPU 已在主机中显示，但未在 Jellyfin 中显示。

在英特尔网站上，检查设备。 /dev/dri/renderD128 以及组标识符 render在 NVIDIA 控制面板中，检查驱动程序、NVIDIA Container Toolkit 以及以下输出： docker exec -it jellyfin nvidia-smi.

视频仍在占用CPU资源

即使GPU可见，也不意味着所有格式都能加速。请检查支持的编解码器、转码设置和FFmpeg寄存器。某些字幕和滤镜可能仍然在使用CPU。

Jellyfin 可以运行，但不会自动显示在设备上。

检查端口 7359/UDP 它必须在本地网络上发布并允许访问。如果您需要使用 DLNA，官方文档指出您可能需要使用网络模式。 host.

使用 Docker Compose 安装 Jellyfin 它允许您将媒体服务器隔离并简化其管理，但最终的可靠性取决于所使用的卷、权限和路径。容器启动并运行后，您可以添加媒体库、创建用户并为您的硬件启用相应的转码功能。

在将服务暴露于家庭网络之外之前，请配置 HTTPS 或 VPN，并备份配置文件夹。这样，您就可以在不丢失用户、元数据或播放历史记录的情况下更新服务器。