Spring Boot 4 + Vue3 企业级多租户 SaaS：从共享 Schema 架构到商业化套餐设计

前言

多租户系统是 SaaS 产品的基石，但其复杂性往往不在于代码实现，而在于初始的模型设计。一个好的设计能让业务开发事半功倍，反之则后患无穷。本文基于 youlai-boot-tenant 和 vue3-element-admin，从真实工程经验出发，为你拆解一套生产级的共享 Schema 多租户方案。

本文看点：

• 模型选择：为什么共享 Schema 是 90% SaaS 产品的首选？
• 核心设计：平台与租户的边界在哪里？如何设计用户角色？
• 权限模型：如何用“三层漏斗模型”（套餐、租户、角色）实现灵活的菜单权限？
• 后端实现：如何用 TransmittableThreadLocal + MyBatis-Plus 插件实现业务代码无感知的租户隔离？
• 生产实践：数据库索引如何设计？Nginx 关键配置是什么？

一、模式选择

在写代码之前，必须先选清楚多租户模式，否则后续所有设计都会反复推翻。

1.1 三种模式

1.2 方案选择

共享数据库 + 共享 Schema + tenant_id 行级隔离

这是 90% SaaS 系统第一阶段最稳妥、性价比最高的方案。

二、模型设计

2.1 平台租户价值

在实际 SaaS 系统中，平台管理员需要做这些工作：

• 系统配置管理：管理菜单、权限、系统参数
• 租户业务管理：查看各租户数据，协助排查问题
• 业务实时监控：实时了解各租户业务运行状况

没有平台租户时的痛点：

有了平台租户（tenant_id=0）的优势：

• 在平台视角查看系统配置、租户列表
• 一键切换到任意租户视角查看具体业务数据
• 无需频繁切换账号，统一管理所有租户

2.2 设计方案

#mermaid-svg-oCpcfgsfr5vNZdGJ{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-oCpcfgsfr5vNZdGJ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-oCpcfgsfr5vNZdGJ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-oCpcfgsfr5vNZdGJ .error-icon{fill:#552222;}#mermaid-svg-oCpcfgsfr5vNZdGJ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-oCpcfgsfr5vNZdGJ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-oCpcfgsfr5vNZdGJ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-oCpcfgsfr5vNZdGJ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-oCpcfgsfr5vNZdGJ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-oCpcfgsfr5vNZdGJ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-oCpcfgsfr5vNZdGJ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-oCpcfgsfr5vNZdGJ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-oCpcfgsfr5vNZdGJ .marker.cross{stroke:#333333;}#mermaid-svg-oCpcfgsfr5vNZdGJ svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-oCpcfgsfr5vNZdGJ p{margin:0;}#mermaid-svg-oCpcfgsfr5vNZdGJ .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-oCpcfgsfr5vNZdGJ .cluster-label text{fill:#333;}#mermaid-svg-oCpcfgsfr5vNZdGJ .cluster-label span{color:#333;}#mermaid-svg-oCpcfgsfr5vNZdGJ .cluster-label span p{background-color:transparent;}#mermaid-svg-oCpcfgsfr5vNZdGJ .label text,#mermaid-svg-oCpcfgsfr5vNZdGJ span{fill:#333;color:#333;}#mermaid-svg-oCpcfgsfr5vNZdGJ .node rect,#mermaid-svg-oCpcfgsfr5vNZdGJ .node circle,#mermaid-svg-oCpcfgsfr5vNZdGJ .node ellipse,#mermaid-svg-oCpcfgsfr5vNZdGJ .node polygon,#mermaid-svg-oCpcfgsfr5vNZdGJ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-oCpcfgsfr5vNZdGJ .rough-node .label text,#mermaid-svg-oCpcfgsfr5vNZdGJ .node .label text,#mermaid-svg-oCpcfgsfr5vNZdGJ .image-shape .label,#mermaid-svg-oCpcfgsfr5vNZdGJ .icon-shape .label{text-anchor:middle;}#mermaid-svg-oCpcfgsfr5vNZdGJ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-oCpcfgsfr5vNZdGJ .rough-node .label,#mermaid-svg-oCpcfgsfr5vNZdGJ .node .label,#mermaid-svg-oCpcfgsfr5vNZdGJ .image-shape .label,#mermaid-svg-oCpcfgsfr5vNZdGJ .icon-shape .label{text-align:center;}#mermaid-svg-oCpcfgsfr5vNZdGJ .node.clickable{cursor:pointer;}#mermaid-svg-oCpcfgsfr5vNZdGJ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-oCpcfgsfr5vNZdGJ .arrowheadPath{fill:#333333;}#mermaid-svg-oCpcfgsfr5vNZdGJ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-oCpcfgsfr5vNZdGJ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-oCpcfgsfr5vNZdGJ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-oCpcfgsfr5vNZdGJ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-oCpcfgsfr5vNZdGJ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-oCpcfgsfr5vNZdGJ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-oCpcfgsfr5vNZdGJ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-oCpcfgsfr5vNZdGJ .cluster text{fill:#333;}#mermaid-svg-oCpcfgsfr5vNZdGJ .cluster span{color:#333;}#mermaid-svg-oCpcfgsfr5vNZdGJ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-oCpcfgsfr5vNZdGJ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-oCpcfgsfr5vNZdGJ rect.text{fill:none;stroke-width:0;}#mermaid-svg-oCpcfgsfr5vNZdGJ .icon-shape,#mermaid-svg-oCpcfgsfr5vNZdGJ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-oCpcfgsfr5vNZdGJ .icon-shape p,#mermaid-svg-oCpcfgsfr5vNZdGJ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-oCpcfgsfr5vNZdGJ .icon-shape rect,#mermaid-svg-oCpcfgsfr5vNZdGJ .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-oCpcfgsfr5vNZdGJ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-oCpcfgsfr5vNZdGJ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-oCpcfgsfr5vNZdGJ :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

