跳至主内容
非官方测试版翻译

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

备份与恢复

本指南将介绍如何备份和恢复 Jellyfin 实例中的数据。

为何备份至关重要​

备份对所有数字数据都极为重要。升级主版本时（例如从 Jellyfin 10.9.x 升级到 10.10.x），可能出现各种导致数据丢失的故障和问题。

此外，Jellyfin 没有降级机制。这一点非常重要：一旦启动新版本的 Jellyfin 实例，所有待处理的迁移会立即应用，导致数据无法在旧版本中使用。唯一能恢复旧版本的方法就是还原备份。因此，若想测试不稳定版本或在升级前保留退路，备份必不可少。实际测试不稳定版本时，建议通过 cron 任务等自动机制更频繁备份，确保遭遇严重问题时能恢复数据。

当遇到程序错误时，备份也能发挥作用。例如新版本中的错误导致 Jellyfin 数据损坏时，通过备份恢复可快速还原正常数据并应用修复方案。没有备份的话，这种情况将束手无策。

最后，管理失误、常规操作问题（如磁盘写满）或比特衰减都可能导致数据损坏，此时必须通过备份恢复。有备无患永远是最佳策略。

备份 Jellyfin 数据有两种方式：一种是使用内置的备份/恢复系统，另一种是手动操作。

内置备份功能​

Jellyfin 的内置备份系统可在服务在线运行时创建备份，而手动备份则必须先停止 Jellyfin。不过在 10.11 版本中，我们仍建议在低负载且无扫描任务时执行备份操作。

创建内置备份​

要创建新备份，请进入 Jellyfin 控制面板，打开Backups标签页并点击Create Backup按钮。随后弹出的窗口会要求您选择需要备份的数据。

  • 数据库：默认启用。包含 jellyfin.db 或所用数据库提供程序中的所有数据。

  • 元数据：元数据文件夹的内容，根据所选设置可能包含元数据图像。

  • 字幕：所有提取的字幕（包括下载的字幕）。

  • Trickplay：所有未与媒体文件同目录存储的 Trickplay 数据。

备份系统会检查备份文件夹（备份写入位置）是否至少有 5GB 可用空间。但若同时备份字幕和快进预览数据，此容量可能不足，请确保预留充足空间。 备份文件夹默认位于 Jellyfin 数据目录内：

  • 官方 Docker：<volume path>/config/data/backups，其中 <volume path> 是 /config 卷的源路径，在 docker-compose.yml 或 docker run 的 -v 选项中设置。

  • LinuxServer.io Docker：<volume path>/config/data/data/backups，其中 <volume path> 是 /config 卷的源路径，在 docker-compose.yml 或 docker run 的 -v 选项中设置。

  • Debian/Ubuntu 安装包：/var/lib/jellyfin/data/backups。

  • RPMFusion Fedora/CentOS 安装包：/var/lib/jellyfin/data/backups。

  • Windows 用户安装版：%LOCALAPPDATA%\Jellyfin\data\backups（即 C:\Users\<Username>\AppData\Local\Jellyfin\data\backups）

  • Windows 服务安装版：%PROGRAMDATA%\Jellyfin\Server\data\backups（即 C:\ProgramData\Jellyfin\Server\data\backups）

  • macOS 安装包 (.dmg)：数据存储在以下路径之一（请备份存在的路径）：~/.config/jellyfin/data/backups、~/.local/share/jellyfin/data/backups、~/Library/Application Support/Jellyfin/data/backups：

  • 便携安装：

    • Linux：数据存储在 ~/.local/share/jellyfin/data/backups
    • Windows：数据与配置位于 C:\Users\<Username>\AppData\Local\jellyfin\data\backups（可用 %LOCALAPPDATA% 表示）
    • macOS：数据存储在以下路径（请备份存在的路径）：~/.config/jellyfin/data/backups、~/.local/share/jellyfin/data/backups、~/Library/Application Support/Jellyfin/data/backups

点击Create按钮后，所有数据将写入新的 zip 归档文件。

从内置备份恢复​

要从备份恢复，您可通过两种方式：在 Web 界面中进入与上一步相同的视图，在备份列表中点击恢复按钮；或启动 jellyfin 时添加 --restore-archive PATH_TO_BACKUP_ZIP 参数。请注意，从 Web 界面启动恢复时，服务器将立即重启以执行此操作，期间服务不可用。

手动备份​

手动备份需要您自行复制 Jellyfin 所需的全部数据。

