最近不管是技术社区还是团队内部的架构评审多租户、数据隔离这几个词的出镜率都高得离谱。尤其是 dify 社区版 1.10 把多租户作为一个核心卖点之后我身边不少做 SaaS 的朋友都在研究这事。其实多租户这套东西说穿了并不玄乎核心就一个问题一套系统服务 N 家客户数据如何既隔得开、又不至于把运维成本和性能拖垮。我这些年经手过不少多租户系统的设计和改造从最初几家大客户的私有化部署到现在上百家租户共用一个集群各种隔离方案都试过。这篇就整理一份可以直接落地的多租户数据隔离参考架构把方案选型、代码改造、常见翻车点一次讲透。无论你是刚接手公司 SaaS 项目的后端开发还是正在规划平台化的技术负责人这篇里的实操经验应该都能帮你少走不少弯路。1. 先弄清楚多租户数据隔离到底要隔离什么1.1 隔离的本质是租户维度的边界很多人一提数据隔离第一反应就是“把数据分开存”。但分开存只是手段多租户隔离的本质是在应用层建立一个贯穿全链路的租户维度边界。什么意思就是说无论是用户登录、接口请求、后台任务还是报表查询系统在任何时刻都要知道当前操作属于哪个租户并且所有数据访问都被强制限制在这个租户的范围内。这个边界建立不起来就会出现两类问题一类是恶意的越权访问比如一个用户通过改 URL 参数就能查到别的公司的数据另一类是更隐蔽的逻辑漏洞比如定时任务里忘记带租户条件结果某个租户的统计数据里混进了所有租户的数据。第二类往往比第一类更致命因为它不是被攻击而是系统自己制造的数据污染。我见过一个真实的案例某 SaaS 平台的报表模块在生成月度账单时查询条件里漏掉了租户 ID结果所有租户看到的账单数据都是全平台累计的。这种事故一旦发生客户信任基本就归零了。所以隔离方案设计的首要任务不是选数据库而是想清楚租户边界如何在代码的每一层传递和被强制执行。1.2 三种租户识别方式要在系统里建立一个租户维度边界第一步是解决“怎么知道当前请求属于哪个租户”的问题。实际项目里常用的有三种识别方式第一种是独立域名或子域名方式比如 tenantA.example.com 和 tenantB.example.com。这种方式最直观用户访问的 URL 天然带着租户信息还可以配合 CDN 和独立 SSL 证书做差异化配置。但缺点也很明显DNS 配置和证书管理在大规模租户场景下会变得很繁琐而且测试环境要模拟多租户域名也比较麻烦。第二种是请求 Header 或 Token 携带租户信息。现在绝大多数 SaaS 架构采用 JWT 做认证租户 ID 作为 Token 里的一个自定义 Claim 一起签发。后端从请求头里解析出租户 ID放入上下文。这种方式灵活不依赖 DNS 配置也方便在 API 网关层统一处理是目前最主流的做法。第三种是 URL 路径参数方式比如 /api/{tenantId}/orders。这种方式老项目改造时比较方便但风险也最大如果后端没有严格校验路径参数和当前登录用户所属租户的一致性就很容易被水平越权。一般不建议新项目直接用这种方式除非有网关层做租户映射。我实际做改造时的偏好是第二种为主域名方式用于大型客户的门户入口路径参数只在某些公开接口的兼容场景下使用。识别方式确定后接下来要做的就是把这个租户 ID 从请求入口一路传递到 SQL 执行层。2. 三种主流隔离模式怎么选2.1 独立数据库模式最稳但也最贵独立数据库模式也就是每个租户一套独立的数据库实例或独立库。这是隔离强度最高的方案租户之间在物理层面完全隔离无论数据备份、恢复、扩缩容还是性能调优都可以针对单个租户独立操作。这种模式的优点很直观安全级别最高完全不存在租户间串数据的可能数据库故障的影响面也小一个租户的库挂了不会拖累其他租户还能给大客户提供专门的资源保障和定制化部署。但缺点同样突出。首先是成本数据库实例数量随租户数线性增长哪怕每个库只占几十 MB也要为每个实例付出独立的内存和进程开销。其次是运维复杂度一百个租户就是一百套备份任务、一百套监控告警、一百套升级流程。哪怕用云数据库托管服务日常管理仍然是个不小的工作量。所以这个模式的实际适用范围很窄要么是客单价极高的政企大客户要么是有强合规要求比如金融行业必须做到数据物理隔离的场景。如果你是做通用型 SaaS全量用这种模式基本等于烧钱。2.2 共享数据库、独立 Schema均衡方案共享数据库、独立 Schema 模式是指所有租户共用一个数据库实例但每个租户拥有自己独立的 Schema在 MySQL 里可以近似理解为独立库在 PostgreSQL 里则是真正的 Schema。这种方案的隔离级别是逻辑层隔离每个 Schema 内的表结构可以独立演进应用层通过切换 search_pathPostgreSQL或者切换数据库名MySQL来实现租户路由。由于数据仍然物理上存放在同一个实例中数据库实例的数量不会随租户数暴涨硬件成本相对可控。它的优点在于隔离性和成本之间取得了较好的平衡一个租户的误操作一般不会直接破坏另一个租户的数据结构备份也能按 Schema 做精细化处理租户之间的数据在存储层就有天然边界。缺点是单个数据库实例的资源始终是共享的一旦某个租户的数据量特别大或者某条 SQL 特别慢仍然可能拖累同实例上的其他租户。我的经验是它特别适合租户数量在几十到几百之间、单租户数据量中等、且存在定制化表结构需求的平台型产品。比如不少企业服务类 SaaS 需要给不同客户开放自定义字段独立 Schema 就能相对安全地支持这类需求。2.3 共享表、租户 ID 维度最常用的取舍共享表模式是所有租户共用同一组表通过表里的租户 ID 字段来区分数据归属。这是互联网 SaaS 产品里最普及的方案几乎所有快速增长的云原生应用初期都会选择它。它的最大优势是资源利用率高一张表可以服务所有租户不需要维护成百上千个 Schema开发和迭代效率也高加字段、加索引只需要操作一套表结构数据聚合分析非常方便跨租户的统计查询天然就能实现。但这个模式最考验的是应用层的隔离纪律。你必须在所有 SQL 查询中强制携带租户条件一条 SQL 漏了 where tenant_id ?后果就是数据串号。而且表数据量会随着租户增长迅速膨胀索引设计、分区策略、慢查询治理都是后续长期要做的事情。现实中很多团队一开始图省事选择共享表后来遇到大客户要求更高隔离级别再想办法迁移。其实这个演进路径是合理的共享表方案本身没有问题问题在于有没有从一开始就把租户上下文的传递机制做好。只要上下文机制是健壮的从共享表迁移到独立 Schema 只是数据搬迁的事。2.4 选型决策按客户、成本、合规三个维度权衡三种模式各有适用场景我给的建议是不要一步到位而是按客户维度做混合隔离免费试用版/低价值客户共享表成本优先中小付费客户共享表或独立 Schema看是否需要定制表结构大客户/强合规客户独立 Schema 或独立库安全优先需要物理隔离的金融政务客户独立库成本侧要注意一个容易被忽略的细节看似省钱的共享表模式随着租户和数据量增长为了扛住压力往往会引入读写分离、分库分表、分布式缓存等复杂基础设施这些总拥有成本未必比一开始用独立 Schema 低。合规侧则要看客户合同里的条款约定有些客户会明确要求数据存储与其他租户物理隔离这时候不管代码层做得有多好都必须用独立库来兜底。所以参考架构在选型上的结论是默认采用共享表 强隔离上下文机制预留独立 Schema 和独立库的升级路径让隔离级别本身成为可配置项。3. 把隔离真正落到代码里的关键步骤3.1 租户上下文的建立与传递代码层的多租户改造第一步是把租户上下文这个基础设施搭好。租户上下文的核心是一个全局的线程级变量用来保存当前请求正在处理哪个租户。我以 Java 技术栈为例最常见的方式是用 ThreadLocal 包一层public class TenantContext { private static final ThreadLocalString CURRENT_TENANT new ThreadLocal(); public static void setTenantId(String tenantId) { CURRENT_TENANT.set(tenantId); } public static String getTenantId() { return CURRENT_TENANT.get(); } public static void clear() { CURRENT_TENANT.remove(); } }这个类本身很简单但它有几个使用上的关键纪律。第一必须在请求进入时设置租户 ID通常在 Filter 或拦截器里从 JWT 或 Header 解析出来。第二必须在请求结束时清理 ThreadLocal否则线程池复用的线程会带着上一个租户的上下文处理下一个请求这是数据串号的头号原因。Component public class TenantFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest httpRequest (HttpServletRequest) request; String tenantId httpRequest.getHeader(X-Tenant-Id); if (StringUtils.hasText(tenantId)) { TenantContext.setTenantId(tenantId); } try { chain.doFilter(request, response); } finally { TenantContext.clear(); } } }如果你用的是 Python/Flask 或 Node.js思路完全一样只是换成 contextvars 或者 AsyncLocal。关键是理解一点租户 ID 不是某个业务代码里随手取的参数而是贯穿整个调用链的上下文状态。任何异步线程、定时任务、消息消费者内部要使用租户上下文时都必须显式传入或者从调用链中继承绝不能在子线程里直接读主线程的 ThreadLocal。3.2 数据访问层如何自动附加租户条件上下文有了之后最难的就是保证所有数据库查询都自动带上租户条件。人工在每条 SQL 里手写 where tenant_id ? 是不现实的总会有遗漏。真正的解法是在数据访问层做一个统一的拦截器自动改写 SQL。MyBatis 的 Interceptor 是一个典型的实现位置。在拦截器里解析即将执行的 SQL 语句如果是 SELECT、UPDATE、DELETE就自动拼接租户条件。需要注意 UPDATE 和 DELETE 必须强制加租户条件否则就可能出现跨租户误改数据。实现上有几点经验值得分享第一只对包含目标表名的 SQL 做拼接系统表、字典表、跨租户的全局配置表要加入白名单。第二INSERT 语句不需要改写 where 条件但需要在应用的实体层自动填充 tenant_id 字段避免开发人员忘记赋值。第三SQL 改写要考虑到别名、子查询、JOIN 等复杂语法简单的字符串拼接很容易出错更稳妥的方案是抽象出通用的 SQL 解析器或者基于规范化的表名映射做处理。如果你的团队用的是 JPA/Hibernate同样有类似的多租户过滤器可以配置。但无论用什么框架我都建议把“自动加租户条件”当成一个独立的基础设施模块来做单元测试测试用例覆盖普通查询、聚合查询、连表查询、子查询、批量更新这几类典型场景。提示多租户拦截器里的 SQL 改写是所有改造中最危险的部分。上线前一定要用生产环境的真实慢日志做一轮全量 SQL review确认没有一条 SQL 会被错误改写或漏改写。3.3 数据源与连接池的处理隔离模式决定了数据源的路由方式。共享表模式下所有租户都用同一个数据源无需动态切换连接池配置也最简单。独立 Schema 模式下需要在应用运行时按租户切换到不同的 Schema也就是动态数据源路由。Java 生态里最常用的方案是继承 AbstractRoutingDataSource重写 determineCurrentLookupKey 方法从 TenantContext 中获取租户 ID然后根据租户 ID 返回对应的数据源 key。public class TenantRoutingDataSource extends AbstractRoutingDataSource { Override protected Object determineCurrentLookupKey() { return TenantContext.getTenantId(); } }不过这里有个关键问题连接池是按租户维度建立的每个租户的数据源都会占用一定数量的数据库连接。如果租户几百个每个租户的连接池配置 5 个连接那连接总数就非常可观了。所以实际做动态数据源时建议把连接池的核心参数调小或者直接为所有租户使用同一个连接池通过 schema 名来做路由而不是按租户建立独立连接池。我在实践中更推荐后一种方式数据库连接还是用统一的连接池只是在执行 SQL 前动态切换当前连接的 schema。PostgreSQL 里的实现是执行 SET search_path TO tenant_xxxMySQL 则是 USE tenant_xxx。这样连接数不会随租户数膨胀路由开销也非常小。只有独立数据库模式才真正需要按租户建独立数据源和独立连接池。4. 实际动手把一个单体应用改造为多租户架构4.1 存量表结构如何改造很多场景不是从零搭建新系统而是把已经跑了好几年的单体系统改造成多租户。这里最大的难点是存量数据怎么打上租户标记。第一步是梳理所有业务表找出哪些是需要按租户隔离的哪些是全局共享的。我一般会定一个简单的规则凡是与业务数据直接相关的表订单、用户、商品、账单、消息等都必须有 tenant_id凡是系统配置类、枚举类、平台管理类的表可以不加但在访问时要明确标注为全局表。第二步给业务表加 tenant_id 字段。这个字段建议用字符串类型UUID而不是自增数字因为多个租户的数据在同一张表里数字主键已经存在再用数字做租户标识很容易混淆。tenant_id 加上后要建立 (tenant_id, 业务主键) 的联合唯一约束防止不同租户的数据在业务索引层面互相干扰。第三步是存量数据的回填。如果原来的系统是单人户的所有存量数据都属于同一个内部租户需要把这批数据统一打上这个内部租户的标识。如果原来的系统是多套独立部署的则需要把每个部署的数据迁移到新系统中按原部署标记租户 ID。这一步建议通过离线脚本完成并且在迁移完跑一遍全表校验每条业务数据都有且仅有一个合法的 tenant_id。4.2 在入口层注册租户上下文中间件表结构改完之后接下来在应用层接入租户上下文。以 Spring Boot 项目为例做法是把自己实现的 TenantFilter 注册到过滤链里。需要注意一个问题Filter 的执行顺序租户过滤器的顺序要放在认证过滤器之后、业务 Controller 之前。因为要先通过认证解析出用户身份再根据用户所属租户设置上下文。顺序错了会出现一个很隐蔽的问题匿名接口比如用户未登录时访问的登录接口也需要租户上下文如果认证过滤器先执行未登录请求直接就被拒掉或者跳过租户上下文就无法设置。我的建议是租户过滤器放在最外层先按请求头里解析到的租户信息设置上下文后续所有组件包括认证就都能访问到。对于移动端或第三方开放平台接入的场景Header 可能不是 X-Tenant-Id而是藏在签名参数里。这种情况建议在 API 网关层做一次统一转换所有进来的请求网关负责识别租户身份并追加统一的租户 Header后端服务无感知这样的架构最干净。后端只认规范化的 Header 名不用关心租户信息是从域名、Token 还是签名参数里解析出来的。4.3 用拦截器统一处理 SQL 级隔离结构改造和上下文之后核心是 SQL 隔离层。我给出一个 MyBatis 拦截器的最小实现思路方便你照着自己的框架改造Intercepts({ Signature(type StatementHandler.class, method prepare, args {Connection.class, Integer.class}) }) public class TenantLineInterceptor implements Interceptor { Override public Object intercept(Invocation invocation) throws Throwable { StatementHandler statementHandler (StatementHandler) invocation.getTarget(); BoundSql boundSql statementHandler.getBoundSql(); String originalSql boundSql.getSql(); String tenantId TenantContext.getTenantId(); if (StringUtils.hasText(tenantId) isTenantTable(originalSql)) { String newSql SqlUtils.appendTenantCondition(originalSql, tenantId); Field sqlField boundSql.getClass().getDeclaredField(sql); sqlField.setAccessible(true); sqlField.set(boundSql, newSql); } return invocation.proceed(); } }这个实现虽然可以用但我必须诚实地说真正上线时字符串级别的 SQL 改写会有各种边界情况。比如 SQL 里已经存在同名的 tenant_id 条件、子查询里带着同名字段、函数内部出现字符串包含 where 关键字等等。所以更可靠的方案是基于 Druid 或 JSqlParser 这类成熟的 SQL 解析库把 SQL 解析成语法树在语法树层面注入条件再重新生成 SQL。另外为了将来从共享表平滑升级到独立 Schema 模式我建议把租户条件注入的逻辑做成可配置的。配置文件里定义一个 tenant.mode 参数值为 shared 时自动加 where tenant_id ?值为 schema 时自动切换 search_path值为 db 时自动路由数据源。业务代码完全不感知隔离级别的变化这是参考架构里很关键的一层抽象。5. 最容易翻车的坑和排查手册5.1 定时任务和异步线程丢失租户上下文多租户系统里最隐蔽的数据串号问题几乎都是从一个被遗忘的异步线程开始的。主线程里 TenantContext 设置得好好的但一旦代码里出现了 Async、消息消费者、定时任务或 CompletableFuture子线程就拿不到父线程的 ThreadLocal自然也就丢了租户上下文。一个行业里常见的失误发生在定时任务场景。比如每天凌晨跑批量结算任务代码里遍历所有租户循环处理for (String tenantId : tenantList) { TenantContext.setTenantId(tenantId); settlementService.settle(); // 如果这里内部又开了异步线程上下文就丢了 }看起来蛮正常的。但如果在 settle 方法里用了并行流或者线程池去批量处理订单明细子线程里完全没有租户信息SQL 拦截器一看 TenantContext 为空可能就直接跳过了租户条件注入。结果就是所有租户的订单都算到一起。解决方案有两个缺一不可。第一线程池的任务提交时显式把租户 ID 作为任务参数传入任务内部主动设置上下文。第二兜底策略如果 SQL 拦截器检测到需要隔离的表没有被注入租户条件直接抛出异常而不是静默执行。也就是说宁可系统报错也不能让数据在无租户边界的情况下被访问。注意这是多租户系统里一条铁律——没有租户上下文的访问必须被视为致命错误而不是正常请求。把漏租户的 SQL 默认拦截成异常能救你无数次。5.2 缓存和消息队列里的租户隔离数据隔离不能只看数据库。Redis 缓存和消息队列里的 key、topic 同样需要租户维度。常见的坑是缓存 key 没有带租户前缀。比如用户信息缓存的 key 设计成 user_123租户 A 和租户 B 的用户 ID 都是 123那就互相覆盖了。设计缓存 key 的规范应该是 tenantId:bizType:bizId比如 t001:user:123。做法虽然简单但需要形成编码规范否则后面排查起来非常费劲。消息队列那边的问题更隐蔽。消费者处理消息时需要知道这条消息属于哪个租户而消息体里不一定包含租户字段。我建议在消息生产时把租户 ID 写入消息头消费者在监听方法里解析消息头并设置上下文。还有一种场景是延迟队列或重试队列要注意从队列重新投递的消息也要重新设置租户上下文不能依赖上一个消费者遗留的状态。搜热词的时候看到 dify 社区版 1.10 的多租户更新本质上也是在做同样的处理。像这种 AI 平台类的产品多租户除了业务数据还要考虑知识库索引、向量数据库集合、模型调用配额的多租户维度逻辑和这里说的一致只是多了几个需要隔离的存储层。5.3 报表导出和后台管理漏过滤报表导出是另一个高发事故区。很多系统里业务页面都用了 MyBatis 拦截器自动加租户条件但报表模块因为性能原因经常直接写原生 SQL 或者用独立的数据查询服务绕过了常规的数据访问层。跑批导出的时候如果没有在 SQL 里手动加租户条件导出来的就是全量的数据。我曾经排查过一个客户投诉案例业务人员导出本租户的销售报表结果 Excel 里出现了几万行其他公司的数据。排查了半天发现那个导出接口为了性能用 JdbcTemplate 直接执行了一条动态拼接的 SQL而 JdbcTemplate 不在 MyBatis 的拦截范围内。所以这里必须补充两条规范第一所有绕过主数据访问层框架的数据库操作必须由开发者在代码 review 阶段明确确认租户条件第二报表查询走独立的网关入口由报表服务统一拼接租户条件避免业务端各自为政。后台管理系统也不能放松。管理员可能拥有跨租户的查询权限负责运营的人需要看到一个租户一个租户的数据。这种场景下的建议是建立“数据权限”体系查询逻辑同时校验用户的角色权限和租户范围管理员可以切换租户身份但切换动作要留审计日志。这里不用强制所有后台查询带单租户条件但必须保证每个查询都在明确的租户范围内执行。5.4 快速定位异常的两条排查路径当数据串号、租户上下文丢失这类问题发生时高效的排查路径比直接翻代码重要得多。第一条路径是看日志。必须在租户过滤器中添加 MDC 变量把租户 ID 打入日志上下文。这样所有业务日志都会自动带上 [tenantIdt001] 这样的前缀排查时 grep 单个租户的日志即可快速定位。没有租户日志前缀的日志系统多租户排查基本靠猜。第二条路径是开 SQL 审计。在测试环境或灰度环境开启 SQL 日志输出检查每条 SQL 是否都有租户条件。自动化一点的做法是写一个集成测试模拟多租户并发访问断言每个租户查询到的数据集只包含自己的数据。这个集成测试的意义不只是验证当前代码更是防止未来新同事接手时不小心破坏隔离逻辑。下面是几张常见问题速查表我贴出来供你参考问题现象可能原因解决思路租户 A 能看到租户 B 的数据拦截器未覆盖某些查询路径检查所有 DAO 是否走统一访问层为绕过访问层的查询补租户条件某条 SQL 无租户条件但未报错拦截器把该表识别为全局表检查表白名单配置确认该表确实需要全局共享异步任务处理的数据归属错乱子线程丢失租户上下文任务提交时显式传入租户 ID子线程内重新设置上下文缓存数据错乱缓存 key 缺少租户维度统一改成 tenantId:业务类型:业务ID 格式清理历史脏数据定时报表数据偶发偏差报表 SQL 拼接了租户条件但使用 JOIN 时产生笛卡尔积检查 JOIN 条件中是否漏掉租户关联必要时用 ROW_NUMBER 去重6. 关于多租户数据隔离说点实在的整套参考架构讲到这里我把核心脉络再串一下多租户数据隔离不是选一个数据库方案就完事而是识别方式、隔离模式、上下文传递、SQL 注入、异步链路、缓存消息、运维排查这一整套体系的组合。刚开始改造时不要追求一步到位做到独立库而是先把共享表和强隔离上下文机制做扎实再叠加动态切换能力这样成本可控、演进路径也清晰。在我个人的实操经验里有几个点值得你再三确认。第一个是租户 ID 无处不在的原则。我见过太多系统在刚开始做多租户时只给主表加了 tenant_id但关联表、日志表、导入记录表、操作审计表全都没有。一旦业务流程覆盖到这些表数据归属就乱了。所以在设计阶段画一遍全平台的数据模型把所有可能存业务数据的表都列出来逐个标记隔离策略这一步一定不要省。第二个是尽量早地建立“无租户上下文即异常”的兜底机制。做多租户最怕的不是报错而是静默地查出串号数据。宁可让一条 SQL 因为缺少租户条件抛异常导致整个接口报错也不能让它在无边界状态下执行。这个策略在上线早期会暴露不少漏网之鱼但排查完这些之后系统会进入一个非常稳定的状态。第三个是隔离模式不要锁死在一种方案上。客户需求是变化的今天很多客户接受共享表明天可能有几个大客户提出数据物理隔离的合规要求。所以从一开始就把 TenantContext 抽象好、把数据源路由做成可配置将来切换模式时就是改配置加迁移脚本的事而不是推倒重写。这个扩展性价值会在平台发展到一个阶段后体现得淋漓尽致。一点小技巧如果团队里多人并行开发多租户功能建议约定一个简单的代码规范——任何新增的 DAO 方法、任何新增的业务表都必须写一个“分租户查询”的单元测试用例验证同一方法是能正确区分不同租户的数据。这个习惯坚持下来多租户相关的回归问题会少一大半。多租户数据隔离说难不难说简单也不简单核心就是纪律和细节。希望这份参考架构能帮你把思路理清楚少踩几个我踩过的坑。 
长河君 · 2026/11/4 8:50:12 · 阅读 1.2k 多租户数据隔离架构设计：从选型到代码落地的实操指南
最近不管是技术社区还是团队内部的架构评审多租户、数据隔离这几个词的出镜率都高得离谱。尤其是 dify 社区版 1.10 把多租户作为一个核心卖点之后我身边不少做 SaaS 的朋友都在研究这事。其实多租户这套东西说穿了并不玄乎核心就一个问题一套系统服务 N 家客户数据如何既隔得开、又不至于把运维成本和性能拖垮。我这些年经手过不少多租户系统的设计和改造从最初几家大客户的私有化部署到现在上百家租户共用一个集群各种隔离方案都试过。这篇就整理一份可以直接落地的多租户数据隔离参考架构把方案选型、代码改造、常见翻车点一次讲透。无论你是刚接手公司 SaaS 项目的后端开发还是正在规划平台化的技术负责人这篇里的实操经验应该都能帮你少走不少弯路。1. 先弄清楚多租户数据隔离到底要隔离什么1.1 隔离的本质是租户维度的边界很多人一提数据隔离第一反应就是“把数据分开存”。但分开存只是手段多租户隔离的本质是在应用层建立一个贯穿全链路的租户维度边界。什么意思就是说无论是用户登录、接口请求、后台任务还是报表查询系统在任何时刻都要知道当前操作属于哪个租户并且所有数据访问都被强制限制在这个租户的范围内。这个边界建立不起来就会出现两类问题一类是恶意的越权访问比如一个用户通过改 URL 参数就能查到别的公司的数据另一类是更隐蔽的逻辑漏洞比如定时任务里忘记带租户条件结果某个租户的统计数据里混进了所有租户的数据。第二类往往比第一类更致命因为它不是被攻击而是系统自己制造的数据污染。我见过一个真实的案例某 SaaS 平台的报表模块在生成月度账单时查询条件里漏掉了租户 ID结果所有租户看到的账单数据都是全平台累计的。这种事故一旦发生客户信任基本就归零了。所以隔离方案设计的首要任务不是选数据库而是想清楚租户边界如何在代码的每一层传递和被强制执行。1.2 三种租户识别方式要在系统里建立一个租户维度边界第一步是解决“怎么知道当前请求属于哪个租户”的问题。实际项目里常用的有三种识别方式第一种是独立域名或子域名方式比如 tenantA.example.com 和 tenantB.example.com。这种方式最直观用户访问的 URL 天然带着租户信息还可以配合 CDN 和独立 SSL 证书做差异化配置。但缺点也很明显DNS 配置和证书管理在大规模租户场景下会变得很繁琐而且测试环境要模拟多租户域名也比较麻烦。第二种是请求 Header 或 Token 携带租户信息。现在绝大多数 SaaS 架构采用 JWT 做认证租户 ID 作为 Token 里的一个自定义 Claim 一起签发。后端从请求头里解析出租户 ID放入上下文。这种方式灵活不依赖 DNS 配置也方便在 API 网关层统一处理是目前最主流的做法。第三种是 URL 路径参数方式比如 /api/{tenantId}/orders。这种方式老项目改造时比较方便但风险也最大如果后端没有严格校验路径参数和当前登录用户所属租户的一致性就很容易被水平越权。一般不建议新项目直接用这种方式除非有网关层做租户映射。我实际做改造时的偏好是第二种为主域名方式用于大型客户的门户入口路径参数只在某些公开接口的兼容场景下使用。识别方式确定后接下来要做的就是把这个租户 ID 从请求入口一路传递到 SQL 执行层。2. 三种主流隔离模式怎么选2.1 独立数据库模式最稳但也最贵独立数据库模式也就是每个租户一套独立的数据库实例或独立库。这是隔离强度最高的方案租户之间在物理层面完全隔离无论数据备份、恢复、扩缩容还是性能调优都可以针对单个租户独立操作。这种模式的优点很直观安全级别最高完全不存在租户间串数据的可能数据库故障的影响面也小一个租户的库挂了不会拖累其他租户还能给大客户提供专门的资源保障和定制化部署。但缺点同样突出。首先是成本数据库实例数量随租户数线性增长哪怕每个库只占几十 MB也要为每个实例付出独立的内存和进程开销。其次是运维复杂度一百个租户就是一百套备份任务、一百套监控告警、一百套升级流程。哪怕用云数据库托管服务日常管理仍然是个不小的工作量。所以这个模式的实际适用范围很窄要么是客单价极高的政企大客户要么是有强合规要求比如金融行业必须做到数据物理隔离的场景。如果你是做通用型 SaaS全量用这种模式基本等于烧钱。2.2 共享数据库、独立 Schema均衡方案共享数据库、独立 Schema 模式是指所有租户共用一个数据库实例但每个租户拥有自己独立的 Schema在 MySQL 里可以近似理解为独立库在 PostgreSQL 里则是真正的 Schema。这种方案的隔离级别是逻辑层隔离每个 Schema 内的表结构可以独立演进应用层通过切换 search_pathPostgreSQL或者切换数据库名MySQL来实现租户路由。由于数据仍然物理上存放在同一个实例中数据库实例的数量不会随租户数暴涨硬件成本相对可控。它的优点在于隔离性和成本之间取得了较好的平衡一个租户的误操作一般不会直接破坏另一个租户的数据结构备份也能按 Schema 做精细化处理租户之间的数据在存储层就有天然边界。缺点是单个数据库实例的资源始终是共享的一旦某个租户的数据量特别大或者某条 SQL 特别慢仍然可能拖累同实例上的其他租户。我的经验是它特别适合租户数量在几十到几百之间、单租户数据量中等、且存在定制化表结构需求的平台型产品。比如不少企业服务类 SaaS 需要给不同客户开放自定义字段独立 Schema 就能相对安全地支持这类需求。2.3 共享表、租户 ID 维度最常用的取舍共享表模式是所有租户共用同一组表通过表里的租户 ID 字段来区分数据归属。这是互联网 SaaS 产品里最普及的方案几乎所有快速增长的云原生应用初期都会选择它。它的最大优势是资源利用率高一张表可以服务所有租户不需要维护成百上千个 Schema开发和迭代效率也高加字段、加索引只需要操作一套表结构数据聚合分析非常方便跨租户的统计查询天然就能实现。但这个模式最考验的是应用层的隔离纪律。你必须在所有 SQL 查询中强制携带租户条件一条 SQL 漏了 where tenant_id ?后果就是数据串号。而且表数据量会随着租户增长迅速膨胀索引设计、分区策略、慢查询治理都是后续长期要做的事情。现实中很多团队一开始图省事选择共享表后来遇到大客户要求更高隔离级别再想办法迁移。其实这个演进路径是合理的共享表方案本身没有问题问题在于有没有从一开始就把租户上下文的传递机制做好。只要上下文机制是健壮的从共享表迁移到独立 Schema 只是数据搬迁的事。2.4 选型决策按客户、成本、合规三个维度权衡三种模式各有适用场景我给的建议是不要一步到位而是按客户维度做混合隔离免费试用版/低价值客户共享表成本优先中小付费客户共享表或独立 Schema看是否需要定制表结构大客户/强合规客户独立 Schema 或独立库安全优先需要物理隔离的金融政务客户独立库成本侧要注意一个容易被忽略的细节看似省钱的共享表模式随着租户和数据量增长为了扛住压力往往会引入读写分离、分库分表、分布式缓存等复杂基础设施这些总拥有成本未必比一开始用独立 Schema 低。合规侧则要看客户合同里的条款约定有些客户会明确要求数据存储与其他租户物理隔离这时候不管代码层做得有多好都必须用独立库来兜底。所以参考架构在选型上的结论是默认采用共享表 强隔离上下文机制预留独立 Schema 和独立库的升级路径让隔离级别本身成为可配置项。3. 把隔离真正落到代码里的关键步骤3.1 租户上下文的建立与传递代码层的多租户改造第一步是把租户上下文这个基础设施搭好。租户上下文的核心是一个全局的线程级变量用来保存当前请求正在处理哪个租户。我以 Java 技术栈为例最常见的方式是用 ThreadLocal 包一层public class TenantContext { private static final ThreadLocalString CURRENT_TENANT new ThreadLocal(); public static void setTenantId(String tenantId) { CURRENT_TENANT.set(tenantId); } public static String getTenantId() { return CURRENT_TENANT.get(); } public static void clear() { CURRENT_TENANT.remove(); } }这个类本身很简单但它有几个使用上的关键纪律。第一必须在请求进入时设置租户 ID通常在 Filter 或拦截器里从 JWT 或 Header 解析出来。第二必须在请求结束时清理 ThreadLocal否则线程池复用的线程会带着上一个租户的上下文处理下一个请求这是数据串号的头号原因。Component public class TenantFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest httpRequest (HttpServletRequest) request; String tenantId httpRequest.getHeader(X-Tenant-Id); if (StringUtils.hasText(tenantId)) { TenantContext.setTenantId(tenantId); } try { chain.doFilter(request, response); } finally { TenantContext.clear(); } } }如果你用的是 Python/Flask 或 Node.js思路完全一样只是换成 contextvars 或者 AsyncLocal。关键是理解一点租户 ID 不是某个业务代码里随手取的参数而是贯穿整个调用链的上下文状态。任何异步线程、定时任务、消息消费者内部要使用租户上下文时都必须显式传入或者从调用链中继承绝不能在子线程里直接读主线程的 ThreadLocal。3.2 数据访问层如何自动附加租户条件上下文有了之后最难的就是保证所有数据库查询都自动带上租户条件。人工在每条 SQL 里手写 where tenant_id ? 是不现实的总会有遗漏。真正的解法是在数据访问层做一个统一的拦截器自动改写 SQL。MyBatis 的 Interceptor 是一个典型的实现位置。在拦截器里解析即将执行的 SQL 语句如果是 SELECT、UPDATE、DELETE就自动拼接租户条件。需要注意 UPDATE 和 DELETE 必须强制加租户条件否则就可能出现跨租户误改数据。实现上有几点经验值得分享第一只对包含目标表名的 SQL 做拼接系统表、字典表、跨租户的全局配置表要加入白名单。第二INSERT 语句不需要改写 where 条件但需要在应用的实体层自动填充 tenant_id 字段避免开发人员忘记赋值。第三SQL 改写要考虑到别名、子查询、JOIN 等复杂语法简单的字符串拼接很容易出错更稳妥的方案是抽象出通用的 SQL 解析器或者基于规范化的表名映射做处理。如果你的团队用的是 JPA/Hibernate同样有类似的多租户过滤器可以配置。但无论用什么框架我都建议把“自动加租户条件”当成一个独立的基础设施模块来做单元测试测试用例覆盖普通查询、聚合查询、连表查询、子查询、批量更新这几类典型场景。提示多租户拦截器里的 SQL 改写是所有改造中最危险的部分。上线前一定要用生产环境的真实慢日志做一轮全量 SQL review确认没有一条 SQL 会被错误改写或漏改写。3.3 数据源与连接池的处理隔离模式决定了数据源的路由方式。共享表模式下所有租户都用同一个数据源无需动态切换连接池配置也最简单。独立 Schema 模式下需要在应用运行时按租户切换到不同的 Schema也就是动态数据源路由。Java 生态里最常用的方案是继承 AbstractRoutingDataSource重写 determineCurrentLookupKey 方法从 TenantContext 中获取租户 ID然后根据租户 ID 返回对应的数据源 key。public class TenantRoutingDataSource extends AbstractRoutingDataSource { Override protected Object determineCurrentLookupKey() { return TenantContext.getTenantId(); } }不过这里有个关键问题连接池是按租户维度建立的每个租户的数据源都会占用一定数量的数据库连接。如果租户几百个每个租户的连接池配置 5 个连接那连接总数就非常可观了。所以实际做动态数据源时建议把连接池的核心参数调小或者直接为所有租户使用同一个连接池通过 schema 名来做路由而不是按租户建立独立连接池。我在实践中更推荐后一种方式数据库连接还是用统一的连接池只是在执行 SQL 前动态切换当前连接的 schema。PostgreSQL 里的实现是执行 SET search_path TO tenant_xxxMySQL 则是 USE tenant_xxx。这样连接数不会随租户数膨胀路由开销也非常小。只有独立数据库模式才真正需要按租户建独立数据源和独立连接池。4. 实际动手把一个单体应用改造为多租户架构4.1 存量表结构如何改造很多场景不是从零搭建新系统而是把已经跑了好几年的单体系统改造成多租户。这里最大的难点是存量数据怎么打上租户标记。第一步是梳理所有业务表找出哪些是需要按租户隔离的哪些是全局共享的。我一般会定一个简单的规则凡是与业务数据直接相关的表订单、用户、商品、账单、消息等都必须有 tenant_id凡是系统配置类、枚举类、平台管理类的表可以不加但在访问时要明确标注为全局表。第二步给业务表加 tenant_id 字段。这个字段建议用字符串类型UUID而不是自增数字因为多个租户的数据在同一张表里数字主键已经存在再用数字做租户标识很容易混淆。tenant_id 加上后要建立 (tenant_id, 业务主键) 的联合唯一约束防止不同租户的数据在业务索引层面互相干扰。第三步是存量数据的回填。如果原来的系统是单人户的所有存量数据都属于同一个内部租户需要把这批数据统一打上这个内部租户的标识。如果原来的系统是多套独立部署的则需要把每个部署的数据迁移到新系统中按原部署标记租户 ID。这一步建议通过离线脚本完成并且在迁移完跑一遍全表校验每条业务数据都有且仅有一个合法的 tenant_id。4.2 在入口层注册租户上下文中间件表结构改完之后接下来在应用层接入租户上下文。以 Spring Boot 项目为例做法是把自己实现的 TenantFilter 注册到过滤链里。需要注意一个问题Filter 的执行顺序租户过滤器的顺序要放在认证过滤器之后、业务 Controller 之前。因为要先通过认证解析出用户身份再根据用户所属租户设置上下文。顺序错了会出现一个很隐蔽的问题匿名接口比如用户未登录时访问的登录接口也需要租户上下文如果认证过滤器先执行未登录请求直接就被拒掉或者跳过租户上下文就无法设置。我的建议是租户过滤器放在最外层先按请求头里解析到的租户信息设置上下文后续所有组件包括认证就都能访问到。对于移动端或第三方开放平台接入的场景Header 可能不是 X-Tenant-Id而是藏在签名参数里。这种情况建议在 API 网关层做一次统一转换所有进来的请求网关负责识别租户身份并追加统一的租户 Header后端服务无感知这样的架构最干净。后端只认规范化的 Header 名不用关心租户信息是从域名、Token 还是签名参数里解析出来的。4.3 用拦截器统一处理 SQL 级隔离结构改造和上下文之后核心是 SQL 隔离层。我给出一个 MyBatis 拦截器的最小实现思路方便你照着自己的框架改造Intercepts({ Signature(type StatementHandler.class, method prepare, args {Connection.class, Integer.class}) }) public class TenantLineInterceptor implements Interceptor { Override public Object intercept(Invocation invocation) throws Throwable { StatementHandler statementHandler (StatementHandler) invocation.getTarget(); BoundSql boundSql statementHandler.getBoundSql(); String originalSql boundSql.getSql(); String tenantId TenantContext.getTenantId(); if (StringUtils.hasText(tenantId) isTenantTable(originalSql)) { String newSql SqlUtils.appendTenantCondition(originalSql, tenantId); Field sqlField boundSql.getClass().getDeclaredField(sql); sqlField.setAccessible(true); sqlField.set(boundSql, newSql); } return invocation.proceed(); } }这个实现虽然可以用但我必须诚实地说真正上线时字符串级别的 SQL 改写会有各种边界情况。比如 SQL 里已经存在同名的 tenant_id 条件、子查询里带着同名字段、函数内部出现字符串包含 where 关键字等等。所以更可靠的方案是基于 Druid 或 JSqlParser 这类成熟的 SQL 解析库把 SQL 解析成语法树在语法树层面注入条件再重新生成 SQL。另外为了将来从共享表平滑升级到独立 Schema 模式我建议把租户条件注入的逻辑做成可配置的。配置文件里定义一个 tenant.mode 参数值为 shared 时自动加 where tenant_id ?值为 schema 时自动切换 search_path值为 db 时自动路由数据源。业务代码完全不感知隔离级别的变化这是参考架构里很关键的一层抽象。5. 最容易翻车的坑和排查手册5.1 定时任务和异步线程丢失租户上下文多租户系统里最隐蔽的数据串号问题几乎都是从一个被遗忘的异步线程开始的。主线程里 TenantContext 设置得好好的但一旦代码里出现了 Async、消息消费者、定时任务或 CompletableFuture子线程就拿不到父线程的 ThreadLocal自然也就丢了租户上下文。一个行业里常见的失误发生在定时任务场景。比如每天凌晨跑批量结算任务代码里遍历所有租户循环处理for (String tenantId : tenantList) { TenantContext.setTenantId(tenantId); settlementService.settle(); // 如果这里内部又开了异步线程上下文就丢了 }看起来蛮正常的。但如果在 settle 方法里用了并行流或者线程池去批量处理订单明细子线程里完全没有租户信息SQL 拦截器一看 TenantContext 为空可能就直接跳过了租户条件注入。结果就是所有租户的订单都算到一起。解决方案有两个缺一不可。第一线程池的任务提交时显式把租户 ID 作为任务参数传入任务内部主动设置上下文。第二兜底策略如果 SQL 拦截器检测到需要隔离的表没有被注入租户条件直接抛出异常而不是静默执行。也就是说宁可系统报错也不能让数据在无租户边界的情况下被访问。注意这是多租户系统里一条铁律——没有租户上下文的访问必须被视为致命错误而不是正常请求。把漏租户的 SQL 默认拦截成异常能救你无数次。5.2 缓存和消息队列里的租户隔离数据隔离不能只看数据库。Redis 缓存和消息队列里的 key、topic 同样需要租户维度。常见的坑是缓存 key 没有带租户前缀。比如用户信息缓存的 key 设计成 user_123租户 A 和租户 B 的用户 ID 都是 123那就互相覆盖了。设计缓存 key 的规范应该是 tenantId:bizType:bizId比如 t001:user:123。做法虽然简单但需要形成编码规范否则后面排查起来非常费劲。消息队列那边的问题更隐蔽。消费者处理消息时需要知道这条消息属于哪个租户而消息体里不一定包含租户字段。我建议在消息生产时把租户 ID 写入消息头消费者在监听方法里解析消息头并设置上下文。还有一种场景是延迟队列或重试队列要注意从队列重新投递的消息也要重新设置租户上下文不能依赖上一个消费者遗留的状态。搜热词的时候看到 dify 社区版 1.10 的多租户更新本质上也是在做同样的处理。像这种 AI 平台类的产品多租户除了业务数据还要考虑知识库索引、向量数据库集合、模型调用配额的多租户维度逻辑和这里说的一致只是多了几个需要隔离的存储层。5.3 报表导出和后台管理漏过滤报表导出是另一个高发事故区。很多系统里业务页面都用了 MyBatis 拦截器自动加租户条件但报表模块因为性能原因经常直接写原生 SQL 或者用独立的数据查询服务绕过了常规的数据访问层。跑批导出的时候如果没有在 SQL 里手动加租户条件导出来的就是全量的数据。我曾经排查过一个客户投诉案例业务人员导出本租户的销售报表结果 Excel 里出现了几万行其他公司的数据。排查了半天发现那个导出接口为了性能用 JdbcTemplate 直接执行了一条动态拼接的 SQL而 JdbcTemplate 不在 MyBatis 的拦截范围内。所以这里必须补充两条规范第一所有绕过主数据访问层框架的数据库操作必须由开发者在代码 review 阶段明确确认租户条件第二报表查询走独立的网关入口由报表服务统一拼接租户条件避免业务端各自为政。后台管理系统也不能放松。管理员可能拥有跨租户的查询权限负责运营的人需要看到一个租户一个租户的数据。这种场景下的建议是建立“数据权限”体系查询逻辑同时校验用户的角色权限和租户范围管理员可以切换租户身份但切换动作要留审计日志。这里不用强制所有后台查询带单租户条件但必须保证每个查询都在明确的租户范围内执行。5.4 快速定位异常的两条排查路径当数据串号、租户上下文丢失这类问题发生时高效的排查路径比直接翻代码重要得多。第一条路径是看日志。必须在租户过滤器中添加 MDC 变量把租户 ID 打入日志上下文。这样所有业务日志都会自动带上 [tenantIdt001] 这样的前缀排查时 grep 单个租户的日志即可快速定位。没有租户日志前缀的日志系统多租户排查基本靠猜。第二条路径是开 SQL 审计。在测试环境或灰度环境开启 SQL 日志输出检查每条 SQL 是否都有租户条件。自动化一点的做法是写一个集成测试模拟多租户并发访问断言每个租户查询到的数据集只包含自己的数据。这个集成测试的意义不只是验证当前代码更是防止未来新同事接手时不小心破坏隔离逻辑。下面是几张常见问题速查表我贴出来供你参考问题现象可能原因解决思路租户 A 能看到租户 B 的数据拦截器未覆盖某些查询路径检查所有 DAO 是否走统一访问层为绕过访问层的查询补租户条件某条 SQL 无租户条件但未报错拦截器把该表识别为全局表检查表白名单配置确认该表确实需要全局共享异步任务处理的数据归属错乱子线程丢失租户上下文任务提交时显式传入租户 ID子线程内重新设置上下文缓存数据错乱缓存 key 缺少租户维度统一改成 tenantId:业务类型:业务ID 格式清理历史脏数据定时报表数据偶发偏差报表 SQL 拼接了租户条件但使用 JOIN 时产生笛卡尔积检查 JOIN 条件中是否漏掉租户关联必要时用 ROW_NUMBER 去重6. 关于多租户数据隔离说点实在的整套参考架构讲到这里我把核心脉络再串一下多租户数据隔离不是选一个数据库方案就完事而是识别方式、隔离模式、上下文传递、SQL 注入、异步链路、缓存消息、运维排查这一整套体系的组合。刚开始改造时不要追求一步到位做到独立库而是先把共享表和强隔离上下文机制做扎实再叠加动态切换能力这样成本可控、演进路径也清晰。在我个人的实操经验里有几个点值得你再三确认。第一个是租户 ID 无处不在的原则。我见过太多系统在刚开始做多租户时只给主表加了 tenant_id但关联表、日志表、导入记录表、操作审计表全都没有。一旦业务流程覆盖到这些表数据归属就乱了。所以在设计阶段画一遍全平台的数据模型把所有可能存业务数据的表都列出来逐个标记隔离策略这一步一定不要省。第二个是尽量早地建立“无租户上下文即异常”的兜底机制。做多租户最怕的不是报错而是静默地查出串号数据。宁可让一条 SQL 因为缺少租户条件抛异常导致整个接口报错也不能让它在无边界状态下执行。这个策略在上线早期会暴露不少漏网之鱼但排查完这些之后系统会进入一个非常稳定的状态。第三个是隔离模式不要锁死在一种方案上。客户需求是变化的今天很多客户接受共享表明天可能有几个大客户提出数据物理隔离的合规要求。所以从一开始就把 TenantContext 抽象好、把数据源路由做成可配置将来切换模式时就是改配置加迁移脚本的事而不是推倒重写。这个扩展性价值会在平台发展到一个阶段后体现得淋漓尽致。一点小技巧如果团队里多人并行开发多租户功能建议约定一个简单的代码规范——任何新增的 DAO 方法、任何新增的业务表都必须写一个“分租户查询”的单元测试用例验证同一方法是能正确区分不同租户的数据。这个习惯坚持下来多租户相关的回归问题会少一大半。多租户数据隔离说难不难说简单也不简单核心就是纪律和细节。希望这份参考架构能帮你把思路理清楚少踩几个我踩过的坑。