多租户架构

概述

多租户（Multi-tenancy）是 IAM（身份与访问管理）系统中的核心架构概念。Code Bird Cloud 采用三层架构设计，通过平台、租户和组织三个层级实现灵活的数据隔离和业务分区，满足从单体应用到大规模 SaaS 平台的各种场景需求。

什么是多租户

在 IAM 语境下，多租户是指在同一套系统实例中为多个独立的业务实体（租户）提供服务，同时确保各租户之间的数据和配置完全隔离。每个租户拥有独立的用户、应用、角色、权限和登录配置等，互不干扰。

多租户的核心价值：

资源共享：多个租户共享同一套基础设施，降低运维成本
数据隔离：每个租户的数据完全隔离，保障安全性和隐私
独立配置：每个租户可以独立配置登录方式、品牌外观、角色权限等
弹性扩展：新增租户无需额外部署，通过平台管理即可完成

Code Bird Cloud 的多租户模型

Code Bird Cloud 采用三层架构实现多租户：

平台层（Platform）
│
├── 租户 A（Tenant A）
│   ├── 用户（Users）
│   ├── 应用（Applications）
│   ├── 角色与权限（Roles & Permissions）
│   ├── 连接器（Connectors）
│   ├── 登录体验（Sign-in Experience）
│   ├── 签名密钥（Signing Keys）
│   └── 组织（Organizations）
│       ├── 组织 1
│       │   ├── 成员（Members）
│       │   └── 成员角色分配
│       └── 组织 2
│           ├── 成员（Members）
│           └── 成员角色分配
│
├── 租户 B（Tenant B）
│   ├── 用户（Users）
│   ├── 应用（Applications）
│   └── ...（同上，完全独立）
│
└── 租户 C（Tenant C）
    └── ...

平台层（Platform Level）

平台层是 Code Bird Cloud 的最高管理层级，由平台管理员（Platform Admin）负责管理。

平台层的职责：

租户管理：创建、编辑、禁用和删除租户
租户管理员指派：为每个租户指定管理员账户
系统监控：查看平台整体运行状况和资源使用情况
全局配置：管理平台级别的全局设置

平台管理员通过 platform-admin 管理后台操作，使用独立的认证体系（platform_admins 表），与租户内的用户体系完全隔离。

租户层（Tenant Level）

租户层是 Code Bird Cloud 的核心业务隔离单元。每个租户相当于一个独立的 IAM 实例，拥有完整的身份管理能力。

每个租户独立拥有：

资源	说明
用户（Users）	租户内的终端用户，包括用户属性、密码、登录历史等
应用（Applications）	租户注册的客户端应用（Web、移动端、M2M 等）
API 资源（API Resources）	租户定义的受保护 API 资源和权限
角色（Roles）	系统级角色定义和用户角色分配
连接器（Connectors）	第三方登录（如微信、GitHub 等）的配置
登录体验（Sign-in Experience）	登录页面的品牌、布局和认证方式配置
签名密钥（Signing Keys）	OIDC 令牌签名密钥
组织（Organizations）	租户内的 B2B 组织实体
组织角色模板	租户级别共享的组织角色定义
组织权限模板	租户级别共享的组织权限定义
审计日志（Audit Logs）	租户内所有操作的审计记录

租户管理员通过 admin 管理后台操作，管理本租户内的所有资源。

组织层（Organization Level）

组织层是租户内部的业务分区单元，用于实现 B2B 多组织场景。组织的核心特点是：

组织在租户内部创建，属于某个特定租户
组织拥有独立的成员列表和成员角色分配
同一用户可以属于多个组织，在不同组织中拥有不同角色
所有组织共享租户级别定义的角色模板和权限模板

组织层不拥有独立的用户、应用或配置，它复用租户层的用户体系和角色模板体系。

数据隔离

Code Bird Cloud 通过 tenant_id 字段实现数据隔离。所有租户级别的数据表都包含 tenant_id 列，系统在数据查询时自动附加租户过滤条件，确保每个租户只能访问自己的数据。

