企业官网建设流程全解析

Immich 自托管照片与视频管理：功能矩阵、快速安装与部署配置详解

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

本文以 Immich 仓库的官方 README（含瑞典语翻译版 readme_i18n/README_sv_SE.md）为主体，系统梳理 Immich 这个高性能自托管照片/视频管理方案的功能全景、官方 Demo 体验方式，并结合仓库中真实的安装脚本、Docker Compose 编排与.env配置示例，讲清楚从零部署到硬件加速的完整实操路径与底层架构映射。

Immich 是什么

Immich 定位为“高性能自托管照片与视频管理解决方案”（High performance self-hosted photo and video management solution），以 AGPLv3 协议开源。它由 Web 端、移动端（Android/iOS）、服务端与机器学习服务共同组成，提供自动备份、人脸识别、语义搜索、共享相册等能力，目标是让用户在自有服务器上拥有完整的数据主权。

README 首页有两条官方提示值得牢记：

• 备份警示：官方反复强调必须遵循 3-2-1 备份策略来保护珍贵的照片和视频（3 份数据、2 种介质、1 份异地），自托管不等于免备份；
• 文档指引：完整的官方文档与安装指南托管在官方站点（immich.app与docs.immich.app），仓库内 docs/ 目录也收录了对应的安装、管理、特性与开发文档。

此外，README 本身支持多语言：readme_i18n/ 下维护着 20 个语言的翻译版 README，其中就包括本文所基于的瑞典语版（README_sv_SE.md）；而面向应用界面的国际化翻译则位于 i18n/ 目录，包含 89 个语言的 JSON 翻译文件（如en.json、zh_Hans.json、sv.json等）。README 末尾还包含贡献者图谱、Star 历史与仓库活跃度等社区统计入口，以及一个可在各语言版本间跳转的语言切换列表。

功能全景：移动端与 Web 端能力矩阵

README 中最核心的技术内容是功能特性矩阵，它明确标注了每项能力在 Mobile 与 Web 两种客户端上的支持情况，是评估部署价值的第一手依据：

注：上表以 readme_i18n/README_sv_SE.md 的瑞典语功能矩阵为准，并补入当前主干英文版 README.md 中新增的 Tags 与 Folder View 两行（瑞典语译本略滞后于主干）。“公开分享”在主干英文版中已同时支持移动端与 Web 端，实际以最新发行版为准。

矩阵中的几项高级能力直接对应 machine-learning/ 子项目的模型实现：

• “按 CLIP 语义搜索”对应 machine-learning/immich_ml/models/clip/ 下的 CLIP 模型（支持文本搜图，如“海边的日落”）；
• “人脸识别与聚类”对应 machine-learning/immich_ml/models/facial_recognition/；
• OCR 能力（文档/照片内文字识别）对应 machine-learning/immich_ml/models/ocr/。

官方 Demo：动手体验 Immich

README 提供了可直接试玩的在线演示环境，无需自行部署即可先感受产品形态：

• 在移动端 App 中，将Server Endpoint URL设置为demo.immich.app（完整地址为https://demo.immich.app）；
• 使用以下凭据登录：

这也可以作为验证你自建服务连通性的参照：如果自建实例登录流程与 Demo 行为不一致，可按 docs/docs/install/post-install.mdx 排查。

快速安装：一键脚本原理与流程

仓库根目录的 install.sh 实现了“一键部署”，阅读其main()流程（install.sh#L73-L102）可以清楚看到它只做了五件事：

1. 创建目录：在当前目录创建./immich-app子目录，若已存在则复用并覆盖其中的 YAML 文件；
2. 下载编排文件：从最新 release 下载docker-compose.yml到该目录（强调：安装应使用当前 release 的编排文件，主干main上的 compose 文件可能与最新发行版不兼容，这一警告同样写在 docker/docker-compose.yml 头部注释中）；
3. 下载并生成 .env：将example.env下载为.env，并通过sha256sum | base64生成随机密码替换默认的DB_PASSWORD；
4. 启动容器：执行docker compose up --remove-orphans -d；
5. 输出访问提示：自动探测主机 IP（macOS 上回退到ipconfig getifaddr en0），提示你通过http://<IP>:2283访问网站或移动端登录。

