SaaS架构设计实战：多租户隔离、计费建模与扩展性避坑指南

简介：这份《SaaS+架构设计》PDF文档面向希望系统掌握SaaS架构原理与实践的开发者、架构师及技术学习者，围绕多租户系统从需求分析到性能优化的完整设计链路展开。内容涵盖SaaS成熟度模型四级分级、RUP“4+1”视图模式（场景、逻辑、开发、过程、物理视图）、MDA模型驱动架构，以及系统级与程序级安全性设计、多租户数据存储的三种方案（独立数据库、共享数据库隔离数据架构、共享数据库共享数据架构）等核心议题。文档还深入讲解数据库层索引优化与消除大表连接、应用层缓存与日志记录、数据加密算法，以及云计算网络性能测试的速率、并发数、吞吐量和响应时间等指标。资源为单个PDF文件，压缩包约967KB，结构紧凑、知识点密集，适合作为SaaS架构入门与进阶的参考笔记。目前已有197人学习，可帮助读者快速建立多租户架构设计的整体认知，理解可配置化、高性能与可伸缩性的落地思路。

1. 从一份 SaaS 架构设计文档说起：多租户、计费与扩展到底怎么落地

很多团队第一次认真写 SaaS 架构设计文档，往往不是因为想写，而是被现实逼出来的：客户从 10 家涨到 200 家，数据库里开始出现「某租户把整张表扫了一遍」的慢查询；销售签了一个要私有化部署的大单，研发发现代码里到处是if (tenantId == xxx)；财务月底对账，发现套餐费用策略和实际用量对不上。这时候才回头补一份架构设计，代价已经很大。

这份「SaaS+架构设计」要解决的核心问题其实就三件事：多租户数据怎么隔离、套餐与计费怎么建模、业务量涨上来之后怎么横向扩展。它适合正在做 B 端产品的后端工程师、技术负责人，也适合需要评审架构方案的产品和运维同学。下面我按自己踩过坑的顺序，把选型理由、可复现的配置和参数、以及最容易翻车的地方讲清楚，新手能照着搭最小骨架，熟手能直接对照边界条件。

2. 多租户数据隔离：三种模式怎么选、怎么建表

多租户是 SaaS 架构设计的地基，选错了后面所有东西都要返工。常见做法有三种：独立数据库、共享数据库独立 Schema、共享数据库共享表加tenant_id字段。选型不是看哪个高级，而是看客户体量、合规要求和运维成本。

2.1 三种隔离模式的成本与边界对比

我一般的做法是混合：标准版走共享表，旗舰版走独立 Schema，私有化大单走独立库。这样一套代码要能同时支持，关键是把租户上下文抽出来，业务代码不直接拼tenant_id。

2.2 用 MyBatis 拦截器自动注入 tenant_id

共享表模式下，最容易翻车的是「有人忘了加tenant_id条件」，导致 A 租户查到 B 租户数据。靠代码规范约束不现实，得用框架层强制。下面是一个基于 MyBatis 拦截器的最小实现：

// TenantInterceptor.java @Intercepts({ @Signature(type = Executor.class, method = "query", args = {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class}) }) public class TenantInterceptor implements Interceptor { @Override public Object intercept(Invocation invocation) throws Throwable { MappedStatement ms = (MappedStatement) invocation.getArgs()[0]; Object param = invocation.getArgs()[1]; // 只处理需要租户隔离的 SQL，通过注解或命名空间判断 if (needTenantFilter(ms)) { String tenantId = TenantContext.get(); // 从 ThreadLocal 取 if (tenantId == null) { throw new IllegalStateException("租户上下文缺失，拒绝执行"); } // 通过改写 SQL 或传入参数方式追加 tenant_id 条件 BoundSql boundSql = ms.getBoundSql(param); String sql = boundSql.getSql(); String newSql = sql + " AND tenant_id = '" + tenantId + "'"; // 反射替换 BoundSql 中的 sql，此处省略反射细节 } return invocation.proceed(); } }

逻辑说明：拦截器在 SQL 执行前统一追加tenant_id条件，业务代码完全无感知。参数说明：TenantContext用ThreadLocal保存当前请求的租户 ID，在网关或过滤器里从 JWT 或请求头解析后写入，请求结束务必remove()，否则线程池复用会导致租户串号——这是血泪经验，线上出现过一次，排查了一整晚。

注意：拦截器方案对JOIN、子查询、UNION的改写很脆弱，复杂 SQL 建议改用独立 Schema 或数据库层行级安全策略，别硬扛。

2.3 租户上下文在网关层的传递

租户 ID 从哪来？常见做法是在 API 网关解析 token，把tenant_id放进请求头透传给下游服务。下游用过滤器写入ThreadLocal：

// TenantFilter.java public class TenantFilter implements Filter { @Override public void doFilter(ServletRequest req, ServletResponse resp, FilterChain chain) throws IOException, ServletException { HttpServletRequest request = (HttpServletRequest) req; String tenantId = request.getHeader("X-Tenant-Id"); try { TenantContext.set(tenantId); chain.doFilter(req, resp); } finally { TenantContext.remove(); // 必须清理，防止线程复用串号 } } }

