跳到主要内容

多租户配置说明

1. 配置总览​

多租户相关配置分为两组:

  • nebula.tenant.*:租户开关、域名解析、表/缓存分类;
  • nebula.person.*:平台账号绑定票据与用户名校验。
nebula:
tenant:
enabled: true
strict: true
header: X-Tenant-Id
code-header: X-Tenant-Code
default-tenant-id: "0194f3c8b6b77c0d91a7d9af9c7d0100"
system-tenant-id: "__system__"
auth-domain: auth.app.example.com
base-domains:
- app.example.com
reserved-subdomains:
- www
- admin
- auth
- login
- static
- docs
- status
- api
- gateway
ignore-tables: []
ignore-caches:
- authSessionCache
- bindingTicketCache
- oauth2LoginStateCache
- oauth2BindStateCache
- tenantByDomainCache
person:
binding-ticket-ttl-seconds: 600
username-min-length: 3
username-max-length: 32

2. nebula.tenant.*​

配置项默认值说明
enabledfalse是否启用多租户;关闭时不启用租户解析、租户选择和平台账号绑定,但租户拦截器仍然生效
stricttrue启动时校验所有 MyBatis 实体表已分类;多租户下未分类直接启动失败,单租户下只汇总提示
headerX-Tenant-Id内部请求传播的租户 ID 头,仅用于可信内网
code-headerX-Tenant-Code匿名请求选择租户的编码头
default-tenant-id0194f3c8b6b77c0d91a7d9af9c7d0100默认租户 ID;单租户下所有请求与写入都归属该租户,多租户下用于启动期和平台级操作
system-tenant-id__system__系统租户 ID,仅作为新建租户的模板源
auth-domain无平台账号中心域名,如 auth.app.example.com
base-domains空允许的租户基础域列表,用于 Host 子域名解析
reserved-subdomains内置 9 个保留子域,不能分配给租户
ignore-tables空额外按全局表处理的表名
tenant-tables空没有实体类的租户表扩展清单;有实体的表通过实现 TenantScoped 自动识别
ignore-caches内置列表额外按全局缓存处理的缓存名,不参与租户前缀

2.1 enabled​

  • false:不启用租户解析和平台账号绑定,也不启用租户缓存前缀;TenantContextFilter 为每个请求设置 default-tenant-id 上下文,租户拦截器仍然注册,所有租户表读写都限定在默认租户,系统租户模板数据不会进入业务查询。
  • true:启用完整链路;平台账号层自动启用,租户登录必须完成绑定;缺少租户上下文的后台写入直接失败,不回退默认租户。

这是部署级开关,不是运行时热切换开关。数据库结构必须先按多租户版本初始化。

2.2 strict​

  • true:多租户启动时通过 TenantTableRegistry.validate() 检查所有已注册实体表;发现未分类表直接抛异常,阻止启动。
  • false:多租户下未分类表按全局表处理并汇总输出一条 WARN。
  • 单租户下两种取值都不会阻止启动,未分类表按全局表放行,只汇总提示一次;开启 enabled=true 前必须完成分类。

生产环境建议保持 true,避免新表漏加租户条件导致数据串租户。临时接入历史表时可以用 ignore-tables 显式登记为全局表。

2.3 base-domains​

用于判断 Host 是否是租户子域名:

  • 只接受一层子域名,例如 acme.app.example.com;
  • app.example.com 本身不是租户;
  • a.b.app.example.com 不是租户;
  • 不在列表中的域名不解析为租户。

通常配置一个基础域,配合通配证书 *.app.example.com。

2.4 auth-domain​

平台账号中心域名,Web 端用它判断当前是否在平台域。默认保留子域中包含 auth,因此该域名不会被解析为租户。

2.5 default-tenant-id​

  • 必填;单租户模式下所有请求、后台任务和写入都由 TenantIdResolver 解析到该值;
  • 数据库的 tenant_id 列没有 DEFAULT,值只来自租户上下文或该配置;
  • 启动时校验该 ID 对应的 auth_tenant 行存在且状态为 ACTIVE;
  • 多租户模式下用于启动期、平台级操作和显式 TenantContext.runAs(defaultTenantId),普通请求仍以会话/域名租户为准;
  • 新建租户的模板来自系统租户,平台级配置和平台管理员归属默认租户;
  • PlatformAdminGuard 要求当前租户等于该值,否则平台管理接口返回 19014;
  • 默认租户不能暂停、不能删除(19021)。

