跳至主内容
非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

故障排除

本文概述了初学者在运行 Jellyfin 服务器时可能遇到的常见问题解决方案。

播放问题​

检查日志是最简单的排查方式，可通过 Web 客户端的控制台或服务器上的日志目录访问。

如果媒体无法转码，请首先检查 ffmpeg 日志。

网络问题​

若可通过 HTTP 访问 Web 界面但无法通过 HTTPS 访问，很可能是证书配置错误。 Jellyfin 使用 PFX 文件处理 HTTPS 流量。 若创建文件时设置了密码，则需在设置页面的网络选项中输入该密码。

若能在本地局域网访问服务器但无法从外部访问，则可能是路由器配置问题。 请检查路由器的端口转发设置，确保服务器可从外部网络访问。

如果完全没有与网络流量相关的日志（即使是局域网连接），说明请求尚未到达服务器。 这通常意味着访问地址错误或网络其他环节存在问题。

调试日志​

调试日志在故障排除时非常有用。由于 Jellyfin 未在前端 UI 提供控制选项，需手动编辑配置文件启用。

日志选项可在 Jellyfin 配置目录 的 logging.json 文件中配置。某些平台还提供 logging.default.json 文件定义默认值，可通过自定义 logging.json 覆盖。

注意

启用调试日志会产生巨量输出：例如仅加载首页就会生成超过 4000 行日志（使用下方配置）。不建议在生产环境长期启用调试日志，仅应在故障排除期间使用。

备注

若在问题排查时被要求提供详细调试日志（超出少量行数），请尽可能压缩日志文件，否则文件体积会非常庞大。

启用调试日志需创建 logging.json 文件并添加以下内容：

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug"
    }
  }
}

若已存在 logging.json 文件，请编辑 Serilog 的 MinimumLevel 部分使其匹配上述配置，但不要修改文件中的其他值。

调试消息在日志中将显示为带 DBG 前缀的行，部分组件在此配置下还会在 INF 级别记录额外信息。

备注

若 logging.json 文件在上次服务器启动前已存在，Jellyfin 会在配置更改后自动重新加载而无需重启。若 logging.json 是上次启动后新建的，则需重启服务器才能使调试日志生效。

要恢复正常日志记录，可移除覆盖文件 logging.json（若之前新建了该文件），或将 logging.json 中 Serilog 的 MinimumLevel 部分恢复为默认值：

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    }
  }
}

实时监控​

此功能允许 Jellyfin 在文件添加或修改时自动更新媒体库。 但该特性仅支持特定文件系统。

在 Linux 系统中，这通过 inotify 实现。 NFS 和 rclone 不支持 inotify，但可通过 mergerfs 等联合文件系统配合网络存储实现支持。

当媒体库规模过大时，可能收到类似错误：

[2019-12-31 09:11:36.652 -05:00]  [ERR] Error in Directory watcher for: "/media/movies"  System.IO.IOException: The configured user limit (8192) on the number of inotify watches has been reached.

如果您运行的是 Debian、RedHat 或其他类似 Linux 发行版，请在终端中执行以下命令：

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.d/40-max-user-watches.conf && sudo sysctl -p

如果您运行的是 ArchLinux，请执行以下命令：

echo fs.inotify.max_user_watches=524288 | sudo tee /etc/sysctl.d/40-max-user-watches.conf && sudo sysctl --system

将其粘贴到终端并按 Enter 运行。对于 Docker 环境，此操作需要在宿主机而非容器内执行。
更多信息请参阅 Guard Listen README 关于增加 inotify 监视器的说明。

在 macOS 上卸载 Jellyfin​

要完全清除 macOS 系统中的 Jellyfin 所有数据，请执行以下命令：

rm -Rfv ~/.config/jellyfin
rm -Rfv ~/.cache/jellyfin
rm -Rfv ~/.local/share/jellyfin

解锁被锁定的用户账户​

当管理员账户被锁定且"忘记密码"功能失效时，需要手动解锁用户。
请先在系统中定位 jellyfin.db 文件。
Linux 系统默认路径为：/var/lib/jellyfin/data/。
其他环境路径请参考服务器路径文档。

Linux 命令行操作​

操作前请确保已安装 sqlite3。
Debian 系系统可通过 apt install sqlite3 安装。
随后执行以下命令/SQL查询：

sqlite3 /PATH/TO/JELLYFIN/DB/jellyfin.db
UPDATE Users SET InvalidLoginAttemptCount = 0 WHERE Username = 'LockedUserName';
UPDATE Permissions SET Value = 0 WHERE Kind = 2 AND UserId IN (SELECT Id FROM Users WHERE Username = 'LockedUserName');
.exit

