跳至主内容

升级与降级

非官方测试版翻译

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

本文详细说明如何在稳定版(Stable)和不稳定版(Unstable)之间进行升级/降级操作，以及您可能需要这样做的原因。

稳定版 vs 不稳定版​

选择哪种安装类型取决于您的需求：不稳定版用于测试新功能，而稳定版则用于为他人提供可靠的服务。

  • 稳定版提供最一致且可预测的用户体验。特定主版本（例如 10.8.z、10.9.z）不会引入、移除或更改主要功能（安全相关的微小调整除外）。错误修复通过点版本发布，在主版本生命周期内根据需要响应错误修复和安全公告。大多数用户应使用稳定版，这将确保最终用户获得最佳运行时间和一致性。

  • 不稳定版提供最新前沿功能，但可能存在快速且不可预测的重大变更或严重错误，且随着 API 持续变更，客户端支持更有限。不稳定版通过每周一 UTC 时间凌晨 5:00 左右的二进制构建发布，或可通过从 master 代码分支自行构建软件包。

此外，由于我们不提供测试版(beta)，不稳定版用于在主版本周期中测试即将发布的版本。如果您希望协助我们测试新版本——我们恳请有能力者参与——您需要运行不稳定版一段时间，并在正式发布时切换回稳定版。

何为"不提供测试版"​

由于为多个独特平台打包 Jellyfin 的复杂性极高（更不用说第三方构建还支持更多平台），从 10.9.0 版本开始，我们决定不再提供明确标记的预发布版本。这对自由开源软件虽不常见，但却是简化主版本发布流程并提高发布频率的实际需要。

作为补偿，我们在主版本发布前设置重大变更的功能冻结窗口，并将定期周更的不稳定版作为替代方案。每个主版本发布前，我们会公布即将发布的不稳定版时间表，并将其映射到假设的"测试版"和"候选版"。例如在四周冻结期内，前三周的不稳定版可视为"测试版"，最后一周视为"候选版"。若想早期测试，可在前三周尝试；若想等待功能稳定，则最后一周再测试。

此方案虽不完美，但显著简化了版本管理，避免引入第三个仓库组件/标签，让不稳定版在发布周期获得更多关注，同时相比显式预发布版本几乎不增加管理开销。

警告与注意事项​

备份至关重要​

通常，从某个稳定版升级到不稳定版后，无法直接降级回原稳定版。这是因为不稳定版可能已修改数据库结构、配置项等元数据，而旧版稳定版无法处理这些变更。

从不稳定版降级到旧稳定版的唯一方法是恢复备份，或完全清除数据重新开始。例外情况是：当稳定版主版本发布时，可从对应版本的不稳定版迁移到该稳定版。

无论何种原因升级到不稳定版前，请务必备份实例数据和配置目录。 您永远不知道会发生什么：可能是迁移失败、导致必须降级的严重错误，或是其他数据损坏。即使临近稳定版发布前的测试也适用此原则。准备好备份→升级后立即测试→发现问题及时回滚（当然请先提交错误报告），这才是万全之策！

您可以使用某些插件来辅助此操作，例如通过 Trakt 插件同步观看记录，但这不一定能保留所有数据。请务必谨慎操作，并在继续前了解其局限性。

更多细节请遵循文档中列出的流程。

在非稳定版中禁用自动更新​

在非稳定版运行期间开启自动更新，或在非稳定版预发布测试阶段使用自动更新可能导致问题。请始终手动执行更新并在完成后进行测试。我们通常不建议在稳定版中使用自动更新（因为可能错过新版发布说明），但理解这种功能的便利性；不过在使用非稳定版时请务必抵制这种诱惑，以免遗漏重要变更。

从稳定版升级至非稳定版​

具体操作细节取决于您的平台和安装方式。本文将详细说明两种最常用的方法：通过我们的仓库安装的 Debian/Ubuntu 软件包，以及 Docker。其他方式（例如手动下载、Windows 安装程序等）的操作流程基本相似，只需调整具体细节；关于各平台的详细说明，请参阅 测试 Jellyfin 服务器 下的子文档。

本文假设您当前运行的是 Jellyfin 稳定版。

插件处理（稳定版→非稳定版）​

我们为稳定版和非稳定版提供独立的插件仓库与版本体系。这种设计可避免意外兼容性问题，同时允许我们根据 master 分支的持续变更快速迭代非稳定版插件。若您使用插件，需切换至非稳定版插件仓库。如果在升级前完成此操作，插件将在升级后自动更新。

插件版本设计确保无缝升级路径：最新 Stable 插件 → Unstable 插件 → 下一版 Stable 插件（例如 13.0.0.0 Stable → 13.2024.0429.0 Unstable → 14.0.0.0 Stable）。

  1. 在 Jellyfin 服务实例中，进入 仪表盘 → 插件 → 仓库管理

  2. 点击垃圾桶图标删除默认的 "Stable" 仓库。

  3. 点击 "+" 按钮添加新仓库。自定义仓库名称，并使用以下仓库 URL：

    https://repo.jellyfin.org/files/plugin-unstable/manifest.json

Debian/Ubuntu 仓库升级（稳定版→非稳定版）​

  1. 编辑 /etc/apt/sources.list.d/jellyfin.sources 文件，在 Components: 行添加 unstable。切勿删除 main，只需在其后添加 unstable：

    ...
    Components: main unstable
    ...

  2. 执行 sudo apt-get update

  3. 运行 sudo apt-get upgrade 应用更新的 Jellyfin 软件包。Jellyfin 将自动重启。

  4. Jellyfin 启动后，若您已提前更新插件仓库，插件将自动升级至新版非稳定版。等待服务完全启动后，再次重启服务（可通过控制台的"重启"按钮或 systemctl 命令），以完成升级流程。

