Immich 中文指南：高性能自托管照片与视频管理方案的全景解读与部署实战

本篇基于 Immich 仓库的简体中文 README 展开，带你完整理解这个自托管照片与视频管理项目的功能矩阵（移动端/网页端能力对照）、官方演示账号信息，并结合仓库内的 install.sh 一键安装脚本、docker/docker-compose.yml 容器编排与环境变量配置，讲清楚一套 Immich 实例的四大服务组成、硬件门槛与底层实现要点，读完即可独立完成部署并理解其架构原理。

项目定位：自托管的照片与视频管理方案

Immich 是一个高性能的自托管照片与视频管理解决方案（High performance self-hosted photo and video management solution），采用 AGPL v3 协议开源（见 LICENSE）。需要特别说明的是：简体中文 README 并非由 Immich 官方团队维护，而是依靠社区贡献者更新，因此内容可能不会及时同步，这一点在文档开头有明确声明。

README 中有两条关键提示值得所有自托管用户牢记：

1. 备份警告：为了您宝贵的照片与视频，请始终遵守 3-2-1 备份方案（3 份副本、2 种不同介质、1 份异地存储）。Immich 是照片的“管理中枢”，不应被当作唯一的备份终点；
2. 完整文档入口：详细的项目文档与安装教程以仓库内 docs/ 目录为准，例如 系统要求、架构说明、安装文档目录。

此外，仓库还收录了 21 份其他语言的 README 翻译（见 README 英文主版本 及各语言分册目录 readme_i18n），包括正体中文（README_zh_TW.md）、日文、韩文、德文等，方便不同语言区用户查阅。

在线演示与体验账号

README 提供了官方在线演示站点供用户快速体验全部功能：在移动端 App 中，可将演示站点的地址填入 服务终端链接（Server Endpoint URL）完成连接。

登录认证信息

邮箱	密码
[e-mail]	demo

功能特性矩阵（移动端 vs 网页端）

README 最核心的内容是一张覆盖 30 项能力的功能矩阵，逐项标注了移动端（Mobile）与网页端（Web）的支持情况。完整矩阵如下：

功能特性	移动端	网页端
上传并查看照片和视频	是	是
软件运行时自动备份	是	N/A
忽略重复的项目	是	是
选择需要备份的相册	是	N/A
下载照片和视频到本地	是	是
多用户支持	是	是
相册与共享相册	是	是
可拖动的快速滚动条	是	是
支持RAW格式	是	是
元数据视图（EXIF、地图）	是	是
通过元数据、对象、人脸和标签进行搜索	是	是
管理功能（用户管理）	否	是
后台备份	是	N/A
虚拟滚动	是	是
OAuth 支持	是	是
API Keys	N/A	是
实况照片备份和查看	是	是
支持360度全景图显示	否	是
用户自定义存储结构	是	是
公共分享	是	是
归档与收藏功能	是	是
足迹地图	是	是
好友分享	是	是
人脸识别与分组	是	是
回忆（那年今日）	是	是
离线支持	是	否
只读相册	是	是
照片堆叠	是	是
标签	否	是
文件夹浏览	否	是

从矩阵可以读出几点选型参考：移动端是备份入口（自动备份、后台备份、离线支持均为移动端独有），网页端承担管理职责（用户管理、API Keys、360 全景显示等仅在网页端提供）。矩阵中"通过元数据、对象、人脸和标签进行搜索"这一智能搜索能力，其背后实现可以在服务端源码中找到佐证。

部署实战：从一键脚本到容器编排

一键安装脚本 install.sh

仓库根目录的 install.sh 实现了最小化的部署流程，其执行链路清晰可查：

1. 创建目录：create_immich_directory() 在当前目录创建 ./immich-app，若已存在则复用并覆盖 YAML 文件；
2. 下载编排文件：download_docker_compose_file() 与 download_dot_env_file() 从最新 release 包中拉取 docker-compose.yml 和 example.env（后者保存为 .env）；
3. 生成随机密码：generate_random_password() 用 $RANDOM + 时间戳做 SHA-256 后取 Base64 前 10 位，替换 .env 中默认的 DB_PASSWORD=postgres，避免使用弱口令；
4. 启动容器：start_docker_compose() 检查 docker compose 命令可用后执行 docker compose up --remove-orphans -d。

安装完成后脚本会输出访问地址 http://<本机IP>:2283（macOS 下通过 ipconfig getifaddr en0 获取 IP），并给出三步修改配置的指引：先 docker compose down 停止容器，再编辑 .env（数据库、Redis、备份/上传位置等），最后 docker compose up --remove-orphans -d 重新拉起。脚本对每一步失败都有独立的退出码（10–14），便于排障。

容器编排 docker/docker-compose.yml

docker/docker-compose.yml 定义了一套由 4 个服务组成的实例：

服务	镜像	职责
immich-server	ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}	REST API、缩略图/转码等后台任务，对外暴露 2283:2283
immich-machine-learning	ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}	机器学习推理（智能搜索、人脸识别等），可加 -cuda/-rocm/-armnn/-openvino/-rknn 后缀启用硬件加速
redis	docker.io/valkey/valkey:9（锁定 digest）	后台任务队列，healthcheck 为 redis-cli ping
database	ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0（锁定 digest）	数据持久化，初始化参数含 --data-checksums，shm_size: 128mb

