Immich 备份与恢复完全指南数据库转储、资产文件系统与回滚机制【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich本文基于 Immich 官方文档 备份与恢复 编写覆盖数据库自动备份的原理与配置、Web 界面与命令行两种恢复路径、文件系统中各类资产的存储位置以及备份顺序等容易出错的关键细节。读完本文你将能够为 Immich 实例制定一套完整的数据库加文件备份方案并掌握从设置页、首次安装引导页或纯命令行三种方式恢复数据库的实操步骤。核心原则为什么必须同时备份数据库和文件官方推荐采用 3-2-1 备份策略3 份数据副本、2 种不同介质、1 份异地来保护照片数据。一个完整的 Immich 备份必须同时包含两部分已上传的照片/视频原始文件Immich 数据库。这一点至关重要因为 Immich 把文件路径和用户元数据都存放在数据库里它不会去扫描图库文件夹来重建索引。换句话说只备份照片文件而没有数据库备份恢复后文件将“无人认领”反之只备份数据库而没有文件则所有资产都会显示为缺失。注意官方文档中的步骤只说明如何为 Immich 实例“做好被备份的准备”、应该备份哪些文件真正执行备份动作、选择什么备份工具仍需要你自己完成。数据库备份自动数据库备份Immich 内置了面向灾难恢复的数据库自动备份功能备份文件存储在UPLOAD_LOCATION/backups目录中并可通过管理后台Web 界面管理在Administration Settings Backup中可以调整备份计划与保留策略默认值为保留最近 14 份备份每天凌晨 2:00 创建一份默认值可在源码 server/src/dtos/config.dto.ts 中确认enabled: true、cronExpression: CronExpression.EVERY_DAY_AT_2AM、keepLastAmount: 14。注意数据库备份只包含元数据不包含任何照片或视频。它必须与UPLOAD_LOCATION中文件的一份拷贝配合使用才有意义。从源码 server/src/services/database-backup.service.ts 的实现可以看到几个细节备份通过pg_dump导出后用gzip --rsyncable压缩先写入.tmp临时文件、成功后再重命名为正式文件名server/src/services/database-backup.service.ts。文件名格式为immich-db-backup-时间戳-vImmich版本-pgPostgres版本.sql.gz这正是管理后台能识别备份版本号的依据每次备份完成后会执行清理逻辑删除超过keepLastAmount的旧备份并清理所有以.tmp结尾的失败备份文件cleanupDatabaseBackups服务启动时会通过数据库锁DatabaseLock.BackupDatabase决定由哪个节点承担备份任务避免多副本部署时重复备份。手动创建一次备份如果不想等待定时任务可以手动触发一次数据库转储进入Administration Job Queues点击右上角Create job选择Create Database Dump并点击Confirm。生成的备份会出现在UPLOAD_LOCATION/backups中并且同样计入保留数量上限。从设置页恢复数据库备份已有 Immich 实例时推荐使用 Web 界面恢复进入Administration Maintenance展开Restore database backup区域列表中会展示所有可用备份及其版本号与创建时间在目标备份旁点击Restore确认恢复操作。恢复备份会清空当前数据库并用备份内容替换。操作开始前系统会自动创建一个恢复点restore point以便恢复失败时回滚。从首次安装引导页恢复全新实例如果是在全新安装上恢复已有备份步骤如下按照 安装指南 下载并配置好.env和docker-compose.yml将旧实例数据目录中backups、encoded-video、library、profile、thumbs、upload六个文件夹移动到新的UPLOAD_LOCATION下使用过外部图库的用户如果之前的实例使用了 external library 功能确保新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 backupImmich 会进入维护模式并对存储文件夹执行完整性检查查看文件夹状态确认图库文件可读点击Next进入备份选择从列表中选择一份备份或直接上传备份文件.sql.gz点击Restore开始恢复。提示恢复前请确认UPLOAD_LOCATION中的文件夹包含备份创建时存在的那些文件。完整性检查会显示每个文件夹是否可读/可写以及文件数量。直接上传备份文件不经过实例自动备份时也可以直接上传备份文件在Restore database backup区域点击Select from computer选择一个.sql.gz文件上传后的备份会以uploaded-前缀出现在列表中源码中uploadBackup方法会给上传文件加该前缀见 server/src/services/database-backup.service.ts点击Restore从上传的文件恢复。备份版本兼容性查看备份列表时Immich 会根据当前版本与文件名中解析出的版本显示兼容性标识绿色对勾备份版本与当前 Immich 版本一致黄色感叹号备份由其他版本的 Immich 创建红色感叹号无法从文件名确定备份版本。警告跨版本恢复可能需要执行数据库迁移。恢复流程会尝试自动运行迁移但条件允许时仍应尽量选择与备份版本兼容的目标版本。恢复流程内部机制文档描述的恢复流程在源码 restoreDatabaseBackup 中有完整实现实际执行顺序为先为当前数据库创建一个恢复点备份文件名带restore-point-前缀恢复前会先终止其他数据库连接并重建publicschema然后解压备份支持.gz与纯.sql通过psql单事务导入如需要则运行数据库迁移runMigrations执行健康检查确认存在管理员用户hasAdmin并调用checkApiHealth验证 API 正常。如果任何一步失败例如备份损坏、缺少管理员用户Immich 会自动将数据库回滚到恢复点保证数据库不会停留在半新半旧的损坏状态。另外源码中的版本校验逻辑要求 Postgres 主版本落在14 19区间不满足时会抛出UnsupportedPostgresError使恢复中止server/src/services/database-backup.service.ts。命令行备份与恢复面向高级用户或自动化恢复场景可以用命令行完成。以下命令中DB_USERNAME替换为数据库用户名默认为postgresDB_DATABASE_NAME替换为数据库名默认为immich。Linux 系统备份# DB_USERNAME 通常为 postgresDB_DATABASE_NAME 通常为 immich docker exec -t immich_postgres pg_dump --clean --if-exists --dbnameDB_DATABASE_NAME --usernameDB_USERNAME | gzip /path/to/backup/dump.sql.gz恢复docker compose down -v # 警告删除所有 Immich 数据从零开始 ## 如需彻底重置 Postgres取消下一行注释并把 DB_DATA_LOCATION 替换为你的 Postgres 数据路径 # rm -rf DB_DATA_LOCATION # 警告删除所有 Immich 数据从零开始 docker compose pull # 可选更新到 Immich 最新版本 docker compose create # 创建但不启动 Immich 应用容器 docker start immich_postgres # 启动 Postgres sleep 10 # 等待 Postgres 就绪 # 如果你修改过默认值请核对数据库用户 # DB_USERNAME 通常为 postgresDB_DATABASE_NAME 通常为 immich 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 --dbnameDB_DATABASE_NAME --usernameDB_USERNAME --single-transaction --set ON_ERROR_STOPon # 恢复备份 docker compose up -d # 启动 Immich 其余应用Windows 系统PowerShell备份# DB_USERNAME 通常为 postgresDB_DATABASE_NAME 通常为 immich [System.IO.File]::WriteAllLines(C:\absolute\path\to\backup\dump.sql, (docker exec -t immich_postgres pg_dump --clean --if-exists --dbnameDB_DATABASE_NAME --usernameDB_USERNAME))恢复docker compose down -v # 警告删除所有 Immich 数据从零开始 ## 如需彻底重置 Postgres取消下一行注释并把 DB_DATA_LOCATION 替换为你的 Postgres 数据路径 # Remove-Item -Recurse -Force DB_DATA_LOCATION # 警告删除所有 Immich 数据从零开始 ## 建议在 docker-compose.yml 中把备份挂载为 volume例如- C:\path\to\backup\dump.sql:/dump.sql docker compose pull # 可选更新到 Immich 最新版本 docker compose create # 创建但不启动 Immich 应用容器 docker start immich_postgres # 启动 Postgres sleep 10 # 等待 Postgres 就绪 docker exec -it immich_postgres bash # 进入容器 Shell 执行以下命令 # 如果备份是 .gz 结尾把 cat 换成 gunzip --stdout # DB_USERNAME 通常为 postgresDB_DATABASE_NAME 通常为 immich 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 --dbnameDB_DATABASE_NAME --usernameDB_USERNAME --single-transaction --set ON_ERROR_STOPon exit # 退出容器 Shell docker compose up -d # 启动 Immich 其余应用命令行恢复的注意事项版本说明备份与恢复流程在 v2.5.0 有所变更如果你的备份由旧版 Immich 创建请在文档版本选择器中查找对应版本的恢复方法。要求全新安装命令行恢复需要数据库处于“从未运行过”的干净状态Docker 容器创建后 Immich server 从未启动。如果应用已经运行过可能出现 Postgres 冲突relation already exists、外键约束冲突等此时需要删除DB_DATA_LOCATION文件夹重置数据库。DB_SKIP_MIGRATIONStrue某些部署方式下无法在不启动 server 的情况下单独启动数据库。此时可在启动服务前设置环境变量DB_SKIP_MIGRATIONStrue阻止 server 运行会干扰恢复流程的迁移数据库恢复完成后移除该变量并重启服务即可该变量定义于 server/src/dtos/env.dto.ts。单事务提交恢复命令中的--single-transaction --set ON_ERROR_STOPon保证所有变更在一个事务中提交数据库绝不会停留在损坏状态如果某些场景不希望这样可以移除这两个参数。文件系统备份Immich不会替你处理文件系统备份这部分必须自行安排。文件系统中有两类内容a原始、未修改的资产照片和视频b生成内容缩略图、转码视频等。官方建议直接备份UPLOAD_LOCATION的全部内容但其中真正关键的只有原始内容位于以下三个文件夹UPLOAD_LOCATION/libraryUPLOAD_LOCATION/uploadUPLOAD_LOCATION/profile如果只备份这三个文件夹恢复后需要重新运行所有资产的转码和缩略图生成任务来重建生成内容。注意如果你把其中某些文件夹如profile/挪到了其他存储设备上请相应调整备份路径。资产类型与存储位置部分存储位置受存储模板Storage Template开关影响。以v1.92.0起的新机器为例默认不会使用UPLOAD_LOCATION/library只有管理员激活存储模板引擎后资产才会进入library/。用户专属目录每个用户有一个唯一的 user ID账号设置页 Account 中可见。资产类型说明存储位置源资产Storage Template 关闭默认通过浏览器、移动端、CLI 上传的原始资产UPLOAD_LOCATION/upload/userID头像图片用户资料图片UPLOAD_LOCATION/profile/userID缩略图每个资产的小图/大图预览及识别人脸缩略图UPLOAD_LOCATION/thumbs/userID转码资产为兼容播放而转码的视频原始文件不删除UPLOAD_LOCATION/encoded-video/userID数据库转储备份Immich 自动创建的灾难恢复备份UPLOAD_LOCATION/backups/Postgres 数据系统运行所需的全部数据库内容DB_DATA_LOCATION仅当采用了把 Postgres 数据目录移入管理范围内的可选变更或从该版本起步的新安装时才会出现开启 Storage Template 时的差异激活存储模板引擎后资产会被移动到UPLOAD_LOCATION/library/userID关闭引擎后资产不会迁回upload/留在library/userID只有新资产才写入UPLOAD_LOCATION/upload管理员可以为用户设置 Storage Labellibrary/目录下用它代替userIDAdmin 的默认 storage label 为admin移动端上传的文件先暂存于UPLOAD_LOCATION/upload/userID上传成功后再转入UPLOAD_LOCATION/library/userID。警告除备份之外任何情况下都不要直接改动或删除上述文件夹内的文件。变更或删除资产会导致文件变为未跟踪或丢失状态。把文件系统当作“只能透过 App 操作”的黑盒查看、修改、删除资产只能通过移动端或浏览器界面进行。备份顺序先数据库后文件一套完整的 Immich 备份应同时包含数据库和资产文件。两者在备份窗口内可能失去同步恢复后表现为“损坏的资产”。处理方式最佳做法在备份期间停止immich-server容器。没有变更发生时备份必然一致无法停服时推荐顺序是先备份数据库再备份文件系统。最坏情况只是文件系统中存在数据库“不知道”的文件——这些文件可以在恢复后手动重新上传反过来的顺序先文件后数据库是危险的恢复后的数据库可能引用文件系统备份中不存在的文件从而产生损坏的资产。附Borg 定时备份脚本模板Immich 官方另提供了一份可每日/每周以 cron 任务运行的 Borg 备份脚本模板先用pg_dump把数据库导出到UPLOAD_LOCATION/database-backup子目录再用 Borg 对UPLOAD_LOCATION做增量、去重的快照备份并按--keep-weekly4 --keep-monthly3策略清理旧快照恢复时用borg mount挂载快照取回文件。该脚本与内置自动备份的关系值得注意由于脚本在每次库备份的同时执行数据库备份、且快照与资产严格同步使用它之后可以安全地在管理后台关闭内置的自动数据库备份以节省存储空间。小结Immich 的备份体系可以概括为三层内置的pg_dump自动转储管理后台可触发、可配置保留份数与计划、UPLOAD_LOCATION文件系统中三类关键目录library/upload/profile、以及正确的备份顺序先库后文件。恢复路径上Web 界面含恢复点自动创建与失败回滚覆盖了绝大多数场景命令行方式则保留给自动化与深度定制需求。只要坚持“数据库 原始文件必须成对备份”这一核心原则实例的数据安全性就有扎实保障。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Immich 备份与恢复完全指南：数据库转储、资产文件系统与回滚机制
Immich 备份与恢复完全指南数据库转储、资产文件系统与回滚机制【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich本文基于 Immich 官方文档 备份与恢复 编写覆盖数据库自动备份的原理与配置、Web 界面与命令行两种恢复路径、文件系统中各类资产的存储位置以及备份顺序等容易出错的关键细节。读完本文你将能够为 Immich 实例制定一套完整的数据库加文件备份方案并掌握从设置页、首次安装引导页或纯命令行三种方式恢复数据库的实操步骤。核心原则为什么必须同时备份数据库和文件官方推荐采用 3-2-1 备份策略3 份数据副本、2 种不同介质、1 份异地来保护照片数据。一个完整的 Immich 备份必须同时包含两部分已上传的照片/视频原始文件Immich 数据库。这一点至关重要因为 Immich 把文件路径和用户元数据都存放在数据库里它不会去扫描图库文件夹来重建索引。换句话说只备份照片文件而没有数据库备份恢复后文件将“无人认领”反之只备份数据库而没有文件则所有资产都会显示为缺失。注意官方文档中的步骤只说明如何为 Immich 实例“做好被备份的准备”、应该备份哪些文件真正执行备份动作、选择什么备份工具仍需要你自己完成。数据库备份自动数据库备份Immich 内置了面向灾难恢复的数据库自动备份功能备份文件存储在UPLOAD_LOCATION/backups目录中并可通过管理后台Web 界面管理在Administration Settings Backup中可以调整备份计划与保留策略默认值为保留最近 14 份备份每天凌晨 2:00 创建一份默认值可在源码 server/src/dtos/config.dto.ts 中确认enabled: true、cronExpression: CronExpression.EVERY_DAY_AT_2AM、keepLastAmount: 14。注意数据库备份只包含元数据不包含任何照片或视频。它必须与UPLOAD_LOCATION中文件的一份拷贝配合使用才有意义。从源码 server/src/services/database-backup.service.ts 的实现可以看到几个细节备份通过pg_dump导出后用gzip --rsyncable压缩先写入.tmp临时文件、成功后再重命名为正式文件名server/src/services/database-backup.service.ts。文件名格式为immich-db-backup-时间戳-vImmich版本-pgPostgres版本.sql.gz这正是管理后台能识别备份版本号的依据每次备份完成后会执行清理逻辑删除超过keepLastAmount的旧备份并清理所有以.tmp结尾的失败备份文件cleanupDatabaseBackups服务启动时会通过数据库锁DatabaseLock.BackupDatabase决定由哪个节点承担备份任务避免多副本部署时重复备份。手动创建一次备份如果不想等待定时任务可以手动触发一次数据库转储进入Administration Job Queues点击右上角Create job选择Create Database Dump并点击Confirm。生成的备份会出现在UPLOAD_LOCATION/backups中并且同样计入保留数量上限。从设置页恢复数据库备份已有 Immich 实例时推荐使用 Web 界面恢复进入Administration Maintenance展开Restore database backup区域列表中会展示所有可用备份及其版本号与创建时间在目标备份旁点击Restore确认恢复操作。恢复备份会清空当前数据库并用备份内容替换。操作开始前系统会自动创建一个恢复点restore point以便恢复失败时回滚。从首次安装引导页恢复全新实例如果是在全新安装上恢复已有备份步骤如下按照 安装指南 下载并配置好.env和docker-compose.yml将旧实例数据目录中backups、encoded-video、library、profile、thumbs、upload六个文件夹移动到新的UPLOAD_LOCATION下使用过外部图库的用户如果之前的实例使用了 external library 功能确保新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 backupImmich 会进入维护模式并对存储文件夹执行完整性检查查看文件夹状态确认图库文件可读点击Next进入备份选择从列表中选择一份备份或直接上传备份文件.sql.gz点击Restore开始恢复。提示恢复前请确认UPLOAD_LOCATION中的文件夹包含备份创建时存在的那些文件。完整性检查会显示每个文件夹是否可读/可写以及文件数量。直接上传备份文件不经过实例自动备份时也可以直接上传备份文件在Restore database backup区域点击Select from computer选择一个.sql.gz文件上传后的备份会以uploaded-前缀出现在列表中源码中uploadBackup方法会给上传文件加该前缀见 server/src/services/database-backup.service.ts点击Restore从上传的文件恢复。备份版本兼容性查看备份列表时Immich 会根据当前版本与文件名中解析出的版本显示兼容性标识绿色对勾备份版本与当前 Immich 版本一致黄色感叹号备份由其他版本的 Immich 创建红色感叹号无法从文件名确定备份版本。警告跨版本恢复可能需要执行数据库迁移。恢复流程会尝试自动运行迁移但条件允许时仍应尽量选择与备份版本兼容的目标版本。恢复流程内部机制文档描述的恢复流程在源码 restoreDatabaseBackup 中有完整实现实际执行顺序为先为当前数据库创建一个恢复点备份文件名带restore-point-前缀恢复前会先终止其他数据库连接并重建publicschema然后解压备份支持.gz与纯.sql通过psql单事务导入如需要则运行数据库迁移runMigrations执行健康检查确认存在管理员用户hasAdmin并调用checkApiHealth验证 API 正常。如果任何一步失败例如备份损坏、缺少管理员用户Immich 会自动将数据库回滚到恢复点保证数据库不会停留在半新半旧的损坏状态。另外源码中的版本校验逻辑要求 Postgres 主版本落在14 19区间不满足时会抛出UnsupportedPostgresError使恢复中止server/src/services/database-backup.service.ts。命令行备份与恢复面向高级用户或自动化恢复场景可以用命令行完成。以下命令中DB_USERNAME替换为数据库用户名默认为postgresDB_DATABASE_NAME替换为数据库名默认为immich。Linux 系统备份# DB_USERNAME 通常为 postgresDB_DATABASE_NAME 通常为 immich docker exec -t immich_postgres pg_dump --clean --if-exists --dbnameDB_DATABASE_NAME --usernameDB_USERNAME | gzip /path/to/backup/dump.sql.gz恢复docker compose down -v # 警告删除所有 Immich 数据从零开始 ## 如需彻底重置 Postgres取消下一行注释并把 DB_DATA_LOCATION 替换为你的 Postgres 数据路径 # rm -rf DB_DATA_LOCATION # 警告删除所有 Immich 数据从零开始 docker compose pull # 可选更新到 Immich 最新版本 docker compose create # 创建但不启动 Immich 应用容器 docker start immich_postgres # 启动 Postgres sleep 10 # 等待 Postgres 就绪 # 如果你修改过默认值请核对数据库用户 # DB_USERNAME 通常为 postgresDB_DATABASE_NAME 通常为 immich 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 --dbnameDB_DATABASE_NAME --usernameDB_USERNAME --single-transaction --set ON_ERROR_STOPon # 恢复备份 docker compose up -d # 启动 Immich 其余应用Windows 系统PowerShell备份# DB_USERNAME 通常为 postgresDB_DATABASE_NAME 通常为 immich [System.IO.File]::WriteAllLines(C:\absolute\path\to\backup\dump.sql, (docker exec -t immich_postgres pg_dump --clean --if-exists --dbnameDB_DATABASE_NAME --usernameDB_USERNAME))恢复docker compose down -v # 警告删除所有 Immich 数据从零开始 ## 如需彻底重置 Postgres取消下一行注释并把 DB_DATA_LOCATION 替换为你的 Postgres 数据路径 # Remove-Item -Recurse -Force DB_DATA_LOCATION # 警告删除所有 Immich 数据从零开始 ## 建议在 docker-compose.yml 中把备份挂载为 volume例如- C:\path\to\backup\dump.sql:/dump.sql docker compose pull # 可选更新到 Immich 最新版本 docker compose create # 创建但不启动 Immich 应用容器 docker start immich_postgres # 启动 Postgres sleep 10 # 等待 Postgres 就绪 docker exec -it immich_postgres bash # 进入容器 Shell 执行以下命令 # 如果备份是 .gz 结尾把 cat 换成 gunzip --stdout # DB_USERNAME 通常为 postgresDB_DATABASE_NAME 通常为 immich 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 --dbnameDB_DATABASE_NAME --usernameDB_USERNAME --single-transaction --set ON_ERROR_STOPon exit # 退出容器 Shell docker compose up -d # 启动 Immich 其余应用命令行恢复的注意事项版本说明备份与恢复流程在 v2.5.0 有所变更如果你的备份由旧版 Immich 创建请在文档版本选择器中查找对应版本的恢复方法。要求全新安装命令行恢复需要数据库处于“从未运行过”的干净状态Docker 容器创建后 Immich server 从未启动。如果应用已经运行过可能出现 Postgres 冲突relation already exists、外键约束冲突等此时需要删除DB_DATA_LOCATION文件夹重置数据库。DB_SKIP_MIGRATIONStrue某些部署方式下无法在不启动 server 的情况下单独启动数据库。此时可在启动服务前设置环境变量DB_SKIP_MIGRATIONStrue阻止 server 运行会干扰恢复流程的迁移数据库恢复完成后移除该变量并重启服务即可该变量定义于 server/src/dtos/env.dto.ts。单事务提交恢复命令中的--single-transaction --set ON_ERROR_STOPon保证所有变更在一个事务中提交数据库绝不会停留在损坏状态如果某些场景不希望这样可以移除这两个参数。文件系统备份Immich不会替你处理文件系统备份这部分必须自行安排。文件系统中有两类内容a原始、未修改的资产照片和视频b生成内容缩略图、转码视频等。官方建议直接备份UPLOAD_LOCATION的全部内容但其中真正关键的只有原始内容位于以下三个文件夹UPLOAD_LOCATION/libraryUPLOAD_LOCATION/uploadUPLOAD_LOCATION/profile如果只备份这三个文件夹恢复后需要重新运行所有资产的转码和缩略图生成任务来重建生成内容。注意如果你把其中某些文件夹如profile/挪到了其他存储设备上请相应调整备份路径。资产类型与存储位置部分存储位置受存储模板Storage Template开关影响。以v1.92.0起的新机器为例默认不会使用UPLOAD_LOCATION/library只有管理员激活存储模板引擎后资产才会进入library/。用户专属目录每个用户有一个唯一的 user ID账号设置页 Account 中可见。资产类型说明存储位置源资产Storage Template 关闭默认通过浏览器、移动端、CLI 上传的原始资产UPLOAD_LOCATION/upload/userID头像图片用户资料图片UPLOAD_LOCATION/profile/userID缩略图每个资产的小图/大图预览及识别人脸缩略图UPLOAD_LOCATION/thumbs/userID转码资产为兼容播放而转码的视频原始文件不删除UPLOAD_LOCATION/encoded-video/userID数据库转储备份Immich 自动创建的灾难恢复备份UPLOAD_LOCATION/backups/Postgres 数据系统运行所需的全部数据库内容DB_DATA_LOCATION仅当采用了把 Postgres 数据目录移入管理范围内的可选变更或从该版本起步的新安装时才会出现开启 Storage Template 时的差异激活存储模板引擎后资产会被移动到UPLOAD_LOCATION/library/userID关闭引擎后资产不会迁回upload/留在library/userID只有新资产才写入UPLOAD_LOCATION/upload管理员可以为用户设置 Storage Labellibrary/目录下用它代替userIDAdmin 的默认 storage label 为admin移动端上传的文件先暂存于UPLOAD_LOCATION/upload/userID上传成功后再转入UPLOAD_LOCATION/library/userID。警告除备份之外任何情况下都不要直接改动或删除上述文件夹内的文件。变更或删除资产会导致文件变为未跟踪或丢失状态。把文件系统当作“只能透过 App 操作”的黑盒查看、修改、删除资产只能通过移动端或浏览器界面进行。备份顺序先数据库后文件一套完整的 Immich 备份应同时包含数据库和资产文件。两者在备份窗口内可能失去同步恢复后表现为“损坏的资产”。处理方式最佳做法在备份期间停止immich-server容器。没有变更发生时备份必然一致无法停服时推荐顺序是先备份数据库再备份文件系统。最坏情况只是文件系统中存在数据库“不知道”的文件——这些文件可以在恢复后手动重新上传反过来的顺序先文件后数据库是危险的恢复后的数据库可能引用文件系统备份中不存在的文件从而产生损坏的资产。附Borg 定时备份脚本模板Immich 官方另提供了一份可每日/每周以 cron 任务运行的 Borg 备份脚本模板先用pg_dump把数据库导出到UPLOAD_LOCATION/database-backup子目录再用 Borg 对UPLOAD_LOCATION做增量、去重的快照备份并按--keep-weekly4 --keep-monthly3策略清理旧快照恢复时用borg mount挂载快照取回文件。该脚本与内置自动备份的关系值得注意由于脚本在每次库备份的同时执行数据库备份、且快照与资产严格同步使用它之后可以安全地在管理后台关闭内置的自动数据库备份以节省存储空间。小结Immich 的备份体系可以概括为三层内置的pg_dump自动转储管理后台可触发、可配置保留份数与计划、UPLOAD_LOCATION文件系统中三类关键目录library/upload/profile、以及正确的备份顺序先库后文件。恢复路径上Web 界面含恢复点自动创建与失败回滚覆盖了绝大多数场景命令行方式则保留给自动化与深度定制需求。只要坚持“数据库 原始文件必须成对备份”这一核心原则实例的数据安全性就有扎实保障。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考