🚀 使用 Docker Compose 部署 Immich

一、项目简介

Immich 是一款开源免费的跨平台照片 / 视频管理工具，被称为 “私有版 Google Photos”，专注于本地数据存储与智能管理，支持照片自动分类、AI 人脸识别、地理标记、RAW 格式解析等功能，适合个人或家庭搭建私有媒体库，兼顾隐私安全与便捷管理。

核心特点：

隐私优先：数据存储在本地服务器，不依赖第三方云服务，避免照片泄露风险。
智能管理：内置 AI 模型（人脸识别、场景分类、物体识别），自动整理照片（如按人物、地点、时间分组）。
多格式支持：兼容 JPG、PNG、RAW（如 CR2、NEF）、视频（MP4、MOV）等主流媒体格式，支持 4K 视频存储与播放。
跨设备访问：提供 Web 界面、iOS/Android 客户端、桌面客户端，支持多设备同步与远程访问。
轻量化部署：基于 Docker 容器化架构，组件清晰（服务器、数据库、Redis、AI 模块），配置简单。
扩展性强：支持自定义存储路径、自动备份、共享相册等功能，可对接外部存储（如 NAS、S3 兼容对象存储）。

二、部署前准备

Immich 依赖 Docker 环境与特定目录存储媒体数据和数据库，需提前完成以下准备，避免启动失败或数据丢失：

1. 必备工具安装

Docker：用于运行 Immich 各组件容器（验证命令：docker --version，未安装可参考 Docker 官方文档）。
Docker Compose：用于编排多容器服务（验证命令：docker compose version，部分 Docker 版本已内置，未安装可参考 Docker Compose 安装文档）。

2. 本地镜像准备（关键！）

配置文件中使用的是 本地镜像 ID（如 79eeffe9d864、9852017fc0a2），需提前将这些镜像加载到 Docker 中（避免启动时因拉取不到镜像报错）： PS：没有网络会打不开，强制升级镜像，没有公网IP无法更新镜像的建议打包成镜像包和镜像ID来脱网使用。

# 假设本地镜像文件为 tar 包（如 immich-server.tar、immich-ml.tar 等），执行加载命令
docker load -i /path/to/immich-server.tar  # 对应镜像 ID 79eeffe9d864
docker load -i /path/to/immich-ml.tar      # 对应镜像 ID 9852017fc0a2
docker load -i /path/to/immich-redis.tar   # 对应镜像 ID f153d02a5c0e
docker load -i /path/to/immich-postgres.tar# 对应镜像 ID b193a13cbb23

# 加载后验证镜像是否存在（出现对应 ID 即成功）
docker images | grep -E "79eeffe9d864|9852017fc0a2|f153d02a5c0e|b193a13cbb23"

3. 目录与权限准备

Immich 需要两个核心目录：媒体存储目录（存放照片 / 视频）和 数据库目录（存储元数据），需提前创建并赋予读写权限（路径需与 .env 一致）：

# 1. 创建部署主目录（示例路径：/opt/immich，可自定义）
mkdir -p /opt/immich && cd /opt/immich

# 2. 创建媒体存储目录（对应 .env 中 UPLOAD_LOCATION）
mkdir -p /mnt/10t/file/Immich/Photos/{library,admin}
# - library：默认媒体存储目录（上传的照片/视频存于此）
# - admin：额外只读媒体目录（配置中挂载为 /admin:ro）

# 3. 创建数据库目录（对应 .env 中 DB_DATA_LOCATION）
mkdir -p /mnt/10t/file/Immich/Photos/postgres

# 4. 赋予目录最高权限（避免容器无法读写数据，新手推荐）
sudo chmod -R 777 /mnt/10t/file/Immich/Photos

4. 端口准备

Immich 通过 2283 端口提供 Web 服务与客户端连接，需确保服务器防火墙 / 安全组开放该端口：

Linux（UFW 防火墙）：sudo ufw allow 2283/tcp；
云服务器：在安全组添加 “允许 TCP 2283 端口入站” 规则。

