Immich 备份与恢复指南-未完纪

为保护数据，建议采用 3-2-1 备份策略。完整的备份方案既应保存已上传的照片和视频，也应保存 Immich 数据库。本文介绍数据库备份方法，以及用户上传的图片、视频所在的位置。原文还提供了可通过 cron 定时运行的 Bash 脚本模板入口。

危险提示：本文说明如何为 Immich 实例做好备份准备，以及哪些文件需要备份。你仍然必须自行使用真正的备份工具，将这些内容备份到合适的位置。

数据库

Immich 在数据库中保存文件路径和用户元数据。它不会扫描图库文件夹来重新建立这些信息，因此数据库备份不可或缺。

自动数据库备份

Immich 会自动创建数据库备份，用于灾难恢复。备份位于 UPLOAD_LOCATION/backups，可在网页界面中管理。

进入“管理 → 设置 → 备份”（Administration → Settings → Backup），可以调整备份计划和保留设置。默认每天凌晨 2:00 创建一次备份，保留最近 14 份。

注意：数据库备份只包含元数据，不包含照片或视频。必须将数据库备份与下文所述的 UPLOAD_LOCATION 文件副本配合使用。

手动创建备份

进入“管理 → 任务队列”（Administration → Job Queues）。
点击右上角的“创建任务”（Create job）。
选择“创建数据库转储”（Create Database Dump），然后点击“确认”（Confirm）。

备份将出现在 UPLOAD_LOCATION/backups 中，并计入备份保留数量限制。

恢复数据库备份

Immich 支持通过网页界面或命令行恢复数据库备份。对于大多数用户，推荐使用网页界面。

从设置页面恢复

如果已有 Immich 安装：

进入“管理 → 维护”（Administration → Maintenance）。
展开“恢复数据库备份”（Restore database backup）。
页面会列出可用备份，以及每份备份的版本和创建时间。
点击目标备份旁的“恢复”（Restore）。
确认恢复操作。

说明：恢复会清空当前数据库，并用备份内容替换。操作开始前会自动创建恢复点，以便在恢复失败时回滚。

在首次设置时恢复

如果在全新安装中恢复已有备份，请按以下步骤操作：

按照安装说明下载并填写 .env 和 docker-compose.yml。
将旧实例中的数据目录移到新的 UPLOAD_LOCATION。这些目录包括 backups、encoded-video、library、profile、thumbs 和 upload。
如果旧实例使用了外部图库，请确保新 docker-compose.yml 中的挂载设置对应相同的目录结构；必要时移动相应文件。

例如，旧位置为 UPLOAD_LOCATION=/my-broken-instance/media，新位置为 UPLOAD_LOCATION=/a-brand-new-instance/data 时，需要进行以下文件移动：

/my-broken-instance/media/backups          ->    /a-brand-new-instance/data/backups
/my-broken-instance/media/encoded-video    ->    /a-brand-new-instance/data/encoded-video
/my-broken-instance/media/library          ->    /a-brand-new-instance/data/library
/my-broken-instance/media/profile          ->    /a-brand-new-instance/data/profile
/my-broken-instance/media/thumbs           ->    /a-brand-new-instance/data/thumbs
/my-broken-instance/media/upload           ->    /a-brand-new-instance/data/upload

运行 docker compose up -d 启动 Immich 服务。
在欢迎页面点击“从备份恢复”（Restore from backup）。
Immich 将进入维护模式，并显示存储文件夹的完整性检查结果。
查看文件夹状态，确认图库文件可访问。
点击“下一步”（Next），进入备份选择页面。
从列表选择备份，或者上传 .sql.gz 备份文件。
点击“恢复”（Restore）开始恢复。

提示：恢复前应确保 UPLOAD_LOCATION 中各文件夹包含创建备份时存在的相同文件。完整性检查会显示各文件夹是否可读、可写，以及其中包含多少文件。

上传备份文件

在“恢复数据库备份”部分点击“从计算机选择”（Select from computer）。
选择一个 .sql.gz 文件。
上传的备份会以 uploaded- 前缀出现在列表中。
点击“恢复”，从上传的文件恢复数据。

备份版本兼容性

查看备份时，Immich 会根据当前版本与备份文件名中的信息显示兼容性提示：

