项目介绍
Immich 管理照片与视频并支持移动端上传。部署相册前最重要的是原文件和数据库的备份规划,缩略图与识别能力可在基本流程稳定后启用。
手机上传与服务端索引共同形成时间轴,机器学习组件再提供人物和语义检索。原始照片、数据库与缩略图承担不同角色,备份时需分清。
适合集中管理家庭照片并保持手机上传习惯。首次导入应先小批量测试,确认拍摄时间、重复文件和账号权限。
核心功能
| 功能 | 作用与使用方式 |
|---|---|
| 自动上传 | 按手机相册设置备份范围 |
| 时间轴 | 按拍摄日期浏览 |
| 相册分享 | 组织照片并设置访问 |
| 人物与检索 | 使用对应机器学习能力 |
| 外部图库 | 按版本管理已有照片 |
功能示意

图 1:自制功能示意图,概括本文的使用要点。

项目信息
| 项目 | 说明 |
|---|---|
| 类型 | Docker |
| 分类 | 软件与创作 |
| 项目仓库 | immich-app/immich |
| 官方入口或文档 | 直接访问 |
| 整理日期 | 2026-11-14 |
安装或使用条件
准备支持 Docker Compose 的主机、空闲端口与持久化目录。群晖可使用 Container Manager 的项目功能;示例目录以 /volume1/docker 为基准,其他存储卷需要自行替换。
安装与使用步骤
- 建立独立项目目录,先保存当前发行版的 Compose 与环境模板,核对同一个发行版的文档。数据库目录必须位于本地支持的文件系统,不能放在 SMB 网络挂载中。
- 根据下面环境表创建
.env,设置实际媒体路径、数据库路径与长随机密码。检查docker compose config --quiet通过后再启动完整服务栈。 - 打开
http://NAS_IP:2283,创建管理员,再创建普通测试账号。先上传十几张测试照片,检查时间、原件下载、缩略图和重复处理。 - 在手机端连接同一地址,测试自动备份和后台权限。确认备份完成后也不要立即删除手机唯一副本,先检查原文件和独立 NAS 备份。
- 需要硬件加速时使用同发行版的加速配置文件,不把别的版本 GPU 示例拼进现有 Compose。
环境文件 .env
在 Compose 同目录保存:
路径已写入 Compose;数据库账号和随机密码由下方准备命令生成。
IMMICH_VERSION=v3 来自本次获取的官方环境模板,部署前应与所选发行版保持一致。更换主版本不能只修改这个变量。示例已给出群晖绝对路径,密码由准备命令自动生成。
首次使用与操作检查
用几十张含不同日期的视频照片测试上传,核对时间、定位和播放。确认手机后台上传和重复处理后再迁移全部资料。
升级使用同版本官方配置并阅读迁移说明。备份后在独立位置恢复核对原文件与相册记录,不把缩略图目录当作原片备份。
Docker Compose
采用本次从 Immich 最新发行版下载的完整配置,保留匹配的应用、机器学习、Valkey 与带向量扩展的 PostgreSQL 镜像。以下用于新建实例;已有旧实例升级必须先按相应版本迁移说明处理,不能直接替换数据库组件。
群晖目录准备
在群晖 SSH 终端执行下面这一段,再将下方配置保存为 /volume1/docker/immich/compose.yaml。也可在 Container Manager 中新建项目,选择该目录并粘贴配置。
sudo sh <<'HALO_PREPARE'
set -eu
mkdir -p /volume1/docker/immich /volume1/docker/immich/postgres /volume1/photos/immich
cd /volume1/docker/immich
umask 077
touch .env
if ! grep -q "^DB_PASSWORD=." .env; then
generated_secret=$(openssl rand -hex 32)
printf 'DB_PASSWORD=%s\n' "$generated_secret" >> .env
fi
if ! grep -q "^DB_USERNAME=." .env; then printf 'DB_USERNAME=postgres\n' >> .env; fi
if ! grep -q "^DB_DATABASE_NAME=." .env; then printf 'DB_DATABASE_NAME=immich\n' >> .env; fi
if ! grep -q "^IMMICH_VERSION=." .env; then printf 'IMMICH_VERSION=v3\n' >> .env; fi
chmod 600 .env
HALO_PREPARE
cd /volume1/docker/immich
所需密码和密钥已自动生成到项目目录的 .env,已有非空值会保留。查看初始化密码可在自己的终端执行 sudo cat /volume1/docker/immich/.env;该文件只保留在本机。
配置中的命名卷由 Docker 创建并管理,不需要手动填写 UID/GID。备份时同时保存这些数据卷,不能只备份项目目录。
#
# WARNING: To install Immich, follow our guide: https://docs.immich.app/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}
# extends:
# file: hwaccel.transcoding.yml
# service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
volumes:
- /volume1/photos/immich:/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
# 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}
# extends: # uncomment this section for hardware acceleration - see https://docs.immich.app/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
env_file:
- .env
environment:
MACHINE_LEARNING_MODEL_REVISION: v2
restart: always
healthcheck:
disable: false
redis:
container_name: immich_redis
image: docker.io/valkey/valkey:9@sha256:418652cfb58ef879d4978c33553735d7147016032d5aefaa14c828e611eb9dfd
healthcheck:
test: redis-cli ping | grep -q PONG || 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: postgres
POSTGRES_DB: immich
POSTGRES_INITDB_ARGS: '--data-checksums'
# Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
# DB_STORAGE_TYPE: 'HDD'
volumes:
- /volume1/docker/immich/postgres:/var/lib/postgresql/data
shm_size: 128mb
restart: always
healthcheck:
disable: false
volumes:
model-cache:
在项目目录保存为 compose.yaml 后,先检查配置,再启动:
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100
配置与常见问题
- 原件目录与数据库缺一不可,机器学习模型缓存不能替代照片备份。
- 首次批量生成缩略图和索引可能占用较多 CPU、内存和磁盘,先小规模确认容量。
- 家庭共享与账号权限需要分别测试,管理员看到所有数据不代表普通账号也应看到。
- 页面无法打开:先用
docker compose ps检查状态,再核对宿主机端口、NAS 防火墙与应用日志。不要把容器端口随意改成另一个数字。 - 文件无法保存:核对宿主目录是否存在、挂载方向及运行用户的读写权限。不要直接给整个存储卷开放所有权限。
更新与备份
同时备份原始媒体、数据库和环境配置,做一次独立恢复验证。
更新前保留原配置和数据备份,阅读所用版本的升级说明;确认兼容后再执行 docker compose pull 和 docker compose up -d。只回退镜像不一定能回退已经迁移过的数据库。