ruoyi-vue-pro 开发指南 ruoyi-vue-pro 开发指南
  • 萌新必读
  • 后端手册
  • 中间件手册
  • 工作流手册
  • 大屏手册
  • 支付手册
  • 会员手册
  • 商城手册
  • ERP 手册
  • CRM 手册
  • AI 大模型手册
  • IoT 物联网手册
  • 公众号手册
  • 系统手册
  • 运维手册
  • 前端手册 Vue 2.x
  • 前端手册 Vue 3.x
  • 工作流手册
  • 大屏手册
  • 支付手册
  • 会员手册
  • 商城手册
  • ERP 手册
  • CRM 手册
  • AI 大模型手册
  • IoT 物联网手册
  • 公众号手册
  • 系统手册
视频教程
  • Vue3 + element-plus (opens new window)
  • Vue3 + vben(ant-design-vue) (opens new window)
  • Vue2 + element-ui (opens new window)
微服务版 (opens new window)
作者博客 (opens new window)
GitHub (opens new window)
  • 萌新必读
  • 后端手册
  • 中间件手册
  • 工作流手册
  • 大屏手册
  • 支付手册
  • 会员手册
  • 商城手册
  • ERP 手册
  • CRM 手册
  • AI 大模型手册
  • IoT 物联网手册
  • 公众号手册
  • 系统手册
  • 运维手册
  • 前端手册 Vue 2.x
  • 前端手册 Vue 3.x
  • 工作流手册
  • 大屏手册
  • 支付手册
  • 会员手册
  • 商城手册
  • ERP 手册
  • CRM 手册
  • AI 大模型手册
  • IoT 物联网手册
  • 公众号手册
  • 系统手册
视频教程
  • Vue3 + element-plus (opens new window)
  • Vue3 + vben(ant-design-vue) (opens new window)
  • Vue2 + element-ui (opens new window)