2.6 system-tenant-id​

系统租户只作为模板命名空间:

  • 保存组织、角色、管理员账号、菜单/按钮/API 目录、权限、字典、通知模板等模板数据;
  • 不分配域名;
  • TenantResolver 会拒绝把系统租户解析为登录租户;
  • 运行时业务查询不会回退到系统租户。

2.7 ignore-tables​

用于把额外的表按全局表处理,不参与自动租户过滤。适用于:

  • 确实没有 tenant_id 的全局配置表;
  • 第三方/框架表;
  • 迁移期间的临时表。

不要把租户表误登记到 ignore-tables,否则会绕开自动隔离。

2.8 ignore-caches​

默认全局缓存包括:

authSessionCache
bindingTicketCache
oauth2LoginStateCache
oauth2BindStateCache
loginFailCountCache
loginLockCache
phoneVerificationCodeCache
emailVerificationCodeCache
phoneSendTimestampCache
emailSendTimestampCache
forgotPasswordCodeCache
forgotPasswordSendTimestampCache
forgotPasswordChangeTokenCache
tenantByDomainCache
personBindCodeCache
personBindCodeSendTimestampCache

这些缓存的 key 本身是高熵一次性值,且读取发生在租户上下文建立之前,必须保持全局命名空间。新增此类缓存时要登记到这里;普通业务缓存不要登记,否则会失去租户隔离。

3. nebula.person.*​

配置项默认值说明
binding-ticket-ttl-seconds600绑定票据有效期,单位秒
username-min-length3平台用户名最小长度
username-max-length32平台用户名最大长度

平台账号层不单独开关,随 nebula.tenant.enabled=true 自动启用。

4. 初始化数据​

初始化 SQL 中包含两个特殊租户:

租户ID编码说明
默认租户0194f3c8b6b77c0d91a7d9af9c7d0100default第一个真实租户,同时是主租户
系统租户__system__system模板命名空间,不可登录

默认租户包含:

  • 管理员账号 admin;
  • ADMIN 角色、ROOT 组织;
  • user-role、user-org 关联;
  • 菜单、按钮、API 目录与 ADMIN 授权;
  • 平台管理员平台账号 platform_admin;
  • 平台管理员与默认租户管理员的绑定关系;
  • provider 目录(GitHub、微信 web/mini)。

系统租户保存同一套模板数据,供新建租户复制。新建租户的模板管理员默认 admin / 123456,创建租户时可以通过 adminUsername / adminPassword / adminNickname / adminEmail / adminPhone 覆盖。

5. SQL 文件​

文件说明
docs/sql/init/postgresql/01-init-structure.sqlPostgreSQL 表结构(默认方言,含租户字段与新增表)
docs/sql/init/postgresql/02-init-data.sqlPostgreSQL 初始化数据(默认租户、系统租户、平台管理员等)
docs/sql/init/mysql/01-init-structure.sqlMySQL 表结构(可选方言)
docs/sql/init/mysql/02-init-data.sqlMySQL 初始化数据(可选方言)

多租户改造只修改全量初始化 SQL,不提供 unreleased 增量迁移脚本,也不做存量数据回填。当前数据库均为开发库,直接删库后执行初始化脚本重建即可。

6. 配置与部署建议​

  • 域名与证书:准备 *.app.example.com 通配证书,auth 保留子域同时覆盖;
  • 默认租户:default-tenant-id 必须与初始化 SQL 一致;启动时会校验该租户存在且为 ACTIVE,不一致直接启动失败;
  • 网关:外部请求不要透传 X-Tenant-Id;匿名请求只允许 X-Tenant-Code;
  • 反向代理:确保 Host 正确传递,且只信任可信代理的 Host / X-Forwarded-Host;
  • 监控:关注 TENANT_CONTEXT_MISSING、租户解析失败、未分类表 WARN、绑定失败率;
  • 备份:删除租户是软删除,但域名会禁用、关联会撤销;恢复需要单独处理。

7. 相关文档​