agentic_huge_data_base / wiki
页面 Cognee · 5.5 多租户访问控制·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 5.5

5.5 · 多租户访问控制（Multi-Tenant Access Control）

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

项目Cognee 章节5.5 状态全文译文 模块配置治理、存储与持久化、检索、召回与索引、系统架构
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Multi-Tenant Access Control 上一章5.4 下一章5.6
源码线索
  • cognee/base_config.py
  • cognee/context_global_variables.py
  • cognee/infrastructure/databases/dataset_database_handler/__init__.py
  • cognee/infrastructure/databases/dataset_database_handler/dataset_database_handler_interface.py
  • cognee/infrastructure/databases/dataset_database_handler/supported_dataset_database_handlers.py
  • cognee/infrastructure/databases/dataset_database_handler/use_dataset_database_handler.py
  • cognee/infrastructure/databases/graph/config.py
  • cognee/infrastructure/databases/graph/get_graph_engine.py
  • cognee/infrastructure/databases/graph/kuzu/KuzuDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/graph/neo4j_driver/Neo4jAuraDevDatasetDatabaseHandler.py
模块标签
  • 配置治理
  • 存储与持久化
  • 检索、召回与索引
  • 系统架构
  • 测试、发布与运维

章节正文

多租户访问控制

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/5.5-multi-tenant-access-control

多租户访问控制

相关源文件

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

  • cognee/base_config.py
  • cognee/context_global_variables.py
  • cognee/infrastructure/databases/dataset_database_handler/__init__.py
  • cognee/infrastructure/databases/dataset_database_handler/dataset_database_handler_interface.py
  • cognee/infrastructure/databases/dataset_database_handler/supported_dataset_database_handlers.py
  • cognee/infrastructure/databases/dataset_database_handler/use_dataset_database_handler.py
  • cognee/infrastructure/databases/graph/config.py
  • cognee/infrastructure/databases/graph/get_graph_engine.py
  • cognee/infrastructure/databases/graph/kuzu/KuzuDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/graph/neo4j_driver/Neo4jAuraDevDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/graph/postgres/PostgresGraphDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/relational/config.py
  • cognee/infrastructure/databases/relational/create_relational_engine.py
  • cognee/infrastructure/databases/relational/get_relational_engine.py
  • cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py
  • cognee/infrastructure/databases/utils/__init__.py
  • cognee/infrastructure/databases/utils/get_graph_dataset_database_handler.py
  • cognee/infrastructure/databases/utils/get_or_create_dataset_database.py
  • cognee/infrastructure/databases/utils/get_vector_dataset_database_handler.py
  • cognee/infrastructure/databases/utils/resolve_dataset_database_connection_info.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/databases/vector/lancedb/LanceDBDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py
  • cognee/modules/data/deletion/prune_system.py
  • cognee/modules/search/operations/get_history.py
  • cognee/modules/users/models/DatasetDatabase.py
  • cognee/root_dir.py
  • cognee/shared/lru_cache.py
  • cognee/tests/test_dataset_delete.py
  • cognee/tests/test_delete_data_and_dataset_if_empty.py
  • cognee/tests/unit/infrastructure/databases/relational/test_RelationalConfig.py
  • cognee/tests/unit/infrastructure/databases/relational/test_SqlAlchemyAdapter.py
  • cognee/tests/unit/infrastructure/databases/relational/test_create_relational_engine.py

目的与范围

本文档描述了 Cognee 的多租户访问控制系统，该系统通过为每个数据集预配独立的数据库实例，实现了用户与数据集之间的物理数据隔离。启用该功能后，每个数据集会被分配专属的向量数据库和图数据库，从而防止跨数据集的数据泄露，并支持企业级 SaaS 部署。

关于通用数据库架构和适配器模式，请参见数据库架构。关于数据库配置和供应商选择，请参见数据库配置与选择。关于认证和授权机制，请参见安全配置。

系统总览

Cognee 的多租户模式有两种运行方式：

模式描述数据库共享方式使用场景
单租户所有用户共享全局数据库实例共享开发环境、单用户部署
多租户每个数据集获得独立的数据库实例隔离生产环境 SaaS、企业部署

该模式由 ENABLE_BACKEND_ACCESS_CONTROL 环境变量控制，系统会自动校验配置的数据库供应商是否支持多租户。

来源：cognee/context_global_variables.py:83-92

后端访问控制激活

自动模式检测
Cognee · 自动模式检测 · 图 1
Cognee · 自动模式检测 · 图 1

自动模式检测流程

系统通过以下步骤自动判断多租户能力：

  1. 校验图数据库和向量数据库处理器是否在 supported_dataset_database_handlers 列表中 cognee/context_global_variables.py:44-56。
  2. 校验处理器是否与配置的数据库供应商（GRAPH_DATABASE_PROVIDER、VECTOR_DB_PROVIDER）匹配 cognee/context_global_variables.py:58-78。

如果校验失败，系统会抛出详细的 EnvironmentError 异常，说明配置问题。

来源：cognee/context_global_variables.py:34-92

支持的数据库处理器
Cognee · 支持的数据库处理器 · 图 2
Cognee · 支持的数据库处理器 · 图 2

支持的处理器-供应商映射关系

每个处理器都实现了 DatasetDatabaseHandlerInterface cognee/infrastructure/databases/dataset_database_handler/dataset_database_handler_interface.py:10-10，并负责以下操作：

  • 通过 create_dataset 为数据集创建独立的数据库实例 cognee/infrastructure/databases/dataset_database_handler/dataset_database_handler_interface.py:12-34。
  • 向 DatasetDatabase 模型提供连接信息。
  • 通过 resolve_dataset_connection_info 解析运行时连接详情（例如获取凭证）cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py:61-72。
  • 在删除数据集时，通过 delete_dataset 删除对应的数据库实例 cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py:75-93。

