1. 项目概述：RAGFlow 四层存储不是“堆砌”，而是精密齿轮咬合

你打开 RAGFlow 的文档，看到“元数据”“对象”“检索”“缓存”四个词并列排开，第一反应可能是——这又是个术语堆砌的宣传话术？我试过直接照着文档跑 demo，结果批量上传 PDF 后查个“合同违约金条款”，返回结果要么驴唇不对马嘴，要么卡在“正在处理中”十分钟不动。后来我把整个存储链路拆开，在本地搭了四套独立日志埋点，连续压测三天，才真正看懂这四层不是平行关系，而是一套环环相扣的流水线：元数据是调度员，对象是原料库，检索是质检台，缓存是速运通道。它解决的从来不是“能不能查”，而是“查得准不准、快不快、稳不稳、省不省”。比如你上传 500 份采购合同，系统要从 200 万 token 的文本里精准定位“供应商延迟交货的违约金计算方式”，这个过程里，元数据决定“去哪找”，对象存储保证“找得到原始内容”，检索引擎负责“找得对”，缓存则确保“下次再问不用重来一遍”。这四层一旦某处松动，比如元数据没打上“合同类型=采购”标签，或者缓存策略把高频查询的法律条文误判为冷数据清掉了，整个 RAG 效果就断崖式下跌。所以这篇不是讲概念定义，而是带你用运维视角看日志、用开发视角看代码、用产品视角看效果，把 RAGFlow 存储架构拆成可触摸、可调试、可优化的实体。无论你是刚接触 RAG 的业务方，还是正在调参的算法工程师，或是负责部署的 SRE，只要你想让 RAG 不再是“玄学黑盒”，这篇就是你的实操地图。

2. 四层存储设计逻辑：为什么必须是四层，而不是三层或五层？

2.1 元数据层：不是“标签”，而是决策中枢

很多人把元数据理解成给文件加个“作者”“创建时间”这种基础信息，这是最大的误区。在 RAGFlow 里，元数据是整个检索流程的“交通指挥中心”。它不存原文，只存“如何找到原文”的指令集。举个真实案例：我们给某律所部署时，客户要求区分“判决书”“起诉状”“代理意见”三类文书，且判决书必须按“案由”（如劳动争议、买卖合同）二次过滤。如果只用文件名或后缀做元数据，系统根本无法识别“（2023）京0101民初123号民事判决书.docx”里的案由。RAGFlow 的解法是：在解析阶段强制注入结构化元数据字段，比如{"doc_type": "judgment", "case_category": "labor_dispute", "court_level": "primary"}。这些字段会写入专用元数据数据库（默认 PostgreSQL），并在后续所有环节被实时调用。

为什么非得单独一层？因为元数据有三大刚性需求：高并发读写、强一致性、低延迟索引。如果把它和原始对象混存在 MinIO 或 S3 里，每次检索前都要先下载整个对象再解析 JSON，光网络 IO 就拖垮性能。而独立元数据层用 B-Tree 索引，WHERE doc_type = 'judgment' AND case_category = 'labor_dispute'这种查询毫秒级响应。我们实测过，当元数据量超 10 万条时，混合存储方案平均查询延迟飙升到 1.2 秒，而独立元数据层稳定在 8ms。更关键的是，元数据层支持动态 Schema —— 你可以随时新增is_confidential: bool字段控制权限，无需迁移历史数据。这背后是 PostgreSQL 的 JSONB 类型和 GIN 索引的组合拳，不是简单贴个标签能实现的。

2.2 对象存储层：不是“存文件”，而是保真原料仓

对象层常被误认为就是“把 PDF 丢进 MinIO”，但 RAGFlow 的对象存储有两重使命：保真性和可追溯性。保真性指原始文件的每一个字节、每一页布局、每个嵌入图片都必须 1:1 还原。我们遇到过客户上传扫描版合同，OCR 后发现公章位置偏移 2 像素，导致关键条款被切到下一页——对象层必须保留原始 PDF 的完整二进制流，而非仅存 OCR 文本。可追溯性则要求每个对象有唯一指纹（SHA256），且与元数据强绑定。比如上传一份《2024 年供应商协议》，系统会生成对象 IDobj_7a8b9c，同时在元数据表里写入object_id: "obj_7a8b9c"和source_hash: "sha256_xxx"。这样当用户反馈“查不到第 5 条付款方式”，运维能立刻用SELECT * FROM metadata WHERE source_hash = 'sha256_xxx'定位到具体对象，再用minio client cat mybucket/obj_7a8b9c下载原始文件复现问题。

