图_1数据存储模块
对应 [[1_项目设计#3.1 数据存储模块|《1_项目设计》3.1 数据存储模块]] 的实现代码；风格参考 3DGS 笔记的“目录 → 文件 → 类 / 函数 → 编号功能说明”。
如何读图
-
每个框的标题采用“名称 + 12 个空格 + 一句话职责”；框内保留编号功能说明。
-
最外层是 backend；内部按真实目录分为 infra、db、indexing，根目录另放 env.py。
-
database.py 和 env.py 保留文件粒度；cache.py、models.py 及两个索引存取文件按必要的类或功能块展开。
-
每条编号说明一个关键接口或职责；编号属于当前小框，不是整个系统的执行顺序。
-
只画一条跨文件依赖箭头 Base；ParentChunkStore 的三个依赖直接写在文件框内，避免交叉连线。
主要关系
- 环境准备：load_env() → 导入存储模块；配置在模块初始化时读取。
- 关系库建表：models 中四个类继承 Base；init_db() 导入模型，再调用 metadata.create_all()。
- 父块存取：ParentChunkStore 调用 SessionLocal、ParentChunk 和 cache，组合 PG 持久化与 Redis 缓存。
- Milvus 访问：MilvusStore 经 milvus_client_session() 完成短连接操作；get_milvus_store() 复用的是 Store 实例。
对应文件
- backend/env.py：环境变量加载。
- backend/infra/database.py：引擎、会话工厂、ORM 基类、建表与 SQL 参数净化。
- backend/infra/cache.py：RedisCache 和共享 cache 实例。
- backend/db/models.py：User、ChatSession、ChatMessage、ParentChunk。
- backend/indexing/milvus_client.py：Milvus 配置、连接和集合读写 / 检索。
- backend/indexing/parent_chunk_store.py：父块 PG / Redis 存取。
范围
本图只覆盖本篇实现部分，不加入后续章节的文档解析、Embedding、Agent、接口鉴权或上传任务。字段与 ER 关系仍见 [[图_7数据库ER关系|图7]]；存储设计仍见 [[图_6数据存储与状态|图6]]。
文档中的验证入口为 test/1_test_storage.py，分别验证 PostgreSQL、Redis、Milvus 与 ParentChunkStore；测试代码位于 backend 目录之外，因此不放入目录框。
图形与文字没有组合，可分别调整矩形宽高；文字保留框内绑定。
Excalidraw Data
Text Elements
backend/ 实现后端业务与存储支撑 ^cc4a8c3c
[[1_项目设计#1）env.py|env.py]] 统一加载项目环境变量
- load_env()：读取根目录 .env，只加载一次
- 在导入其他存储模块前调用 ^6f16b9d5
infra/ 提供数据库连接与缓存访问 ^41821a7f
db/ 声明关系数据库的 ORM 模型 ^fd5f0af5
indexing/ 提供文档索引与知识库存取 ^0ac06ab3
[[1_项目设计#1）database.py|database.py]] 配置关系库连接与建表能力
- engine：配置 PostgreSQL 引擎
- SessionLocal：创建数据库会话
- Base：提供 ORM 声明基类
- init_db()：导入模型并创建数据表
- before_cursor_execute()：SQL 执行前净化参数
- _clean_nul_chars()：递归清洗字符串 ^8dd7cfc9
[[1_项目设计#2）cache.py|cache.py]] 封装 Redis 缓存访问 ^87a2fe7b
RedisCache 统一缓存读写与清理
- init()：读取连接、键前缀与 TTL
- _get_client()：按需创建 Redis 客户端
- get_json()：读 JSON；未命中 / 异常返回 None
- set_json()：写 JSON 并设置过期时间
- delete() / delete_pattern()：按键 / 模式删除 ^68d9715f
cache = RedisCache()：供其他模块共享 ^c3f73b5b
[[1_项目设计#1）models.py|models.py]] 声明四类持久化数据模型 ^1d473581
User 定义账号与角色
- 声明 users 表：账号、密码哈希、角色
- sessions：关联用户的会话 ^918d8453
ChatSession 定义会话及用户、消息关联
- 声明会话及 metadata_json
- 限定同一用户下 session_id 唯一
- 关联所属用户和消息列表 ^e4bc7e08
ChatMessage 定义消息正文与检索轨迹
- 声明消息正文、类型、时间与 rag_trace
- 关联所属会话；随会话级联删除 ^757c58c5
ParentChunk 定义 L1/L2 父级文本块
- 声明 L1/L2 父块全文与来源
- 保存块层级及父子关联 ID ^1a3c3328
四个类均继承 database.py 中的 Base。 ^814bfc21
[[1_项目设计#1）milvus_client.py|milvus_client.py]] 封装 Milvus 集合与检索操作 ^e9148e0b
MilvusSettings 读取并保存 Milvus 连接配置
- from_env()：读取地址、Collection 与超时配置 ^def65414
milvus_client_session() 管理一次客户端连接的创建与关闭
- 创建客户端 → yield 供调用 → finally 关闭连接 ^55c98026
MilvusStore 提供集合管理、数据读写与检索
- _run() / session()：通过上述短连接执行操作
- init_collection() → ensure_collection()：创建字段、BM25 Function 与索引
- insert()：写入 L3 数据；query() / query_all()：条件 / 分页查询
- get_chunks_by_ids()：按 chunk_id 批量取块
- dense_retrieve()：Dense 检索
- hybrid_retrieve()：Dense + BM25 → RRF → 返回候选
- delete()：删除匹配记录；has_collection()：检查集合
- drop_collection()：删除整个集合 ^4bdaa6c7
get_milvus_store() 获取可复用的 MilvusStore 实例
- 按需创建并复用 Store 实例；不缓存客户端连接 ^0a76d9e9
[[1_项目设计#2）parent_chunk_store.py|parent_chunk_store.py]] 封装父块持久化与缓存 ^be0e64b5
ParentChunkStore 管理父块的持久化与缓存
- upsert_documents()：更新 / 插入父块，写 Redis，最后提交 PG
- get_documents_by_ids()：先查 Redis；未命中批查 PG 并回填缓存
- delete_by_filename()：删除 PG 父块，再清除对应缓存
- _to_dict() / _cache_key()：转换 ORM 记录 / 生成父块缓存键 ^fa7d7ce1
依赖：SessionLocal + ParentChunk + cache 本文件只负责父块存取，不负责文档分块或向量化。 ^66f5582c
Base ^6fa1d818
主要依赖：models.py → database.Base；ParentChunkStore → SessionLocal / ParentChunk / cache。 ^a323acb4
Element Links
6f16b9d5: [[1_项目设计#1）env.py]]
8dd7cfc9: [[1_项目设计#1）database.py]]
87a2fe7b: [[1_项目设计#2）cache.py]]
1d473581: [[1_项目设计#1）models.py]]
e9148e0b: [[1_项目设计#1）milvus_client.py]]
be0e64b5: [[1_项目设计#2）parent_chunk_store.py]]
%%
Drawing
1 | N4KAkARALgngDgUwgLgAQQQDwMYEMA2AlgCYBOuA7hADTgQBuCpAzoQPYB2KqATLZMzYBXUtiRoIACyhQ4zZAHoFAc0JRJQgEYA6bGwC2CgF7N6hbEcK4OCtptbErHALRY8RMpWdx8Q1TdIEfARcZgRmBShcZQUebR4ATm0ARho6IIR9BA4oZm4AbXAwUDBSiBJuCAAzAHZiAFZcTWSAFjTSyFhESsDsKI5lYPayzG4W+v4ymG5kgGYJosgKEnVu |
%%