平台管理员

平台视角 tenant_id=0

切换租户

租户管理

系统配置

租户A tenant_id=1

租户B tenant_id=2

查看租户A业务数据

查看租户B业务数据

核心设计：平台也是一个特殊的租户（tenant_id=0）

// 统一的数据访问逻辑，tenant_id=0 代表平台
String sql = "SELECT * FROM users WHERE tenant_id = ?";

// 应用场景：
// 1. 平台管理员查看平台配置：tenant_id = 0
// 2. 平台管理员切换到租户A查看数据：tenant_id = 1
// 3. 租户A员工查看自己数据：tenant_id = 1

2.3 用户角色设计

三、权限设计

多租户的权限设计，就像是为每个租户分配一个带锁的抽屉柜，既要保证每个租户只能打开自己的抽屉，又要能灵活地给不同级别的租户配置不同数量和类型的抽屉。本项目通过一个“三层过滤模型”来实现这一目标。

3.1 漏斗模型

一个用户最终能看到哪些菜单，取决于三层过滤的结果。我们可以把它想象成一个漏斗：

#mermaid-svg-gBZaStl1AVn4GCZC{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-gBZaStl1AVn4GCZC .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-gBZaStl1AVn4GCZC .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-gBZaStl1AVn4GCZC .error-icon{fill:#552222;}#mermaid-svg-gBZaStl1AVn4GCZC .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-gBZaStl1AVn4GCZC .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-gBZaStl1AVn4GCZC .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-gBZaStl1AVn4GCZC .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-gBZaStl1AVn4GCZC .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-gBZaStl1AVn4GCZC .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-gBZaStl1AVn4GCZC .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-gBZaStl1AVn4GCZC .marker{fill:#333333;stroke:#333333;}#mermaid-svg-gBZaStl1AVn4GCZC .marker.cross{stroke:#333333;}#mermaid-svg-gBZaStl1AVn4GCZC svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-gBZaStl1AVn4GCZC p{margin:0;}#mermaid-svg-gBZaStl1AVn4GCZC .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-gBZaStl1AVn4GCZC .cluster-label text{fill:#333;}#mermaid-svg-gBZaStl1AVn4GCZC .cluster-label span{color:#333;}#mermaid-svg-gBZaStl1AVn4GCZC .cluster-label span p{background-color:transparent;}#mermaid-svg-gBZaStl1AVn4GCZC .label text,#mermaid-svg-gBZaStl1AVn4GCZC span{fill:#333;color:#333;}#mermaid-svg-gBZaStl1AVn4GCZC .node rect,#mermaid-svg-gBZaStl1AVn4GCZC .node circle,#mermaid-svg-gBZaStl1AVn4GCZC .node ellipse,#mermaid-svg-gBZaStl1AVn4GCZC .node polygon,#mermaid-svg-gBZaStl1AVn4GCZC .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-gBZaStl1AVn4GCZC .rough-node .label text,#mermaid-svg-gBZaStl1AVn4GCZC .node .label text,#mermaid-svg-gBZaStl1AVn4GCZC .image-shape .label,#mermaid-svg-gBZaStl1AVn4GCZC .icon-shape .label{text-anchor:middle;}#mermaid-svg-gBZaStl1AVn4GCZC .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-gBZaStl1AVn4GCZC .rough-node .label,#mermaid-svg-gBZaStl1AVn4GCZC .node .label,#mermaid-svg-gBZaStl1AVn4GCZC .image-shape .label,#mermaid-svg-gBZaStl1AVn4GCZC .icon-shape .label{text-align:center;}#mermaid-svg-gBZaStl1AVn4GCZC .node.clickable{cursor:pointer;}#mermaid-svg-gBZaStl1AVn4GCZC .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-gBZaStl1AVn4GCZC .arrowheadPath{fill:#333333;}#mermaid-svg-gBZaStl1AVn4GCZC .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-gBZaStl1AVn4GCZC .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-gBZaStl1AVn4GCZC .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-gBZaStl1AVn4GCZC .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-gBZaStl1AVn4GCZC .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-gBZaStl1AVn4GCZC .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-gBZaStl1AVn4GCZC .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-gBZaStl1AVn4GCZC .cluster text{fill:#333;}#mermaid-svg-gBZaStl1AVn4GCZC .cluster span{color:#333;}#mermaid-svg-gBZaStl1AVn4GCZC div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-gBZaStl1AVn4GCZC .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-gBZaStl1AVn4GCZC rect.text{fill:none;stroke-width:0;}#mermaid-svg-gBZaStl1AVn4GCZC .icon-shape,#mermaid-svg-gBZaStl1AVn4GCZC .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-gBZaStl1AVn4GCZC .icon-shape p,#mermaid-svg-gBZaStl1AVn4GCZC .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-gBZaStl1AVn4GCZC .icon-shape rect,#mermaid-svg-gBZaStl1AVn4GCZC .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-gBZaStl1AVn4GCZC .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-gBZaStl1AVn4GCZC .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-gBZaStl1AVn4GCZC :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