为什么不用数据库 BLOB？因为对象层要扛住海量小文件（单次上传 1000+ PDF）。PostgreSQL BLOB 在 10 万文件量级时，VACUUM 压力会让整个库锁表数分钟。而 MinIO 的分布式对象存储，通过纠删码（Erasure Coding）把 1 个文件切片存到 4 个节点，既防止单点故障，又让吞吐量线性增长。我们压测时用fio模拟 500 并发上传 1MB 文件，MinIO 集群（3 节点）吞吐达 1.8GB/s，PostgreSQL BLOB 仅 120MB/s。更隐蔽的设计是对象层的“版本快照”机制：每次文件更新，不是覆盖原对象，而是生成新 IDobj_7a8b9c_v2，旧版本仍可回溯。这对法律、医疗等强审计场景是刚需——你能证明“2024 年 3 月 1 日生效的协议版本”和“2024 年 6 月修订版”的差异，靠的就是对象层的不可篡改性。

2.3 检索层：不是“搜关键词”，而是语义精算台

检索层常被简化为“向量相似度匹配”，但 RAGFlow 的检索是多级精算流水线。第一级是元数据过滤（Metadata Filtering），第二级是向量召回（Vector Retrieval），第三级是重排序（Reranking）。以查询“员工离职补偿金计算标准”为例：

• 元数据过滤：先筛出doc_type = 'labor_regulation' AND effective_date <= '2024-06-01'的法规文件，瞬间从 10 万文档缩到 200 份；
• 向量召回：对这 200 份文档的 chunk 向量做近邻搜索（ANN），用 FAISS 的 IVF_PQ 算法，召回 top-50 相似 chunk；
• 重排序：用 Cross-Encoder 模型（如 bge-reranker-base）对 50 个 chunk 重新打分，把真正讨论“N+1 补偿”的 chunk 排到前 3。

为什么不能只用向量检索？因为向量空间里，“离职”和“辞职”语义相近，但法律效力天差地别。我们测试过纯向量方案，在 1000 份劳动法规中召回准确率仅 63%，而三级精算后达 92%。更关键的是检索层的“chunk 策略”：RAGFlow 默认用语义分块（Semantic Chunking），不是按固定长度切文本。它会识别“第十二条”“【免责声明】”这类标题节点，确保法律条款不被截断。我们对比过固定 512 字符分块，发现 23% 的关键条款（如违约金计算公式）被切到两个 chunk 里，导致检索失效。而语义分块通过 spaCy 的依存句法分析，把“违约金 = 未履行部分价款 × 10%”完整保留在一个 chunk 中，这才是法律 RAG 的底线。

2.4 缓存层：不是“存结果”，而是智能流量调度器

缓存层最容易被当成“把检索结果存 Redis”，但 RAGFlow 的缓存是带上下文感知的智能网关。它缓存的不是最终答案，而是“检索中间态”：包括元数据过滤后的文档 ID 列表、向量召回的 chunk ID 及相似度分数、重排序后的 top-k chunk ID。这样当用户连续问“补偿金标准”“代通知金怎么算”“经济补偿金个税怎么交”，系统能复用第一次的元数据过滤结果（都是劳动法规），只重跑向量和重排序，节省 60% 计算量。我们实测过，对同一知识域的连续 5 次查询，缓存命中率从 0%（首次）升到 89%（第五次），P95 延迟从 2.1s 降到 0.4s。

为什么缓存要分层？因为不同环节的时效性要求不同：元数据过滤结果可缓存 1 小时（法规更新不频繁），向量召回结果缓存 10 分钟（语义向量相对稳定），重排序结果只缓存 1 分钟（用户意图可能突变）。RAGFlow 用 Redis 的 TTL 机制实现分级过期，还内置了缓存穿透防护——当查询“不存在的法规名称”时，不会让请求穿透到后端，而是缓存一个空结果（null）并设短 TTL（30 秒），避免恶意刷量击穿数据库。更绝的是缓存预热：系统启动时自动加载高频查询（如“劳动合同法第三十八条”）的缓存，用户首问就能秒回。这背后是 Redis 的SCAN+EXPIRE组合，不是简单SET key value能搞定的。

3. 四层协作实操：从上传文件到返回答案的全链路拆解

3.1 文件上传阶段：元数据注入与对象落盘

