Immich Docker Compose 部署教程｜私有云相册、手机照片视频自动备份、NAS 部署

🎉 前言！#

准备好你的 Linux 环境（极空间、群晖、威联通、树莓派，或任意一台 Linux 服务器），跟着我一步步操作必定能运行起来

**PS：**写于2026年4月3日，后续更新可能新增配置会不适用
如果在任何步骤卡住，可以直接复制报错问AI
如果不出意外的话，完成三步快速启动后就可以访问了
为了照顾新手小白所以尽可能的多写点^^
作者：一个从坑里爬出来的技术爱好者

一、🎯 一键部署方案#

两个配置文件获取方案，选择一个即可：

📥 方案一：从官方下载（推荐）#

1
# 创建部署目录
2
mkdir -p ./immich-app
3
cd ./immich-app
4

5
# 下载最新配置文件
6
wget https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
7
wget https://github.com/immich-app/immich/releases/latest/download/example.env
8
mv example.env .env

⚡ 方案二：使用我的配置（复制粘贴）#

可以根据自己个性需求修改配置，如果你是小白只修改.env文件的用户名和密码即可
创建docker-compose.yml文件

1
# 警告: 安装 Immich 请遵循官方指南: https://docs.immich.app/install/docker-compose
2
#
3
# 请务必使用当前发行版对应的 docker-compose.yml:
4
#
5
# https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
6
#
7
# main 分支上的配置文件可能与最新发行版不兼容
8

9
# 项目名称
10
name: immich
11

12
services:
13
  # Immich 主服务
14
  immich-server:
15
    container_name: immich_server
16
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
17
    # 硬件转码加速配置（如需开启取消注释）
18
    # extends:
19
    #   file: hwaccel.transcoding.yml
20
    #   service: cpu # 可设置为 [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] 开启硬件加速转码
21
    volumes:
22
      # 请勿修改此行。如需更改媒体文件存储路径，请编辑 .env 文件中的 UPLOAD_LOCATION
23
      - ${UPLOAD_LOCATION}:/data
24
      - /etc/localtime:/etc/localtime:ro
25
    env_file:
26
      - .env
27
    ports:
28
      - '2283:2283'
29
    depends_on:
30
      - redis
31
      - database
32
    restart: always
33
    healthcheck:
34
      disable: false
35

36
  # 机器学习服务（人脸识别、图像分类等）
37
  immich-machine-learning:
38
    container_name: immich_machine_learning
39
    # 硬件加速配置，可在镜像标签后添加 -[armnn, cuda, rocm, openvino, rknn]
40
    # 示例: ${IMMICH_VERSION:-release}-cuda
41
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
42
    # 硬件加速配置（如需开启取消注释）- 详见官方文档
43
    # extends:
44
    #   file: hwaccel.ml.yml
45
    #   service: cpu # 可设置为 [armnn, cuda, rocm, openvino, openvino-wsl, rknn] 开启硬件加速推理
46
    volumes:
47
      - model-cache:/cache
48
    env_file:
49
      - .env
50
    restart: always
51
    healthcheck:
52
      disable: false
53

54
  # 缓存数据库
55
  redis:
56
    container_name: immich_redis
57
    image: docker.io/valkey/valkey:9@sha256:3eeb09785cd61ec8e3be35f8804c8892080f3ca21934d628abc24ee4ed1698f6
58
    healthcheck:
59
      test: redis-cli ping || exit 1
60
    restart: always
61

62
  # 主数据库
63
  database:
64
    container_name: immich_postgres
65
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23
66
    environment:
67
      POSTGRES_PASSWORD: ${DB_PASSWORD}
68
      POSTGRES_USER: ${DB_USERNAME}
69
      POSTGRES_DB: ${DB_DATABASE_NAME}
70
      POSTGRES_INITDB_ARGS: '--data-checksums'
71
      # 如果数据库存储在机械硬盘上，取消下面这行注释
72
      DB_STORAGE_TYPE: 'HDD'
73
    volumes:
