Immich：自托管高性能照片与视频管理系统全解——功能矩阵、演示环境与源码级部署指南（基于官方韩语 README）

Immich 是一个自托管（self-hosted）的高性能照片与视频管理解决方案，提供移动端自动备份、AI 驱动的多模态搜索（元数据 / 物体 / 人脸 / CLIP 语义检索）、相册与共享、人脸聚类、照片堆栈、"那年今天"（Memories）等完整图库能力。本文以 Immich 仓库官方韩语 README（readme_i18n/README_ko_KR.md）为主体骨架，完整继承其中的功能矩阵、演示环境与备份建议，并结合仓库内服务端控制器、枚举定义、部署配置与文档目录展开源码级佐证，读完你可以掌握 Immich 的完整功能版图、演示账号使用方式，以及如何基于仓库自带配置自行部署一套可用的实例。

图 1：Immich 官方主界面截图（来源：仓库 design/immich-screenshots.png，与韩语 README 中的主截图一致）

1. 项目定位与核心原则

1.1 一句话定位

韩语 README 将项目定位为"고성능 자체 호스팅 사진 및 동영상 관리 솔루션"，即高性能的自托管照片与视频管理方案（见 readme_i18n/README_ko_KR.md 第 14 行的标题说明）。"自托管"意味着服务器运行在你自己的硬件上（家用 NAS、虚拟机、树莓派等），数据主权完全归用户所有；"高性能"则体现在 Web 端与移动端对数万张照片的虚拟滚动渲染、服务端异步作业队列（ML 分析、转码等）设计上——仓库中 machine-learning/ 目录下的独立机器学习服务、server/src/workers/ 中的异步 worker，正是这一架构取向的体现。

1.2 官方备份警告（3-2-1 原则）

韩语 README 开头用 WARNING 级别的提示框明确提醒：

⚠️ 对于珍贵的照片和视频，请务必遵循 3-2-1 备份策略！

这一警告的逻辑在于：Immich 本身是一个图库 / 归档管理工具，其存储结构（默认按用户与年月组织文件，支持自定义存储模板）方便管理，但它不构成备份——原文件仍需保留在手机本地与至少一份离线介质上。仓库的部署文档同样延续这一原则，安装前置要求见 docs/docs/install/requirements.md，备份与恢复的官方做法见 docs/docs/administration/backup-and-restore.md。

1.3 多语言文档体系

Immich 的 README 被翻译成 20 种语言，统一存放在 readme_i18n/ 目录下（如 readme_i18n/README_ja_JP.md、readme_i18n/README_zh_CN.md 等），由根目录 README.md 的语言导航条互相跳转。韩语 README 即其中的 README_ko_KR.md，与英文版内容保持同步，是韩国用户理解 Immich 能力的第一入口。

2. 演示环境与演示账号

韩语 README 提供了官方演示环境的接入方式，这也是快速体验 Immich 全部功能的最短路径：

• Web 端：直接在浏览器访问演示站点 demo.immich.app；
• 移动端：安装 Immich 移动 App 后，在登录页的"服务器端点 URL"（Server Endpoint URL）字段中填写 https://demo.immich.app。

2.1 演示登录凭据

邮箱（E-mail）	密码（비밀번호）
[e-mail]	demo

使用演示账号可以完整体验功能矩阵（见下一节）中列出的所有能力，包括搜索、相册、人脸聚类结果与 Memories 等，无需自己部署即可评估是否适合自建。

3. 功能矩阵全解（移动端 × Web 端）

韩语 README 的核心内容是一张功能 × 端矩阵表。下表完整继承该表，并逐组给出仓库内的源码 / 文档佐证，方便读者自行深入验证。

