14.2 · 租户、角色与权限（Tenants, Roles, and Permissions）

租户、角色与权限

租户、角色与权限

相关源文件

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

• cognee/alembic/versions/6ee94db7381f_remove_unique_constraint_tenant_name.py
• cognee/infrastructure/databases/relational/ModelBase.py
• cognee/infrastructure/databases/relational/__init__.py
• cognee/modules/data/methods/create_dataset.py
• cognee/modules/users/methods/create_default_user.py
• cognee/modules/users/methods/get_default_user.py
• cognee/modules/users/methods/get_user.py
• cognee/modules/users/models/Tenant.py
• cognee/modules/users/models/__init__.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/get_user_role_names_in_tenant.py
• cognee/modules/users/permissions/methods/has_user_management_permission.py
• cognee/modules/users/permissions/methods/revoke_permission_on_dataset.py
• cognee/modules/users/permissions/permission_types.py
• cognee/modules/users/roles/methods/__init__.py
• cognee/modules/users/roles/methods/create_role.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/add_user_to_tenant.py
• cognee/modules/users/tenants/methods/create_tenant.py
• cognee/modules/users/tenants/methods/get_users_in_tenant.py
• cognee/modules/users/tenants/methods/remove_user_from_tenant.py
• cognee/modules/users/tenants/methods/select_tenant.py
• cognee/tests/test_permissions.py
• cognee/tests/unit/users/permissions/test_has_user_management_permission.py
• cognee/tests/unit/users/roles/test_role_management_methods.py
• cognee/tests/unit/users/tenants/test_remove_user_from_tenant.py

Cognee 实现了多租户架构，可以对数据集和系统资源进行细粒度的访问控制。权限系统基于关系型数据库（SQLAlchemy）构建，通过角色、租户成员身份和显式的访问控制列表（ACL）来管理用户与数据的交互方式。

多租户架构

Cognee 中的租户充当组织容器。一个用户可以属于多个租户，但在资源创建和作用域限定方面，任意时刻只有一个租户处于"活跃"状态。

租户创建与管理

使用 create_tenant 创建租户，该函数会将创建者设置为 owner_id cognee/modules/users/tenants/methods/create_tenant.py:13-32。所有者拥有对租户的完整管理权限，包括添加或移除用户。

• 活跃租户：select_tenant 函数会更新 User 模型中的 tenant_id 字段，从而确定后续操作的作用域上下文 cognee/modules/users/tenants/methods/select_tenant.py:15-62。
• 用户关联：用户通过 UserTenant 关联表与租户建立关联 cognee/modules/users/models/UserTenant.py:1-10。
• 添加用户：add_user_to_tenant 函数允许租户所有者邀请其他用户。该函数强制要求只有租户的 owner_id 才能执行此操作 cognee/modules/users/tenants/methods/add_user_to_tenant.py:18-49。

数据流：租户选择

下图展示了用户如何在关系型数据库中切换不同租户之间的活跃上下文。

租户上下文切换

来源：cognee/modules/users/tenants/methods/select_tenant.py:15-62，cognee/modules/users/tenants/methods/add_user_to_tenant.py:18-49，cognee/modules/users/models/UserTenant.py:1-10

角色与用户管理

角色允许在租户内进行分组权限管理。Cognee 使用一组预定义的角色名称来授权管理操作。

角色分配

用户可以在租户内被分配角色（例如"admin"、"Researcher"）。这些角色存储在 Role 模型中，并通过 UserRole 关联表进行关联 cognee/modules/users/roles/methods/add_user_to_role.py:23-67。

• 校验：将用户添加到角色时，系统会验证该用户是否已经是该角色所属租户的成员 cognee/modules/users/roles/methods/add_user_to_role.py:51-54。

管理权限

has_user_management_permission 函数是管理任务（如列出用户或分配角色）的核心守卫 cognee/modules/users/permissions/methods/has_user_management_permission.py:13-45。

• 所有者访问：租户所有者（tenant.owner_id）始终被授予权限 cognee/modules/users/permissions/methods/has_user_management_permission.py:38-39。
• 基于角色的访问：如果用户拥有 USER_MANAGEMENT_ALLOWED_ROLE_NAMES 中列出的角色，则会被授予权限 cognee/modules/users/permissions/methods/has_user_management_permission.py:41-43。默认情况下，这包括 "admin" 角色 cognee/modules/users/permissions/permission_types.py:8-10。

来源：cognee/modules/users/permissions/methods/has_user_management_permission.py:13-45，cognee/modules/users/permissions/permission_types.py:1-11，cognee/modules/users/roles/methods/add_user_to_role.py:23-67

权限类型与数据集

Cognee 支持 PERMISSION_TYPES 中定义的四种主要权限类型 cognee/modules/users/permissions/permission_types.py:3：

1. read：查看数据和搜索结果。
2. write：添加新数据或更新现有实体。
3. delete：从系统中移除数据。
4. share：向其他用户授予权限。

数据集访问解析

当用户尝试访问数据集时，Cognee 通过聚合三个层面的访问权限来解析权限：

1. 直接用户权限：显式授予 User ID 的权限。
2. 租户权限：授予整个 Tenant 的权限。
3. 角色权限：授予用户拥有的特定 Role ID 的权限。

get_all_user_permission_datasets 函数执行此聚合操作，并过滤结果以确保只返回属于用户当前 tenant_id 的数据集 cognee/modules/users/permissions/methods/get_all_user_permission_datasets.py:10-48。

权限解析逻辑

来源：cognee/modules/users/permissions/methods/get_all_user_permission_datasets.py:10-48，cognee/modules/users/permissions/methods/get_principal_datasets.py:1-10

授予与撤销权限

权限通过 authorized_give_permission_on_datasets 函数进行管理。该函数确保只有具有足够权限的用户（所有者或拥有 share 权限的用户）才能向其他人分发访问权限 cognee/modules/users/permissions/methods/authorized_give_permission_on_datasets.py:1-20。

默认权限

Cognee 提供了辅助函数，用于在创建新实体时建立基线访问权限：

• give_default_permission_to_user：向用户分配初始权限 cognee/modules/users/permissions/methods/give_default_permission_to_user.py:1-10。
• give_default_permission_to_tenant：向租户的所有成员分配权限 cognee/modules/users/permissions/methods/give_default_permission_to_tenant.py:1-10。
• give_default_permission_to_role：向特定角色分配权限 cognee/modules/users/permissions/methods/give_default_permission_to_role.py:1-10。

数据集删除与清理

当通过 delete_dataset 删除数据集时，系统会在所有存储层执行清理操作。这包括移除 DatasetDatabase 条目，并调用特定的处理器来清除向量数据库和图数据库中的数据 cognee/modules/data/methods/delete_dataset.py:15-36。然后，ORM 会触发级联操作来删除相关的 ACL 行 cognee/modules/data/methods/delete_dataset.py:63-78。

数据集删除流程

来源：cognee/modules/users/permissions/methods/authorized_give_permission_on_datasets.py:1-20，cognee/modules/data/methods/delete_dataset.py:15-78，cognee/tests/test_permissions.py:157-161