Jellyseerr与Jellyfin全库扫描故障排查指南

问题现象分析

当用户在Jellyseerr中执行Jellyfin全库扫描时，系统可能返回401未授权错误，具体表现为：

1. 完整库扫描失败，提示"Request failed with status code 401"
2. 手动触发扫描无响应
3. 仅"最近添加"扫描功能正常
4. 媒体库中部分内容缺失"在Jellyfin播放"按钮

核心故障原因

经过技术分析，该问题主要涉及以下两种典型场景：

1. 认证令牌失效

当使用LDAP/外部认证系统（如Authentik）时，Jellyfin的访问令牌可能过期。Jellyseerr在执行全库扫描时需要持久的有效令牌，而近期添加扫描由于数据量较小，可能在令牌有效期内完成。

2. 权限配置问题

用户账户可能缺少对某些媒体库的访问权限。特别是：

• 隐藏了首个媒体库（即使后续库可访问）
• 权限继承设置异常
• 媒体库可见性配置冲突

解决方案

令牌刷新方案

1. 完全退出Jellyseerr当前会话
2. 清除浏览器缓存或使用隐私模式重新登录
3. 确保认证提供商（如Authentik）的会话有效期设置合理

权限检查方案

1. 登录Jellyfin管理后台
2. 检查用户权限分配：
   • 确认所有需要同步的媒体库均已授权
   • 特别注意首个媒体库的权限状态
3. 临时取消所有媒体库隐藏设置进行测试

技术建议

1. 对于使用外部认证的系统，建议：
   • 设置合理的令牌刷新间隔
   • 在Jellyseerr配置中使用服务账户而非个人账户
2. 定期检查媒体库权限继承关系
3. 复杂权限体系下，建议创建专用的Jellyseerr同步账户

后续维护

建议用户定期检查：

• Jellyfin与Jellyseerr的日志同步情况
• 媒体库完整度指标
• 权限变更后的自动扫描结果

通过以上系统化的排查和维护，可有效保障Jellyseerr与Jellyfin的媒体库同步稳定性。