Immich 自托管照片与视频管理方案：功能矩阵、部署路径与特性实现对照（基于官方 README）

Immich 自托管照片与视频管理方案：功能矩阵、部署路径与特性实现对照（基于官方 README）

【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich

Immich 是一个高性能的自托管（self-hosted）照片与视频管理解决方案，官方仓库的多语言 README（本文以 readme_i18n/README_th_TH.md 泰语版为参照主体，与 README.md 英文版互为印证）完整列出了项目定位、在线演示、全量功能矩阵与翻译计划。读完本文，你可以基于 README 的功能清单快速判断 Immich 是否满足你的媒体库管理需求，并能结合仓库中的docker-compose.yml、.env示例、一键安装脚本与服务端源码，理解每个特性背后的实际实现位置。

项目定位与核心提示

README 将 Immich 概括为 "High performance self-hosted photo and video management solution"（高性能自托管照片和视频管理方案），并给出两条关键提示：

1. 备份警告（重要）：README 以醒目警告形式提醒——对于重要的照片和视频，请始终遵循 3-2-1 备份策略（保留 3 份副本、存于 2 种不同介质、其中 1 份异地）。这是官方文档中最强烈的安全提醒，后文会结合仓库中的备份实现进一步说明。
2. 文档入口：完整的安装指南与主文档位于官方文档站点（immich.app），仓库内的docs/目录即该文档站的源码，例如 docs/docs/install/docker-compose.mdx、docs/docs/administration/backup-and-restore.md 可直接查阅。

仓库采用 AGPL v3 许可证（见 README.md 顶部的 License 徽标），多语言 README 通过readme_i18n/目录维护，包含泰语、简体中文、日语、韩语、德语等 20 余种语言的版本，主 README 内嵌语言切换链接。

在线演示（Demo）与登录凭证

README 提供了一个公共演示实例，供尚未自行部署的用户直观体验：

• 演示地址：https://demo.immich.app
• 移动端 App 接入时，将该地址填入Server Endpoint URL即可连接。

这一设计说明 Immich 的客户端（移动端/网页端）都是围绕"服务器端点 URL + 账号"这一模型工作的，自托管部署后同样以http://<你的主机>:2283作为端点（默认端口 2283，见 docker/docker-compose.yml 中immich-server的ports映射）。

完整功能矩阵（README 原表全量继承）

README 的核心内容是一张"特性 × 平台"矩阵表，明确区分了移动端（Mobile）与网页端（Web）的能力差异。下表完整继承 readme_i18n/README_th_TH.md 中的 27 行特性（译成中文）：

说明：英文版 README.md 的功能表比泰语版多出Tags（标签，网页端支持）与Folder View（文件夹视图，移动端与网页端均支持）两行，阅读时以英文版为准可得到最新全量能力。

从这张矩阵可以提炼出三个平台差异要点：

• 移动端独有：打开应用自动备份、指定相册备份、后台备份、离线支持——这些都是依赖操作系统通知/后台任务能力的功能，故网页端标注 N/A。
• 网页端独有：用户管理（Administration）、API 密钥、360 度全景展示、Tags——管理与高级展示类功能集中在网页端。
• 双端通用：CLIP 语义搜索、人脸识别聚类、LivePhoto 播放、伙伴共享、地图、回忆等核心体验。

功能特性在仓库中的实现落点（源码佐证）

README 承诺的每项能力都能在仓库源码中找到对应实现，以下按功能分组给出关键路径，便于深入阅读：

服务端（NestJS + TypeScript）

服务端代码位于server/src/，从 server/package.json 可确认其技术栈：@nestjs/core、bullmq（基于 Redis 的任务队列）、sharp（图像解码/转码）、fluent-ffmpeg（视频转码）、openid-client（OAuth）、jsonwebtoken、bcrypt，以及pg/kysely（PostgreSQL 与查询构建）。server/src/services/目录下的 100 余个服务文件与功能矩阵几乎一一对应：

此外，server/src/下还有queries/（36 个 SQL 查询文件）、repositories/（62 个数据访问层文件）与emails/（9 个 React Email 模板，配合nodemailer发送通知），体现了"控制器 → 服务 → 仓储 → SQL"的分层结构。

机器学习服务（Python）

"搜索基于元数据、物体、人脸与 CLIP" 这一卖点由独立的machine-learning/服务承担，模型代码位于machine-learning/immich_ml/models/：

• CLIP 视觉/文本编码：machine-learning/immich_ml/models/clip/visual.py 中BaseCLIPVisualEncoder以(ModelType.VISUAL, ModelTask.SEARCH)注册，将图片转为向量供语义搜索；文本侧对应clip/textual.py。
• 人脸检测与识别：machine-learning/immich_ml/models/facial_recognition/ 下的detection.py与recognition.py分别完成检测框定位与人脸特征提取，聚类结果由服务端的person.service.ts组织为"人物"页面。
• OCR：machine-learning/immich_ml/models/ocr/提供检测/识别/CTC 后处理，支撑"文字内容可搜索"。