微服务版 (opens new window)
作者博客 (opens new window)
GitHub (opens new window)
  • 萌新必读

    • 简介
    • 交流群
    • 视频教程
    • 功能列表
    • 快速启动(后端项目)
    • 快速启动(前端项目)
    • 接口文档
    • 技术选型
    • 项目结构
    • 代码热加载
    • 一键改包
    • 迁移模块(适合新项目)
    • 删除功能(以租户为例)
    • 表结构变更(版本升级)
    • 国产信创数据库(DM 达梦、大金、OpenGauss)
    • 如何去除 Redis 缓存
    • 内网穿透
    • 面试题、简历模版、简历优化
    • 项目外包
  • 后端手册

    • 新建模块
    • 代码生成【单表】(新增功能)
    • 代码生成【主子表】
    • 代码生成(树表)
    • 功能权限
    • 数据权限
    • 用户体系
    • 三方登录
    • OAuth 2.0(SSO 单点登录)
    • SaaS 多租户【字段隔离】
      • 1. 多租户是什么?
      • 2. 数据隔离方案
        • 2.1 DATASOURCE 模式
        • 2.2 SCHEMA 模式
        • 2.3 COLUMN 模式
        • 2.4 方案选择
      • 3. 多租户的开关
      • 4. 多租户的业务功能
      • 5. 多租户的技术组件
        • 5.1 租户上下文
        • 5.2 Web 层【重要】
        • 5.3 Security 层
        • 5.4 DB 层【重要】
        • 5.5 Redis 层【重要】
        • 5.6 AOP【重要】
        • 5.7 Job【重要】
        • 5.8 MQ
        • 5.9 Async
      • 6. 租户独立域名
      • 7. 租户切换
    • SaaS 多租户【数据库隔离】
    • WebSocket 实时通信
    • 异常处理(错误码)
    • 参数校验、时间传参
    • 分页实现
    • VO 对象转换、数据翻译
    • 文件存储(上传下载)
    • Excel 导入导出
    • 操作日志、访问日志、异常日志
    • MyBatis 数据库
    • MyBatis 联表&分页查询
    • 多数据源(读写分离)、事务
    • Redis 缓存
    • 本地缓存
    • 异步任务
    • 分布式锁
    • 幂等性(防重复提交)
    • 请求限流(RateLimiter)
    • HTTP 接口签名(防篡改)
    • 单元测试
    • 验证码
    • 工具类 Util
    • 配置管理
    • 数据库文档
  • 中间件手册

    • 定时任务
    • 消息队列(内存)
    • 消息队列(Redis)
    • 消息队列(RocketMQ)
    • 消息队列(RabbitMQ)
    • 消息队列(Kafka)
    • 限流熔断
  • 工作流手册

    • 工作流演示
    • 功能开启
    • 工作流(达梦适配)
    • 审批接入(流程表单)
    • 审批接入(业务表单)
    • 流程设计器(BPMN)
    • 流程设计器(钉钉、飞书)
    • 选择审批人、发起人自选
    • 会签、或签、依次审批
    • 流程发起、取消、重新发起
    • 审批通过、不通过、驳回
    • 审批加签、减签
    • 审批转办、委派、抄送
    • 执行监听器、任务监听器
    • 流程表达式
    • 流程审批通知
  • 大屏手册

    • 报表设计器
    • 大屏设计器
  • 支付手册

    • 功能开启
    • 支付宝支付接入
    • 微信公众号支付接入
    • 微信小程序支付接入
    • 支付宝、微信退款接入
    • 支付宝转账接入
    • 微信转账接入
    • 钱包充值、支付、退款
    • 模拟支付、退款
  • 会员手册

    • 功能开启
    • 微信公众号登录
    • 微信小程序登录
    • 微信小程序订阅消息
    • 微信小程序码
    • 会员用户、标签、分组
    • 会员等级、积分、签到
  • 商城手册

    • 商城演示
    • 功能开启
    • 商城装修
    • 在线客服
    • 【商品】商品分类
    • 【商品】商品属性
    • 【商品】商品 SPU 与 SKU
    • 【商品】商品评价
    • 【交易】购物车
    • 【交易】交易订单
    • 【交易】售后退款
    • 【交易】快递发货
    • 【交易】门店自提
    • 【交易】分销返佣
    • 【营销】优惠劵
    • 【营销】积分商城
    • 【营销】拼团活动
    • 【营销】秒杀活动
    • 【营销】砍价活动
    • 【营销】满减送活动
    • 【营销】限时折扣
    • 【营销】内容管理
    • 【统计】会员、商品、交易统计
  • ERP手册

    • ERP 演示
    • 功能开启
    • 【产品】产品信息、分类、单位
    • 【库存】产品库存、库存明细
    • 【库存】其它入库、其它出库
    • 【库存】库存调拨、库存盘点
    • 【采购】采购订单、入库、退货
    • 【销售】销售订单、出库、退货
    • 【财务】采购付款、销售收款
  • CRM手册

    • CRM 演示
    • 功能开启
    • 【线索】线索管理
    • 【客户】客户管理、公海客户
    • 【商机】商机管理、商机状态
    • 【合同】合同管理、合同提醒
    • 【回款】回款管理、回款计划
    • 【产品】产品管理、产品分类
    • 【通用】数据权限
    • 【通用】跟进记录、待办事项
  • AI大模型手册

    • AI 大模型演示
    • 功能开启
    • AI 聊天对话
    • AI 绘画创作
    • AI 知识库
    • AI 音乐创作
    • AI 写作助手
    • AI 思维导图
    • AI 工具(function calling)
    • AI 工作流
    • Dify 工作流
    • FastGPT 工作流
    • Coze 智能体
    • 【模型接入】OpenAI
    • 【模型接入】通义千问
    • 【模型接入】DeepSeek
    • 【模型接入】字节豆包
    • 【模型接入】腾讯混元
    • 【模型接入】硅基流动
    • 【模型接入】MiniMax
    • 【模型接入】月之暗灭
    • 【模型接入】百川智能
    • 【模型接入】文心一言
    • 【模型接入】LLAMA
    • 【模型接入】智谱 GLM
    • 【模型接入】讯飞星火
    • 【模型接入】微软 OpenAI
    • 【模型接入】谷歌 Gemini
    • 【模型接入】Stable Diffusion
    • 【模型接入】Midjourney
    • 【模型接入】Suno
  • IoT物联网手册

    • 功能开启
  • 公众号手册

    • 功能开启
    • 公众号接入
    • 公众号粉丝
    • 公众号标签
    • 公众号消息
    • 自动回复
    • 公众号菜单
    • 公众号素材
    • 公众号图文
    • 公众号统计
  • 系统手册

    • 短信配置
    • 邮件配置
    • 站内信配置
    • 数据脱敏、字段权限
    • 敏感词
    • 地区 & IP 库
  • 运维手册

    • 开发环境
    • Linux 部署
    • Docker 部署
    • Jenkins 部署
    • 宝塔部署
    • HTTPS 证书
    • 服务监控
  • 前端手册 Vue 3.x

    • 开发规范
    • 菜单路由
    • Icon 图标
    • 字典数据
    • 系统组件
    • 通用方法
    • 配置读取
    • CRUD 组件
    • 国际化
    • IDE 调试
    • 代码格式化
  • 前端手册 Vue 2.x

    • 开发规范
    • 菜单路由
    • Icon 图标
    • 字典数据
    • 系统组件
    • 通用方法
    • 配置读取
  • 更新日志

    • 【v2-6-0】开发中
    • 【v2.5.0】2025-05-13
    • 【v2.4.2】2025-04-12
    • 【v2.4.1】2025-02-09
    • 【v2.4.0】2024-12-31
    • 【v2.3.0】2024-10-07
    • 【v2.2.0】2024-08-02
    • 【v2.1.0】2024-05-05
    • 【v2.0.1】2024-03-01
    • 【v2.0.0】2024-01-26
  • 开发指南
  • 后端手册
