Immich 项目部署

一、功能概览

二、部署方案选择

本文以 Docker Compose 为主线。

三、环境要求

• 系统：Linux 服务器（也可在 Windows 或 macOS 的 Docker 环境中试用）
• 硬件：至少 2 核 CPU、6GB 内存（人脸识别和智能搜索会占用较多内存）
• 软件：Docker Engine 与 Docker Compose 插件
• 磁盘：
  • 照片库目录：容量要足够大，建议使用独立磁盘或挂载盘
  • 数据库目录：必须是本地磁盘，不支持网络共享存储（如 NFS、SMB）
• 端口：默认使用 2283 端口

Docker 版本注意

• 命令是 docker compose（中间是空格），不是旧版的 docker-compose。
• 若报 unknown shorthand flag: 'd' in -d，通常是装了发行版自带的旧版 dockerio 包。请卸载后按 Docker 官方仓库方式重装。
• 若报 can't set healthcheck.start_interval as feature require Docker Engine v25 or later，可升级 Docker，或把 docker-compose.yml 中数据库服务里的 start_interval 这一行注释掉。

四、Docker Compose 部署步骤

4.1 创建部署目录

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

4.2 获取配置文件

在 GitHub 上打开 immich-app/immich 仓库的 Releases 页面，下载最新版本附带的两个文件，放入上面的目录：

1. docker-compose.yml
2. example.env，下载后重命名为 .env

也可以使用 wget -O 命令，从最新版 Release 的下载路径分别保存为上述两个文件名。

4.3 编辑 .env

示例内容（以你实际下载的文件为准，不同版本字段可能略有差异）：

# 上传文件（照片库）的存放位置，请指向容量充足的目录
UPLOAD_LOCATION=./library

# 数据库文件存放位置，必须是本地磁盘，不支持网络共享
DB_DATA_LOCATION=./postgres

# 时区，取消注释并修改
TZ=Asia/Shanghai

# Immich 版本，可固定为具体版本号，避免意外升级
IMMICH_VERSION=v2

# 数据库密码，只能使用 A-Z a-z 0-9，请改成随机强密码
DB_PASSWORD=请替换为随机密码

DB_USERNAME=postgres
DB_DATABASE_NAME=immich

要点：

• UPLOAD_LOCATION 请指向全新的目录，并确认有足够剩余空间。
• DB_PASSWORD 只用大小写字母和数字，避免特殊字符导致 Docker 解析出错，可用 pwgen 生成。
• 生产环境建议把 IMMICH_VERSION 固定到具体版本，升级时再手动修改。

4.4 启动

docker compose up -d

首次启动会拉取镜像，耗时取决于网速。查看状态：

docker compose ps
docker compose logs -f immich-server

4.5 初始化管理员

用浏览器访问「服务器IP地址:2283」，点击 Getting Started，第一个注册的用户自动成为管理员，后续用户由管理员创建。

五、服务组成说明

典型的 docker-compose.yml 包含以下服务：

数据说明：

• 数据库中只有元数据和用户信息。
• 原始照片和视频存放在 UPLOAD_LOCATION，这是备份的重点。

六、手机端接入

1. 在应用商店安装 Immich 官方手机应用。
2. 登录时填写服务器地址，格式为「协议加 IP 或域名加端口」，局域网内可直接使用服务器 IP 加 2283 端口。
3. 登录后点击右上角云朵图标进入备份页面，选择要备份的相册，打开 Enable Backup。
4. 首次备份量大，耗时较长，可先选少量照片测试。
5. 在管理员后台的任务队列页面可查看服务器对照片的处理进度。

七、反向代理与（公网访问推荐）

不建议把 2283 端口直接暴露到公网，建议放在反向代理之后并启用 证书。

Caddy 示例（自动申请证书）：

photos.example.com {
    reverse_proxy 127.0.0.1:2283
}

如果使用 Nginx，请注意：

• 必须开启 WebSocket 升级支持，否则网页实时状态异常。
• 需要把请求体大小限制调大（client_max_body_size），否则大文件、视频上传会失败。
• 需要把读写超时调长，避免大文件上传中断。

八、备份与恢复

1. 照片文件：备份整个 UPLOAD_LOCATION，可使用 rsync、restic、Borg 等工具，并同步一份到异地。
2. 数据库：Immich 自带数据库定时备份功能，可在管理后台查看与配置；也建议把数据库目录一并纳入备份。
3. 恢复演练：定期在测试环境做一次恢复，确认备份可用。
4. 3-2-1 原则：3 份副本、2 种不同介质、1 份异地。

九、升级与维护

cd ~/immich-app

# 升级前先阅读版本发布说明，留意是否有破坏性变更
docker compose pull
docker compose up -d

# 清理旧镜像
docker image prune

建议：

• 升级前先备份数据库和照片库。
• 大版本升级务必阅读发布说明，按要求修改 .env 或 docker-compose.yml。
• 固定版本号，不要长期依赖浮动标签自动升级。

十、性能与硬件加速（可选）

• 机器学习服务支持 GPU 或专用硬件加速，视频转码也支持硬件加速，具体需要在 Compose 文件中启用官方提供的对应配置片段，并确认驱动与容器运行时已就绪。
• 机器学习服务可以单独部署到性能更强的机器上，主服务通过配置指向它。
• 内存紧张时，可降低机器学习并发或在后台任务设置中限制并发数。

十一、常见问题排查

十二、命令速查

# 启动 / 停止 / 重启
docker compose up -d
docker compose down
docker compose restart

# 查看状态与日志
docker compose ps
docker compose logs -f immich-server

# 升级
docker compose pull && docker compose up -d