Immich 自托管照片与视频管理：功能矩阵、快速安装与部署配置详解

本文以 Immich 仓库的官方 README（含瑞典语翻译版 readme_i18n/README_sv_SE.md）为主体，系统梳理 Immich 这个高性能自托管照片/视频管理方案的功能全景、官方 Demo 体验方式，并结合仓库中真实的安装脚本、Docker Compose 编排与 .env 配置示例，讲清楚从零部署到硬件加速的完整实操路径与底层架构映射。

Immich 是什么

Immich 定位为“高性能自托管照片与视频管理解决方案”（High performance self-hosted photo and video management solution），以 AGPLv3 协议开源。它由 Web 端、移动端（Android/iOS）、服务端与机器学习服务共同组成，提供自动备份、人脸识别、语义搜索、共享相册等能力，目标是让用户在自有服务器上拥有完整的数据主权。

README 首页有两条官方提示值得牢记：

• 备份警示：官方反复强调必须遵循 3-2-1 备份策略来保护珍贵的照片和视频（3 份数据、2 种介质、1 份异地），自托管不等于免备份；
• 文档指引：完整的官方文档与安装指南托管在官方站点（immich.app 与 docs.immich.app），仓库内 docs/ 目录也收录了对应的安装、管理、特性与开发文档。

此外，README 本身支持多语言：readme_i18n/ 下维护着 20 个语言的翻译版 README，其中就包括本文所基于的瑞典语版（README_sv_SE.md）；而面向应用界面的国际化翻译则位于 i18n/ 目录，包含 89 个语言的 JSON 翻译文件（如 en.json、zh_Hans.json、sv.json 等）。README 末尾还包含贡献者图谱、Star 历史与仓库活跃度等社区统计入口，以及一个可在各语言版本间跳转的语言切换列表。

功能全景：移动端与 Web 端能力矩阵

README 中最核心的技术内容是功能特性矩阵，它明确标注了每项能力在 Mobile 与 Web 两种客户端上的支持情况，是评估部署价值的第一手依据：

功能	移动端	Web 端
上传并查看视频与照片	支持	支持
打开 App 时自动备份	支持	不适用
防止资源（照片/视频）重复	支持	支持
可选择性指定相册进行备份	支持	不适用
将照片/视频下载到本地设备	支持	支持
多用户支持	支持	支持
相册与共享相册	支持	支持
可拖动/可擦洗的滚动条	支持	支持
RAW 格式支持	支持	支持
元数据查看（EXIF、地图）	支持	支持
按元数据、物体、人脸与 CLIP 语义搜索	支持	支持
管理功能（用户管理）	不支持	支持
后台备份	支持	不适用
虚拟滚动（大量资产流畅浏览）	支持	支持
OAuth 登录支持	支持	支持
API 密钥	不适用	支持
LivePhoto/MotionPhoto 备份与播放	支持	支持
360 度全景图像显示	不支持	支持
用户自定义存储结构	支持	支持
公开分享	支持	支持
归档与收藏	支持	支持
世界地图（按地理位置浏览）	支持	支持
伙伴共享（Partner Sharing）	支持	支持
人脸识别与人脸聚类	支持	支持
记忆（“x 年前”回顾）	支持	支持
离线支持	支持	不支持
只读画廊	支持	支持
图像堆叠（Stacked Photos）	支持	支持
标签（Tags）	不支持	支持
文件夹视图（Folder View）	支持	支持

注：上表以 readme_i18n/README_sv_SE.md 的瑞典语功能矩阵为准，并补入当前主干英文版 README.md 中新增的 Tags 与 Folder View 两行（瑞典语译本略滞后于主干）。“公开分享”在主干英文版中已同时支持移动端与 Web 端，实际以最新发行版为准。

矩阵中的几项高级能力直接对应 machine-learning/ 子项目的模型实现：