当你点击“上传合同”按钮，RAGFlow 的后台其实启动了精密的协同作业。第一步是元数据预提取：系统用python-magic库识别文件 MIME 类型（application/pdf），用pdfplumber读取 PDF 元数据（如Author,Producer），同时调用自定义规则引擎。比如检测到文件名含“采购合同”，自动注入{"contract_type": "purchase", "party_a": "XXX科技有限公司"}。这步耗时约 120ms，全部在内存完成，不碰对象存储。

第二步是对象分片与落盘：PDF 被pdfplumber解析为页面，每页用layoutparser检测文本块、表格、图片区域。文本块按语义切分（如标题+正文为一个 chunk），每个 chunk 生成唯一 IDchunk_abc123，连同原始坐标（page: 5, x1: 100, y1: 200）存入对象存储。注意：原始 PDF 二进制流和所有 chunk 的坐标信息，都作为独立对象存入 MinIO，路径为raw/{file_id}.pdf和chunks/{chunk_id}.json。我们曾因跳过坐标存储，导致用户点击答案时无法高亮原文位置，被迫返工重跑 2 万份文件。

第三步是元数据持久化：把file_id,chunk_ids,extracted_metadata写入 PostgreSQL。这里有个关键参数metadata_ttl（默认 3600 秒），它控制元数据缓存过期时间。我们建议生产环境设为 1800 秒——太短增加 DB 压力，太长导致元数据更新延迟。SQL 执行示例：

INSERT INTO documents (id, name, mime_type, source_hash, metadata) VALUES ('doc_xyz789', '采购合同2024.pdf', 'application/pdf', 'sha256_abc...', '{"contract_type":"purchase","party_a":"XXX科技"}'); -- 同时插入 chunks 关联表 INSERT INTO document_chunks (doc_id, chunk_id, page_num) VALUES ('doc_xyz789', 'chunk_abc123', 5);

这步完成后，对象层和元数据层就完成了“原料入库”，但此时还不能检索——因为向量还没生成。

3.2 向量化阶段：检索层的“原料加工”

向量化不是后台默默运行的黑盒，而是检索层的主动加工。RAGFlow 默认用bge-m3模型，但关键在分块向量化策略。它不把整篇 PDF 喂给模型，而是对每个chunk_abc123单独编码。每个 chunk 的向量维度是 1024，存入 FAISS 索引。这里有两个魔鬼细节：

• 向量归一化：FAISS 要求所有向量 L2 范数为 1，否则余弦相似度计算失真。RAGFlow 在vectorize_chunk()函数里强制执行vector = vector / np.linalg.norm(vector)；
• 索引分片：当 chunk 总数超 100 万，FAISS 的 IVF_PQ 索引会分 1000 个聚类中心（nlist=1000），每个中心管 1000 个 chunk。我们压测发现，nlist 设为 500 时，召回率下降 7%，但构建速度加快 40%——需根据硬件权衡。

向量化完成后，检索层会生成index.faiss文件存入对象存储，并在元数据表里更新vector_index_path: "indexes/doc_xyz789.faiss"。此时检索层才算“备料完成”。我们曾因磁盘满导致index.faiss写失败，系统日志只报Index build failed，最后发现是 MinIO 的usages指标爆红，扩容后解决。所以务必监控 MinIO 的disk_usage和 PostgreSQL 的pg_stat_database.blks_hit（缓存命中率）。

3.3 查询执行阶段：四层实时协同流水线

用户输入“供应商延迟交货的违约金怎么算？”，RAGFlow 启动四层联动：

1. 元数据层响应：查询SELECT id FROM documents WHERE contract_type = 'purchase' AND status = 'active'，返回 37 个doc_id；
2. 对象层加载：并发拉取这 37 个文档的vector_index_path，用faiss.read_index()加载索引到内存；
3. 检索层计算：对问题文本编码，用index.search()在 37 个索引中并行召回，合并后取 top-50 chunk_id；
4. 缓存层介入：检查cache.get("rerank_input_doc_xyz789_chunk_abc123")，若命中则跳过重排序，直接取缓存分数；
5. 结果组装：用chunk_id查对象存储获取原文，按重排序分数拼接答案，并注入来源链接（/document/doc_xyz789#page=5）。

这个过程里，缓存层是真正的“润滑剂”。我们抓包发现，一次查询平均触发 12 次 Redis 请求：3 次元数据缓存（文档列表、字段映射、权限策略），5 次向量缓存（各索引的 top-k 结果），4 次重排序缓存。如果禁用缓存，P99 延迟从 1.8s 暴涨到 4.3s。但缓存也有陷阱：当用户问“最新版采购合同”，而缓存里存的是旧版结果，必须用cache.delete_pattern("doc_xyz789*")清除关联缓存。RAGFlow 的DocumentService.refresh_cache()方法就是干这个的，它会在文档更新时自动触发。

