agentic_huge_data_base / wiki
页面 Cognee · 7.2 安全配置·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 7.2

7.2 · 安全配置（Security Configuration）

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

项目Cognee 章节7.2 状态全文译文 模块配置治理、认证、权限与安全、检索、召回与索引、接口与服务契约
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Security Configuration 上一章7.1 下一章7.3
源码线索
  • .env.template
  • README.md
  • assets/cognee_benefits.png
  • cognee/api/v1/config/config.py
  • cognee/infrastructure/llm/config.py
  • cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/bedrock/adapter.py
  • cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py
  • cognee/modules/settings/__init__.py
  • cognee/modules/settings/get_settings.py
  • cognee/modules/settings/save_llm_config.py
模块标签
  • 配置治理
  • 认证、权限与安全
  • 检索、召回与索引
  • 接口与服务契约
  • 界面与交互

章节正文

安全配置

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/7.2-security-configuration

安全配置

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • .env.template
  • README.md
  • assets/cognee_benefits.png
  • cognee/api/v1/config/config.py
  • cognee/infrastructure/llm/config.py
  • cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/bedrock/adapter.py
  • cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py
  • cognee/modules/settings/__init__.py
  • cognee/modules/settings/get_settings.py
  • cognee/modules/settings/save_llm_config.py
  • cognee/modules/settings/save_vector_db_config.py
  • cognee/modules/users/permissions/methods/get_user_role_names_in_tenant.py
  • cognee/modules/users/permissions/methods/has_user_management_permission.py
  • cognee/modules/users/permissions/permission_types.py
  • cognee/tests/unit/infrastructure/llm/test_get_llm_client.py
  • cognee/tests/unit/users/permissions/test_has_user_management_permission.py

本文档介绍了 Cognee 的安全相关配置设置、认证机制和多租户访问控制功能。这些设置控制 Cognee 如何处理用户认证、数据隔离、外部请求和内容过滤。

有关通用配置设置，请参阅 7.1 环境变量参考。有关存储相关的安全注意事项，请参阅 7.3 存储配置。

安全设置概览

Cognee 通过环境变量提供五个主要的安全控制项：

设置项默认值用途
REQUIRE_AUTHENTICATIONFalse强制 API 请求进行用户认证
ENABLE_BACKEND_ACCESS_CONTROLTrue*启用按用户/数据集进行数据库隔离
ACCEPT_LOCAL_FILE_PATHTrue控制是否允许将本地文件路径添加到 Cognee
ALLOW_HTTP_REQUESTSTrue控制 Cognee 是否可以发起出站 HTTP 请求
ALLOW_CYPHER_QUERYTrue控制是否启用 Cypher 查询搜索类型

*如果配置了受支持的数据库处理器，则默认值为 True，否则为 False。

来源：.env.template:212-240

核心安全设置

REQUIRE_AUTHENTICATION
REQUIRE_AUTHENTICATION=False  # 设置为 True 以强制认证

当设置为 True 时，所有 API 请求必须包含有效的认证凭证。当设置为 False 时，Cognee 会对未认证的请求回退到默认用户。

实现流程：

Cognee · REQUIRE_AUTHENTICATION · 图 1
Cognee · REQUIRE_AUTHENTICATION · 图 1

认证检查发生在 get_authenticated_user() 函数中，该函数依赖于 REQUIRE_AUTHENTICATION 或 ENABLE_BACKEND_ACCESS_CONTROL 的启用状态。该函数返回已认证的用户，或者回退到默认用户。

关键实现文件：

  • 认证强制：cognee/modules/users/methods/get_authenticated_user.py:13-16
  • 默认用户创建：cognee/modules/users/methods/get_authenticated_user.py:33-42

来源：cognee/modules/users/methods/get_authenticated_user.py:1-45, .env.template:228-230

ENABLE_BACKEND_ACCESS_CONTROL
ENABLE_BACKEND_ACCESS_CONTROL=True  # 强制按数据集进行数据库隔离

启用后，Cognee 会为每个用户-数据集组合创建独立的数据库实例，从而在多租户部署中提供数据隔离。此设置仅适用于受支持的数据库提供方。

受支持的数据库处理器：

数据库类型受支持的处理器
向量数据库lancedb, pgvector, qdrant, falkor_vector_local
图数据库kuzu, neo4j_aura_dev, falkor_graph_local
关系型数据库sqlite, postgres（所有部署方式）

访问控制决策流程：

Cognee · ENABLE_BACKEND_ACCESS_CONTROL · 图 2
Cognee · ENABLE_BACKEND_ACCESS_CONTROL · 图 2

