Immich 自托管照片与视频管理系统：能力全景与源码实现对照

本文基于 Immich 仓库的俄语版主 README（readme_i18n/README_ru_RU.md）展开，完整继承其中的项目定位、演示环境说明、移动端/Web 端功能矩阵与翻译机制，并结合当前仓库的服务端、机器学习与移动端源码逐项印证每项能力的落地实现，帮助你在评估或部署这套自托管照片/视频管理系统之前，建立从功能到代码路径的完整认知。

项目定位与总体说明

README 对 Immich 的一句话定义是：高性能的自托管（self-hosted）照片与视频存储、分组与管理方案。仓库根目录的 README.md 与俄语版内容一致，项目采用 AGPL v3 许可证，并配套官方文档站（仓库内 docs/docs/ 目录即文档源文件）。

官方 README 中有两条明确的运维提示，部署前务必注意：

1. 3-2-1 备份原则：官方用 WARNING 级别强调，珍贵的照片和视频应始终遵循 3-2-1 备份策略（3 份副本、2 种介质、1 份异地）。自托管意味着数据主权归你，但同时也意味着备份责任归你；
2. 安装指引以官方文档为准：README 将具体安装步骤指向文档站的安装章节，对应仓库内的 docs/docs/install/requirements.md、docs/docs/install/docker-compose.mdx 等文件。

从仓库目录结构看，整个系统由四个可独立运行的组件构成，这也解释了 README 中"高性能"的来源——它是前后端分离 + 独立 ML 推理服务的架构：

组件	仓库路径	职责
服务端 API	server/	NestJS 后端，含 82 个控制器、100+ 个服务，负责资产管理、鉴权、分享、任务调度
机器学习服务	machine-learning/	独立的 Python 推理服务，内置 CLIP、人脸识别、OCR 三类模型
移动端 App	mobile/	Flutter 客户端，含备份、下载、小组件等原生能力
Web 前端	web/	SvelteKit 应用，面向管理员与日常浏览

演示环境与体验凭据

README 提供了一个可在线体验的演示实例。在移动端应用中，将 Server Endpoint URL（服务器地址）一栏填写为 https://demo.immich.app，然后使用以下账号登录：

邮箱	密码
[e-mail]	demo

这个演示环境是验证下文功能矩阵最快速的方式——无需自行部署，即可看到人脸分组、时间轴、地图等功能在真实数据上的表现。若要本地部署，仓库内 docker/docker-compose.yml 与 docker/example.env 给出了标准编排：immich-server（端口 2283）、immich-machine-learning、valkey（Redis 兼容）与 postgres（内置向量扩展的定制镜像）四个容器。docker/example.env 中的关键变量为：

# 上传文件（照片/视频原件）的存储位置
UPLOAD_LOCATION=./library

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

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

# postgres 连接密码，官方建议更换为仅含 A-Za-z0-9 的随机密码
DB_PASSWORD=postgres

注意 compose 文件头部的注释强调：生产部署应使用当前 release 版本发布的 compose 文件，main 分支上的 compose 可能与最新 release 不兼容。

完整功能矩阵：移动端 vs Web 端

以下表格完整继承自 README 的功能清单，逐项标注移动端（App）与 Web 端的支持情况：

功能	移动端	Web 端
上传、查看视频与照片	支持	支持
打开应用时自动备份	支持	不适用
防止资产重复	支持	支持
选择指定相册进行备份	支持	不适用
将照片/视频下载到本地设备	支持	支持
多用户账号支持	支持	支持
相册与共享相册	支持	支持
可拖拽滚动的时间轴滚动条	支持	支持
RAW 格式支持	支持	支持
元数据查看（EXIF、地图）	支持	支持
按元数据、物体、人脸与 CLIP 语义搜索	支持	支持
管理功能（用户管理）	不支持	支持
后台备份	支持	不适用
虚拟滚动	支持	支持
OAuth 支持	支持	支持
API 密钥	不适用	支持
LivePhoto / MotionPhoto 备份与播放	支持	支持
360° 全景图展示	不支持	支持
用户自定义存储结构	支持	支持
公开分享	支持	支持
归档与收藏	支持	支持
全球地图	支持	支持
合作者共享（Partner Sharing）	支持	支持
人脸识别与聚类分组	支持	支持
回忆（X 年前的今天）	支持	支持
离线支持	支持	不支持
只读画廊	支持	支持
堆叠照片/拼贴	支持	支持
标签（Tags）	不支持	支持
文件夹视图	支持	支持

可以归纳出分工边界：移动端独占的能力集中在"采集与备份"侧（自动备份、后台备份、相册选择性备份、离线支持），Web 端独占的能力集中在"管理"侧（用户管理、API 密钥、360° 展示、标签），其余核心浏览与检索能力两端齐备。

能力到源码：关键功能的实现印证

下面选取功能矩阵中技术含量最高的几项，对照当前仓库源码说明其实际落地位置，便于阅读代码或二次开发时快速定位。

上传、备份与去重

