agentic_huge_data_base / wiki
页面 Cognee · 14.1 认证系统·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 14.1

14.1 · 认证系统（Authentication System）

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

项目Cognee 章节14.1 状态全文译文 模块接口与服务契约、测试、发布与运维、系统架构、安装与启动
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Authentication System 上一章14 下一章14.2
源码线索
  • .github/workflows/dockerhub-mcp.yml
  • Dockerfile
  • cognee-mcp/Dockerfile
  • cognee-mcp/README.md
  • cognee-mcp/entrypoint.sh
  • cognee-mcp/pyproject.toml
  • cognee-mcp/src/__init__.py
  • cognee-mcp/src/client.py
  • cognee-mcp/src/cognee_client.py
  • cognee-mcp/src/server.py
模块标签
  • 接口与服务契约
  • 测试、发布与运维
  • 系统架构
  • 安装与启动
  • 界面与交互

章节正文

认证系统

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/14.1-authentication-system

认证系统

相关源文件

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

  • .github/workflows/dockerhub-mcp.yml
  • Dockerfile
  • cognee-mcp/Dockerfile
  • cognee-mcp/README.md
  • cognee-mcp/entrypoint.sh
  • cognee-mcp/pyproject.toml
  • cognee-mcp/src/__init__.py
  • cognee-mcp/src/client.py
  • cognee-mcp/src/cognee_client.py
  • cognee-mcp/src/server.py
  • cognee-mcp/uv.lock
  • cognee/alembic/versions/7c5d4e2f8a91_add_parent_user_id_to_users.py
  • cognee/alembic/versions/b1c2d3e4f5a6_add_user_api_key_table.py
  • cognee/api/v1/api_keys/routers/__init__.py
  • cognee/api/v1/api_keys/routers/get_api_key_management_router.py
  • cognee/api/v1/users/routers/get_auth_router.py
  • cognee/modules/users/api_key/create_api_key.py
  • cognee/modules/users/api_key/delete_api_key.py
  • cognee/modules/users/api_key/exceptions.py
  • cognee/modules/users/api_key/get_api_keys.py
  • cognee/modules/users/api_key/hash_api_key.py
  • cognee/modules/users/authentication/api_key/api_key_jwt_strategy.py
  • cognee/modules/users/authentication/api_key/get_api_key_transport.py
  • cognee/modules/users/authentication/default/default_transport.py
  • cognee/modules/users/authentication/get_api_auth_backend.py
  • cognee/modules/users/authentication/get_api_key_backend.py
  • cognee/modules/users/authentication/get_client_auth_backend.py
  • cognee/modules/users/get_fastapi_users.py
  • cognee/modules/users/get_user_manager.py
  • cognee/modules/users/models/UserApiKey.py
  • cognee/tests/unit/test_add_parent_user_id_migration.py
  • docker-compose.yml
  • entrypoint.sh

Cognee 使用基于 FastAPI Users 构建的灵活认证系统，支持多种认证方式，包括 JWT Bearer 令牌、HTTP Cookie 和 API 密钥。该系统设计用于同时处理交互式用户会话（通过 Web 前端）和程序化访问（通过 REST API 或 MCP 服务器）。

系统架构

认证层由 FastAPIUsers 类编排，该类将用户管理逻辑与各种认证后端集成在一起。

认证后端

Cognee 配置了三个不同的后端以提供全面的访问控制：

  1. API 密钥后端：使用存储在关系数据库中的自定义 API 密钥校验请求 cognee/modules/users/get_fastapi_users.py:17-17。
  2. API 认证后端：使用 JWT Bearer 令牌，通常用于外部 API 消费者 cognee/modules/users/get_fastapi_users.py:15-15。
  3. 客户端认证后端：使用仅限 HTTP 的 Cookie，针对 Web 前端进行了优化 cognee/modules/users/get_fastapi_users.py:16-16。
认证流程示意图

下图说明了不同认证方法如何解析为 User 实体。

认证策略解析

Cognee · 认证流程示意图 · 图 1
Cognee · 认证流程示意图 · 图 1

来源：cognee/modules/users/get_fastapi_users.py:14-23、cognee/modules/users/get_user_manager.py:22-62、cognee/modules/users/authentication/get_api_auth_backend.py:14-29、cognee/modules/users/authentication/get_client_auth_backend.py:14-31

API 密钥认证

Cognee 允许用户生成和管理长期有效的 API 密钥。这些密钥用于对 cognify、add 和 search 端点进行程序化访问。

实现细节
  • 生成：密钥使用 secrets.token_hex(32) 生成 cognee/modules/users/api_key/create_api_key.py:56-57。
  • 存储：密钥可以存储为原始字符串，也可以使用 SHA-256 进行哈希处理，具体取决于 HASH_API_KEY 环境变量 cognee/modules/users/api_key/hash_api_key.py:4-16。
  • 查找：UserManager 重写了 get_by_token 方法，通过查询 prepared_api_key 在 UserApiKey 表中进行 API 密钥查找 cognee/modules/users/get_user_manager.py:46-58。
