CentOS 上 Jellyfin 的兼容性与应对
总体兼容性概览
- 在 CentOS 7/8 上，Jellyfin 通过 RPM 包、Docker 容器等方式均可稳定运行，整体兼容性较好。常见问题是 依赖缺失（如 libicu、fontconfig）、FFmpeg 版本不匹配、防火墙/SELinux 限制、以及 插件/版本升级带来的变更。针对这些问题，优先补齐依赖、使用官方仓库或静态 FFmpeg、按需放行端口与 SELinux 策略，可显著降低兼容性风险。
常见兼容性问题与修复要点
- 依赖与运行库：未安装 libicu、fontconfig 会导致启动或界面异常。修复：执行
yum install -y libicu fontconfig。
- FFmpeg 编解码异常：系统自带的 FFmpeg 可能缺少编解码器或版本不兼容。修复：启用 RPMFusion 安装
ffmpeg，或使用 John Van Sickle 静态 FFmpeg 并在 Jellyfin 控制台设置 FFmpeg 路径。
- 硬件加速（Intel Quick Sync）：在部分 **旧版本（如 10.4.3 后）**可能出现硬件加速不可用。修复：安装 i965-va-driver-shaders 等驱动，确保
/dev/dri 设备可访问，并在容器/系统层正确授权。
- 存储与挂载：Jellyfin 主要面向本地文件系统；使用 S3 需通过 s3fs-fuse 挂载为本地目录后再添加媒体库。
- 插件与版本升级：升级后可能出现 插件不兼容、功能变化、依赖冲突。修复：优先更新插件至兼容版本；升级前备份配置与数据，阅读更新说明；必要时回退版本或临时禁用插件定位问题。
- 权限与所有权：以 非 root 运行的 Jellyfin 需要对 配置、缓存、媒体目录具备访问权限。修复：统一目录所有者（如
jellyfin:jellyfin）与权限，或在 Docker 中正确映射卷与用户映射。
- 字体与界面显示：封面/字幕出现方块字多为字体缺失。修复：安装中文字体（如 Noto CJK 等）并在 Jellyfin 控制台配置字体路径或启用备用字体。
- 安全与漏洞：历史版本存在 任意文件读取漏洞（如 CVE-2021-21402）。修复：升级至包含修复的 最新稳定版。
部署与网络配置建议
- 安装方式：优先使用 官方仓库 RPM 或 Docker 部署；RPM 安装可配合
yum localinstall 简化依赖处理。
- 端口放行：确保放行 8096/TCP（HTTP）、8920/TCP（HTTPS），以及 1900/UDP、5353/UDP（发现/MDNS，按需）。命令示例：
firewall-cmd --zone=public --add-port=8096/tcp --permanent && firewall-cmd --reload。
- SELinux：若启用 SELinux，需为 Jellyfin 配置相应策略（如媒体目录访问、端口标签等），避免因策略限制导致无法读取媒体或绑定端口。
快速排查清单
- 服务状态与日志：使用
systemctl status jellyfin 查看状态，执行 journalctl -u jellyfin -xe 或查看 /var/log/jellyfin/ 下日志定位启动/运行报错。
- 依赖与二进制：确认
libicu、fontconfig 已安装；执行 ffmpeg -version 验证可用；必要时在 Jellyfin 控制台设置 FFmpeg 路径。
- 权限与目录：核对媒体目录、配置目录、缓存目录的所有者与权限（常见为 jellyfin:jellyfin，权限 755/644 逐级检查）。
- 硬件加速：执行
ls /dev/dri 检查设备；必要时安装 i965-va-driver-shaders，并在容器启动时映射 /dev/dri 或以特权模式运行（注意安全边界）。