3.4 缓存治理实战：如何避免“缓存雪崩”和“脏数据”

缓存不是设个 TTL 就完事。我们在线上踩过三个大坑：

• 雪崩陷阱：所有缓存用相同 TTL（如 3600 秒），整点时大量 key 同时过期，Redis QPS 瞬间从 2000 冲到 15000，后端服务被压垮。解法是给 TTL 加随机扰动：ttl = 3600 + random.randint(0, 600)，让过期时间分散在 ±10 分钟内；
• 脏数据陷阱：用户修改了合同 PDF，但元数据里的effective_date没更新，缓存仍返回旧版结果。我们强制要求：任何文档更新操作，必须调用CacheManager.invalidate_related(doc_id)，它会删除doc_id相关的所有缓存 key（doc:{id}:meta,doc:{id}:vector:*,chunk:{id}:rerank）；
• 内存泄漏陷阱：Redis 的maxmemory设为 4GB，但INFO memory显示used_memory_human长期 3.9GB，mem_fragmentation_ratio达 1.8。排查发现是缓存 key 过长（含完整 chunk 文本），改成只存chunk_id，用对象存储查原文，内存占用直降 65%。

现在我们的缓存治理 SOP 是：

1. 每日凌晨 2 点执行redis-cli --scan --pattern "doc:*" | xargs redis-cli del清理僵尸 key；
2. 每 5 分钟用redis-cli info keyspace监控db0:keys=12345,expires=12300，若expires接近keys，说明过期策略失效；
3. 对高频查询（如“劳动合同法”）启用cache.persist()，将其转为永久 key，避免反复计算。

这套组合拳让线上缓存命中率稳定在 78%，P95 延迟波动小于 ±0.1s。

4. 四层问题排查：从日志、指标到代码级定位

4.1 元数据层问题：查不到文档？先盯住 PostgreSQL 的慢查询

当用户说“我上传的合同怎么搜不到”，90% 的根因在元数据层。第一反应不是查向量，而是看 PostgreSQL 日志。我们配置了log_min_duration_statement = 1000（记录超 1 秒的 SQL），发现典型问题：

• 缺失索引：SELECT * FROM documents WHERE contract_type = 'purchase'没走索引，EXPLAIN显示Seq Scan。解法：CREATE INDEX idx_contract_type ON documents USING btree (contract_type)；
• JSONB 查询慢：WHERE metadata @> '{"is_confidential": true}'耗时 2.3s。解法：建 GIN 索引CREATE INDEX idx_metadata_gin ON documents USING GIN (metadata)；
• 锁等待：SELECT * FROM pg_locks l JOIN pg_stat_activity a ON l.pid = a.pid WHERE a.state = 'active'发现UPDATE documents SET metadata = ...长时间持有行锁。原因是批量更新时没分页，改成UPDATE ... WHERE id IN (SELECT id FROM documents WHERE ... LIMIT 1000)。

我们把常用诊断 SQL 写成脚本：

# 检查慢查询TOP5 psql -c "SELECT query, total_time, calls FROM pg_stat_statements ORDER BY total_time DESC LIMIT 5;" # 检查索引使用率 psql -c "SELECT indexrelname, idx_scan FROM pg_stat_user_indexes WHERE idx_scan = 0;"

这些命令放在/opt/ragflow/bin/diagnose.sh，运维一键执行。

4.2 对象层问题：文件打不开？用 MinIO 的 heal 命令照妖

对象层问题往往表现为“文件损坏”“图片不显示”。这不是 RAGFlow 的 bug，而是 MinIO 的存储健康问题。我们线上集群曾因磁盘坏道，导致raw/contract.pdf的部分分片丢失。症状是用户下载文件时，浏览器报ERR_CONTENT_LENGTH_MISMATCH。解法不是重传，而是用 MinIO 自带的mc admin heal：

# 检查所有桶的健康状态 mc admin heal myminio/ # 修复指定桶 mc admin heal myminio/mybucket

heal命令会比对纠删码校验和，自动从其他节点恢复损坏分片。我们把它加入 crontab 每 2 小时执行一次：

0 */2 * * * /usr/local/bin/mc admin heal myminio/ >> /var/log/minio-heal.log 2>&1

