Immich 自托管照片视频管理方案：功能体系、部署配置与源码实现解析

Immich 是一个高性能的自托管（self-hosted）照片与视频备份管理解决方案，提供移动端与 Web 端双客户端，支持自动备份、多用户、智能搜索与人脸识别等能力。本文基于仓库中的土耳其语项目介绍文档 readme_i18n/README_tr_TR.md 展开，完整继承其功能特性矩阵与演示信息，并结合 install.sh、docker/docker-compose.yml 以及 server/src/services 下的服务端源码，讲清 Immich 的部署方式、运行要求、功能边界与底层实现依据，帮助你评估、部署并深入理解这套方案。

项目定位与核心主张

土耳其语 README 将 Immich 定义为“Yüksek performanslı, kendine ait barındırılan fotoğraf ve video yedekleme çözümü”（高性能的自托管照片与视频备份解决方案）。这一定位包含三层含义：

1. 自托管（self-hosted）：所有照片、视频与元数据存储在用户自己的服务器与磁盘上，官方提供 Docker Compose 部署方式与一键安装脚本，数据归属完全由用户掌控；
2. 备份（backup）：移动端应用打开时自动备份、支持后台备份与按相册选择性备份，是移动设备照片的主要备份目标；
3. 高性能：服务端基于 NestJS（TypeScript）实现，数据库为带向量扩展的 PostgreSQL，配合虚拟滚动、缩略图生成与视频转码等机制支撑大体量图库的流畅浏览。

文档同时给出两条重要提醒：

• 3-2-1 备份策略警告：对珍贵的照片与视频，应始终遵循 3-2-1 备份方案（3 份数据、2 种介质、1 份异地）。Immich 作为自托管系统，本身是 3-2-1 中的“一份”，不能替代完整备份体系；
• 官方文档入口：包括安装指南在内的正式文档以仓库内的 docs/ 目录为准，例如 安装要求、环境变量说明、Docker Compose 安装。

部署：从一键脚本到 Compose 文件

一键安装脚本

仓库根目录的 install.sh 是最简部署入口，其主流程（见 install.sh 起）为：

1. 在当前目录创建 ./immich-app 目录（若已存在则覆盖其中的 YAML 文件）；
2. 下载 docker-compose.yml 与 .env 文件（.env 源自仓库中的 docker/example.env）；
3. 为 .env 中的 DB_PASSWORD 生成随机密码（先尝试 sha256sum | base64，失败时退化为拼接 $RANDOM）；
4. 执行 docker compose up --remove-orphans -d 启动容器，成功后打印访问地址 http://<IP>:2283，并提示后续修改 .env 的标准流程：docker compose down → 修改 .env → docker compose up --remove-orphans -d。

脚本要求系统已安装 docker compose（V2 Compose 插件，而非已弃用的 docker-compose）与 curl。

Compose 四容器架构

docker/docker-compose.yml 定义了生产部署的完整拓扑，共 4 个服务加 1 个模型缓存卷：

服务	镜像	作用与关键点
immich-server	ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}	主服务，暴露端口 2283:2283；将 ${UPLOAD_LOCATION} 挂载到容器内 /data，依赖 redis 与 database（见 docker-compose.yml）
immich-machine-learning	ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}	机器学习容器，负责 CLIP、人脸识别与 OCR 推理；挂载命名卷 model-cache:/cache 用于缓存模型权重（见 docker-compose.yml）
redis	docker.io/valkey/valkey:9（固定摘要）	缓存与队列，健康检查为 redis-cli ping
database	ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0（固定摘要）	内置向量扩展的 PostgreSQL 14；POSTGRES_INITDB_ARGS: '--data-checksums' 开启数据校验，shm_size: 128mb（见 docker-compose.yml）

两个值得注意的工程细节：

• 硬件加速是可选扩展：server 与 machine-learning 两个服务都预留了 extends 注释位，分别指向 docker/hwaccel.transcoding.yml（转码加速：nvenc、quicksync、rkmpp、vaapi 等）与 docker/hwaccel.ml.yml（推理加速：armnn、cuda、rocm、openvino、rknn 等），对应官方文档 ML 硬件加速 与 硬件转码；
• Compose 文件须与发布版本匹配：文件头注释明确提醒 main 分支的 docker-compose.yml 可能与最新 release 不兼容，应从对应 release 下载。

关键环境变量

docker/example.env 暴露了安装后必须理解的核心配置：

# 上传文件的存储位置（照片视频本体、缩略图等）
UPLOAD_LOCATION=./library

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

# 时区（可选，TZ 标识符）
# TZ=Etc/UTC

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

# PostgreSQL 连接口令，应改为随机密码，仅限 A-Za-z0-9
DB_PASSWORD=postgres

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

配合 docs/docs/install/environment-variables.md，可以看到这两个位置变量（UPLOAD_LOCATION、DB_DATA_LOCATION）与 Compose 文件中的挂载行一一对应：修改挂载位置的正确方式是改 .env 而不是改 Compose 的 volumes 行。