backend_access_control_enabled() 函数会验证配置的数据库处理器是否支持多用户模式，并且是否与配置的提供方匹配。如果验证失败，则会抛出 EnvironmentError，并提供修正配置的指导。

实现细节：

  • 访问控制检查：cognee/context_global_variables.py:77-86
  • 处理器验证：cognee/context_global_variables.py:28-74
  • 受支持处理器注册表：cognee/context_global_variables.py:89-90

来源：cognee/context_global_variables.py:77-100, .env.template:232-240

ACCEPT_LOCAL_FILE_PATH
ACCEPT_LOCAL_FILE_PATH=True  # 在后端部署中设置为 False

控制 Cognee 在通过 cognee.add() 添加数据时是否接受本地文件系统路径。当设置为 False 时，Cognee 会拒绝添加本地文件的尝试，从而在共享或云部署中防止未经授权的文件系统访问。

安全理由：

  • 防止用户从服务器的文件系统中读取任意文件
  • 建议在 Cognee 作为后端服务运行时设置为 False
  • 在本地/桌面使用场景中应保持为 True

来源：.env.template:215-216

ALLOW_HTTP_REQUESTS
ALLOW_HTTP_REQUESTS=True  # 设置为 False 以防止 SSRF 攻击

控制 Cognee 是否可以发起出站 HTTP 请求（例如，在数据入库期间获取 URL）。当设置为 False 时，可以防止服务器端请求伪造（SSRF）攻击，即用户可能试图让服务器访问内部资源。

安全理由：

  • 在未实施适当网络隔离时，防止 SSRF 攻击
  • 阻止通过 cognee.add(url) 进行的基于 URL 的数据入库
  • 在没有网络分段的安全敏感环境中应设置为 False

来源：.env.template:218-220

ALLOW_CYPHER_QUERY
ALLOW_CYPHER_QUERY=True  # 设置为 False 以禁用 Cypher 搜索

控制 SearchType.CYPHER 搜索类型是否可用，该类型允许用户对图数据库执行任意的 Cypher 查询。

安全理由：

  • 防止通过 Cypher 进行潜在的查询注入或未经授权的数据访问
  • 禁用后，用户只能使用经过验证的预定义搜索类型
  • 在用户不应直接访问数据库的环境中应设置为 False

来源：.env.template:222-223

多租户数据库隔离

当 ENABLE_BACKEND_ACCESS_CONTROL 启用时，Cognee 使用 DatasetDatabase 模型实现按用户、按数据集的数据库隔离。

架构
Cognee · 架构 · 图 3
Cognee · 架构 · 图 3

处理流程：

  1. 上下文设置：使用数据集和用户调用 set_database_global_context_variables(dataset, user_id)。
  2. 数据库查找：get_or_create_dataset_database() 获取或创建一个 DatasetDatabase 记录。
  3. 处理器调用：向量和图处理器创建隔离的数据库实例。
  4. 连接解析：resolve_dataset_database_connection_info() 填充连接详情。
  5. 上下文变量赋值：数据库配置被设置到当前异步上下文的 ContextVars 中。
  6. 请求隔离：所有后续的数据库操作都使用特定于用户的数据库实例。

来源：cognee/context_global_variables.py:102-179, cognee/infrastructure/databases/utils/get_or_create_dataset_database.py:65-120

DatasetDatabase 模型

DatasetDatabase 模型存储隔离数据库实例的连接信息：

Cognee · DatasetDatabase 模型 · 图 4
Cognee · DatasetDatabase 模型 · 图 4

关键字段：

  • owner_id：指向拥有此数据集的用户/主体的外键。
  • dataset_id：指向数据集的外键。
  • 提供方字段：指定向量/图数据库类型（例如 lancedb、kuzu）。
  • 处理器字段：指定管理数据库创建的处理器。
  • 连接信息：存储提供方特定连接详情（主机、端口、凭证）的 JSON 字段。

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

数据库创建过程
Cognee · 数据库创建过程 · 图 5
Cognee · 数据库创建过程 · 图 5

处理器职责：

  • 向量处理器：为每个数据集创建向量数据库实例（例如 LanceDB 目录、PGVector 数据库）。
  • 图处理器：为每个数据集创建图数据库实例（例如 Kuzu 数据库文件、Neo4j Aura 数据库）。
  • 返回连接信息：URL、凭证、数据库名称和提供方特定设置。

来源：cognee/infrastructure/databases/utils/get_or_create_dataset_database.py:18-38, cognee/context_global_variables.py:126-179

受支持的数据库处理器

每个处理器实现一个 create_dataset(dataset_id, user) 方法，用于预配隔离的数据库实例：

