中文

应用程序

在 Debian 或 Ubuntu 上安装 Jellyfin

从官方软件源安装 Jellyfin,通过 Caddy 以 HTTPS 发布,管理账户,了解没有 GPU 时转码的局限,并完成更新与备份。

阅读约 10 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

本指南介绍如何从官方软件源安装免费开源的媒体服务器 Jellyfin。配置向导通过 SSH 隧道完成,随后由 Caddy 以 HTTPS 发布该服务。

完成本指南后,Jellyfin 将通过 https://jellyfin.您的域名.com 响应,其端口无法从互联网访问,每个人都拥有自己的账户,并且您会清楚在没有显卡的情况下,您的服务器实际能够推送多少流。

订购服务器

本指南适用于由您自行管理的服务器:

前提条件

Jellyfin 的文档建议为系统、Jellyfin 文件和转码缓存(不含媒体)配备 8 GB 内存和 100 GB SSD。对于远程访问,文档建议上传带宽至少为 20 Mbit/s。

使用的端口

端口 方向 作用 是否需要开放
80/tcp 入站 证书验证以及重定向到 HTTPS 是
443/tcp 入站 通过 HTTPS 访问 Jellyfin 是
443/udp 入站 HTTP/3 建议开放
8096/tcp 本地 Jellyfin 的 HTTP 界面 否
8920/tcp 本地 内置 HTTPS,此处不使用 否
7359/udp 本地 局域网发现,对远程服务器无用 否

步骤 1:检查防火墙

终端
sudo ufw status verbose
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp

第一条命令应显示 Status: active,且入站策略为 deny。如果不是这样,请先停下来并启用 UFW。不要为 8096 添加任何规则。

步骤 2:添加官方软件源

安装所需的工具和软件源的签名密钥:

终端
sudo apt update
sudo apt install -y curl gnupg
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.jellyfin.org/jellyfin_team.gpg.key | sudo gpg --dearmor --yes -o /etc/apt/keyrings/jellyfin.gpg

仅限 Ubuntu,请启用 Universe 组件,它提供 FFmpeg 的一些依赖项:

终端
sudo apt install -y software-properties-common
sudo add-apt-repository -y universe

然后声明软件源:

终端
export VERSION_OS="$(awk -F'=' '/^ID=/{ print $NF }' /etc/os-release)"
export VERSION_CODENAME="$(awk -F'=' '/^VERSION_CODENAME=/{ print $NF }' /etc/os-release)"
export DPKG_ARCHITECTURE="$(dpkg --print-architecture)"
cat <<EOF | sudo tee /etc/apt/sources.list.d/jellyfin.sources
Types: deb
URIs: https://repo.jellyfin.org/${VERSION_OS}
Suites: ${VERSION_CODENAME}
Components: main
Architectures: ${DPKG_ARCHITECTURE}
Signed-By: /etc/apt/keyrings/jellyfin.gpg
EOF
sudo apt update

步骤 3:安装指定版本

Jellyfin 要求更新时不要跳过主版本。因此,本指南安装的是选定的版本,并将其锁定,避免 apt upgrade 在您不知情时更改它。

软件包带有与您的系统相关的后缀,例如 deb13 或 ubu2404:

终端
. /etc/os-release
case "$ID" in
  debian) SUFFIX="deb${VERSION_ID}" ;;
  ubuntu) SUFFIX="ubu$(echo "$VERSION_ID" | tr -d .)" ;;
esac
echo "$SUFFIX"
apt-cache madison jellyfin-server | head -n 5

安装该版本,然后将其锁定:

终端
sudo apt install -y "jellyfin=12.4+${SUFFIX}" "jellyfin-server=12.4+${SUFFIX}" "jellyfin-web=12.4+${SUFFIX}"
sudo apt-mark hold jellyfin jellyfin-server jellyfin-web

该软件包还会安装 jellyfin-ffmpeg,即适配 Jellyfin 的 FFmpeg 版本。检查服务:

终端
systemctl status jellyfin --no-pager
curl -fsS http://127.0.0.1:8096/health

最后一条命令应返回 Healthy。从您的电脑上,该端口应保持关闭:

终端
nc -vz -w 5 您的服务器IP 8096

此命令应当失败。如果没有 nc,请在浏览器中打开 http://您的服务器IP:8096:页面不应加载。如果连接成功,请先用 sudo systemctl stop jellyfin 停止 Jellyfin,并修正防火墙,然后再继续。

步骤 4:准备媒体

创建一个 Jellyfin 服务可读取、且您的用户可写入的文件夹:

终端
sudo mkdir -p /srv/media/movies /srv/media/shows /srv/media/music
sudo chown -R 您的用户名:jellyfin /srv/media
sudo chmod -R u=rwX,g=rX,o= /srv/media
sudo find /srv/media -type d -exec chmod g+s {} +

