如何一步一步地使用 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，並備份設定資料夾。這樣，您就可以在不遺失使用者、元資料或播放歷史記錄的情況下更新伺服器。