所有业务菜单

第一层过滤 套餐边界

第二层过滤 租户配置

第三层过滤 角色权限

用户最终可见菜单

说明： 套餐决定功能上限，租户决定实际启用范围，角色决定用户可见权限。

3.2 三层模型详解

总结：一个用户最终能看到的菜单，是 套餐边界 ∩ 租户配置 ∩ 角色权限 的三者交集。

3.3 套餐示例

• 基础套餐：包含核心的系统管理功能，例如：用户管理、角色管理、部门管理、字典管理等。
• 高级套餐：在基础套餐之上，额外提供代码生成、AI 助手、功能演示等所有业务功能模块。

3.4 核心表结构

— 菜单表：新增 scope 字段区分平台和业务菜单
CREATE TABLE `sys_menu` (
`id` bigint NOT NULL AUTO_INCREMENT,
`name` varchar(64) NOT NULL COMMENT '菜单名称',
`scope` tinyint(1) NOT NULL DEFAULT 2 COMMENT '菜单范围(1=平台菜单 2=业务菜单)',
— … 其他字段
PRIMARY KEY (`id`)
);

— 租户套餐表：定义不同的服务级别
CREATE TABLE `sys_tenant_plan` (
`id` bigint NOT NULL AUTO_INCREMENT COMMENT '套餐ID',
`name` varchar(100) NOT NULL COMMENT '套餐名称',
`code` varchar(50) NOT NULL COMMENT '套餐编码',
— … 其他字段
PRIMARY KEY (`id`)
);

