Jellyfin与Linux系统的兼容性测试

Jellyfin与Linux系统的兼容性测试方案

一 测试目标与范围

• 验证在不同发行版与部署形态下（Ubuntu/Debian、CentOS、Docker）的安装、启动、基础功能与稳定性。
• 评估硬件加速（Intel Quick Sync、AMD AMF、NVIDIA NVENC/NVDEC、VAAPI）的可用性与转码性能。
• 覆盖常见播放场景：H.264/H.265/AV1 视频、外挂字幕（含CJK）、局域网多客户端并发、远程访问与反向代理。
• 识别并复现典型问题：字幕乱码、媒体库扫描慢、播放卡顿、驱动缺失等，并形成可复现的验证步骤与修复方案。

二 测试环境设计

• 硬件矩阵
  • CPU/GPU：Intel Core i5-10代及以上（支持iHD）、Intel J4105/N5105/Elkhart Lake、AMD GCN 1.0+（r600/radeonsi）、NVIDIA GTX 10系+/Turing+、以及ARM SBC（如RK3399）。
  • 存储与网络：SSD/NVMe、SATA HDD、USB3.0/eMMC、千兆/2.5G/万兆 网络。
• 系统与版本
  • 发行版：Ubuntu 20.04/22.04/24.04、Debian 11/12、CentOS 7/Stream 8/9、Arch Linux。
  • 容器：Docker 20.10+、可选 Podman。
• 软件与驱动
  • 内核：5.4+（建议 5.15+ 获取更好的 iGPU 支持）。
  • 显卡驱动：intel-media-va-driver-non-free（iHD）、mesa-va-drivers（r600/radeonsi）、nvidia-driver + nvidia-container-toolkit。
• 客户端
  • 浏览器（Chrome/Edge/Firefox）、Jellyfin Desktop、Kodi + Jellyfin 插件、Android/iOS 官方客户端、VLC 作为对照播放器。

三 测试用例与步骤

• 安装与部署
  • 原生安装（APT/RPM）：导入 GPG、添加官方仓库、安装包、启动服务，访问 http://:8096 完成初始化。
  • Docker 安装：拉取镜像、映射 /config /cache /media、暴露 8096/8920/7359/1900（HTTP/HTTPS/SSDP/UPnP），验证容器日志与端口连通。
• 基础功能
  • 媒体库：添加电影/剧集库，验证元数据抓取、封面/字幕自动匹配、定时刷新。
  • 播放：内嵌与外挂字幕（SRT/ASS/SSA）、音轨切换、字幕样式与同步、播放速度/章节跳转。
  • 网络：局域网直连与 WAN 远程访问、反向代理（Nginx/Apache + HTTPS）、带宽/码率自适应。
• 硬件加速
  • Intel QSV：安装 iHD，Jellyfin 控制台选择 QSV，VA-API 信息检查（vainfo/jellyfin-ffmpeg），验证 H.264/H.265/VP9/AV1 硬解与 HDR→SDR 色调映射（OpenCL/VPP）。
  • AMD AMF：安装 AMF 驱动，选择 AMF 路径，验证 H.264/H.265 硬解/转码。
  • NVIDIA NVENC/NVDEC：安装 nvidia-driver 与 nvidia-container-toolkit，选择 NVENC/NVDEC，验证 H.264/H.265/AV1 硬解/转码与并发转码数。
  • VAAPI（通用）：验证 VAAPI 在 Intel/AMD 上的硬解与转码，检查驱动加载与解码路径。
• 稳定性与异常
  • 长时间播放（≥24小时）、多客户端并发（≥5路）、大库扫描（≥10,000 条目）、异常重启与恢复、磁盘/网络抖动场景。
• 性能与观测
  • 转码性能：记录 CPU/GPU 占用、转码码率、帧率、首帧时间、卡顿次数。
  • 观测工具：intel_gpu_top、nvidia-smi、ffmpeg -hwaccel、容器资源限制（CPU/内存/IO）。

四 关键判定标准

• 安装与可用性：各发行版与 Docker 方式均能成功安装、启动、访问控制台，基础播放与媒体库功能无崩溃/无致命错误。
• 硬件加速：目标编解码在对应平台能启用硬解/硬转，转码后画质正常、音画同步、无明显卡顿。
• 字幕与本地化：CJK 字幕正常显示，无方块乱码；外挂字幕编码/换行/样式正确。
• 网络与并发：远程访问稳定，带宽/码率自适应生效；并发播放下无异常中断。
• 稳定性：长时间运行与多场景切换后服务不崩溃、资源占用稳定、日志无致命错误。

五 常见问题与修复要点

• 字幕乱码：安装中文字体（如 Noto CJK），重启 Jellyfin 后重新扫描/播放。
• 媒体库扫描慢：优化存储/网络（本地盘优先、避免高延迟挂载），必要时使用本地元数据代理与定时刷新。
• 播放卡顿：优先启用硬件加速（QSV/AMF/NVENC/NVDEC/VAAPI），客户端首选 LibVLC，必要时降低码率或分辨率。
• Intel QSV 在容器中不可用：官方 jellyfin/jellyfin 镜像不含 iHD，可改用包含驱动的社区镜像（如 nyanmisaka/jellyfin），或在宿主机正确安装 iHD 并映射 /dev/dri。
• 老显卡 VAAPI 驱动缺失：在容器中安装 mesa-va-drivers，通过 vainfo 验证 r600/radeonsi 驱动加载与解码能力。
• ARM 平台硬解异常：如 RK3399 + Debian 出现周期性卡顿，先用 VLC 验证播放器硬解能力，排查 内核/驱动/FFmpeg 版本与调用路径差异。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！