在您的电脑上,使用 rsync 发送文件:

终端
rsync -avh --progress ./my-videos/ 您的用户名@您的服务器IP:/srv/media/movies/

步骤 5:通过 SSH 隧道完成向导

在您的电脑上打开隧道,并保持该会话处于打开状态:

终端
ssh -L 8096:127.0.0.1:8096 您的用户名@您的服务器IP

打开 http://localhost:8096,然后按照向导操作:

  1. 选择语言。
  2. 使用长且唯一的密码创建管理员账户。
  3. 选择 /srv/media 中的文件夹来添加媒体库,也可以跳过这一步。
  4. 选择元数据的语言。
  5. 保持勾选允许远程连接:在代理之后,您的访客会被视为远程用户。

步骤 6:将 Jellyfin 限制在本地回环

登录后,打开控制台 > 网络,并填写:

字段 值 作用
本地网络地址(可选) 127.0.0.1 Jellyfin 只在服务器本机监听
代理服务器地址 127.0.0.1 Jellyfin 接受来自 Caddy 的 X-Forwarded-* 请求头

保存,然后重启服务并检查监听情况:

终端
sudo systemctl restart jellyfin
sudo ss -ltnp | grep 8096
sudo grep -A1 -E '<(KnownProxies|LocalNetworkAddresses)>' /etc/jellyfin/network.xml

该端口应仅显示为 127.0.0.1:8096。SSH 隧道依然可以使用。

如果没有已知代理,Jellyfin 会忽略 Caddy 传来的地址,并把所有访客都视为本地访客:此时对远程访问的限制将不再生效。

步骤 7:通过 HTTPS 发布 Jellyfin

将此站点添加到 /etc/caddy/Caddyfile,或添加到 /etc/caddy/sites/ 中的某个文件:

caddyfile
jellyfin.您的域名.com {
	reverse_proxy 127.0.0.1:8096
}

Caddy 无需任何特殊设置即可转发 Jellyfin 使用的 WebSocket。请不要在此站点上启用完整的访问日志:Jellyfin 的某些 URL 可能包含 api_key 参数。

终端
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

验证结果

终端
curl -I http://jellyfin.您的域名.com
curl -fsS https://jellyfin.您的域名.com/health

第一条命令应返回指向 HTTPS 的 308 重定向,第二条应返回 Healthy。然后登录 https://jellyfin.您的域名.com,播放一段视频,并确认它能够启动。在 Jellyfin 应用中,请将同一地址填写为服务器。

管理账户

在控制台 > 用户中,使用添加用户为每个人创建一个账户。您自己观看内容时,请使用一个没有管理员权限的账户。

对于每个账户,请检查以下设置:

  • 仅限访问确有必要的媒体库;
  • 启用从登陆页面隐藏此用户,以免暴露账户列表;
  • 填写用户被锁定前可尝试登录的次数,例如 5。此锁定默认不启用,达到阈值后该账户会被停用;
  • 如果服务器无法承受,请取消勾选允许播放需要转码的视频。

Jellyfin 没有原生的双重验证:请强制使用长且唯一的密码。要重新启用被锁定的账户,管理员需要在其资料中取消勾选禁用此用户。因此请另外保留一个备用的管理员账户。

了解没有 GPU 时的局限

Jellyfin 有四种播放文件的方式,从最轻量到最耗资源依次为:

模式 处理方式 服务器负载
Direct Play 文件原样发送 几乎为零
Remux 更换容器,保留流 低
Direct Stream 转换音频,保留视频 低到中等
Transcode 即时重新编码视频 非常高

为了保持良好的使用条件:

  • 优先选择设备原生支持的格式,可查阅编解码器兼容性表。
  • 在播放期间查看控制台中的播放模式:它会显示视频是否正在被转码以及原因。
  • 为相关账户禁止视频转码。不兼容的文件可能因此无法播放,但不会再让服务器不堪重负。
  • 限制线程数:在控制台 > 播放 > 转码中,使用转码线程数。服务器会保持响应,但播放可能出现卡顿。
  • 避免码率限制过低,设置位于播放 > 流媒体传输。码率超过**互联网流媒体传输比特率限制(Mbps)**的视频会被转码以适应该限制。
  • 留意磁盘:临时文件存放在 /var/cache/jellyfin/transcodes。请预留大约您最大文件的大小乘以同时播放的流数。

如果您的服务器配有兼容的 GPU,请参阅硬件加速文档。同时也要考虑您所用套餐的带宽和流量额度:每一路流消耗的码率都接近文件本身的码率。

更新 Jellyfin

Jellyfin 无法回退:首次启动时,迁移会修改数据。请查阅发行说明,并在任何更新之前先备份。

查看已安装的版本和可用的版本:

