Immich 3.3.5 上手：自托管相册部署、外部库与备份升级要点

Immich 是一个开源的自托管照片与视频管理服务，服务端跑在自己的机器上，手机端负责自动备份。时间线、相册、人脸聚类、语义搜索和 OCR 都在本地完成，素材不交给第三方云端。想脱离按容量计费的网盘、又不想丢掉手机自动备份的人，通常会先看它。

Immich 是什么：自托管相册与手机备份服务

它的形态接近一个自建的相片云。服务端存原图、生成缩略图、维护元数据，Web 端和 Android、iOS 客户端负责浏览与上传。项目以 AGPL-3.0 许可开源，由 FUTO 支持开发，GitHub 仓库目前显示约 11.8 万 star、约 7,500 个 fork。

和网盘的区别在于职责划分。网盘以文件为单位同步，相册只是附带视图；Immich 以资产为单位建库，时间线、地点、人物、标签都是数据库里的一等字段。因此换客户端、换域名都不影响库的结构。

架构拆成四块：Postgres 数据库、Redis 任务队列、Node 服务、独立的机器学习容器。官方 Compose 文件已经把四者串好，不需要自己拼装。

授权方式比较特别。官方购买页写明买断不给额外功能，单人 25 美元、家庭 100 美元，属于支持性质。功能上不设付费墙，这一点和常见的开源加闭源双版本模式不同。

部署方式：Docker Compose 三件套与硬件门槛

官方把 Docker Compose 作为生产部署的推荐方式。下载 docker-compose.yml 与 example.env，把后者改名 .env，再改三个变量：UPLOAD_LOCATION 指向素材目录、DB_DATA_LOCATION 指向数据库目录、DB_PASSWORD 换成随机值。之后执行 docker compose up -d 启动。

硬件门槛不算低。官方要求页给的是内存 6GB 起、推荐 8GB，CPU 2 核起、推荐 4 核。只有 4GB 内存的机器要关掉机器学习功能才跑得动。

存储要留余量。缩略图与转码视频通常让库体积多出 10-20%。数据库文件在 1-3 GB 之间，必须放本地 SSD，文档明确不支持网络共享。

v3 起还有一条指令集要求：amd64 上的机器学习容器需要 x86-64-v2，多数 2012 年之后发布的 CPU 满足。不满足的话只能停在 v2.7.5，而这个版本已经不再维护。

Windows 用户容易卡在数据库目录。Postgres 数据不能放在 NTFS 或 WSL 的 /mnt 挂载下，要把 .env 里的 DB_DATA_LOCATION 改成 Docker volume。

macOS 与 Windows 上用 Docker Desktop 也能跑。官方文档把非 Linux 环境标为不推荐，排障时能给到的支持会相应减少。

端口暴露不要照搬示例。默认只在内网使用的话，把 2283 限制在局域网内，再按需通过反向代理加一层认证；打算放到公网，就要同时处理证书与访问控制，别只做端口转发。

外部库与目录：把已有照片挂进来

外部库适合已经有整理好目录的人。扫描时 Immich 读取磁盘上的文件并生成资产，不复制原图，这些资产会进主时间线，也能加相册、看地图。

限制要提前知道。按外部库文档，一个外部库只能属于一个用户。在 Immich 里加的相册归类、描述等元数据只存在数据库里，不会写回文件。

文件在库内换目录后重新扫描，会被当成新资产，之前加的元数据随之丢失。文件在磁盘上被删，重扫会移入回收站，30 天后清空。

扫不出来时按这份清单排查：

• Compose 里 volumes 是否同时挂给了 server 与 worker 容器。
• 导入路径是否与容器内看到的路径一致。
• 不要用符号链接，也不要跨 Docker 挂载做链接。
• 目录权限与属主是否正确。
• 路径写正斜杠，不要用反斜杠。

两条路可以并用：新照片走手机上传，历史库用外部库只读挂载。这样既保住老目录的结构，也不至于把几百 GB 再复制一遍。

搜索、人脸与 OCR 的能力边界

搜索走 Postgres 加 VectorChord 扩展，CLIP 模型负责图文匹配。默认模型偏快，换成更大的模型结果更细，代价是更慢、更吃内存。

可筛选的维度不少：人物、文件名或扩展名、原始路径、描述、图片里的文字、地点、标签、相机型号、时间段、媒体类型、星级。

中文提示词要换模型。默认英文 CLIP 对中文查询的召回有限，搜索文档里单独列了多语言模型一栏，换之前先算清内存预算。

语义搜索依赖索引任务跑完。刚导入大批素材时，搜索结果会滞后一段时间，要等队列里的 Smart Search 任务处理完才准。

人脸聚类不保证一次分对。同一个人被拆成多个簇、或者陌生人被误合并，都要在界面上手动合并与拆分，这部分目前仍需人工收拾。

备份、升级与版本策略的坑

数据库只存路径与元数据，服务端不扫描库目录。这意味着数据库备份和文件备份两样都要做，备份文档建议按 3-2-1 策略留多份。

自动备份默认每天 2:00 生成，保留 14 份，落在 UPLOAD_LOCATION/backups 下。它只含元数据，不含照片和视频。

文件侧要备份的是几个目录：library 放原图，encoded-video 放转码结果，profile 放头像，backups 放数据库导出。恢复时目录结构与数据库备份要成对还原，缺一样都会出现空缩略图或打不开的资产。

升级流程是改 .env 里的 IMMICH_VERSION，再执行 docker compose pull 与 docker compose up -d。大版本带破坏性变更，升级前要读发布说明。

升级文档写得很直接：官方不给降级，也不为旧版本回补补丁。服务端只与同大版本的客户端兼容，稳妥做法是先升手机端，再升服务端。

v3.0.0 于 2026-07-01 发布，破坏性变更主要落在 API 端点，影响的是对接 API 的第三方工具。多数人按常规方式更新即可。目前稳定版是 v3.3.5，10 月 30 日放出了 v3.4.0-rc.1 预览版。

适合谁用，怎么开始

适合有 NAS 或常开小主机、在意原图与元数据归属、也愿意自己维护升级的人。它把相册和手机备份收在一个服务里，长期看省下的是订阅费。

不适合完全不想碰命令行的人，也不适合需要厂商服务承诺的场景。它本质是自建服务，出问题要自己查日志、自己判断是磁盘、网络还是模型的问题。

按这台机器的用途挑版本也有讲究。追稳定就用 v3 这类大版本标签，跟着补丁走；想提前试新功能再切到 release candidate 通道，但别在只存着一份照片的机器上这么干。

1. 准备机器：至少 2 核 4GB 内存，数据盘按库体积再加两成留空间。
2. 拉两个文件：docker-compose.yml 与 example.env，把后者改名 .env。
3. 改 UPLOAD_LOCATION、DB_DATA_LOCATION、DB_PASSWORD，然后 docker compose up -d。
4. 装手机端，先备份一个相册验证链路，再放开全量备份。
5. 配好数据库定时备份与文件同步，两步都做完再往里搬老照片。

如果同时还要归档文档，Paperless-ngx 上手那套流程和这里的思路相近。机器上跑着多个服务时，Beszel 轻量服务器监控这类工具能提前发现磁盘写满。部署编排本身可以看Coolify 自托管部署平台的做法。