芋道源码
2022-03-07
目录

SaaS 多租户【字段隔离】

本章节,将介绍多租户的基础知识、以及怎样使用多租户的功能。

相关的视频教程:

  • 01、如何实现多租户的 DB 封装? (opens new window)
  • 02、如何实现多租户的 Redis 封装? (opens new window)
  • 03、如何实现多租户的 Web 与 Security 封装? (opens new window)
  • 04、如何实现多租户的 Job 封装? (opens new window)
  • 05、如何实现多租户的 MQ 与 Async 封装? (opens new window)
  • 06、如何实现多租户的 AOP 与 Util 封装? (opens new window)
  • 07、如何实现多租户的管理? (opens new window)
  • 08、如何实现多租户的套餐? (opens new window)

# 1. 多租户是什么?

多租户,简单来说是指一个业务系统,可以为多个组织服务,并且组织之间的数据是隔离的。

例如说,在服务上部署了一个 ruoyi-vue-pro (opens new window) 系统,可以支持多个不同的公司使用。这里的一个公司就是一个租户,每个用户必然属于某个租户。因此,用户也只能看见自己租户下面的内容,其它租户的内容对他是不可见的。

# 2. 数据隔离方案

多租户的数据隔离方案,可以分成分成三种:

  1. DATASOURCE 模式:独立数据库
  2. SCHEMA 模式:共享数据库,独立 Schema
  3. COLUMN 模式:共享数据库,共享 Schema,共享数据表

# 2.1 DATASOURCE 模式

一个租户一个数据库,这种方案的用户数据隔离级别最高,安全性最好,但成本也高。

DATASOURCE 模式

  • 优点:为不同的租户提供独立的数据库,有助于简化数据模型的扩展设计,满足不同租户的独特需求;如果出现故障,恢复数据比较简单。
  • 缺点:增大了数据库的安装数量,随之带来维护成本和购置成本的增加。

# 2.2 SCHEMA 模式

多个或所有租户共享数据库,但一个租户一个表。

SCHEMA 模式

  • 优点:为安全性要求较高的租户提供了一定程度的逻辑数据隔离,并不是完全隔离;每个数据库可以支持更多的租户数量。
  • 缺点:如果出现故障,数据恢复比较困难,因为恢复数据库将牵扯到其他租户的数据; 如果需要跨租户统计数据,存在一定困难。

# 2.3 COLUMN 模式

共享数据库,共享数据架构。租户共享同一个数据库、同一个表,但在表中通过 tenant_id 字段区分租户的数据。这是共享程度最高、隔离级别最低的模式。

COLUMN 模式

  • 优点:维护和购置成本最低,允许每个数据库支持的租户数量最多。
  • 缺点:隔离级别最低,安全性最低,需要在设计开发时加大对安全的开发量;数据备份和恢复最困难,需要逐表逐条备份和还原。

# 2.4 方案选择

