使用docker-compose部署immich

你好我叫阿杰

563人浏览 · 2026-04-03 17:11:56

你好我叫阿杰 · 2026-04-03 17:11:56 发布

前言

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

PS：写于2026年4月3日，immich版本：v2.6.2
后续更新可能新增配置会不适用。

如果在任何步骤卡住，可以直接复制报错问AI。

如果不出意外的话，完成三步快速启动后就可以访问了。

为了照顾新手小白所以尽可能的多写点^^

作者：一个从坑里爬出来的技术爱好者

一、🎯 一键部署方案

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

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

# 创建部署目录
mkdir -p ./immich-app
cd ./immich-app

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

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

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

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

# 项目名称
name: immich

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

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

  # 缓存数据库
  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:9@sha256:3eeb09785cd61ec8e3be35f8804c8892080f3ca21934d628abc24ee4ed1698f6
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always

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

# 数据卷
volumes:
  model-cache:

二、🚀 三步快速启动

1️⃣ 基础配置

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

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

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

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

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

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

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

2️⃣ 启动服务

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

3️⃣ 访问验证

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

三、⚡ 核心功能亮点

✅ 自动备份 - 从手机自动同步照片
✅ 智能相册 - AI 自动整理分类
✅ 人脸识别 - 自动识别人物分组
✅ 隐私安全 - 数据完全自主掌控
✅ 跨平台 - 支持 Web/iOS/Android

四、🛠️ 常用管理命令

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

# 📈 查看服务状态
docker compose ps

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

# 🔄 重启服务
docker compose restart

# ⏹️ 停止服务
docker compose down

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

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

复制粘贴即可

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

🎮 使用说明

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

dps        # 原命令：docker compose ps
dlog       # 原命令：docker compose logs -f
drestart   # 原命令：docker compose restart
dstop      # 原命令：docker compose down
dup        # 原命令：docker compose up -d
dpull      # 原命令：docker compose pull
dupdate    # 原命令组合：docker compose pull && docker compose up -d

六、💡 验证是否生效

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

七、🎯 Immich 初始化配置指南

1️⃣ 访问注册页面

首先，在浏览器打开你部署的 Immich 地址（例如：你的服务器IP:2283），来到首次使用的注册页面。
在这里插入图片描述

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

注册登录后，进入设置 → 存储模板，这是最重要的配置项之一。
在这里插入图片描述

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

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

📁 格式说明：

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

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

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

完成初始化设置后点击右上角账号设置，把能用的功能都打开。
在这里插入图片描述

八、🎉 完成部署！

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

📱 现在可以：

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

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

九、💡 优化建议

🎯 性能优化：

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

🔐 安全设置：

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

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

1. 🚫 端口 2283 被占用

解决方法：修改端口映射

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

找到以下配置行：

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

修改为：

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

保存后重启服务：

docker compose down
docker compose up -d

2. 🔐 权限不足

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

# 为 Immich 的存储目录设置适当权限
sudo chmod 755 ./library
# 如果使用自定义存储路径，请相应修改路径
# 例如：sudo chmod 755 /path/to/your/library
sudo chown -R $(whoami):$(whoami) ./library

3. ❌ 启动失败

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

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

# 查看特定服务的日志
docker compose logs immich-server
docker compose logs database
docker compose logs redis

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

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

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

4. ⏱️ 访问超时

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

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

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

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

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

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

# 开启 2283 端口
sudo ufw allow 2283/tcp
# 查看规则是否已添加
sudo ufw status
# 重新加载防火墙规则
sudo ufw reload

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

# 永久开启 2283 端口
sudo firewall-cmd --zone=public --add-port=2283/tcp --permanent
# 重新加载防火墙规则
sudo firewall-cmd --reload
# 验证端口已开放
sudo firewall-cmd --zone=public --list-ports

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

# 允许 2283 端口的 TCP 流量
sudo iptables -A INPUT -p tcp --dport 2283 -j ACCEPT
# 保存规则（根据系统不同）
# Ubuntu/Debian: 
sudo iptables-save > /etc/iptables/rules.v4
# 或
sudo netfilter-persistent save
# RHEL/CentOS 7+: 
sudo service iptables save

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

# 使用 netstat 检查端口监听状态
sudo netstat -tulpn | grep 2283
# 使用 ss 命令
sudo ss -tulpn | grep 2283
# 从本机测试端口连通性
telnet localhost 2283
# 或
nc -zv localhost 2283

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

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

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