agentic_huge_data_base / wiki
页面 Cognee · 7.3 存储配置·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 7.3

7.3 · 存储配置（Storage Configuration）

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目Cognee 章节7.3 状态全文译文 模块存储与持久化、配置治理、测试、发布与运维、图谱与关系
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Storage Configuration 上一章7.2 下一章8
源码线索
  • cognee/base_config.py
  • cognee/context_global_variables.py
  • cognee/eval_framework/modal_eval_dashboard.py
  • cognee/infrastructure/databases/graph/config.py
  • cognee/infrastructure/databases/graph/get_graph_engine.py
  • cognee/infrastructure/databases/utils/get_or_create_dataset_database.py
  • cognee/infrastructure/databases/vector/config.py
  • cognee/infrastructure/databases/vector/create_vector_engine.py
  • cognee/infrastructure/databases/vector/get_vector_engine.py
  • cognee/infrastructure/files/storage/LocalFileStorage.py
模块标签
  • 存储与持久化
  • 配置治理
  • 测试、发布与运维
  • 图谱与关系
  • 文档对象与元数据

章节正文

存储配置

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/7.3-storage-configuration

存储配置

相关源文件

本章引用的主要源码文件：

  • cognee/base_config.py
  • cognee/context_global_variables.py
  • cognee/eval_framework/modal_eval_dashboard.py
  • cognee/infrastructure/databases/graph/config.py
  • cognee/infrastructure/databases/graph/get_graph_engine.py
  • cognee/infrastructure/databases/utils/get_or_create_dataset_database.py
  • cognee/infrastructure/databases/vector/config.py
  • cognee/infrastructure/databases/vector/create_vector_engine.py
  • cognee/infrastructure/databases/vector/get_vector_engine.py
  • cognee/infrastructure/files/storage/LocalFileStorage.py
  • cognee/infrastructure/files/storage/S3FileStorage.py
  • cognee/infrastructure/files/storage/s3_config.py
  • cognee/infrastructure/files/utils/open_data_file.py
  • cognee/modules/graph/methods/delete_data_related_edges.py
  • cognee/modules/graph/methods/delete_data_related_nodes.py
  • cognee/modules/graph/methods/get_dataset_related_edges.py
  • cognee/modules/graph/methods/get_dataset_related_nodes.py
  • cognee/modules/ingestion/data_types/S3BinaryData.py
  • cognee/modules/users/models/DatasetDatabase.py
  • cognee/root_dir.py
  • cognee/shared/lru_cache.py
  • cognee/tasks/ingestion/resolve_data_directories.py
  • cognee/tests/test_s3_file_storage.py

本文档介绍了 Cognee 的文件存储配置系统，该系统控制原始数据文件、数据库文件和缓存数据的存储方式与存储位置。存储后端可以配置为使用本地文件系统或 AWS S3。

适用范围：本文涵盖文件存储配置、目录结构以及存储抽象层。关于数据库特定配置（向量数据库、图数据库、关系型数据库），请参见数据库配置与选择。关于通用系统配置，请参见配置系统。关于安全相关的存储设置，请参见安全配置。

存储后端架构

Cognee 实现了一个可插拔的存储后端系统，将文件操作抽象在通用接口之后。这使得可以在不更改应用程序代码的情况下，在本地文件系统和云存储（S3）之间无缝切换。

存储提供者关联

下图将自然语言描述的存储概念与实现这些概念的具体代码实体关联起来。

Cognee · 存储提供者关联 · 图 1
Cognee · 存储提供者关联 · 图 1

来源：cognee/infrastructure/files/storage/S3FileStorage.py:23-31、cognee/modules/ingestion/data_types/S3BinaryData.py:21-25、cognee/tasks/ingestion/resolve_data_directories.py:10-22、cognee/base_config.py:11-16

配置管理

存储配置通过 BaseConfig 类以及 S3 和数据库后端的专用配置模型进行管理。

核心存储设置

BaseConfig 类定义了整个系统的根目录。它使用 pydantic.model_validator 确保所有路径都是绝对路径。

