Immich：自建照片视频库
Immich 是高性能自托管照片与视频管理应用，也是最流行的 Google Photos 开源替代品之一。 它提供 Web 与移动端上传、相册共享、时间线、地图、EXIF、RAW、LivePhoto、语义搜索、人脸识别与自动备份等能力，采用 AGPL-3.0 许可证。
Pigsty 的 app/immich 模板使用 Docker Compose 拉起 Immich 应用层，并使用 Pigsty 托管的 PostgreSQL 保存元数据。
当前模板按 Immich v3 组织，默认使用 VectorChord 作为相似图片、智能搜索与人脸检索的向量扩展。
相比 Immich 官方的单机 Compose 模板，这里的关键差异是：PostgreSQL 不再跑在应用容器里，而是交给 Pigsty 管理，从而获得监控、备份、PITR、扩展管理与高可用接入能力。
快速开始
Immich 建议至少 2C / 6GB 内存，流畅使用建议 4C / 8GB 内存；v3 的 amd64 机器学习镜像需要 x86-64-v2 指令集。生产环境建议使用 Linux 与本地 SSD。
在运行 兼容操作系统 的全新 Linux x86 / ARM 服务器上执行：
curl -fsSL https://repo.pigsty.cc/get | bash; cd ~/pigsty
./bootstrap
./configure -c app/immich
vi pigsty.yml # 必改：密码、域名、媒体文件路径
./deploy.yml # 安装 Pigsty 与 PostgreSQL
./docker.yml # 安装 Docker 和 Compose
./app.yml # 安装 Immich
默认入口：
http://photo.pigsty
http://10.10.10.10:2283
如果使用 photo.pigsty，请在浏览器所在主机添加 hosts 解析，或将模板中的域名替换为真实域名。
模板结构
conf/app/immich.yml 定义了单节点 Immich 自建模板。默认拓扑包括：
immich：Immich Server、Machine Learning 与本地 Valkey/Redis 容器所在节点。pg-immich：Pigsty 托管的 PostgreSQL 数据库集群。infra：Nginx 入口、Grafana、VictoriaMetrics 等基础设施。etcd：Patroni 所需的分布式配置存储。
应用容器包括：
immich-server：API、Web UI 与后台任务，默认监听宿主机2283端口。immich-machine-learning：CLIP 与人脸识别模型推理。redis：本地 Valkey 队列与缓存。
模板不会启动 Immich 上游 Compose 中的 PostgreSQL 容器；数据库由 Pigsty 通过 DB_URL 提供。
数据存储策略
Immich 的状态被拆成三层，请分别管理：
- 媒体文件：原图、原视频、缩略图、转码视频、头像与上传队列，保存在
UPLOAD_LOCATION对应的宿主机目录。 - PostgreSQL：保存用户、相册、资产、EXIF、文件路径、任务状态、人物、人脸与智能搜索向量等元数据。
- Valkey/Redis：保存队列、缓存与运行时状态，不应当作为权威数据源。
照片和视频本体不会写入 PostgreSQL。反过来，Immich 也不会把媒体目录当成唯一真相重新扫描出完整业务状态；数据库里保存的路径与元数据同样关键。
因此，一个可恢复的 Immich 备份必须同时包含 PostgreSQL 与媒体目录。只备份数据库会丢照片，只备份文件也无法可靠恢复相册、用户、分享、人脸与检索状态。
PostgreSQL
默认数据库连接与向量扩展：
DB_URL=postgresql://dbuser_immich:DBUser.Immich@10.10.10.10:5432/immich
DB_VECTOR_EXTENSION=vectorchord
模板会在 pg-immich 集群安装扩展包并创建数据库扩展：
CREATE EXTENSION vchord CASCADE;
CREATE EXTENSION earthdistance CASCADE;
vchord 需要通过 pg_libs 加入 shared_preload_libraries，模板已经配置：
pg_extensions: [ pgvector, vchord ]
pg_libs: 'vchord.so, pg_stat_statements, auto_explain'
这里默认使用直连 PostgreSQL 的 5432 端口。不要把 Immich 指向事务池模式的 PgBouncer；迁移、索引和预备语句场景下，直连 PostgreSQL 或 session pooling 更稳妥。
Immich 官方仍然把预置 PostgreSQL 视为高级用法，但同时明确这种模式可以解锁 pgBackRest / Barman 这类 WAL 流式备份。Pigsty 模板选择无超级用户路径：由 Pigsty 预先创建数据库、用户和扩展，Immich 业务用户不需要 PostgreSQL 超级用户权限。
媒体文件
Immich 上传的照片、视频、缩略图、转码文件和头像保存在宿主机目录，也就是模板中的 UPLOAD_LOCATION：
/data/immich/library
PostgreSQL 只保存元数据和文件路径。媒体文件不在 PostgreSQL 中，也不会被 pgBackRest 自动保护。
生产环境至少需要备份两层数据：
- PostgreSQL：使用 Pigsty pgBackRest / PITR。
- 媒体文件：对
/data/immich/library做完整文件级备份，覆盖其中的原图、上传队列、缩略图、转码文件、头像与其他生成资产。
如果需要更一致的组合备份，先停止 immich-server，再同时备份数据库和媒体目录。如果业务不能停止，则建议先备份数据库，再备份文件系统。
镜像与网络
默认镜像来自 GHCR 与 Docker Hub：
docker pull ghcr.io/immich-app/immich-server:v3
docker pull ghcr.io/immich-app/immich-machine-learning:v3
docker pull docker.io/valkey/valkey:9
如果拉取镜像较慢或受限，请在 pigsty.yml 中配置 proxy_env 或 docker_registry_mirrors。
运维命令
安装后进入 /opt/immich：
cd /opt/immich
make up # 启动 Immich
make logs # 跟随日志
make info # 查看容器状态
make pull # 拉取镜像
make restart # 重启容器
make down # 停止并移除容器
如需固定具体 Immich 版本，在 pigsty.yml 中设置：
IMMICH_VERSION: v3.0.1
升级 Immich 或 VectorChord 前，请先阅读上游 release notes。VectorChord 包升级后，通常还需要在 immich 数据库中更新扩展并重建相关索引：
ALTER EXTENSION vchord UPDATE;
REINDEX INDEX face_index;
REINDEX INDEX clip_index;
大型图库重建索引可能耗时较长，执行前请确认已有备份和维护窗口。
参考
- Immich 项目： https://github.com/immich-app/immich
- Immich 预置 PostgreSQL： https://docs.immich.app/administration/postgres-standalone/
- Immich 备份与恢复： https://docs.immich.app/administration/backup-and-restore/
- Pigsty Immich 模板： https://github.com/pgsty/pigsty/blob/main/conf/app/immich.yml
- Pigsty Docker 模块
- Pigsty Nginx 入口