三、配置 Docker Compose

Immich 部署依赖 docker-compose.yml（服务编排）与 .env（环境变量配置），需按步骤创建并核对关键参数：

1. 步骤 1：编写 docker-compose.yml 文件

在 /opt/immich 目录创建 docker-compose.yml，复制以下内容（关键配置已标注，与用户提供一致）：

# 编辑存储模板规则
#存储模板规则允许你定义文件的存储路径。下面是我推荐的存储模板规则：
#{{album}}/{{y}}/{{MM}}/{{filename}}
#这个规则将文件存储在以账号名称、年份、月份和原始文件名命名的目录结构中。

#
# WARNING: To install Immich, follow our guide: https://immich.app/docs/install/docker-compose
#
# Make sure to use the docker-compose.yml of the current release:
#
# https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
#
# The compose file on main may not be compatible with the latest release.

name: immich

services:
  immich-server:
    container_name: immich_server  # 服务器容器名
    #image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    #image: ghcr.io/immich-app/immich-server:release
    image: 79eeffe9d864  # 本地 Immich 服务器镜像 ID（需提前加载）
    # extends:
    #   file: hwaccel.transcoding.yml
    #   service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
    volumes:
      # Do not edit the next line. If you want to change the media storage location on your system, edit the value of UPLOAD_LOCATION in the .env file
      - /etc/localtime:/etc/localtime:ro  # 同步宿主机时区
      - ${UPLOAD_LOCATION}:/usr/src/app/upload  # 媒体存储目录（从 .env 读取路径）
      - /mnt/10t/file/Immich/Photos/admin:/admin:ro  # 额外只读媒体目录（ro=只读）
      #都在env文件里面了。
      #- /mnt/10t/jiedian2/admin:/mnt/10t/jiedian2/admin:ro  不需要只读，可删可看好。
      #- /mnt/10t/jiedian2/12301654:/mnt/10t/jiedian2/12301654

    env_file:
      - .env  # 加载环境变量配置
    ports:
      - '2283:2283'  # 端口映射：主机 2283 → 容器 2283（核心访问端口）
    depends_on:
      - redis  # 依赖 Redis 服务（启动顺序：先启 Redis/数据库）
      - database
    restart: always  # 容器退出后自动重启
    healthcheck:
      disable: false  # 启用健康检查

  immich-machine-learning:
    container_name: immich_machine_learning  # AI 模块容器名
    # For hardware acceleration, add one of -[armnn, cuda, rocm, openvino, rknn] to the image tag.
    # Example tag: ${IMMICH_VERSION:-release}-cuda
    #image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    #image: ghcr.io/immich-app/immich-machine-learning:release
    image: 9852017fc0a2  # 本地 AI 模型镜像 ID（需提前加载）

    # extends: # uncomment this section for hardware acceleration - see https://immich.app/docs/features/ml-hardware-acceleration
    #   file: hwaccel.ml.yml
    #   service: cpu # set to one of [armnn, cuda, rocm, openvino, openvino-wsl, rknn] for accelerated inference - use the `-wsl` version for WSL2 where applicable
    volumes:
      - model-cache:/cache  # 挂载 AI 模型缓存卷（避免重复下载）
    env_file:
      - .env
    #ports:
      #- 3003:3003
    restart: always
    healthcheck:
      disable: false

  redis:
    container_name: immich_redis  # Redis 容器名（用于缓存）
    #image: docker.io/valkey/valkey:8-bookworm@sha256:fec42f399876eb6faf9e008570597741c87ff7662a54185593e74b09ce83d177
    #image: redis:6.2-alpine
    #image: valkey/valkey
    image: f153d02a5c0e  # 本地 Redis 镜像 ID（需提前加载）
    healthcheck:
      test: redis-cli ping || exit 1   # 健康检查：测试 Redis 连接
    restart: always

  database:
    container_name: immich_postgres  # 数据库容器名（PostgreSQL + 向量扩展）
    #image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    # 本地数据库镜像 ID（需提前加载）
    image: b193a13cbb23 #直接调用ID了，加载本地压缩的镜像名不靠谱#tensorchord/pgvecto-rs

    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}  # 数据库密码（从 .env 读取）
      POSTGRES_USER: ${DB_USERNAME}     # 数据库用户名（默认 postgres）
      POSTGRES_DB: ${DB_DATABASE_NAME}  # 数据库名（默认 immich）
      POSTGRES_INITDB_ARGS: '--data-checksums'  # 启用数据校验（防 corruption）
      # Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
      # DB_STORAGE_TYPE: 'HDD'
    volumes:
      # Do not edit the next line. If you want to change the database storage location on your system, edit the value of DB_DATA_LOCATION in the .env file
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data  # 数据库存储目录（从 .env 读取）
    restart: always

