简介：这份《SaaS+架构设计》PDF文档面向希望系统掌握SaaS架构原理与实践的开发者、架构师及技术学习者，围绕多租户系统从需求分析到性能优化的完整设计链路展开。内容涵盖SaaS成熟度模型四级分级、RUP“4+1”视图模式（场景、逻辑、开发、过程、物理视图）、MDA模型驱动架构，以及系统级与程序级安全性设计、多租户数据存储的三种方案（独立数据库、共享数据库隔离数据架构、共享数据库共享数据架构）等核心议题。文档还深入讲解数据库层索引优化与消除大表连接、应用层缓存与日志记录、数据加密算法，以及云计算网络性能测试的速率、并发数、吞吐量和响应时间等指标。资源为单个PDF文件，压缩包约967KB，结构紧凑、知识点密集，适合作为SaaS架构入门与进阶的参考笔记。目前已有197人学习，可帮助读者快速建立多租户架构设计的整体认知框架。
1. 从一份被反复传阅的 SaaS 架构设计 PDF 说起：多租户到底难在哪
很多团队第一次认真讨论 SaaS 架构设计，往往不是因为业务起飞，而是因为一个具体的事故：某个大客户的一条慢查询把整个数据库拖垮，所有租户一起超时。这时候大家才意识到，把单租户系统改个域名、加个tenant_id字段，根本不叫 SaaS。SaaS 架构设计的核心矛盾只有一个——多租户共享基础设施的同时，还要保证数据隔离、性能隔离和可计费。这份被反复传阅的 SaaS 架构设计 PDF 之所以值得逐页拆，是因为它把「共享」和「隔离」这对矛盾拆成了可落地的分层决策：租户模型怎么选、数据隔离做到哪一层、请求链路怎么带上租户上下文、计量计费怎么不拖垮主流程。适合正在做 To B 产品、准备从私有化转向 SaaS、或者已经被多租户问题折腾过一轮的工程师，下面按「先立住理论、再动手复现」的顺序讲透。
2. 多租户模型选型：三种隔离级别与它们的成本边界
2.1 共享表 + tenant_id：最省成本，也最容易翻车
最常见的做法是所有租户共用一套表，每张业务表加一个tenant_id列，所有查询强制带上这个条件。它的优势是运维成本极低，一次建表全租户可用，扩容只需要加只读副本。但它的代价藏在细节里：任何一个忘记加tenant_id的查询都会造成跨租户数据泄露，任何一个租户的大批量写入都会和其他租户争抢同一张表的锁。
我一般会要求团队在共享表模式下做三件事。第一，所有 SQL 走统一的 DAO 层，禁止业务代码手写查询，tenant_id由框架自动注入。第二，给每张表建(tenant_id, 业务主键)的联合索引，而不是单独的主键索引，否则租户维度的查询会走全表扫描。第三，对写入量大的租户做限流，避免单租户打满连接池。
-- 共享表模式的典型建表：tenant_id 必须在最左前缀 CREATE TABLE orders ( id BIGINT NOT NULL AUTO_INCREMENT, tenant_id VARCHAR(32) NOT NULL, order_no VARCHAR(64) NOT NULL, amount DECIMAL(12,2) NOT NULL, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uk_tenant_order (tenant_id, order_no), KEY idx_tenant_created (tenant_id, created_at) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;这段建表语句的关键在于联合唯一索引uk_tenant_order，它保证同一租户内订单号唯一，但不同租户可以用相同订单号。如果只建order_no单列唯一索引，第二个租户插入相同订单号就会失败，这是共享表模式最隐蔽的坑之一。idx_tenant_created则服务于租户维度的分页查询，避免WHERE tenant_id = ? ORDER BY created_at走 filesort。
2.2 独立 Schema：隔离性上来了，迁移成本也上来了
当租户数量在几百到几千、且部分客户对数据隔离有硬性要求时，独立 Schema 是折中方案。每个租户一个数据库 Schema，表结构完全相同，连接时切换 Schema。它的好处是数据物理隔离、单租户备份恢复不影响他人、单租户慢查询不会锁其他租户的表。代价是建租户时要执行一遍 DDL，版本升级时要对每个 Schema 跑迁移脚本，Schema 数量多了之后连接池管理会变得复杂。
实操上我会把租户到 Schema 的映射放在一张全局路由表里，应用启动时加载到本地缓存，请求进来后根据tenant_id查路由，再决定用哪个数据源。迁移脚本必须支持幂等，因为升级过程中可能中断重跑。
# 租户路由：根据 tenant_id 返回对应的数据源 TENANT_SCHEMA_MAP = { "tenant_a": "schema_tenant_a", "tenant_b": "schema_tenant_b", } def get_datasource(tenant_id: str): schema = TENANT_SCHEMA_MAP.get(tenant_id) if not schema: raise ValueError(f"unknown tenant: {tenant_id}") # 从连接池取对应 schema 的连接，连接池按 schema 维度隔离 return connection_pool[schema]这段代码的逻辑是路由与连接池绑定，每个 Schema 独立连接池，避免一个租户的连接耗尽影响其他租户。参数上要注意连接池上限要按租户数量动态计算，比如 100 个租户、每个池上限 10，总连接数就是 1000，超过数据库max_connections就会出问题。常见做法是给活跃租户分配独立池，冷租户共享一个池。
2.3 独立实例：隔离最彻底，只适合头部客户
独立实例是每个租户一套完整的应用加数据库，隔离性最好，但运维成本随租户数线性增长。它通常只用于付费能力强的头部客户，或者有合规要求必须物理隔离的场景。选型时不要一上来就追求独立实例，除非客户明确要求且愿意承担对应成本。多数 SaaS 产品的合理路径是：中小租户共享表，中大型租户独立 Schema，头部客户独立实例，三层并存。
3. 请求链路里的租户上下文：从网关到数据库怎么一路带下去
3.1 租户标识的注入点与传递方式
租户上下文必须在请求入口就确定，常见做法是从域名、请求头或 JWT 中解析。域名方式适合每个租户有独立子域名的场景，请求头方式适合 API 调用，JWT 方式适合前后端分离且已做认证的系统。解析出来的tenant_id要放进线程上下文或协程上下文，供后续 DAO 层自动读取。
// 网关过滤器：解析租户并写入上下文 public class TenantFilter implements Filter { @Override public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) { HttpServletRequest request = (HttpServletRequest) req; String tenantId = resolveTenant(request); // 从域名/Header/JWT 解析 if (tenantId == null) { throw new IllegalArgumentException("tenant not found"); } TenantContext.set(tenantId); try { chain.doFilter(req, res); } finally { TenantContext.clear(); // 必须清理，否则线程复用会串租户 } } }这里最关键的是finally里的TenantContext.clear()。线程池复用线程时，如果不清除上下文，下一个请求可能读到上一个租户的tenant_id，造成数据串租户。这个 bug 在压测时不容易发现，因为压测往往用同一个租户，但生产环境多租户并发时必然暴露。
3.2 DAO 层自动注入 tenant_id 的实现
上下文有了，接下来要在 DAO 层自动把tenant_id拼进 SQL。用 MyBatis 的话可以写一个拦截器，在 SQL 执行前改写语句；用 JPA 的话可以用@Filter或 Hibernate 的CurrentTenantIdentifierResolver。核心原则是业务代码不感知tenant_id，避免有人漏写。
// MyBatis 拦截器：自动为查询追加 tenant_id 条件 @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 parameter = invocation.getArgs()[1]; String tenantId = TenantContext.get(); if (tenantId != null && needTenantFilter(ms)) { // 通过反射改写 SQL，追加 tenant_id = ? BoundSql boundSql = ms.getBoundSql(parameter); String newSql = boundSql.getSql() + " AND tenant_id = '" + tenantId + "'"; // 实际实现应使用参数绑定，避免 SQL 注入 } return invocation.proceed(); } }这段代码是示意，真实实现必须用参数绑定而不是字符串拼接，否则会有 SQL 注入风险。参数上要注意needTenantFilter要排除掉全局表（如租户配置表、字典表），否则会给不该加条件的表也加上tenant_id，导致查询结果为空。常见做法是维护一个白名单，只有白名单内的表才追加条件。
3.3 跨服务调用时租户上下文的透传
微服务架构下，租户上下文还要跨服务传递。常见做法是把tenant_id放进请求头，下游服务在网关或拦截器里重新解析并写入上下文。如果用消息队列，tenant_id要作为消息头或消息体的一部分传递，消费端解析后设置上下文。这里容易踩的坑是异步任务：定时任务或异步线程没有请求入口，tenant_id需要显式传入，不能依赖上下文自动获取。
4. 计量与计费：怎么统计租户用量又不拖垮主流程
4.1 用量采集的三种时机与取舍
SaaS 计费依赖用量统计，采集时机直接影响主流程性能。同步采集是在业务操作里直接写计量表，实时性最好但会增加主流程耗时；异步采集是通过消息队列解耦，主流程只发消息，计量服务消费后落库；批量采集是定时任务扫描业务表统计，对主流程零侵入但实时性差。我一般推荐异步采集，兼顾实时性和性能。
# 异步计量：业务操作后发消息，不阻塞主流程 def create_order(tenant_id, order_data): order = save_order(tenant_id, order_data) # 发送计量消息，失败不影响下单 try: mq.send("usage.topic", { "tenant_id": tenant_id, "metric": "order_count", "value": 1, "timestamp": int(time.time()) }) except Exception as e: logger.warn(f"usage report failed: {e}") return order这里的关键是计量消息发送失败不能影响主流程，所以用 try-catch 包住。参数上metric要设计成可扩展的枚举，比如order_count、api_calls、storage_bytes，方便后续增加计费维度。timestamp用于按时间窗口聚合，避免消息延迟导致统计错位。
4.2 计量数据的聚合与账单生成
原始计量数据量大，不能直接用于出账，需要按小时或按天聚合。常见做法是用流处理或定时任务把原始数据聚合成租户维度的用量汇总表，出账时再按套餐规则计算费用。聚合表要保留租户、指标、时间窗口、用量四个维度，方便按不同粒度查询。
| 字段 | 类型 | 说明 |
|---|---|---|
| tenant_id | varchar | 租户标识 |
| metric | varchar | 计量指标 |
| window_start | datetime | 统计窗口开始 |
| window_end | datetime | 统计窗口结束 |
| total_value | bigint | 窗口内累计用量 |
出账时按套餐的单价和阶梯规则计算，注意阶梯计费要处理窗口边界，比如每月前 1000 次免费，超出部分按量计费，跨窗口的用量要正确累加。
4.3 计费对账与异常用量处理
计量系统难免出现重复消费或漏消费，所以要有对账机制。常见做法是每天用业务表的真实数据核对计量汇总表，差异超过阈值就告警。异常用量比如某租户突然用量暴涨，要有熔断或限流，避免被恶意刷量导致账单异常。这里我踩过的坑是消息队列重复消费导致用量翻倍，后来在消费端加了幂等键（租户+指标+时间窗口）才解决。
5. 多租户架构的避坑与排查：五条血泪经验
5.1 现象：某租户查询返回了其他租户的数据
原因通常是 DAO 层漏加tenant_id条件，或者线程上下文未清理导致串租户。排查时先看 SQL 日志里有没有tenant_id条件，再看上下文清理逻辑是否在finally里。解决方式是强制所有查询走统一 DAO 层，并在拦截器里做兜底校验，发现无tenant_id的查询直接抛异常。
5.2 现象：单个租户的慢查询拖垮整个数据库
原因是共享表模式下租户之间没有资源隔离，一个租户的大查询占满连接池或锁住表。解决方式是对租户维度做限流，给每个租户分配最大连接数和最大 QPS，超出后排队或拒绝。更彻底的做法是把大租户迁到独立 Schema 或独立实例。
5.3 现象：租户数据迁移时业务中断
原因是迁移脚本没有做在线双写或灰度切换，直接停服迁移。解决方式是先双写新旧存储，校验数据一致后再切读，最后停写旧存储。迁移脚本要支持断点续传，避免中途失败后从头再来。
5.4 现象：计量数据与实际用量对不上
原因是消息重复消费或消费失败未重试。解决方式是在消费端加幂等键，用 Redis 或数据库唯一索引去重；消费失败要进死信队列并告警，不能静默丢弃。
5.5 现象：租户上下文在异步线程里丢失
原因是上下文存在 ThreadLocal 里，异步线程拿不到。解决方式是在提交异步任务时显式传递tenant_id，或者用支持上下文透传的线程池包装器。定时任务要在任务参数里带上tenant_id，不能依赖自动获取。
6. 从共享表到独立实例的平滑演进：一个可验证的迁移技巧
多租户架构不是一次选型定终身，业务增长会逼着你从共享表往独立 Schema 甚至独立实例演进。我一般会设计一个「租户分层路由」层，让同一套代码支持多种隔离级别，迁移时只改路由配置不改业务代码。具体做法是定义租户的隔离级别字段，路由层根据级别决定用共享数据源还是独立数据源。
# 租户分层路由：根据隔离级别选择数据源 def get_datasource(tenant_id): tenant = tenant_repo.get(tenant_id) if tenant.isolation_level == "shared": return shared_datasource elif tenant.isolation_level == "schema": return schema_datasource_pool[tenant.schema_name] elif tenant.isolation_level == "instance": return instance_datasource_pool[tenant.instance_id] raise ValueError(f"unknown isolation level: {tenant.isolation_level}")迁移时先把租户的isolation_level从shared改成schema，同时把数据从共享表同步到独立 Schema，校验一致后切读，观察一段时间无异常再删共享表数据。这个过程中路由层始终返回正确的数据源，业务代码无感知。验证方法是写一个对账脚本，对比迁移前后同一租户的查询结果，确保行数和关键字段完全一致。
我自己的习惯是每次架构演进都先写对账脚本再动手迁移，宁可多花半天写校验，也不愿半夜被数据不一致的电话叫醒。这套分层路由的思路，希望帮到你。
本文还有配套的精品资源，点击获取