处理器名称提供方实现方式
lancedblancedb为数据集的 LanceDB 实例创建一个目录
pgvectorpgvector为每个数据集创建一个独立的 PostgreSQL 数据库
kuzukuzu为数据集的 Kuzu 数据库文件创建一个目录
neo4jneo4j预配一个 Neo4j 数据库实例
qdrantqdrant在 Qdrant 中创建一个集合命名空间

处理器配置：

  • VECTOR_DATASET_DATABASE_HANDLER：选择向量处理器的环境变量。
  • GRAPH_DATASET_DATABASE_HANDLER：选择图处理器的环境变量。

来源：.env.template:135-136, .env.template:160-161, cognee/context_global_variables.py:28-74

数据库连接安全

当多租户模式启用时，数据库连接按用户进行隔离。对于 PGVector，Cognee 可以创建独立的 PostgreSQL 数据库。

连接池配置： Cognee 通过 POOL_ARGS 环境变量支持自定义连接池设置：

# 高负载场景下的连接池配置示例
POOL_ARGS='{"pool_size": 5, "max_overflow": 10, "pool_recycle": -1, "pool_timeout": 30}'

来源：.env.template:127-128

认证与 API 密钥

Cognee 集成了 FastAPI Users 进行认证，并支持用于内部用户管理和外部大语言模型（LLM）服务的 API 密钥。

用户管理权限

Cognee 使用基于角色的访问控制（RBAC）系统来管理租户用户。权限逻辑集中在 has_user_management_permission 中。

Cognee · 用户管理权限 · 图 6
Cognee · 用户管理权限 · 图 6

实现方式：

  • USER_MANAGEMENT_ALLOWED_ROLE_NAMES 集合定义了哪些角色（例如 "admin"）可以管理用户 cognee/modules/users/permissions/permission_types.py:8-10。
  • has_user_management_permission 函数检查请求者是否是租户所有者，或者是否拥有允许的角色之一 cognee/modules/users/permissions/methods/has_user_management_permission.py:13-45。

来源：cognee/modules/users/permissions/methods/has_user_management_permission.py:13-45, cognee/modules/users/permissions/permission_types.py:1-11

用户的 API 密钥认证

Cognee 允许用户生成并使用 API 密钥进行认证。这些密钥通过 UserManager 进行管理。

关键特性：

  • 掩码处理：get_settings 函数确保通过配置端点返回 API 密钥时进行掩码处理，仅显示前 10 个字符，后跟星号 cognee/modules/settings/get_settings.py:94-96。

来源：cognee/modules/settings/get_settings.py:94-96, cognee/modules/users/authentication/get_api_auth_backend.py:13-29

大语言模型（LLM）与提供方安全

大模型提供方配置与验证

LLMConfig 类管理 LLM 提供方的安全设置，包括 API 密钥和速率限制。

安全特性：

  • 字符串消毒：Cognee 会自动去除 API 密钥和端点两端的引号，以防止 Docker 或 Shell 环境经常导致的配置错误 cognee/infrastructure/llm/config.py:91-125。
  • Ollama 验证：特定验证确保如果设置了任何与 Ollama 相关的环境变量，则所有必需的变量（LLM_MODEL、LLM_ENDPOINT、LLM_API_KEY）都必须存在 cognee/infrastructure/llm/config.py:155-198。
  • 密钥保护：LLM 客户端缓存键使用 _SecretCacheKey 类，确保原始密钥（API 密钥）不会在日志或 repr() 输出中暴露 cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:27-44。

来源：cognee/infrastructure/llm/config.py:91-125, cognee/infrastructure/llm/config.py:155-198, cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:27-44

AWS Bedrock 安全

BedrockAdapter 支持多种 AWS 认证方式：

  1. API 密钥：直接使用 Bearer 令牌。
  2. AWS 凭证：显式提供 aws_access_key_id 和 aws_secret_access_key。
  3. AWS 配置文件：通过 aws_profile_name 使用 boto3 凭证链。

来源：cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/bedrock/adapter.py:32-106

其他安全配置

数据库连接参数

Cognee 支持用于安全数据库连接的自定义连接和池参数：

  • DATABASE_CONNECT_ARGS：用于 SSL 和超时设置 /.env.template:124。
  • POOL_ARGS：连接池调优 /.env.template:127。

来源：.env.template:124-127

安全配置总结

Cognee · 安全配置总结 · 图 7
Cognee · 安全配置总结 · 图 7

来源：.env.template:212-240, cognee/context_global_variables.py:77-179, cognee/modules/settings/get_settings.py:87-191, cognee/infrastructure/llm/config.py:91-125