备份版本与当前 Immich 版本一致。
备份由其他 Immich 版本创建。
无法确定备份版本。

警告：恢复其他版本创建的备份可能需要执行数据库迁移。恢复过程会尝试自动迁移，但应尽可能选择兼容的版本进行恢复。

恢复过程

Immich 会依次执行以下操作：

备份当前数据库，创建恢复点。
恢复选定的备份。
在需要时执行数据库迁移。
执行健康检查，确认恢复成功。

如果恢复失败，例如备份损坏或缺少管理员用户，Immich 会自动回滚到恢复点。

通过命令行恢复

高级用户或需要自动化恢复的场景，可以使用命令行恢复数据库。

Linux：备份

将 <DB_USERNAME> 替换为数据库用户名，未修改时通常为 postgres；将 <DB_DATABASE_NAME> 替换为数据库名，未修改时通常为 immich。

# Replace <DB_USERNAME> with the database username - usually postgres unless you have changed it.
# Replace <DB_DATABASE_NAME> with the database name - usually immich unless you have changed it.
docker exec -t immich_postgres pg_dump --clean --if-exists --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME> | gzip > "/path/to/backup/dump.sql.gz"

Linux：恢复

危险提示：以下过程用于从零开始恢复。docker compose down -v 会删除相关卷；示例中被注释的删除数据库目录命令会永久重置数据库。执行前务必理解命令影响，并保留可用备份。

docker compose down -v  # CAUTION! Deletes all Immich data to start from scratch
## Uncomment the next line and replace DB_DATA_LOCATION with your Postgres path to permanently reset the Postgres database
# rm -rf DB_DATA_LOCATION # CAUTION! Deletes all Immich data to start from scratch
docker compose pull             # Update to latest version of Immich (if desired)
docker compose create           # Create Docker containers for Immich apps without running them
docker start immich_postgres    # Start Postgres server
sleep 10                        # Wait for Postgres server to start up
# Check the database user if you deviated from the default
# Replace <DB_USERNAME> with the database username - usually postgres unless you have changed it.
# Replace <DB_DATABASE_NAME> with the database name - usually immich unless you have changed it.
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=<DB_DATABASE_NAME> --username=<DB_USERNAME> --single-transaction --set ON_ERROR_STOP=on  # Restore Backup
docker compose up -d            # Start remainder of Immich apps

Windows PowerShell：备份

同样需要根据实际配置替换数据库用户名和数据库名。

# Replace <DB_USERNAME> with the database username - usually postgres unless you have changed it.
# Replace <DB_DATABASE_NAME> with the database name - usually immich unless you have changed it.
[System.IO.File]::WriteAllLines("C:\absolute\path\to\backup\dump.sql", (docker exec -t immich_postgres pg_dump --clean --if-exists --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME>))

Windows PowerShell：恢复

应通过 docker-compose.yml 将备份作为卷挂载到 immich_postgres 容器，例如 - 'C:\path\to\backup\dump.sql:/dump.sql'。下面命令中的删除目录步骤具有破坏性；若备份以 .gz 结尾，应按代码注释将 cat 替换为 gunzip --stdout。

docker compose down -v  # CAUTION! Deletes all Immich data to start from scratch
## Uncomment the next line and replace DB_DATA_LOCATION with your Postgres path to permanently reset the Postgres database
# Remove-Item -Recurse -Force DB_DATA_LOCATION # CAUTION! Deletes all Immich data to start from scratch
## You should mount the backup (as a volume, example: `- 'C:\path\to\backup\dump.sql:/dump.sql'`) into the immich_postgres container using the docker-compose.yml
docker compose pull                               # Update to latest version of Immich (if desired)
docker compose create                             # Create Docker containers for Immich apps without running them
docker start immich_postgres                      # Start Postgres server
sleep 10                                          # Wait for Postgres server to start up
docker exec -it immich_postgres bash              # Enter the Docker shell and run the following command
# If your backup ends in `.gz`, replace `cat` with `gunzip --stdout`
# Replace <DB_USERNAME> with the database username - usually postgres unless you have changed it.
# Replace <DB_DATABASE_NAME> with the database name - usually immich unless you have changed it.

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=<DB_DATABASE_NAME> --username=<DB_USERNAME>  --single-transaction --set ON_ERROR_STOP=on
exit                                              # Exit the Docker shell
docker compose up -d                              # Start remainder of Immich apps

