CentOS 环境下 Jellyfin 故障排查手册
一 快速定位流程
- 检查服务状态：运行 systemctl status jellyfin，若未运行，执行 systemctl start jellyfin 并观察状态输出中的错误提示。
- 查看实时日志：使用 journalctl -u jellyfin -f 跟踪服务日志；同时查看 /var/log/jellyfin/jellyfin.log 获取应用层详细报错。
- 确认端口监听：默认端口为 8096，执行 ss -tulnp | grep 8096 或 netstat -tulnp | grep 8096 检查是否在监听。
- 网络连通性：从本机与客户端分别测试访问 http://服务器IP:8096，并用 ping/nslookup 排查 DNS 与连通性问题。
- 资源与依赖：用 top/htop 检查 CPU/内存/磁盘；确认已安装转码依赖 FFmpeg 及基础依赖 libicu、fontconfig。
- 媒体库路径：核对媒体库在系统中的真实路径与权限，确保 Jellyfin 运行账号可读写。
二 常见症状与处理要点
- 无法访问 Web 界面：
- 服务未起：journalctl 查看失败原因；2) 端口未监听：ss/netstat 确认 8096；3) 防火墙/云安全组未放行 TCP 8096；4) SELinux 拦截，临时 setenforce 0 验证，长期为 Jellyfin 配置正确的 SELinux 策略。
- 启动失败：
- 查看 /var/log/jellyfin/jellyfin.log 与 journalctl -u jellyfin 的错误栈；2) 检查配置文件 /etc/jellyfin/ 下如 config.xml 或 system.xml 的语法与关键项（端口、路径、编码等）；3) 缺失依赖时安装 libicu、fontconfig、FFmpeg；4) 仍异常可备份后尝试重装。
- 播放报错或转码失败：
- 确认 FFmpeg 已安装且在 PATH 中；2) 在控制台检查转码器与硬件加速设置；3) 客户端不兼容时，尝试切换播放器或开启兼容模式。
- 媒体库不显示或权限错误：
- 核对媒体库路径在系统中的真实存在与挂载状态；2) 确保运行账号对目录具备 读/执行 权限（必要时用 chmod/chown 修正）；3) 若使用 NFS/SMB，确认挂载选项未限制访问。
- 中文封面/字幕乱码：
安装中文字体（如 fonts-noto-cjk-extra），重启 Jellyfin 后清理并重建封面缓存。
三 关键命令清单
| 目标 |
命令示例 |
| 服务状态 |
systemctl status jellyfin |
| 启动/开机自启 |
systemctl start jellyfin；systemctl enable jellyfin |
| 实时日志 |
journalctl -u jellyfin -f |
| 应用日志 |
tail -f /var/log/jellyfin/jellyfin.log |
| 端口监听 |
ss -tulnp |
| 资源监控 |
top；htop |
| 依赖安装 |
yum install -y epel-release；yum install -y ffmpeg；yum install -y libicu fontconfig |
| SELinux 临时放行 |
setenforce 0（验证用，生产请改为策略放行） |
| 防火墙放行 |
firewall-cmd --add-port=8096/tcp --permanent && firewall-cmd --reload |
四 日志与监控
- 日志位置与检索：Jellyfin 日志位于 /var/log/jellyfin/，结合 journalctl -u jellyfin 与 grep/awk 做关键字定位，例如：journalctl -u jellyfin | grep “ERROR”。
- 日志轮转与集中：使用 logrotate 管理 /var/log/jellyfin/*.log，可接入 rsyslog/syslog-ng 或 ELK 做集中化分析与可视化。
五 环境与依赖自检
- 转码器与基础库：确保 FFmpeg 可用（RHEL/CentOS 可通过 EPEL 与 RPM Fusion 安装），并安装 libicu、fontconfig 等基础依赖，避免因编解码或字体缺失导致异常。
- SELinux 与防火墙：若启用 SELinux，需为 Jellyfin 配置合适的策略或临时设为宽容模式验证问题；同时放行 TCP 8096 端口并验证云厂商安全组规则。
