系统架构 · 隔离多租户与资源治理

💡 一句话理解

多租户就是把一栋楼按"合租"运营: 独栋 (Separate DB) 最贵但隔壁着不了火, 合租大通铺 (行级 tenant_id) 最便宜但全靠每个人自觉关门——没有数据库层的门禁 (RLS), 一条忘写 WHERE 的 SQL 就是串号事故。

Noisy Neighbor 是合租的经典矛盾: 半夜开派对的大租户把水电网 (连接池/CPU/IO) 吃光, 全楼陪瘫。配额 (Quota) 与分池 (Bulkhead) 就是物业管理: 给每个租户装独立电表、限定最大功率——出了事只跳自家的闸。

🧠 必知必会 必考 & 必会

Multi-tenancy 多租户

一套系统服务多个客户, 数据同住一张表、靠 tenant_id 列区分。本质是把隔离成本摊薄: 省钱的同时把"数据边界"从物理边界变成了每一条 SQL 的纪律。

SELECT tenant_id, count(*) FROM orders GROUP BY tenant_id;
-- 关键: 一张表服务所有租户, tenant_id 是第一等公民
-- → acme | 81234 ; beta | 421

Single-tenant 单租户

一租户一套部署 (独立进程/独立库), 隔离最彻底、故障和升级互不影响, 代价是成本随租户数线性增长, 适合付费能力强的金融/大客户。

# helm install tenant-acme ./chart --set tenant=acme
# 关键: 一租户一套 release, 升级/故障半径=1, 但成本 ×N
# → 200 个租户 = 200 套发布流水线, 没自动化别选这条路

Row-level Isolation 行级隔离

所有租户共用表, 行上打 tenant_id 标。是 SaaS 主流: 迁移只跑 1 遍、成本最低; 风险也最集中——任何一条漏过滤的 SQL 都能读到别人。

ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
CREATE POLICY t_isolation ON orders
  USING (tenant_id = current_setting('app.tenant_id'));
-- 关键: 应用每个连接先 SET app.tenant_id, 漏 WHERE 也查不出别人

Shared DB / Schema / Separate DB

三档隔离: 共享库共享表 (最省)、共享库独立 schema (中等, 迁移跑 N 遍)、独立库 (最贵最稳)。选型问题本质是客单价问题: 大客户买得起隔离, 长尾租户买不起。

CREATE SCHEMA tenant_acme;   -- schema 档: 1 个 DB, N 个 schema
CREATE DATABASE tenant_acme; -- 独立档: 1 个租户 1 个 DB
-- 关键: 三档 = 三种价格, DDL 迁移成本从 1 遍变 N 遍

RLS 强制策略 (PostgreSQL)

行级安全策略把租户过滤下沉到数据库内核, 应用想忘都忘不掉。注意两层开关: ENABLE 只约束普通角色, 表 owner 默认绕过, 必须 FORCE 才连 owner 一起管。

ALTER TABLE orders FORCE ROW LEVEL SECURITY;
-- 关键: 只 ENABLE 不 FORCE 时, 表 owner 直连可读全表
-- → owner 连接执行 SELECT 也只看得见 app.tenant_id 那一份

Resource Quota 资源配额

给租户的资源上限 (CPU/内存/实例数/请求数)。配额是硬顶不是排队: 超了直接拒绝, 所以必须配告警和用户侧提示, 否则用户只会看到"创建失败"。

apiVersion: v1
kind: ResourceQuota
spec:
  hard:
    requests.cpu: "50"    # 关键: 硬顶, 超了创建 Pod 直接 Forbidden

Noisy Neighbor 喧闹邻居

共享环境里一个租户的突发负载 (大报表、死循环、爬虫) 侵蚀其他租户的资源。定位靠按租户聚合的资源视图, 治理靠限流+分池+迁出三连。

SELECT usename, count(*) FROM pg_stat_activity
  GROUP BY usename ORDER BY count(*) DESC;