创建手动备份​

  1. 停止正在运行的 Jellyfin 服务。此步骤至关重要，否则数据库将被锁定，恢复时可能无法正常使用。请注意这将中断所有播放。

    • 全平台通用：在 Jellyfin 控制面板点击"关机"。此操作应能在所有平台正常停止进程，若无效请尝试下方方法。
    • Docker：docker stop jellyfin
    • Debian/Ubuntu 安装包：sudo systemctl stop jellyfin 或 sudo service jellyfin stop
    • Windows 安装程序：右键点击系统托盘图标选择"退出"；或在任务管理器终止 Jellyfin 进程。
    • macOS 安装包 (.dmg)：在活动监视器终止 Jellyfin 进程。
    • 便携安装（全平台适用）：停止正在运行的 jellyfin 或 jellyfin.exe 程序（无论以何种方式启动）。

  2. 将数据目录和配置目录复制到目标位置。副本命名可自由决定，建议采用含日期和版本号的格式（如 jellyfin.2024-05-01_10.8.13）。具体路径因平台而异，通常遵循支持平台的 XDG 目录规范。更多信息请参阅配置文档。

    注意：以下为默认路径，若您曾修改过数据/配置路径，请使用自定义路径。

    • 官方 Docker 版：数据目录即 /config 卷的源路径（在 docker-compose.yml 或 docker run 的 -v 参数中设定），此目录包含配置目录。
    • LinuxServer.io Docker 版：配置目录即 /config 卷的源路径（在 docker-compose.yml 或 docker run 的 -v 参数中设定），此目录包含数据目录。
    • Debian/Ubuntu 安装包：数据目录 /var/lib/jellyfin，配置目录 /etc/jellyfin（路径定义于 /etc/default/jellyfin）。
    • RPMFusion Fedora/CentOS 安装包：数据目录 /var/lib/jellyfin，配置目录 /etc/jellyfin（路径定义于 /etc/sysconfig/jellyfin）。
    • Windows 托盘/安装程序 (.exe)：数据目录为 %PROGRAMDATA%\Jellyfin\Server（即 C:\ProgramData\Jellyfin\Server）或 %LOCALAPPDATA%\Jellyfin（即 C:\Users\<Username>\AppData\Local\Jellyfin），此目录包含配置目录。
    • macOS 安装包 (.dmg)：数据存储于以下路径（请备份存在的目录）：~/.config/jellyfin/、~/.local/share/jellyfin/、~/Library/Application Support/Jellyfin/。
    • 便携安装版：
      • Linux：数据与配置目录均为 ~/.local/share/jellyfin
      • Windows：数据目录为 %LOCALAPPDATA%\jellyfin（即 C:\Users\<Username>\AppData\Local\jellyfin），此目录包含配置目录。
      • macOS：数据存储于以下路径（请备份存在的目录）：~/.config/jellyfin/、~/.local/share/jellyfin/、~/Library/Application Support/Jellyfin/。

    以 Debian 为例，可通过以下命令将两个目录复制到目标路径：

    TIMESTAMP=$(date +%Y%m%d%H%M%S)
    VERSION=10.9.10
    sudo mkdir -p /media/backups/jellyfin.${TIMESTAMP}_${VERSION}  # Or change the path wherever in your system makes sense to you
    sudo cp -a /var/lib/jellyfin /media/backups/jellyfin.${TIMESTAMP}_${VERSION}/data
    sudo cp -a /etc/jellyfin /media/backups/jellyfin.${TIMESTAMP}_${VERSION}/config

  3. 重新启动 Jellyfin（升级后或当前版本）。至此，步骤 2 选择的路径中已保存数据的安全副本。

从手动备份恢复​

本流程假定您已按前述步骤完成备份。

  1. 停止正在运行的 Jellyfin 服务进程。

  2. 转移当前数据/配置目录（例如添加 .bak 后缀）：sudo mv /var/lib/jellyfin /var/lib/jellyfin.bak 与 sudo mv /etc/jellyfin /etc/jellyfin.bak。

  3. 将备份文件复制（切勿移动或重命名）到原始路径：sudo cp -a /media/backups/jellyfin.2024-10-27_10.9.11/data /var/lib/jellyfin 与 sudo cp -a /media/backups/jellyfin.2024-10-27_10.9.11/config /etc/jellyfin。

  4. 如需降级，请将 Jellyfin 版本降至与备份一致的版本。

  5. 重新启动 Jellyfin。在版本匹配的前提下，系统应能正常加载旧数据启动。若您进行了降级操作，此过程可能会自动完成。