SQLiteBrowser 图形界面操作​

在具备桌面环境的系统中可使用 SQLiteBrowser。
首先在 SQLite Browser 中打开数据库文件，
进入 Execute SQL 标签页并执行以下查询：

UPDATE Users SET InvalidLoginAttemptCount = 0 WHERE Username = 'LockedUserName';
UPDATE Permissions SET Value = 0 WHERE Kind = 2 AND UserId IN (SELECT Id FROM Users WHERE Username = 'LockedUserName');

修复管理员账户权限​

当管理员账户权限异常时，可通过简单 SQL 查询修复。

注意

手动修改数据库可能导致实例不可修复的损坏。操作前请备份数据库：
cp /PATH/TO/JELLYFIN/DB/jellyfin.db /PATH/TO/JELLYFIN/DB/jellyfin.db.bck

操作前请确保已安装 sqlite3。
Debian 系系统可通过 apt install sqlite3 安装。
随后执行以下命令/SQL查询：
默认路径列表请参考配置目录文档。

sqlite3 /PATH/TO/JELLYFIN/DB/jellyfin.db

查看权限概览​

查看所有用户的当前权限：

SELECT Permissions.Value,Permissions.Kind,Users.Username  FROM Permissions INNER JOIN Users ON Permissions.UserID = Users.Id;

仅检查管理员账户权限（请将 AdminUsername 替换为实际管理员用户名）：

SELECT Value,Kind FROM Permissions WHERE UserId IN (SELECT Id FROM Users WHERE Username = 'AdminUsername');

首行数值 1 或 0 表示权限是否启用。各权限类型说明详见 Jellyfin 源代码中的 PermissionKind 枚举。

修复权限​

备注

并非所有权限都是必需的，后续可通过 Web 界面移除多余权限。

UPDATE Permissions SET Value = 1 WHERE (Kind = 0 OR Kind = 3 OR Kind = 4 OR Kind = 5 OR Kind = 6 OR Kind = 7 OR Kind = 8 OR Kind = 9 OR Kind = 10 OR Kind = 11 OR Kind = 12 OR Kind = 13 OR Kind = 14 OR Kind = 15 OR Kind = 16 OR Kind = 17 OR Kind = 18 OR Kind = 19 OR Kind = 20 OR Kind = 21) AND UserId IN (SELECT Id FROM Users WHERE Username = 'AdminUsername');

.exit

文本渲染异常问题​

若字符字体缺失，文本可能显示为方框 ☐☐☐☐☐☐。安装对应语言字体可解决此问题：

  • 媒体库封面：需在服务器系统安装字体
  • 字幕：字体来源取决于客户端
    具体安装位置请参考字体配置文档。

活动设备未显示问题​

若仪表盘中的活动设备区域未显示任何设备的内容播放进度，可能是因为系统时钟未同步。在基于 systemd 的 Linux 系统中，您可通过运行以下命令启用在线 NTP 服务器同步（该操作将启动并启用 chronyd 或 ntpd 服务）。完成后请务必重启 Jellyfin。

timedatectl set-ntp true

数据库锁定错误​

当遇到扫描失败或数据不一致问题时，请检查日志文件中是否有类似"Database Locked"的错误。若发现此类错误，请先在管理面板检查并行扫描任务限制并降低该值。若当前设置为0，请调整为 CPU 核心数的一半。若仍无效，可尝试更改锁定模式（同时请保持任务限制在合理低值）。

锁定模式有三种可选设置：

  • NoLock - 默认模式，适用于大多数用户

  • Optimistic - 尝试所有写入操作，失败时自动重试

  • Pessimistic - 执行写入操作时始终阻塞所有读取

停止 Jellyfin 服务器并进入其配置目录。目录中有多个 XML 文件，请找到 database.xml 文件并编辑 LockingBehavior 选项：

<?xml version="1.0" encoding="utf-8"?>
<DatabaseConfigurationOptions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <DatabaseType>Jellyfin-SQLite</DatabaseType>
  <LockingBehavior>Optimistic</LockingBehavior>
</DatabaseConfigurationOptions>

完成后重启 Jellyfin 实例。若问题仍未解决，可尝试将 LockingBehavior 设为 Pessimistic（悲观锁），但请注意这会带来显著性能损耗，因此仅建议在 Optimistic（乐观锁）无法解决问题时使用。

LXC 特定问题​

团队已注意到 LXC 容器存在特定问题。若在 LXC 环境中将锁定模式设为 Optimistic 后出现此类错误，建议迁移至完全虚拟化（虚拟机）或 Docker 环境。短期内 LXC 问题不太可能得到解决，对于 LXC 环境中的数据库锁定问题我们将无法提供支持。