Jellyfin 10.11.0

非官方测试版翻译

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

我们很高兴为您带来 Jellyfin 10.11.0——全新的稳定版本。这可能是我们迄今为止规模最大、最具影响力的版本之一（甚至没有之一），包含一系列重大的后端变更，旨在提升性能、长期可扩展性和可维护性。本次发布的筹备历时已久，开发周期超过六个月，又经过六个月的 RC 测试，彻底打乱了我们原定的半年发布计划。但我们坚信这些成果完全值得——无论是对于当前用户的使用体验，还是项目的长期健康发展。

如果您只想快速了解升级系统必须掌握的关键信息（注意：这些内容您务必了解！），请直接阅读下方的"TL; DR"章节；若想全面了解 Jellyfin 10.11.0 的所有重要特性与改进，欢迎继续阅读全文！您也可以在 GitHub 查看完整的服务端和网页端更新日志。

—— Joshua

TL; DR

在升级到 Jellyfin 10.11.0 之前，请务必阅读本节内容！否则可能导致问题！如有疑问或遇到困难，随时欢迎在我们的聊天室寻求帮助。

1. 与所有重大版本升级一样，请务必在升级前停止 Jellyfin 服务并完整手动备份您的数据和配置目录！尽管升级流程理应无缝衔接且设有防护机制，但我们在 RC 测试期间发现了诸多异常问题，有备无患才是明智之选。

2. 升级前必须运行 Jellyfin 10.10.7 版本！虽然 Jellyfin 10.9.11 或许也能正常升级，但该路径未经充分测试。不支持从任何其他版本直接升级，升级必定失败；请先升级至 10.10.7 版本，再升级至 10.11.0。

3. 首次升级将执行多个长时间运行的迁移任务，耗时可能长达数小时（具体取决于资料库大小和状态）。迁移期间切勿取消或中断系统操作；对于超大型资料库，建议通宵运行迁移。您可通过本地网络使用全新的启动界面和日志查看器（详见下文）监控升级进度，具体原因请参阅下文详解。

4. 升级程序会自动备份现有 library.db 文件并命名为 library.db.old。若升级失败，可用此文件恢复。成功升级且 Jellyfin 10.11.0 稳定运行后，可删除此备份。如需因失败重试迁移，请停止 Jellyfin 服务，将此文件重命名为 library.db，然后重启 Jellyfin，迁移将重新执行。

5. 若您曾调整过"资料库分页大小"（默认值为 100），出于性能考虑，建议在升级前恢复默认设置。

6. 升级后强烈建议执行完整资料库扫描，确保所有数据正确载入。未执行此操作可能导致异常问题（虽概率较低，但若元数据条目损坏或迁移异常则可能发生）。此外，音乐资料库用户应额外执行"扫描缺失元数据"操作，这对升级后音乐功能的正常运行可能至关重要。虽然其他类型资料库不一定强制要求，但仍建议执行此扫描以确保功能完备。

7. Jellyfin 10.11.0 不兼容 32 位 ARM 系统（armhf），例如第一代和第二代树莓派或其他低端/老旧单板计算机，以及任何运行 32 位操作系统的 ARM 设备。在 ARM 系统上运行 Jellyfin 10.11.0 必须 使用 ARM64 操作系统。详细信息请参阅下文。

8. 本次发布还修复了多个安全漏洞，包括我们自身的问题以及上游项目（如 .NET）的缺陷。我们强烈建议您尽快升级至 10.11.0 版本。

9. 与所有 Jellyfin 重大版本更新一样，即使经过 6 个月的 RC 测试，仍可能存在缺陷。我们再次提醒您升级前务必进行完整备份——这是发现需要回退至旧版本时的唯一途径。

现在让我们进入激动人心的新功能环节！

媒体库数据库已全面迁移至 EF Core！

有必要先介绍些背景：长期以来，Jellyfin 的后端代码如同"意大利面条"般混乱。在 Jellyfin 诞生前的历史版本中，新增功能开发时很少考虑长期最佳实践。这导致代码库充斥着原始 SQLite 语句的数据库调用，数据库管理功能完全没有集中到 ORM（对象关系映射系统）中。

这带来三大弊端：(1) 任何数据库结构变更都需要复杂易错的手动迁移，每次变更都需要定制方案，缺乏安全措施且不支持回退；(2) 添加新功能或修改现有功能极其困难，往往需要重写大量无关代码；(3) 系统被完全限制在基于文件的 SQLite 方案中，无法支持其他数据库引擎。

EF Core 作为 .NET/C#（Jellyfin 的开发框架/语言）的 ORM 工具应运而生。它简化了数据库管理流程，让我们能彻底清除遗留的混乱代码，大幅优化 Jellyfin 的数据库处理机制。其特性包括：带版本控制的自动迁移处理器、标准化的数据库调用接口，以及未来支持其他后端数据库引擎的灵活性。

