Jellyfin 在 Linux 上的兼容性问题与对策
总体兼容性与系统支持
常见兼容性问题一览
| 问题类别 | 典型表现 | 常见触发因素 | 解决思路 |
|---|---|---|---|
| 发行版与版本支持 | 安装失败、依赖解析错误、启动异常 | 老系统（如 CentOS 7）仓库过旧；Ubuntu 18.04 不在最新官方支持列表 | 升级至 Ubuntu 20.04+；或改用 Docker；在 CentOS 上启用 EPEL/RPM Fusion 并手动补齐依赖 |
| FFmpeg 与多媒体编解码 | 转码失败、播放报错、某些格式黑屏 | 系统缺少 FFmpeg 或版本不匹配；Jellyfin 内置/系统 FFmpeg 路径不一致 | 安装系统 FFmpeg（如 RPM Fusion 的 ffmpeg/ffmpeg-devel）；必要时在 Jellyfin 设置中指定 FFmpeg 路径 |
| 硬件加速（VAAPI/Intel/AMD/NVIDIA） | 转码不可用、CPU 占用高、画面卡顿 | 老内核/驱动不匹配；容器未映射 /dev/dri；权限不足 | 升级内核与驱动；容器添加设备映射与权限；按需配置 VAAPI/AMF/NVENC |
| 存储与权限 | 媒体库扫描不到、播放报 403/404、封面/字幕方块 | 运行用户与媒体文件所有者不一致；挂载点权限/SELinux/ACL 限制；S3 等对象存储未挂载为本地文件系统 | 统一运行用户与目录所有者（如 jellyfin:jellyfin）；检查挂载与权限；S3 用 s3fs-fuse 挂载为本地路径 |
| 网络与防火墙 | 无法访问 8096/8920 端口、外网不可达 | firewalld/ufw 未放行端口；端口被占用；反向代理配置错误 | 放行 8096/TCP（HTTP）与 8920/TCP（HTTPS）；排查端口占用；核对反向代理 WebSocket 与协议头 |
| 插件与版本兼容性 | 升级后插件报错、页面空白、功能异常 | 插件未适配新版本 Jellyfin | 暂时禁用/回退插件；升级到兼容版本；必要时回滚 Jellyfin 版本 |
| 字体与界面渲染 | 封面/字幕中文显示为方块 | 系统缺少中文字体 | 安装中文字体包（如 fonts-wqy-zenhei 等）或挂载字体目录 |
| 安全与漏洞 | 特定版本存在任意文件读取等风险 | 运行旧版本 | 及时升级到包含修复的版本（如修复 CVE-2021-21402 的版本） |
| 容器化特有 | 硬件加速不可用、设备不可见、权限被拒 | 未映射 /dev/dri、未开启特权/能力、卷权限错误 | 正确映射设备与权限（如设备 /dev/dri、适当 capabilities）；核对卷挂载与用户映射 |
快速排查与规避建议