从 docker/docker-compose.yml 的注释可推断硬件加速方式：在 ML 镜像 tag 后追加cuda、rocm、openvino、rknn等后缀（如${IMMICH_VERSION:-release}-cuda），配合hwaccel.ml.yml扩展文件；视频转码加速则由hwaccel.transcoding.yml提供nvenc、quicksync、vaapi等选项（对应 docker/hwaccel.ml.yml 与 docker/hwaccel.transcoding.yml）。

移动端（Flutter）

移动端代码在mobile/，采用 Flutter + Riverpod + Drift（本地 SQLite，见mobile/drift_schemas/中的 31 个版本 schema 文件）。README 中"离线支持""后台备份""只读画廊"等移动端能力即由mobile/lib/下的服务与 Provider 实现；mobile/pigeon/目录定义了一系列平台通道接口（native_sync_api.dart、permission_api.dart等），用于与 Android/iOS 原生层交换权限与同步事件。

网页端（SvelteKit）

网页端位于web/（Svelte + SvelteKit，web/src/下约 253 个.svelte组件），承担管理后台、CLIP 搜索、地图、360 度全景展示（移动端标注"不支持"的功能在此实现）等能力。

部署方式与关键配置（结合仓库实操文件）

README 提示安装指南以官方文档为准，仓库内则提供了完整的可执行部署材料：

方案一：一键安装脚本

仓库根目录的 install.sh 是官方 one-click 安装脚本，其执行流程（从源码逐行可确认）为：

1. 创建./immich-app目录；
2. 从 Immich 官方 release 下载最新的docker-compose.yml；
3. 下载example.env并重命名为.env；
4. 用sha256sum + base64生成随机DB_PASSWORD替换默认值postgres；
5. 执行docker compose up --remove-orphans -d启动；
6. 打印访问地址http://<主机IP>:2283。

注意脚本明确要求使用当前 release的 compose 文件，而非 main 分支版本（docker/docker-compose.yml 头部注释同样强调了这一点：main 上的 compose 文件可能与最新 release 不兼容）。

方案二：Docker Compose 手动部署

docker/docker-compose.yml 定义了四个服务，理解它们即可理解整套架构：

配套的环境变量模板 docker/example.env 仅需理解 5 个变量：

DB_USERNAME=postgres与DB_DATABASE_NAME=immich无需修改。此外 compose 文件中还留有两处注释掉的extends块，分别用于开启转码硬件加速与 ML 硬件加速，需要时取消注释并选择对应服务名即可。

备份策略：README 警告的落地实现

README 顶部的 3-2-1 备份警告不是空话——仓库中提供了完整的机制支撑，详见 docs/docs/administration/backup-and-restore.md 与 server/src/services/database-backup.service.ts：

• 自动数据库备份：Immich 每日定时（默认凌晨 2:00）创建数据库转储，默认保留最近 14 份，存储于UPLOAD_LOCATION/backups，可在"管理 > 设置 > 备份"调整策略，也可在"管理 > 任务队列"手动触发Create Database Dump。
• 关键认知：数据库只保存文件路径与元数据，不包含照片视频本体。因此完整的 3-2-1 备份必须同时覆盖三块数据：UPLOAD_LOCATION下的媒体文件（backups、encoded-video、library、profile、thumbs、upload等子目录）、DB_DATA_LOCATION数据库目录、以及.env中的DB_PASSWORD等配置。
• 恢复路径：网页端"管理 > 维护"中可直接从备份列表恢复（恢复前会自动创建回滚点），新实例也可在 Onboarding 阶段导入旧备份目录完成迁移。
• 仓库还提供了可定时执行的备份脚本模板（docs/docs/guides/template-backup-script.md 所指的 bash 模板），便于把"数据库 dump + 媒体目录复制"固化为 cron 任务。

参与翻译与项目支持

README 末尾的 "Translations" 一节说明翻译通过 Weblate 平台进行（文档给出 hosted.weblate 上的 immich 项目入口与翻译进度徽标），开发者指南位于 docs/docs/developer/translations.md。仓库根目录的i18n/目录存放了 90+ 种语言的界面翻译 JSON（如 i18n/en.json、i18n/zh_Hans.json），而readme_i18n/目录维护 README 本身的多语言版本——本文参照的 readme_i18n/README_th_TH.md 即其中之一。贡献与支持的详细说明见 docs/docs/overview/support-the-project.md 与 CONTRIBUTING.md。

小结

以 readme_i18n/README_th_TH.md 为骨架可以看出：Immich 的 README 用一张功能矩阵清晰界定了移动端与网页端的分工（移动端强在自动/后台备份与离线，网页端强在管理与高级展示），并用演示实例降低了首次体验门槛；而结合 docker/docker-compose.yml、docker/example.env、install.sh 与server/src/services/下的服务实现可以确认，README 承诺的 CLIP 搜索、人脸聚类、LivePhoto 播放、伙伴共享、回忆等功能均有明确的代码落点，备份要求则配套了自动转储与恢复流程。若计划自托管，建议路径为：用install.sh或 release 版 compose 文件完成部署 → 修改.env中DB_PASSWORD与存储位置 → 按 3-2-1 策略配置数据库 +UPLOAD_LOCATION+ 数据库目录的三重备份。

【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich