100 万级照片不卡顿：Immich 数据库索引优化与 PostgreSQL 维护深度实战。

当你的 Immich 相册库突破 100 万张照片时，你会发现之前的所谓“优化”在绝对的数据量面前都是毛毛雨。你会遇到 Web 端全局搜索时数据库 CPU 瞬间锁死、侧边时间轴拖动卡顿、甚至是简单的照片重命名都要转圈。

作为一个处理过 PB 级数据的底层架构师，我得告诉你：Immich 的性能瓶颈不在它的 Node.js 后端，而在那台被埋在 Docker 里的 PostgreSQL。如果不对 pgvector 索引和数据库内存参数进行“手术级”调整，百万级图库只会是你 NAS 的负担。

💡 报错现象总结：当照片总数突破百万量级，执行“智能搜索”或刷新“地图视图”时，immich_postgres 容器频繁报出 server closed the connection unexpectedly。查询 pg_stat_activity 会发现大量的 vector_cosine_ops 计算处于 Active 状态，单次查询延迟超过 10 秒。

---

内存溢出的真相：为什么 pgvector 索引会失效？

Immich 依靠 pgvector 插件进行 HNSW 索引查询。这种索引本质上是在内存中构建一个巨大的“近邻图”。

在默认配置下，PostgreSQL 的 work_mem 通常只有 4MB。当你尝试在 100 万个维度高达 512 或 768 的特征向量中搜索时，数据库会因为内存不足被迫将搜索索引“换出”到磁盘。磁盘 I/O 代替了内存计算，这就是你搜索卡死的根本原因。

-- 架构师深度诊断：查看当前向量索引的构建状态
-- 如果你的 ef_construction 设得太低，百万量级下的搜索精度和速度都会崩盘
SELECT relname, n_tup_ins, n_tup_upd, n_tup_del 
FROM pg_stat_user_tables 
WHERE relname = 'smart_search_embeddings';

针对百万级数据的数据库参数调优建议：

参数名称	官方/默认值	百万级调优值	架构师调优逻辑
shared_buffers	128MB	机型内存的 25%	确保核心元数据和热点索引常驻内存
work_mem	4MB	64MB - 128MB	为复杂的向量排序提供充足的内存空间
maintenance_work_mem	64MB	1GB+	加速大规模导入时的索引重建速度
max_parallel_workers	8	根据核心数设定	开启并行扫描，压榨多核 CPU 性能

---

索引竞态：时间轴拖动的“隐形杀手”

除了搜索，百万级数据下的时间轴缩略图加载也极度考验数据库。每一屏滚动都会触发一次复杂的 SQL 查询，带有 ORDER BY captureDateTime DESC 这种全表扫描性质的操作。

如果你的数据库没有针对这个字段建立完美的 B-Tree 索引，或者索引因为频繁的删除和重新导入产生了严重的碎片（Bloat），数据库执行计划就会误判，选择最慢的扫描方式。

---

填坑实战：给 PostgreSQL 做“深层除垢”

面对百万级库的卡顿，你不得不执行以下硬核维护操作：

1. 手动执行 VACUUM FULL：在大规模清理或迁移照片后，数据库实际上并没有释放物理空间。你需要强制收缩数据文件，这能显著提升磁盘扫描效率。
2. HNSW 索引重构：当数据量翻倍后，你需要调整 m（最大连接数）和 ef_construction（构建动态列表大小）参数来重造向量索引。虽然这可能需要跑几个小时，但能让搜索延迟从 10 秒降到 200 毫秒。
3. 分离 WAL 日志存储：如果你的 NAS 有多块盘，尝试将数据库的事务日志（WAL）放在独立的 NVMe SSD 上。这能解决“写入锁”导致的浏览卡顿。

这种“重装上阵”式的维护，是维持超大规模自建系统稳定的必经之路。

---

降维打击：获取 GitCode 《Immich 百万级数据库性能调优 SQL 套餐》

与其在卡顿的界面前怀疑人生，不如直接给数据库换个“引擎”。

我已经针对百万级照片库的极端场景，在 GitCode 维护了一个**《Immich 百万级数据库性能调优 SQL 套餐》**。这个套餐包含了全套的 postgresql.conf 优化脚本，以及专门针对 pgvector 大规模数据集优化的索引重建命令。

直接前往 GitCode 访问这些方案。别让技术瓶颈限制了你的记忆收藏，用最专业的数据库运维方案，支撑起你的数字遗产。

[获取 GitCode 《Immich 百万级数据库性能调优 SQL 套餐》]