Jellyfin 在 CentOS 上的故障排查方法
一 快速定位与通用排查
- 确认服务状态与最近日志：使用命令查看是否运行、是否崩溃重启以及最近报错。
- 命令示例：systemctl status jellyfin；journalctl -u jellyfin -b；journalctl -xeu jellyfin
- 实时跟踪日志：对文件日志与 systemd 日志分别跟踪，便于捕捉瞬时错误。
- 命令示例：tail -f /var/log/jellyfin/*.log；journalctl -fu jellyfin
- 检查端口监听与连通性：确认 8096/8920 等端口处于监听，外部可达。
- 命令示例：ss -ltnp | grep -E ‘8096|8920’；curl -I http://127.0.0.1:8096；从外网测试或本机防火墙放行后测试
- 资源与依赖检查：排查 CPU/内存/磁盘 是否紧张；确认 FFmpeg 可用（转码必需）；必要时查看进程是否存在与占用。
- 命令示例：top/htop；df -h；which ffmpeg；ps aux | grep jellyfin
- 配置与权限核对：核对关键配置（如端口、路径、缓存、网络）与目录权限；Jellyfin 配置通常位于 /etc/jellyfin/，日志默认在 /var/log/jellyfin/。
- 服务启动失败通用思路：若 journal 提示 Failed with result ‘exit-code’，优先检查 unit 文件 ExecStart、脚本/二进制权限、端口冲突、环境变量、运行用户与资源限制等。
二 常见症状与对应处理
- 页面打不开或端口不通
- 检查监听与连通：ss -ltnp | grep -E ‘8096|8920’；从外网测试；临时关闭防火墙验证（firewalld/iptables）；云主机需放行安全组 8096/8920。
- 查看访问日志与 systemd 日志定位握手/权限/崩溃原因。
- 启动失败或反复重启
- 用 journalctl -xeu jellyfin 查看退出码与堆栈；核对 unit 文件 ExecStart、工作目录、运行用户；检查配置文件语法与路径；排查端口占用与资源限制。
- 转码失败或 CPU 占用高
- 确认 FFmpeg 已安装并在 Jellyfin 控制台设置 FFmpeg 路径（如：/usr/bin/ffmpeg）；必要时替换为静态编译版本或系统仓库版本。
- 硬件加速不可用（QSV/VA-API）
- 宿主机加载 i915 驱动并验证 /dev/dri 可用；Docker 需映射设备 --device=/dev/dri:/dev/dri 且使用包含驱动的镜像或自行安装 media-driver；注意部分 QSV 驱动与容器镜像的许可兼容性差异。
- 中文封面/方块字
- 安装 CJK 字体（如 Noto CJK）；重启 Jellyfin；在控制台计划任务中触发媒体库重新扫描以重新生成封面。
三 Docker 部署的专项排查
- 查看容器日志与实时输出：docker logs -f <容器名>；确认是否因权限、设备、路径映射或驱动缺失导致异常。
- 核对端口与目录映射：确保 -p 8096:8096 -p 8920:8920 与媒体/配置/缓存卷挂载正确；验证宿主机目录权限对容器内用户可读写。
- 硬件加速与设备直通：添加 --device=/dev/dri:/dev/dri；必要时设置 PUID/PGID 与权限；若使用官方镜像，确认已按宿主机环境准备 iHD 驱动或改用集成驱动的社区镜像。
- 字体与国际化：容器内安装 fonts-noto-cjk-extra 等字体包并重启，解决封面/界面中文方块字。
四 监控与进一步诊断
- 进程与资源监控：ps aux | grep jellyfin；top -p ；结合 systemctl status 与 journalctl 观察趋势与异常时段。
- API 健康检查：curl http://:8096/api/server/status 获取运行状态与基础指标，便于对接 Prometheus/Grafana 或 Nagios/Zabbix 做持续监控与告警。
