架构与系统设计 / 系统课时
串租问题排查
串租问题排查
串租不是单点故障,而是租户身份在请求、SQL、缓存或异步链路中被错误复用。本课给出一套从证据固化到逐层修复的排查顺序,帮助你快速确认数据从哪里跨越了租户边界。
学习目标
- 根据同一条链路中的租户标识差异确认串租事实
- 依次排查上下文泄漏、SQL 漏条件、缓存污染和异步传播
- 完成修复后的并发回归与隔离验收
先固定证据再改代码
真正的串租必须同时满足两个条件:请求属于租户 A,但查询、缓存命中或最终响应出现了租户 B 的数据。先记录 traceId、登录租户、上下文租户、SQL 参数、缓存键和异步任务租户,避免只凭用户截图猜测根因。

建议先在测试环境对同一接口连续发送租户 A、租户 B、租户 A 三次请求。若第三次请求稳定返回租户 B 数据,优先检查线程复用和缓存;若只在特定查询出现,优先检查 SQL;若只在消息、定时任务或异步回调中出现,优先检查上下文传播。
用链路日志定位首个错位点
下面的主示例创建并运行一个日志筛选脚本。第一个参数是日志文件,第二个参数是实际链路 ID;示例依赖 Linux、macOS 或带有 grep 的 Shell 环境。
cat > check-tenant-trace.sh <<'SCRIPT'
#!/usr/bin/env bash
set -euo pipefail
LOG_FILE="${1:?usage: ./check-tenant-trace.sh <LOG_FILE> <TRACE_ID>}"
TRACE_ID="${2:?usage: ./check-tenant-trace.sh <LOG_FILE> <TRACE_ID>}"
grep -F "$TRACE_ID" "$LOG_FILE" \
| grep -E "authTenantId=|contextTenantId=|sqlTenantId=|cacheKey=|asyncTenantId="
SCRIPT
chmod +x check-tenant-trace.sh
./check-tenant-trace.sh app.log 7f3a9c预期输出:
<TIME> traceId=7f3a9c authTenantId=tenant-a contextTenantId=tenant-a
<TIME> traceId=7f3a9c sqlTenantId=tenant-a
<TIME> traceId=7f3a9c cacheKey=tenant:tenant-a:order:10086
<TIME> traceId=7f3a9c asyncTenantId=tenant-a实际时间和链路 ID 会不同。从上到下寻找第一个不一致字段:它通常就是故障边界,后续字段即使继续错误,也往往只是被上游污染后的结果。
四类根因与修复方法
| 故障层 | 典型证据 | 根因 | 修复原则 |
|---|---|---|---|
| 请求上下文 | authTenantId 正确,下一请求的 contextTenantId 仍是旧值 |
ThreadLocal 未在异常或提前返回时清理 |
在最外层过滤器的 finally 中统一清理 |
| SQL | 上下文正确,但 SQL 参数缺少 tenant_id |
手写 SQL、联表、子查询或绕过插件 | 租户表强制显式条件,并对复杂 SQL 做审计 |
| 缓存 | SQL 正确,缓存命中后返回其他租户数据 | 键只使用业务 ID,未包含租户维度 | 键统一为 tenant:{tenantId}:{domain}:{id} |
| 异步 | 同步接口正常,线程池或消息消费异常 | 子线程未传播上下文,或传播后未清理 | 提交任务时捕获租户,执行结束后清理 |
下面是上下文清理的片段示例,依赖项目已有的 TenantContext 和过滤器链。关键点不是在哪里设置,而是无论正常、异常还是提前返回都必须执行 clear()。
TenantContext.setTenantId(authenticatedTenantId);
try {
filterChain.doFilter(request, response);
} finally {
TenantContext.clear();
}缓存修复后还要删除旧键,否则新代码可能继续命中历史污染数据。异步任务不要直接读取提交线程的 ThreadLocal,应在提交时捕获租户 ID,在执行线程中设置,并在 finally 中清理。
回归验证与验收
修复后至少执行三组测试:两个租户使用相同业务主键交替访问;线程池并发执行带租户任务;缓存预热后切换租户重复读取。数据库层还应检查响应中的每条记录都满足当前 tenant_id。
验收时确认同一 traceId 的全部租户字段一致,任何租户表 SQL 都包含租户条件,缓存键可直接识别所属租户,异步任务开始和结束均有上下文设置与清理。四项同时通过,才算真正消除串租风险。
本课总结
- 串租排查应从同一链路的首个租户标识错位点开始
- 请求上下文、SQL、缓存和异步任务必须分别验证
- 修复后要用交替租户、并发线程和缓存复用场景完成回归
下一课预告
下一课将继续排查多租户系统的性能瓶颈,重点分析索引、连接池、热点租户、批量任务与缓存命中率。