API 密钥数据模型

UserApiKey 模型跟踪与特定用户关联的密钥。

字段类型描述
idUUID主键 cognee/modules/users/models/UserApiKey.py:11
user_idUUID外键，关联到 principals.id cognee/modules/users/models/UserApiKey.py:12-14
api_keystr（可能已哈希的）密钥字符串 cognee/modules/users/models/UserApiKey.py:15
labelstr密钥的掩码版本（例如 abcd****）cognee/modules/users/models/UserApiKey.py:16
namestr用户定义的密钥名称 cognee/modules/users/models/UserApiKey.py:17

来源：cognee/modules/users/models/UserApiKey.py:8-18、cognee/modules/users/api_key/create_api_key.py:33-43、cognee/modules/users/get_user_manager.py:51-53

条件认证

Cognee 支持"本地模式"，在该模式下不严格要求进行认证。这由 REQUIRE_AUTHENTICATION 环境变量控制。

get_authenticated_user

此函数是跨 API 路由使用的主要依赖项。其行为根据系统配置而变化：

  • 如果 REQUIRE_AUTHENTICATION 为 False：如果 FastAPI Users 依赖项未提供用户，系统会通过 get_default_user 回退到默认系统用户 cognee/modules/users/methods/get_default_user.py:1-10。
  • 如果 REQUIRE_AUTHENTICATION 为 True：系统严格强制要求存在有效的会话或 API 密钥。

自然语言到代码映射：认证守卫

Cognee · get_authenticated_user · 图 2
Cognee · get_authenticated_user · 图 2

来源：cognee/modules/users/methods/get_authenticated_user.py:1-20、cognee/modules/users/methods/get_default_user.py:1-10、cognee-mcp/src/server.py:13-13

JWT 和 Bearer 令牌

系统使用两种基于 JWT 的策略：

  1. APIJWTStrategy：由 get_api_auth_backend 用于 Bearer 令牌认证 cognee/modules/users/authentication/get_api_auth_backend.py:14-29。
  2. DefaultJWTStrategy：由 get_client_auth_backend 用于基于 Cookie 的会话 cognee/modules/users/authentication/get_client_auth_backend.py:14-31。
配置

JWT 行为由环境变量控制：

  • FASTAPI_USERS_JWT_SECRET：用于签署令牌的密钥（默认为 "super_secret"）cognee/modules/users/authentication/get_api_auth_backend.py:18。
  • JWT_LIFETIME_SECONDS：令牌过期时间（默认为 3600 秒）cognee/modules/users/authentication/get_api_auth_backend.py:19。

来源：cognee/modules/users/authentication/get_api_auth_backend.py:17-21、cognee/modules/users/authentication/get_client_auth_backend.py:20-23

用户管理端点

get_auth_router 和 get_api_key_management_router 定义了标准的认证操作。

认证路由（/v1/auth）
  • POST /login：认证用户凭证，并使用 default_transport 中的参数设置 auth_token Cookie cognee/api/v1/users/routers/get_auth_router.py:14-39。
  • POST /logout：清除认证 Cookie cognee/api/v1/users/routers/get_auth_router.py:41-48。
  • GET /me：返回当前认证用户的电子邮件 cognee/api/v1/users/routers/get_auth_router.py:50-54。
API 密钥管理（/v1/auth/api-keys）
  • GET /api-keys：列出当前用户的所有 API 密钥，如果启用了 HASH_API_KEY，则对密钥进行掩码处理 cognee/api/v1/api_keys/routers/get_api_key_management_router.py:25-57。
  • POST /api-keys：使用 create_api_key 创建新的十六进制编码 API 密钥 cognee/api/v1/api_keys/routers/get_api_key_management_router.py:59-84。
  • DELETE /api-keys/{api_key_id}：吊销现有的 API 密钥 cognee/api/v1/api_keys/routers/get_api_key_management_router.py:85-99。

来源：cognee/api/v1/users/routers/get_auth_router.py:11-56、cognee/api/v1/api_keys/routers/get_api_key_management_router.py:22-101、cognee/modules/users/api_key/create_api_key.py:25-54

MCP 客户端认证

MCP 服务器中使用的 CogneeClient 根据连接模式动态处理认证请求头。

API 模式请求头

当连接到远程 Cognee 实例时，客户端根据是否存在租户 ID 或标准 API 令牌生成请求头 cognee-mcp/src/cognee_client.py:70-85：

  • 云/租户模式：如果在 URL 中检测到租户 UUID，则使用 X-Api-Key 和 X-Tenant-Id 请求头 cognee-mcp/src/cognee_client.py:79-82。
  • 标准 API 模式：使用标准的 Authorization: Bearer <token> 请求头 cognee-mcp/src/cognee_client.py:84-84。

来源：cognee-mcp/src/cognee_client.py:44-85