安全配置（中文译文）
原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/7.2-security-configuration
翻译时间：2026-05-27T08:45:31.597Z
翻译模型：deepseek-chat
原文字符数：19624
项目：Cognee (cognee)
---
安全配置
相关源文件
以下文件为本维基页面的生成提供了上下文：
.env.templateREADME.mdassets/cognee_benefits.pngcognee/api/v1/config/config.pycognee/infrastructure/llm/config.pycognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/bedrock/adapter.pycognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.pycognee/modules/settings/__init__.pycognee/modules/settings/get_settings.pycognee/modules/settings/save_llm_config.pycognee/modules/settings/save_vector_db_config.pycognee/modules/users/permissions/methods/get_user_role_names_in_tenant.pycognee/modules/users/permissions/methods/has_user_management_permission.pycognee/modules/users/permissions/permission_types.pycognee/tests/unit/infrastructure/llm/test_get_llm_client.pycognee/tests/unit/users/permissions/test_has_user_management_permission.py
本文档介绍了 Cognee 的安全相关配置设置、认证机制和多租户访问控制功能。这些设置控制 Cognee 如何处理用户认证、数据隔离、外部请求和内容过滤。
有关通用配置设置，请参阅 7.1 环境变量参考。有关存储相关的安全注意事项，请参阅 7.3 存储配置。
---
安全设置概览
Cognee 通过环境变量提供五个主要的安全控制项：
| 设置项 | 默认值 | 用途 |
|---|---|---|
REQUIRE_AUTHENTICATION | False | 强制 API 请求进行用户认证 |
ENABLE_BACKEND_ACCESS_CONTROL | True* | 启用按用户/数据集进行数据库隔离 |
ACCEPT_LOCAL_FILE_PATH | True | 控制是否允许将本地文件路径添加到 Cognee |
ALLOW_HTTP_REQUESTS | True | 控制 Cognee 是否可以发起出站 HTTP 请求 |
ALLOW_CYPHER_QUERY | True | 控制是否启用 Cypher 查询搜索类型 |
*如果配置了受支持的数据库处理器，则默认值为 True，否则为 False。
来源：.env.template:212-240
---
核心安全设置
REQUIRE_AUTHENTICATION
REQUIRE_AUTHENTICATION=False # 设置为 True 以强制认证当设置为 True 时，所有 API 请求必须包含有效的认证凭证。当设置为 False 时，Cognee 会对未认证的请求回退到默认用户。
实现流程：
flowchart TB
Request["API 请求"]
Auth{"REQUIRE_AUTHENTICATION"}
Check["FastAPI Users 认证检查"]
Default["get_default_user()"]
User["用户对象"]
Error401["HTTP 401 未授权"]
Request --> Auth
Auth -->|True| Check
Auth -->|False| Check
Check -->|已认证| User
Check -->|未认证 + 必需| Error401
Check -->|未认证 + 可选| Default
Default --> User
认证检查发生在 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（所有部署方式） |
访问控制决策流程：
flowchart TB
EnvCheck{"环境变量中存在 ENABLE_BACKEND_ACCESS_CONTROL？"}
EnvValue{"值为 'true'？"}
MultiCheck["multi_user_support_possible()"]
HandlerCheck{"存在受支持的处理器？"}
ProviderCheck{"处理器与提供方匹配？"}
Enabled["访问控制已启用"]
Disabled["访问控制已禁用"]
Error["抛出 EnvironmentError"]
EnvCheck -->|是| EnvValue
EnvCheck -->|否| MultiCheck
EnvValue -->|是| MultiCheck
EnvValue -->|否| Disabled
MultiCheck --> HandlerCheck
HandlerCheck -->|是| ProviderCheck
HandlerCheck -->|否| Error
ProviderCheck -->|是| Enabled
ProviderCheck -->|否| Error
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 模型实现按用户、按数据集的数据库隔离。
架构
flowchart TB
subgraph "数据库配置上下文"
ContextVars["ContextVars: graph_db_config, vector_db_config, session_user"]
end
subgraph "请求处理"
Request["API 请求 + 用户"]
SetContext["set_database_global_context_variables()"]
GetOrCreate["get_or_create_dataset_database()"]
ResolveConn["resolve_dataset_database_connection_info()"]
end
subgraph "关系型数据库"
DatasetDB[("DatasetDatabase 表")]
end
subgraph "数据库处理器"
VectorHandler["向量数据集数据库处理器"]
GraphHandler["图数据集数据库处理器"]
end
subgraph "隔离的数据库"
UserVectorDB[("用户向量数据库: user_id + dataset_id")]
UserGraphDB[("用户图数据库: user_id + dataset_id")]
end
Request --> SetContext
SetContext --> GetOrCreate
GetOrCreate --> DatasetDB
GetOrCreate --> VectorHandler
GetOrCreate --> GraphHandler
VectorHandler --> UserVectorDB
GraphHandler --> UserGraphDB
DatasetDB --> ResolveConn
ResolveConn --> ContextVars
ContextVars -.-> UserVectorDB
ContextVars -.-> UserGraphDB
处理流程：
- 上下文设置：使用数据集和用户调用
set_database_global_context_variables(dataset, user_id)。 - 数据库查找：
get_or_create_dataset_database()获取或创建一个DatasetDatabase记录。 - 处理器调用：向量和图处理器创建隔离的数据库实例。
- 连接解析：
resolve_dataset_database_connection_info()填充连接详情。 - 上下文变量赋值：数据库配置被设置到当前异步上下文的
ContextVars中。 - 请求隔离：所有后续的数据库操作都使用特定于用户的数据库实例。
来源：cognee/context_global_variables.py:102-179, cognee/infrastructure/databases/utils/get_or_create_dataset_database.py:65-120
---
DatasetDatabase 模型
DatasetDatabase 模型存储隔离数据库实例的连接信息：
classDiagram
class DatasetDatabase {
+UUID owner_id
+UUID dataset_id
+String vector_database_name
+String graph_database_name
+String vector_database_provider
+String graph_database_provider
+String graph_dataset_database_handler
+String vector_dataset_database_handler
+String vector_database_url
+String graph_database_url
+String vector_database_key
+String graph_database_key
+JSON graph_database_connection_info
+JSON vector_database_connection_info
+DateTime created_at
+DateTime updated_at
}
关键字段：
owner_id：指向拥有此数据集的用户/主体的外键。dataset_id：指向数据集的外键。- 提供方字段：指定向量/图数据库类型（例如
lancedb、kuzu）。 - 处理器字段：指定管理数据库创建的处理器。
- 连接信息：存储提供方特定连接详情（主机、端口、凭证）的 JSON 字段。
来源：cognee/modules/users/models/DatasetDatabase.py:1-41
---
数据库创建过程
sequenceDiagram
participant Client
participant SetContext as set_database_global_context_variables()
participant GetOrCreate as get_or_create_dataset_database()
participant Handler as 数据集数据库处理器
participant DB as 隔离的数据库
participant ContextVar as ContextVars
Client->>SetContext: dataset, user_id
SetContext->>GetOrCreate: dataset, user
alt DatasetDatabase 已存在
GetOrCreate->>GetOrCreate: 获取现有记录
else DatasetDatabase 不存在
GetOrCreate->>Handler: create_dataset(dataset_id, user)
Handler->>DB: 创建/预配数据库
DB-->>Handler: 连接信息
Handler-->>GetOrCreate: 数据库配置字典
GetOrCreate->>GetOrCreate: 创建 DatasetDatabase 记录
end
GetOrCreate-->>SetContext: DatasetDatabase
SetContext->>SetContext: 构建配置字典
SetContext->>ContextVar: 设置 graph_db_config
SetContext->>ContextVar: 设置 vector_db_config
SetContext->>ContextVar: 设置 file_storage_config
ContextVar-->>Client: 数据库上下文已配置
处理器职责：
- 向量处理器：为每个数据集创建向量数据库实例（例如 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) 方法，用于预配隔离的数据库实例：
| 处理器名称 | 提供方 | 实现方式 |
|---|---|---|
lancedb | lancedb | 为数据集的 LanceDB 实例创建一个目录 |
pgvector | pgvector | 为每个数据集创建一个独立的 PostgreSQL 数据库 |
kuzu | kuzu | 为数据集的 Kuzu 数据库文件创建一个目录 |
neo4j | neo4j | 预配一个 Neo4j 数据库实例 |
qdrant | qdrant | 在 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 中。
flowchart TD
Req["管理用户的请求"]
GetTenant["get_tenant(tenant_id)"]
IsOwner{"用户是所有者？"}
GetRoles["get_user_role_names_in_tenant()"]
CheckRoles{"拥有 'admin' 角色？"}
Allowed["权限已授予"]
Denied["PermissionDeniedError"]
Req --> GetTenant
GetTenant --> IsOwner
IsOwner -->|是| Allowed
IsOwner -->|否| GetRoles
GetRoles --> CheckRoles
CheckRoles -->|是| Allowed
CheckRoles -->|否| Denied
实现方式：
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 认证方式：
- API 密钥：直接使用 Bearer 令牌。
- AWS 凭证：显式提供
aws_access_key_id和aws_secret_access_key。 - 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
---
安全配置总结
flowchart TB
subgraph "请求安全"
Auth["REQUIRE_AUTHENTICATION"]
LocalFile["ACCEPT_LOCAL_FILE_PATH"]
HTTP["ALLOW_HTTP_REQUESTS"]
Cypher["ALLOW_CYPHER_QUERY"]
end
subgraph "用户认证与权限"
UserAPIKey["用户 API 密钥"]
RBAC["has_user_management_permission"]
JWT["JWT 策略"]
end
subgraph "数据隔离"
AccessCtrl["ENABLE_BACKEND_ACCESS_CONTROL"]
DatasetDB["DatasetDatabase"]
IsolatedDBs["按用户/数据集的数据库"]
end
subgraph "LLM 安全"
LLMKeys["LLM API 密钥（已消毒）"]
BedrockAuth["Bedrock IAM/密钥认证"]
Masking["设置中的密钥掩码"]
end
Auth -.-> UserAPIKey
AccessCtrl --> DatasetDB
DatasetDB --> IsolatedDBs
LLMKeys --> Masking
RBAC --> Auth
来源：.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