Immich 自托管照片与视频备份管理方案部署架构、功能矩阵与源码级实现详解【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immichImmich 是一个高吞吐的自托管self-hosted照片与视频管理解决方案核心价值在于把照片库从消费级云盘迁回自己的服务器同时保留接近商业应用的体验。本文以 Immich 仓库的项目说明文档为骨架完整覆盖其部署架构、环境参数、移动端与 Web 端功能矩阵和多语言体系并结合仓库源码印证“Memories 回忆、CLIP 搜索、人脸聚类、存储模板”等关键功能的真实实现读完后你将能够独立完成 Immich 的容器化部署并理解其功能背后的服务端调用链。项目定位与 3-2-1 备份原则项目说明文档README.md 及其各语言版本如西班牙语 README_es_ES.md对 Immich 的定义是“High performance self-hosted photo and video management solution”——高性能自托管的照片与视频备份管理方案。文档同时给出了一条贯穿始终的重要警示⚠️ 请务必为你的照片和视频遵循 3-2-1 备份策略3 份副本、2 种不同介质、1 份异地存放。这条警示的意图非常明确Immich 是备份体系中的一环而非唯一副本。官方仓库中甚至内置了面向 PostgreSQL 数据库的定期备份服务database-backup.service.ts 负责生成数据库转储配合文档 backup-and-restore.md 中介绍的脚本化流程可以覆盖“库内数据 媒体文件 数据库”三层备份对象与 3-2-1 原则形成呼应。部署架构Docker Compose 四服务拓扑Immich 的安装以 Docker Compose 为主路径。docker/docker-compose.yml 定义了四个服务文件头部注释明确要求使用当前发布版本对应的 compose 文件main 分支上的版本可能与最新 release 不兼容服务容器名镜像作用immich-serverimmich_serverghcr.io/immich-app/immich-server主服务端 API监听 2283 端口immich-machine-learningimmich_machine_learningghcr.io/immich-app/immich-machine-learningML 推理人脸检测/嵌入、CLIP、OCR、对象标签redisimmich_redisdocker.io/valkey/valkey任务队列与缓存databaseimmich_postgresghcr.io/immich-app/postgres内置 vectorchord、pgvector 扩展元数据与向量检索存储几个值得注意的工程细节向量检索内建于数据库Postgres 镜像标签为14-vectorchord0.4.3-pgvectors0.2.0说明向量相似性搜索人脸嵌入、CLIP 文本搜图直接在数据库层完成无需独立的向量数据库组件ML 硬件加速是可选挂载compose 文件中immich-server与immich-machine-learning均保留了extends注释段通过 hwaccel.transcoding.yml 与 hwaccel.ml.yml 分别接入 nvenc/quicksync/vaapi 等转码加速与 cuda/rocm/openvino/rknn 等推理加速镜像 tag 后缀即代表加速变体如release-cuda模型缓存持久化ML 容器挂载命名卷model-cache:/cache避免每次启动重新下载模型依赖与重启策略immich-server通过depends_on声明对 redis 与 database 的依赖所有服务均为restart: always并启用 healthcheckPostgres 存储约束compose 中shm_size: 128mb且 example.env 注释明确“数据库不支持放在网络共享目录上”。仓库同时提供了生产与无 root 场景变体docker-compose.prod.yml 与 docker-compose.rootless.yml以及开发用 docker-compose.dev.yml一键安装脚本为 install.sh。关键 .env 参数example.env 是所有环境变量的模板核心参数如下变量默认值说明UPLOAD_LOCATION./library上传媒体文件的存储位置compose 中固定挂载到容器/data改位置只改这里DB_DATA_LOCATION./postgres数据库文件位置挂载到/var/lib/postgresql/data绝不要指向网络共享TZ注释状态时区取 IANA tz database 标识符如Asia/ShanghaiIMMICH_VERSIONv3使用的主版本线可固定到具体版本号如v2.1.0DB_PASSWORDpostgresPostgres 连接密码必须改为随机值仅允许A-Za-z0-9字符DB_USERNAME/DB_DATABASE_NAMEpostgres/immich以下划线线标注“无需修改”的固定值完整的变量清单维护在官方文档 environment-variables.md。硬件与软件前提安装文档 requirements.md 给出了明确基线适用于以 compose 方式自部署的读者操作系统推荐 Linux/*nix 64 位Ubuntu、Debian 等非 Linux 平台Windows 走 Docker Desktop/WSL2、macOS 走 Docker Desktop体验较差官方不重点支持内存最低 6GB推荐 8GB。4GB 内存机器可以禁用 ML 功能运行但上传体验会受影响CPU最低 2 核推荐 4 核运行amd64与arm64平台且自v3起 amd64 的 ML 容器要求x86-64-v2及以上微架构约 2012 年后的主流 CPU 均满足存储推荐 EXT4、ZFS、APFS 等支持用户/组权限的 Unix 文件系统缩略图与转码视频平均会使图库体积膨胀 10–20%数据库文件典型 1–3GB建议本地 SSD若使用 Docker 资源限制Postgres 至少需要 2GB 内存软件Docker Compose 插件。官方强调需要docker composeV2 插件已弃用的docker-composeV1不受支持Windows 用户若数据库只能放在 NTFS/WSL 挂载目录可改为 Docker volume文档给出了具体 diff。功能矩阵移动端与 Web 端的能力边界项目说明文档的核心是一张“功能 × 端”矩阵直接体现了 Immich 的三端形态Flutter 移动 App、SvelteKit Web、NestJS 服务端。下表继承自西班牙语文档的功能清单并标注了服务端对应实现的所在文件便于按图索骥功能移动端Web服务端实现依据上传与查看照片/视频✓✓asset.service.ts、asset-media.service.ts打开应用自动备份✓N/A移动端同步层mobile/lib/domain/services sync.service.ts选择性相册备份✓N/Aalbum.service.ts下载到本地设备✓✓download.service.ts多用户支持✓✓user.service.ts、user-admin.service.ts相册与共享相册✓✓album.service.tsRAW 格式支持✓✓元数据/缩略图管线 metadata.service.ts元数据查看EXIF、地图✓✓map.service.ts元数据/物体/人脸/CLIP 搜索✓✓search.service.ts、ocr.service.ts管理功能用户管理✗✓auth-admin.service.ts后台备份✓N/A移动端后台任务 服务端队列虚拟滚动✓✓客户端渲染能力OAuth 登录✓✓auth.service.tsAPI 密钥N/A✓api-key.service.tsLivePhoto/MotionPhoto 备份与回放iOS✓asset-media.service.ts用户自定义存储结构✓✓storage-template.service.ts公开分享✗移动✓shared-link.service.ts归档与收藏✓✓asset.service.ts全球地图✗移动✓map.service.ts协作者共享Partner✓✓partner.service.ts人脸识别与聚类✓✓person.service.ts回忆几年前这一天✓✓memory.service.ts离线支持✓✗移动端本地库mobile/lib/data/dbdrift schema 见 drift_schemas只读图库✓✓library.service.ts转码播放✓✓transcoding.service.ts、hls.service.ts注意矩阵揭示的端差异管理操作、API 密钥、公开分享链接、地图等“重管理”能力集中在 Web 端自动备份、后台备份、离线浏览等“重设备”能力集中在移动端。这种划分与服务端代码结构一致——server/src/services 下每个能力都有独立 service 文件并配套.spec.ts单元测试管理域能力通过CurrentUser权限装饰器如 decorators.ts 中的Permission体系限制为仅 Web 管理员路径暴露。核心功能的源码级印证Memories 回忆“x 年前这一天”如何生成西语文档功能表中“Recuerdos (hace x años)”对应的实现是 memory.service.ts。其机制服务端注册了一个后台作业JobName.MemoryGenerateOnJob装饰器绑定到QueueName.BackgroundTask队列由 job.service.ts 按调度周期触发每次运行在数据库锁DatabaseLock.MemoryCreation下执行以“今天 ± 3 天”为窗口常量DAYS 3用系统元数据键SystemMetadataKey.MemoriesState记录已处理的日期防止重复生成对窗口内每个目标日期调用assetRepository.getByDayOfYear找出“历史上同一年中这一天的所有资产”为每个年份创建一条MemoryType.OnThisDay记录showAt/hideAt限定为该目标日期的当天可见配套的JobName.MemoryCleanup作业定期清理过期回忆记录。也就是说“回忆”不是实时计算的视图而是后台作业预生成、按日期窗口定时展示的数据实体——这解释了为什么该功能在移动端与 Web 端表现完全一致两端都只是查询MemoryService.search。CLIP 文本搜图从查询到向量检索search.service.ts 中可以看到 CLIP 搜索的缓存键构造machineLearning.clip.modelName dto.query dto.language。从源码结构看搜索链路由SearchService聚合元数据搜索、人脸/物体标签、OCR 文本与 CLIP 向量检索其中 CLIP 部分先查“查询文本→图像嵌入”的缓存未命中时调用 ML 容器machine-learning/immich_ml/models/clip获取文本嵌入再交给 Postgres 的向量扩展做相似性匹配。ML 服务本身以 gunicorn FastAPI 方式运行入口 machine-learning/immich_ml/main.py模型会话支持 onnxruntime 与 RKNN 两种后端immich_ml/sessions。人脸聚类与存储模板人脸聚类person.service.ts 暴露PersonService人脸检测/嵌入由 ML 容器产出后服务端通过JobName.PersonGenerateThumbnail、JobName.PersonCleanup、JobName.PersonFileMigration等后台作业维护人脸组、缩略图与文件迁移人脸库的 ANN 索引由 ML 侧 C 扩展 machine-learning/ann 提供。自定义存储结构storage-template.service.ts 的StorageTemplateService按用户定义的模板年/月/相册/标签/地理等表达式在新资产入库时计算其最终目录路径对应文档 storage-template.mdx。演示环境与上手验证项目文档提供了一个官方托管的 Web 演示实例用于快速体验完整功能移动端 App 将服务器 URL 指向该演示域名即可连接。演示账号凭据为邮箱demoimmich.app 密码demo在开始自部署前用演示环境熟悉相册、搜索、地图、分享等交互是官方文档建议的上手路径。多语言体系i18n 目录与 Weblate 工作流西语 README 本身就证明了项目的翻译机制仓库根目录 i18n/ 下维护着 80 余种语言的 JSON 翻译文件含es.json、zh_Hans.json、ja.json、de.json等README 的语言导航即指向这些文件如 README_es_ES.md、README_ca_ES.md。翻译工作流文档 translations.md 说明了三点关键设计集中式协作本地化托管在 Weblate 平台上集中管理贡献者可在平台上申请新语言、提交修订ICU 消息格式复数、数字、日期等本地化格式采用 ICU message format运行时由intl-messageformat库处理避免各端各自实现格式化逻辑键一致性校验移动端提供 check_i18n_keys.py 脚本校验各语言文件的键集合与英文基准一致防止翻译缺失导致界面回退。对部署者而言这意味着Immich 的界面语言含西语、简体中文等开箱即用对贡献者而言新增语言只需遵循i18n/目录的命名约定语言代码 可选地区/文字变体如sr_Cyrl.json、yue_Hant.json并通过 CI 的键校验。小结Immich 的仓库文档骨架传递出三个清晰信息3-2-1 备份原则不可妥协——Immich 是备份链中的一环部署形态高度收敛——四个 Docker 服务、一个.env、8GB 内存起步向量检索内建于 Postgres 使架构保持精简能力矩阵端侧分明——管理在 Web、备份与离线在移动端而 Memories、CLIP 搜索、人脸聚类等“智能”功能全部由服务端后台作业 独立 ML 容器驱动并通过每个 service 配套的 spec 测试保证行为可验证。按 docker/ 目录下的 compose 文件与 example.env 起步再对照 docs/docs/install/ 中的安装与升级指南即可完成一次符合官方预期的自托管部署。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Immich 自托管照片与视频备份管理方案：部署架构、功能矩阵与源码级实现详解
Immich 自托管照片与视频备份管理方案部署架构、功能矩阵与源码级实现详解【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immichImmich 是一个高吞吐的自托管self-hosted照片与视频管理解决方案核心价值在于把照片库从消费级云盘迁回自己的服务器同时保留接近商业应用的体验。本文以 Immich 仓库的项目说明文档为骨架完整覆盖其部署架构、环境参数、移动端与 Web 端功能矩阵和多语言体系并结合仓库源码印证“Memories 回忆、CLIP 搜索、人脸聚类、存储模板”等关键功能的真实实现读完后你将能够独立完成 Immich 的容器化部署并理解其功能背后的服务端调用链。项目定位与 3-2-1 备份原则项目说明文档README.md 及其各语言版本如西班牙语 README_es_ES.md对 Immich 的定义是“High performance self-hosted photo and video management solution”——高性能自托管的照片与视频备份管理方案。文档同时给出了一条贯穿始终的重要警示⚠️ 请务必为你的照片和视频遵循 3-2-1 备份策略3 份副本、2 种不同介质、1 份异地存放。这条警示的意图非常明确Immich 是备份体系中的一环而非唯一副本。官方仓库中甚至内置了面向 PostgreSQL 数据库的定期备份服务database-backup.service.ts 负责生成数据库转储配合文档 backup-and-restore.md 中介绍的脚本化流程可以覆盖“库内数据 媒体文件 数据库”三层备份对象与 3-2-1 原则形成呼应。部署架构Docker Compose 四服务拓扑Immich 的安装以 Docker Compose 为主路径。docker/docker-compose.yml 定义了四个服务文件头部注释明确要求使用当前发布版本对应的 compose 文件main 分支上的版本可能与最新 release 不兼容服务容器名镜像作用immich-serverimmich_serverghcr.io/immich-app/immich-server主服务端 API监听 2283 端口immich-machine-learningimmich_machine_learningghcr.io/immich-app/immich-machine-learningML 推理人脸检测/嵌入、CLIP、OCR、对象标签redisimmich_redisdocker.io/valkey/valkey任务队列与缓存databaseimmich_postgresghcr.io/immich-app/postgres内置 vectorchord、pgvector 扩展元数据与向量检索存储几个值得注意的工程细节向量检索内建于数据库Postgres 镜像标签为14-vectorchord0.4.3-pgvectors0.2.0说明向量相似性搜索人脸嵌入、CLIP 文本搜图直接在数据库层完成无需独立的向量数据库组件ML 硬件加速是可选挂载compose 文件中immich-server与immich-machine-learning均保留了extends注释段通过 hwaccel.transcoding.yml 与 hwaccel.ml.yml 分别接入 nvenc/quicksync/vaapi 等转码加速与 cuda/rocm/openvino/rknn 等推理加速镜像 tag 后缀即代表加速变体如release-cuda模型缓存持久化ML 容器挂载命名卷model-cache:/cache避免每次启动重新下载模型依赖与重启策略immich-server通过depends_on声明对 redis 与 database 的依赖所有服务均为restart: always并启用 healthcheckPostgres 存储约束compose 中shm_size: 128mb且 example.env 注释明确“数据库不支持放在网络共享目录上”。仓库同时提供了生产与无 root 场景变体docker-compose.prod.yml 与 docker-compose.rootless.yml以及开发用 docker-compose.dev.yml一键安装脚本为 install.sh。关键 .env 参数example.env 是所有环境变量的模板核心参数如下变量默认值说明UPLOAD_LOCATION./library上传媒体文件的存储位置compose 中固定挂载到容器/data改位置只改这里DB_DATA_LOCATION./postgres数据库文件位置挂载到/var/lib/postgresql/data绝不要指向网络共享TZ注释状态时区取 IANA tz database 标识符如Asia/ShanghaiIMMICH_VERSIONv3使用的主版本线可固定到具体版本号如v2.1.0DB_PASSWORDpostgresPostgres 连接密码必须改为随机值仅允许A-Za-z0-9字符DB_USERNAME/DB_DATABASE_NAMEpostgres/immich以下划线线标注“无需修改”的固定值完整的变量清单维护在官方文档 environment-variables.md。硬件与软件前提安装文档 requirements.md 给出了明确基线适用于以 compose 方式自部署的读者操作系统推荐 Linux/*nix 64 位Ubuntu、Debian 等非 Linux 平台Windows 走 Docker Desktop/WSL2、macOS 走 Docker Desktop体验较差官方不重点支持内存最低 6GB推荐 8GB。4GB 内存机器可以禁用 ML 功能运行但上传体验会受影响CPU最低 2 核推荐 4 核运行amd64与arm64平台且自v3起 amd64 的 ML 容器要求x86-64-v2及以上微架构约 2012 年后的主流 CPU 均满足存储推荐 EXT4、ZFS、APFS 等支持用户/组权限的 Unix 文件系统缩略图与转码视频平均会使图库体积膨胀 10–20%数据库文件典型 1–3GB建议本地 SSD若使用 Docker 资源限制Postgres 至少需要 2GB 内存软件Docker Compose 插件。官方强调需要docker composeV2 插件已弃用的docker-composeV1不受支持Windows 用户若数据库只能放在 NTFS/WSL 挂载目录可改为 Docker volume文档给出了具体 diff。功能矩阵移动端与 Web 端的能力边界项目说明文档的核心是一张“功能 × 端”矩阵直接体现了 Immich 的三端形态Flutter 移动 App、SvelteKit Web、NestJS 服务端。下表继承自西班牙语文档的功能清单并标注了服务端对应实现的所在文件便于按图索骥功能移动端Web服务端实现依据上传与查看照片/视频✓✓asset.service.ts、asset-media.service.ts打开应用自动备份✓N/A移动端同步层mobile/lib/domain/services sync.service.ts选择性相册备份✓N/Aalbum.service.ts下载到本地设备✓✓download.service.ts多用户支持✓✓user.service.ts、user-admin.service.ts相册与共享相册✓✓album.service.tsRAW 格式支持✓✓元数据/缩略图管线 metadata.service.ts元数据查看EXIF、地图✓✓map.service.ts元数据/物体/人脸/CLIP 搜索✓✓search.service.ts、ocr.service.ts管理功能用户管理✗✓auth-admin.service.ts后台备份✓N/A移动端后台任务 服务端队列虚拟滚动✓✓客户端渲染能力OAuth 登录✓✓auth.service.tsAPI 密钥N/A✓api-key.service.tsLivePhoto/MotionPhoto 备份与回放iOS✓asset-media.service.ts用户自定义存储结构✓✓storage-template.service.ts公开分享✗移动✓shared-link.service.ts归档与收藏✓✓asset.service.ts全球地图✗移动✓map.service.ts协作者共享Partner✓✓partner.service.ts人脸识别与聚类✓✓person.service.ts回忆几年前这一天✓✓memory.service.ts离线支持✓✗移动端本地库mobile/lib/data/dbdrift schema 见 drift_schemas只读图库✓✓library.service.ts转码播放✓✓transcoding.service.ts、hls.service.ts注意矩阵揭示的端差异管理操作、API 密钥、公开分享链接、地图等“重管理”能力集中在 Web 端自动备份、后台备份、离线浏览等“重设备”能力集中在移动端。这种划分与服务端代码结构一致——server/src/services 下每个能力都有独立 service 文件并配套.spec.ts单元测试管理域能力通过CurrentUser权限装饰器如 decorators.ts 中的Permission体系限制为仅 Web 管理员路径暴露。核心功能的源码级印证Memories 回忆“x 年前这一天”如何生成西语文档功能表中“Recuerdos (hace x años)”对应的实现是 memory.service.ts。其机制服务端注册了一个后台作业JobName.MemoryGenerateOnJob装饰器绑定到QueueName.BackgroundTask队列由 job.service.ts 按调度周期触发每次运行在数据库锁DatabaseLock.MemoryCreation下执行以“今天 ± 3 天”为窗口常量DAYS 3用系统元数据键SystemMetadataKey.MemoriesState记录已处理的日期防止重复生成对窗口内每个目标日期调用assetRepository.getByDayOfYear找出“历史上同一年中这一天的所有资产”为每个年份创建一条MemoryType.OnThisDay记录showAt/hideAt限定为该目标日期的当天可见配套的JobName.MemoryCleanup作业定期清理过期回忆记录。也就是说“回忆”不是实时计算的视图而是后台作业预生成、按日期窗口定时展示的数据实体——这解释了为什么该功能在移动端与 Web 端表现完全一致两端都只是查询MemoryService.search。CLIP 文本搜图从查询到向量检索search.service.ts 中可以看到 CLIP 搜索的缓存键构造machineLearning.clip.modelName dto.query dto.language。从源码结构看搜索链路由SearchService聚合元数据搜索、人脸/物体标签、OCR 文本与 CLIP 向量检索其中 CLIP 部分先查“查询文本→图像嵌入”的缓存未命中时调用 ML 容器machine-learning/immich_ml/models/clip获取文本嵌入再交给 Postgres 的向量扩展做相似性匹配。ML 服务本身以 gunicorn FastAPI 方式运行入口 machine-learning/immich_ml/main.py模型会话支持 onnxruntime 与 RKNN 两种后端immich_ml/sessions。人脸聚类与存储模板人脸聚类person.service.ts 暴露PersonService人脸检测/嵌入由 ML 容器产出后服务端通过JobName.PersonGenerateThumbnail、JobName.PersonCleanup、JobName.PersonFileMigration等后台作业维护人脸组、缩略图与文件迁移人脸库的 ANN 索引由 ML 侧 C 扩展 machine-learning/ann 提供。自定义存储结构storage-template.service.ts 的StorageTemplateService按用户定义的模板年/月/相册/标签/地理等表达式在新资产入库时计算其最终目录路径对应文档 storage-template.mdx。演示环境与上手验证项目文档提供了一个官方托管的 Web 演示实例用于快速体验完整功能移动端 App 将服务器 URL 指向该演示域名即可连接。演示账号凭据为邮箱demoimmich.app 密码demo在开始自部署前用演示环境熟悉相册、搜索、地图、分享等交互是官方文档建议的上手路径。多语言体系i18n 目录与 Weblate 工作流西语 README 本身就证明了项目的翻译机制仓库根目录 i18n/ 下维护着 80 余种语言的 JSON 翻译文件含es.json、zh_Hans.json、ja.json、de.json等README 的语言导航即指向这些文件如 README_es_ES.md、README_ca_ES.md。翻译工作流文档 translations.md 说明了三点关键设计集中式协作本地化托管在 Weblate 平台上集中管理贡献者可在平台上申请新语言、提交修订ICU 消息格式复数、数字、日期等本地化格式采用 ICU message format运行时由intl-messageformat库处理避免各端各自实现格式化逻辑键一致性校验移动端提供 check_i18n_keys.py 脚本校验各语言文件的键集合与英文基准一致防止翻译缺失导致界面回退。对部署者而言这意味着Immich 的界面语言含西语、简体中文等开箱即用对贡献者而言新增语言只需遵循i18n/目录的命名约定语言代码 可选地区/文字变体如sr_Cyrl.json、yue_Hant.json并通过 CI 的键校验。小结Immich 的仓库文档骨架传递出三个清晰信息3-2-1 备份原则不可妥协——Immich 是备份链中的一环部署形态高度收敛——四个 Docker 服务、一个.env、8GB 内存起步向量检索内建于 Postgres 使架构保持精简能力矩阵端侧分明——管理在 Web、备份与离线在移动端而 Memories、CLIP 搜索、人脸聚类等“智能”功能全部由服务端后台作业 独立 ML 容器驱动并通过每个 service 配套的 spec 测试保证行为可验证。按 docker/ 目录下的 compose 文件与 example.env 起步再对照 docs/docs/install/ 中的安装与升级指南即可完成一次符合官方预期的自托管部署。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考