先说问题:全家人的照片,正在替别人交「房租」
手机相册是普通人最大的一笔数字资产:孩子的成长记录、旅行照片、证件扫描件,一年几千张往上走。云端相册看着方便,代价也明确:免费空间早就不够用,订阅按月扣费;原图可能被压缩;哪天账号出问题或服务调整政策,十几年的照片说没就没。更现实的是,很多人家里其实躺着一台 7×24 开机的服务器或者 NAS,硬盘空间大把,却没用在最该用的地方。
Immich 就是把这件事接回来的工具:开源、自建,体验对标 Google 相册——时间线浏览、人脸分组、地图视图、智能搜索、手机 App 自动备份一应俱全,照片原图躺在你自己的硬盘上。本篇按官方推荐的 Docker Compose 架构完整部署一套,并把手机备份、外部图库、机器配置这些真正影响长期使用体验的环节讲透。部署前的整机规划可以先看 自建服务入门:从一台 VPS 开始的完整规划;如果你已经有网盘类服务在跑,也可以先读系列里的 Cloudreve 私人云盘篇,想清楚照片到底归哪套系统管——结论先说:通用文件归网盘,照片和视频交给 Immich,两者分工不重叠。
架构先行:四个容器,各干一件事
Immich 不是单容器应用,官方 Compose 是四个服务协同,先理解架构再动手,后面排障会轻松很多:
| 容器 | 作用 | 说明 |
|---|---|---|
| immich-server | 主服务 | 提供 Web 界面与 API、处理上传、管理图库,监听 2283 端口 |
| immich-machine-learning | 机器学习 | 人脸识别、智能搜索的向量计算,独立容器方便单独加速或迁移 |
| database | PostgreSQL 数据库 | 存照片元数据、向量数据,用的是带向量扩展的定制镜像 |
| redis | 缓存/队列 | 任务队列与缓存,官方新版 Compose 已换成 Valkey 镜像,作用相同 |
两个关键点先记住:第一,数据库用的是 Immich 官方定制的 PostgreSQL 镜像(带 VectorChord 等向量扩展),不要图省事换成通用 postgres 镜像,智能搜索会直接罢工,升级时也不要擅自跨大版本换数据库镜像;第二,机器学习容器是整套系统里最吃资源的,模型文件要单独缓存,它慢不等于主服务坏了。
部署:官方 Compose 落地
新建一个目录,比如 /opt/immich,在里面放两个文件。先是 .env:
# 照片库存放位置(原图+缩略图,空间要留足)UPLOAD_LOCATION=./library# 数据库存放位置(务必放在本地 SSD 上)DB_DATA_LOCATION=./postgres# 镜像版本,release 表示跟随最新正式版IMMICH_VERSION=release# 数据库密码,换成你自己的强密码DB_PASSWORD=请换成强密码DB_USERNAME=postgresDB_DATABASE_NAME=immich再是 docker-compose.yml(结构与官方仓库当前版本一致,细节以官方最新文件为准):
name: immich
services: immich-server: container_name: immich_server image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release} volumes: - ${UPLOAD_LOCATION}:/data - /etc/localtime:/etc/localtime:ro env_file: - .env ports: - 2283:2283 depends_on: - redis - database restart: always
immich-machine-learning: container_name: immich_machine_learning image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release} volumes: - model-cache:/cache env_file: - .env restart: always
redis: container_name: immich_redis image: docker.io/valkey/valkey:8-bookworm restart: always
database: container_name: immich_postgres image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0 environment: POSTGRES_PASSWORD: ${DB_PASSWORD} POSTGRES_USER: ${DB_USERNAME} POSTGRES_DB: ${DB_DATABASE_NAME} POSTGRES_INITDB_ARGS: '--data-checksums' volumes: - ${DB_DATA_LOCATION}:/var/lib/postgresql/data restart: always
volumes: model-cache:cd /opt/immichdocker compose up -ddocker compose logs -f immich-server日志滚动到服务监听后,浏览器打开 http://服务器IP:2283,第一个注册的账号就是管理员。和所有自建服务一样,这个位置要第一时间自己占住,并设强密码。
WARNINGImmich 官方在文档里明确提醒:该软件仍在快速开发中,不应被视为照片的唯一存放方式。Immich 是相册系统,不是备份系统本身——原图目录和数据库必须再有一份独立备份(见下文),否则硬盘坏掉时,相册做得再漂亮也救不回来。另外,数据库目录千万不要放在 NFS、SMB 这类网络盘上,PostgreSQL 在网络文件系统上极易损坏;照片库目录相对宽容,但为了缩略图生成速度,同样建议本地盘。
机器配置要求:别让老硬件拖垮体验
Immich 的资源消耗主要来自三处:上传时的转码与缩略图生成、机器学习的人脸/向量计算、PostgreSQL 数据库。参考配置:
| 项目 | 最低可用 | 舒适推荐 |
|---|---|---|
| CPU | 2 核(支持 AVX 的 x86 或 ARM64) | 4 核以上 |
| 内存 | 4 GB(官方下限附近,需加 swap 兜底) | 6–8 GB 以上 |
| 数据库盘 | 本地 SSD | NVMe SSD |
| 照片盘 | 按存量 + 未来 3 年增量预留 | 机械盘阵列或大容量 SSD 均可 |
| GPU | 不需要 | 可选:给机器学习容器换 CUDA 镜像加速识别 |
两个经验值:第一,老 CPU 没有 AVX2 时机器学习会明显变慢甚至跑不动部分模型,批量导入几万张照片时尤其明显,耐心等或错峰跑;第二,数据库盘的速度直接决定时间线滑动和搜索的跟手程度,把 DB_DATA_LOCATION 放在 SSD 上,是整套系统性价比最高的一笔投入,照片原图放机械盘完全没问题。
手机 App 自动备份:装好之后就不用再管
Immich 的手机 App(iOS / Android 官方应用商店均可下载)是整套体验的核心,配置一次,之后全自动:
- 打开 App,服务器地址填
http://服务器IP:2283(内网)或后面配好的 HTTPS 域名; - 用管理员或自己的账号登录;
- 点右上角云朵图标进入备份设置,打开「自动备份」,勾选要备份的相册(相机胶卷必选,微信、截图相册按需);
- 按需开启「仅 Wi-Fi 时备份」「仅充电时后台备份」,避免流量和电量焦虑;
- 首次备份建议连着充电器、亮着屏跑完存量,之后增量都是秒传。
备份完成后,Web 端时间线里就能按年月日浏览全部照片,同一张照片在手机删掉本地副本也不影响服务器上的原图——这才是「备份」该有的样子。给家人开账号时,每个人独立账号、独立图库,管理员在后台创建即可,互不可见。
外部图库:把已有的照片盘接进来
很多人部署 Immich 之前,照片已经躺在某个目录里了(比如 NAS 的共享盘、从旧网盘导出的存档),没必要重新上传一遍。用外部图库只读挂载进来即可。先给 immich-server 服务追加一行挂载:
volumes: - ${UPLOAD_LOCATION}:/data - /mnt/photos-archive:/mnt/photos-archive:ro注意末尾的 :ro 只读标记不能省。然后 docker compose up -d 重建服务,再到 Web 界面:右上角头像 → 管理 → 外部图库 → 创建图库,导入路径填容器内路径 /mnt/photos-archive,指定归属用户,保存后手动触发一次扫描。Immich 只读取和建立索引,不改动原文件,原始目录结构原封不动。后续往这个目录里丢新照片,Immich 会按计划自动重新扫描;也可以在图库设置里做排除规则,跳过缓存目录之类的杂项。
外部图库和上传图库的区别要拎清:上传的照片归 Immich 全权管理(包括 App 里删除即真删),外部图库只读索引、不能在 Immich 里删原文件。珍贵存档用外部图库挂载更稳妥,日常手机照片走 App 备份,两条线并行不悖。
智能功能:人脸分组与智能搜索
机器学习容器就绪后(首次启动要下载模型,耐心等它跑完,docker compose logs -f immich-machine-learning 能看到进度),两个能力会陆续生效:
- 人脸识别:自动把同一人的人脸聚成一组,在「探索」页给人物命名之后,就能按人翻照片,给孩子建一个从出生到现在的自动相册毫无压力;
- 智能搜索:基于 CLIP 模型的语义搜索,搜「海边」「雪」「猫」这类场景词就能出结果,不依赖文件名和标签。默认模型对中文支持一般,可以在管理后台的机器学习设置里更换为多语言 CLIP 模型,中文搜索会准很多。
批量导入后的第一个晚上,建议让机器通宵跑任务队列:缩略图、人脸、向量都在排队生成,期间界面能用但搜索结果不全,这是正常现象,不是故障。
对外访问与 HTTPS
手机在外面也要能自动备份,就需要一个 HTTPS 入口,做法与系列其他服务一致:用 Nginx Proxy Manager:所有自建服务的统一入口 新增 Proxy Host 指向 2283 端口并申请证书。Immich 会上传原图视频,体积大,记得在 NPM 的高级配置里放开请求体大小限制:
client_max_body_size 0;同时把代理超时调大,避免长视频上传中途被掐断。安全方面,Immich 是全家照片的总仓,管理后台和图库绝不能裸奔在公网弱口令之下:强密码、关闭不必要的公开分享、只给家人开账号,具体原则见 自建服务安全加固:最小暴露与访问控制。
备份:相册系统的备份要备两样东西
Immich 的完整备份 = 照片库目录 + 数据库导出,缺一不可:
- 照片库:
UPLOAD_LOCATION指向的目录,含原图、缩略图、转码视频,直接按目录打包或用同步工具做异地副本; - 数据库:存着相册结构、人物、标签等全部元数据,用容器内的 pg_dump 导出:
docker exec -t immich_postgres pg_dumpall -c -U postgres | gzip > immich-db-$(date +%F).sql.gz(容器名以你自己的 Compose 为准。)把两样东西按 3-2-1 原则纳入整机备份计划,脚本化方法见 自建服务备份与迁移实战。另外 Immich 自身升级较频繁,升级前先做一次完整备份,跨版本回滚时数据库能救命。
常见问题与排障
App 连不上服务器。 先在手机浏览器里直接打开同一个地址验证可达;内网用 IP+2283,走域名要确认 HTTPS 证书有效;公司或校园网拦截非标端口时,统一走 443 反向代理最省心。
照片上传了但没有缩略图、人脸识别不动。 十有八九是机器学习容器没正常工作:docker compose logs immich-machine-learning 看是否在反复报错或还在下载模型;内存不足被 OOM 杀掉也会这样,docker compose ps 看它是不是在反复重启,小内存机器先加 swap。
时间线滑动卡顿、搜索很慢。 检查数据库是不是被你放在了机械盘或网络盘上,迁回本地 SSD 立竿见影;照片量特别大时,也可以适当调高 PostgreSQL 的共享内存配置。
数据库容器起不来。 常见原因是数据目录权限不对或放在了不支持的文件系统上;确认 DB_DATA_LOCATION 是本地目录、属主正确,再看 docker compose logs database 的第一条报错。
升级之后 Web 界面 500 或功能异常。 Immich 有时要求 server 与 machine-learning 镜像版本严格一致,两边都用同一个 IMMICH_VERSION;先看官方发布说明有没有破坏性变更,再决定是否升级,出问题就用升级前的备份回滚,别在故障现场硬修数据库。
小结
Immich 是自建服务里最能提升全家人幸福感的一个:按官方四容器架构部署,数据库放 SSD,手机 App 打开自动备份存量一次跑完,再把旧照片盘用外部图库只读挂进来,人脸分组和智能搜索会让翻照片从「找文件」变成「逛相册」。最后记住那句官方提醒——它再好用也只是相册系统,原图和数据库的独立备份一天都不能少。做到这几点,云端相册的订阅就可以停了。