终端
jellyfin --version
sudo apt update
apt-cache madison jellyfin-server

备份之后,请将 12.4 替换为目标版本:

终端
. /etc/os-release
case "$ID" in
  debian) SUFFIX="deb${VERSION_ID}" ;;
  ubuntu) SUFFIX="ubu$(echo "$VERSION_ID" | tr -d .)" ;;
esac
TARGET=12.4
sudo apt-mark unhold jellyfin jellyfin-server jellyfin-web
sudo apt install -y "jellyfin=${TARGET}+${SUFFIX}" "jellyfin-server=${TARGET}+${SUFFIX}" "jellyfin-web=${TARGET}+${SUFFIX}"
sudo apt-mark hold jellyfin jellyfin-server jellyfin-web
sudo journalctl -u jellyfin --no-pager -n 50

备份与恢复

自 Jellyfin 10.11 起,控制台 > 备份 > 创建备份可以在服务器运行时生成归档。它存放在 /var/lib/jellyfin/data/backups 中,要求至少有 5 GB 可用空间,并可在同一页面中恢复。请将这些归档复制到服务器之外。

手动方式适合在更新之前使用,因为它保留全部配置,并且在服务停止时执行:

终端
sudo systemctl stop jellyfin
sudo mkdir -p /var/backups/jellyfin
sudo tar -czpf "/var/backups/jellyfin/jellyfin-$(date +%F)-$(dpkg-query -W -f='${Version}' jellyfin-server).tar.gz" /etc/jellyfin /var/lib/jellyfin
sudo systemctl start jellyfin
sudo chmod -R go-rwx /var/backups/jellyfin

文件名中包含版本号:请使用同一版本来恢复它。检查归档中是否包含数据库:

终端
sudo sh -c 'tar -tzf "$(ls -1t /var/backups/jellyfin/*.tar.gz | head -n 1)" | grep "jellyfin.db$"'

要恢复,请替换归档名称:

终端
ARCHIVE=/var/backups/jellyfin/jellyfin-2026-11-18-12.4+deb13.tar.gz
sudo systemctl stop jellyfin
sudo mv /var/lib/jellyfin /var/lib/jellyfin.bak
sudo mv /etc/jellyfin /etc/jellyfin.bak
sudo tar -xzpf "$ARCHIVE" -C /
sudo systemctl start jellyfin

这些备份不包含您的媒体。请单独保存 /srv/media,例如使用 rsync 同步到其他位置。

故障排除

Unable to locate package jellyfin 或软件源错误

检查软件源文件以及您的版本代号:

终端
cat /etc/apt/sources.list.d/jellyfin.sources
sudo apt update

Suites 的值应为 bookworm、trixie、jammy 或 noble。URIs 应以 debian 或 ubuntu 结尾。

Version '12.4+...' for 'jellyfin' was not found

变量 SUFFIX 为空,或该版本在您的系统上不存在。请运行 echo "$SUFFIX",然后与 apt-cache madison jellyfin-server 的输出比对。

Ubuntu 上 jellyfin-ffmpeg 的依赖项未满足

Universe 组件尚未启用。请重新执行步骤 2 中的 add-apt-repository 命令,然后执行 sudo apt update。

address already in use

另一个程序占用了 8096 端口:

终端
sudo ss -ltnp | grep 8096
sudo journalctl -u jellyfin --no-pager -n 50

浏览器中出现 502 错误

Jellyfin 已停止,或没有监听在 127.0.0.1:8096 上。请使用 systemctl status jellyfin --no-pager 和 curl -fsS http://127.0.0.1:8096/health 检查。更新后的首次启动时,迁移可能需要一些时间。

修改网络设置后界面无法访问

请在服务停止的状态下直接修正配置:

终端
sudo systemctl stop jellyfin
sudo nano /etc/jellyfin/network.xml
sudo systemctl start jellyfin

LocalNetworkAddresses 和 KnownProxies 应各自包含 <string>127.0.0.1</string>。

远程连接被拒绝

请确认在控制台 > 网络中已勾选允许远程连接,并且该用户的资料中也允许远程访问。

媒体库一直为空

服务很可能没有访问这些文件的权限:

终端
sudo -u jellyfin ls -la /srv/media/movies

如果出现 Permission denied,请重新执行步骤 4 中的命令,然后重新扫描媒体库。

播放卡顿,或处理器一直保持 100%

视频很可能正在被转码。请在控制台中检查播放模式,然后应用有关没有 GPU 时的局限那一节中的建议。转换错误可在 /var/log/jellyfin 的文件中找到:

终端
sudo ls -lt /var/log/jellyfin | head

播放期间出现 No space left on device

转码缓存已占满磁盘:

终端
df -h /var/cache/jellyfin
sudo du -sh /var/cache/jellyfin/transcodes

参考资料