開發(fā)實戰(zhàn)：數(shù)據(jù)隔離、租戶上下文與業(yè)務定制全解析)
我第一次認真研究多租戶不是從概念文檔開始的而是線上出了一個數(shù)據(jù)串租戶的事故。一個接口把A公司的訂單數(shù)據(jù)返回給了B公司雖然只影響了幾個人但那天的排查過程至今難忘。后來做SaaS平臺、做低代碼系統(tǒng)也看過若依的多租戶擴展研究過dify社區(qū)版1.10多租戶的工作空間設計越來越確認一件事不管底層選哪種隔離方案多租戶下的系統(tǒng)業(yè)務開發(fā)都繞不開三個核心問題——數(shù)據(jù)怎么隔、租戶上下文怎么傳、業(yè)務定制怎么做。這篇文章想把這些問題一次說透也把我在實際項目里踩過的坑和沉淀的做法整理出來給正在做多租戶改造或新系統(tǒng)設計的后端開發(fā)、架構(gòu)師一點參考。1. 先搞清楚多租戶到底解決什么問題1.1 從一棟寫字樓說起多租戶最簡單的理解就是多個客戶共同使用同一套系統(tǒng)但彼此看不到對方的數(shù)據(jù)?？梢韵胂蟪稍谝粭潓懽謽抢镛k公電梯、水電、保潔、園區(qū)網(wǎng)絡都是共享的但每家公司的辦公室是獨立的門禁卡只能刷開自己公司的區(qū)域。軟件里的租戶就是這些入駐公司系統(tǒng)實例是整棟樓數(shù)據(jù)是各家的辦公室用戶是樓里的員工員工屬于哪家公司就只能進哪家公司的門。這里特別容易混淆的是“租戶”和“用戶”。租戶是一個組織或業(yè)務空間用戶是自然人一個租戶下可以有多個用戶一個用戶也可能屬于多個租戶。在系統(tǒng)設計里租戶表、用戶表、用戶和租戶的關(guān)聯(lián)表都是基礎數(shù)據(jù)后面講權(quán)限模型時會再展開。1.2 多租戶給業(yè)務開發(fā)增加的三個維度多租戶給業(yè)務開發(fā)增加的維度我歸納成三個數(shù)據(jù)隔離、上下文傳遞、業(yè)務定制。數(shù)據(jù)隔離解決的是“A租戶不能看到B租戶的數(shù)據(jù)”落點是表結(jié)構(gòu)、SQL、緩存、文件存儲上下文傳遞解決的是“一次請求從進入到返回系統(tǒng)始終知道當前是哪個租戶”落點是攔截器、ThreadLocal、網(wǎng)關(guān)Header業(yè)務定制解決的是“不同租戶可以用不同的菜單、字段、參數(shù)、功能開關(guān)”落點是配置體系和擴展點設計。這三個問題不是孤立的。隔離做不好系統(tǒng)隨時可能數(shù)據(jù)泄露上下文傳不好隔離就無從談起定制做得太死租戶就會抱怨系統(tǒng)不好用。多租戶的業(yè)務開發(fā)之所以比普通系統(tǒng)復雜就是因為任何一個業(yè)務模塊都要同時回答“這個數(shù)據(jù)屬于哪個租戶”“當前請求是哪個租戶”“這個租戶要的展示和邏輯是否和別人不同”。1.3 若依和dify里的多租戶形態(tài)其實不太一樣熱門開源項目的多租戶實現(xiàn)可以幫我們理解不同形態(tài)是怎么落地的。例如若依系列做多租戶擴展時最穩(wěn)妥、也最常見的做法是在業(yè)務表增加tenant_id字段配合權(quán)限框架在SQL層做數(shù)據(jù)過濾。它本質(zhì)上屬于共享數(shù)據(jù)庫、共享表的模式好處是改動小、好上手適合快速給企業(yè)項目加租戶能力。dify社區(qū)版到了1.10以后多租戶基本圍繞工作空間workspace展開一個工作空間對應一組資源和成員成員在空間里有不同角色API調(diào)用通過Key識別工作空間。它同樣沒有為每個租戶拆分數(shù)據(jù)庫但用空間概念把用戶、知識庫、應用、文件這些資源串在了一條歸屬鏈上?？催@兩個項目的價值不在于爭論誰的實現(xiàn)更好而在于明白“租戶”并不一定叫公司也可以是工作空間、項目組、門店。關(guān)鍵是找對業(yè)務上的隔離邊界然后把這個邊界貫穿到所有數(shù)據(jù)模型和操作鏈路里。2. 租戶隔離策略選型別一上來就選最重的2.1 三種主流隔離模式對比多租戶系統(tǒng)最底層的決策就是數(shù)據(jù)怎么存。業(yè)內(nèi)一般分成三種模式也可以說是四個層級。我習慣用下面這個表來做團隊內(nèi)部討論隔離模式數(shù)據(jù)存儲方式優(yōu)點缺點典型場景獨立數(shù)據(jù)庫每個租戶一個庫隔離最強恢復和備份清晰成本高運維量大表結(jié)構(gòu)變更要逐庫執(zhí)行金融、醫(yī)療、合規(guī)要求高的場景共享數(shù)據(jù)庫、獨立Schema每個租戶一個Schema隔離中等可單獨遷移和備份連接數(shù)管理復雜跨租戶統(tǒng)計麻煩有一定合規(guī)要求但對成本敏感的B端系統(tǒng)共享數(shù)據(jù)庫、共享表所有租戶同一套表用tenant_id區(qū)分開發(fā)成本最低表結(jié)構(gòu)調(diào)整方便隔離風險高必須靠代碼和規(guī)范兜底SaaS起步期、內(nèi)部系統(tǒng)、工具類平臺還有把共享表按租戶ID范圍做分片或分庫的本質(zhì)上是前兩種的變體。真正動手前建議把四種形態(tài)都畫進評估表逐項打過項目需求再做決定。2.2 按業(yè)務階段選隔離級別很多人一談多租戶第一反應是“每個租戶一個獨立數(shù)據(jù)庫最安全”。從工程上看這不一定是最優(yōu)解。租戶數(shù)量少而單租戶體量大、字段差異極大、數(shù)據(jù)有強合規(guī)隔離要求時獨立庫確實省心但如果客戶是一批剛起步的小公司日活不高每個租戶一個庫會帶來大量空轉(zhuǎn)資源和連接負擔而且表結(jié)構(gòu)修改要逐個庫去遷移開發(fā)效率直線下降。我一般會建議SaaS業(yè)務這樣分階段早期用共享表租戶ID靠SQL層自動過濾和數(shù)據(jù)約束兜底當出現(xiàn)少數(shù)客戶需要強隔離時把這類客戶升級到獨立Schema甚至獨立數(shù)據(jù)庫通過租戶級別路由隔離等客戶規(guī)模再上去再考慮分庫分表。不要為了“未來可能很強隔離”而過度設計多租戶系統(tǒng)的演進空間應該一開始就留好但不必一步到位。2.3 開源項目里的隔離策略參考回到開源項目。若依的多租戶擴展通常以共享表為主核心是在框架的數(shù)據(jù)權(quán)限層增加租戶過濾dify社區(qū)版的多租戶則是用工作空間加成員關(guān)系來建模底層以共享庫為主通過應用數(shù)據(jù)和知識庫等表的歸屬字段完成隔離。兩個項目都不約而同選擇了共享表的起步方案因為對社區(qū)版來說這是成本和易用性之間的平衡點。如果你的業(yè)務正在選型要注意一個容易忽略的問題隔離策略不是只影響存儲還會影響業(yè)務流程。比如獨立庫模式下一個跨租戶的管理員操作要遍歷所有庫共享表模式下管理員反而容易通過單條SQL完成批操作但也要注意別把不同租戶的數(shù)據(jù)掃到一起。選擇隔離級別時要連管理后臺的設計、報表統(tǒng)計、租戶平滑遷移一起考慮。3. 租戶上下文讓業(yè)務代碼不感知租戶的關(guān)鍵3.1 租戶上下文是什么租戶上下文就是當前請求從進入到返回期間“我是誰”的租戶身份標記。它一般是一個租戶ID也可以帶上租戶類型、套餐等級、是否試用等附加信息。沒有上下文的系統(tǒng)查詢時永遠不知道該過濾什么這就是很多項目串租戶的開始。你可以把租戶上下文想象成進入園區(qū)時發(fā)的門禁卡刷卡進樓后到任何一層、任何一個房間系統(tǒng)都能通過這張卡判斷你屬于哪家公司。它必須在進入系統(tǒng)時發(fā)放并在離開時收回否則下一刷可能刷出別人的身份。3.2 請求鏈路里如何傳遞租戶ID最常見的實現(xiàn)方式是在網(wǎng)關(guān)或過濾器層解析請求里的租戶標識。有人習慣放在Header比如X-Tenant-Id有人習慣把它編碼在JWT里也有系統(tǒng)通過域名或子域名區(qū)分租戶。無論哪種落地時都要有一個全局的TenantContext來暫存當前請求的租戶ID。public class TenantContext { private static final ThreadLocalLong TENANT_ID new ThreadLocal(); public static void setTenantId(Long tenantId) { TENANT_ID.set(tenantId); } public static Long getTenantId() { return TENANT_ID.get(); } public static void clear() { TENANT_ID.remove(); } }然后在Filter里設置和清理public class TenantFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest httpRequest (HttpServletRequest) request; try { String tenantId httpRequest.getHeader(X-Tenant-Id); TenantContext.setTenantId(Long.valueOf(tenantId)); chain.doFilter(request, response); } finally { TenantContext.clear(); } } }這里有兩個細節(jié)必須注意第一不要只set不clear否則在線程池復用的容器里下一個請求可能讀到上一個租戶的ID第二公用接口、登錄接口、健康檢查接口要提前放行不能用空的租戶ID去查數(shù)據(jù)。建議在過濾器里做白名單判斷未匹配到的接口直接拒絕。如果是微服務架構(gòu)網(wǎng)關(guān)解析完租戶后要把租戶ID通過Header向下游傳遞下游服務自己也要做一次校驗。別輕信Header里的值至少要做格式校驗和租戶有效性校驗防止構(gòu)造請求模擬其他租戶。3.3 異步任務、消息隊列、定時任務不能丟上下文多租戶上下文在同步請求里很好做麻煩的是線程切換。服務里用線程池處理任務時ThreadLocal默認不會從主線程傳給子線程這會導致異步邏輯里的租戶ID為空。推薦兩種處理方式一種是使用阿里開源的TransmittableThreadLocal做線程池變量的自動傳遞一種是在提交任務時手動把租戶ID傳到任務里在新線程重新設置上下文。手動方式雖然啰嗦但在跨服務、跨系統(tǒng)的場景里更可控。消息隊列消費端也要類似處理。生產(chǎn)者發(fā)送MQ消息時需要把tenantId作為消息頭或業(yè)務字段一并發(fā)送消費者收到消息后在消費邏輯開始前調(diào)用TenantContext.setTenantId設置租戶上下文消費完再清理。定時任務往往是重災區(qū)調(diào)度平臺可以給任務傳參從參數(shù)里取租戶ID一個任務要處理多個租戶就循環(huán)調(diào)用每輪循環(huán)設置一次上下文處理完立刻清理。executor.execute(() - { TenantContext.setTenantId(taskTenantId); try { doBusiness(); } finally { TenantContext.clear(); } });4. 數(shù)據(jù)隔離落到SQL層自動改寫與強制兜底4.1 別讓業(yè)務代碼手寫tenant_id一些團隊早期用最樸素的方式做隔離每個Mapper的SQL都手動加and tenant_id#{tenantId}。業(yè)務少的時候還能應付業(yè)務一多只要一個開發(fā)忘記加或者多個WHERE條件拼接順序出錯就會產(chǎn)生一個巨大的數(shù)據(jù)漏洞。手寫tenant_id最大的風險不在寫錯而在“漏寫”。人不可能在每個查詢里都保持同樣的警醒。所以要靠框架層面把租戶過濾變成“默認行為”業(yè)務代碼里盡量不出現(xiàn)tenant_id讓它在ORM層自動拼接。這既能減少代碼噪音又能降低漏加條件的事故率。如果團隊用的是MyBatis-Plus推薦直接用官方提供的TenantLineInnerInterceptor它的邏輯就是自動把租戶條件拼到需要執(zhí)行的SQL上。4.2 自動填充租戶ID與SQL自動改寫配合自動過濾寫入時的租戶ID也要自動填充。MyBatis-Plus里可以通過MetaObjectHandler實現(xiàn)Component public class MyMetaObjectHandler implements MetaObjectHandler { Override public void insertFill(MetaObject metaObject) { Long tenantId TenantContext.getTenantId(); this.strictInsertFill(metaObject, tenantId, Long.class, tenantId); } Override public void updateFill(MetaObject metaObject) { this.strictUpdateFill(metaObject, updateTime, LocalDateTime.class, LocalDateTime.now()); } }此外再注冊租戶SQL攔截器Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new TenantLineInnerInterceptor(new TenantLineHandler() { Override public Expression getTenantId() { return new LongValue(TenantContext.getTenantId()); } Override public String getTenantIdColumn() { return tenant_id; } Override public boolean ignoreTable(String tableName) { return sys_config.equals(tableName) || sys_dict.equals(tableName); } })); return interceptor; }我建議對全表默認開啟租戶過濾只有明確標注的系統(tǒng)配置表、全局數(shù)據(jù)字典、公共服務表才放進ignoreTable白名單。白名單一定是“最小集”而不是為了省事把所有表都忽略。對于必須忽略租戶過濾的Mapper方法可以用注解明確聲明做到每次忽略都有據(jù)可查。還需要注意一個細節(jié)自動改寫SQL雖然方便但遇到子查詢、join、union時容易出錯。攔截器能否正確處理取決于框架實現(xiàn)所以不要以為配好了就萬事大吉必須在壓測和測試用例里覆蓋多表關(guān)聯(lián)場景。復雜SQL寧可拆成多次查詢也不要在一條SQL里繞暈攔截器。4.3 表設計與索引里的租戶維度既然以tenant_id作為隔離標志表設計時就要把它當作一等公民。所有業(yè)務主表、明細表、日志表都要有tenant_id字段并且和業(yè)務唯一鍵一起建唯一索引。例如租戶內(nèi)的訂單流水號不能重復若無腦地給order_no建唯一索引兩個租戶都生成單號ORDER-001第二個插入就直接報唯一鍵沖突改成tenant_idorder_no組合唯一索引才符合業(yè)務語義。涉及統(tǒng)計報表時常用條件往往是tenant_id時間范圍索引設計也要考慮這個組合。可以建立一個復合索引tenant_id created_at讓租戶過濾先行。數(shù)據(jù)庫的查詢計劃設計得越好多租戶場景下的資源搶占就越可控。另外建議把視圖、存儲過程也納入租戶過濾設計如果是動態(tài)拼接SQL的報表系統(tǒng)要額外小心避免租戶ID只作用在第一層子查詢。這個環(huán)節(jié)最容易出的問題是“只給主表加tenant_id關(guān)聯(lián)子表忘了加”。一個訂單頭帶訂單明細訂單頭有租戶ID訂單明細沒有通過主表關(guān)聯(lián)還好一旦把明細表單獨拉出來統(tǒng)計數(shù)據(jù)就串了。經(jīng)驗做法是所有業(yè)務表都帶tenant_id不依賴join父表來推斷歸屬。5. 多租戶下的業(yè)務定制權(quán)限、菜單、字段擴展5.1 用戶、租戶、角色是什么關(guān)系多租戶系統(tǒng)的權(quán)限模型我強烈建議采用“用戶全局唯一租戶內(nèi)分配角色”的結(jié)構(gòu)。也就是說一個用戶名可以在系統(tǒng)里注冊一次但TA在不同租戶里可以有不同角色。若依的權(quán)限模型偏“用戶-部門-角色”加上多租戶后要處理的是“用戶屬于哪個租戶再在租戶內(nèi)維護部門、角色和菜單權(quán)限”dify的模型則是賬號加工作空間成員賬號全局唯一在工作空間內(nèi)分owner/editor等角色。兩者的共同點在于租戶和用戶是多對多關(guān)系必須用關(guān)聯(lián)表承載。因此基礎表至少要包含tenant租戶、user用戶、tenant_member租戶成員、role角色、permission權(quán)限、tenant_role租戶角色關(guān)聯(lián)。業(yè)務代碼在判斷權(quán)限時不能只問“用戶有沒有這個權(quán)限”還要問“用戶在當前租戶下有沒有這個權(quán)限”。很多越權(quán)漏洞就是因為只校驗了角色權(quán)限沒有校驗租戶上下文的歸屬關(guān)系。5.2 租戶級菜單、字典和參數(shù)配置不同租戶要的菜單結(jié)構(gòu)、首頁皮膚、流程模板往往不一樣。如果每個租戶都復制一份配置后續(xù)系統(tǒng)升級就要逐租戶改維護量驚人。更推薦“默認配置租戶覆蓋”的方式。以菜單為例系統(tǒng)級菜單表里tenant_id為空表示通用菜單tenant_id有值表示該租戶的定制菜單業(yè)務加載菜單時先查該租戶的定制菜單再合并通用菜單。這樣能覆蓋80%的租戶差異又不用為每個租戶建表。數(shù)據(jù)字典、參數(shù)配置也可以做同樣的設計查詢時優(yōu)先取租戶ID匹配的那一行取不到再取租戶ID為空的那一行。注意要控制默認為空還是租戶覆蓋最好在配置中顯式指定否則代碼里到處是if (tenantValue ! null ? tenantValue : globalValue)可讀性會很差。做一個通用配置查詢工具類一行方法拿到最終的解析值所有業(yè)務模塊復用。5.3 字段級擴展和功能開關(guān)怎么做租戶A要記客戶生日租戶B要記客戶VIP等級這種字段差異幾乎每個SaaS項目都會遇到。我的建議是分三個檔次。低層是預留幾個通用擴展字段比如ext1到ext5臨時頂一下中層是主表加一個JSON字段把不確定的擴展屬性放進去高層是真正的擴展子表每行是tenant_id業(yè)務主鍵字段名字段值。三者的取舍是擴展字段最簡單但有上限JSON列最靈活但查詢統(tǒng)計困難擴展子表最正規(guī)但開發(fā)量最大。功能開關(guān)也是租戶定制的重要部分。可以在參數(shù)配置表里存一組布爾值例如是否開啟多級審批、是否顯示庫存預警、是否支持會員積分。業(yè)務代碼里通過配置服務讀取這些開關(guān)而不是用一堆if判斷租戶ID。這樣運營人員可以在后臺單獨配置某個租戶的功能不需要發(fā)版。這里的關(guān)鍵是功能開關(guān)的變化要能及時刷新緩存里一般要把tenantId作為鍵的一部分避免租戶之間串配置。6. 多租戶開發(fā)中常見的坑與排查實錄6.1 數(shù)據(jù)串租戶的典型現(xiàn)場這里寫一個真實復盤。當時系統(tǒng)上線第二天客服收到B租戶反饋在列表里看到了一批明顯不屬于自己的訂單號。我第一時間查了操作日志和接口參數(shù)發(fā)現(xiàn)請求的租戶ID沒問題過濾條件也沒問題問題出在報表查詢里用了一條手寫SQL只按org_id關(guān)聯(lián)完全沒帶tenant_id。這個場景非常典型手寫SQL繞過框架攔截或者關(guān)聯(lián)子表時依賴父表隔離導致漏網(wǎng)之魚。修復步驟是第一立即下線問題報表第二在原SQL補上租戶條件短期內(nèi)止血第三排查所有類似手寫SQL看是否有同樣的漏過濾第四在租戶SQL攔截器里把關(guān)鍵業(yè)務表加進強制處理表禁止使用忽略注解。更重要的是在測試環(huán)境中構(gòu)造兩個租戶的數(shù)據(jù)編寫“租戶A查詢不到租戶B數(shù)據(jù)”的用例把這類回歸測試納入CI。6.2 ThreadLocal泄漏與線程池復用另一個高頻問題是ThreadLocal在不同請求間串數(shù)據(jù)。典型場景容器線程池里執(zhí)行完A租戶請求后沒有清理線程被還給池子下一個B租戶請求復用這個線程時TenantContext.getTenantId()返回的還是A的ID于是B租戶的數(shù)據(jù)查詢?nèi)贿^濾成了A租戶的數(shù)據(jù)表現(xiàn)就是“數(shù)據(jù)越查越少”或“部分功能空白”。排查要點是看日志里有沒有租戶ID和登錄用戶ID不匹配的記錄或者在過濾器中加一條調(diào)試日志每次請求結(jié)束打印線程名和租戶ID。解決方法很明確過濾器的finally塊里統(tǒng)一調(diào)用TenantContext.clear()線程池提交任務時顯式傳租戶參數(shù)不依賴隱式傳遞。只要做到“請求結(jié)束必清理線程切換必傳參”這類問題基本能根除。6.3 緩存、MQ、定時任務的租戶隔離緩存是另一個容易忽略的地方。如果Redis的key只寫成order:detail:1001兩個租戶只要業(yè)務ID相同就會相互覆蓋。經(jīng)驗做法是所有業(yè)務緩存key都要帶上租戶ID比如tenant:123:order:detail:1001。CacheManager或RedisTemplate層面可以做KeyGenerator的邏輯但最保險的還是業(yè)務代碼中強制遵守key命名規(guī)范。MQ消息必須攜帶租戶ID并且消費邏輯里像請求一樣設置租戶上下文。定時任務特殊之處在于沒有外部請求必須從任務參數(shù)或數(shù)據(jù)庫中讀取要處理的租戶列表然后逐個設置上下文去跑。之前我遇到過一個統(tǒng)計任務把本來應該匯總整個租戶的數(shù)據(jù)由于缺失租戶上下文的設置統(tǒng)計到了全局默認租戶最后報表數(shù)據(jù)全錯。給定時任務增加租戶維度的日志能顯著提高排查效率。6.4 多租戶問題速查表場景可能原因排查方向解決方案列表數(shù)據(jù)串租戶手寫SQL漏tenant_id關(guān)聯(lián)子表未過濾查MyBatis SQL日志確認是否存在不帶tenant_id的SQL啟用ORM層自動改寫刪除固定忽略名單A租戶請求查不到任何數(shù)據(jù)ThreadLocal中租戶ID為殘留舊值或空值在過濾器入口和出口打印租戶IDfinally清理校驗非法租戶ID不同租戶參數(shù)互相覆蓋緩存key沒有租戶維度查看Redis key確認是否共用前綴key加入tenant_id配置查詢結(jié)果按租戶隔離異步任務里數(shù)據(jù)越權(quán)或丟失線程池沒有傳遞上下文排查異步方法getTenantId()是否為空使用TransmittableThreadLocal或手動傳參定時任務統(tǒng)計錯誤任務未按租戶循環(huán)設置上下文檢查任務日志中的租戶ID任務參數(shù)傳遞租戶列表循環(huán)設置并clear做多租戶系統(tǒng)這幾年我最大的體會是技術(shù)方案可以逐步演進但上下文傳遞和SQL層兜底這兩件事必須從第一天就做好。等業(yè)務量起來后再補排查成本會指數(shù)級上升。另一個實用建議是建立一套多租戶回歸用例集每次發(fā)版前用兩個虛擬租戶的數(shù)據(jù)跑一遍關(guān)鍵鏈路把“數(shù)據(jù)串租戶”變成測試階段就能發(fā)現(xiàn)的問題而不是線上事故。多租戶本質(zhì)上并不神秘它要求的只是把“邊界意識”內(nèi)化到每一張表、每一條SQL、每一個異步任務里。希望這些踩坑經(jīng)驗能讓你少走幾步彎路。 多租戶系統(tǒng)開發(fā)實戰(zhàn)：數(shù)據(jù)隔離、租戶上下文與業(yè)務定制全解析
我第一次認真研究多租戶不是從概念文檔開始的而是線上出了一個數(shù)據(jù)串租戶的事故。一個接口把A公司的訂單數(shù)據(jù)返回給了B公司雖然只影響了幾個人但那天的排查過程至今難忘。后來做SaaS平臺、做低代碼系統(tǒng)也看過若依的多租戶擴展研究過dify社區(qū)版1.10多租戶的工作空間設計越來越確認一件事不管底層選哪種隔離方案多租戶下的系統(tǒng)業(yè)務開發(fā)都繞不開三個核心問題——數(shù)據(jù)怎么隔、租戶上下文怎么傳、業(yè)務定制怎么做。這篇文章想把這些問題一次說透也把我在實際項目里踩過的坑和沉淀的做法整理出來給正在做多租戶改造或新系統(tǒng)設計的后端開發(fā)、架構(gòu)師一點參考。1. 先搞清楚多租戶到底解決什么問題1.1 從一棟寫字樓說起多租戶最簡單的理解就是多個客戶共同使用同一套系統(tǒng)但彼此看不到對方的數(shù)據(jù)?？梢韵胂蟪稍谝粭潓懽謽抢镛k公電梯、水電、保潔、園區(qū)網(wǎng)絡都是共享的但每家公司的辦公室是獨立的門禁卡只能刷開自己公司的區(qū)域。軟件里的租戶就是這些入駐公司系統(tǒng)實例是整棟樓數(shù)據(jù)是各家的辦公室用戶是樓里的員工員工屬于哪家公司就只能進哪家公司的門。這里特別容易混淆的是“租戶”和“用戶”。租戶是一個組織或業(yè)務空間用戶是自然人一個租戶下可以有多個用戶一個用戶也可能屬于多個租戶。在系統(tǒng)設計里租戶表、用戶表、用戶和租戶的關(guān)聯(lián)表都是基礎數(shù)據(jù)后面講權(quán)限模型時會再展開。1.2 多租戶給業(yè)務開發(fā)增加的三個維度多租戶給業(yè)務開發(fā)增加的維度我歸納成三個數(shù)據(jù)隔離、上下文傳遞、業(yè)務定制。數(shù)據(jù)隔離解決的是“A租戶不能看到B租戶的數(shù)據(jù)”落點是表結(jié)構(gòu)、SQL、緩存、文件存儲上下文傳遞解決的是“一次請求從進入到返回系統(tǒng)始終知道當前是哪個租戶”落點是攔截器、ThreadLocal、網(wǎng)關(guān)Header業(yè)務定制解決的是“不同租戶可以用不同的菜單、字段、參數(shù)、功能開關(guān)”落點是配置體系和擴展點設計。這三個問題不是孤立的。隔離做不好系統(tǒng)隨時可能數(shù)據(jù)泄露上下文傳不好隔離就無從談起定制做得太死租戶就會抱怨系統(tǒng)不好用。多租戶的業(yè)務開發(fā)之所以比普通系統(tǒng)復雜就是因為任何一個業(yè)務模塊都要同時回答“這個數(shù)據(jù)屬于哪個租戶”“當前請求是哪個租戶”“這個租戶要的展示和邏輯是否和別人不同”。1.3 若依和dify里的多租戶形態(tài)其實不太一樣熱門開源項目的多租戶實現(xiàn)可以幫我們理解不同形態(tài)是怎么落地的。例如若依系列做多租戶擴展時最穩(wěn)妥、也最常見的做法是在業(yè)務表增加tenant_id字段配合權(quán)限框架在SQL層做數(shù)據(jù)過濾。它本質(zhì)上屬于共享數(shù)據(jù)庫、共享表的模式好處是改動小、好上手適合快速給企業(yè)項目加租戶能力。dify社區(qū)版到了1.10以后多租戶基本圍繞工作空間workspace展開一個工作空間對應一組資源和成員成員在空間里有不同角色API調(diào)用通過Key識別工作空間。它同樣沒有為每個租戶拆分數(shù)據(jù)庫但用空間概念把用戶、知識庫、應用、文件這些資源串在了一條歸屬鏈上?？催@兩個項目的價值不在于爭論誰的實現(xiàn)更好而在于明白“租戶”并不一定叫公司也可以是工作空間、項目組、門店。關(guān)鍵是找對業(yè)務上的隔離邊界然后把這個邊界貫穿到所有數(shù)據(jù)模型和操作鏈路里。2. 租戶隔離策略選型別一上來就選最重的2.1 三種主流隔離模式對比多租戶系統(tǒng)最底層的決策就是數(shù)據(jù)怎么存。業(yè)內(nèi)一般分成三種模式也可以說是四個層級。我習慣用下面這個表來做團隊內(nèi)部討論隔離模式數(shù)據(jù)存儲方式優(yōu)點缺點典型場景獨立數(shù)據(jù)庫每個租戶一個庫隔離最強恢復和備份清晰成本高運維量大表結(jié)構(gòu)變更要逐庫執(zhí)行金融、醫(yī)療、合規(guī)要求高的場景共享數(shù)據(jù)庫、獨立Schema每個租戶一個Schema隔離中等可單獨遷移和備份連接數(shù)管理復雜跨租戶統(tǒng)計麻煩有一定合規(guī)要求但對成本敏感的B端系統(tǒng)共享數(shù)據(jù)庫、共享表所有租戶同一套表用tenant_id區(qū)分開發(fā)成本最低表結(jié)構(gòu)調(diào)整方便隔離風險高必須靠代碼和規(guī)范兜底SaaS起步期、內(nèi)部系統(tǒng)、工具類平臺還有把共享表按租戶ID范圍做分片或分庫的本質(zhì)上是前兩種的變體。真正動手前建議把四種形態(tài)都畫進評估表逐項打過項目需求再做決定。2.2 按業(yè)務階段選隔離級別很多人一談多租戶第一反應是“每個租戶一個獨立數(shù)據(jù)庫最安全”。從工程上看這不一定是最優(yōu)解。租戶數(shù)量少而單租戶體量大、字段差異極大、數(shù)據(jù)有強合規(guī)隔離要求時獨立庫確實省心但如果客戶是一批剛起步的小公司日活不高每個租戶一個庫會帶來大量空轉(zhuǎn)資源和連接負擔而且表結(jié)構(gòu)修改要逐個庫去遷移開發(fā)效率直線下降。我一般會建議SaaS業(yè)務這樣分階段早期用共享表租戶ID靠SQL層自動過濾和數(shù)據(jù)約束兜底當出現(xiàn)少數(shù)客戶需要強隔離時把這類客戶升級到獨立Schema甚至獨立數(shù)據(jù)庫通過租戶級別路由隔離等客戶規(guī)模再上去再考慮分庫分表。不要為了“未來可能很強隔離”而過度設計多租戶系統(tǒng)的演進空間應該一開始就留好但不必一步到位。2.3 開源項目里的隔離策略參考回到開源項目。若依的多租戶擴展通常以共享表為主核心是在框架的數(shù)據(jù)權(quán)限層增加租戶過濾dify社區(qū)版的多租戶則是用工作空間加成員關(guān)系來建模底層以共享庫為主通過應用數(shù)據(jù)和知識庫等表的歸屬字段完成隔離。兩個項目都不約而同選擇了共享表的起步方案因為對社區(qū)版來說這是成本和易用性之間的平衡點。如果你的業(yè)務正在選型要注意一個容易忽略的問題隔離策略不是只影響存儲還會影響業(yè)務流程。比如獨立庫模式下一個跨租戶的管理員操作要遍歷所有庫共享表模式下管理員反而容易通過單條SQL完成批操作但也要注意別把不同租戶的數(shù)據(jù)掃到一起。選擇隔離級別時要連管理后臺的設計、報表統(tǒng)計、租戶平滑遷移一起考慮。3. 租戶上下文讓業(yè)務代碼不感知租戶的關(guān)鍵3.1 租戶上下文是什么租戶上下文就是當前請求從進入到返回期間“我是誰”的租戶身份標記。它一般是一個租戶ID也可以帶上租戶類型、套餐等級、是否試用等附加信息。沒有上下文的系統(tǒng)查詢時永遠不知道該過濾什么這就是很多項目串租戶的開始。你可以把租戶上下文想象成進入園區(qū)時發(fā)的門禁卡刷卡進樓后到任何一層、任何一個房間系統(tǒng)都能通過這張卡判斷你屬于哪家公司。它必須在進入系統(tǒng)時發(fā)放并在離開時收回否則下一刷可能刷出別人的身份。3.2 請求鏈路里如何傳遞租戶ID最常見的實現(xiàn)方式是在網(wǎng)關(guān)或過濾器層解析請求里的租戶標識。有人習慣放在Header比如X-Tenant-Id有人習慣把它編碼在JWT里也有系統(tǒng)通過域名或子域名區(qū)分租戶。無論哪種落地時都要有一個全局的TenantContext來暫存當前請求的租戶ID。public class TenantContext { private static final ThreadLocalLong TENANT_ID new ThreadLocal(); public static void setTenantId(Long tenantId) { TENANT_ID.set(tenantId); } public static Long getTenantId() { return TENANT_ID.get(); } public static void clear() { TENANT_ID.remove(); } }然后在Filter里設置和清理public class TenantFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest httpRequest (HttpServletRequest) request; try { String tenantId httpRequest.getHeader(X-Tenant-Id); TenantContext.setTenantId(Long.valueOf(tenantId)); chain.doFilter(request, response); } finally { TenantContext.clear(); } } }這里有兩個細節(jié)必須注意第一不要只set不clear否則在線程池復用的容器里下一個請求可能讀到上一個租戶的ID第二公用接口、登錄接口、健康檢查接口要提前放行不能用空的租戶ID去查數(shù)據(jù)。建議在過濾器里做白名單判斷未匹配到的接口直接拒絕。如果是微服務架構(gòu)網(wǎng)關(guān)解析完租戶后要把租戶ID通過Header向下游傳遞下游服務自己也要做一次校驗。別輕信Header里的值至少要做格式校驗和租戶有效性校驗防止構(gòu)造請求模擬其他租戶。3.3 異步任務、消息隊列、定時任務不能丟上下文多租戶上下文在同步請求里很好做麻煩的是線程切換。服務里用線程池處理任務時ThreadLocal默認不會從主線程傳給子線程這會導致異步邏輯里的租戶ID為空。推薦兩種處理方式一種是使用阿里開源的TransmittableThreadLocal做線程池變量的自動傳遞一種是在提交任務時手動把租戶ID傳到任務里在新線程重新設置上下文。手動方式雖然啰嗦但在跨服務、跨系統(tǒng)的場景里更可控。消息隊列消費端也要類似處理。生產(chǎn)者發(fā)送MQ消息時需要把tenantId作為消息頭或業(yè)務字段一并發(fā)送消費者收到消息后在消費邏輯開始前調(diào)用TenantContext.setTenantId設置租戶上下文消費完再清理。定時任務往往是重災區(qū)調(diào)度平臺可以給任務傳參從參數(shù)里取租戶ID一個任務要處理多個租戶就循環(huán)調(diào)用每輪循環(huán)設置一次上下文處理完立刻清理。executor.execute(() - { TenantContext.setTenantId(taskTenantId); try { doBusiness(); } finally { TenantContext.clear(); } });4. 數(shù)據(jù)隔離落到SQL層自動改寫與強制兜底4.1 別讓業(yè)務代碼手寫tenant_id一些團隊早期用最樸素的方式做隔離每個Mapper的SQL都手動加and tenant_id#{tenantId}。業(yè)務少的時候還能應付業(yè)務一多只要一個開發(fā)忘記加或者多個WHERE條件拼接順序出錯就會產(chǎn)生一個巨大的數(shù)據(jù)漏洞。手寫tenant_id最大的風險不在寫錯而在“漏寫”。人不可能在每個查詢里都保持同樣的警醒。所以要靠框架層面把租戶過濾變成“默認行為”業(yè)務代碼里盡量不出現(xiàn)tenant_id讓它在ORM層自動拼接。這既能減少代碼噪音又能降低漏加條件的事故率。如果團隊用的是MyBatis-Plus推薦直接用官方提供的TenantLineInnerInterceptor它的邏輯就是自動把租戶條件拼到需要執(zhí)行的SQL上。4.2 自動填充租戶ID與SQL自動改寫配合自動過濾寫入時的租戶ID也要自動填充。MyBatis-Plus里可以通過MetaObjectHandler實現(xiàn)Component public class MyMetaObjectHandler implements MetaObjectHandler { Override public void insertFill(MetaObject metaObject) { Long tenantId TenantContext.getTenantId(); this.strictInsertFill(metaObject, tenantId, Long.class, tenantId); } Override public void updateFill(MetaObject metaObject) { this.strictUpdateFill(metaObject, updateTime, LocalDateTime.class, LocalDateTime.now()); } }此外再注冊租戶SQL攔截器Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new TenantLineInnerInterceptor(new TenantLineHandler() { Override public Expression getTenantId() { return new LongValue(TenantContext.getTenantId()); } Override public String getTenantIdColumn() { return tenant_id; } Override public boolean ignoreTable(String tableName) { return sys_config.equals(tableName) || sys_dict.equals(tableName); } })); return interceptor; }我建議對全表默認開啟租戶過濾只有明確標注的系統(tǒng)配置表、全局數(shù)據(jù)字典、公共服務表才放進ignoreTable白名單。白名單一定是“最小集”而不是為了省事把所有表都忽略。對于必須忽略租戶過濾的Mapper方法可以用注解明確聲明做到每次忽略都有據(jù)可查。還需要注意一個細節(jié)自動改寫SQL雖然方便但遇到子查詢、join、union時容易出錯。攔截器能否正確處理取決于框架實現(xiàn)所以不要以為配好了就萬事大吉必須在壓測和測試用例里覆蓋多表關(guān)聯(lián)場景。復雜SQL寧可拆成多次查詢也不要在一條SQL里繞暈攔截器。4.3 表設計與索引里的租戶維度既然以tenant_id作為隔離標志表設計時就要把它當作一等公民。所有業(yè)務主表、明細表、日志表都要有tenant_id字段并且和業(yè)務唯一鍵一起建唯一索引。例如租戶內(nèi)的訂單流水號不能重復若無腦地給order_no建唯一索引兩個租戶都生成單號ORDER-001第二個插入就直接報唯一鍵沖突改成tenant_idorder_no組合唯一索引才符合業(yè)務語義。涉及統(tǒng)計報表時常用條件往往是tenant_id時間范圍索引設計也要考慮這個組合。可以建立一個復合索引tenant_id created_at讓租戶過濾先行。數(shù)據(jù)庫的查詢計劃設計得越好多租戶場景下的資源搶占就越可控。另外建議把視圖、存儲過程也納入租戶過濾設計如果是動態(tài)拼接SQL的報表系統(tǒng)要額外小心避免租戶ID只作用在第一層子查詢。這個環(huán)節(jié)最容易出的問題是“只給主表加tenant_id關(guān)聯(lián)子表忘了加”。一個訂單頭帶訂單明細訂單頭有租戶ID訂單明細沒有通過主表關(guān)聯(lián)還好一旦把明細表單獨拉出來統(tǒng)計數(shù)據(jù)就串了。經(jīng)驗做法是所有業(yè)務表都帶tenant_id不依賴join父表來推斷歸屬。5. 多租戶下的業(yè)務定制權(quán)限、菜單、字段擴展5.1 用戶、租戶、角色是什么關(guān)系多租戶系統(tǒng)的權(quán)限模型我強烈建議采用“用戶全局唯一租戶內(nèi)分配角色”的結(jié)構(gòu)。也就是說一個用戶名可以在系統(tǒng)里注冊一次但TA在不同租戶里可以有不同角色。若依的權(quán)限模型偏“用戶-部門-角色”加上多租戶后要處理的是“用戶屬于哪個租戶再在租戶內(nèi)維護部門、角色和菜單權(quán)限”dify的模型則是賬號加工作空間成員賬號全局唯一在工作空間內(nèi)分owner/editor等角色。兩者的共同點在于租戶和用戶是多對多關(guān)系必須用關(guān)聯(lián)表承載。因此基礎表至少要包含tenant租戶、user用戶、tenant_member租戶成員、role角色、permission權(quán)限、tenant_role租戶角色關(guān)聯(lián)。業(yè)務代碼在判斷權(quán)限時不能只問“用戶有沒有這個權(quán)限”還要問“用戶在當前租戶下有沒有這個權(quán)限”。很多越權(quán)漏洞就是因為只校驗了角色權(quán)限沒有校驗租戶上下文的歸屬關(guān)系。5.2 租戶級菜單、字典和參數(shù)配置不同租戶要的菜單結(jié)構(gòu)、首頁皮膚、流程模板往往不一樣。如果每個租戶都復制一份配置后續(xù)系統(tǒng)升級就要逐租戶改維護量驚人。更推薦“默認配置租戶覆蓋”的方式。以菜單為例系統(tǒng)級菜單表里tenant_id為空表示通用菜單tenant_id有值表示該租戶的定制菜單業(yè)務加載菜單時先查該租戶的定制菜單再合并通用菜單。這樣能覆蓋80%的租戶差異又不用為每個租戶建表。數(shù)據(jù)字典、參數(shù)配置也可以做同樣的設計查詢時優(yōu)先取租戶ID匹配的那一行取不到再取租戶ID為空的那一行。注意要控制默認為空還是租戶覆蓋最好在配置中顯式指定否則代碼里到處是if (tenantValue ! null ? tenantValue : globalValue)可讀性會很差。做一個通用配置查詢工具類一行方法拿到最終的解析值所有業(yè)務模塊復用。5.3 字段級擴展和功能開關(guān)怎么做租戶A要記客戶生日租戶B要記客戶VIP等級這種字段差異幾乎每個SaaS項目都會遇到。我的建議是分三個檔次。低層是預留幾個通用擴展字段比如ext1到ext5臨時頂一下中層是主表加一個JSON字段把不確定的擴展屬性放進去高層是真正的擴展子表每行是tenant_id業(yè)務主鍵字段名字段值。三者的取舍是擴展字段最簡單但有上限JSON列最靈活但查詢統(tǒng)計困難擴展子表最正規(guī)但開發(fā)量最大。功能開關(guān)也是租戶定制的重要部分。可以在參數(shù)配置表里存一組布爾值例如是否開啟多級審批、是否顯示庫存預警、是否支持會員積分。業(yè)務代碼里通過配置服務讀取這些開關(guān)而不是用一堆if判斷租戶ID。這樣運營人員可以在后臺單獨配置某個租戶的功能不需要發(fā)版。這里的關(guān)鍵是功能開關(guān)的變化要能及時刷新緩存里一般要把tenantId作為鍵的一部分避免租戶之間串配置。6. 多租戶開發(fā)中常見的坑與排查實錄6.1 數(shù)據(jù)串租戶的典型現(xiàn)場這里寫一個真實復盤。當時系統(tǒng)上線第二天客服收到B租戶反饋在列表里看到了一批明顯不屬于自己的訂單號。我第一時間查了操作日志和接口參數(shù)發(fā)現(xiàn)請求的租戶ID沒問題過濾條件也沒問題問題出在報表查詢里用了一條手寫SQL只按org_id關(guān)聯(lián)完全沒帶tenant_id。這個場景非常典型手寫SQL繞過框架攔截或者關(guān)聯(lián)子表時依賴父表隔離導致漏網(wǎng)之魚。修復步驟是第一立即下線問題報表第二在原SQL補上租戶條件短期內(nèi)止血第三排查所有類似手寫SQL看是否有同樣的漏過濾第四在租戶SQL攔截器里把關(guān)鍵業(yè)務表加進強制處理表禁止使用忽略注解。更重要的是在測試環(huán)境中構(gòu)造兩個租戶的數(shù)據(jù)編寫“租戶A查詢不到租戶B數(shù)據(jù)”的用例把這類回歸測試納入CI。6.2 ThreadLocal泄漏與線程池復用另一個高頻問題是ThreadLocal在不同請求間串數(shù)據(jù)。典型場景容器線程池里執(zhí)行完A租戶請求后沒有清理線程被還給池子下一個B租戶請求復用這個線程時TenantContext.getTenantId()返回的還是A的ID于是B租戶的數(shù)據(jù)查詢?nèi)贿^濾成了A租戶的數(shù)據(jù)表現(xiàn)就是“數(shù)據(jù)越查越少”或“部分功能空白”。排查要點是看日志里有沒有租戶ID和登錄用戶ID不匹配的記錄或者在過濾器中加一條調(diào)試日志每次請求結(jié)束打印線程名和租戶ID。解決方法很明確過濾器的finally塊里統(tǒng)一調(diào)用TenantContext.clear()線程池提交任務時顯式傳租戶參數(shù)不依賴隱式傳遞。只要做到“請求結(jié)束必清理線程切換必傳參”這類問題基本能根除。6.3 緩存、MQ、定時任務的租戶隔離緩存是另一個容易忽略的地方。如果Redis的key只寫成order:detail:1001兩個租戶只要業(yè)務ID相同就會相互覆蓋。經(jīng)驗做法是所有業(yè)務緩存key都要帶上租戶ID比如tenant:123:order:detail:1001。CacheManager或RedisTemplate層面可以做KeyGenerator的邏輯但最保險的還是業(yè)務代碼中強制遵守key命名規(guī)范。MQ消息必須攜帶租戶ID并且消費邏輯里像請求一樣設置租戶上下文。定時任務特殊之處在于沒有外部請求必須從任務參數(shù)或數(shù)據(jù)庫中讀取要處理的租戶列表然后逐個設置上下文去跑。之前我遇到過一個統(tǒng)計任務把本來應該匯總整個租戶的數(shù)據(jù)由于缺失租戶上下文的設置統(tǒng)計到了全局默認租戶最后報表數(shù)據(jù)全錯。給定時任務增加租戶維度的日志能顯著提高排查效率。6.4 多租戶問題速查表場景可能原因排查方向解決方案列表數(shù)據(jù)串租戶手寫SQL漏tenant_id關(guān)聯(lián)子表未過濾查MyBatis SQL日志確認是否存在不帶tenant_id的SQL啟用ORM層自動改寫刪除固定忽略名單A租戶請求查不到任何數(shù)據(jù)ThreadLocal中租戶ID為殘留舊值或空值在過濾器入口和出口打印租戶IDfinally清理校驗非法租戶ID不同租戶參數(shù)互相覆蓋緩存key沒有租戶維度查看Redis key確認是否共用前綴key加入tenant_id配置查詢結(jié)果按租戶隔離異步任務里數(shù)據(jù)越權(quán)或丟失線程池沒有傳遞上下文排查異步方法getTenantId()是否為空使用TransmittableThreadLocal或手動傳參定時任務統(tǒng)計錯誤任務未按租戶循環(huán)設置上下文檢查任務日志中的租戶ID任務參數(shù)傳遞租戶列表循環(huán)設置并clear做多租戶系統(tǒng)這幾年我最大的體會是技術(shù)方案可以逐步演進但上下文傳遞和SQL層兜底這兩件事必須從第一天就做好。等業(yè)務量起來后再補排查成本會指數(shù)級上升。另一個實用建議是建立一套多租戶回歸用例集每次發(fā)版前用兩個虛擬租戶的數(shù)據(jù)跑一遍關(guān)鍵鏈路把“數(shù)據(jù)串租戶”變成測試階段就能發(fā)現(xiàn)的問題而不是線上事故。多租戶本質(zhì)上并不神秘它要求的只是把“邊界意識”內(nèi)化到每一張表、每一條SQL、每一個異步任務里。希望這些踩坑經(jīng)驗能讓你少走幾步彎路。