Immich 自托管照片与视频管理方案：架构解析、Docker 部署与功能全景

Immich 是一个高性能的自托管（self-hosted）照片与视频管理方案，本文基于仓库根目录 README 展开，结合 docker/ 部署配置、docs/docs/ 官方文档与 server/、machine-learning/ 等源码实现，完整讲解 Immich 的部署方式、核心环境变量、后台服务架构与全量功能矩阵。读完本文，你将能够独立完成 Immich 的 Docker 部署与参数配置，并理解其四大容器（server、machine-learning、redis、postgres）之间的协作原理。

一、项目定位与核心特性

README 将 Immich 定义为 "High performance self-hosted photo and video management solution"（高性能自托管照片与视频管理方案），采用 AGPL v3 开源协议。其核心能力包括：多用户支持、相册与共享相册、基于元数据/物体/人脸/CLIP 的智能搜索、人脸识别与聚类、LivePhoto 备份与回放、公开分享、合作伙伴共享（Partner Sharing）、堆叠照片、全局地图、用户自定义存储结构、OAuth 与 API Keys 等。

来自 README 的重要提醒：请务必遵循 3-2-1 备份策略（3 份数据副本、2 种不同介质、1 份异地）来保护你珍贵的照片和视频，自托管不等于免备份。

Immich 提供三类客户端，全部基于仓库中 open-api/immich-openapi-specs.json 自动生成的 REST 客户端：

1. 移动端 App（Android / iOS，Dart + Flutter 编写，代码位于 mobile/lib）；
2. Web 端（响应式网站，TypeScript + SvelteKit，代码位于 web/src）；
3. CLI 命令行工具（npm 包，主要用于批量上传，代码位于 packages/cli）。

二、系统架构：四大容器与请求链路

Immich 采用经典的客户端—服务端设计，使用专用数据库做持久化，前端通过 REST API 与后端通信。官方架构图见 docs/docs/developer/img/app-architecture.webp（图文版说明在 架构文档）。

从 docker/docker-compose.yml 可以确认，一次标准部署会启动四个容器，其职责分工为：

容器	镜像	职责
immich_server	ghcr.io/immich-app/immich-server	处理 REST API 请求、执行后台任务（缩略图、元数据提取、转码等）
immich_machine_learning	ghcr.io/immich-app/immich-machine-learning	运行机器学习模型（人脸识别、CLIP 智能搜索、OCR）
immich_redis	valkey/valkey:9（Redis 协议）	后台任务的队列管理（基于 BullMQ）
immich_postgres	ghcr.io/immich-app/postgres:14-vectorchord...	持久化数据（用户、相册、资产、共享设置等）

关键协作机制（依据 架构文档）：

• 服务端分层：immich-server 是 TypeScript + Node.js 项目，基于 Nest.js 框架与 Kysely 查询构建器，代码位于 server/src，并按"六边形架构"将技术实现（src/repositories）与核心业务逻辑（src/services）分离。
• 后台作业（Background Jobs）：缩略图生成、元数据提取、视频转码、智能搜索、人脸识别、存储模板迁移、XMP Sidecar 处理、文件/用户删除等任务，通过 Redis 队列分发给 worker 执行。部分作业会链式触发后续作业——例如智能搜索和人脸识别依赖缩略图先生成完毕。
• 机器学习独立容器：ML 服务用 Python + FastAPI 编写（machine-learning/immich_ml），所有模型采用 ONNX 格式并缓存复用；将其独立成容器的目的是便于部署在独立机器上（如 GPU 主机）或直接禁用。
• 数据库选型细节：Postgres 定制镜像同时内置 VectorChord 与 pgvector 扩展，用于 CLIP 向量检索；未显式指定 DB_VECTOR_EXTENSION 时，服务端启动会自动检测，优先级为 VectorChord > pgvector。

三、部署快速上手

3.1 硬件与软件要求

依据 安装要求文档：