硬件与软件要求

来自 docs/docs/install/requirements.md 的官方要求，是部署前必须核对的清单：

硬件

• 操作系统：推荐 Linux 或 *nix 64 位系统（Ubuntu、Debian 等）；非 Linux 平台的 Docker 体验较差，官方明确不推荐，且支持能力有限；
• 内存：最低 6GB，推荐 8GB。仅 4GB 内存的机器可以禁用机器学习功能运行；
• CPU：最低 2 核，推荐 4 核；支持 amd64 与 arm64。自 v3 起，amd64 平台的 ML 容器要求 >= x86-64-v2 微架构（约 2012 年后的大多数 CPU 满足）；不支持该指令集的 CPU 只能停留在不再受支持的 v2.7.5；
• 存储：推荐支持用户/组权限的 Unix 文件系统（EXT4、ZFS、APFS 等）；缩略图与转码视频平均会使图库体积增加 10-20%；
• Postgres 数据库文件：通常为 1-3GB，DB_DATA_LOCATION 应使用本地 SSD，绝不使用任何网络共享；若使用 Docker 资源限制，Postgres 至少需要 2GB 内存。

软件

• Docker Engine（Linux/WSL2）或 Docker Desktop（Windows/macOS），必须带 Compose 插件；
• 必须使用 docker compose 命令，旧版 docker-compose 已弃用，不再受 Immich 支持。

Windows 用户的特例：Postgres 数据必须落在支持属主/权限的文件系统上，NTFS/exFAT/WSL 挂载目录均不可用；可将 .env 中 DB_DATA_LOCATION=./postgres 改为 DB_DATA_LOCATION=pgdata，并在 Compose 底部 volumes: 下追加 pgdata: 改用 Docker 命名卷。

在线 Demo 与登录凭据

README（含土耳其语版本）提供了官方演示环境，便于在部署前体验完整功能：

Demo 访问地址: https://demo.immich.app

登录凭据:
email:    [e-mail]
password: demo

移动端应用接入 Demo 时，将 Server Endpoint URL 一项填写为 https://demo.immich.app 即可登录同一演示实例。这为评估搜索、相册、地图等 Web/移动端功能提供了零成本途径。

功能特性矩阵

以下表格完整继承自土耳其语 README 的功能矩阵（Mobile/Web 双端支持情况），是了解 Immich 功能边界的权威清单：

功能	Mobile	Web
上传并查看视频与照片	支持	支持
应用打开时自动备份	支持	N/A
可选定相册进行备份	支持	N/A
将照片与视频下载到本地设备	支持	支持
多用户支持	支持	支持
相册与共享相册	支持	支持
可删除/可拖动的滚动条	支持	支持
RAW 格式支持（HEIC、HEIF、DNG、Apple ProRaw）	支持	支持
元数据视图（EXIF、地图）	支持	支持
按元数据、物体、人脸与 CLIP 搜索	支持	支持
管理功能（用户管理）	不支持	支持
后台备份	支持	N/A
虚拟滚动	支持	支持
OAuth 支持	支持	支持
API 密钥	N/A	支持
LivePhoto 备份与播放	iOS	支持
用户自定义存储结构	支持	支持
公开分享	不支持	支持
归档与收藏夹	支持	支持
世界地图	不支持	支持
伙伴分享（Partner Sharing）	支持	支持
人脸识别与聚类	不支持	支持
离线支持	支持	不支持

对照英文主 README.md 的功能表可以看到，当前主干版本还新增了若干特性：资产去重（Prevent duplication of assets）、360 度全景图显示、Memories（多年前的今天）、只读图库、堆叠照片（Stacked Photos）、标签（Tags）与文件夹视图（Folder View），且“公开分享”“全球地图”“人脸识别”“LivePhoto 播放”在英文表中已标注为双端或部分支持——说明土耳其语译版相对主干略滞后，实际功能应以 README.md 与 docs/docs/features/ 目录（如 标签、文件夹视图、人脸聚类、搜索）为准。

关键功能的源码实现印证

以下各节从服务端源码验证上表中最具工程含量的几项功能，全部证据来自 server/src/services 下的 NestJS 服务层。

用户自定义存储结构

“用户自定义存储结构”由 server/src/services/storage-template.service.ts 实现。该服务基于 Handlebars 模板引擎渲染资产的落盘路径，内置 21 个预设模板（storage-template.service.ts），例如：