模式选择

  • 一般情况下,可以考虑采用 COLUMN 模式,开发、运维简单,以最少的服务器为最多的租户提供服务。
  • 租户规模比较大,或者一些租户对安全性要求较高,可以考虑采用 DATASOURCE 模式,当然它也相对复杂的多。
  • 不推荐采用 SCHEMA 模式,因为它的优点并不明显,而且它的缺点也很明显,同时对复杂 SQL 支持一般。

提问:项目支持哪些模式?

目前支持最主流的 DATASOURCE 和 COLUMN 两种模式。而 SCHEMA 模式不推荐使用,所以暂时不考虑实现。

考虑到让大家更好的理解 DATASOURCE 和 COLUMN 模式,拆成了两篇文章:

  • 《SaaS 多租户【字段隔离】》:讲解 COLUMN 模式
  • 《SaaS 多租户【数据库隔离】》:讲解 DATASOURCE 模式

# 3. 多租户的开关

系统有两个配置项,设置为 true 时开启多租户,设置为 false 时关闭多租户。

注意,两者需要保持一致,否则会报错!

配置项 说明 配置文件
yudao.server.tenant 后端开关 示例
VUE_APP_TENANT_ENABLE 前端开关 示例

疑问:为什么要设置两个配置项?

前端登录界面需要使用到多租户的配置项,从后端加载配置项的话,体验会比较差。

# 4. 多租户的业务功能

多租户主要有两个业务功能:

业务功能 说明 界面 代码
租户管理 配置系统租户,创建对应的租户管理员 租户管理 后端 (opens new window) 前端 (opens new window)
租户套餐 配置租户套餐,自定每个租户的菜单、操作、按钮的权限 租户套餐 后端 (opens new window) 前端 (opens new window)

下面,我们来新增一个租户,它使用 COLUMN 模式。

① 点击 [租户管理] 菜单,点击 [新增] 按钮,填写租户的信息。

新增租户

② 点击 [确认] 按钮,完成租户的创建,它会自动创建对应的租户管理员、角色等信息。

租户的管理员、角色

③ 退出系统,登录刚创建的租户。

登录界面

至此,我们已经完成了租户的创建。

# 5. 多租户的技术组件

技术组件 yudao-spring-boot-starter-biz-tenant (opens new window),实现透明化的多租户能力,针对 Web、Security、DB、Redis、AOP、Job、MQ、Async 等多个层面进行封装。

# 5.1 租户上下文

TenantContextHolder (opens new window) 是租户上下文,通过 ThreadLocal 实现租户编号的共享与传递。

通过调用 TenantContextHolder 的 #getTenantId() 静态方法,获得当前的租户编号。绝绝绝大多数情况下,并不需要。

# 5.2 Web 层【重要】

实现可见 web (opens new window) 包。

默认情况下,前端的每个请求 Header 必须带上 tenant-id,值为租户编号,即 system_tenant 表的主键编号。

请求示例

如果不带该请求头,会报“租户的请求未传递,请进行排查”错误提示。

😜 方式一:通过 yudao.tenant.ignore-urls 配置项,可以设置哪些 URL 无需带该请求头。例如说:

 配置项

😆 方式二:【推荐】在 Controller 方法上,使用 @TenantIgnore 注解,忽略该方法的租户校验。例如说:

// TenantController.java

@GetMapping("/get-id-by-name")
@TenantIgnore // <--- 重要!!!
public CommonResult<Long> getTenantIdByName(@RequestParam("name") String name) {
    // ...
}

# 5.3 Security 层

实现可见 security (opens new window) 包。

主要是校验登录的用户,校验是否有权限访问该租户,避免越权问题。

# 5.4 DB 层【重要】

实现可见 db (opens new window) 包。

COLUMN 模式,基于 MyBatis Plus 自带的多租户 (opens new window)功能实现。

核心:每次对数据库操作时,它会自动拼接 WHERE tenant_id = ? 条件来进行租户的过滤,并且基本支持所有的 SQL 场景。

如下是具体方式:

① 需要开启多租户的表,必须添加 tenant_id 字段。例如说 system_users、system_role 等表。