参数说明：X-Tenant-Id由网关统一注入，禁止客户端直接伪造，网关要校验 token 里的租户和请求头是否一致。finally里的remove()不是可选项，是必须项。

3. 套餐与计费建模：费用策略怎么设计才不返工

SaaS 套餐的费用策略是产品和技术交叉最密集的地方，也是最容易「上线后改不动」的地方。热搜里常看到「saas 套餐的费用策略」，说明大家都在纠结：按坐席、按用量、按功能、还是混合？我的经验是，计费模型要预留「计量事件」这一层，别把套餐和价格硬编码进业务表。

3.1 计费模型的三层结构

把计费拆成三层：计量（Metering）、定价（Pricing）、账单（Billing）。计量负责记录「发生了什么」，比如 API 调用次数、存储用量、活跃坐席数；定价负责「怎么算钱」，比如阶梯价、包月、超额单价；账单负责「出账和收款」。三层解耦后，改价格策略不用动业务代码。

-- 计量事件表：所有可计费行为都往这里写 CREATE TABLE usage_event ( id BIGINT PRIMARY KEY AUTO_INCREMENT, tenant_id VARCHAR(64) NOT NULL, event_type VARCHAR(64) NOT NULL, -- 如 api_call / storage_gb / seat quantity DECIMAL(18,4) NOT NULL, occurred_at DATETIME NOT NULL, idempotent_key VARCHAR(128) NOT NULL, -- 幂等键，防重复计量 UNIQUE KEY uk_idem (tenant_id, idempotent_key), KEY idx_tenant_time (tenant_id, occurred_at) ); -- 套餐定价表：支持阶梯和超额 CREATE TABLE price_plan ( id BIGINT PRIMARY KEY AUTO_INCREMENT, plan_code VARCHAR(64) NOT NULL, event_type VARCHAR(64) NOT NULL, included_qty DECIMAL(18,4) DEFAULT 0, -- 套餐内包含量 unit_price DECIMAL(18,6) DEFAULT 0, -- 超额单价 tier_json JSON, -- 阶梯价配置 UNIQUE KEY uk_plan_event (plan_code, event_type) );

逻辑说明：usage_event用idempotent_key保证同一笔用量只记一次，避免重试导致多计费。price_plan把「包含量」和「超额单价」分开，阶梯价用 JSON 存，方便运营改而不发版。参数说明：quantity用DECIMAL不用FLOAT，金额和用量都别用浮点，这是财务对账翻车的经典原因。

3.2 出账任务的幂等与重跑

出账通常按月跑批，最怕的是任务失败重跑导致重复出账。做法是给每个「租户 + 账期」加唯一约束，出账前先查状态。

-- 账单表加唯一约束 ALTER TABLE invoice ADD UNIQUE KEY uk_tenant_period (tenant_id, billing_period); -- 出账前检查，已出账则跳过 INSERT INTO invoice (tenant_id, billing_period, amount, status) SELECT :tenantId, :period, SUM(...), 'PENDING' FROM usage_event WHERE tenant_id = :tenantId AND occurred_at BETWEEN :start AND :end ON DUPLICATE KEY UPDATE updated_at = NOW();

参数说明：billing_period用2024-06这种字符串，别用时间戳，方便人看和排查。ON DUPLICATE KEY UPDATE保证重跑不会产生第二条账单，但要注意它不会更新金额，如果定价变了需要显式处理。

提示：出账任务一定要能「按租户单独重跑」，全量重跑在大租户上可能跑几小时，出问题没法快速修复。

4. 扩展性与性能：从单库到分片的演进路径

SaaS 架构设计躲不开扩展性问题。客户涨上来之后，第一个瓶颈通常是数据库连接数和单表数据量。别一上来就分库分表，先做读写分离和缓存，撑不住了再分片。

4.1 连接池与慢查询的必调参数

共享表模式下，所有租户共用一个库，连接池配置直接决定系统能扛多少并发。下面是我常用的 HikariCP 配置：

spring: datasource: hikari: maximum-pool-size: 50 # 按 DB 最大连接数的 70% 设 minimum-idle: 10 connection-timeout: 3000 # 3 秒拿不到连接就失败，别无限等 idle-timeout: 600000 max-lifetime: 1800000 # 小于 DB 的 wait_timeout leak-detection-threshold: 60000 # 连接泄漏检测，60 秒

参数说明：maximum-pool-size不是越大越好，超过 DB 承载反而拖慢整体；leak-detection-threshold在压测和预发环境必开，能提前发现没关闭的连接。慢查询方面，idx_tenant_time这类联合索引要保证「租户 + 时间」的查询走索引，否则大租户一查就全表扫。

4.2 分片键的选择与路由

