agentic_huge_data_base / wiki
页面 Cognee · 14 用户管理与权限·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 14

14 · 用户管理与权限（User Management and Permissions）

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

项目Cognee 章节14 状态全文译文 模块认证、权限与安全、系统架构、测试、发布与运维、界面与交互
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节User Management and Permissions 上一章13.4 下一章14.1
源码线索
  • 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/infrastructure/databases/relational/ModelBase.py
  • cognee/infrastructure/databases/relational/__init__.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
模块标签
  • 认证、权限与安全
  • 系统架构
  • 测试、发布与运维
  • 界面与交互
  • 存储与持久化

章节正文

用户管理与权限

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/14-user-management-and-permissions

用户管理与权限

相关源文件

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

  • 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/infrastructure/databases/relational/ModelBase.py
  • cognee/infrastructure/databases/relational/__init__.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/get_api_key_backend.py
  • cognee/modules/users/get_fastapi_users.py
  • cognee/modules/users/get_user_manager.py
  • cognee/modules/users/models/UserApiKey.py
  • cognee/modules/users/permissions/methods/__init__.py
  • cognee/modules/users/permissions/methods/authorized_revoke_permission_on_datasets.py
  • cognee/modules/users/permissions/methods/get_all_user_permission_datasets.py
  • cognee/modules/users/permissions/methods/revoke_permission_on_dataset.py
  • cognee/modules/users/roles/methods/__init__.py
  • cognee/modules/users/roles/methods/delete_role.py
  • cognee/modules/users/roles/methods/remove_user_from_role.py
  • cognee/modules/users/tenants/methods/__init__.py
  • cognee/modules/users/tenants/methods/get_users_in_tenant.py
  • cognee/modules/users/tenants/methods/remove_user_from_tenant.py
  • cognee/tests/test_permissions.py
  • cognee/tests/unit/users/roles/test_role_management_methods.py
  • cognee/tests/unit/users/tenants/test_remove_user_from_tenant.py

Cognee 提供了一套全面的用户管理与授权系统，专为支持多租户 AI 应用而设计。该系统通过多种认证后端处理身份验证，将用户组织为层级结构（租户和角色），并对数据集和系统资源实施细粒度的访问控制。

该系统的核心构建在 FastAPI Users 和 SQLAlchemy 之上，并对其进行了扩展，以支持数据集级别的权限控制以及与特定用户上下文绑定的持久化代理记忆。

系统架构总览图

下图展示了认证层、关系数据模型与权限执行逻辑之间的关系。

用户管理架构

Cognee · 系统架构总览图 · 图 1
Cognee · 系统架构总览图 · 图 1

来源：cognee/modules/users/models/User.py:15-46, cognee/modules/users/permissions/methods/get_all_user_permission_datasets.py:10-48, cognee/modules/users/get_user_manager.py:22-58, cognee/modules/users/models/UserApiKey.py:8-17

认证系统

Cognee 利用 FastAPI Users 提供灵活的认证框架。它支持以下几种主要的认证方式：

  • JWT Bearer 令牌： 用于 API 交互的标准 OAuth2 流程。
  • API 密钥： 用于程序化访问的持久密钥，通过 UserApiKey 进行管理 cognee/modules/users/models/UserApiKey.py:8-17。
  • 条件认证： 由 REQUIRE_AUTHENTICATION 设置控制。

UserManager cognee/modules/users/get_user_manager.py:22-58 负责处理用户的生命周期，包括注册和登录。它还包含通过令牌检索用户的逻辑，该逻辑会检查 UserApiKey 表，并可选地通过 prepare_api_key 对令牌进行哈希处理 cognee/modules/users/api_key/hash_api_key.py:12-16。

详情请参见认证系统。

来源：cognee/modules/users/get_user_manager.py:22-58, cognee/modules/users/api_key/hash_api_key.py:12-16, cognee/modules/users/api_key/create_api_key.py:25-54

租户、角色与权限

Cognee 实现了多租户架构，用户可归属于 Tenants（租户）。权限在数据集级别强制执行，并可从 Roles（角色）或 Tenants（租户）继承。

权限层级

当用户尝试访问数据集时，系统会按以下顺序检查：

  1. 直接用户权限（用户作为 Principal 主体）。
  2. 用户被分配的 Role 所授予的权限 cognee/modules/users/roles/methods/add_user_to_role.py:1-15。
  3. Tenant 所授予的权限。

函数 get_all_user_permission_datasets cognee/modules/users/permissions/methods/get_all_user_permission_datasets.py:10-48 通过遍历用户的租户和角色来聚合这些权限，然后进行去重并根据活跃的 tenant_id 进行过滤。

详情请参见租户、角色与权限。

来源：cognee/modules/users/permissions/methods/get_all_user_permission_datasets.py:10-48, cognee/modules/users/tenants/methods/__init__.py:1-10, cognee/modules/users/permissions/methods/authorized_give_permission_on_datasets.py:13-35

权限解析流程

下图展示了在 cognee.search 或 cognee.add 等操作期间，Cognee 如何解析 User 是否有权访问特定 Dataset。

授权解析流程

Cognee · 权限解析流程 · 图 2
Cognee · 权限解析流程 · 图 2

来源：cognee/modules/users/permissions/methods/get_all_user_permission_datasets.py:10-48, cognee/modules/users/permissions/methods/__init__.py:1-16, cognee/tests/test_permissions.py:116-172

API 密钥管理

程序化访问通过 API 密钥实现。create_api_key 函数 cognee/modules/users/api_key/create_api_key.py:25-54 会生成一个原始令牌，对其进行哈希处理（如果启用了 HASH_API_KEY），并将其存储在 user_api_key 表中 cognee/modules/users/models/UserApiKey.py:9-17。

get_api_key_management_router cognee/api/v1/api_keys/routers/get_api_key_management_router.py:22-101 提供了以下 REST 端点：

  • GET /api-keys：列出现有密钥（如果已哈希，则显示掩码值）。
  • POST /api-keys：为已认证用户创建新密钥。
  • DELETE /api-keys/{api_key_id}：撤销访问权限。

详情请参见认证系统。

来源：cognee/modules/users/api_key/create_api_key.py:25-54, cognee/api/v1/api_keys/routers/get_api_key_management_router.py:22-101, cognee/modules/users/api_key/hash_api_key.py:1-17

代理记忆装饰器

@agent_memory 装饰器提供了一个高级抽象，用于管理 AI 代理工作流中特定于用户的上下文。它会自动将用户身份和记忆配置注入到函数调用中，确保代理的"回忆"严格按用户和租户边界进行隔离。它还支持 parent_user_id 逻辑，即父用户可以继承代理用户创建的数据集的权限。

详情请参见代理记忆装饰器。

来源：cognee/modules/users/models/User.py:23-25, cognee/modules/users/permissions/methods/get_document_ids_for_user.py:1-9