— 套餐菜单关联表：定义套餐的菜单边界
CREATE TABLE `sys_tenant_plan_menu` (
`plan_id` bigint NOT NULL COMMENT '套餐ID',
`menu_id` bigint NOT NULL COMMENT '菜单ID',
PRIMARY KEY (`plan_id`, `menu_id`)
);

— 租户菜单关联表：租户个性化菜单配置
CREATE TABLE `sys_tenant_menu` (
`tenant_id` bigint NOT NULL COMMENT '租户ID',
`menu_id` bigint NOT NULL COMMENT '菜单ID',
PRIMARY KEY (`tenant_id`, `menu_id`)
);

四、后端实现

理解了租户模型的设计原理，我们再来思考技术实现：

既然 tenant_id 如此重要，它如何在系统中安全、准确地传递？

4.1 请求链路

数据库

MyBatis Mapper

业务服务

租户上下文

租户过滤器

客户端

数据库

MyBatis Mapper

业务服务

租户上下文

租户过滤器

客户端

#mermaid-svg-TsA8tYRhOeRkqxkQ{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-TsA8tYRhOeRkqxkQ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-TsA8tYRhOeRkqxkQ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-TsA8tYRhOeRkqxkQ .error-icon{fill:#552222;}#mermaid-svg-TsA8tYRhOeRkqxkQ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-TsA8tYRhOeRkqxkQ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-TsA8tYRhOeRkqxkQ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-TsA8tYRhOeRkqxkQ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-TsA8tYRhOeRkqxkQ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-TsA8tYRhOeRkqxkQ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-TsA8tYRhOeRkqxkQ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-TsA8tYRhOeRkqxkQ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-TsA8tYRhOeRkqxkQ .marker.cross{stroke:#333333;}#mermaid-svg-TsA8tYRhOeRkqxkQ svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-TsA8tYRhOeRkqxkQ p{margin:0;}#mermaid-svg-TsA8tYRhOeRkqxkQ .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-TsA8tYRhOeRkqxkQ text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-TsA8tYRhOeRkqxkQ .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-TsA8tYRhOeRkqxkQ .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-TsA8tYRhOeRkqxkQ .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-TsA8tYRhOeRkqxkQ .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-TsA8tYRhOeRkqxkQ #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-TsA8tYRhOeRkqxkQ .sequenceNumber{fill:white;}#mermaid-svg-TsA8tYRhOeRkqxkQ #sequencenumber{fill:#333;}#mermaid-svg-TsA8tYRhOeRkqxkQ #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-TsA8tYRhOeRkqxkQ .messageText{fill:#333;stroke:none;}#mermaid-svg-TsA8tYRhOeRkqxkQ .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-TsA8tYRhOeRkqxkQ .labelText,#mermaid-svg-TsA8tYRhOeRkqxkQ .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-TsA8tYRhOeRkqxkQ .loopText,#mermaid-svg-TsA8tYRhOeRkqxkQ .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-TsA8tYRhOeRkqxkQ .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-TsA8tYRhOeRkqxkQ .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-TsA8tYRhOeRkqxkQ .noteText,#mermaid-svg-TsA8tYRhOeRkqxkQ .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-TsA8tYRhOeRkqxkQ .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-TsA8tYRhOeRkqxkQ .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-TsA8tYRhOeRkqxkQ .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-TsA8tYRhOeRkqxkQ .actorPopupMenu{position:absolute;}#mermaid-svg-TsA8tYRhOeRkqxkQ .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-TsA8tYRhOeRkqxkQ .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-TsA8tYRhOeRkqxkQ .actor-man circle,#mermaid-svg-TsA8tYRhOeRkqxkQ line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-TsA8tYRhOeRkqxkQ :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