{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}
{{y}}/{{#if album}}{{album}}{{else}}Other/{{MM}}{{/if}}/{{filename}}
{{make}}/{{model}}/{{lensModel}}/{{filename}}

支持的日期与相机元数据 token 包括：y/yy（年）、M/MM/MMM/MMMM（月）、d/dd（日）、W/WW（周）、h/hh/H/HH（时）、m/mm（分）、s/ss/SSS（秒），以及 album、album-startDate-y、make、model、lensModel、filename、assetId 等字段（见 storage-template.service.ts）。

从源码结构看，模板在 ConfigInit / ConfigUpdate 事件时编译并缓存（onConfigInit），ConfigValidate 事件会用一个模拟资产（/upload/test/IMG_123.jpg）试渲染来校验模板合法性——这意味着在管理端保存模板前，服务端会先做“干跑”验证，非法模板不会直接生效。渲染时文件名还会经过 sanitize-filename 清洗。官方文档 存储模板 给出了更多配置示例。

多维度搜索

“按元数据、物体、人脸与 CLIP 搜索”对应 server/src/services/search.service.ts。该服务对外暴露的方法覆盖矩阵中提到的全部搜索维度：

• searchPerson：按人名查找人脸聚类（personRepository.getByName，支持 withHidden 隐藏人员参数）；
• searchPlaces：按地名搜索（searchRepository.searchPlaces）；
• searchMetadata：按 EXIF/元数据条件组合检索，支持按 checksum（28 位 base64 或 hex）精确定位资产，并通过 albumIds 与共享链接（shared link）访问控制做权限收敛；
• getExploreData：探索视图，聚合“最多城市”与“最近添加”两组数据（maxFields: 12, minAssetsPerField: 5）；
• 语义搜索依赖 SmartSearchDto 与 isSmartSearchEnabled 开关，并将 CLIP 文本向量结果放入一个容量 100 的 LRU 缓存（embeddingCache）以减少对 ML 服务的重复请求。

CLIP 向量之所以能落库查询，与 Compose 中数据库镜像自带 vectorchord + pgvectors 扩展直接对应；语义侧的推理模型位于 machine-learning/immich_ml/models/clip 目录。

人脸识别与聚类

矩阵中“人脸识别与聚类（Web 支持）”由 server/src/services/person.service.ts 的服务端部分与 ML 容器协同完成：人脸特征提取在 machine-learning 容器的 facial_recognition 模型 中执行，服务端负责聚类分组、命名与展示，对应文档 更好的面孔聚类 与 人脸识别。

转码、HLS 与后台任务

Web 端流畅播放视频依赖服务端转码：server/src/services/transcoding.service.ts 管理转码作业，hls.service.ts 提供 HLS 分片播放流，queue.service.ts 负责后台任务队列调度（与 redis 容器配合），job.service.ts 管理任务状态。这也解释了为什么 Compose 中 server 容器依赖 redis——缩略图生成、转码、缩略图清理等都走异步队列。

API 密钥与多用户

矩阵中“API 密钥（仅 Web 支持）”由 server/src/services/api-key.service.ts 实现，配合 docs/docs/features/command-line-interface.md 中提到的 CLI（packages/cli），允许用户用个人密钥以编程方式访问自己的数据（例如脚本化上传，见 docs/docs/guides/python-file-upload.md）。多用户与认证由 auth.service.ts、user-admin.service.ts 等承担，OAuth 配置见 docs/docs/administration/oauth.md。

翻译生态与本文档的位置

土耳其语 README 是 Immich 官方翻译体系的一部分：

• readme_i18n/ 目录存放 22 个语言的 README 译本（README_tr_TR.md 即其一），由根 README.md 的语言导航入口统一链接；
• 产品界面翻译由仓库根 i18n/ 目录维护，覆盖 100+ 语言文件（如 i18n/tr.json、i18n/en.json）；
• 翻译贡献流程见 docs/docs/developer/translations.md。

这也意味着：阅读土耳其语文档的社区成员与英文社区获得的是同一份功能与版本语义，翻译版本仅存在措辞层面的滞后。

备份策略提醒与总结

Immich 的 README 反复强调 3-2-1 备份原则：自托管服务器只是备份链中的一环，重要照片视频仍应保持多份、多介质、异地的完整策略。仓库内 docs/docs/administration/backup-and-restore.md 也提供了服务端自身的备份与恢复指导。

综合来看，Immich 的技术形态可以概括为：

• 部署侧：4 容器 Compose 架构（server + machine-learning + redis + 向量版 Postgres），一键脚本 install.sh 完成初始化，UPLOAD_LOCATION/DB_DATA_LOCATION 双位置变量掌控全部数据落盘；
• 功能侧：以移动端自动备份为入口，Web 端承载管理、分享与高级检索，功能矩阵中“N/A/不支持”的边界（如移动端的 API 密钥、Web 端的后台备份）清晰明确；
• 实现侧：NestJS 服务层 + Handlebars 存储模板 + 向量数据库搜索 + 异步任务队列，各功能点均可在 server/src/services/ 中找到对应实现，ML 能力独立容器化并支持多种硬件加速后端。

对于需要完全掌握自己照片数据、又希望获得接近云端相册体验（智能搜索、人脸聚类、地图、分享）的自托管用户，这套“Docker 部署 + 移动/Web 双端 + 可插拔 ML 加速”的架构是完整可复现的方案。