这项迁移工作始于近五年前，最初转换了用户认证等简单数据库。但媒体库数据库这头"大象"因其极端复杂性、广泛关联性及对静态 XML 文件的依赖，导致项目停滞数年。直到 @JPVenson 加入项目不到六个月便接手这项艰巨任务，并最终推动完成。

对普通用户而言，这项变革可能看似平淡：查询确实更快了，未来更新也会更稳定，但多数变化是隐形的。然而对 Jellyfin 的后端架构和长期发展而言，这具有里程碑意义。简化的数据库访问将让我们编写更简洁可靠的代码，更快实现新功能，执行复杂迁移，以最小成本开启更多可能性。我们终于能着手处理堆积如山的特性需求——其中许多在此次变革前几乎无法实现。对管理员而言，未来还将解锁新潜力（虽尚未正式支持）：使用 PostgreSQL 等"专业"数据库系统运行 Jellyfin，实现冗余备份、负载均衡及更便捷的运维管理。前景一片光明！

数据去重与迁移机制

迁移的核心是将所有媒体库数据从旧版 library.db 转移到新版 jellyfin.db 结构中。表面简单的过程实则暗藏玄机：我们借转换之机主动优化了数据结构，同步清理了大量前述的混乱代码。因此本次迁移首次在数据库中建立了规范的关系型交叉引用，包括外键约束。

然而弊端在于，逻辑混乱且损坏的媒体库数据在迁移过程中极易引发问题，这也正是诸多故障的根源。此次迁移不仅要重构数据结构，还需修复逻辑损坏并清理所有"不再合理"的数据，例如缺少上级关联的媒体条目，或重复出现于多组媒体中的人物数据。

这种去重与清理工作极其耗时，其规模很大程度上取决于现有数据库中逻辑不一致条目的数量。这意味着：数据库历史越久远、逻辑损坏条目越多，迁移过程就需要耗费更多时间进行清理。这也导致迁移时长难以预估——30万条无异常记录的数据库可能几分钟完成迁移，而仅有30个剧集但存在严重不一致的库却可能耗时数小时。

因此我们再次强调：请在非高峰时段（如夜间）执行迁移并确保其完整运行。若迁移快速完成自然理想，若耗时较长也能避免影响用户访问。

启动界面与日志查看器

迁移工作催生了一项实用新功能：启动界面与日志查看器。此前当Jellyfin执行启动或迁移任务时，系统会呈现假死状态——界面无法加载，除非开启调试日志级别，否则用户难以感知进度。启动界面彻底改变了这种情况：它通过专属WebUI（仅限配置的本地网络访问）实时显示系统准备状态和日志信息。对于小型实例可能转瞬即逝，但对启动缓慢的大型实例而言，这将成为追踪进度和调试问题的无价工具。

内置备份与恢复支持

新架构的首个重大福利便是万众期待的功能：实时元数据备份与恢复！您现在可以创建完整数据库快照，将其备份至外部存储，并在重大故障时进行恢复。定期备份功能也将大幅简化日常维护及未来升级流程，确保您始终拥有完好的数据副本。

需注意：备份恢复系统仅支持在原运行环境还原，不可用于跨操作系统或第三方容器迁移。

激进的内存数据库缓存

新版数据库引擎采用激进内存缓存策略，通过将元数据预载至内存避免磁盘读取瓶颈——这正是旧版Jellyfin的常见性能痛点。实际应用中，Jellyfin内存占用量将显著增加（最高可达整个媒体库数据库大小），但这绝非资源浪费：您将获得肉眼可见的速度提升（尤其对大型媒体库），且系统会在其他任务需要内存时主动释放资源。升级时请注意此变化带来的资源利用率提升。

改进的锁定机制

新数据库引擎支持多种锁定模式。多数用户无需关注此功能，但频繁遭遇数据库锁定问题的用户现可调整相关设置。详细说明请参阅此技术博客。

移除ARM32 (armhf)架构支持

在 Jellyfin 10.10.0 中，我们已弃用 ARM32 支持，并在 Jellyfin 10.11.0 中完全移除了该功能；Jellyfin 现在要求在 ARM 平台上运行 ARM64 操作系统。实际上，这意味着放弃对非常老旧或低端 ARM 单板计算机（如 Raspberry Pi 1/2 等）的支持。我们发现这些老旧单板计算机即使在不转码的情况下运行 Jellyfin 也表现极差，因此我们决定放弃支持以简化发布流程，并帮助用户获得开箱即用的最佳体验。如果您仍在使用此类系统，或使用未运行 64 位操作系统的新型 ARM 单板计算机，则需要升级硬件和/或重新安装 64 位操作系统才能升级至 Jellyfin 10.11.0。

弃用内置 TLS/SSL 支持