功能	移动端	Web
上传与查看照片、视频	支持	支持
打开 App 时自动备份	支持	N/A
资产去重（防止内容重复）	支持	支持
为备份选择特定相册	支持	N/A
将照片、视频下载到本地设备	支持	支持
多用户支持	支持	支持
相册与共享相册	支持	支持
可拖动 / 可擦除（scrubbable）滚动条	支持	支持
RAW 格式支持	支持	支持
元数据查看（EXIF、地图）	支持	支持
按元数据、物体、人脸、CLIP 搜索	支持	支持
管理功能（用户管理）	不支持	支持
后台备份	支持	N/A
虚拟滚动	支持	支持
OAuth 支持	支持	支持
API 密钥	N/A	支持
Live Photo / Motion Photo 备份与播放	支持	支持
360 度全景图显示	不支持	支持
用户自定义存储结构	支持	支持
公开共享	不支持	支持
归档与收藏	支持	支持
全球地图	支持	支持
与搭档（Partner）共享	支持	支持
人脸识别与人脸聚类	支持	支持
回忆 / "X 年前今天"（Memories）	支持	支持
离线支持	支持	不支持
只读画廊（Read-only gallery）	支持	支持
照片堆栈（Stacked Photos）	支持	支持

说明：该矩阵以当前仓库中的韩语 README 为准；根目录英文版 README.md 在后续迭代中又补充了 Tags、Folder View 等行，阅读时可按仓库实际版本理解。

3.1 媒体上传、查看与去重

上传、查看与"防止资产重复"（콘텐츠 중복 방지）是图库系统的基石。服务端将每个资产的可见性建模为 server/src/enum.ts 中的 AssetVisibility 枚举：Archive（归档）、Timeline（时间线）、Hidden（隐藏——该值在注释中被明确说明用于 Live Photo / Motion Photo 的视频部分）、Locked（锁定）。这一枚举解释了功能表中"Live Photo 备份与播放"的实现细节：Live Photo 的视频分量作为一个独立资产存在，但被标记为 hidden，从而在时间线中不可见、却与主照片绑定播放。

RAW 格式支持则与移动端解码能力相关，移动端代码位于 mobile/lib/（其中 extensions/codec_extensions.dart 等模块处理视频 / 图像编解码），移动端能力矩阵中"打开 App 时自动备份""后台备份""相册选择备份"均标注为 Web 端 N/A——这些能力天然依赖手机系统的前台 / 后台任务机制，实现分布于 mobile/lib/services/ 与 mobile/lib/repositories/ 等目录，移动端备份的官方说明见 docs/docs/features/mobile-backup.md。

3.2 搜索：元数据、物体、人脸与 CLIP 四路检索

功能表中的"按元数据、物体、人脸、CLIP 搜索"对应服务端 server/src/controllers/search.controller.ts 的搜索接口体系，底层由独立的机器学习服务支撑。machine-learning/immich_ml/models/ 目录按模型类型组织：

• clip/ —— CLIP 语义检索（输入自然语言描述匹配图像）；
• facial_recognition/ —— 人脸检测与聚类（对应"人脸识别与聚类"行）；
• ocr/ —— OCR 文字识别。

多路检索的产品化行为（搜索框、过滤器、人脸搜索面板等）有专门文档：docs/docs/features/searching.md 与 docs/docs/features/facial-recognition.md；ML 服务的硬件加速部署（CUDA / ROCm 等）见 docs/docs/features/ml-hardware-acceleration.md，转码加速见 docs/docs/features/hardware-transcoding.md 与 docker/hwaccel.ml.yml、docker/hwaccel.transcoding.yml 两份示例片段。

3.3 照片堆栈（Stacked Photos）

"照片堆栈"允许把多张照片（典型场景：同一时刻的多张连拍 / 角度图）折叠为一个单元展示。服务端实现为独立的 NestJS 控制器 server/src/controllers/stack.controller.ts：

• GET /stacks 检索堆栈列表，POST /stacks 创建堆栈；
• 值得注意的合并语义（见 stack.controller.ts 的接口描述）：若传入的资产 ID 已是某个既有堆栈的主资产（primary asset），该既有堆栈会被合并进新创建的堆栈——这一设计避免了"同一张照片属于两个堆栈"的状态冲突；
• DELETE /stacks 支持按 ID 批量删除，整个堆栈 API 的稳定性标注为 v2 起 stable（HistoryBuilder().added('v1').beta('v1').stable('v2')）。