volumes:
  model-cache:   # 全局卷：AI 模型缓存（跨容器复用，避免重启后重新下载）

2. 步骤 2：编写 .env 环境变量文件

在 /opt/immich 目录创建 .env，复制以下内容（关键参数需核对，与用户提供一致）：

ini

# You can find documentation for all the supported env variables at https://immich.app/docs/install/environment-variables

# The location where your uploaded files are stored
#UPLOAD_LOCATION=./library
UPLOAD_LOCATION=/mnt/10t/file/Immich/Photos/library  # 媒体存储目录（照片/视频存储路径，与目录准备一致）

# The location where your database files are stored. Network shares are not supported for the database
#DB_DATA_LOCATION=./postgres
DB_DATA_LOCATION=/mnt/10t/file/Immich/Photos/postgres  # 数据库存储目录（PostgreSQL 数据路径，与目录准备一致）

# To set a timezone, uncomment the next line and change Etc/UTC to a TZ identifier from this list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
# TZ=Etc/UTC
TZ=Asia/Shanghai    # 时区（确保时间显示正确，亚洲上海）

# The Immich version to use. You can pin this to a specific version like "v1.71.0"
IMMICH_VERSION=release  # Immich 版本（默认 release，即稳定版）

# Connection secret for postgres. You should change it to a random password
# Please use only the characters `A-Za-z0-9`, without special characters or spaces
#DB_PASSWORD=postgres
# 数据库密码（关键！需修改为强密码，仅含字母数字，无特殊字符）
DB_PASSWORD=BaLt42Ncd7s3XX6 #修改为安全的随机密码。

# The values below this line do not need to be changed
###################################################################################
# 以下参数无需修改（默认配置）
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

3. 配置项关键说明（新手必看）

配置项	作用与注意事项
镜像 ID（如 `79eeffe9d864`）	必须提前通过 `docker load` 加载本地镜像，否则启动会报错 “no such image”。
`UPLOAD_LOCATION`	媒体文件核心存储目录，删除或误改会导致照片丢失，务必与实际目录一致。
`DB_PASSWORD`	数据库密码需为强密码（仅字母 + 数字），若含特殊字符（如 `!@#`）会导致数据库启动失败。
`volumes: /admin:ro`	`ro` 表示只读，容器无法修改该目录文件（适合存放无需编辑的旧照片库）。
`model-cache` 卷	AI 模型缓存卷（约数百 MB），避免每次重启容器重新下载模型，节省带宽。

四、启动与验证

1. 启动 Immich 服务

在 /opt/immich 目录执行以下命令，启动所有组件（首次启动需初始化数据库，耗时 1-3 分钟）：

bash

docker compose up -d

2. 验证部署状态

（1）检查容器是否正常运行

执行命令，若所有容器的 State 均为 Up，说明启动成功：

bash

docker compose ps

若部分容器状态为 Exited，执行以下命令查看错误日志（核心排查方法）：

bash