-- 关键: 先定位谁占着连接, 再决定限流还是迁走
-- → acme_rw | 97 ; beta_rw | 3  (凶手一目了然)

Bulkhead 舱壁隔离

像船的水密隔舱: 把资源 (线程/连接/并发额度) 按租户切成独立隔间, 一个隔间进水不沉全船。代价是资源利用率下降——隔间留了余量就不能被别人借用。

BulkheadConfig.custom()
    .maxConcurrentCalls(20)
    .build();
// 关键: acme 的并发预算 20, 打满只堵自己
// → 第 21 个并发调用立刻 BulkheadFullException

Tenant Context 租户上下文

请求进来的租户身份 (通常来自 JWT/网关 header) 存进 ThreadLocal, 数据层自动读取。致命弱点: 线程池复用与异步切换会丢上下文, 必须用装饰器传递、用完清理。

private static final ThreadLocal<String> TENANT = new ThreadLocal<>();
TENANT.set("acme");   // 关键: 进线程池/异步就丢, 必须传递版装饰器
// → @Async 线程里 TENANT.get() == null, 数据层查不到租户

RBAC + 租户双维权控

角色 (能不能做) 与租户归属 (是不是你的数据) 是两个正交维度, 角色对不等于数据对: 同是 admin, A 公司的 admin 也不该读 B 公司的行。

def can_read(user, order):
    # 关键: 角色校验之外, 必须再校验数据归属
    return user.has_role("reader") and order.tenant_id == user.tenant_id
# → A 公司 admin 读 B 公司订单: 角色通过, 归属拒绝

Namespace 命名空间

K8s 里逻辑分组的"房间": 配额、网络策略、RBAC 都挂在 namespace 上, 常用来隔离租户或测试/生产环境。它只是逻辑隔离——节点、内核仍是共享的, 强隔离要上容器 runtime 或独立集群。

kubectl create namespace tenant-acme
kubectl get pods -n tenant-acme
# 关键: namespace = 租户房间, 配额/网络策略都挂在它上面
# → No resources found in tenant-acme namespace.

缓存 key 租户前缀

多租户系统里缓存是仅次于数据库的串号高发地: key 不带租户段, 两个租户就读写同一份值。纪律: 租户上下文必须参与 key 生成, 且禁止手拼 key。

key := fmt.Sprintf("t:%s:orders:%s", tenantID, orderID)
// 关键: 缓存 key 不带租户前缀 = 跨租户串数据
// → t:acme:orders:1001 命中的是 acme 自己的数据

🏭 生产实战 real world

// 网关已校验 JWT, 服务入口只做上下文装载与清理 (Spring)
public class TenantInterceptor implements HandlerInterceptor {
  public boolean preHandle(HttpServletRequest req, HttpServletResponse resp, Object h) {
    String tid = req.getHeader("X-Tenant-ID");
    if (tid == null) throw new MissingTenantException();  // 无租户上下文一律拒绝
    TenantContext.set(tid);
    return true;
  }
  public void afterCompletion(HttpServletRequest req, HttpServletResponse resp,
                              Object h, Exception ex) {
    TenantContext.clear();  // 关键: Tomcat 线程复用, 不清理下一个请求就继承上个租户
  }
}

-- 迁移脚本: 应用连接用非超级用户 app_rw (RLS 对超级用户无效)
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
ALTER TABLE orders FORCE ROW LEVEL SECURITY;  -- 连表 owner 也强制
CREATE POLICY orders_tenant ON orders
  USING (tenant_id = current_setting('app.tenant_id'))
  WITH CHECK (tenant_id = current_setting('app.tenant_id'));
-- 每次业务请求开始: SET app.tenant_id = 'acme'
-- 连接归还连接池前必须 RESET app.tenant_id, 否则下个请求继承

apiVersion: v1
kind: ResourceQuota
metadata: { name: tenant-acme-quota, namespace: tenant-acme }
spec:
  hard:
    requests.cpu: "50"        # 客户买的是 50 核, 超了创建直接 Forbidden
    requests.memory: 100Gi
    pods: "300"
