如何使用 Docker Compose 部署 Immich

Immich 是一个开源的自建照片和视频备份解决方案，通过 Docker 部署可以快速构建一个稳定的自主管理系统。本文将带你一步步完成使用 Docker Compose 部署 Immich 的过程，帮助你在生产环境中实现高效的媒体管理。

1. 环境准备

在开始部署之前，请确保你已经安装并配置了以下软件：

Docker Engine
请参考官方文档安装 Docker Engine，并确保 Docker 守护进程正在运行。
Docker Compose
Docker Compose 是一个用来管理多容器应用的工具，建议使用最新版。
可通过命令 docker compose version 检查是否已安装。如未安装，请参考 Docker 官方文档进行安装。
服务器或虚拟机环境
部署 Immich 建议使用 Linux 系统环境，保证磁盘空间足够存储备份数据。
如果你在 Windows 或 macOS 上进行测试，也可以通过 Docker Desktop 进行部署。

2. 准备部署文件

2.1 创建部署目录

首先在你的服务器或主机上创建一个用于存放部署文件的目录，例如：

mkdir -p ~/immich-app
cd ~/immich-app

该目录将用来保存 docker-compose.yml 配置文件和环境变量文件 .env。

2.2 下载配置文件

建议从 Immich 的 GitHub Releases 页面下载最新的部署配置文件。你可以通过以下命令下载：

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

如果你喜欢，也可以直接在浏览器中下载这两个文件，然后将其放入刚创建的目录中（注意将下载后的 example.env 重命名为 .env）。

3. 配置环境变量

打开 .env 文件，你会看到如下示例配置内容：

# Immich 环境变量示例
# 可以在 https://immich.app/docs/install/environment-variables 中查看所有支持的变量# 上传文件存储路径，建议设置为一个专用目录
UPLOAD_LOCATION=./library# 数据库文件存储路径，注意网络共享目录不支持用于数据库
DB_DATA_LOCATION=./postgres# 设置时区，这里示例中将时区设置为上海
TZ=Asia/Shanghai# 指定要使用的 Immich 版本
IMMICH_VERSION=release# 数据库密码，建议修改为随机密码，且仅包含 A-Za-z0-9 字符
DB_PASSWORD=postgres# 数据库基本配置，通常无需修改
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

根据你的实际情况，可以对以下内容做出调整：

UPLOAD_LOCATION
指定一个有足够存储空间的目录，用于存放上传的照片和视频。
DB_DATA_LOCATION
用于存储 PostgreSQL 数据库数据，同样建议设置为专用目录。
TZ
设置你所在的时区。
IMMICH_VERSION
默认为 release 版本，如果你想指定具体版本号，也可以将该值修改为类似 v1.71.0 的格式。
DB_PASSWORD
请修改为你自己的安全密码，数据库默认只在容器网络内部使用。

4. 启动 Immich 应用

在完成 .env 文件配置后，就可以启动 Immich 的 Docker Compose 服务了。在 ~/immich-app 目录下执行以下命令：

docker compose up -d

该命令会进行以下操作：

拉取最新的 Immich 镜像（包括相应的后端服务和数据库镜像）。
根据 docker-compose.yml 文件定义启动多个容器，其中包括：
- Immich 服务器容器
- PostgreSQL 数据库容器
- 其他辅助服务容器（如反向代理，视具体配置而定）

使用 -d 参数后，容器将以后台模式运行，你可以通过 docker compose ps 查看当前运行的容器状态。

5. 验证部署和后续配置

5.1 验证服务状态

访问服务器的 IP 地址或域名，默认情况下 Immich 应用会监听 80 端口。如果你在部署过程中修改了端口，请使用对应端口访问。
检查日志：
可以通过命令 docker compose logs -f 实时查看容器启动和运行日志，确认各项服务是否正常工作。

5.2 根据业务需要进行调整

数据备份与存储：
确保 UPLOAD_LOCATION 和 DB_DATA_LOCATION 指向的路径有足够的磁盘空间，并且在生产环境中可以通过挂载持久化卷来保障数据不丢失。
安全配置：
根据实际生产环境注意网络安全，建议为 Docker 服务和数据库容器设置合适的防火墙规则，不直接暴露数据库端口。同时，建议使用 HTTPS 对外提供服务，可通过反向代理（例如 Nginx）实现 TLS 加密。
升级与维护：
当 Immich 发布新版本时，只需更新 IMMICH_VERSION 变量并重新拉取镜像，然后重启服务即可完成升级。

6. 常见问题排查

如果容器启动失败
请检查 .env 文件中环境变量的配置是否正确，尤其是路径配置、时区和数据库密码设置。
如果服务无法访问
请确认 Docker 主机防火墙或安全组规则是否允许访问相应端口；另外，也可以检查 docker compose logs 中是否有错误信息。
资源不足问题
如果发现容器运行时磁盘空间不足或内存占用高，请检查宿主机资源，并考虑扩展存储或为容器设置资源限制。