另外，对象层问题常伴随S3Error: NoSuchKey，这其实是元数据里object_id和 MinIO 实际路径不一致。用SELECT object_id FROM documents WHERE name = 'xxx.pdf'查出 ID，再mc ls myminio/mybucket/ | grep {object_id}确认是否存在。不一致就手动同步或删掉元数据记录。

4.3 检索层问题：答案不相关？FAISS 的 nprobe 参数是开关

检索结果驴唇不对马嘴，大概率是 FAISS 的nprobe参数没调好。nprobe控制搜索时访问的聚类中心数量，默认 10。值太小（如 1），只查最近的 1 个中心，召回率暴跌；值太大（如 100），查遍所有中心，延迟翻倍。我们用faiss.ParameterSpace().set_index_parameter()动态调优：

# 在检索前设置 index.nprobe = 20 # 平衡速度与精度 # 或根据查询长度自适应 if len(query) > 50: index.nprobe = 30 # 长查询需要更广搜索 else: index.nprobe = 15 # 短查询侧重速度

另一个关键是向量维度对齐。我们曾把bge-m3（1024 维）换成text2vec-large-chinese（768 维），但忘了重建 FAISS 索引，导致index.add()报Dimension mismatch。解决方案是：换模型必跑ragflow-cli rebuild-index --model text2vec-large-chinese，它会清空旧索引，重新向量化所有 chunk。

4.4 缓存层问题：命中率低？用 Redis 的 monitor 实时抓包

缓存命中率低于 50%？别急着调 TTL，先用redis-cli monitor抓实时请求：

# 在 Redis 服务器执行 redis-cli monitor | grep -E "(GET|SET|DEL)"

你会看到类似：

1712345678.123456 [0 127.0.0.1:56789] "GET" "doc:xyz789:meta" 1712345678.123457 [0 127.0.0.1:56789] "SET" "doc:xyz789:meta" "..." "EX" "3600" 1712345678.123458 [0 127.0.0.1:56789] "GET" "chunk:abc123:rerank"

如果GET后紧跟SET（即每次都未命中），说明 key 名设计有问题。比如我们曾用chunk:{id}:{query_hash}作 key，但query_hash稍有变化（空格、标点）就生成新 key，导致命中率不足 10%。改成chunk:{id}:rerank_v1（固定版本号），命中率升至 85%。

此外，用redis-cli --bigkeys找内存大户：

redis-cli --bigkeys | grep "string" # 找大字符串key # 发现 cache:full_text_search_result 占 120MB，立即优化为只存 top-3 chunk_id

5. 四层优化进阶：从可用到高性能的实战技巧

5.1 元数据层优化：用物化视图加速复杂查询

当元数据字段增多（如contract_type,party_a,effective_date,jurisdiction），多条件组合查询变慢。我们放弃在应用层拼 SQL，改用 PostgreSQL 物化视图：

-- 创建物化视图，预计算常用组合 CREATE MATERIALIZED VIEW mv_contract_search AS SELECT id, name, metadata->>'contract_type' as contract_type, metadata->>'party_a' as party_a, (metadata->>'effective_date')::date as effective_date, metadata->>'jurisdiction' as jurisdiction FROM documents WHERE metadata ? 'contract_type'; -- 刷新视图（每天凌晨） REFRESH MATERIALIZED VIEW CONCURRENTLY mv_contract_search;

查询时直接SELECT * FROM mv_contract_search WHERE contract_type='purchase' AND jurisdiction='beijing'，速度提升 12 倍。注意CONCURRENTLY参数允许刷新时不锁表，这是生产环境必备。

5.2 对象层优化：MinIO 的纠删码配比调优

MinIO 默认纠删码是EC:4（4 数据块 + 4 校验块），适合高可靠性场景。但我们发现，对于 RAGFlow 的 chunk 小文件（平均 2KB），EC:2（2+2）更优：

• 存储开销从 200% 降到 100%（省一半磁盘）；
• 小文件写入吞吐从 800MB/s 提升到 1.2GB/s；
• 重建速度加快 3 倍（坏盘恢复更快）。
  调整命令：

# 停止 MinIO systemctl stop minio # 重建集群，指定 EC:2 minio server --erasure-set=2 http://node{1...4}/data{1...4}

代价是容错能力降为“最多坏 2 块盘”，但配合 RAID10，实际风险可控。

5.3 检索层优化：FAISS 的 GPU 加速实战

CPU 版 FAISS 在百万 chunk 下，单次召回耗时 300ms。我们用 NVIDIA T4 GPU（16G 显存）加速：

