Immich 部署教程：Docker Compose、照片上传与持久化

配置先满足当前要求

官方目前列出至少 6GB 内存、2 核 CPU，建议 8GB、4 核。机器学习容器在 amd64 的 v3 环境还要求 x86-64-v2；虚拟机需要提供相应 CPU 指令集。

数据库放本地 SSD，照片文件库另留足够容量。缩略图和转码会增加空间，不能只按原图大小选择磁盘。以下采用 Linux、Docker Engine 与 Compose 插件，已经有环境可继续操作。

下载同一发布版本的配置

mkdir -p "$HOME/immich-app"
cd "$HOME/immich-app"
curl -fL https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml -o docker-compose.yml
curl -fL https://github.com/immich-app/immich/releases/latest/download/example.env -o .env
chmod 600 .env

两份文件来自同一版本发布资产。长期使用时保存这次下载的文件和版本记录；升级时按对应发布说明更新，配置文件与镜像版本应保持匹配。

修改存储目录与数据库密码

编辑 .env，将 UPLOAD_LOCATION 指向有足够空间的文件库目录，DB_DATA_LOCATION 指向本地数据库目录。两个目录承担不同数据，数据库目录不要放在网络共享中。

DB_PASSWORD 使用随机的字母或数字串，例如执行 openssl rand -hex 24 生成。按该发布文件保留数据库镜像和必需扩展，不把它随意替换成普通 PostgreSQL。

在 docker-compose.yml 中检查 immich-server 的端口映射。准备使用宿主机 Caddy 时，将原映射改为 127.0.0.1:2283:2283，保留文件中的其他设置。

启动并绑定域名

docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100 immich-server

使用 photos.example.com 域名指向服务器，并在宿主机 Caddy 建立入口；域名需改成自己的。

photos.example.com {
    reverse_proxy 127.0.0.1:2283
}

确认域名 HTTPS 能打开初始化页，再创建第一个管理员。未出现页面时查看数据库、服务状态和代理日志，不反复重置数据目录。

上传、客户端和备份

先上传少量照片，确认原图、缩略图和下载正常，再导入整份相册。在手机客户端填写同一个 HTTPS 服务地址，登录后选择需要备份的相册。

备份同时保存照片文件库、数据库备份以及配置。数据库记录文件、相册和用户关系，仅保留图片目录不能恢复全部功能；应用升级前保存可恢复的副本。

先确认升级路径和客户端版本

记录当前服务端版本、IMMICH_VERSION、Compose 文件及数据库镜像，再阅读目标版本发行说明。跨版本升级可能涉及数据库扩展与配置变更；已使用官方 VectorChord 数据库镜像的实例，不需要重复执行面向旧 pgvecto.rs 的迁移。

按官方兼容说明核对手机客户端版本，跨主版本升级前先更新客户端。备份完成并在隔离副本验证升级路径后，将 IMMICH_VERSION 设为选定版本，再执行 docker compose pull 和 docker compose up -d。

照片与数据库必须一起保存

Immich 的自动数据库备份不包含照片和视频。保存数据库备份、整个 UPLOAD_LOCATION、外部文件库及挂载配置，还有 .env 和 Compose。最好停止 immich-server 的写入再备份；无法停写时，官方建议先备份数据库，再备份文件，减少数据库引用不存在文件的情况。

数据库备份出现在照片存储目录，不代表它已经在另一台机器上。把这组副本复制到独立存储，检查可读性和校验和，记录生成备份的 Immich 与数据库版本。

恢复方法要与备份版本匹配

官方在 v2.5.0 调整了备份恢复流程。当前版本可通过维护界面或首次初始化入口恢复数据库；较早版本的备份要切换到对应文档，不能照抄新界面的步骤。恢复数据库会替换现有数据，先在新实例预演，并确认照片目录及外部文件库挂载完整。

恢复后检查旧相册、原图下载、视频播放、手机客户端同步和任务队列。若只恢复了原始文件目录，需要按官方说明重新生成缩略图和转码；重新生成预览不能补回丢失的原图。

升级失败时恢复升级前的完整副本

Immich 官方不支持降级，即便同一个次版本内也不支持。不要把旧镜像连接到已升级的数据库。停止新实例并保留日志，在隔离目录按旧版本文档恢复升级前的数据库、照片、挂载与配置；核对相册和文件后再切换入口。

升级后新上传的照片先单独保存，并记录对应时间。恢复点之后的数据不包含在旧备份内；确认补回方式和客户端状态后再恢复上传，避免把“网页能打开”当成相册已完整恢复。