CREATE TABLE `system_role` (
   `id` bigint NOT NULL AUTO_INCREMENT COMMENT '角色ID',
   `name` varchar(30) CHARACTER NOT NULL COMMENT '角色名称',
   `tenant_id` bigint NOT NULL DEFAULT '0' COMMENT '租户编号',
   PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB AUTO_INCREMENT=1 COMMENT='角色信息表';

并且该表对应的 DO 需要使用到 tenantId 属性时,建议继承 TenantBaseDO (opens new window) 类。

② 无需开启多租户的表,需要添加表名到 yudao.tenant.ignore-tables 配置项目。例如说:

 配置项

如果不配置的话,MyBatis Plus 会自动拼接 WHERE tenant_id = ? 条件,导致报 tenant_id 字段不存在的错误。

友情提示:MyBatis Plus 的多租户方案,在我们在 MyBatis XML 手写 SQL 时,是不生效的,即不会拼接 `tenant_id` 字段!!!

解决方案:需要手动自己拼接,可见 ErpPurchaseStatisticsMapper.xml 案例,如下所示:

tenant_id = ${@cn.iocoder.yudao.framework.tenant.core.context.TenantContextHolder@getRequiredTenantId()}
  • 其中,后面 ${@...} 一串,是 MyBatis 调用静态方法的方式,即使用 TenantContextHolder 的 #getRequiredTenantId() 方法,获得当前的租户编号。

补充说明:后续和球友沟通下来,部分简单 SQL 情况下,MyBatis Plus 还是会拼接。可见 https://t.zsxq.com/O8ys4 (opens new window) 帖子,欢迎讨论!

③ 另外,无需开启多租户的表,也可以通过在 DO 实体类上,添加 @TenantIgnore 注解,忽略该表的租户过滤。例如说:

@TableName("system_dict_data")
@TenantIgnore // <--- 重要!!!
public class DictDataDO extends BaseDO {
    
    // ... 省略属性
    
}

# 5.5 Redis 层【重要】

实现可见 redis (opens new window) 包。

由于 Redis 不同于 DB 有 tenant_id 字段,无法通过类似 WHERE tenant_id = ? 的方式过滤,所以需要通过在 Redis Key 上增加 :t{tenantId} 后缀的方式,进行租户之间的隔离。

例如说,假设 Redis Key 是 user:%d,示例是 user:1024;对应到多租户 1 的 Redis Key 是 user:t1:1024。

为什么 Redis Key 要多租户隔离呢?

  • ① 在使用 DATASOURCE 模式时,不同库的相同表的 id 可能相同,例如说 A 库的用户,和 B 库的用户都是 1024,直接缓存会存在 Redis Key 的冲突。
  • ② 在所有模式下,跨租户可能存在相同的需要唯一的数据,例如说用户的手机号,直接缓存会存在 Redis Key 的冲突。

# 使用方式一:基于 Spring Cache + Redis【推荐】

只需要一步,在方法上添加 Spring Cache 注解,例如说 @Cachable、@CachePut、@CacheEvict。

具体的实现原理,可见 TenantRedisCacheManager (opens new window) 的源码。

注意!!!默认配置下,Spring Cache 都开启 Redis Key 的多租户隔离。如果不需要,可以将 Key 添加到 yudao.tenant.ignore-caches 配置项中。如下图所示:

 配置项

# 使用方式二:基于 RedisTemplate + TenantRedisKeyDefine

暂时没有合适的封装,需要在自己 format Redis Key 的时候,手动将 :t{tenantId} 后缀拼接上。

这也是为什么,我推荐你使用 Spring Cache + Redis 的原因!

# 5.6 AOP【重要】

实现可见 aop (opens new window) 包。

① 声明 @TenantIgnore (opens new window) 注解在方法上,标记指定方法不进行租户的自动过滤,避免自动拼接 WHERE tenant_id = ? 条件等等。

例如说:RoleServiceImpl (opens new window) 的 #initLocalCache() (opens new window) 方法,加载所有租户的角色到内存进行缓存,如果不声明 @TenantIgnore 注解,会导致租户的自动过滤,只加载了某个租户的角色。

// RoleServiceImpl.java
public class RoleServiceImpl implements RoleService {

    @Resource
    @Lazy // 注入自己,所以延迟加载
    private RoleService self;
    
    @Override
    @PostConstruct
    @TenantIgnore // 忽略自动多租户,全局初始化缓存
    public void initLocalCache() {
        // ... 从数据库中,加载角色
    }

    @Scheduled(fixedDelay = SCHEDULER_PERIOD, initialDelay = SCHEDULER_PERIOD)
    public void schedulePeriodicRefresh() {
        self.initLocalCache(); // <x> 通过 self 引用到 Spring 代理对象
    }
}

有一点要格外注意,由于 @TenantIgnore 注解是基于 Spring AOP 实现,如果是方法内部的调用,避免使用 this 导致不生效,可以采用上述示例的 <x> 处的 self 方式。

② 使用 TenantUtils (opens new window) 的 #execute(Long tenantId, Runnable runnable) 方法,模拟指定租户( tenantId ),执行某段业务逻辑( runnable )。

例如说:在 TenantServiceImpl (opens new window) 的 #createTenant(...) 方法,在创建完租户时,需要模拟该租户,进行用户和角色的创建。如下图所示:

TenantUtils 模拟租户

# 5.7 Job【重要】

实现可见 job (opens new window) 包。

声明 @TenantJob (opens new window) 注解在 Job 方法上,实现并行遍历每个租户,执行定时任务的逻辑。

# 5.8 MQ

实现可见 mq (opens new window) 包。

通过租户对 MQ 层面的封装,实现租户上下文,可以继续传递到 MQ 消费的逻辑中,避免丢失的问题。实现原理是:

  • 发送消息时,MQ 会将租户上下文的租户编号,记录到 Message 消息头 tenant-id 上。
  • 消费消息时,MQ 会将 Message 消息头 tenant-id,设置到租户上下文的租户编号。

# 5.9 Async

实现可见 YudaoAsyncAutoConfiguration (opens new window) 类。

通过使用阿里开源的 TransmittableThreadLocal (opens new window) 组件,实现 Spring Async 执行异步逻辑时,租户上下文可以继续传递,避免丢失的问题。

# 6. 租户独立域名

在我们使用 SaaS 云产品的时候,每个租户会拥有 独立的子域名,例如说:租户 A 对应 a.iocoder.cn,租户 B 对应 b.iocoder.cn。

目前管理后台已经提供类似的能力,更多大家可以基于它去拓展。实现方式:

  1. 在 system_tenant 表里,有个 website 字段为该租户的独立域名,你可以填写你希望分配给它的子域名。
  2. 在 Nginx 上做 泛域名解析 到你的前端项目,例如说 Nginx 的 server_name *.iocoder.cn 解析到 Vue3 管理后台。

这样用户在访问管理后台的登录界面,会自动根据当前访问域名的 host,向后端获得对应的 tenant-id 编号,后续请求都带上它!

ps:商城 uniapp 暂时还没做,感兴趣可以 pull request 贡献下噢!

# 7. 租户切换

① 拥有 system:tenant:visit 权限的用户,支持切换租户,从而查看和操作其它租户的数据。如下图所示:

切换租户

system:tenant:visit 权限的分配,可以在角色管理时,分配 [系统管理 -> 租户管理 -> 租户切换] 权限。

② 注意:如果你的 HTTP 接口是查询个人相关的信息,不能进行租户的切换,例如说:登录用户的个人信息等。此时,yudao.tenant.ignore-urls 配置项进行添加。

yudao:
  tenant:
    ignore-urls:
      - /admin-api/system/user/profile/**
      - /admin-api/system/auth/**

③ 如果你要拓展这块的实现,最好阅读如下代码:

  • 前端:https://gitee.com/yudaocode/yudao-ui-admin-vue3/commit/c6898c0a99b00fb08863295d7fb1adb06cf66113 (opens new window)
  • Boot 后端:https://gitee.com/zhijiantianya/ruoyi-vue-pro/commit/59234e1eeade300a68adc8183d58f616c14e90f1 (opens new window)
  • Cloud 后端:https://gitee.com/zhijiantianya/yudao-cloud/commit/a07963335549da0e49f13c98cb79adc11df1524b (opens new window)
OAuth 2.0(SSO 单点登录)
SaaS 多租户【数据库隔离】

← OAuth 2.0(SSO 单点登录) SaaS 多租户【数据库隔离】→

Theme by Vdoing | Copyright © 2019-2025 芋道源码 | MIT License
  • 跟随系统
  • 浅色模式
  • 深色模式
  • 阅读模式
×