跳到主要内容

多租户业务功能

本文从使用视角说明多租户开启后能做什么、典型流程是什么,以及哪些边界是刻意不做的。

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. 企业切换​

用户在一个企业内点击“切换企业”时:

  1. 通过 GET /api/auth/account/person/tenants 或 GET /api/auth/my/tenants 获取已关联企业;
  2. 点击目标企业后导航到目标子域名;
  3. 目标子域有有效令牌就直接进入,否则进入目标租户登录页。

不做跨租户令牌交换,也不提供 SSO 一次性 code。切换失败或目标企业无权限时,停在目标企业的登录页或无权限页是正常流程。

移动端的做法是:先注销当前租户推送,再清理本地会话,然后以新企业代码重新登录;同一时刻只保留一个租户会话。

6. 成员邀请​

租户管理员或平台管理员可以发起邀请:

  1. 填写邮箱/手机号、预分配角色、预分配组织;
  2. 服务端校验该联系方式在本租户是否已有账号;
  3. 创建 auth_tenant_invitation,token 哈希存储、单次使用、默认 7 天有效;
  4. 被邀请人通过邀请链接接受:
    • 租户内没有账号:先创建待激活账号;
    • 有平台账号:验证平台凭据后建立关联;
    • 没有平台账号:创建平台账号并建立关联;
    • 租户需要审批:关联先为 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 的资源;查不到就是查不到,不会回退到系统租户。

业务方仍需要遵守两条规则:

  1. 租户表实体继承 TenantBaseEntity,或实现 TenantScoped 并提供 tenantId 字段;手写 SQL 显式带 tenant_id;
  2. 在没有租户上下文的入口(定时任务、消息消费、命令行)显式使用 TenantContext.runAs(defaultTenantId, ...);多租户下禁止静默回退默认租户。

11. 刻意不做​

  • 自定义域名(当前只有一层租户子域名);
  • 跨租户免密切换 / SSO 一次性 code;
  • 跨租户令牌交换;
  • 平台管理员代登录或模拟登录;
  • 平台管理员读取用户密码、OAuth secret、会话令牌;
  • 存量单租户数据自动迁移/回填;
  • 租户级 SAML/OIDC 企业 IdP、机器对机器 API 客户端、计费与配额。

12. 相关文档​