---
apiVersion: v1
kind: LimitRange              # 没写 resources 的容器给默认值, 防裸奔吃节点
spec:
  limits:
    - type: Container
      default: { cpu: 500m, memory: 512Mi }

# 应用侧报错: HikariPool-1 - Connection is not available, request timed out after 30000ms.
# DB 侧报错: ERROR 1040 (HY000): Too many connections
# MySQL: 谁占着连接? 按持有时间倒序
SELECT host, db, command, time, state FROM information_schema.processlist
ORDER BY time DESC LIMIT 10;
-- → 975 行来自 acme-report, command=Query, time=180+ (报表全表扫)
# 处置: kill 报表会话止血 → 报表迁只读副本 → 连接池按租户分池收尾

Map<String, HikariDataSource> pools = new ConcurrentHashMap<>();

HikariDataSource poolOf(String tenant) {
  return pools.computeIfAbsent(tenant, id -> {
    HikariConfig c = new HikariConfig();
    c.setJdbcUrl("jdbc:mysql://db:3306/saas?connectTimeout=1000");
    c.setMaximumPoolSize(10);       // 关键: 每租户上限, 总和必须 ≤ DB max_connections
    c.setConnectionTimeout(2000);    // 拿不到连接快速失败, 不无限排队拖垮线程
    return new HikariDataSource(c);
  });
}

resilience4j:
  bulkhead:
    instances:
      tenant-acme:              # 大租户独立隔间
        maxConcurrentCalls: 20   # acme 的并发预算
        maxWaitDuration: 100ms   # 排队上限, 超时快速失败
      tenant-default:            # 其余租户共享默认池
        maxConcurrentCalls: 50
# 超限抛 BulkheadFullException → 网关层映射为 429 + Retry-After

# nginx: 带 X-Tenant-ID: acme 的流量进独占集群, 其余进共享池
upstream shared       { server 10.0.1.10:8080; server 10.0.1.11:8080; }
upstream acme_cluster { server 10.2.0.10:8080; }

map $http_x_tenant_id $backend {
    acme      acme_cluster;
    default   shared;
}
# server 块里 proxy_pass http://$backend; 切流 = 改 map + reload, 可秒回滚

# 每租户每分钟 1000 次: Redis INCR + EXPIRE (分钟窗口足够用)
key="rl:t:${TENANT_ID}:$(date +%Y%m%d%H%M)"
n=$(redis-cli INCR "$key")
[ "$n" -eq 1 ] && redis-cli EXPIRE "$key" 60
if [ "$n" -gt 1000 ]; then
  # 关键: 超配额必须显式告知 + 升级入口, 静默失败用户只会骂你
  echo "HTTP 429; Retry-After: 60"
fi

def export_orders(tenant_id, user):
    # 导出禁止绕过租户过滤: 参数化 SQL + 强制 tenant 谓词
    rows = db.execute(
        "SELECT id, amount FROM orders WHERE tenant_id = %s",
        (tenant_id,),
    )
    audit.log("export", tenant=tenant_id, user=user.id, rows=len(rows))
    # 关键: 导出走独立限流 + 行数入审计, 出事能定位到人
    return to_excel(rows)

# 路由配置: X-Tenant-ID 决定去向
tenants:
  acme:    { pool: dedicated, replicas: 4 }  # 付了专属费
  beta:    { pool: dedicated, replicas: 2 }
  default: { pool: shared, maxTenants: 200 }  # 共享池设上限, 防无限塞
# 共享池 CPU 超 70% 时, 优先把"增长率最大"的租户迁出为独占

⚠️ 编码注意与常见坑 pitfalls

-- 错: SELECT * FROM orders WHERE id = 1001;   -- → 返回了别家租户的订单
-- 对: SELECT * FROM orders
--     WHERE id = 1001 AND tenant_id = current_setting('app.tenant_id');

