不稳定版用户注意：EFCore重构即将来临

非官方测试版翻译

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

不稳定版用户请注意：我们计划在未来几周内合并针对library.db的EFCore转换方案。所有不稳定版用户必须了解当前进展、实施计划以及如何缓解可能产生的问题。 稳定版（10.y.z）用户无需任何操作。

当前不稳定版构建已在10.10.0发布后暂停约4周，在此期间我们将合并这些重大的数据库变更。过程中必然会出现故障——包括程序错误、修复方案和数据库迁移。特此郑重提醒您：(a) 通过完善的备份恢复策略做好准备并禁用自动更新；或(b) 暂时切换到10.10.0稳定版直至过渡完成（但我们恳请您不要切换，因为测试阶段需要您的协助！）

若需了解详情，请继续阅读。

—— Joshua

什么是EFCore？为何要迁移至此框架？

EFCore是C#/.NET平台的数据库处理框架，可简化Jellyfin代码库中的数据库查询操作。

我们的原始数据库代码由Emby在.NET Core尚未诞生的年代编写，当时Mono主导着跨平台C#兼容性。该实现存在严重缺陷：SQLite查询语句直接硬编码在源码中，数据库架构设计欠佳且缺乏迁移能力。多年来，当我们尝试改进代码库、增加新功能时，这些问题持续困扰着我们，因此团队早在数年前就启动了向EFCore的迁移工作。

在@BarronPM的辛勤工作下，我们快速迁移了多个数据库模块，这些模块已在多个主要版本中稳定运行。但媒体库数据库因其极端复杂的结构和糟糕的设计方案始终维持原状，这导致了一系列问题：例如搜索效率低下、新增媒体类型困难（或淘汰旧类型）、处理"非标准"媒体类型（即电影/电视剧/音乐专辑之外的格式）时产生的代码复杂性及程序错误。

如今，得益于@JPVenson的贡献，媒体库数据库的EFCore实现终于准备就绪。但这里存在一个重要限制。

程序错误不可避免

合并这项重大变更后，程序错误必然会出现。这些错误可能彻底损坏您的媒体库数据库。因此最首要的是，所有运行不稳定版本的用户必须清楚认识到即将发生的变更，并做好充分准备。

我们的工作重点

我们的核心目标是确保10.10.x到10.11.x稳定版之间的迁移过程平稳无碍。当10.11.0发布时，我们需要为大多数稳定版用户提供无缝升级体验。

为此，我们必须在不稳定版环境中测试变更方案，并验证迁移流程对10.10.x稳定版数据的兼容性。

但由此带来的局限是：我们可能无法完美实现不稳定版到不稳定版的迁移方案。虽然会尽力尝试，但无法对此作出保证。

实施时间表

1. 这篇博文旨在向所有使用不稳定版本的用户发出预警：本次变更即将到来。请注意，在本文发布时，由于近期发布了 10.10.0 版本，不稳定版本构建已被禁用，并将暂时保持禁用状态。

2. 在本文发布约 1-2 周后，我们将把 Library 的 EFCore 迁移合并到 master 分支，并开始初步测试。若您想参与协助，必须从源代码构建 Jellyfin，参与测试的人越多越好！

3. 合并后约 2 周，若整体进展顺利，我们将重新向公众开放不稳定版本构建。此时所有不稳定版本构建将在启动时执行初始迁移操作。这将使我们从 10.10.0 发布起大约经过 4 周（误差一周左右）的时间。

4. 在后续几周内，我们将收集错误报告并尝试修复。这里可能出现难点：若我们无法实现完整的迁移方案，可能会优先保证稳定版到不稳定版的迁移路径，而非不稳定版本间的迁移。若发生这种情况，您可能需要还原旧版本再应用新迁移。

这对您实际意味着什么

首先，若您认为风险过高，现在就是退出时机。请在我们几周后恢复不稳定版本构建前立即切换到其他版本。

其次，务必采用基于我们建议的备份流程的可靠备份策略。定期备份数据，并建议保留最近稳定版的备份用于迁移测试。每次应用新不稳定版本构建前必须备份。

第三，确保禁用自动升级功能。我们通常建议禁用此功能，若您仍在使用，请立即停用。

第四，若遇到问题，请在错误报告标题注明 [EFCore Library]。这将帮助我们快速定位问题。

第五点也是最后一点，若迁移失败，请先还原旧版数据库再重试迁移。若仍失败，请尝试使用最早期的备份（建议 10.9.11 或 10.10.0 稳定版）。若_该版本_仍无法迁移，请提交新的错误报告。