• “按 CLIP 语义搜索”对应 machine-learning/immich_ml/models/clip/ 下的 CLIP 模型（支持文本搜图，如“海边的日落”）；
• “人脸识别与聚类”对应 machine-learning/immich_ml/models/facial_recognition/；
• OCR 能力（文档/照片内文字识别）对应 machine-learning/immich_ml/models/ocr/。

官方 Demo：动手体验 Immich

README 提供了可直接试玩的在线演示环境，无需自行部署即可先感受产品形态：

• 在移动端 App 中，将 Server Endpoint URL 设置为 demo.immich.app（完整地址为 https://demo.immich.app）；
• 使用以下凭据登录：

邮箱	密码
[e-mail]	demo

这也可以作为验证你自建服务连通性的参照：如果自建实例登录流程与 Demo 行为不一致，可按 docs/docs/install/post-install.mdx 排查。

快速安装：一键脚本原理与流程

仓库根目录的 install.sh 实现了“一键部署”，阅读其 main() 流程（install.sh#L73-L102）可以清楚看到它只做了五件事：

1. 创建目录：在当前目录创建 ./immich-app 子目录，若已存在则复用并覆盖其中的 YAML 文件；
2. 下载编排文件：从最新 release 下载 docker-compose.yml 到该目录（强调：安装应使用当前 release 的编排文件，主干 main 上的 compose 文件可能与最新发行版不兼容，这一警告同样写在 docker/docker-compose.yml 头部注释中）；
3. 下载并生成 .env：将 example.env 下载为 .env，并通过 sha256sum | base64 生成随机密码替换默认的 DB_PASSWORD；
4. 启动容器：执行 docker compose up --remove-orphans -d；
5. 输出访问提示：自动探测主机 IP（macOS 上回退到 ipconfig getifaddr en0），提示你通过 http://<IP>:2283 访问网站或移动端登录。

脚本结束时的提示还给出了安装后的标准配置循环：

1. docker compose down 停止容器；
2. 修改 .env 中的数据库、Redis、备份（上传）位置等配置；
3. docker compose up --remove-orphans -d 重新启动。

脚本要求系统已安装 docker compose 与 curl，否则会以明确的退出码报错退出。

手动部署：Docker Compose 四大服务

若要手动安装，参考仓库内 docker/docker-compose.yml（docker/docker-compose.yml#L12-L76），整个部署由 4 个服务组成：

服务	容器名	镜像	职责与要点
immich-server	immich_server	ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}	核心 API 服务，对外映射 2283:2283 端口；依赖 redis 与 database；媒体库挂载 ${UPLOAD_LOCATION}:/data
immich-machine-learning	immich_machine_learning	ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}	人脸/CLIP/OCR 推理服务；挂载命名卷 model-cache:/cache 缓存模型
redis	immich_redis	valkey:9	任务队列与缓存，健康检查为 redis-cli ping
database	immich_postgres	ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0	定制 PostgreSQL，内置 vectorchord 与 pgvectors 扩展（存储 CLIP/人脸向量），初始化参数开启 --data-checksums，shm_size: 128mb

两个数据卷必须落到本地磁盘：

• ${UPLOAD_LOCATION}:/data —— 上传的原始照片/视频与派生文件；
• ${DB_DATA_LOCATION}:/var/lib/postgresql/data —— 数据库文件，官方明确数据库不支持放在网络共享存储上。

.env 关键配置项

环境变量模板见 docker/example.env，逐项说明：

变量	模板默认值	说明
UPLOAD_LOCATION	./library	上传文件的存储位置，也是 compose 中媒体库挂载点
DB_DATA_LOCATION	./postgres	数据库文件位置，不支持网络共享
TZ	（注释状态）	时区，取消注释并改为 tz 数据库中的时区标识
IMMICH_VERSION	v3	使用的 Immich 版本，可固定为具体版本号（如 v2.1.0）用于稳定部署
DB_PASSWORD	postgres	数据库连接密钥，官方强烈建议改为随机密码，且只能使用 A-Za-z0-9，不得含特殊字符或空格
DB_USERNAME	postgres	模板注释标明“此线下方的值无需修改”
DB_DATABASE_NAME	immich	数据库名