Docker 升级（稳定版→非稳定版）​

  1. 停止您的 Jellyfin 容器。

  2. 拉取 jellyfin/jellyfin:unstable 镜像标签。

  3. 使用新镜像启动 Jellyfin 容器

发布时从非稳定版升级至稳定版​

当新版 Jellyfin 主版本发布后，在下一版 Unstable 构建发布前的窗口期内，您可以直接从 Unstable 升级至该新 Stable 版本。这为参与 Unstable 测试的用户提供了在正式发布前迁移到 Stable 版本的途径。

作为发布流程的一部分，Unstable 每周构建会暂停 1-2 周，专门留出升级窗口期。之后 Unstable 构建将恢复正常。若您希望继续使用 Unstable 版本，只需等待窗口期结束；否则请按以下流程"降级"到新 Stable 版本。

具体操作步骤因平台和安装方式而异。本文将详述两种最常用场景：通过官方仓库安装的 Debian/Ubuntu 包，以及 Docker 容器。其他方式（如手动下载、Windows 安装包等）流程基本类似，仅细节调整；各平台具体操作请参见"测试 Jellyfin 服务端"子文档。

我们假设您当前正在运行 Jellyfin 不稳定版（Unstable）。

插件处理（Unstable 转 Release）​

Stable 和 Unstable 版本的插件分别存放在独立仓库中，采用不同的版本控制机制。如果您使用插件，需要切换回 Stable 插件仓库，避免在 Stable 安装中混入不兼容的 Unstable 插件。注意：新版本发布后，插件可能需要数小时至数天才能完成适配；若插件已准备就绪，按此步骤操作后切换至 Stable 时会自动升级。

插件版本设计确保无缝升级路径：最新 Stable 插件 → Unstable 插件 → 下一版 Stable 插件（例如 13.0.0.0 Stable → 13.2024.0429.0 Unstable → 14.0.0.0 Stable）。

  1. 在 Jellyfin 服务实例中，进入 仪表盘 → 插件 → 仓库管理

  2. 点击垃圾桶图标删除 "Unstable" 仓库

  3. 点击"+"按钮添加新仓库。自定义仓库名称（默认"Stable"），仓库 URL 填写如下：

    https://repo.jellyfin.org/files/plugin/manifest.json

Debian/Ubuntu 系统（Unstable 转 Release）​

  1. 编辑 /etc/apt/sources.list.d/jellyfin.sources 文件，从 Components: 行移除 unstable

    ...
    Components: main
    ...

  2. 执行 sudo apt-get update

  3. 执行 sudo apt install jellyfin=<version> jellyfin-server=<version> jellyfin-web=<version> 将 <version> 替换为目标版本（如 10.9.1+ubu2204），这将覆盖安装 Stable 版本。Jellyfin 将自动重启。

    示例：sudo apt install jellyfin=10.9.1+ubu2204 jellyfin-server=10.9.1+ubu2204 jellyfin-web=10.9.1+ubu2204

Docker 容器（Unstable 转 Release）​

  1. 停止您的 Jellyfin 容器。

  2. 拉取 jellyfin/jellyfin:latest 镜像标签

  3. 使用新镜像启动 Jellyfin 容器

后续操作（Unstable 转 Release）​

  1. 适配新版本的插件上线后，Jellyfin 会按前述机制自动升级插件至稳定版。若发现未自动升级的插件，请尝试手动更新。

从 Unstable 降级至旧版 Stable​

如前所述，此操作需使用首次升级 Unstable 前创建的备份进行恢复。

具体操作细节取决于您的平台和安装方式。本文将详细说明两种最常用的方法：通过我们的仓库安装的 Debian/Ubuntu 软件包，以及 Docker。其他方式（例如手动下载、Windows 安装程序等）的操作流程基本相似，只需调整具体细节；关于各平台的详细说明，请参阅 测试 Jellyfin 服务器 下的子文档。

我们假设您当前正在运行 Jellyfin 不稳定版（Unstable）。

Debian/Ubuntu（从 Unstable 降级到旧版 Stable）​

  1. 使用服务管理器停止 Jellyfin（例如 sudo service jellyfin stop）。确保 Jellyfin 已完全停止运行。

  2. 恢复您备份的配置和数据目录。请务必先完全移除当前内容（或将其移出目录）。

  3. 编辑 /etc/apt/sources.list.d/jellyfin.sources 文件，从 Components: 行中移除 unstable：

    ...
    Components: main
    ...

  4. 运行 sudo apt-get update。

  5. 运行 sudo apt-get install --reinstall jellyfin jellyfin-server jellyfin-web。这将强制重新安装新的 Stable 版本覆盖现有 Unstable 版本。Jellyfin 应会自动启动；若未启动，请使用服务管理器手动启动（例如 sudo service jellyfin start）。

Docker（从 Unstable 降级到旧版 Stable）​

  1. 停止您的 Jellyfin 容器。

  2. 恢复您备份的配置和数据目录。请务必先完全移除当前内容（或将其移出目录）。

  3. 拉取 jellyfin/jellyfin:latest 镜像标签。

  4. 使用更新后的镜像启动新的 Jellyfin 容器。

安装后步骤（从 Unstable 降级到旧版 Stable）​

  1. 您的备份应已恢复原始插件仓库和插件版本。若未恢复，您可能需要移除所有 Unstable 插件并重新安装；相关配置信息将保留。