变量代码实体默认值描述
DATA_ROOT_DIRECTORYBaseConfig.data_root_directory.data_storage原始用户数据的根目录
SYSTEM_ROOT_DIRECTORYBaseConfig.system_root_directory.cognee_system系统文件（数据库）的根目录
CACHE_ROOT_DIRECTORYBaseConfig.cache_root_directory.cognee_cache临时制品的根目录
LOGS_ROOT_DIRECTORYBaseConfig.logs_root_directory~/.cognee/logs系统日志存储目录

来源：cognee/base_config.py:11-15、cognee/base_config.py:32-35

多用户存储上下文

当 backend_access_control_enabled() 返回 true 时，Cognee 会在 DatabaseContextManager 中动态地将用户 ID 和租户 ID 注入到目录结构中，从而实现存储路径的隔离。

Cognee · 多用户存储上下文 · 图 2
Cognee · 多用户存储上下文 · 图 2

来源：cognee/context_global_variables.py:108-115、cognee/context_global_variables.py:141-147

S3 后端配置

当 STORAGE_BACKEND 设置为 "s3" 时，Cognee 使用 S3Config 来管理 AWS 凭证和端点。

来源：cognee/infrastructure/files/storage/s3_config.py:6-14、cognee/infrastructure/files/storage/S3FileStorage.py:41-52、cognee/modules/ingestion/data_types/S3BinaryData.py:99-106

目录与路径解析

Cognee 将存储组织为层级结构，并动态解析路径，同时支持本地和 S3 方案。

数据路径规范化

如果检测到存储后端为 S3 但未提供特定的缓存路径，BaseConfig 类会自动调整 cache_root_directory。

逻辑：如果 STORAGE_BACKEND == "s3" 且 STORAGE_BUCKET_NAME 存在，则缓存路径设置为 s3://{bucket_name}/cognee/cache。

来源：cognee/base_config.py:23-30

递归目录解析

resolve_data_directories 函数负责将目录路径转换为单个文件的列表。

  1. S3 方案：如果 include_subdirectories 为 True，则使用 s3fs.glob(base_path + "**") 递归列出所有键。
  2. 本地方案：使用 os.walk(item) 进行递归的本地扫描。
  3. 校验：使用 fs.isdir 或 os.path.isdir 过滤掉代表目录的键。

来源：cognee/tasks/ingestion/resolve_data_directories.py:44-64、cognee/tasks/ingestion/resolve_data_directories.py:66-79

数据库文件解析

数据库适配器（图数据库和向量数据库）会相对于 system_root_directory 解析自身的文件路径。

图数据库路径

GraphConfig 模型根据提供者动态生成 graph_file_path：

  • 如果未提供路径，则默认为 {system_root_directory}/databases/{graph_filename}。
  • 文件名默认为 cognee_graph_{provider}。
  • 它包含处理遗留路径的逻辑（例如，将 kuzu 迁移到 ladybug）。

来源：cognee/infrastructure/databases/graph/config.py:83-103

向量数据库路径

如果未指定 URL，VectorConfig 模型会将 vector_db_url 默认为 {system_root_directory}/databases/cognee.lancedb。

来源：cognee/infrastructure/databases/vector/config.py:53-67

S3 实现细节

元数据获取

S3BinaryData 实现了异步元数据检索。它以二进制模式（rb）打开 S3 文件，并使用 get_file_metadata 提取内容哈希和大小。

来源：cognee/modules/ingestion/data_types/S3BinaryData.py:38-58

性能监控

系统会跟踪 S3 操作的延迟。任何超过 S3_SLOW_OPERATION_THRESHOLD_SEC（默认 30.0 秒）的操作（元数据获取或文件打开）都会触发警告日志。

来源：cognee/infrastructure/files/storage/S3FileStorage.py:17、cognee/infrastructure/files/storage/S3FileStorage.py:136-145、cognee/modules/ingestion/data_types/S3BinaryData.py:73-83

文件操作

S3FileStorage 提供了标准的文件交互 API：

  • store()：使用 s3.open(mode="w" 或 "wb") 将字符串或二进制流写入 S3。它在写入前会确保目录存在。
  • open()：一个异步上下文管理器，返回一个封装了 S3 文件流的 FileBufferedReader。
  • file_exists()：封装了 s3.exists()。

来源：cognee/infrastructure/files/storage/S3FileStorage.py:54-95、cognee/infrastructure/files/storage/S3FileStorage.py:98-132、cognee/infrastructure/files/storage/S3FileStorage.py:170-186