```bash

查看指定容器日志（如数据库容器）

docker compose logs -f database

或查看所有容器日志

docker compose logs ```
- 常见错误：DB_PASSWORD 含特殊字符（需修改为纯字母数字）、目录权限不足（执行 sudo chmod -R 777 /mnt/10t/file/Immich/Photos）、镜像未加载（重新执行 docker load）。

（2）访问 Immich Web 界面

打开浏览器，输入 http://服务器IP:2283（如 http://192.168.1.100:2283）；
首次访问会进入登录页面，使用默认管理员账号登录：
- 邮箱：admin@immich.app；
- 密码：immich（首次登录后需立即修改，保障安全）；
成功进入主界面（显示 “相册”“上传” 等功能），说明部署成功。

五、基础配置与使用

1. 首次使用：修改管理员密码

登录后点击右上角头像 →「Account Settings」（账户设置）；
在「Change Password」栏输入旧密码（immich）和新密码（强密码，如 Immich@2024!）；
点击「Save」，下次登录需使用新密码。

2. 上传照片 / 视频（核心功能）

（1）Web 界面上传

点击左侧「Upload」→「Select Files」，选择本地照片 / 视频；
（可选）勾选「Album」创建相册（如 “2024 旅行”），将上传文件归类；
点击「Upload」，进度条完成后，照片会显示在「All Photos」（所有照片）中。

（2）客户端上传（推荐）

在手机应用商店搜索「Immich」，下载 iOS/Android 客户端；
打开客户端，输入服务器地址（http://服务器IP:2283）、管理员邮箱和新密码，完成登录；
进入「设置」→「自动上传」，开启 “后台自动上传”，手机照片会自动同步到服务器。

3. 启用 AI 功能（人脸识别 / 分类）

AI 功能默认启用，需等待模型加载完成（首次启动可能需要几分钟）：

上传一批含人脸的照片，Immich 会自动识别并分组（在「People」标签页查看）；
点击「Search」（搜索），可通过关键词（如 “风景”“猫”）查找相关照片，AI 会自动匹配内容。

4. 访问只读媒体目录（/admin）

配置中挂载的 /mnt/10t/file/Immich/Photos/admin 目录，可在 Web 界面通过「Library」→「Add Library」→ 选择「/admin」添加，添加后可查看该目录的照片，但无法修改或删除（只读权限）。

六、维护与管理

1. 容器基础操作

操作需求	命令	说明
停止 Immich 服务	`docker compose down`	停止所有容器，数据保存在挂载目录中
重启 Immich 服务	`docker compose restart`	配置修改后需执行，确保新配置生效
查看实时日志（排错）	`docker compose logs -f immich_server`	查看服务器运行日志（如上传失败原因）
进入数据库容器（进阶）	`docker exec -it immich_postgres psql -U postgres -d immich`	管理数据库（需数据库密码）

2. 数据备份（核心！防止照片丢失）

Immich 数据分为两部分，需分别备份：

（1）媒体数据备份（照片 / 视频）

bash

# 打包备份媒体目录（文件名含日期，耗时较长，需预留空间）
tar -czf immich-media-backup-$(date +%Y%m%d).tar.gz /mnt/10t/file/Immich/Photos/library

（2）数据库备份（元数据：相册、标签、人脸信息）

bash

# 备份 PostgreSQL 数据库（输出为 sql 文件）
docker exec immich_postgres pg_dump -U postgres -d immich > immich-db-backup-$(date +%Y%m%d).sql

3. 更新 Immich 版本

若有新的本地镜像，需先停止旧服务，加载新镜像后重启：

bash

# 1. 停止旧服务
docker compose down

# 2. 加载新镜像（假设新镜像文件为 new-immich-server.tar）
docker load -i /path/to/new-immich-server.tar

# 3. 修改 docker-compose.yml 中的镜像 ID 为新 ID
# 4. 启动新服务
docker compose up -d

4. 清理无用数据（释放空间）

清理缓存：AI 模型缓存（model-cache 卷）若过大，可删除后重启容器（会重新下载模型）：