74
      # 请勿修改此行。如需更改数据库存储路径，请编辑 .env 文件中的 DB_DATA_LOCATION
75
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
76
    shm_size: 128mb
77
    restart: always
78
    healthcheck:
79
      disable: false
80

81
# 数据卷
82
volumes:
83
  model-cache:

二、🚀 三步快速启动#

1️⃣ 基础配置#

创建.env文件-你需要修改DB_USERNAME、DB_DATABASE_NAME

1
# Immich 环境变量示例
2
# 可以在 https://immich.app/docs/install/environment-variables 中查看所有支持的变量
3

4
# 上传文件存储路径，建议设置为一个专用目录
5
UPLOAD_LOCATION=./library
6

7
# 数据库文件存储路径，注意网络共享目录不支持用于数据库
8
DB_DATA_LOCATION=./postgres
9

10
# 设置时区，这里示例中将时区设置为上海
11
TZ=Asia/Shanghai
12

13
# 指定要使用的 Immich 版本
14
IMMICH_VERSION=release
15

16

17

18
# 数据库基本配置=
19
DB_USERNAME=你的用户名
20
# 数据库密码，建议修改为随机密码，且仅包含 A-Za-z0-9 字符
21
DB_PASSWORD=你的密码
22
DB_DATABASE_NAME=immich

2️⃣ 启动服务#

1
# 启动所有容器
2
docker compose up -d

3️⃣ 访问验证#

🌐 浏览器访问：http://你的服务器IP:2283
🔍 检查状态：docker compose ps
📊 查看日志：docker compose logs -f

三、⚡ 核心功能亮点#

✅ 自动备份 - 从手机自动同步照片

✅ 智能相册 - AI 自动整理分类

✅ 人脸识别 - 自动识别人物分组

✅ 隐私安全 - 数据完全自主掌控

✅ 跨平台 - 支持 Web/iOS/Android

四、🛠️ 常用管理命令#

📁 需要注意：此命令必须在与 docker-compose.yml 文件相同的目录下执行才可生效
否则可能报错：no configuration file provided: not found

1
# 📈 查看服务状态
2
docker compose ps
3

4
# 📋 查看实时日志
5
docker compose logs -f
6

7
# 🔄 重启服务
8
docker compose restart
9

10
# ⏹️ 停止服务
11
docker compose down
12

13
# 🔼 更新到最新版
14
docker compose pull
15
docker compose up -d

五、🛠️ 简化管理命令-设置别名#

复制粘贴即可

1
echo "
2
# Immich 核心管理别名
3
alias dps='docker compose ps'           # 📈 查看服务状态
4
alias dlog='docker compose logs -f'     # 📋 查看实时日志
5
alias drestart='docker compose restart' # 🔄 重启服务
6
alias dstop='docker compose down'       # ⏹️ 停止服务
7
alias dup='docker compose up -d'        # 🆙 启动服务
8
alias dpull='docker compose pull'       # 🔼 拉取新镜像
9
alias dupdate='docker compose pull && docker compose up -d'  # ⚡ 一键更新
10
" >> ~/.bashrc && source ~/.bashrc

🎮 使用说明#

设置后，你的命令就简化为：

1
dps      # 原命令：docker compose ps
2
dlog     # 原命令：docker compose logs -f
3
drestart # 原命令：docker compose restart
4
dstop    # 原命令：docker compose down
5
dup      # 原命令：docker compose up -d
6
dpull    # 原命令：docker compose pull
7
dupdate  # 原命令组合：docker compose pull && docker compose up -d

六、💡 验证是否生效#

1
# 验证别名已设置alias dps
2
# 应该显示：alias dps='docker compose ps'

七、🎯 Immich 初始化配置指南#

1️⃣ 访问注册页面#

首先，在浏览器打开你部署的 Immich 地址（例如：http://你的服务器IP:2283），来到首次使用的注册页面。

2️⃣ 配置存储模板（关键步骤）#

注册登录后，进入设置 → 存储模板，这是最重要的配置项之一。