脚本结束时的提示还给出了安装后的标准配置循环：

1. docker compose down停止容器；
2. 修改.env中的数据库、Redis、备份（上传）位置等配置；
3. docker compose up --remove-orphans -d重新启动。

脚本要求系统已安装docker compose与curl，否则会以明确的退出码报错退出。

手动部署：Docker Compose 四大服务

若要手动安装，参考仓库内 docker/docker-compose.yml（docker/docker-compose.yml#L12-L76），整个部署由 4 个服务组成：

两个数据卷必须落到本地磁盘：

• ${UPLOAD_LOCATION}:/data—— 上传的原始照片/视频与派生文件；
• ${DB_DATA_LOCATION}:/var/lib/postgresql/data—— 数据库文件，官方明确数据库不支持放在网络共享存储上。

.env关键配置项

环境变量模板见 docker/example.env，逐项说明：

一键脚本会自动替你替换DB_PASSWORD；手动安装时必须自行处理。完整的环境变量参考（含 SMTP、OAuth、硬件加速等全部变量）见仓库文档 docs/docs/install/environment-variables.md。

硬件加速：机器学习与视频转码两套配置

Immich 通过extends机制把硬件加速配置拆成了两个附加文件，按需注释启用：

1. 机器学习加速—— docker/hwaccel.ml.yml

在immich-machine-learning服务上启用，支持cpu、armnn（ARM Mali GPU）、rknn（瑞芯微 NPU，需映射/dev/dri并放开 AppArmor）、cuda（NVIDIA）、rocm（AMD）、openvino等后端。compose 文件注释说明：只需在镜像 tag 后追加后端名即可，例如${IMMICH_VERSION:-release}-cuda；openvino-wsl等-wsl变体用于 WSL2 环境。

2. 视频转码加速—— docker/hwaccel.transcoding.yml

在immich-server服务上启用，支持cpu、nvenc（NVIDIA）、quicksync（Intel）、rkmpp（瑞芯威）、vaapi/vaapi-wsl等后端；NVIDIA 场景通过deploy.resources.reservations.devices声明 GPU 能力（compute/video）。

两个文件头部均提示：如果使用 Unraid 等只允许单一 compose 文件的平台，可以把对应后端的配置直接内联到主docker-compose.yml的相应服务中。docker/docker-compose.yml#L16-L18 与 docker/docker-compose.yml#L36-L41 中预留的注释块正是这一机制的挂载点。相关文档位于 docs/docs/install/（requirements.md、docker-compose.mdx、one-click.md、upgrading.md等）。

功能矩阵与仓库结构的对应关系

把 README 的能力清单放回仓库目录，可以验证每项功能都有对应的实现载体：

从源码结构看，服务端通过server/src/workers/中的后台 Worker 消费 Redis 队列执行转码、向量计算等异步任务，这解释了为什么immich-server在 compose 中显式depends_onredis——机器学习结果（人脸、CLIP 向量）先由独立 ML 服务异步产出，再由服务端任务管线落库，从而支撑“搜索按物体、人脸与 CLIP”这类高级检索。

结语：部署要点回顾

• 无论一键脚本还是手动安装，产物都是immich-app目录下的docker-compose.yml+.env，访问入口为http://<IP>:2283；
• DB_PASSWORD必须改为纯字母数字的随机值；UPLOAD_LOCATION与DB_DATA_LOCATION必须指向本地磁盘；
• 有 GPU/NPU 时，按hwaccel.ml.yml（模型 tag 后缀）与hwaccel.transcoding.yml（extends内联）分别加速推理与转码；
• 上线前请把 3-2-1 备份策略落实为定期任务——官方文档中的备份与恢复指引见 docs/docs/administration/backup-and-restore.md。

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