Ubuntu 上 Jellyfin 兼容性测试方案
一 测试目标与环境准备
- 目标：验证 Jellyfin 在 Ubuntu 上的安装部署、硬件解码、网络访问、字幕渲染与常见播放场景的稳定性与性能。
- 推荐环境：
- 宿主机：Ubuntu 20.04/22.04/24.04 LTS（桌面或服务器版均可）
- 客户端：主流 网页浏览器、Android/iOS、智能电视/流媒体盒子、Kodi 插件
- 资源：≥4 核 CPU、≥4 GB 内存、SSD 存储；如涉及转码建议配备 Intel 核显 或 NVIDIA GPU
- 部署方式：优先准备两套并行环境用于对比
- 原生 APT 安装（系统级依赖清晰）
- Docker 安装（环境隔离、回滚方便）
二 快速验证步骤
- APT 安装与连通性
- 添加官方仓库并安装：
- sudo apt update && sudo apt install -y apt-transport-https ca-certificates curl gnupg
- sudo mkdir -p /etc/apt/keyrings
- curl -fsSL https://repo.jellyfin.org/jellyfin_team.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/jellyfin.gpg
- echo “deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/jellyfin.gpg] https://repo.jellyfin.org/ubuntu $(lsb_release -cs) main” | sudo tee /etc/apt/sources.list.d/jellyfin.sources > /dev/null
- sudo apt update && sudo apt install -y jellyfin
- 服务与访问：
- sudo systemctl status jellyfin（应为 active/running）
- 浏览器访问 http://服务器IP:8096 完成初始化（创建管理员、添加媒体库）
- Docker 安装与连通性
- 运行容器（示例）：
- docker run -d --name jellyfin -p 8096:8096 -v /path/to/media:/media -e PUID=1000 -e PGID=1000 jellyfin/jellyfin
- 访问 http://服务器IP:8096 完成初始化
- 基础功能检查
- 媒体库扫描、元数据抓取、海报/剧照下载
- 多用户与权限、播放历史与继续播放
- 局域网多设备访问（同网段与跨 VLAN 场景各测一次）
三 专项兼容性测试用例
- 硬件解码与转码
- Intel 平台：安装 intel-media-va-driver-non-free，在 Jellyfin 后台启用 VAAPI/Quick Sync；播放 H.264/H.265/VP9/AV1 的 1080p/4K 文件，观察是否走硬解、CPU 占用是否显著降低
- NVIDIA 平台：安装 NVIDIA 驱动与容器工具，启用 NVENC/NVDEC，对比软解/硬解 CPU/GPU 占用与流畅度
- 字幕渲染
- SRT/SSA/ASS 常见编码；中文字幕验证是否出现“方块乱码”，必要时安装中文字体并重启 Jellyfin
- 网络与访问
- 直连与 Nginx/Apache 反向代理（HTTP/HTTPS、域名访问）、局域网与公网访问、带宽/并发压力下的稳定性
- 客户端兼容性
- 网页端、Android/iOS 原生 App、智能电视/盒子（如 Android TV）、Kodi 插件；不同编解码与容器封装组合下的播放成功率
- 资源与稳定性
- 多用户并发播放、定时任务（库扫描/元数据刷新）、长时间运行（≥24 小时）下的内存/句柄泄漏与异常重启情况
四 判定标准与结果记录
- 判定标准
- 安装与升级：APT 与 Docker 两种部署方式均能成功安装、启动、访问控制台；APT 源与 GPG 校验通过
- 播放体验：1080p/4K 本地直连播放无明显卡顿；启用硬解后 CPU 占用显著下降；不同客户端首帧起播时间可接受
- 字幕渲染：中英文字幕显示正常，无乱码或错位
- 稳定性：并发播放与长时间运行无崩溃/重启；日志无持续性错误
- 建议记录表
| 测试项 |
前置条件 |
操作步骤 |
预期结果 |
实际结果 |
结论 |
| APT 安装 |
Ubuntu 22.04/24.04 |
添加官方源并安装，访问 :8096 |
安装成功、服务运行、页面可访问 |
|
|
| Docker 安装 |
Docker 已安装 |
运行官方镜像，访问 :8096 |
容器启动、页面可访问 |
|
|
| Intel QSV 硬解 |
Intel 核显、驱动已装 |
播放 H.265 4K，查看转码信息 |
显示 QSV/VAAPI，CPU 占用低 |
|
|
| 字幕中文 |
中文字幕文件 |
播放含中文 ASS/SRT |
字幕正常无方块 |
|
|
| 反向代理 |
Nginx/Apache 已配置 |
通过域名 HTTPS 访问 |
正常播放、证书有效 |
|
|
| 并发播放 |
≥3 客户端 |
同时播放不同码率 |
无明显卡顿与崩溃 |
|
|
五 常见问题与修复要点
- 安装阶段提示找不到软件包：Jellyfin 不在 Ubuntu 标准源，需添加 官方 APT 仓库 后再安装
- 登录/访问异常：先检查 Jellyfin 服务状态 与端口监听（默认 8096），再排查防火墙/反向代理配置
- 播放卡顿或高 CPU：启用 硬件加速（Intel QSV/VAAPI、NVIDIA NVENC/NVDEC），并在客户端优先选择 硬件解码
- 字幕乱码：安装 中文字体（如文泉驿、Noto 等）并重启 Jellyfin 服务
- 媒体库扫描慢：检查媒体存储性能与网络挂载；必要时优化媒体源或更新元数据