解析租户ID

1. 从Token解析

2. 从域名匹配

MyBatis-Plus拦截器

自动添加 tenant_id 条件

请求结束清理

HTTP请求（携带Token/域名）

TenantContextHolder.setTenantId(id)

userMapper.selectList(query)

SELECT * FROM user WHERE tenant_id = ?

查询结果

返回数据

响应结果

TenantContextHolder.clear()

4.2 上下文方案

ThreadLocal 的问题：

• ❌ 线程池场景下丢失上下文
• ❌ @Async 异步任务中失效
• ❌ 多租户数据安全风险高

TransmittableThreadLocal 的优势：

• ✅ 解决父子线程上下文传递
• ✅ 线程池和异步场景安全
• ✅ 阿里开源，生产验证

public class TenantContextHolder {
// 使用 TransmittableThreadLocal 存储租户 ID 和忽略标志
private static final TransmittableThreadLocal<Long> TENANT_ID_HOLDER = new TransmittableThreadLocal<>();
private static final TransmittableThreadLocal<Boolean> IGNORE_TENANT_HOLDER = new TransmittableThreadLocal<>();

// 设置/获取当前租户 ID
public static void setTenantId(Long tenantId) { /* … */ }
public static Long getTenantId() { /* … */ }

// 设置/获取是否忽略租户过滤
public static void setIgnoreTenant(boolean ignore) { /* … */ }
public static boolean isIgnoreTenant() { /* … */ }

// 清理上下文，防止内存泄漏
public static void clear() { /* … */ }
}

4.3 Mybatis-Plus 插件

该插件的核心是实现 TenantLineHandler 接口，告诉 MyBatis-Plus 如何获取租户 ID、租户字段名以及哪些表需要忽略。

MyTenantLineHandler.java

// MyTenantLineHandler.java
@Component
public class MyTenantLineHandler implements TenantLineHandler {

// 从上下文中获取租户 ID
@Override
public Expression getTenantId() { /* … */ }

// 获取租户字段名（如 "tenant_id"）
@Override
public String getTenantIdColumn() { /* … */ }

// 判断是否忽略特定表的租户过滤
@Override
public boolean ignoreTable(String tableName) { /* … */ }
}

MybatisConfig.java

然后，在 MyBatis-Plus 的主配置中注册这个处理器。

// MybatisConfig.java
@Configuration
public class MybatisConfig {

@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
// 1. 多租户插件（必须在最前面）
interceptor.addInnerInterceptor(new TenantLineInnerInterceptor(myTenantLineHandler));
// 2. 其他插件（如数据权限、分页）
// …
return interceptor;
}
}

4.4 SQL 拦截效果

原始 SQL：

SELECT * FROM sys_user;

实际执行 SQL（tenant_id=1 时）：

SELECT * FROM sys_user WHERE tenant_id = 1;

4.5 Filter 实现

// TenantContextFilter.java
@Component
@Order(1)
public class TenantContextFilter extends OncePerRequestFilter {

@Override
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) {
try {
// 解析租户 ID 并设置到上下文
Long tenantId = resolveTenantId(request);
if (tenantId != null) {
TenantContextHolder.setTenantId(tenantId);
}
chain.doFilter(request, response);
} finally {
// 清理上下文
TenantContextHolder.clear();
}
}

private Long resolveTenantId(HttpServletRequest request) {
// 核心解析逻辑：
// 1. 从已认证信息 SecurityContext 中获取
// 2. 尝试从请求头 Token 中解析
// 3. 尝试从域名中解析
// …
return tenantId;
}
}