一键脚本会自动替你替换 DB_PASSWORD；手动安装时必须自行处理。完整的环境变量参考（含 SMTP、OAuth、硬件加速等全部变量）见仓库文档 docs/docs/install/environment-variables.md。

硬件加速：机器学习与视频转码两套配置

Immich 通过 extends 机制把硬件加速配置拆成了两个附加文件，按需注释启用：

1. 机器学习加速 —— docker/hwaccel.ml.yml

在 immich-machine-learning 服务上启用，支持 cpu、armnn（ARM Mali GPU）、rknn（瑞芯微 NPU，需映射 /dev/dri 并放开 AppArmor）、cuda（NVIDIA）、rocm（AMD）、openvino 等后端。compose 文件注释说明：只需在镜像 tag 后追加后端名即可，例如 ${IMMICH_VERSION:-release}-cuda；openvino-wsl 等 -wsl 变体用于 WSL2 环境。

2. 视频转码加速 —— docker/hwaccel.transcoding.yml

在 immich-server 服务上启用，支持 cpu、nvenc（NVIDIA）、quicksync（Intel）、rkmpp（瑞芯威）、vaapi / vaapi-wsl 等后端；NVIDIA 场景通过 deploy.resources.reservations.devices 声明 GPU 能力（compute/video）。

两个文件头部均提示：如果使用 Unraid 等只允许单一 compose 文件的平台，可以把对应后端的配置直接内联到主 docker-compose.yml 的相应服务中。docker/docker-compose.yml#L16-L18 与 docker/docker-compose.yml#L36-L41 中预留的注释块正是这一机制的挂载点。相关文档位于 docs/docs/install/（requirements.md、docker-compose.mdx、one-click.md、upgrading.md 等）。

功能矩阵与仓库结构的对应关系

把 README 的能力清单放回仓库目录，可以验证每项功能都有对应的实现载体：

能力域	实现位置
上传/备份/搜索/共享等 API	server/src/：NestJS 服务端，含 controllers/（82 个控制器）、services/（102 个服务）、queries/（SQL 查询）等
Web 界面（管理、分享、浏览）	web/src/：SvelteKit 前端，routes/ 下为页面路由，lib/ 下为组件与逻辑
移动端（自动备份、后台备份、离线）	mobile/：Flutter 应用，lib/services/、lib/repositories/ 承担同步与本地数据库（drift）逻辑，pigeon/ 下为平台通道 API
人脸/CLIP/OCR 推理	machine-learning/：Python 服务，immich_ml/models/ 下按模型拆分
多语言（界面 + README）	i18n/（89 个语言文件）与 readme_i18n/（20 个语言 README）
安装与运维文档	docs/docs/install/、docs/docs/administration/（备份与恢复、维护模式、OAuth、服务器命令等）

从源码结构看，服务端通过 server/src/workers/ 中的后台 Worker 消费 Redis 队列执行转码、向量计算等异步任务，这解释了为什么 immich-server 在 compose 中显式 depends_on redis——机器学习结果（人脸、CLIP 向量）先由独立 ML 服务异步产出，再由服务端任务管线落库，从而支撑“搜索按物体、人脸与 CLIP”这类高级检索。

结语：部署要点回顾

• 无论一键脚本还是手动安装，产物都是 immich-app 目录下的 docker-compose.yml + .env，访问入口为 http://<IP>:2283；
• DB_PASSWORD 必须改为纯字母数字的随机值；UPLOAD_LOCATION 与 DB_DATA_LOCATION 必须指向本地磁盘；
• 有 GPU/NPU 时，按 hwaccel.ml.yml（模型 tag 后缀）与 hwaccel.transcoding.yml（extends 内联）分别加速推理与转码；
• 上线前请把 3-2-1 备份策略落实为定期任务——官方文档中的备份与恢复指引见 docs/docs/administration/backup-and-restore.md。