Immich：高性能自托管照片与视频管理方案部署与使用指南

一、项目官方信息

Immich 是一个高性能自托管照片与视频管理方案，定位对标 Google 相册：你把照片视频备份到自己服务器，手机 App 自动备份、网页浏览，并且支持人脸聚类、CLIP 语义搜索、地图时间线、回忆（Memories）等。官方 README 明确警告：珍贵照片视频务必遵循 3-2-1 备份策略。

它的核心能力（README 功能表）包括：App 打开即自动备份、防止重复资源、选择性相册备份、多用户、相册与共享相册、RAW 格式支持、EXIF/地图元数据查看、按元数据/物体/人脸/CLIP 搜索、OAuth、LivePhoto/MotionPhoto 备份与播放、全局地图、搭档共享、人脸识别聚类、回忆（x years ago）、只读画廊、文件夹视图、标签等。

二、官方图片

Immich 官方 README 中的主截图，展示了 Web 端相册时间线与照片浏览界面。

官方提供在线 Demo：https://demo.immich.app，账号 demo@immich.app，密码 demo，可在部署前先体验。

三、环境要求

根据官方文档（https://docs.immich.app/install/requirements）：

• 已安装 Docker 引擎与 Docker Compose 插件。
• 内存 2GB 以上（启用人脸识别/机器学习容器建议 4GB+）。
• 磁盘：存放照片与视频的大容量数据盘；Immich 会在数据盘上生成缩略图与编码缓存。
• 端口：Web 服务默认监听 2283。
• 可选但推荐：NVIDIA GPU（加速机器学习/人脸识别与视频转码）。
• 不支持在树莓派等 ARM 设备上运行机器学习容器（官方要求）。

四、完整部署步骤

1. 准备目录

mkdir -p /opt/immich && cd /opt/immich

2. 下载官方 compose 与环境文件

官方安装方式是从 Release 下载现成的 docker-compose.yml 与示例 .env：

wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

国内服务器若访问 GitHub Release 慢，可配置代理或用 jsdelivr / 镜像加速后再下载，文件内容与官方一致即可。

3. 按需编辑 .env

打开 .env，重点确认两个路径变量，把它们指向你实际存放照片的目录：

# 上传目录（Immich 原生照片库）
UPLOAD_LOCATION=/opt/immich/upload
# 时区
TZ=Asia/Shanghai

UPLOAD_LOCATION 是照片数据落盘的位置，务必指向大容量磁盘，后续迁移也要整体迁移这个目录。

4. 启动服务

docker compose up -d

官方 compose 会拉起以下容器：

• immich-server：主服务（Web + API），监听 2283。
• immich-microservices：后台任务（缩略图、元数据、转码）。
• immich-machine-learning：机器学习（人脸识别、CLIP 搜索），可选但推荐。
• redis：缓存。
• postgres：数据库。

查看日志确认全部就绪：

docker compose ps
docker compose logs -f immich-server

5. 初始化管理员

浏览器打开 http://服务器IP:2283，首次进入会要求创建管理员账号（邮箱 + 密码）。创建后即进入 Web 控制台。

6. 连接手机 App

在 iOS / Android 应用商店安装 Immich App，打开后在「Server Endpoint URL」填入 http://服务器IP:2283，用刚创建的账号登录，即可开启自动备份。

7. 验证

• Web 端能看到时间线，手动上传一张照片成功。
• 手机端拍摄一张照片，等待自动备份出现在 Web 时间线。
• 在「Administration → Jobs」里看到缩略图、元数据任务在跑。

五、使用方法

• 自动备份：手机 App 登录后开启备份，App 打开即自动上传最近照片；可选择只备份特定相册。
• 相册与共享：Web/App 里建相册，可把相册共享给其他用户或生成公开分享链接。
• 人脸识别：在探索页会自动按人脸聚类，可给人物命名；同一人的照片自动归拢。
• 搜索：支持按地点、物体、文字（CLIP）、相机型号等搜索，例如直接搜“海边 狗”。
• 外部库：把已有的照片目录挂载为 External Library，让 Immich 索引但不移动原文件。
• OAuth / SSO：可在设置里对接外部 OAuth 登录，README 功能表明确支持 OAuth。
• 备份提醒：README 强调坚持 3-2-1 备份——Immich 是照片管理工具，不是唯一备份，重要照片请再异地留存一份。

六、常见问题 FAQ

1. 启动后 2283 打不开 / 一直转圈？ 多为数据库或 microservices 未就绪。用 docker compose ps 看容器状态，docker compose logs immich-microservices 查错；首次启动 Postgres 初始化需要稍等。

2. 照片上传了但看不到缩略图？ 缩略图由 immich-microservices 异步生成。到「Administration → Jobs」手动触发 Thumbnail 任务，或等待队列跑完。

3. 人脸识别 / CLIP 搜索不工作？ 需要 immich-machine-learning 容器正常运行，且内存充足（建议 4GB+）。ARM 设备跑不了该容器，这是官方限制。

4. .env 里 UPLOAD_LOCATION 改错了怎么办？ 它决定照片落盘位置，改错会导致照片写到错误磁盘。改完需 docker compose up -d 重建容器；已上传的照片要把旧目录整体迁到新路径。

5. 手机 App 连不上服务器？ 检查 App 里的 Server Endpoint URL 是否填对（含端口 2283）、服务器防火墙是否放行 2283；公网部署建议套反向代理 + HTTPS 后再用域名连接。

6. Immich 能当唯一的照片备份吗？ 不能。README 明确提醒遵循 3-2-1 备份策略，Immich 是管理与浏览工具，重要照片要额外异地备份。

七、跳转链接

• GitHub 仓库：https://github.com/immich-app/immich
• 官方文档：https://docs.immich.app/
• 安装要求：https://docs.immich.app/install/requirements
• 在线 Demo：https://demo.immich.app