版本警告：备份与恢复流程在 v2.5.0 中发生了变化。如果备份由更旧的 Immich 版本创建，请在原文文档的版本选择器中找到对应版本的手动恢复说明。

注意：要正确恢复数据库，必须使用完全全新的安装，也就是创建 Docker 容器后 Immich 服务从未运行过。如果应用已经运行，可能出现 Postgres 冲突，例如关系已存在、外键约束冲突等。此时需要删除 DB_DATA_LOCATION 文件夹以重置数据库，再恢复。

提示：某些部署方式很难只启动数据库而不启动服务端。此时可以在启动服务前设置环境变量 DB_SKIP_MIGRATIONS=true，阻止服务端运行会干扰恢复的迁移。数据库恢复完成后，删除该变量并重启服务。

上述恢复命令在同一个事务中提交全部变更，以避免数据库处于部分恢复的损坏状态。某些情况下可能不希望这样运行，可以从命令中删除 --single-transaction --set ON_ERROR_STOP=on 来关闭这一行为。

文件系统

Immich 不会替你备份文件系统，必须自行安排。文件系统中的内容分为两类：未经修改的原始资源，也就是照片和视频；以及系统生成的内容。建议备份整个 UPLOAD_LOCATION。其中真正不可替代的原始内容位于：

UPLOAD_LOCATION/library
UPLOAD_LOCATION/upload
UPLOAD_LOCATION/profile

如果只备份这些目录，从备份恢复后需要对全部资源重新运行视频转码和缩略图生成任务。

注意：如果把其中某些目录，例如 profile/，移动到了其他存储设备，应根据实际部署调整备份路径。

资源类型与存储位置

部分存储位置受“存储模板”（Storage Template）设置影响。

关闭存储模板：默认情况

对于从 1.92.0 版本开始运行的新安装，默认不会使用 UPLOAD_LOCATION/library。只有系统管理员启用存储模板引擎后才会使用它。更多信息请参阅该版本的发布说明。

每名用户都拥有一个唯一标识字符串。可在“账户设置 → 账户 → 用户 ID”（Account Settings → Account → User ID）中查看。

原始资源：通过浏览器、手机或 CLI 上传的原始文件，存储在 UPLOAD_LOCATION/upload/<userID>。
头像：用户个人资料图片，存储在 UPLOAD_LOCATION/profile/<userID>。
缩略图：各资源的小缩略图、大预览图，以及识别人脸的缩略图，存储在 UPLOAD_LOCATION/thumbs/<userID>。
编码后的资源：为提高兼容性而重新编码的视频，存储在 UPLOAD_LOCATION/encoded-video/<userID>；原视频不会被删除。
数据库转储备份：Immich 自动创建的灾难恢复备份，存储在 UPLOAD_LOCATION/backups/。
Postgres：包含系统正常运行所需全部信息的 Immich 数据库，存储在 DB_DATA_LOCATION。只有按 v1.102.0 说明进行了可选配置变更，或从该版本开始安装的用户，才会看到此目录。

启用存储模板引擎后，所有资源都会移动到 UPLOAD_LOCATION/library/<userID>。再次关闭引擎时，已有资源仍留在这个目录，不会移回 UPLOAD_LOCATION/upload；后续新资源则保存到 UPLOAD_LOCATION/upload。

启用存储模板

每名用户仍有唯一用户 ID。管理员可以为用户设置存储标签（Storage Label），在 library/ 目录中用该标签替代 <userID>。管理员默认的存储标签为 admin。用户 ID 与存储标签可在“账户设置 → 账户 → 用户 ID”中查看。

原始资源：通过网页、手机和 CLI 上传的原始文件，存储在 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>。
数据库转储备份：自动灾难恢复备份存储在 UPLOAD_LOCATION/backups/。
Postgres：数据库存储在 DB_DATA_LOCATION。此目录出现的版本条件与关闭存储模板时相同：进行了 v1.102.0 所述可选变更，或从该版本开始安装。