import faiss # 加载 GPU 版本 res = faiss.StandardGpuResources() gpu_index = faiss.index_cpu_to_gpu(res, 0, index) # 0 表示 GPU 0 # 搜索 D, I = gpu_index.search(query_vector, k=50)

实测 P95 延迟从 320ms 降到 45ms。但要注意：GPU 显存必须大于索引大小。我们用faiss.index_memory_usage(index)测出 100 万 chunk 索引占 1.2G 显存，T4 完全够用。如果显存不足，用faiss.index_cpu_to_gpu_multiple分片加载。

5.4 缓存层优化：Redis 的 LFU 策略替代 LRU

默认 LRU（最近最少使用）对 RAG 场景不友好——某个冷门法规被查一次，就挤掉高频的《劳动合同法》缓存。我们改用 LFU（最不经常使用）：

# Redis 配置文件 maxmemory-policy allkeys-lfu lfu-log-factor 10 # 调高衰减因子，让热度更持久 lfu-decay-time 1 # 每分钟衰减热度

然后用redis-cli --hotkeys查热点 key：

redis-cli --hotkeys | grep "doc:" # 输出 doc:labour_law:rerank_v1 (120 hits)

对这类 key，我们手动EXPIRE doc:labour_law:rerank_v1 86400设为 24 小时永不过期，确保核心法规永远在缓存里。

6. 四层扩展思考：当业务规模突破单机瓶颈

6.1 元数据层扩展：从 PostgreSQL 到 Citus 分片集群

当文档量超 1000 万，单 PostgreSQL 压力山大。我们迁移到 Citus（PostgreSQL 扩展），把documents表按tenant_id分片：

-- 在 Citus coordinator 节点执行 SELECT create_distributed_table('documents', 'tenant_id'); SELECT create_distributed_table('document_chunks', 'doc_id');

查询时SELECT * FROM documents WHERE tenant_id = 'law_firm_a'自动路由到对应 worker 节点，QPS 从 1200 提升到 8500。关键经验：分片键必须是高频查询条件，我们选tenant_id（律所/企业租户），因为 95% 查询都带租户隔离。

6.2 对象层扩展：MinIO 多集群联邦

单 MinIO 集群跨机房延迟高。我们用 MinIO Federation，把北京、上海、深圳集群组成联邦：

# 启动联邦模式 minio server --address :9000 \ http://bj-node{1...3}/data{1...4} \ http://sh-node{1...3}/data{1...4} \ http://sz-node{1...3}/data{1...4}

用户上传时，mc cp contract.pdf myminio/mybucket/自动选择最近集群（北京用户走 BJ 集群），但所有集群数据全局一致。联邦的代价是跨集群同步延迟（<500ms），对 RAG 的最终一致性足够。

6.3 检索层扩展：FAISS 的分布式索引

单机 FAISS 顶不住亿级 chunk。我们用faiss.contrib.ondisk构建磁盘索引：

# 构建 ondisk 索引 index = faiss.index_factory(1024, "IVF1000,PQ32") faiss.write_index(index, "/mnt/ssd/index.ivf") # 搜索时 mmap 加载 index = faiss.read_index("/mnt/ssd/index.ivf", faiss.IO_FLAG_MMAP)

再用 Nginx 负载均衡分发查询到 5 台检索服务器，每台管 2000 万 chunk，P95 延迟仍控制在 120ms 内。

6.4 缓存层扩展：Redis Cluster 的 slot 迁移

当 Redis 单节点内存超 32G，必须分片。我们用 Redis Cluster，按 key 前缀分 slot：

• doc:*→ slot 0-5000
• chunk:*→ slot 5001-10000
• query:*→ slot 10001-16383
  迁移命令：

# 将 slot 0-5000 迁到新节点 redis-cli --cluster reshard 127.0.0.1:7000 --cluster-from {old_node_id} --cluster-to {new_node_id} --cluster-slots 5000

迁移时业务无感，因为客户端自动重定向。我们用redis-cli --cluster check每周验证集群健康。

我在实际部署中发现，四层扩展不是“一步到位”，而是按业务压力点逐层突破：先扛住元数据查询洪峰（Citus），再解决对象存储 IO 瓶颈（MinIO Federation），最后优化检索延迟（FAISS GPU）。每次扩展前，必做三件事：1）用pg_stat_statements找出 TOP1 SQL；2）用minio admin prometheus看磁盘 IO wait；3）用redis-cli --latency测缓存延迟。数据不会说谎，它会明确告诉你，下一个该拧紧哪颗螺丝。