跳到主要内容

多租户模块总览

1. 模块定位​

Nebula 的多租户不是简单地给每张表加一个 tenant_id,而是把“人”和“人在企业里的身份”拆成两层:

  • 平台账号(auth_person):全局身份,只回答“你是谁”,不携带任何租户权限;
  • 租户账号(auth_user):租户内身份,回答“你在该租户是谁、有什么角色和组织”;
  • 关联(auth_person_user):把两者连起来,只有在关联为 ACTIVE 且平台账号为 ACTIVE 时才算有效绑定。

在此之上,每个租户拥有独立子域名、独立用户/角色/组织/菜单/权限资源,以及独立的字典、参数、通知、文件、审计与调度数据。

多租户默认关闭。nebula.tenant.enabled=false 时不启用租户解析、租户选择和平台账号绑定,但租户拦截器仍然生效,所有租户表读写都限定在默认租户;开启后平台账号层随之启用,并强制绑定。

2. 核心概念​

概念载体说明
租户auth_tenant企业/组织,多租户隔离边界
租户编码auth_tenant.code公开、不可变,可下发给用户;也用于移动端输入企业代码
租户子域名auth_tenant_domain.domain如 acme.app.example.com,Web 端租户识别依据
平台账号auth_person全局身份;用户名、邮箱、手机号全局唯一
租户账号auth_user租户内身份;角色、组织、权限只挂在这里
平台账号-租户账号关联auth_person_userPENDING / ACTIVE / REVOKED 三种状态
系统租户auth_tenant.id = __system__纯模板命名空间,不是可登录客户租户,不分配域名
默认租户初始化数据固定 ID,code = default第一个真实客户租户,同时是平台主租户
主租户默认租户平台级配置(验证码通道、存储后端)与平台管理员归属该租户

3. 身份模型​

三条不能破坏的约束:

  1. 平台账号不带权限。 角色、组织、菜单、按钮、接口权限、数据范围全部挂在 auth_user 上。
  2. 绑定只认数据库事实。 唯一判定条件是 (tenant_id, user_id) 存在 ACTIVE 关联,且对应 auth_person.status = ACTIVE;同名、同邮箱、同手机号都不触发自动关联。
  3. 切换企业不是换令牌。 切换 = 导航到目标租户子域名;目标子域有自己的租户令牌,没有就重新登录。

4. 运行时隔离范围​

层面隔离方式
数据库tenant_id CHAR(32) NOT NULL CHECK (tenant_id <> ''),无 DEFAULT;查询由 TenantLineInnerInterceptor 追加条件,写入由服务端显式赋值
实体租户表实体继承 TenantBaseEntity 或实现 TenantScoped;插入时由 TenantIdResolver 显式填充 tenant_id,数据库无 DEFAULT
缓存未登记为全局的缓存自动加 {tenantId}: 前缀
线程上下文TenantContext(ThreadLocal);异步执行器显式传播
领域事件事件 envelope 携带 tenantId,消费前 TenantContext.runAs
Outbox扫描使用 TenantContext.ignore,逐条按事件租户恢复上下文
调度任务数据带租户,租户不可用时暂停该租户全部任务
文件存储对象 key 前缀 t/{tenantId}/;storage_content 带 tenant_id
审计audit_record 带 tenant_id、person_id、target_tenant_id
服务调用内部请求传播 X-Tenant-Id / X-Tenant-Code;已认证请求以令牌租户为准
前端令牌每个租户子域独立存储自己的令牌,不跨子域共享

5. 主要能力​

  • 租户解析:Host 子域名、企业代码两种来源;系统租户不能被解析为登录租户
  • 强制绑定:租户认证成功后判定关联;无有效绑定返回绑定挑战,不签发令牌
  • 平台账号自助:资料、密码、邮箱/手机号绑定、我的企业、绑定关系、退出所有企业
  • 企业切换:展示已关联企业并导航到目标子域;不做跨租户换令牌
  • 成员邀请:租户管理员或平台管理员创建邀请,被邀请人接受后建号并绑定
  • 租户 OAuth2:平台维护 provider 目录,租户配置自己的 client_id/secret 与回调
  • 平台租户管理:创建、更新、启停、删除租户;维护子域名;查看邀请
  • 租户开通:从系统租户复制组织、角色、管理员、菜单/按钮/API 与权限,各模块复制自己的模板数据
  • 状态联动:租户停用后暂停调度、撤销会话,恢复后按配置恢复任务

6. 与 Auth 模块的关系​

多租户的入口、会话与绑定逻辑都在 nebula-auth:

  • TenantContextFilter:匿名请求解析租户;
  • TenantResolver:Host / 企业码解析;
  • PersonBindingService:绑定判定、绑定挑战、完成绑定;
  • DefaultLoginSessionService:签发租户会话并写入 tenantId/personId/platformAdmin;
  • PlatformTenantController / TenantSettingsController:平台与租户管理接口;
  • TenantResourceProvisioner:新租户资源初始化。

租户会话建立后,后续业务模块只依赖 TenantContext 与 TenantBaseEntity,不需要自己解析租户。

7. 单租户兼容​

配置行为
nebula.tenant.enabled=false不启用租户解析、租户缓存前缀和平台账号绑定;租户拦截器仍注册,读写限定默认租户
nebula.tenant.enabled=true启用租户解析、数据隔离、强制绑定;平台账号层自动启用

开启前请先阅读 配置说明 与 建表与数据模型;关闭状态与开启状态的数据结构不同,切换不是运行时开关。

8. 相关文档​