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

按 Immich 当前官方 Compose 安装方式部署相册，配置文件库、数据库、域名入口和客户端上传。

配置先满足当前要求

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

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

下载同一发布版本的配置

以下只用于首次安装，固定使用 v3.4.1 的两份发布文件。Linux 服务器需已安装 Bash、curl 和 GNU Coreutils 的 sha256sum；$HOME/immich-app 必须尚不存在。已有目录、配置或照片数据时，不要运行这段初始化命令。

bash；使用前请核对本文前提。

bash <<'BASH'
set -eu
set -C
umask 077

install_dir="$HOME/immich-app"
if [ -e "$install_dir" ] || [ -L "$install_dir" ]; then
    printf '%s\n' 'immich-app 已存在；保留原目录，先检查已有配置和数据。' >&2
    exit 1
fi
command -v curl >/dev/null
command -v sha256sum >/dev/null
mkdir -m 700 -- "$install_dir"
cd -- "$install_dir"
mkdir -m 700 .init-download

release=v3.4.1
base="https://github.com/immich-app/immich/releases/download/$release"
if ! curl -fL "$base/docker-compose.yml" > .init-download/docker-compose.yml; then
    printf '%s\n' 'Compose 下载失败；保留 .init-download，不继续安装。' >&2
    exit 1
fi
if ! curl -fL "$base/example.env" > .init-download/example.env; then
    printf '%s\n' '环境文件下载失败；保留 .init-download，不继续安装。' >&2
    exit 1
fi
sha256sum --check --status <<'SHA256'
1455e3f474687cb96ecb2eab23a0a7268ac5515b094022c66f3902ceb7f0a564  .init-download/docker-compose.yml
dda820cecbcf5fd5d6afecc54107bbd3c973088c631d380dfc83e9f0f2c6b210  .init-download/example.env
SHA256

cat .init-download/docker-compose.yml > docker-compose.yml
sed 's/^IMMICH_VERSION=v3$/IMMICH_VERSION=v3.4.1/' .init-download/example.env > .env
chmod 600 .env
BASH

两份文件先下载到 .init-download，校验通过后才生成 docker-compose.yml 和 .env；.env 中的 IMMICH_VERSION 固定为 v3.4.1。中途失败时，保留新建目录、下载文件和可能已生成的配置，先检查失败原因，不要删除目录或覆盖配置后重试。已有实例的更新按后面的升级说明处理。

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

上面的初始化命令成功结束、两份正式文件均已生成后，在当前终端执行 cd "$HOME/immich-app"，再编辑 .env。将 UPLOAD_LOCATION 指向有足够空间的文件库目录，DB_DATA_LOCATION 指向本地数据库目录。两个目录承担不同数据，数据库目录不要放在网络共享中。

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

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

启动并绑定域名

bash；使用前请核对本文前提。

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

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

caddyfile；使用前请核对本文前提。

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

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