// 错: em.createNativeQuery("SELECT * FROM t_order WHERE id = ?1")  // 过滤器失效
// 对: em.createNativeQuery("SELECT * FROM t_order WHERE id = ?1 AND tenant_id = ?2")
//         .setParameter(2, TenantContext.get())

-- 错: CREATE INDEX idx_status ON orders (status);                  -- → 全表扫
-- 对: CREATE INDEX idx_tenant_status ON orders (tenant_id, status);

key := "config:pay"                          // 错: 两个租户读写同一份, 串数据
key := fmt.Sprintf("t:%s:config:pay", tenantID) // 对: 租户段参与 key

# 错: for row in db.execute("SELECT * FROM bills"): send(row)  # → 跨租户群发
# 对: for tid in all_tenants():
#         with tenant_scope(tid): send_all(... WHERE tenant_id = %s ...)

// 错: log.info("order paid id={}", orderId);       // → 不知道是谁的订单
// 对: MDC.put("tenant", TenantContext.get());      // pattern: %X{tenant} %msg

# 错: 前端只显示"创建失败" —— 用户以为系统坏了
# 对: 网关把 Forbidden: exceeded-quota 映射为:
#     HTTP 429 + "租户 Pod 配额已满, 请升级套餐或清理资源"

-- 错: 报表直连主库: SELECT count(*) FROM orders;    -- → 主库 CPU 100%
-- 对: 报表走 replica + 强制 tenant 过滤 + 单租户 1 并发配额

-- 错: UPDATE tenant SET deleted = 1;          -- → 行还在, 仍被扫描统计
-- 对: DELETE FROM orders WHERE tenant_id = :tid;  -- + 清缓存 + 删除留审计

# 错: 前端 v-if="user.isAdmin" 隐藏按钮        # → 直接 curl 接口仍成功
# 对: @require_role("admin") + assert row.tenant_id == user.tenant_id

-- 错: ALTER TABLE t ENABLE ROW LEVEL SECURITY;  -- → owner 连接可读全表
-- 对: ALTER TABLE t FORCE ROW LEVEL SECURITY;   -- → owner 也受策略约束

# 错: 每租户 maximumPoolSize: 10 × 200 租户 = 2000 连接 → 打爆 DB
# 对: 热租户独享 10, 长尾共享池 50, 总预算 <= max_connections * 0.8

# 错: order = get(id); return order          # → 改 id 就能读别家数据
# 对: order = get(id)
#     if order.tenant_id != ctx.tenant: abort(404)   # 404 而非 403, 不泄存在性

-- 错: for schema in all_schemas: ALTER TABLE ...  -- 串行 300 遍, 失败重头
-- 对: 每批 20 个并发执行 + 记录 schema 迁移版本, 顶到版本的跳过

-- 错: SELECT status, count(*) FROM orders GROUP BY status;   -- 全租户聚合
-- 对: ... WHERE tenant_id = ?  -- 走 (tenant_id, status) 索引, 毫秒级

// 错: 消费回调直接调 service                       // → TenantContext 为 null
// 对: 消费入口先 TenantContext.set(msg.getTenantId()), finally 里 clear

# 错: alert: quota_exceeded  severity: info      # → 打满才有人看, 已是事故
# 对: 80% → P3 周报;  95% → P2 即时;  100% → P1 + 用户侧横幅提示

// 错: executor.submit(() -> notify(order));       // → 子线程 tenant == null
// 对: executor.setTaskDecorator(r -> copyTenantAndRun(r))  // 提交时快照租户

# 错: 把生产 datasource 配置复制进测试环境     # → 测试直连生产库
# 对: 测试专用 namespace + 脱敏数据集 + 租户统一带 qa- 前缀隔离

# 错: export() 直接 db.execute("SELECT * FROM orders")   # → 全租户泄露
# 对: rows = scoped(TenantContext.get()).all(); audit.log("export", rows=len)