几个值得注意的编排细节：

• 媒体存储路径由 .env 的 UPLOAD_LOCATION 挂载到容器内 /data，compose 文件注释明确提醒不要直接改挂载行，而要改 .env；数据库路径同理由 DB_DATA_LOCATION 控制；
• immich-server 通过 depends_on 声明依赖 redis 与 database，三者均设置 restart: always 与健康检查；
• 硬件加速通过 extends 引用 docker/hwaccel.transcoding.yml（转码，支持 nvenc/quicksync/rkmpp/vaapi 等）与 docker/hwaccel.ml.yml（推理，支持 armnn/cuda/rocm/openvino/rknn），默认注释状态即 CPU 模式；
• 另有面向开发者的 docker/docker-compose.dev.yml、docker/docker-compose.prod.yml（附带 Prometheus + Grafana 监控栈，需在 .env 设置 IMMICH_TELEMETRY_INCLUDE=all）与 docker/docker-compose.rootless.yml。

compose 文件头部有重要注释：请始终使用当前 release 的 docker-compose.yml，main 分支上的 compose 文件可能与最新发布版不兼容。

关键环境变量 example.env

docker/example.env 是部署后第一优先级需要编辑的文件，核心变量如下：

# 上传文件的存储位置
UPLOAD_LOCATION=./library
# 数据库文件存储位置，不支持网络共享
DB_DATA_LOCATION=./postgres
# 时区，默认为 Etc/UTC，可取消注释修改为任意 TZ 标识符
# 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

更完整的变量清单可查阅 环境变变量文档。

硬件与软件要求

部署前建议对照 系统要求文档 自检：

• 操作系统：推荐 64 位 Linux/*nix；Windows 需通过 Docker Desktop 或 WSL2，macOS 使用 Docker Desktop；
• 内存：最低 6GB，推荐 8GB（仅 4GB 内存时可关闭机器学习功能运行）；
• CPU：最低 2 核、推荐 4 核，支持 amd64 与 arm64；自 v3 起，amd64 平台的机器学习容器要求 >= x86-64-v2 微架构级别（约 2012 年后的 CPU 均满足）；
• 存储：Postgres 数据库文件（DB_DATA_LOCATION）应放在本地 SSD，绝不能放在任何网络共享上；缩略图与转码视频平均会使照片库体积增加 10–20%；
• 软件：Docker 引擎 + Compose 插件，且必须是 docker compose（v2 插件形式），旧版 docker-compose（v1）已不再受支持。

架构与源码级佐证

README 功能矩阵中的能力，在仓库中都有对应的实现支撑。根据 架构文档：

• 客户端三件套：Flutter 编写的移动端 App（mobile/lib）、SvelteKit + TypeScript 的 Web 应用（web/src）、以及用于批量上传的 CLI（packages/cli），三者都基于 OpenAPI 规格（open-api/immich-openapi-specs.json）自动生成 REST 客户端；
• 服务端：TypeScript/Node.js + Nest.js + Kysely，按六边形架构思路将技术实现（src/repositories）与业务逻辑（src/services）分离；
• 机器学习服务：Python + FastAPI，全部模型使用 ONNX 格式，独立容器化后可部署到别的机器上或整体禁用；
• 后台任务：缩略图生成、元数据提取、视频转码、智能搜索、人脸识别、存储模板迁移等任务经由 Redis（BullMQ）队列调度执行，部分任务存在依赖链（例如智能搜索依赖缩略图先完成）。

以功能矩阵中的"智能搜索"为例，server/src/services/search.service.ts 中的 SearchService 同时提供人员搜索（searchPerson）、地点搜索（searchPlaces）、元数据搜索（searchMetadata，支持 checksum 查重、分页游标与可见性过滤，Locked 可见性需管理员权限）等多种检索入口，并在类内用一个容量 100 的 LRU 缓存（embeddingCache = new LRUMap<string, string>(100)）缓存文本向量，减少重复调用机器学习服务获取 embedding 的开销——这正是"搜索 by 元数据、对象、人脸"矩阵项在代码层的落地。

机器学习的模型实现同样有迹可循：machine-learning/immich_ml/models 下按 clip/（智能搜索）、facial_recognition/、ocr/ 三个子模块组织，与 compose 中 model-cache 卷挂载的 /cache（模型下载缓存）相配合。

多语言支持

Immich 的界面翻译同样采用社区众包模式，翻译进度见官方 Weblate 平台（多语言开发文档）。仓库中 i18n/ 目录收录了 90+ 种语言的翻译文件（en.json、zh_Hans.json、zh_Hant.json、ja.json 等），这些文件即界面文案的来源。

许可与参与

• 许可协议：AGPL v3（LICENSE）；
• 与同类方案的对比可参考 对比文档；
• 贡献指南见 CONTRIBUTING.md，社区维护的 README 分册（readme_i18n）也欢迎提交翻译改进。

适用前提提醒：本文所有命令、配置文件路径与环境变量均基于当前仓库实际内容，适用于以 Docker Compose 方式部署的 Immich 实例；由于简体中文 README 由社区维护，若与最新 release 行为有出入，请以 release 附带的 compose 文件与官方文档为准。