多租户业务功能
本文从使用视角说明多租户开启后能做什么、典型流程是什么,以及哪些边界是刻意不做的。
1. 能力地图
| 能力 | 使用者 | 说明 |
|---|---|---|
| 租户品牌与登录配置 | 所有访问者 | 按子域名或企业码返回租户名称、Logo、登录方式开关 |
| 租户登录 | 租户成员 | 用户名密码、手机验证码、邮箱验证码、租户 OAuth |
| 平台账号强制绑定 | 首次登录的租户成员 | 创建新平台账号或绑定已有平台账号 |
| 平台账号自助 | 已绑定用户 | 资料、密码、邮箱/手机号、我的企业、绑定关系 |
| 企业切换 | 已绑定用户 | 展示已关联企业并导航到目标子域 |
| 成员邀请 | 租户管理员/平台管理员 | 邀请邮箱/手机号加入租户 |
| 租户设置 | 租户管理员 | 名称、Logo、联系邮箱、扩展设置 JSON |
| 租户 OAuth 配置 | 租户管理员/平台管理员 | 配置本租户的第三方登录凭据 |
| 平台租户管理 | 平台管理员 | 创建、更新、启停、删除租户,维护子域名 |
| 平台账号查询 | 平台管理员 | 分页查看平台账号,用于排障 |
2. 租户识别与登录页
租户的识别方式:
- Web:优先使用子域名,如
acme.app.example.com; - 移动端:没有子域名,使用构建配置、上次选择、企业码输入或深链
?tenantCode=acme; - 登录页手动输入:通过
X-Tenant-Code请求头传递企业代码。
租户识别成功后,GET /api/frontend/init 与 GET /api/auth/get-auth-config 返回该租户的品牌信息和登录方式开关。租户状态不是 ACTIVE 时,登录与业务请求都会被拒绝。
3. 平台账号与租户账号
3.1 两层身份
- 平台账号是跨企业的全局身份,用于关联你在各企业的账号;
- 租户账号是你在某个企业内的身份,角色、组织、权限都挂在这里;
- 同一个平台账号可以关联多个租户;同一个租户内的一个平台账号只能关联一个租户账号。
平台账号不单独登录。当前实现中,平台资料、联系方式、我的企业等能力都通过当前租户会话读写,personId 由后端从令牌中读取,客户端不能指定。
3.2 平台账号自助
已绑定用户可以在“平台账号”面板完成:
- 查看用户名、展示名、状态、最近登录;
- 修改展示名;
- 修改平台密码;
- 绑定/换绑平台邮箱或手机号(需要平台绑定专用验证码);
- 查看已关联企业并进入;
- 查看/解绑平台账号与租户账号的关联;
- 退出所有企业(撤销该平台账号的全部租户会话)。
4. 强制绑定
4.1 为什么强制
平台账号是“人”的全局身份。没有平台账号,用户无法跨企业识别、无法统一找回、也无法在企业切换时确认“这些账号是同一个人”。因此多租户开启后,租户登录成功但未绑定平台账号时不会签发令牌。
4.2 用户看到什么
登录接口返回 bindingRequired=true,并带上:
{
"bindingRequired": true,
"bindingReason": "NO_LINK",
"linkStatus": "NONE",
"pendingApproval": false,
"bindingTicket": "一次性票据",
"tenantCode": "acme",
"proposedUsername": "zhangsan",
"proposedDisplayName": "张三",
"email": "zhangsan@acme.com",
"phone": "13800000000"
}
绑定页提供两个选择:
| 选择 | 适用场景 |
|---|---|
| 设置平台账号(创建新账号) | 用户还没有平台账号;默认用租户用户名作为建议值 |
| 登录已有平台账号 | 用户已经有一个平台账号,希望关联当前企业账号 |
预填的邮箱/手机号只是待验证值,不能因为和某个平台账号相同就自动关联。
4.3 审批中的关联
如果租户开启加入审批,绑定完成后关联为 PENDING,响应 pendingApproval=true,不签发令牌。用户需要等待管理员批准,批准后重新登录才会签发令牌。
4.4 关联被撤销
关联被用户或管理员撤销后变为 REVOKED。再次登录仍会进入绑定页,必须重新完成一次显式绑定;由于 (tenant_id, user_id) 唯一,重新绑定更新原记录,不新增第二条。
5. 企业切换
用户在一个企业内点击“切换企业”时:
- 通过
GET /api/auth/account/person/tenants或GET /api/auth/my/tenants获取已关联企业; - 点击目标企业后导航到目标子域名;
- 目标子域有有效令牌就直接进入,否则进入目标租户登录页。
不做跨租户令牌交换,也不提供 SSO 一次性 code。切换失败或目标企业无权限时,停在目标企业的登录页或无权限页是正常流程。
移动端的做法是:先注销当前租户推送,再清理本地会话,然后以新企业代码重新登录;同一时刻只保留一个租户会话。
6. 成员邀请
租户管理员或平台管理员可以发起邀请:
- 填写邮箱/手机号、预分配角色、预分配组织;
- 服务端校验该联系方式在本租户是否已有账号;
- 创建
auth_tenant_invitation,token 哈希存储、单次使用、默认 7 天有效; - 被邀请人通过邀请链接接受:
- 租户内没有账号:先创建待激活账号;
- 有平台账号:验证平台凭据后建立关联;
- 没有平台账号:创建平台账号并建立关联;
- 租户需要审批:关联先为
PENDING。
邀请 token 绑定租户,不能跨租户使用。仅联系方式相同不会自动关联平台账号。
7. 租户 OAuth2
平台维护 provider 目录(GitHub、微信 web/mini 等),租户按需配置自己的登录 App:
- 配置项包括
client_id、client_secret、回调地址、前端回调白名单、授权/令牌/用户信息端点、scope; client_secret加密落库,接口永不返回明文;- 租户配置不继承系统租户凭据,未配置就是不可用;
- 租户管理员只能配置平台允许的 provider;平台管理员可以代配任意租户;
- 租户 OAuth 登录只签发租户会话,不自动创建或登录平台账号;未绑定的租户用户仍然进入绑定流程。
8. 平台租户管理
平台管理员在默认租户内可以:
- 分页查询租户(按关键字、状态);
- 创建租户(编码、名称、子域名、Logo、联系邮箱、设置 JSON、管理员账号信息);
- 更新租户资料;
- 启用、暂停、标记过期、删除租户;
- 维护租户域名(主域名、附加域名);
- 创建和查看租户邀请;
- 分页查询平台账号。
默认租户不能暂停或删除。删除租户是软删除(状态置 DELETED),会禁用域名并撤销该租户全部平台账号关联。
9. 租户设置
租户管理员可以读写当前租户设置:
- 名称、Logo、联系邮箱;
settings_json扩展配置,当前已使用requireApproval控制新绑定是否需要审批。
平台管理员也可以读写当前租户设置,但仍受当前租户上下文约束;跨租户操作要走平台租户管理接口。
10. 数据隔离对业务的意义
开启多租户后,业务模块不需要自己写租户条件:
- 租户表自动按
tenant_id过滤;写入时由TenantIdResolver显式填充默认租户/当前租户,数据库无 DEFAULT; - 缓存自动按租户隔离;
- 异步任务、领域事件、调度任务、文件 key、审计记录都带租户;
- 租户 A 的用户无法通过 ID 直接访问租户 B 的资源;查不到就是查不到,不会回退到系统租户。
业务方仍需要遵守两条规则:
- 租户表实体继承
TenantBaseEntity,或实现TenantScoped并提供tenantId字段;手写 SQL 显式带tenant_id; - 在没有租户上下文的入口(定时任务、消息消费、命令行)显式使用
TenantContext.runAs(defaultTenantId, ...);多租户下禁止静默回退默认租户。
11. 刻意不做
- 自定义域名(当前只有一层租户子域名);
- 跨租户免密切换 / SSO 一次性 code;
- 跨租户令牌交换;
- 平台管理员代登录或模拟登录;
- 平台管理员读取用户密码、OAuth secret、会话令牌;
- 存量单租户数据自动迁移/回填;
- 租户级 SAML/OIDC 企业 IdP、机器对机器 API 客户端、计费与配额。