bash

bash docker volume rm immich_model-cache docker compose up -d
删除旧照片：在 Web 界面或客户端删除无用照片，服务器会自动清理对应文件（需在「设置」中确认 “删除文件时同时删除原始文件” 已开启）。

七、常见问题排查

1. 登录提示 “无效的邮箱或密码”

原因 1：默认密码输入错误（首次登录密码为 immich，不是 .env 中的 DB_PASSWORD）。

解决：确认输入密码为 immich，登录后立即修改为新密码。 - 原因 2：数据库未初始化完成（首次启动需 1-3 分钟）。

解决：等待几分钟后重新尝试登录，或查看数据库日志确认是否正常。

2. 上传照片失败（提示 “权限被拒绝”）

原因：UPLOAD_LOCATION 目录权限不足，容器无法写入文件。
解决：执行 sudo chmod -R 777 /mnt/10t/file/Immich/Photos/library，赋予最大权限，重新上传。

3. AI 功能不工作（无人脸识别 / 分类）

原因 1：AI 模型未加载完成（首次启动需下载模型，约数百 MB）。

解决：等待 5-10 分钟，查看 AI 容器日志确认模型加载状态：docker compose logs -f immich_machine_learning。 - 原因 2：model-cache 卷挂载异常。

解决：删除缓存卷并重启：docker volume rm immich_model-cache && docker compose up -d。

4. 客户端无法连接服务器

原因 1：2283 端口未开放或被占用。

解决：检查端口占用 netstat -tuln | grep 2283，释放端口或修改 docker-compose.yml 中的端口（如 2284:2283），重启服务。 - 原因 2：服务器 IP 或端口输入错误（客户端配置中）。

解决：确认客户端输入的服务器地址为 http://服务器IP:2283（无 HTTPS，若配置了 HTTPS 需改为 https）。

5. 数据库启动失败（日志提示 “password authentication failed”）

原因：.env 中 DB_PASSWORD 与容器内配置不一致（如修改 .env 后未重启数据库）。
解决：停止服务后删除数据库目录（rm -rf /mnt/10t/file/Immich/Photos/postgres/*），重新启动（会重新初始化数据库，需重新上传照片，谨慎操作！）。

通过以上步骤，新手可快速搭建 Immich 私有照片管理系统，实现照片的安全存储与智能管理。如需更高级的功能（如 HTTPS 加密、共享相册、外部存储对接），可参考 Immich 官方文档进一步探索。

🚀 使用 Docker Compose 部署 Immich

一、项目简介

二、部署前准备

1. 必备工具安装

2. 本地镜像准备（关键！）

3. 目录与权限准备

4. 端口准备

三、配置 Docker Compose

1. 步骤 1：编写 docker-compose.yml 文件

2. 步骤 2：编写 .env 环境变量文件

3. 配置项关键说明（新手必看）

四、启动与验证

1. 启动 Immich 服务

2. 验证部署状态

（1）检查容器是否正常运行

查看指定容器日志（如数据库容器）

或查看所有容器日志

（2）访问 Immich Web 界面

五、基础配置与使用

1. 首次使用：修改管理员密码

2. 上传照片 / 视频（核心功能）

（1）Web 界面上传

（2）客户端上传（推荐）

3. 启用 AI 功能（人脸识别 / 分类）

4. 访问只读媒体目录（/admin）

六、维护与管理

1. 容器基础操作

2. 数据备份（核心！防止照片丢失）

（1）媒体数据备份（照片 / 视频）

（2）数据库备份（元数据：相册、标签、人脸信息）

3. 更新 Immich 版本

4. 清理无用数据（释放空间）

七、常见问题排查

1. 登录提示 “无效的邮箱或密码”

2. 上传照片失败（提示 “权限被拒绝”）

3. AI 功能不工作（无人脸识别 / 分类）

4. 客户端无法连接服务器

5. 数据库启动失败（日志提示 “password authentication failed”）