在 Debian 或 Ubuntu 上安装 Jellyfin
从官方软件源安装 Jellyfin,通过 Caddy 以 HTTPS 发布,管理账户,了解没有 GPU 时转码的局限,并完成更新与备份。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
本指南介绍如何从官方软件源安装免费开源的媒体服务器 Jellyfin。配置向导通过 SSH 隧道完成,随后由 Caddy 以 HTTPS 发布该服务。
完成本指南后,Jellyfin 将通过 https://jellyfin.您的域名.com 响应,其端口无法从互联网访问,每个人都拥有自己的账户,并且您会清楚在没有显卡的情况下,您的服务器实际能够推送多少流。
订购服务器
本指南适用于由您自行管理的服务器:
前提条件
- 运行 Debian 12 或 13,或 Ubuntu 22.04 或 24.04 的 amd64 或 arm64 服务器
- 使用具有
sudo权限的用户进行 SSH 访问 - 已启用 UFW,并已按照指南配置 UFW 防火墙并避免失去 SSH 访问完成配置
- Caddy,已按照指南使用 Caddy 反向代理并自动启用 HTTPS安装
- 为
jellyfin.您的域名.com创建一条指向您的服务器IP的 DNS A 记录,例如参照指南创建 A 记录 - 足够的磁盘空间,用于存放媒体、元数据和转码缓存
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,然后按照向导操作:
- 选择语言。
- 使用长且唯一的密码创建管理员账户。
- 选择
/srv/media中的文件夹来添加媒体库,也可以跳过这一步。 - 选择元数据的语言。
- 保持勾选允许远程连接:在代理之后,您的访客会被视为远程用户。
步骤 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/ 中的某个文件:
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 updateSuites 的值应为 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 jellyfinLocalNetworkAddresses 和 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