🎯 推荐使用我的配置模板：

1
{{y}}/{{MM}}/{{dd}}/{{filename}}

📁 格式说明：

{{y}}→ 年份（如：2026）
{{MM}}→ 月份（如：05）
{{dd}}→ 日期（如：20）
{{filename}}→ 原始文件名

✨ 效果预览：一张在 2026年5月20日上传的 photo.jpg会被自动归类到：

1
上传文件夹/2026/05/20/photo.jpg

完成初始化设置后点击右上角账号设置，把能用的功能都打开

八、🎉 完成部署！#

✨ 恭喜！你的私有照片库已部署完成！

📱 现在可以：

在浏览器中创建管理员账户
下载手机 App 开启自动备份
享受完全私有的 Google Photos 体验！

💡 提示：首次使用建议先上传少量照片测试，确认功能正常后再进行批量导入。

九、💡 优化建议#

🎯 性能优化：

将 ./postgres数据库文件夹路径优先放在固态硬盘，./library 存放照片文件夹可以放在机械硬盘
根据硬件配置添加 GPU 加速（可选）

🔐 安全设置：

修改默认数据库密码
配置 HTTPS 访问
设置防火墙规则

十、🔧 Immich 常见问题解决代码指南#

🚫 端口 2283 被占用#

解决方法：修改端口映射

1
# 编辑 docker-compose.yml 文件vim docker-compose.yml

找到以下配置行：

1
# 原始配置ports:- '2283:2283'

修改为：

1
# 修改后配置（将主机端口改为 2284）ports:- '2284:2283'

保存后重启服务：

1
docker compose down
2
docker compose up -d

🔐 权限不足#

解决方法：设置存储目录权限

1
# 为 Immich 的存储目录设置适当权限sudo chmod 755 ./library
2

3
# 如果使用自定义存储路径，请相应修改路径# 例如：sudo chmod 755 /path/to/your/library
4
sudo chown -R $(whoami):$(whoami) ./library

❌ 启动失败#

解决方法：检查详细错误日志

1
# 查看所有服务的完整日志
2
docker compose logs
3

4
# 查看特定服务的日志
5
docker compose logs immich-server
6
docker compose logs database
7
docker compose logs redis
8

9
# 查看最近 50 行日志
10
docker compose logs --tail=50
11

12
# 实时追踪日志输出
13
docker compose logs -f
14

15
# 查看更早的日志（如果服务已停止）
16
docker compose logs --no-log-prefix

⏱️ 访问超时#

解决方法：检查防火墙设置，总有一个命令适合你

首先检查你的防火墙状态和工具#

在开始之前，先确认你的系统使用了哪种防火墙。

1
# 查看系统防火墙状态
2
sudo ufw status
3
sudo firewall-cmd --state
4
sudo iptables -L -n

根据你的系统选择合适的命令#

情况 A：如果你使用 UFW（Ubuntu/Debian 常见）#

1
# 开启 2283 端口
2
sudo ufw allow 2283/tcp
3

4
# 查看规则是否已添加
5
sudo ufw status
6

7
# 重新加载防火墙规则
8
sudo ufw reload

情况 B：如果你使用 Firewalld（CentOS/RHEL/Fedora 常见）#

1
# 永久开启 2283 端口
2
sudo firewall-cmd --zone=public --add-port=2283/tcp --permanent
3

4
# 重新加载防火墙规则
5
sudo firewall-cmd --reload
6

7
# 验证端口已开放
8
sudo firewall-cmd --zone=public --list-ports

情况 C：如果你使用 iptables（传统系统）#

1
# 允许 2283 端口的 TCP 流量
2
sudo iptables -A INPUT -p tcp --dport 2283 -j ACCEPT
3

4
# 保存规则（根据系统不同）# Ubuntu/Debian:
5
sudo iptables-save > /etc/iptables/rules.v4
6
# 或sudo netfilter-persistent save
7

8
# RHEL/CentOS 7+:
9
sudo service iptables save

验证端口是否已成功开放#