来源：cognee/infrastructure/databases/dataset_database_handler/dataset_database_handler_interface.py:10-81，cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py:15-94

DatasetDatabase 模型

模式结构

DatasetDatabase 表将每个数据集映射到其专属的数据库实例。该模型定义在 cognee/modules/users/models/DatasetDatabase.py 中。

列名类型用途
owner_idUUID外键，指向拥有该数据集的用户 cognee/modules/users/models/DatasetDatabase.py:10-10
dataset_idUUID主键，外键指向数据集 cognee/modules/users/models/DatasetDatabase.py:11-13
vector_database_name字符串向量数据库实例的名称/标识符
graph_database_name字符串图数据库实例的名称/标识符
vector_database_provider字符串供应商类型（例如 "lancedb"）
graph_database_provider字符串供应商类型（例如 "kuzu"、"neo4j"）
vector_dataset_database_handler字符串向量数据库的处理器标识符
graph_dataset_database_handler字符串图数据库的处理器标识符
vector_database_url字符串向量数据库的连接 URL
graph_database_url字符串图数据库的连接 URL
graph_database_connection_infoJSON额外的连接元数据（用户名、密码等）cognee/modules/users/models/DatasetDatabase.py:32-34
vector_database_connection_infoJSON额外的连接元数据 cognee/modules/users/models/DatasetDatabase.py:35-37

来源：cognee/modules/users/models/DatasetDatabase.py:7-41

数据库关系
Cognee · 数据库关系 · 图 3
Cognee · 数据库关系 · 图 3

DatasetDatabase 表将用户与其特定的数据集存储配置关联起来。

来源：cognee/modules/users/models/DatasetDatabase.py:10-13，cognee/infrastructure/databases/utils/get_or_create_dataset_database.py:64-82

上下文变量隔离

每个请求的数据库配置

Cognee 使用 Python 的 ContextVar 提供线程安全、每个请求独立的数据库配置：

vector_db_config = ContextVar("vector_db_config", default=None)
graph_db_config = ContextVar("graph_db_config", default=None)
session_user = ContextVar("session_user", default=None)

这些变量在 DatabaseContextManager 中设置，确保不同的异步任务可以同时操作不同的数据集而不会相互干扰 cognee/context_global_variables.py:25-27。

来源：cognee/context_global_variables.py:25-27，cognee/context_global_variables.py:108-160

上下文配置流程
Cognee · 上下文配置流程 · 图 4
Cognee · 上下文配置流程 · 图 4

当后端访问控制启用时，DatabaseContextManager 会执行以下操作：

  1. 通过 get_or_create_dataset_database 获取或创建数据集的 DatasetDatabase 记录 cognee/context_global_variables.py:137。
  2. 通过 resolve_dataset_database_connection_info 解析连接信息（例如获取凭证）cognee/context_global_variables.py:139。
  3. 使用数据集专属配置设置 vector_db_config 和 graph_db_config 上下文变量 cognee/context_global_variables.py:150-160。

来源：cognee/context_global_variables.py:108-160，cognee/infrastructure/databases/utils/get_or_create_dataset_database.py:64-67

数据库预配工作流

使用隔离数据库创建数据集
Cognee · 使用隔离数据库创建数据集 · 图 5
Cognee · 使用隔离数据库创建数据集 · 图 5

get_or_create_dataset_database 函数确保每个数据集在关系型数据库中都有自己独立的数据库配置 cognee/infrastructure/databases/utils/get_or_create_dataset_database.py:64-121。

来源：cognee/infrastructure/databases/utils/get_or_create_dataset_database.py:64-121

处理器专属预配：PGVector

PGVectorDatasetDatabaseHandler 为每个数据集创建一个专用的 PostgreSQL 数据库：

  1. 基于 dataset_id 生成数据库名称 cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py:29。
  2. 校验供应商是否为 pgvector cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py:24-27。
  3. 使用新配置调用 create_pg_database cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py:44-56。

create_pg_database 函数使用连接到默认 postgres 数据库的维护引擎来执行 CREATE DATABASE 语句，然后初始化 vector 扩展 cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py:20-64。

来源：cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py:21-58，cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py:20-64

数据集删除与清理

删除工作流

当数据集被删除时，系统会清理已预配的数据库实例。在多租户模式下，Cognee 会遍历 DatasetDatabase 记录，并调用相应处理器的 delete_dataset 方法 cognee/modules/data/deletion/prune_system.py:40-54。

对于 PGVector，这涉及通过 delete_pg_database 删除整个数据库实例，该方法会在删除数据库之前终止所有活动的后端连接 cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py:66-106。

来源：cognee/modules/data/deletion/prune_system.py:40-54，cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py:66-106

配置参考

环境变量
变量名默认值描述
ENABLE_BACKEND_ACCESS_CONTROL自动检测启用多租户模式（true/false）cognee/context_global_variables.py:83-84
USE_UNIFIED_PROVIDER""如果设置为 pghybrid，则强制图数据库和向量数据库引擎都使用 PostgresAdapter cognee/infrastructure/databases/graph/get_graph_engine.py:160-166，cognee/infrastructure/databases/vector/create_vector_engine.py:78-96

来源：cognee/context_global_variables.py:83-92，cognee/infrastructure/databases/graph/get_graph_engine.py:159-166，cognee/infrastructure/databases/vector/create_vector_engine.py:77-96