备份与恢复

推荐使用3-2-1 备份策略来保护数据。应保存您上传的照片/视频副本以及 Immich 数据库的副本以实现全面的备份解决方案。本页面概述了如何备份数据库及用户上传的图片和视频的位置。可在这里找到可用作 cron 任务运行的模板 bash 脚本。

危险

本页面的说明只告诉您如何为 Immich 实例做好备份准备，以及哪些文件需要备份。您仍需自行使用实际的备份工具来进行备份。

数据库

注意

Immich 将文件路径保存到数据库中，不会扫描库文件夹来更新数据库，因此备份非常重要。

信息

有关备份和恢复 Postgres 数据库的详细信息，请参考官方PostgreSQL 文档。

注意

不建议直接备份 DB_DATA_LOCATION 文件夹。如果在数据库运行时这样做，可能会导致备份损坏且无法恢复。

自动数据库转储

警告

自动数据库转储可以在 Postgres 数据库文件损坏时恢复数据库。这些转储没有监控，若失败不会通知您。

注意

数据库转储不包含任何图片或视频，仅包含元数据。它们只能与 UPLOAD_LOCATION 中的其他文件副本一起使用，如下所述。

为了灾难恢复，Immich 会自动创建数据库转储。这些转储存储在 UPLOAD_LOCATION/backups 中。请确保将数据库和下面提到的资源文件夹独立备份。您可以在管理设置中调整转储的计划和保留数量。默认情况下，Immich 会保留最近 14 次的数据库转储，并每天凌晨 2:00 创建一个新的转储。

触发转储

您可以在管理作业状态页面中触发数据库转储。访问此页面，在右上角打开 "创建作业" 模态框，选择 "创建数据库转储" 并点击 "确认"。作业将运行并触发转储，您可以通过检查日志或 backups/ 文件夹来验证转储是否正确完成。此转储将计入根据您的设置保留的最近 X 次转储。

恢复

我们希望将来可以更简单地进行恢复操作，目前您可以通过主机上的 UPLOAD_LOCATION/backups 文件夹找到数据库转储。然后请按照以下部分的步骤恢复数据库。

手动备份与恢复

Linux 系统
Windows 系统 (PowerShell)

备份
docker exec -t immich_postgres pg_dumpall --clean --if-exists --username=<DB_USERNAME> | gzip > "/path/to/backup/dump.sql.gz"

恢复
docker compose down -v  # 注意！删除所有 Immich 数据以从头开始
## 取消下一行的注释并将 DB_DATA_LOCATION 替换为您的 Postgres 路径以永久重置 Postgres 数据库
# rm -rf DB_DATA_LOCATION # 注意！删除所有 Immich 数据以从头开始
docker compose pull             # 更新到最新版本的 Immich（如果需要）
docker compose create           # 为 Immich 应用创建 Docker 容器而不运行它们
docker start immich_postgres    # 启动 Postgres 服务器
sleep 10                        # 等待 Postgres 服务器启动
# 如果您未遵循默认设置，请检查数据库用户
gunzip --stdout "/path/to/backup/dump.sql.gz" \
| sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" \
| docker exec -i immich_postgres psql --dbname=postgres --username=<DB_USERNAME>  # 恢复备份
docker compose up -d            # 启动 Immich 的其余应用

备份
[System.IO.File]::WriteAllLines("C:\absolute\path\to\backup\dump.sql", (docker exec -t immich_postgres pg_dumpall --clean --if-exists --username=<DB_USERNAME>))

恢复
docker compose down -v  # 注意！删除所有 Immich 数据以从头开始
## 取消下一行的注释并将 DB_DATA_LOCATION 替换为您的 Postgres 路径以永久重置 Postgres 数据库
# Remove-Item -Recurse -Force DB_DATA_LOCATION # 注意！删除所有 Immich 数据以从头开始
## 您应将备份（作为卷，例如：`- 'C:\path\to\backup\dump.sql:/dump.sql'`）挂载到 immich_postgres 容器中，并使用 docker-compose.yml。
docker compose pull                               # 更新到最新版本的 Immich（如果需要）
docker compose create                             # 为 Immich 应用创建 Docker 容器而不运行它们
docker start immich_postgres                      # 启动 Postgres 服务器
sleep 10                                          # 等待 Postgres 服务器启动
docker exec -it immich_postgres bash              # 进入 Docker shell 并运行以下命令
# 如果您未遵循默认设置，请检查数据库用户。如果您的备份以 `.gz` 结尾，请将 `cat` 替换为 `gunzip --stdout`。
cat "/dump.sql" | sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" | psql --dbname=postgres --username=<DB_USERNAME>
exit                                              # 退出 Docker shell
docker compose up -d                              # 启动 Immich 的其余应用

注意：要使数据库恢复正确进行，需要全新安装（即从未运行过 Immich 服务器，仅创建 Docker 容器）。如果 Immich 应用已运行，数据库恢复时可能会遇到 Postgres 冲突（例如关系已存在、违反外键约束、多主键等），这种情况下需要删除 DB_DATA_LOCATION 文件夹以重置数据库。

提示

某些部署方式可能难以单独启动数据库而不启动服务器。在这种情况下，您可以在启动服务之前设置环境变量 DB_SKIP_MIGRATIONS=true。这将防止服务器运行干扰恢复过程的迁移。在数据库恢复后，请确保删除此变量并重新启动服务。

