Docker Compose 部署 Immich：手机照片自动备份与常见故障排查

Immich 是一套自托管照片与视频管理平台，支持网页浏览、手机相册上传、相册管理、人物识别和搜索等功能。

部署这类项目，除了让容器正常启动，还需要明确媒体目录、数据库目录、访问方式以及备份范围。否则，服务看起来运行正常，后续迁移、更新或磁盘故障时仍然可能遇到问题。

本文以 Linux 主机为例，完成 Immich 的基础部署、手机连接和常见故障排查。适用于新建实例，已有数据的环境不要直接覆盖配置。

1. 部署环境与资源要求

准备一台已安装 Docker Engine 和 Docker Compose 插件的 Linux 主机。

项目	要求或建议
操作系统	64 位 Debian、Ubuntu 等 Linux 系统
CPU	最低 2 核，推荐 4 核
内存	最低 6GB，推荐 8GB
数据库存储	优先使用本机 SSD，不使用网络共享目录
媒体存储	根据照片、视频、处理文件和后续增长规划
默认服务端口	TCP 2283

当前 Immich v3 的机器学习容器在 amd64 平台上要求 CPU 支持 x86-64-v2。使用旧设备或虚拟机时，需要检查对应指令集是否可用。

如果准备使用莱卡云 Linux 云服务器部署，建议先按以上条件核对配置，再结合现有照片容量和视频比例规划磁盘。

以下服务器端命令以 root 账户执行为例。先确认 Docker 环境：

复制代码

docker --version
docker compose version
docker info

如果 docker compose version 无法正常执行，需要先安装或修复 Compose 插件。本文使用的是带空格的 docker compose 命令。

2. 规划配置与数据目录

本例采用以下目录：

路径	用途
`/opt/immich`	项目配置目录
`/opt/immich/docker-compose.yml`	容器编排文件
`/opt/immich/.env`	环境变量和数据库密码
`/opt/immich/library`	媒体数据目录
`/opt/immich/postgres`	PostgreSQL 数据目录

先创建项目目录：

复制代码

mkdir -p /opt/immich
cd /opt/immich

检查所在磁盘的容量：

复制代码

df -h /opt/immich

如果系统盘较小，应在首次启动前，将媒体路径安排到容量充足、已经正确挂载的数据盘。

不要因为目录名包含 data 或 library，就认为它已经位于数据盘。实际存储位置需要结合挂载情况确认。

3. 下载官方 Compose 文件

在新建的项目目录中执行：

复制代码

wget -O docker-compose.yml \
  https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml

wget -O .env \
  https://github.com/immich-app/immich/releases/latest/download/example.env

检查文件是否存在：

复制代码

ls -la docker-compose.yml .env

.env 是隐藏文件，普通的 ls 不一定会显示。

这里使用官方发布的配套文件，不手动拼接不同教程里的数据库、缓存或机器学习容器配置。

已有实例不要用这组下载命令覆盖现有文件，尤其是 .env**。**

4. 修改环境变量

使用编辑器打开配置：

复制代码

nano /opt/immich/.env

找到对应变量并修改：

复制代码

UPLOAD_LOCATION=/opt/immich/library
DB_DATA_LOCATION=/opt/immich/postgres
TZ=Asia/Shanghai

如果 TZ 前面有注释符号 #，需要去掉。

以上只是需要调整的部分，不能用这三行替换整个 .env****文件。其他变量保留官方模板内容。

接着生成随机数据库密码：

复制代码

openssl rand -hex 24

将输出结果填入 .env 的 DB_PASSWORD= 后面，替换默认值。

这是首次初始化前的密码设置。数据库已经创建后，仅修改 .env 中的密码，并不会自动修改数据库内部用户的密码，可能造成连接失败。

保存配置，创建目录：

复制代码

mkdir -p /opt/immich/library
mkdir -p /opt/immich/postgres
chmod 600 /opt/immich/.env

如果使用自定义数据盘路径，创建目录的命令也要同步调整。

5. 限制首次访问范围

首次注册的用户会成为管理员，初始化页面不应直接开放给所有人。

如果打算先通过 SSH 隧道测试，可以编辑 docker-compose.yml，在 immich-server 服务的 ports 中，将原来的端口映射替换为：

复制代码

ports:
  - "127.0.0.1:2283:2283"

只替换对应端口映射，保持其他配置及缩进不变。

这样服务仅通过宿主机回环地址发布，后续可以通过 SSH 隧道完成初始化，或由宿主机上的反向代理提供 HTTPS 访问。

6. 校验配置并启动服务

进入项目目录：

复制代码

cd /opt/immich
docker compose config --quiet

确认没有报错，再执行：

复制代码

docker compose up -d
docker compose ps -a

首次运行需要拉取镜像并初始化相关服务。

如果容器没有正常运行，查看日志：

复制代码

docker compose logs --tail=100

需要持续观察时使用：

复制代码

docker compose logs -f --tail=100

按 Ctrl+C 只会退出日志查看，不会停止容器。

随后在服务器上检查 HTTP 响应：

复制代码

curl -I --max-time 10 http://127.0.0.1:2283

能够收到 HTTP 响应，说明该地址已有服务响应；是否完全可用，还要结合响应状态、容器健康状态及实际页面判断。

7. 创建管理员并验证上传

