架构与系统设计 / 系统课时

串租问题排查

串租问题排查

串租不是单点故障,而是租户身份在请求、SQL、缓存或异步链路中被错误复用。本课给出一套从证据固化到逐层修复的排查顺序,帮助你快速确认数据从哪里跨越了租户边界。

学习目标

  • 根据同一条链路中的租户标识差异确认串租事实
  • 依次排查上下文泄漏、SQL 漏条件、缓存污染和异步传播
  • 完成修复后的并发回归与隔离验收

先固定证据再改代码

真正的串租必须同时满足两个条件:请求属于租户 A,但查询、缓存命中或最终响应出现了租户 B 的数据。先记录 traceId、登录租户、上下文租户、SQL 参数、缓存键和异步任务租户,避免只凭用户截图猜测根因。

串租问题排查流程

建议先在测试环境对同一接口连续发送租户 A、租户 B、租户 A 三次请求。若第三次请求稳定返回租户 B 数据,优先检查线程复用和缓存;若只在特定查询出现,优先检查 SQL;若只在消息、定时任务或异步回调中出现,优先检查上下文传播。

用链路日志定位首个错位点

下面的主示例创建并运行一个日志筛选脚本。第一个参数是日志文件,第二个参数是实际链路 ID;示例依赖 Linux、macOS 或带有 grep 的 Shell 环境。

bash
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

预期输出:

text
<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()。

java
TenantContext.setTenantId(authenticatedTenantId);
try {
    filterChain.doFilter(request, response);
} finally {
    TenantContext.clear();
}

缓存修复后还要删除旧键,否则新代码可能继续命中历史污染数据。异步任务不要直接读取提交线程的 ThreadLocal,应在提交时捕获租户 ID,在执行线程中设置,并在 finally 中清理。

回归验证与验收

修复后至少执行三组测试:两个租户使用相同业务主键交替访问;线程池并发执行带租户任务;缓存预热后切换租户重复读取。数据库层还应检查响应中的每条记录都满足当前 tenant_id。

验收时确认同一 traceId 的全部租户字段一致,任何租户表 SQL 都包含租户条件,缓存键可直接识别所属租户,异步任务开始和结束均有上下文设置与清理。四项同时通过,才算真正消除串租风险。

本课总结

  • 串租排查应从同一链路的首个租户标识错位点开始
  • 请求上下文、SQL、缓存和异步任务必须分别验证
  • 修复后要用交替租户、并发线程和缓存复用场景完成回归

下一课预告

下一课将继续排查多租户系统的性能瓶颈,重点分析索引、连接池、热点租户、批量任务与缓存命中率。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

串租问题排查

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通