相关测试位于 server/test/ 的 medium 测试集中，OpenAPI 契约中同步暴露，见 open-api/immich-openapi-specs.json。

3.4 Memories："X 年前的今天"

"추억 (~년 전)"（回忆）功能按拍摄日期聚合历史同期照片（例如"3 年前的今天"）。服务端实现见 server/src/controllers/memory.controller.ts：

• GET /memories 默认按创建日期降序返回，也支持升序或随机排序（接口描述原文见 memory.controller.ts）；
• POST /memories 创建记忆（名称 + 描述 + 资产 ID 列表），GET /memories/statistics 提供统计（如总张数、覆盖年数），支撑 UI 上"X 年前 · N 张照片"的摘要展示。

3.5 归档、收藏与共享体系

• 归档与收藏（보관 및 즐겨찾기）：归档走 AssetVisibility.Archive 状态（见 3.1 的枚举），将资产移出时间线但保留可检索性；
• 相册与共享相册 / 只读画廊：共享链路文档见 docs/docs/features/sharing.md；"只读画廊"指共享链接中隐藏元数据、禁止下载的受限视图；
• 公开共享：韩语 README 矩阵中标注移动端"不支持 / Web 支持"，说明公开链接管理是 Web 管理台的能力；
• Partner Sharing（搭档共享）：双人互享、仅彼此可见的轻量协作模式，产品文档见 docs/docs/features/partner-sharing.md。

3.6 管理、OAuth 与 API 密钥

矩阵中三类"接入与安全"能力各有落点：

• 管理功能（用户管理）：仅 Web 端支持。从源码结构看，管理界面属于 Web 应用 web/src/routes/ 中的设置 / 管理区域，用户生命周期由服务端 user 相关控制器与服务承载，管理后台的文档入口见 docs/docs/administration/（如 system-settings.md、jobs-workers.md）；
• OAuth：移动端与 Web 均可用，允许以外部身份提供方（Keycloak、Google 等）登录，官方配置指南见 docs/docs/administration/oauth.md；服务端枚举中定义了令牌端点鉴权方式 client_secret_post / client_secret_basic（server/src/enum.ts）；
• API 密钥：仅 Web 端可申请，用于脚本 / CLI 访问。服务端入口是 server/src/controllers/api-key.controller.ts；配合 packages/cli/ 中的命令行工具，可对自托管实例做自动化上传与管理，CLI 用法见 docs/docs/features/command-line-interface.md，REST 契约的完整定义见 open-api/immich-openapi-specs.json。

3.7 自定义存储结构

"用户自定义存储结构"（사용자 정의 스토리지 구조）指服务端落盘目录模板（按用户 ID、年 / 月 / 日等占位符组织文件树）。服务端实现位于 server/src/services/storage-template.service.ts，产品配置文档见 docs/docs/administration/storage-template.mdx（文档中的占位符如 {y}、{MM} 即由此服务渲染）。

3.8 性能相关行：虚拟滚动与可拖动滚动条

"虚拟滚动"与"可拖动 / 可擦除滚动条"是 Immich 宣称"高性能"的直接体现：Web 端基于 SvelteKit（web/src/）仅渲染视口内的缩略图节点，移动端（Flutter，mobile/lib/）同理，配合可拖动定位的 scrub 滚动条，使用户在数十万级资产下仍可快速跳转年份。这两行在矩阵中同时标注移动端与 Web 支持，说明双端共享同一交互范式。

4. 仓库结构与部署方式

功能矩阵中每一项能力，在仓库中都有对应的模块落点，整体结构如下：