如果采用前面的回环地址绑定，在自己的电脑终端执行：

复制代码

ssh -N -L 12283:127.0.0.1:2283 用户名@服务器IP

将用户名和服务器 IP 替换为真实信息。SSH 使用非默认端口时，添加 -p 端口号。

保持这个终端连接，然后在电脑浏览器中打开：

复制代码

http://127.0.0.1:12283

按照页面提示创建管理员账户。

先上传少量测试素材，确认：

照片能够正常打开；
拍摄日期和排列顺序符合预期；
短视频能够播放；
下载后的原文件可以正常使用。

这里的 127.0.0.1:12283 是电脑上的 SSH 隧道入口，不能直接拿去作为手机 App 的服务器地址。

8. 配置手机访问与自动备份

手机需要一个实际可访问的服务地址，可以通过私有网络访问，也可以通过配置好 HTTPS 的域名访问。

如果使用宿主机上的反向代理，可将上游指向：

复制代码

http://127.0.0.1:2283

如果反向代理也运行在容器里，则应根据容器网络配置上游地址。代理容器中的 127.0.0.1 指向代理容器自身，不能直接照搬宿主机地址。

完成访问配置后：

在手机浏览器中确认服务地址能够正常打开。
安装 Immich App，填写同一个服务地址。
登录账户，授予所需照片访问权限。
选择一个测试相册，启用备份。
拍摄一张新照片，检查服务器端是否收到。

首次导入大量照片时，建议使用稳定的 Wi-Fi，并接通电源。

后台上传受到手机系统调度和电池优化影响。启用备份后，仍需查看待上传数量和实际完成情况。

9. 常见故障排查

9.1 本机能访问，服务器公网 IP 打不开

如果使用了：

复制代码

- "127.0.0.1:2283:2283"

这是预期行为，因为端口仅发布在回环地址上。

应通过 SSH 隧道、已配置的反向代理或私有网络方案访问，无须为此关闭防火墙。

9.2 容器持续重启

先查看状态与最近日志：

复制代码

cd /opt/immich
docker compose ps -a
docker compose logs --since=10m --tail=200

再检查资源：

复制代码

free -h
df -h /opt/immich/library /opt/immich/postgres
docker stats --no-stream

重点结合日志检查内存不足、磁盘已满、目录权限、数据库认证和 CPU 指令集兼容性。

不要通过删除 postgres 目录来尝试"修复"已有实例。

9.3 数据库提示密码认证失败

检查是否在初始化之后修改了 .env 中的 DB_PASSWORD。

已有数据库会保留内部用户密码。环境变量与数据库密码不一致时，需要按数据库密码变更流程处理；如果是误改配置，可核对并恢复原有值。

9.4 上传后缩略图暂未生成

批量导入后，后台可能仍在处理缩略图、视频和机器学习任务。

先检查任务队列与日志，再判断是否资源不足。上传完成和所有后台任务完成，并不是同一个时间点。

9.5 大视频上传失败，小照片正常

依次检查：

反向代理的请求体大小限制；
代理及前置服务的超时设置；
磁盘剩余空间；
上传失败时的服务日志。

如果前面还有 CDN 或 WAF，也需要检查其上传限制。

9.6 手机在 Wi-Fi 下正常，移动网络下失败

先检查 App 的备份网络设置。

如果服务器只允许局域网访问，切换到移动网络后无法连接也是预期现象，需要先解决远程访问方式。

10. 设置备份，保留恢复能力

Immich 的数据库导出备份不包含照片和视频原文件。

需要同时保存：

内容	本例位置或说明
媒体文件	`/opt/immich/library`
数据库导出备份	默认位于媒体目录下的 `backups`
部署配置	`docker-compose.yml` 和 `.env`

可在管理界面的任务队列中创建数据库导出任务，完成后再检查生成的备份文件。界面名称可能随版本或语言设置不同而变化。

本例可以查看备份目录：

复制代码

ls -lh /opt/immich/library/backups

随后还要使用备份工具，将媒体文件、数据库导出和配置复制到独立存储位置。同盘多复制一个目录，不能应对整块磁盘故障。

备份期间应协调上传和其他写入，尽量保证媒体文件与数据库对应。不要把直接复制正在运行的 PostgreSQL 数据目录，当成已经验证可用的数据库导出备份。

正式迁入大量照片之前，建议在独立测试环境中完成一次恢复验证。

11. 更新时不要覆盖现有配置

更新前，先阅读目标版本的发布说明，确认是否需要调整 Compose 文件、环境变量或按指定版本顺序升级。

完成数据和配置备份、按说明调整配置后，再执行常规更新操作：

复制代码

cd /opt/immich
docker compose pull
docker compose up -d
docker compose ps -a
docker compose logs --since=5m --tail=100

如果 IMMICH_VERSION 固定为具体版本，pull 仍会使用该版本对应的镜像，需要根据升级计划调整版本值。

更新后重新验证登录、上传、浏览和视频播放。涉及数据库迁移时，不要把换回旧镜像视为完整回滚方案。

完成部署后，先用少量照片运行一段时间，确认手机上传稳定、存储空间充足，并且备份可以恢复，再逐步扩大媒体库。这样后续维护时，每一部分数据在哪里、出现问题该检查什么，都有明确依据。