1. 多租户上新这件事先想清楚你的产品打算怎么切多租户功能在今年的产品版本里几乎成了标配无论是从私有化部署转向SaaS化服务还是原本单机部署的产品要支持多组织共用一套系统最后都会落到同一个问题这套系统能不能让多个互不隶属的客户在一个环境里安全、干净地一起跑。我这次负责的刚好就是产品从一客户一部署向一平台多租户切换的过程标题虽然是集成与适配指南但真正动起手来会发现集成和适配只是表象最麻烦的是产品形态定位没想清楚就开工。你给开发者的文档写得再漂亮底层的隔离粒度定错了后面所有的适配工作都是在打补丁。1.1 多租户不等于账号系统先分清隔离粒度很多人把多租户和RBAC权限模型混在一起以为给用户表加个组织字段、登录后带出组织ID就算多租户了。这个理解在演示Demo里没问题但真实产品里租户是一个独立的业务边界它的核心是数据隔离和资源按租户计量而账号体系只是入口。举个例子A公司和B公司都在你的SaaS平台上注册了工作区A公司的销售订单、B公司的客户档案、C公司的财务凭证这些数据在数据库里可以物理隔离也可以逻辑隔离但无论哪种方式查询时都必须带上租户维度否则一旦接口的过滤条件漏了最轻的是数据串号最重的是客户隐私数据泄露这个性质就不一样了。所以我在文档里给研发团队的第一条建议是先回答三个问题你的产品是多租户还是多组织多租户通常指平台方统一运营、租户之间完全隔离多组织则可能是同一集团下多个部门共享部分数据隔离要求没那么高。你的租户粒度绑定在哪个层级是按企业、按项目还是按工作空间这会直接影响租户ID放在哪一层中间件里传递。你的数据模型是共享库共享表、共享库独立Schema还是独立实例这三种模式的成本、隔离强度、扩容方式完全不同。1.2 三种隔离方案怎么选这块我建议技术负责人早点拍板因为它决定了后续集成的很多细节。三种主流方案各有利弊我列个对比表。隔离方案隔离强度成本扩容难度典型适用场景独立实例每租户一套环境物理隔离最强极高新租户需部署运维压力大超大型客户、合规要求极高的金融行业共享数据库、独立Schema逻辑隔离较强中需支持Schema创建和迁移中大型SaaS租户数量可控共享库共享表逻辑隔离最弱低最容易但数据量膨胀快中小型SaaS租户量极大单租户数据量小我们现在用的就是第三种共享库共享表所有租户的业务数据在同一张表里靠tenant_id字段区分。这个方案上线快、硬件成本低但对开发者的纪律性要求最高因为每一行数据、每一条SQL、每一个缓存键都必须把租户维度带进去。如果你以为共享表只是加个字段那就大错特错了。后面会讲到隐藏的改造成本在索引、唯一约束、定时任务、消息队列这些不起眼的角落里。2. 集成方的第一道坎租户上下文与身份识别的传递逻辑多租户功能上新的消息一发布最先来问我的不是后端开发而是负责对接第三方系统的集成同事——他们手里的老系统要接入我们的开放平台却发现原来单租户时代的API签名、Token方案全变了现在需要额外理解租户的概念。这里其实是很多集成文档写得不清楚的地方多租户集成不是说让你在请求参数里硬加一个tenantId而是在身份识别链路里把租户上下文作为一等公民传递。2.1 从网关到业务层的租户标识链路以我们的平台为例完整链路是这样的客户端Web端、移动端、第三方系统请求进入API网关网关解析JWT TokenToken中带tenant_id声明网关校验通过后把tenant_id写入请求头比如X-Tenant-Id业务服务在入口处统一解析这个请求头存入当前线程的上下文ThreadLocal或类似机制业务代码在查询数据库时从上下文取出tenant_id作为强制过滤条件。前两步是身份识别后三步是上下文传递。集成方一般只需要关注前两步你的系统在调用我们API时Token里必须带上合法的租户标识。这个标识不是登录后固定不变的有的场景下同一个集成账号可能操作多个租户那就需要通过请求头动态切换当前租户而不是把租户写死在配置里。我见过不少集成方把tenant_id直接写在代码配置文件中一旦产品方调整了租户结构或者客户在后台重新创建了工作区配置就得改一遍非常脆弱。正确的做法是集成方自己维护一份外部系统账号与租户ID的映射关系在调用API前动态获取。2.2 这套链路容易断的地方从理论上讲这链路不难但实际执行中到处都是坑我挑几个最常见的第一个坑异步线程里上下文丢了。主线程的ThreadLocal在进入线程池后不会自动传递如果业务代码里用了Async或手动线程池子线程里根本拿不到tenant_id。这个问题的隐蔽性在于它不会每次必现只有并发量大了、线程复用频繁的时候才会偶发表现数据串了。我当时给团队的解决方案是写一个自定义的TaskDecorator在提交任务的时候把主线程的租户上下文快照拷到子线程任务执行完毕再清理。这个方案网上有很多现成实现关键是必须有强制代码审查防止有人绕过装饰器直接往线程池里丢任务。第二个坑第三方回调没有租户上下文。比如支付回调、Webhook通知这类请求不是用户在线发起的网关层解析不到用户Token自然也不知道这个请求属于哪个租户。处理方式一般是在发送通知时把租户ID放到消息体里或者回调URL的路径上回调服务从消息体解析后重新构建上下文。第三个坑消息队列消费方不知道自己在处理谁的请求。这个问题我在第4部分详细展开这里先提醒一句千万不要默认消息里只有业务数据就万事大吉租户ID必须作为消息头的强制字段。2.3 兼容多套鉴权体系的过渡方案很多产品上新多租户功能时存量客户还在用老的API密钥方式没法一天之内全切到JWT。这时候要说清楚过渡策略避免集成方两头踩空。我们是这么做的老接口维护一段时间兼容期兼容期内API网关同时支持旧密钥和新Token两种鉴权方式。旧密钥会关联一个默认租户新Token则完整携带租户上下文。网关上有一个映射表把旧的app_key映射到某个租户ID请求进来后如果没有X-Tenant-Id就回退到映射表里的默认值。这样做的缺点是调试时会困惑为什么同样的代码有的请求有租户上下文有的没有所以在兼容期文档里一定要写清楚每个接口的鉴权要求并给出明确的租户上下文缺失时的报错提示。我们后来统一了错误码10001 缺少租户上下文集成方看到这个错误码就知道问题出在鉴权阶段而不是业务逻辑。3. 数据隔离与代码改造成本共享表模式下的边界怎么守如果你选用了共享库共享表的方案意味着你选择了对开发人员自觉性要求最高的一种模式。我这里说的改造重点不在这张表加一列tenant_id——那是DDL的事几秒钟就搞定——在于怎么保证系统里所有数据通路都以租户为边界并且不因为过度隔离把代码搞成一团乱麻。3.1 为什么共享表模式最容易被低估因为单租户时代SQL写的是select * from orders where id ?直接、干净、膝盖不疼。加了一个租户维度后业务查询要额外维护一个恒真的身份条件这就像走路时腿上多绑了一根绳没有这跟绳你走得更顺但这根绳恰恰是你的安全绳。我举个例子订单查询接口// 单租户写法 ListOrder orders orderMapper.selectByCustomer(customerId); // 多租户写法 OrderQuery query new OrderQuery(); query.setTenantId(TenantContext.getTenantId()); query.setCustomerId(customerId); ListOrder orders orderMapper.selectByTenantAndCustomer(query);差别看着不大但如果在几十个Mapper方法里都手写这个setTenantId工作量大、容易漏写。更稳的做法是用MyBatis的拦截器或JPA的过滤器实现在SQL层自动拼接条件业务代码不感知租户维度由中间件兜底。我实测下来的建议是业务代码里不写租户条件统一走ORM拦截器自动注入。拦截器在生成SQL前根据上下文里的租户ID拼接到WHERE子句中。代价是排查问题时多一道抽象你看到的SQL和业务代码不是一一对应的但收益是漏配概率大幅降低。3.2 tenant_id的隐形蔓延和漏配有一个几乎每个改造项目都会遇到的场景内网管理后台。这类后台通常是平台运营人员用的它天然没有当前租户的概念但数据在上面。我见过某团队把全站所有接口都加了租户过滤结果运营后台查不到任何数据因为运营工单、平台配置、全局字典这些压根不该按租户隔离。所以数据隔离改造前一定要做一次数据边界清单。把系统里所有的业务对象分成三类数据类别处理方式示例强租户数据必须带租户隔离订单、客户档案、工单、文件资源弱租户数据按租户可见但可共享某些基础项产品目录、基础资料、模板配置全局数据不按租户隔离所有租户共享平台公告、系统字典、运营配置漏配最容易发生在弱租户数据和全局数据的边界上比如系统里有个产品分类表A租户自定义了两个分类B租户登录后居然能看到A租户的分类这就是典型的漏配——分类表属于弱租户数据需要对租户做过滤而过滤条件往往被当成基础服务不需要就给省了。3.3 唯一约束与全局主键序列的改造思路这一节容易被文档遗漏但特别影响集成体验。共享表模式下原来的主键自增策略会出问题如果订单表的主键是自增IDA租户和B租户的数据在表里混合存储主键虽然在物理上不会重复但业务上可能出现B租户的第一条数据的ID比A租户的第100条还大而且同一张表的ID序列是全局共享的等到了千万级数据量自增ID的唯一性倒还好说性能和数据分布的均匀性就成了隐患。我们的做法是引入统一的ID生成服务不用数据库自增改由应用层生成雪花ID。这样有几个好处主键全局唯一不与租户产生关联导数据时不会撞键分库分表时不用调整ID生成逻辑排查问题时可以通过ID快速定位是哪个分片的数据。另外唯一约束也要做租户维度的调整。举例原来的uk(user_id)唯一索引在所有租户下只能有一个记录现在要改成uk(tenant_id, user_id)否则A租户的用户与B租户的用户在user_id上撞了就会直接插入失败这个错误在集成测试阶段几乎必现但很多团队是在联调到第N个并发场景时才被炸出来。4. 缓存、定时任务与消息队列多租户最容易静默出错的三块如果说第3部分讲的数据隔离是明面上的那么缓存、定时任务和消息队列里的租户边界问题就是暗沟。因为这些问题平时不报错、不影响主流程只有数据开始串了、或者某个租户的数据被别人篡改了才会暴露而且暴露的时候往往已经过了很久很难回溯。4.1 Redis缓存键设计必须把租户ID当第一维度品牌项目里99%的Redis键在设计时都没考虑租户维度。比如你用一个缓存键存放系统配置system:config:list单租户没问题多租户之后A租户改了配置B租户读到的是A租户的配置看起来只是配置乱了但如果是缓存了提现费率、短信签名这类敏感数据后果会是费率串号、签名串发直接引起客诉。我们改缓存键时的统一规范是租户维度必须跟在前缀之后的第一段比如config:{tenantId}:list而不是放在最后。原因很简单——开发者在看Redis数据分布时一眼就能按租户过滤而且keys config:*这种模糊扫描的代价也更低。还有一类隐蔽的坑是用UUID作为key但没带租户的短时缓存比如短信验证码、文件上传预签名URL。如果你在生成这个UUID时把租户ID编码进去验证时就能避免跨租户借用。我们的做法是在生成验证码时就把它存入sms:code:{tenantId}:{phone}校验时用同样的键去取这样就算有人拿着A租户手机号拿到的验证码也不可能在B租户的手机号场景下通过校验。4.2 定时任务的租户遍历与调度错乱多租户改造之前定时任务写起来很爽半夜扫一遍全表把今天过期的优惠券标记为失效给即将到期的订单发提醒。多租户之后这个全表扫描就有问题了——扫描范围是全租户的虽然不会漏处理但会带来两个问题第一任务没有按租户隔离高峰期一个任务把所有租户的数据全扫了性能互相拖累。可以理解成本来应该全员排队结账的收银台突然开了一个超级通行证把所有人都放进来一起挤。第二任务的执行逻辑如果涉及根据最近一次数据做决策就会出现跨租户影响。例如发月报任务遍历所有租户但计算报表时引用了全局缓存的当前配置结果给A租户发月报时用的是B租户的模板这是一个非常难排查的逻辑串扰。改法其实不复杂把定时任务改造成按租户分批调度。写一个统一的调度入口先查出所有可用租户然后一个租户一个租户地执行每个租户的任务上下文隔离互不干扰。要注意的是租户列表本身要缓存并在新增租户时动态刷新不然新租户永远跑不上任务。4.3 消息队列消费方如何知道自己在处理谁的请求有段时间我们排查过一个线上问题A租户上传了一批文件转码服务处理后把结果消息发到队列结果B租户的文件列表里出现了一张A租户的转码后文件。这个问题的根源就是消息里带了文件ID没带租户ID消费方只按文件ID去更新数据库没有按租户ID校验权限。正确做法是在消息体里强制携带租户上下文而且在生产端发送消息的时候就校验当前线程上下文是否有租户信息没有就直接报错不允许裸消息进入队列。消费端收到消息后先解析租户ID再重建租户上下文最后落库。我这里给一个消息体的规范示例你可以直接用在自己的项目里{ eventType: FILE_TRANSCODE_COMPLETE, tenantId: T-202311-0001, traceId: a3f9c2..., payload: { fileId: F-23311, status: SUCCESS } }traceId是为了排查链路用的tenantId是隔离用的payload才是业务数据。我们团队内部要求所有消息体必须包含tenantId和traceId两个字段否则测试环境都过不去。5. 一次租户ID丢失引发的全链路排查定位过程完整复盘这部分我特意单独拿一节出来写因为排查问题时的思路比罗列规范更能让你明白为什么需要兼容这么多细节。事情发生在上线后的第三周现象是管理后台报表里偶尔出现别的租户的数据且只在每天凌晨3点到4点之间出现持续时间不长白天很难复现。5.1 现象观察与问题定性凌晨出现的报表数据串号意味着这不是用户操作引起的而是定时任务或者异步批处理链路出了问题。第一轮我们怀疑定时任务的租户遍历逻辑有误于是把凌晨任务全部停掉结果第二天凌晨问题依然出现说明定时任务不是元凶。接下来怀疑的是异步线程池的上下文丢失。我们检查了所有Async的方法发现报表生成的入口确实在主线程设置了租户上下文但内部有很多并行子任务子任务里没有继承ThreadLocal导致部分子查询没有租户过滤条件。当时我认为这就是根因加了TaskDecorator后台跑了一晚数据依旧串。到这里我开始意识到问题不在线程池而是还有一条完全没走线程池的通路——数据同步Job拉取第三方系统数据时走的是一条独立的数据管道完全没有登录态和租户上下文而是在配置中心读取一个全局默认租户ID然后所有同步数据都落到了这个默认租户下。5.2 通过 traceId 定位真实租户归属当时之所以难以定位是因为我们日常排查依赖日志里的租户ID字段但数据同步管道的日志根本没有打租户ID大家看到一个没有租户的日志就以为是正常系统日志没有潜意识去追查它。后来我们靠两步锁定第一步把凌晨报表涉及的数据用SQL直接按创建时间筛出来发现这些数据都有一个共同特征——create_by字段是系统自动任务system而不是真实用户第二步顺着system用户的操作记录找到数据同步Job的执行日志补齐日志中的租户上下文字段后发现Job初始化时压根没设置租户导致在SQL层的租户拦截器把每条写操作都落到了一个默认租户ID。问题的全貌于是清楚了数据同步Job在多租户改造时被归为非用户触发、天然不依赖租户的一类任务因此没有加入租户上下文初始化逻辑。但它落库的数据是真实的业务数据必须按来源数据本身携带的租户标识去归属而不是不设置租户让拦截器用默认值兜底。5.3 根因修复与边界防守策略修复很简单在Job启动前根据同步任务配置的租户ID初始化上下文。真正有价值的不是修复本身而是接下来的防守策略我们做了三件事强制规则所有写操作在事务提交前必须校验租户字段。我们在ORM框架的拦截器里对INSERT和UPDATE操作做检测如果捕获到租户ID为空的写操作直接抛异常宁可任务失败也不让脏数据落库。这是从源头堵住静默错误。日志规范化所有系统任务日志在开头打印租户上下文快照。有了这个快照随便翻开一条日志就能判断当前任务的租户维度排查效率提高一个量级。数据巡检写一个离线脚本每小时扫一次核心业务表统计租户ID为空或者默认租户ID的数据条数。有异常就告警不用等到客户投诉才发现。这套组合拳打完后续再没出现过类似问题。也推荐你在多租户上线的头一个月每天都跑一遍巡检脚本宁可自己发现小问题也别等客户帮你发现大问题。6. 上线前的适配验证清单从功能到运维的过渡代码写完了集成文档也发了接下来最容易被忽视的就是验证环节。多租户功能因为涉及身份识别、数据隔离、权限边界三层逻辑测试不靠专项用例很难把坑都踩出来。我整理了一份我们每次发版都过一遍的验证清单这里直接分享给你。6.1 研发侧验证场景研发自测阶段这七个场景建议每天跑一次编号验证项判断标准1同一账号切换租户切换后所有接口请求中的租户上下文同步更新不残留旧上下文2A租户的数据B租户不可见以B租户的Token访问A租户的资源ID必须返回403或4043租户头缺失时的行为网关返回明确错误码而不是走默认租户兜底4异步线程池场景并发执行任务时线程池中的子任务上下文与主线程一致5消息队列消费场景消费后落库数据的租户ID与消息头一致6定时任务租户扫描每个租户的多租户资源都单独执行无交叉引用7并发场景下的唯一约束跨租户并发创建相同业务单号不应出现唯一约束冲突这里特别提醒第3项有些团队为了图省事网关层发现租户头缺失时默认用一个“公共租户”这是很危险的做法。公共租户一旦存在就等于给所有未正确传租户的请求留了一个后门。我们后来彻底去掉了默认租户的逻辑宁可报错也不要默认。6.2 运维与交付侧清单多租户不只是研发的事运维和交付同学在新租户入驻时有一套标准的操作步骤否则新租户上线会出各种幺蛾子创建租户基础信息包括租户编码、租户名称、状态、套餐版本写入租户管理表。初始化租户字典与基础配置每个租户使用的模板、通知渠道、权限角色都要生成默认副本。开通资源配额文件存储桶、对象存储路径、消息队列Topic按租户隔离要为新租户创建独立的资源路径。关联集成方如果是第三方系统接入需要生成该租户的独立API凭据或密钥。数据迁移脚本检查如果老客户从单租户环境迁移到多租户平台需要确认迁移后的数据都带上了正确的租户ID不能有遗漏。我们曾经在交付时漏了第4步结果客户的新系统上线后调API一直报“缺少租户维度”的错误排查到半夜才发现管理员后台根本没给这位客户生成独立的集成凭据全平台只有一个测试用的公共密钥。6.3 多租户功能的后续扩展空间写在最后多租户功能一旦立住了后续的很多能力都可以沿着这个边界自然生长出来。比如按租户做数据导出与审计有了租户维度平台合规审计时可以按租户快速导出所有相关数据而不是在全量数据里捞。按租户做用量统计和账单每个租户的API调用量、存储占用、消息条数天然可计量SaaS计费就有数据基础。按租户做灰度发布新功能可以先放给某个租户试用收集反馈后再全量放开这比直接全量发布稳得多。我个人在实际操作中的体会是多租户改造最大的成本不在技术而在于把租户边界是产品的一等公民这件事彻底灌输给参与开发、测试、运维的每一个人。只要有一个环节还沿用单租户时代的假设线上就会出现奇怪的数据串扰。先守住边界再谈功能拓展这句话值得打在每一个相关文档的首页。