我们宣布弃用 Jellyfin 中的内置 TLS/SSL 支持功能，并计划在 Jellyfin 10.12.0 中彻底移除。当前的内置 TLS 机制非常繁琐，且与外部系统（如 Let's Encrypt 的 certbot）集成不佳，导致每次证书更新都需要手动操作和重启。此外，编译 TLS 支持会依赖外部库，使我们的 Linux 打包二进制文件复杂化。我们始终推荐通过反向代理运行 Jellyfin，这些解决方案能提供更完善的 TLS/SSL 集成，因此在下一个版本中我们将移除此功能。对于未使用反向代理但通过 TLS 运行生产级互联网服务的用户，请立即部署反向代理。即使移除该功能，我们仍会保留内置 Kestrel TLS 系统的手动配置选项，但这仅作为高级特殊场景的备选方案（不会在前端界面提供），常规实例应迁移至反向代理。

磁盘空间检查

Jellyfin 现在会主动检查配置目录和数据目录的可用空间。如果任一数据目录的可用空间不足 2GB，系统将拒绝启动以防止数据损坏。同时新增了路径配置错误预防机制，避免已知问题发生。

新功能与增强

本次更新带来多项值得期待的新功能和改进：

用户体验

• 搜索性能大幅提升，让您更快找到所需内容。

• "收藏"页面现支持直播电视频道、音乐视频、相册、照片和季集等新增媒体类型。

• 新增 Firefox 134+ 的 HEVC 解码支持，详情参见客户端支持页面。

• 可禁用字幕的默认样式。

• 浏览媒体库时，剧集可按合集分组展示。

• 主题媒体现在支持随机播放。

• 可为客串明星分配角色（如 Kelsey Grammer 饰演 Morgan Bateson 船长）。

• 登录页面背景支持自定义"启动画面"图片。

• 实验性布局重新设计了导航栏，优化了媒体库筛选与排序控件。

管理员体验

• 控制台仪表板新增服务器媒体项目数量统计和存储空间监控。

• 媒体分段提供程序现可像其他元数据提供程序那样按媒体库单独配置。

• 支持为 VideoToolbox 硬件加速启用 AV1 解码。

• M3U 调谐器可配置为使用原生帧率。

• 品牌定制功能大幅扩展：新增启动画面支持、增强免责声明功能、自定义 CSS；未来还将推出更多特性，让管理员能根据品牌需求完全定制用户体验。

• 仪表盘页面迁移至新技术栈的工作已接近完成，绝大多数页面完成转换后提供了更简洁清晰的组织布局。

• 替换文件时，Jellyfin 现在能够识别该操作并在扫描期间清理相关数据（章节、trickplay 文件及提取的字幕和附件），确保这些数据会重新生成以匹配新文件。

转码与媒体处理

• 我们已升级至上游 FFmpeg 7.1 版本，带来诸多改进。

• 现支持在 Intel HD/UHD 显卡和 Rockchip RK3588 上实现基于 3D LUT 的 HDR 色调映射，显著提升性能。

• 现支持在 Rockchip RK3588 上实现杜比视界 Profile 5 的色调映射。

• 使用硬件转码时，ASS/SSA 字幕的渲染精度显著提升。

• 现支持通过 Apple VideoToolbox 实现 AV1 硬件解码。

• 改进了动态 HDR 元数据处理机制，包括准确识别 HDR10+ 视频，并选择性移除杜比视界（DoVi）或 HDR10+ 元数据，避免仅支持单一动态 HDR 元数据的设备出现黑屏问题。

客户端开发变更

以下变更适用于所有客户端应用开发者。请仔细阅读并根据需要更新您的应用程序。

HTTP API

• 新增开发者选项用于在禁用弃用授权方法的情况下测试客户端。我们计划在 10.12.0 版本中移除旧版授权方法。授权与测试的详细说明请参阅此文档。

• OnPlaybackStart、OnPlaybackProgress 和 OnPlaybackStopped 操作现已弃用。请改用 ReportPlaybackStart、ReportPlaybackProgress 和 ReportPlaybackStopped 操作，旧版操作将在未来版本中移除。

• 新增 GetSystemStorage 操作用于获取服务器存储信息。

• 新增 BackupApi 用于备份的列出、创建和恢复操作。

• 歌词现支持逐词时间轴标记功能。

• 家长分级评分已迁移至支持子分数的新属性 ratingScore。

• 服务器在启动/关闭/重启期间可能返回 503 Service Unavailable 状态码。客户端应预判此状态码，根据 Retry-After: sec 响应头采取行动，并按需重试操作。

插件

• 所有数据库访问必须通过 EF Core 实现。服务器将不再接受原始 SQL 语句。

• 插件现可提供自定义数据库访问功能。此 API 高度实验性，可能随时变更，目标在 10.12.0 版本中实现稳定。

• 元数据插件应使用新版外部 URL 提供者接口，以便为外部元数据链接提供更规范的命名。

观影愉快！