企业官网建设流程全解析

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

【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/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 推理服务的架构：

演示环境与体验凭据

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

这个演示环境是验证下文功能矩阵最快速的方式——无需自行部署，即可看到人脸分组、时间轴、地图等功能在真实数据上的表现。若要本地部署，仓库内 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 端独占的能力集中在"管理"侧（用户管理、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 备份。

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