数据库层面的隔离模型：

users 表         → tenant_id 隔离
applications 表  → tenant_id 隔离
roles 表         → tenant_id 隔离
resources 表     → tenant_id 隔离
organizations 表 → tenant_id 隔离
audit_logs 表    → tenant_id 隔离
...

这种「共享数据库、按 tenant_id 分区」的策略在安全性和运维效率之间取得了平衡：

安全性：每次数据操作都会自动附加 tenant_id 条件，防止跨租户数据泄露
运维效率：所有租户共用同一个数据库实例，便于备份、升级和监控
扩展性：新增租户只需在数据库中创建记录，无需额外的数据库实例

租户 → 组织 → 用户关系

三层架构中各实体的关系如下：

平台管理员（Platform Admin）
    │
    │ 创建和管理
    v
租户（Tenant）
    │
    │ 包含
    ├── 用户（User）
    │     │
    │     │ 可以加入
    │     └── 组织（Organization） ← 租户内创建
    │           │
    │           └── 组织成员角色（Organization User Role）
    │
    ├── 应用（Application）
    ├── 角色和权限（Role & Permission）
    ├── 组织角色模板（Organization Role Template）
    └── 组织权限模板（Organization Permission Template）

关键关系说明：

一个平台可以管理多个租户
一个租户可以拥有多个用户、多个应用、多个组织
一个用户属于一个租户，但可以加入该租户下的多个组织
一个组织属于一个租户，其成员来自该租户的用户
组织角色模板在租户级别定义，所有组织共享使用

与 Logto 的对比

Code Bird Cloud 的多租户设计参考了 Logto 的架构，并在此基础上增加了显式的多租户支持：

维度	Code Bird Cloud	Logto
租户概念	显式支持，由 Platform Admin 管理	每个 Logto 实例即一个租户（Logto Cloud 中支持多租户）
平台管理	独立的 Platform Admin 管理后台	在 Logto Cloud 中通过 Dashboard 管理
组织功能	租户内的 B2B 组织，共享租户级别的角色和权限模板	类似，Organization 用于 B2B 场景
数据隔离	同一数据库，按 tenant_id 隔离	每个实例独立数据库（自托管），或平台级隔离（Cloud）
自托管	单实例支持多租户	单实例即一个租户

Code Bird Cloud 的优势在于：单次部署即可为多个业务实体提供独立的 IAM 服务，无需为每个业务实体单独部署实例。

何时使用租户 vs 组织

租户和组织都提供了隔离能力，但适用的场景不同：

使用租户的场景

完全独立的业务实体：不同的公司、品牌或产品线，需要完全独立的用户体系、登录配置和应用管理
SaaS 平台运营：你在运营一个 SaaS 平台，每个客户需要独立的 IAM 配置
数据合规隔离：不同业务之间有严格的数据隔离要求（如不同地区的合规要求）
独立品牌：每个业务需要独立的登录页面外观和认证方式

使用组织的场景

B2B 多组织：同一个产品内的多个客户组织，共享相同的登录流程和应用配置
企业多部门：同一企业内的不同部门或团队，需要在组织维度进行权限隔离
协作平台：用户可以同时参与多个组织，在不同组织中承担不同角色
共享用户体系：多个组织的成员来自同一个用户池，使用相同的认证方式

决策参考

需求	推荐方案
完全独立的用户体系	租户
独立的登录页面和认证方式	租户
独立的应用注册和 API 资源	租户
共享用户池，按组划分权限	组织
用户可以同时属于多个分组	组织
共享角色和权限模板定义	组织

多租户架构 ​

概述 ​

什么是多租户 ​

Code Bird Cloud 的多租户模型 ​

平台层（Platform Level） ​

租户层（Tenant Level） ​

组织层（Organization Level） ​

数据隔离 ​

租户 → 组织 → 用户关系 ​

与 Logto 的对比 ​

何时使用租户 vs 组织 ​

使用租户的场景 ​

使用组织的场景 ​

决策参考 ​

相关文档 ​