文件系统

Immich 在文件系统中存储两种内容：(a) 原始、未修改的资源（照片和视频），以及 (b) 生成的内容。我们建议备份 UPLOAD_LOCATION 的全部内容，但只有原始内容是关键的，这些内容存储在以下文件夹中：

UPLOAD_LOCATION/library
UPLOAD_LOCATION/upload
UPLOAD_LOCATION/profile

如果您选择仅备份这些文件夹，则需要在从备份恢复后重新运行所有资源的转码和缩略图生成作业。

注意

如果您将这些文件夹中的一些移动到不同的存储设备，如 profile/，请确保调整备份路径以匹配您的设置。

资源类型与存储位置

某些存储位置会受到存储模板的影响。有关更多详细信息，请参见下文。

存储模板关闭（默认）。
存储模板开启

备注

UPLOAD_LOCATION/library 文件夹在运行版本 1.92.0 的新机器上默认不会使用。仅在系统管理员启用存储模板引擎时才会使用，详细信息请阅读发布说明。

1. 用户特定文件夹：

每个用户都有一个唯一的字符串标识它们。
您可以在账户“账户设置 -> 账户 -> 用户 ID”中找到您的用户 ID。

2. 资源类型与存储位置：

源资源：
- 通过浏览器界面、移动客户端和 CLI 上传的原始资源。
- 存储在 UPLOAD_LOCATION/upload/<userID> 中。
用户头像：
- 用户个人资料图像。
- 存储在 UPLOAD_LOCATION/profile/<userID> 中。
预览图像：
- 每个资源的小缩略图和大预览图像，以及识别的面部缩略图。
- 存储在 UPLOAD_LOCATION/thumbs/<userID> 中。
编码资源：
- 为了更好的兼容性，已从原始内容重新编码的视频。原始内容不会被删除。
- 存储在 UPLOAD_LOCATION/encoded-video/<userID> 中。
Postgres 数据库：
- Immich 数据库包含使系统正常运行所需的所有信息。
  注意： 此文件夹仅对根据 v1.102.0 进行更改的用户（这是可选且非强制更改）或从此版本开始的用户可见。
- 存储在 DB_DATA_LOCATION 中。
危险
对该文件夹的备份并不构成对数据库的备份！请按照此处列出的说明了解如何进行正确的备份。

备注

如果选择启用存储模板引擎，它会将所有资源移动到 UPLOAD_LOCATION/library/<userID>。

当您关闭存储模板引擎时，它会将资源保留在 UPLOAD_LOCATION/library/<userID>，而不会将其返回到 UPLOAD_LOCATION/upload。 新资源 将保存到 UPLOAD_LOCATION/upload。

1. 用户特定文件夹：

每个用户都有一个唯一的字符串标识它们。
- 管理员可以为用户设置一个存储标签，该标签将在 library/ 文件夹中替代 <userID> 使用。
- 管理员默认的存储标签是 admin。
您可以在账户设置 -> 账户 -> 用户 ID 中找到您的用户 ID 和存储标签。

2. 资产类型和存储位置：

源资产：
- 通过浏览器界面、移动端和命令行界面上传的原始资产。
- 存储在 UPLOAD_LOCATION/library/<userID>。
头像图片：
- 用户的个人资料图片。
- 存储在 UPLOAD_LOCATION/profile/<userID>。
缩略图图片：
- 每个资产的预览图片（模糊、小、大）以及识别的人脸缩略图。
- 存储在 UPLOAD_LOCATION/thumbs/<userID>。
编码资产：
- 从原始视频重新编码以实现更广泛兼容性的视频。原始视频不会被删除。
- 存储在 UPLOAD_LOCATION/encoded-video/<userID>。
上传队列中的文件（移动端）：
- 通过移动应用程序上传的文件。
- 临时存储在 UPLOAD_LOCATION/upload/<userID>。
- 上传成功后转移到 UPLOAD_LOCATION/library/<userID>。
Postgres：
- Immich 数据库，包含使系统正常运行的所有信息。 注意： 此文件夹仅对已按照 v1.102.0 中提到的更改（可选的、非强制更改）或从此版本开始的用户可见。
- 存储在 DB_DATA_LOCATION。
危险
对此文件夹的备份并不构成对数据库的备份！请按照此处列出的说明了解如何正确执行备份。

危险

除备份外，在任何情况下都不要触碰这些文件夹中的文件。更改或删除资产可能会导致文件未被追踪或丢失。您可以将其视为必须通过移动端或浏览器界面访问、更改和删除资产的应用。

备份顺序

Immich 的备份应同时包含数据库和资产文件。备份这些内容时可能会导致不同步，恢复后可能会出现损坏的资产。处理此问题的最佳方法是在进行备份时停止 immich-server 容器。如果没有任何更改，那么备份将始终保持同步。

如果无法停止容器，则推荐的顺序是首先备份数据库，然后备份文件系统。这样，最糟糕的情况是文件系统中有数据库不知道的文件。如果必要，这些文件可以在恢复后手动（重新）上传。如果反过来备份，即先备份文件系统再备份数据库，那么恢复的数据库可能会引用文件系统备份中不存在的文件，从而导致损坏的资产。

数据库​

自动数据库转储​

触发转储​

恢复​

手动备份与恢复​

文件系统​

资源类型与存储位置​

备份顺序​

数据库