移动端侧，mobile/lib/services/ 下提供了完整的备份基础设施：background_upload.service.dart 与 foreground_upload.service.dart 分别对应上表"后台备份"与"打开应用时自动备份"，download.service.dart 负责下载到本地设备。服务端侧，同步与去重的入口在 server/src/services/sync.service.ts（对应 sync.controller.ts 暴露的同步接口），重复检测则由 server/src/services/duplicate.service.ts 承担——README 中"防止资产重复"在 Web 端同样支持，对应管理界面中的重复资产管理入口。

搜索：元数据 + 人脸 + CLIP 语义检索

这是 Immich 最核心的差异化能力。README 将其概括为"按元数据、物体、人脸与 CLIP 搜索"。从源码结构看，检索的统一入口是 server/src/services/search.service.ts（SearchService，见该文件 L35），而真正执行跨模态检索的模型在独立的 ML 服务中：

• machine-learning/immich_ml/models/clip/ —— CLIP 零样本图像/文本嵌入，支撑"按自然语言搜图"；
• machine-learning/immich_ml/models/facial_recognition/ —— 人脸检测与特征提取；
• machine-learning/immich_ml/models/ocr/ —— 图片内文字识别。

ML 服务通过 machine-learning/immich_ml/sessions/ort.py 基于 ONNX Runtime 加载模型，docker/docker-compose.yml 的注释说明可通过修改镜像标签追加 -cuda、-rocm、-openvino、-rknn、-armnn 等后缀启用硬件加速，仓库同时提供了 docker/hwaccel.ml.yml 与 docker/hwaccel.transcoding.yml 两个加速编排模板。

人脸识别与聚类分组

App 与 Web 均支持的"人脸识别与聚类"，在服务端由 server/src/services/person.service.ts（PersonService，L52）管理人物（Person/Face）实体与分组关系，配合 person.controller.ts 对外提供接口；聚类计算依赖 ML 服务产出的人脸向量，再由服务端数据库聚合。

分享体系：相册、公开链接与合作者共享

功能表中"公开分享"与"合作者共享"是两个独立能力，分别对应：

• server/src/services/album.service.ts：私有与共享相册；
• server/src/services/shared-link.service.ts：基于链接的公开分享，支撑"只读画廊"场景；
• server/src/services/partner.service.ts：合作者（Partner）共享，允许在保持各自账号独立的前提下共享特定内容。

记忆、地图与标签

• 回忆（X 年前的今天）：server/src/services/memory.service.ts（MemoryService，L16）按拍摄日期检索历史同期素材；
• 全球地图：server/src/services/map.service.ts 提供按地理位置查询素材的接口，移动端地图能力见 mobile/lib/services/map.service.dart；
• 标签：server/src/services/tag.service.ts（TagService，L24）——功能表中明确标注仅 Web 端支持。

管理、鉴权与 API 密钥

功能表中"管理功能（用户管理）"仅 Web 端支持，对应 server/src/controllers/ 下的管理端控制器（user-admin.controller.ts、auth-admin.controller.ts、config-admin.controller.ts 等，均带 -admin 后缀标识权限边界）。鉴权侧，auth.service.ts 处理常规登录，oauth.controller.ts 支撑 OAuth，api-key.service.ts 为 Web 端提供 API 密钥管理，供脚本或第三方程序调用 OpenAPI（规范文件见 open-api/immich-openapi-specs.json）。

多语言支持：从 i18n 目录到翻译流程

本文所依据的俄语版 README 本身即是 Immich 多语言实践的一部分——仓库 readme_i18n/ 目录下维护着 20 个语言的 README 译本（西班牙语、法语、日语、中文简体/繁体、乌克兰语等），而主 README 通过语言徽章导航到各译本。

项目级国际化则集中在 i18n/ 目录：当前仓库包含 89 个语言的 JSON 翻译文件（从 af.json 阿法尔语到 zh_Hant.json 繁体中文），这些文件被移动端（Flutter 本地化）与 Web 端（SvelteKit 国际化）共同消费。移动端 App 名称字符串的资源打包见 mobile/assets/ 与各平台 manifest，而 mobile/scripts/check_i18n_keys.py 提供了 i18n key 一致性校验脚本，可用于发现缺失或多余的翻译键。

翻译协作流程在文档站有专门页面（对应 docs/docs/developer/translations.md），README 中附带的 Weblate 徽章即指向该协作平台。若你希望贡献新语言，基本路径是：在 Weblate 上完成翻译后，合入结果以 JSON 文件形式落地到 i18n/ 目录。

小结

Immich 的 README 以功能矩阵为核心契约：备份与采集能力沉在 Flutter 移动端的原生服务层，管理与检索能力沉在 NestJS 服务端加独立 ONNX 推理服务的组合中，四容器 Docker 编排（server / machine-learning / valkey / postgres）把这套架构收敛为可一键自托管的部署单元。对自托管用户而言，建议先通过演示实例验证功能契合度，再按 docker/example.env 固化存储位置与版本策略，并牢记 README 反复强调的一点——自托管解决的是数据主权问题，而数据安全仍取决于你是否执行了 3-2-1 备份。