Jellyseerr与Jellyfin用户名同步机制解析

背景说明

在Jellyseerr媒体请求系统中，当用户通过Jellyfin认证登录时，存在用户名显示不一致的情况。核心问题在于Jellyfin修改用户名后，Jellyseerr界面显示未能自动同步更新。这涉及到两个系统间的用户信息同步机制。

技术原理

Jellyseerr的用户体系采用双重标识设计：

1. Jellyfin用户名：来自Jellyfin系统的原始用户名
2. 本地账户标识：包括显示名称(displayName)和电子邮件字段

当用户首次通过Jellyfin登录时，系统会执行以下操作：

• 将Jellyfin用户名同时写入本地账户的电子邮件字段（因Jellyfin无邮箱系统）
• 显示名称字段初始为空，界面展示时会优先使用Jellyfin用户名

同步机制详解

1. 自动更新条件：

   • 必须通过Jellyfin原生登录表单重新认证
   • 系统会比对Jellyfin API返回的最新用户名
   • 仅更新Jellyfin用户名字段，不影响本地账户的电子邮件标识

2. 显示优先级规则：

   • 存在displayName时优先显示
   • 无displayName时显示Jellyfin用户名
   • 括号内始终显示电子邮件标识（初始同步自Jellyfin用户名）

典型问题解决方案

1. 显示名不同步：

   • 退出当前会话
   • 使用Jellyfin登录表单重新认证
   • 系统将自动获取最新Jellyfin用户名

2. 括号内标识更新：

   • 进入用户编辑界面
   • 手动更新电子邮件字段
   • 或保持空白直接保存触发同步

最佳实践建议

1. 对于Jellyfin用户：

   • 建议统一使用Jellyfin认证登录
   • 重要修改后需重新登录触发同步

2. 对于管理员：

   • 修改用户名后应通知用户重新登录
   • 可通过编辑界面强制刷新用户数据
   • 保留原始请求记录无需重建账户

架构设计思考

这种设计实现了：

• 保持Jellyfin作为主认证源的权威性
• 本地账户系统的独立性
• 请求历史的持久化存储
• 灵活的用户标识展示策略

理解这一机制有助于管理员更好地管理跨系统用户身份，也为后续可能的定制开发提供了理论基础。