1
# 使用 netstat 检查端口监听状态
2
sudo netstat -tulpn | grep 2283
3

4
# 使用 ss 命令
5
sudo ss -tulpn | grep 2283
6

7
# 从本机测试端口连通性
8
telnet localhost 2283
9
# 或
10
nc -zv localhost 2283

如果你的 Immich 使用了非标准端口#

如果按照你之前提到的解决方案，已将端口从 2283 修改为 2284：

1
# 开放 2284 端口（UFW）sudo ufw allow 2284/tcp
2

3
# 开放 2284 端口（Firewalld）sudo firewall-cmd --zone=public --add-port=2284/tcp --permanent
4
sudo firewall-cmd --reload

1
# 检查 2283 端口是否开放sudo ufw status
2
# 或sudo firewall-cmd --list-ports
3

4
# 开放 2283 端口（Ubuntu/Debian）sudo ufw allow 2283/tcp
5
sudo ufw reload
6

7
# 开放 2283 端口（CentOS/RHEL/Fedora）sudo firewall-cmd --zone=public --add-port=2283/tcp --permanent
8
sudo firewall-cmd --reload
9

10
# 如果你修改了端口（如 2284），则开放对应端口sudo ufw allow 2284/tcp

音乐

音乐

🎉 前言！#

一、🎯 一键部署方案#

📥 方案一：从官方下载（推荐）#

⚡ 方案二：使用我的配置（复制粘贴）#

二、🚀 三步快速启动#

1️⃣ 基础配置#

2️⃣ 启动服务#

3️⃣ 访问验证#

三、⚡ 核心功能亮点#

四、🛠️ 常用管理命令#

五、🛠️ 简化管理命令-设置别名#

🎮 使用说明#

六、💡 验证是否生效#

七、🎯 Immich 初始化配置指南#

1️⃣ 访问注册页面#

2️⃣ 配置存储模板（关键步骤）#

八、🎉 完成部署！#

九、💡 优化建议#

十、🔧 Immich 常见问题解决代码指南#

🚫 端口 2283 被占用#

🔐 权限不足#

❌ 启动失败#

⏱️ 访问超时#

首先检查你的防火墙状态和工具#

根据你的系统选择合适的命令#

情况 A：如果你使用 UFW（Ubuntu/Debian 常见）#

情况 B：如果你使用 Firewalld（CentOS/RHEL/Fedora 常见）#

情况 C：如果你使用 iptables（传统系统）#

验证端口是否已成功开放#

如果你的 Immich 使用了非标准端口#

文章分享

评论区

音乐

音乐

Immich Docker Compose 部署教程｜私有云相册、手机照片视频自动备份、NAS 部署

🎉 前言！#

一、🎯 一键部署方案#

📥 方案一：从官方下载（推荐）#

⚡ 方案二：使用我的配置 （复制粘贴）#

二、🚀 三步快速启动#

1️⃣ 基础配置#

2️⃣ 启动服务#

3️⃣ 访问验证#

三、⚡ 核心功能亮点#

四、🛠️ 常用管理命令#

五、🛠️ 简化管理命令-设置别名#

🎮 使用说明#

六、💡 验证是否生效#

七、🎯 Immich 初始化配置指南#

1️⃣ 访问注册页面#

2️⃣ 配置存储模板（关键步骤）#

八、🎉 完成部署！#

九、💡 优化建议#

十、🔧 Immich 常见问题解决代码指南#

🚫 端口 2283 被占用#

🔐 权限不足#

❌ 启动失败#

⏱️ 访问超时#

首先检查你的防火墙状态和工具#

根据你的系统选择合适的命令#

情况 A：如果你使用 UFW（Ubuntu/Debian 常见）#

情况 B：如果你使用 Firewalld（CentOS/RHEL/Fedora 常见）#

情况 C：如果你使用 iptables（传统系统）#

验证端口是否已成功开放#

如果你的 Immich 使用了非标准端口#

文章分享

评论区

⚡ 方案二：使用我的配置（复制粘贴）#