当单表超过千万级，考虑分片。分片键首选tenant_id，因为 SaaS 的查询几乎都带租户维度，按租户分片能保证单租户查询落在单库，避免跨片 JOIN。

// 简单取模分片路由 public class ShardingRouter { private static final int SHARD_COUNT = 8; public static String route(String tenantId) { int hash = Math.abs(tenantId.hashCode()); int shard = hash % SHARD_COUNT; return "ds_" + shard; // 对应数据源名 } }

逻辑说明：用tenantId的 hash 取模决定数据源。参数说明：SHARD_COUNT一旦定下就别轻易改，扩容需要数据迁移；如果预判增长快，可以用一致性哈希或预留双倍分片。注意大租户可能造成数据倾斜，必要时给大租户单独分片。

注意：分片后跨租户的统计报表会变得很麻烦，常见做法是把计量数据同步到分析型存储（如 ClickHouse）再聚合，别在业务库上跑全量统计。

5. 避坑与排查：SaaS 架构设计里最容易翻车的五件事

这一章是我这些年踩过的坑，每条都按「现象 → 原因 → 解决」写，能帮你省下不少后悔药。

坑一：租户数据串号。现象是 A 客户看到 B 客户的数据，偶发且难复现。原因是ThreadLocal没在请求结束时清理，线程池复用导致上一个请求的租户 ID 残留。解决是过滤器里finally必须remove()，并在拦截器里对空租户直接抛异常拒绝执行，别让它静默通过。

坑二：计费重复计量。现象是客户账单金额偏高，投诉多收钱。原因是计量事件在重试或消息重复消费时被写了两次。解决是给usage_event加idempotent_key唯一约束，消费端用「业务 ID + 事件类型」做幂等键，插入冲突就忽略。

坑三：套餐变更后历史账单被改。现象是运营改了套餐价格，上个月的账单金额跟着变了。原因是账单直接关联了price_plan的当前值。解决是出账时把当时的单价快照进账单明细，账单一旦生成就与定价表解耦，改价只影响未来账期。

坑四：大租户拖垮整个库。现象是一个大客户跑报表，其他租户全部超时。原因是共享库没有资源隔离，大查询占满连接和 IO。解决是给大租户单独分片或独立 Schema，同时对查询加超时和限流，报表类请求走只读副本。

坑五：分片后扩容迁移出错。现象是加机器后部分租户数据查不到。原因是取模分片数变了，路由结果和旧数据位置对不上。解决是扩容前用双写 + 数据迁移工具把数据搬到新分片，校验一致后再切路由，别直接改SHARD_COUNT。

6. 用一套最小验证脚本确认隔离与计费是否真的生效

架构设计写完不代表落地正确，我习惯用一套最小验证脚本在预发环境跑一遍，确认隔离和计费真的生效。下面这段用 Python 模拟两个租户并发写入和查询，验证不会串号：

import threading import requests BASE = "http://localhost:8080" results = {} def worker(tenant_id, token): headers = {"Authorization": token, "X-Tenant-Id": tenant_id} # 写入一条本租户数据 requests.post(f"{BASE}/orders", json={"amount": 100}, headers=headers) # 查询，确认只看到自己的数据 resp = requests.get(f"{BASE}/orders", headers=headers).json() results[tenant_id] = [o["tenant_id"] for o in resp["data"]] threads = [ threading.Thread(target=worker, args=("tenant_a", "token_a")), threading.Thread(target=worker, args=("tenant_b", "token_b")), ] for t in threads: t.start() for t in threads: t.join() # 断言：每个租户只能看到自己的数据 for tid, seen in results.items(): assert all(x == tid for x in seen), f"{tid} 串号了: {seen}" print("隔离验证通过")

逻辑说明：两个线程用不同租户身份并发请求，如果ThreadLocal或拦截器有问题，seen里会出现别的租户 ID，断言直接失败。参数说明：X-Tenant-Id在真实环境由网关注入，测试时手动带上；token要和租户匹配，否则网关校验会拦掉。

计费验证则更简单，跑一笔用量后查账单：

-- 验证：同一幂等键重复写入，用量只记一次 INSERT INTO usage_event (tenant_id, event_type, quantity, occurred_at, idempotent_key) VALUES ('tenant_a', 'api_call', 1, NOW(), 'req-001') ON DUPLICATE KEY UPDATE quantity = quantity; SELECT SUM(quantity) FROM usage_event WHERE tenant_id = 'tenant_a' AND event_type = 'api_call'; -- 重复执行上面的 INSERT，SUM 应该保持 1，不是 2

参数说明：idempotent_key用业务请求 ID，重复插入时ON DUPLICATE KEY UPDATE不改变数量，保证幂等。验证时故意插两次，看SUM是否稳定。

我现在的习惯是：任何 SaaS 架构设计评审前，先让写方案的人把这两段验证脚本跑通，跑不通的方案一律打回。架构图再漂亮，隔离和计费这两条底线守不住，上线就是事故。希望帮到你。

本文还有配套的精品资源，点击获取