Immich 自托管照片视频管理方案：功能体系、部署配置与源码实现解析

Immich 自托管照片视频管理方案功能体系、部署配置与源码实现解析【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immichImmich 是一个高性能的自托管self-hosted照片与视频备份管理解决方案提供移动端与 Web 端双客户端支持自动备份、多用户、智能搜索与人脸识别等能力。本文基于仓库中的土耳其语项目介绍文档 readme_i18n/README_tr_TR.md 展开完整继承其功能特性矩阵与演示信息并结合 install.sh、docker/docker-compose.yml 以及server/src/services下的服务端源码讲清 Immich 的部署方式、运行要求、功能边界与底层实现依据帮助你评估、部署并深入理解这套方案。项目定位与核心主张土耳其语 README 将 Immich 定义为“Yüksek performanslı, kendine ait barındırılan fotoğraf ve video yedekleme çözümü”高性能的自托管照片与视频备份解决方案。这一定位包含三层含义自托管self-hosted所有照片、视频与元数据存储在用户自己的服务器与磁盘上官方提供 Docker Compose 部署方式与一键安装脚本数据归属完全由用户掌控备份backup移动端应用打开时自动备份、支持后台备份与按相册选择性备份是移动设备照片的主要备份目标高性能服务端基于 NestJSTypeScript实现数据库为带向量扩展的 PostgreSQL配合虚拟滚动、缩略图生成与视频转码等机制支撑大体量图库的流畅浏览。文档同时给出两条重要提醒3-2-1 备份策略警告对珍贵的照片与视频应始终遵循 3-2-1 备份方案3 份数据、2 种介质、1 份异地。Immich 作为自托管系统本身是 3-2-1 中的“一份”不能替代完整备份体系官方文档入口包括安装指南在内的正式文档以仓库内的docs/目录为准例如 安装要求、环境变量说明、Docker Compose 安装。部署从一键脚本到 Compose 文件一键安装脚本仓库根目录的 install.sh 是最简部署入口其主流程见 install.sh 起为在当前目录创建./immich-app目录若已存在则覆盖其中的 YAML 文件下载docker-compose.yml与.env文件.env源自仓库中的 docker/example.env为.env中的DB_PASSWORD生成随机密码先尝试sha256sum | base64失败时退化为拼接$RANDOM执行docker compose up --remove-orphans -d启动容器成功后打印访问地址http://IP:2283并提示后续修改.env的标准流程docker compose down→ 修改.env→docker compose up --remove-orphans -d。脚本要求系统已安装docker composeV2 Compose 插件而非已弃用的docker-compose与curl。Compose 四容器架构docker/docker-compose.yml 定义了生产部署的完整拓扑共 4 个服务加 1 个模型缓存卷服务镜像作用与关键点immich-serverghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}主服务暴露端口2283:2283将${UPLOAD_LOCATION}挂载到容器内/data依赖redis与database见 docker-compose.ymlimmich-machine-learningghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}机器学习容器负责 CLIP、人脸识别与 OCR 推理挂载命名卷model-cache:/cache用于缓存模型权重见 docker-compose.ymlredisdocker.io/valkey/valkey:9固定摘要缓存与队列健康检查为redis-cli pingdatabaseghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0固定摘要内置向量扩展的 PostgreSQL 14POSTGRES_INITDB_ARGS: --data-checksums开启数据校验shm_size: 128mb见 docker-compose.yml两个值得注意的工程细节硬件加速是可选扩展server 与 machine-learning 两个服务都预留了extends注释位分别指向 docker/hwaccel.transcoding.yml转码加速nvenc、quicksync、rkmpp、vaapi等与 docker/hwaccel.ml.yml推理加速armnn、cuda、rocm、openvino、rknn等对应官方文档 ML 硬件加速 与 硬件转码Compose 文件须与发布版本匹配文件头注释明确提醒 main 分支的docker-compose.yml可能与最新 release 不兼容应从对应 release 下载。关键环境变量docker/example.env 暴露了安装后必须理解的核心配置# 上传文件的存储位置照片视频本体、缩略图等 UPLOAD_LOCATION./library # 数据库文件存储位置。不支持网络共享盘 DB_DATA_LOCATION./postgres # 时区可选TZ 标识符 # TZEtc/UTC # Immich 版本可固定到具体版本号如 v2.1.0 IMMICH_VERSIONv3 # PostgreSQL 连接口令应改为随机密码仅限 A-Za-z0-9 DB_PASSWORDpostgres # 以下无需修改 DB_USERNAMEpostgres DB_DATABASE_NAMEimmich配合 docs/docs/install/environment-variables.md可以看到这两个位置变量UPLOAD_LOCATION、DB_DATA_LOCATION与 Compose 文件中的挂载行一一对应修改挂载位置的正确方式是改.env而不是改 Compose 的volumes行。硬件与软件要求来自 docs/docs/install/requirements.md 的官方要求是部署前必须核对的清单硬件操作系统推荐 Linux 或 *nix 64 位系统Ubuntu、Debian 等非 Linux 平台的 Docker 体验较差官方明确不推荐且支持能力有限内存最低 6GB推荐 8GB。仅 4GB 内存的机器可以禁用机器学习功能运行CPU最低 2 核推荐 4 核支持amd64与arm64。自v3起amd64平台的 ML 容器要求 x86-64-v2微架构约 2012 年后的大多数 CPU 满足不支持该指令集的 CPU 只能停留在不再受支持的v2.7.5存储推荐支持用户/组权限的 Unix 文件系统EXT4、ZFS、APFS 等缩略图与转码视频平均会使图库体积增加 10-20%Postgres 数据库文件通常为 1-3GBDB_DATA_LOCATION应使用本地 SSD绝不使用任何网络共享若使用 Docker 资源限制Postgres 至少需要 2GB 内存。软件Docker EngineLinux/WSL2或 Docker DesktopWindows/macOS必须带 Compose 插件必须使用docker compose命令旧版docker-compose已弃用不再受 Immich 支持。Windows 用户的特例Postgres 数据必须落在支持属主/权限的文件系统上NTFS/exFAT/WSL 挂载目录均不可用可将.env中DB_DATA_LOCATION./postgres改为DB_DATA_LOCATIONpgdata并在 Compose 底部volumes:下追加pgdata:改用 Docker 命名卷。在线 Demo 与登录凭据README含土耳其语版本提供了官方演示环境便于在部署前体验完整功能Demo 访问地址: https://demo.immich.app 登录凭据: email: demoimmich.app password: demo移动端应用接入 Demo 时将Server Endpoint URL一项填写为https://demo.immich.app即可登录同一演示实例。这为评估搜索、相册、地图等 Web/移动端功能提供了零成本途径。功能特性矩阵以下表格完整继承自土耳其语 README 的功能矩阵Mobile/Web 双端支持情况是了解 Immich 功能边界的权威清单功能MobileWeb上传并查看视频与照片支持支持应用打开时自动备份支持N/A可选定相册进行备份支持N/A将照片与视频下载到本地设备支持支持多用户支持支持支持相册与共享相册支持支持可删除/可拖动的滚动条支持支持RAW 格式支持HEIC、HEIF、DNG、Apple ProRaw支持支持元数据视图EXIF、地图支持支持按元数据、物体、人脸与 CLIP 搜索支持支持管理功能用户管理不支持支持后台备份支持N/A虚拟滚动支持支持OAuth 支持支持支持API 密钥N/A支持LivePhoto 备份与播放iOS支持用户自定义存储结构支持支持公开分享不支持支持归档与收藏夹支持支持世界地图不支持支持伙伴分享Partner Sharing支持支持人脸识别与聚类不支持支持离线支持支持不支持对照英文主 README.md 的功能表可以看到当前主干版本还新增了若干特性资产去重Prevent duplication of assets、360 度全景图显示、Memories多年前的今天、只读图库、堆叠照片Stacked Photos、标签Tags与文件夹视图Folder View且“公开分享”“全球地图”“人脸识别”“LivePhoto 播放”在英文表中已标注为双端或部分支持——说明土耳其语译版相对主干略滞后实际功能应以 README.md 与docs/docs/features/目录如 标签、文件夹视图、人脸聚类、搜索为准。关键功能的源码实现印证以下各节从服务端源码验证上表中最具工程含量的几项功能全部证据来自server/src/services下的 NestJS 服务层。用户自定义存储结构“用户自定义存储结构”由 server/src/services/storage-template.service.ts 实现。该服务基于 Handlebars 模板引擎渲染资产的落盘路径内置 21 个预设模板storage-template.service.ts例如{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}} {{y}}/{{#if album}}{{album}}{{else}}Other/{{MM}}{{/if}}/{{filename}} {{make}}/{{model}}/{{lensModel}}/{{filename}}支持的日期与相机元数据 token 包括y/yy年、M/MM/MMM/MMMM月、d/dd日、W/WW周、h/hh/H/HH时、m/mm分、s/ss/SSS秒以及album、album-startDate-y、make、model、lensModel、filename、assetId等字段见 storage-template.service.ts。从源码结构看模板在ConfigInit/ConfigUpdate事件时编译并缓存onConfigInitConfigValidate事件会用一个模拟资产/upload/test/IMG_123.jpg试渲染来校验模板合法性——这意味着在管理端保存模板前服务端会先做“干跑”验证非法模板不会直接生效。渲染时文件名还会经过sanitize-filename清洗。官方文档 存储模板 给出了更多配置示例。多维度搜索“按元数据、物体、人脸与 CLIP 搜索”对应 server/src/services/search.service.ts。该服务对外暴露的方法覆盖矩阵中提到的全部搜索维度searchPerson按人名查找人脸聚类personRepository.getByName支持withHidden隐藏人员参数searchPlaces按地名搜索searchRepository.searchPlacessearchMetadata按 EXIF/元数据条件组合检索支持按 checksum28 位 base64 或 hex精确定位资产并通过albumIds与共享链接shared link访问控制做权限收敛getExploreData探索视图聚合“最多城市”与“最近添加”两组数据maxFields: 12, minAssetsPerField: 5语义搜索依赖SmartSearchDto与isSmartSearchEnabled开关并将 CLIP 文本向量结果放入一个容量 100 的 LRU 缓存embeddingCache以减少对 ML 服务的重复请求。CLIP 向量之所以能落库查询与 Compose 中数据库镜像自带vectorchordpgvectors扩展直接对应语义侧的推理模型位于 machine-learning/immich_ml/models/clip 目录。人脸识别与聚类矩阵中“人脸识别与聚类Web 支持”由 server/src/services/person.service.ts 的服务端部分与 ML 容器协同完成人脸特征提取在machine-learning容器的 facial_recognition 模型 中执行服务端负责聚类分组、命名与展示对应文档 更好的面孔聚类 与 人脸识别。转码、HLS 与后台任务Web 端流畅播放视频依赖服务端转码server/src/services/transcoding.service.ts管理转码作业hls.service.ts 提供 HLS 分片播放流queue.service.ts 负责后台任务队列调度与redis容器配合job.service.ts 管理任务状态。这也解释了为什么 Compose 中 server 容器依赖redis——缩略图生成、转码、缩略图清理等都走异步队列。API 密钥与多用户矩阵中“API 密钥仅 Web 支持”由 server/src/services/api-key.service.ts 实现配合 docs/docs/features/command-line-interface.md 中提到的 CLIpackages/cli允许用户用个人密钥以编程方式访问自己的数据例如脚本化上传见 docs/docs/guides/python-file-upload.md。多用户与认证由auth.service.ts、user-admin.service.ts等承担OAuth 配置见 docs/docs/administration/oauth.md。翻译生态与本文档的位置土耳其语 README 是 Immich 官方翻译体系的一部分readme_i18n/目录存放 22 个语言的 README 译本README_tr_TR.md即其一由根 README.md 的语言导航入口统一链接产品界面翻译由仓库根i18n/目录维护覆盖 100 语言文件如 i18n/tr.json、i18n/en.json翻译贡献流程见 docs/docs/developer/translations.md。这也意味着阅读土耳其语文档的社区成员与英文社区获得的是同一份功能与版本语义翻译版本仅存在措辞层面的滞后。备份策略提醒与总结Immich 的 README 反复强调 3-2-1 备份原则自托管服务器只是备份链中的一环重要照片视频仍应保持多份、多介质、异地的完整策略。仓库内 docs/docs/administration/backup-and-restore.md 也提供了服务端自身的备份与恢复指导。综合来看Immich 的技术形态可以概括为部署侧4 容器 Compose 架构server machine-learning redis 向量版 Postgres一键脚本 install.sh 完成初始化UPLOAD_LOCATION/DB_DATA_LOCATION双位置变量掌控全部数据落盘功能侧以移动端自动备份为入口Web 端承载管理、分享与高级检索功能矩阵中“N/A/不支持”的边界如移动端的 API 密钥、Web 端的后台备份清晰明确实现侧NestJS 服务层 Handlebars 存储模板 向量数据库搜索 异步任务队列各功能点均可在server/src/services/中找到对应实现ML 能力独立容器化并支持多种硬件加速后端。对于需要完全掌握自己照片数据、又希望获得接近云端相册体验智能搜索、人脸聚类、地图、分享的自托管用户这套“Docker 部署 移动/Web 双端 可插拔 ML 加速”的架构是完整可复现的方案。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考