目录	职责
server/	NestJS 服务端：控制器（server/src/controllers/）、服务（server/src/services/）、SQL 查询（server/src/queries/）、PostgreSQL 模式（server/src/schema/）
machine-learning/	独立 ML 服务（FastAPI）：CLIP / 人脸 / OCR 模型，见 machine-learning/immich_ml/
web/	SvelteKit Web 应用（时间线、搜索、管理台、公开共享页）
mobile/	Flutter 移动端（自动 / 后台备份、离线浏览、Live Photo）
packages/	TypeScript 工作区包：cli/、sdk/、plugin-sdk/ 等
docker/	官方部署配置与示例环境文件
docs/	官方文档站源码（Docusaurus）
open-api/	OpenAPI 规范与移动端生成补丁
i18n/	客户端翻译 JSON（含 i18n/ko.json）

4.1 基于 Docker 部署（推荐）

仓库 docker/ 目录提供了开箱即用的编排文件：

• docker/docker-compose.yml —— 标准生产编排（server、machine-learning、database 三个核心服务）；
• docker/example.env —— 环境变量样例，复制为 .env 后按需修改；
• docker/hwaccel.transcoding.yml / docker/hwaccel.ml.yml —— GPU 硬件加速（转码 / ML 推理）的可选附加片段；
• docker/docker-compose.dev.yml、docker/docker-compose.rootless.yml —— 开发与无 root 场景变体。

部署流程的完整文档在 docs/docs/install/ 下：前置要求 requirements.md、一键脚本 one-click.md / script.md、compose 方式 docker-compose.mdx、Kubernetes kubernetes.md，以及 upgrading.md 与 post-install.mdx（升级与安装后注册管理员账号）。仓库根目录的 install.sh 即文档中提到的社区一键安装脚本本身。

适用前提：部署机需可运行 Docker；数据库（PostgreSQL）随 compose 编排提供，无需单独安装。生产建议遵循 docker/README.md 中的说明，并按 1.2 节的 3-2-1 原则保留独立备份。

4.2 文档站与 API 文档

• 文档站源码：docs/，侧边栏定义见 docs/sidebars.js；开发者视角的架构说明见 docs/docs/developer/architecture.mdx；
• REST API 规范：open-api/immich-openapi-specs.json，由服务端 @Endpoint 装饰器（如 stack.controller.ts 中所见）自动生成，API 文档入口见 docs/docs/api.md。

5. 翻译与社区参与

韩语 README 末段指向翻译体系：Immich 的客户端翻译采用社区协作模式，翻译指南见 docs/docs/developer/translations.md。仓库内的两条翻译线互相对应：

1. README 多语言版：readme_i18n/ 目录，本文章主体文档 README_ko_KR.md 即其一；
2. 客户端 UI 翻译：i18n/ 目录下的逐语言 JSON（如 i18n/ko.json），移动端与 Web 端共用键值体系，移动端侧有键一致性校验脚本 mobile/scripts/check_i18n_keys.py。

社区贡献入口（文档、代码、翻译）的说明见 CONTRIBUTING.md 与 docs/docs/developer/pr-checklist.md。

6. 关键文件索引

主题	路径
韩语 README（本文主体）	readme_i18n/README_ko_KR.md
英文主 README	README.md
主界面截图	design/immich-screenshots.png
生产编排 / 环境变量样例	docker/docker-compose.yml / docker/example.env
一键安装脚本	install.sh
搜索 / 人脸 / 相册 / 堆栈 / 记忆 API 规范	open-api/immich-openapi-specs.json
资产可见性枚举（Live Photo 视频隐藏机制）	server/src/enum.ts
堆栈控制器	server/src/controllers/stack.controller.ts
Memories 控制器	server/src/controllers/memory.controller.ts
API 密钥控制器	server/src/controllers/api-key.controller.ts
存储模板服务	server/src/services/storage-template.service.ts
ML 模型（CLIP / 人脸 / OCR）	machine-learning/immich_ml/models/
安装文档目录	docs/docs/install/
管理员指南目录	docs/docs/administration/
韩语 UI 翻译	i18n/ko.json