4.6 菜单权限实现

4.6.1 获取当前用户路由（核心）

MenuServiceImpl 中的 listCurrentUserRoutes 方法是整个菜单权限的核心，它精确处理了平台管理员和租户用户的不同场景，并整合了三层漏斗模型的过滤逻辑。

// MenuServiceImpl.java
@Override
public List<RouteVO> listCurrentUserRoutes() {
try {
// 核心逻辑步骤：
// 1. 手动控制租户上下文，临时忽略租户插件
TenantContextHolder.setIgnoreTenant(true);

// 2. 获取套餐菜单边界 (漏斗第一层)
Set<Long> planMenuIdSet = resolveTenantPlanMenuIdSet(targetTenantId);

// 3. 根据用户角色获取菜单 (漏斗第二、三层)
List<Menu> menuList = getMenusByRoles();

// 4. 使用套餐边界过滤菜单
List<Menu> filteredMenuList = menuList.stream()
.filter(menu -> planMenuIdSet.contains(menu.getId()))
.collect(Collectors.toList());

// 5. 构建路由并返回
return buildRoutes(filteredMenuList);
} finally {
// 恢复租户上下文
TenantContextHolder.clear();
}
}

4.6.2 套餐菜单边界解析

resolveTenantPlanMenuIdSet 方法体现了“套餐未配则授权所有业务菜单”的兜底策略，确保了系统的健壮性。

// MenuServiceImpl.java
private Set<Long> resolveTenantPlanMenuIdSet(Long tenantId) {
try {
TenantContextHolder.setIgnoreTenant(true);
// … 省略查询租户套餐和套餐菜单的逻辑

// 兜底逻辑：若套餐未配置菜单，则返回所有业务菜单
List<Long> fallbackMenuIds = this.list(new LambdaQueryWrapper<Menu>()
.select(Menu::getId)
.eq(Menu::getScope, MenuScopeEnum.TENANT.getValue()))
.stream()
.map(Menu::getId)
.collect(Collectors.toList());
return new HashSet<>(fallbackMenuIds);
} finally {
// … 恢复上下文
}
}

五、前端实现：租户切换

前端不参与租户隔离逻辑，只负责给平台租户管理员一个切换入口。

5.1 前端切换组件

在布局组件（如 LayoutToolbar.vue）中，我们使用一个简单的下拉菜单组件来展示租户列表，并绑定切换事件。

<template>
<!– 仅当用户可切换且租户列表多于一个时显示 –>
<TenantSwitcher v-if="showTenantSwitcher" @change="handleTenantChange" />
</template>

<script setup lang="ts">
import { useTenantStore } from "@/store/modules/tenant";

const tenantStore = useTenantStore();

// 处理切换事件
function handleTenantChange(tenantId: number) {
tenantStore.switchTenant(tenantId).then(() => {
// 切换成功后刷新页面以应用新权限
window.location.reload();
});
}
</script>

5.2 状态管理与切换逻辑 (Pinia Store)

前端的租户状态管理和切换逻辑都集中在 src/store/modules/tenant.ts 中。它负责加载租户列表、持久化当前租户状态、以及处理切换操作。

// src/store/modules/tenant.ts
import { defineStore } from "pinia";
import TenantAPI from "@/api/system/tenant";
import type { TenantInfo } from "@/types/api";
import { STORAGE_KEYS } from "@/constants";
import AuthAPI from "@/api/auth";
import { AuthStorage } from "@/utils/auth";