• 操作系统：推荐 64 位 Linux/*nix（Ubuntu、Debian 等）；Windows 需 WSL 2 或 Docker Desktop，macOS 用 Docker Desktop；
• 内存：最低 6GB，推荐 8GB（仅 4GB 时建议禁用机器学习功能运行）；
• CPU：最低 2 核，推荐 4 核；支持 amd64 与 arm64。注意自 v3 起，amd64 平台的机器学习容器要求 >= x86-64-v2 微架构级别（约 2012 年后的 CPU 均可满足）；
• 存储：推荐支持用户/组权限的 Unix 文件系统（EXT4、ZFS、APFS 等）。缩略图与转码视频平均会使媒体库体积增加 10–20%；
• 软件：必须安装 Docker 及 Docker Compose 插件，且必须使用 docker compose 命令（旧的 docker-compose 已不受支持）。

3.2 使用 install.sh 一键部署

仓库根目录提供了一键安装脚本 install.sh，其执行流程为：

1. 创建 ./immich-app 目录（已存在则覆盖其中的 YAML 文件）；
2. 从最新发布版下载 docker-compose.yml 与 example.env（重命名为 .env）；
3. 用 sha256sum | base64 生成随机密码，替换 .env 中默认的 DB_PASSWORD=postgres；
4. 执行 docker compose up --remove-orphans -d 启动容器，并打印访问地址 http://<本机IP>:2283。

脚本还给出了标准的后续配置三步法：先 docker compose down 停容器 → 修改 .env → 再 docker compose up --remove-orphans -d 恢复容器。

3.3 手动使用 Docker Compose 部署

Docker Compose 是官方推荐的生产部署方式（详见 Docker Compose 安装文档）。注意：应使用当前 release 发布版附带的 docker-compose.yml（随 release 资产一起发布），main 分支上的 compose 文件可能与最新 release 不兼容——docker/README.md 对此有专门警告。

仓库中的 docker/docker-compose.yml 关键结构如下（节选）：

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    # 硬件加速转码时取消注释，service 可设为 nvenc/quicksync/rkmpp/vaapi/vaapi-wsl
    # extends:
    #   file: hwaccel.transcoding.yml
    #   service: cpu
    volumes:
      # 修改媒体存储位置请改 .env 中的 UPLOAD_LOCATION，不要直接改这行
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    ports:
      - '2283:2283'
    depends_on: [redis, database]
    restart: always

  immich-machine-learning:
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    # 硬件加速推理：在镜像 tag 后追加 -[armnn, cuda, rocm, openvino, rknn]
    # 例如 ${IMMICH_VERSION:-release}-cuda
    volumes:
      - model-cache:/cache   # 模型缓存卷，跨容器重启复用已下载模型
    env_file:
      - .env
    restart: always

  redis:
    image: docker.io/valkey/valkey:9@sha256:...  # 带固定摘要的 Valkey 9
    healthcheck:
      test: redis-cli ping | grep -q PONG || exit 1

  database:
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:...
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
      # 数据库不在 SSD 上时取消注释：DB_STORAGE_TYPE: 'HDD'
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    shm_size: 128mb

volumes:
  model-cache:

两个值得注意的实现细节：

• 镜像摘要锁定：Redis 与 Postgres 镜像均带 @sha256: 内容摘要锁定，保证部署的数据库/队列版本可复现；Postgres 为 Immich 定制镜像（内置向量扩展）。
• 硬件加速：compose 文件默认以 CPU 模式运行。需要 GPU 加速转码时，将 extends 指向 docker/hwaccel.transcoding.yml（可选 nvenc、quicksync、rkmpp、vaapi、vaapi-wsl）；ML 推理加速则通过 docker/hwaccel.ml.yml 或在镜像 tag 后追加 -cuda、-rocm、-openvino、-armnn、-rknn 实现。

四、关键环境变量与配置

docs/docs/install/environment-variables.md 给出了完整的环境变量参考，此处结合 docker/example.env 讲解部署时最需要关注的变量。

重要：修改环境变量后必须重建容器（docker compose up -d）才生效，仅重启容器不会刷新环境；若不生效可用 docker compose up -d --force-recreate 强制重建。

4.1 Compose 层变量（由 docker-compose.yml 消费）

变量	说明	默认值	生效容器
IMMICH_VERSION	镜像 tag，可固定为具体版本如 v2.1.0	v3	server、machine learning
UPLOAD_LOCATION	上传文件的宿主机路径	（必填）	server
DB_DATA_LOCATION	Postgres 数据库文件的宿主机路径，不支持网络共享	（必填）	database

4.2 example.env 中的核心配置

# 上传文件存储位置
UPLOAD_LOCATION=./library

# 数据库文件存储位置（不支持网络共享）
DB_DATA_LOCATION=./postgres

# 时区：取消注释并改为 TZ 标识符，例如 Asia/Shanghai
# TZ=Etc/UTC

# Immich 版本，可固定为具体版本如 "v2.1.0"
IMMICH_VERSION=v3

# Postgres 连接密码，只允许 A-Za-z0-9，务必改为随机值
DB_PASSWORD=postgres

# 以下无需修改
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

4.3 常用运维变量（节选自官方文档）

变量	说明	默认值
TZ	时区，作为 EXIF 时区兜底、日志时间戳与 cron 执行依据	—
IMMICH_LOG_LEVEL	日志级别（verbose/debug/log/warn/error）	log
IMMICH_LOG_FORMAT	日志格式（console/json）	console
IMMICH_MEDIA_LOCATION	容器内媒体路径，不要改（应改用 UPLOAD_LOCATION）	/data
CPU_CORES	供 Immich 服务器使用的核心数	自动检测
IMMICH_PORT / IMMICH_HOST	监听端口/地址（server 与 ML 各一份）	2283 / 3003；0.0.0.0
IMMICH_WORKERS_INCLUDE / IMMICH_WORKERS_EXCLUDE	只运行/排除运行指定 worker	—
DB_STORAGE_TYPE	按存储介质优化 Postgres 并发/顺序 IO（SSD/HDD）	SSD
DB_URL	直连数据库 URL（设置后 DB_HOSTNAME 等五个变量被忽略）	—
DB_SKIP_MIGRATIONS	启动时是否跳过数据库迁移	false
REDIS_HOSTNAME / REDIS_PORT	Redis 连接地址	redis / 6379
IMMICH_ALLOW_SETUP	为 false 时禁用管理员注册与数据库恢复端点	true

两条来自文档的实用提示：DB_STORAGE_TYPE: 'HDD' 会通过切换 Postgres 的 effective_io_concurrency 相关配置，让数据库在机械盘上走顺序 IO；Postgres 库文件通常只有 1–3 GB，强烈建议放在本地 SSD 上且绝不使用网络共享，若使用 Docker 资源限额则数据库至少需要 2GB 内存。

五、完整功能矩阵（README 原版）

以下功能矩阵完整继承自 README，标明各功能在移动端（Mobile）与 Web 端的可用性：

Features	Mobile	Web
Upload and view videos and photos	Yes	Yes
Auto backup when the app is opened	Yes	N/A
Prevent duplication of assets	Yes	Yes
Selective album(s) for backup	Yes	N/A
Download photos and videos to local device	Yes	Yes
Multi-user support	Yes	Yes
Album and Shared albums	Yes	Yes
Scrubbable/draggable scrollbar	Yes	Yes
Support raw formats	Yes	Yes
Metadata view (EXIF, map)	Yes	Yes
Search by metadata, objects, faces, and CLIP	Yes	Yes
Administrative functions (user management)	No	Yes
Background backup	Yes	N/A
Virtual scroll	Yes	Yes
OAuth support	Yes	Yes
API Keys	N/A	Yes
LivePhoto/MotionPhoto backup and playback	Yes	Yes
Support 360 degree image display	No	Yes
User-defined storage structure	Yes	Yes
Public Sharing	Yes	Yes
Archive and Favorites	Yes	Yes
Global Map	Yes	Yes
Partner Sharing	Yes	Yes
Facial recognition and clustering	Yes	Yes
Memories (x years ago)	Yes	Yes
Offline support	Yes	No
Read-only gallery	Yes	Yes
Stacked Photos	Yes	Yes
Tags	No	Yes
Folder View	Yes	Yes

六、Demo 环境与试用

项目提供了公开 Demo 实例，移动端 App 可直接将 Server Endpoint URL 配置为 https://demo.immich.app 体验。

登录凭据

Email	Password
[e-mail]	demo

七、翻译与国际化

Immich 的界面翻译基于社区协作（Weblate 托管），仓库内 i18n/ 目录收录了约 85 种语言/地区的翻译文件（如 zh_Hans.json、de.json、ja.json、ru.json 等）。项目自身的 README 也提供了 20 种语言版本，位于 readme_i18n/ 目录（含 简体中文版、繁体中文版）。翻译机制的完整说明见 翻译文档。

八、深入仓库：继续探索的路标

方向	入口路径	说明
服务端 API 与业务逻辑	server/src/controllers、server/src/services	Nest.js 控制器按资源类型组织 CRUD 端点，DTO 与 OpenAPI schema 对应
OpenAPI 规范	open-api/immich-openapi-specs.json	三端客户端代码均由此自动生成
机器学习服务	machine-learning/immich_ml	模型（CLIP、人脸识别、OCR）与会话实现（ort/rknn）
移动端 App	mobile/lib	Flutter 应用，drift 本地数据库 + Riverpod 状态管理
Web 前端	web/src	SvelteKit + Tailwind CSS
端到端测试	e2e/src	覆盖 server、web、maintenance 三大模块
部署与文档	docs/docs/install、docker/	安装、环境变量、升级（upgrading.md）、安装后步骤（post-install.mdx）

九、总结

Immich 以一个 Docker Compose 编排即可完整落地：immich-server 承担 API 与后台作业，immich-machine-learning 独立处理 ONNX 模型推理，Valkey 负责任务队列，定制版 Postgres 持久化数据与向量检索。部署时抓住三个要点即可：使用 release 版 compose 文件、修改 .env 后必须重建容器、数据库目录务必使用本地 SSD。在此之上，通过 UPLOAD_LOCATION、IMMICH_VERSION、硬件加速 extends 文件与 worker 包含/排除变量，可以按硬件条件与使用规模灵活裁剪这套自托管照片视频管理系统。