export const useTenantStore = defineStore("tenant", () => {
const currentTenantId = ref<number | null>(null);
const currentTenant = ref<TenantInfo | null>(null);
const tenantList = ref<TenantInfo[]>([]);

// 加载租户信息（由路由守卫调用）
async function loadTenant() {
/* … */
}

// 设置当前租户并持久化
function setCurrentTenant(tenant: TenantInfo) {
/* … */
}

// 切换租户核心逻辑
async function switchTenant(tenantId: number): Promise<void> {
// 1. (平台用户) 尝试获取新 Token
await refreshTokenIfSupported(tenantId);
// 2. 调用后端 API 切换租户
const tenantInfo = await TenantAPI.switchTenant(tenantId);
// 3. 更新并持久化 state
setCurrentTenant(tenantInfo);
}

return {
/* … */
};
});

六、租户配置指南

理解了技术架构后，我们通过一个完整的操作流程，来演示如何从零开始创建一个新租户并为其配置服务。

注意：本指南的操作涉及 youlai-boot-tenant (后端) 和 vue3-element-admin (前端) 两个项目。

6.1 核心流程

创建套餐 → 为套餐分配菜单 → 创建租户并关联套餐 → (可选)为租户微调菜单 → 配置Nginx

6.2 创建租户套餐

套餐是商业化服务的基础，它定义了不同级别租户的功能边界（即最多能拥有哪些菜单）。

6.3 新增租户

创建租户时，需要为其关联一个预先定义好的套餐，并指定一个唯一的域名用于身份识别。

6.4 更换租户套餐

当租户需要升级或降级服务时，平台可以为其更换套餐。

操作：在弹窗中选择新的套餐并确认。

6.5 (可选) 为租户定制菜单

在套餐的基础上，平台可以为特定租户进行菜单微调，以满足个性化需求。

操作：在弹出的抽屉中，你可以关闭该租户不需要的功能。注意，这里的可调范围不能超过该租户所在套餐的边界。

6.6 配置 Nginx 域名解析

这是让租户通过独立域名访问系统的最后一步，也是最关键的一步。

警告：如果 Nginx 未正确配置 proxy_set_header Host $host;，后端将无法通过域名识别租户身份，导致所有请求都 fallback 到平台或其他默认租户，造成数据隔离失效或访问错误。

七、在线演示

• 平台租户视角：https://vue.youlai.tech
• 业务租户视角：https://demo.youlai.tech
• 测试账号：admin / 123456

可以通过以下步骤，亲身体验并验证平台与租户的权限隔离效果：

1. 平台管理员视角验证 (vue.youlai.tech)

• 登录：使用账号 admin / 123456 登录平台。
• 验证平台菜单：检查左侧菜单栏，应包含 租户管理 和 系统配置 等平台专属菜单。
• 验证租户切换：
  • 点击页面右上角的 平台主租户 下拉框。
  • 选择 演示租户 或其他业务租户进行切换。
  • 切换成功后，页面会自动刷新。
• 验证数据隔离：
  • 切换到 演示租户 租户后，进入 系统管理 -> 用户管理 页面。
  • 你将看到属于 演示租户 租户的用户列表，而不是平台或其他租户的用户。这证明了数据行级隔离生效。

2. 业务租户视角验证 (demo.youlai.tech)

• 登录：使用账号 admin / 123456 登录。
• 验证菜单边界：
  • 检查左侧菜单栏，不应包含 租户管理 等平台菜单。
  • 检查右上角，没有租户切换的下拉框。
• 验证数据隔离：
  • 进入 系统管理 -> 用户管理 页面。
  • 你只能看到当前租户（演示租户）的用户，无法看到平台或其他租户的数据。

八、结语

多租户架构不仅仅是技术实现，更是对业务模型的深刻理解。本文介绍的“共享 Schema + tenant_id 行级隔离”方案，经过了大量生产环境的验证，是 SaaS 系统起步阶段的最佳选择。

希望本文能为你构建自己的多租户系统提供清晰的思路和可落地的参考。

附：源码

• 后端：https://gitee.com/youlaiorg/youlai-boot-tenant (基于 Spring Boot 4 的多租户实现)
• 前端：https://gitee.com/youlaiorg/vue3-element-admin (Vue3 + Element Plus 权限管理系统)