1. 项目概述：AIAgent架构中的多租户隔离挑战
最近在设计和评审几个大型AIAgent平台项目时，我发现一个普遍被低估的架构风险：多租户隔离。很多团队在初期快速迭代时，往往把精力都放在了Prompt工程、模型调用和前端交互上，认为只要在数据库层面做好租户ID过滤就万事大吉。但当我们真正把系统放到生产环境，面对高并发、复杂工作流和混合部署模型时，一系列“隐性”的隔离漏洞就会暴露出来，轻则导致数据错乱，重则引发严重的安全合规事故。
我亲身经历过一次由“租户上下文污染”引发的线上故障。在一个为多个企业客户提供智能客服Agent的SaaS平台上，某个租户的客服对话历史突然混入了另一个完全不相干租户的客户信息和内部沟通记录。你能想象那个场景吗？A公司的客服机器人开始回答B公司客户的专属问题，甚至引用了B公司的内部政策文档。这不仅仅是功能Bug，更是灾难性的数据泄漏。事后排查，问题根源并非出在显式的数据查询层，而是一个被所有人忽略的“请求上下文”对象在异步任务中没有被正确隔离。
这个项目标题点出的五个问题——租户上下文污染、模型缓存穿透、向量库跨租户泄漏等，正是这类AIAgent架构在规模化时必须直面的核心挑战。它们之所以“隐性”，是因为它们往往潜伏在应用层、缓存层、甚至是大模型服务内部，传统的基于数据库tenant_id的隔离手段在这里完全失效。而OpenTelemetry作为云原生可观测性的事实标准，为我们提供了一套强大的工具，不仅能追踪问题，更能通过规范的埋点设计，从架构层面构建起可审计、可验证的隔离防线。
接下来的内容，我将结合实战中的踩坑经验，逐一拆解这五大漏洞的形成机理、潜在危害，并分享一套可直接复用的OpenTelemetry追踪模板与防御实践。无论你正在构建的是企业级RAG应用、多Agent协作系统，还是通用的AI能力平台，这些经验都能帮你提前堵上漏洞。
2. 漏洞一：租户上下文污染的根因分析与防御实践
租户上下文污染，在我看来是AIAgent架构中最隐蔽也最危险的漏洞。它的本质是：在一次请求的处理链路中，属于租户A的上下文信息（如会话历史、用户身份、个性化参数）意外地“污染”了后续处理租户B请求的执行环境。
2.1 污染是如何发生的：从线程池到异步回调
在同步、单线程的简单场景下，我们通常会用ThreadLocal来存储当前请求的租户上下文。这在Spring的SecurityContextHolder或一些自定义的TenantContext工具类中很常见。然而，AIAgent的工作流极少是线性的。一个典型的智能问答流程可能涉及：接收用户问题 -> 检索向量库 -> 调用大模型 -> 记录交互历史 -> 触发后续异步任务（如发送通知、更新知识库）。一旦流程中引入了异步操作（如@Async、消息队列、CompletableFuture），当前线程的ThreadLocal上下文就无法传递到新的执行线程中。
更复杂的情况出现在回调或事件驱动架构中。例如，当大模型流式输出内容时，我们可能会注册回调函数来处理每一块返回的Token。如果这个回调函数是在模型服务SDK的IO线程池中执行的，它完全丢失了原始请求的租户上下文。我曾见过一个案例，系统为节省资源使用了一个全局共享的模型客户端实例，其回调处理器在处理不同租户的流式响应时，错误地将日志和指标记录到了最后一个设置上下文的租户名下，造成了严重的计费和日志混乱。
核心根因可以归结为两点：1. 上下文传递链路的断裂，尤其是在跨线程、跨进程的边界；2. 共享资源（如静态变量、单例Bean、连接池）的不当使用，导致一个租户的数据残留影响了另一个租户。
2.2 防御实践：构建可靠的上下文传播机制
解决这个问题，不能靠零散的修补，而需要一套贯穿整个技术栈的上下文传播机制。我的实践是将其分为三层：
第一层：定义清晰的上下文载体不要只用简单的租户ID。定义一个包含完整追踪信息的上下文对象（TenantContext），至少应包含：
tenantId：租户唯一标识。userId：终端用户标识（对于子租户或用户级隔离很重要）。sessionId：会话标识，用于串联一次完整交互。traceId：OpenTelemetry的追踪ID，这是实现全链路可观测的关键。requestPath：当前请求路径，用于辅助诊断。
// 示例：上下文对象定义 public class AgentRequestContext { private String tenantId; private String userId; private String sessionId; private String traceId; private Map<String, String> customAttributes; // 用于扩展 // ... getters and setters }第二层：实现自动化的上下文注入与提取在所有入口点（如HTTP控制器、消息监听器）自动注入上下文，在所有出口点（如HTTP客户端调用、消息发送、数据库操作）自动提取并附加上下文。
对于Spring生态，可以利用HandlerInterceptor或Servlet Filter在请求入口处解析请求头（如X-Tenant-Id）并构建上下文，存入TransmittableThreadLocal（这是阿里开源的一个支持线程池传递的ThreadLocal增强库）。更重要的是，必须将traceId和tenantId等信息注入到OpenTelemetry的Span属性中。
// 示例：在OpenTelemetry Span中记录租户属性 Span currentSpan = Span.current(); if (currentSpan != null) { currentSpan.setAttribute("tenant.id", tenantContext.getTenantId()); currentSpan.setAttribute("user.id", tenantContext.getUserId()); }第三层：确保上下文在异步边界无损传递这是最关键的一步。放弃原生的ThreadLocal，改用TransmittableThreadLocal或类似方案。在提交异步任务前，务必捕获当前上下文；在任务执行开始时，恢复上下文。
// 示例：使用TransmittableThreadLocal包装上下文 private static final TransmittableThreadLocal<AgentRequestContext> contextHolder = new TransmittableThreadLocal<>(); // 在异步任务执行前，上下文会被自动传递 CompletableFuture.runAsync(() -> { // 在这里可以直接获取到正确的租户上下文 AgentRequestContext ctx = contextHolder.get(); // ... 执行业务逻辑 }, executorService);实操心得：不要试图在每个异步调用点手动传递参数。通过AOP或封装公共的异步执行器，将上下文传递逻辑集中处理。我们团队封装了一个
TenantAwareExecutorService，它内部使用TtlExecutors包装，确保所有提交的任务都能自动携带上下文，从根本上杜绝了手动遗漏的风险。
3. 漏洞二：模型缓存穿透的租户边界失效与重建
模型缓存穿透是指不同租户的请求，由于缓存键设计不当或缓存层隔离缺失，导致命中同一份缓存结果。这在AIAgent场景下后果尤为严重，因为缓存的内容可能包含上一个租户的私有数据、个性化推理结果或敏感的业务逻辑。
3.1 缓存边界为何失效：键设计、预热策略与共享实例
最常见的失效点是缓存键（Cache Key）设计。很多开发者会使用“模型名+输入文本”的哈希值作为键。假设两个不同租户的用户问了同一个通用问题“今天天气怎么样？”，他们就会命中同一份缓存。如果缓存的回答中包含了基于租户A地理位置的信息，那么租户B的用户就会得到错误的地理天气信息。更糟糕的是，如果缓存的是包含租户A内部数据的增强检索结果（RAG上下文），那就直接造成了数据泄漏。
其次，缓存预热策略也可能成为漏洞。有些系统会在启动时用一批“公共问题”预加载缓存，以期提升性能。但如果这些公共问题的答案生成过程依赖了当时请求的上下文（比如默认使用了系统管理员的租户ID来检索知识库），那么预热的缓存本身就携带了错误的租户信息。
第三，共享的模型服务实例。为了节省成本，多个租户可能共享同一个托管的模型API端点（如OpenAI的同一个deployment）。一些模型服务提供商或中间件为了提升性能，会在服务端对完全相同的输入进行缓存。如果这个服务端缓存没有租户维度，那么第一个租户的请求结果就会被返回给后续相同输入的其他租户。
3.2 重建缓存隔离边界的四层策略
面对模型缓存穿透，我们需要一个纵深防御策略，从应用层到基础设施层建立多层隔离。
第一层：应用层缓存键强化在构造缓存键时，必须强制包含租户标识符。这听起来简单，但关键在于确保这个标识符在所有可能生成缓存的地方都被一致地加入。一个实用的模式是创建一个CacheKeyBuilder工具类。
public class TenantAwareCacheKeyBuilder { public static String buildKey(String cacheName, String modelId, String input, AgentRequestContext context) { // 使用明确的字段拼接，便于调试和排查 return String.format("%s:%s:%s:%s", cacheName, context.getTenantId(), // 核心：注入租户ID modelId, DigestUtils.md5Hex(input)); // 对长输入做哈希 } }第二层：缓存命名空间隔离如果使用Redis或Memcached这类分布式缓存，可以利用其namespace或database的概念进行物理或逻辑隔离。例如，为每个租户分配一个独立的Redisdatabase（虽然Redis官方不推荐将database作为多租户隔离的主要手段，但在可控的租户数量下可作为一层防护），或者在所有键前增加tenant:{id}:前缀。一些云服务商提供的缓存服务直接支持多租户隔离策略。
第三层：模型服务级隔离配置在调用外部模型API时，充分利用其提供的隔离特性。例如，对于Azure OpenAI，可以为不同租户创建不同的deployment。对于开源模型自建服务，可以通过在请求头中传递租户ID，并在模型服务端配置根据该ID选择不同的模型参数或上下文过滤器。即使服务端有缓存，由于请求路径或参数不同，缓存也会自然隔离。
第四层：引入租户感知的缓存失效策略缓存数据可能因为租户自身知识的更新而失效。例如，租户A上传了新文档到知识库，那么所有与这些文档相关的问答缓存都应失效。我们需要监听租户的数据变更事件，并批量清理与该租户相关的缓存键。这要求我们的缓存键模式必须是可模式化匹配的，以便执行高效的批量删除操作（如Redis的SCAN命令配合tenant:{id}:*模式）。
注意事项：谨慎使用全局缓存失效。在微服务架构下，一个租户的缓存失效事件可能需要广播到所有持有缓存的业务服务。我们引入了基于Redis Pub/Sub的轻量级事件机制，当知识库更新时，发布一个包含
tenantId和affectedDocIds的事件，各服务监听并局部清理相关缓存。
4. 漏洞三：向量库与状态存储的跨租户泄漏风险
向量数据库（如Pinecone、Weaviate、Milvus）和用于存储会话状态、中间结果的键值存储（如Redis），是AIAgent的“记忆体”。这里的跨租户泄漏风险极高，因为数据访问模式复杂，且很多查询操作是基于数学计算（向量相似度搜索），而非简单的键值查询。
4.1 向量库泄漏：当相似度搜索越过租户墙
向量库的核心操作是相似度搜索。标准的做法是在为每个文档创建向量嵌入（Embedding）时，将tenant_id作为一个独立的字段存入元数据（Metadata）。查询时，在过滤条件（Filter）中加上tenant_id = ‘current_tenant‘。这看似安全，实则存在多个陷阱：
- 过滤器绕过：如果查询API调用时忘记添加过滤器，或者过滤器条件因为代码Bug被置空，就会导致全库搜索，返回其他租户的相似文档。我遇到过因为一个前端查询参数解析库的默认值问题，导致在特定条件下过滤器对象为
null，从而引发了泄漏。 - 嵌入模型不一致：如果不同租户的文档是由不同版本或不同参数的嵌入模型处理的，它们的向量空间可能不完全对齐。但更危险的是，如果系统使用一个共享的、使用混合租户数据训练的“全局”模型来为所有租户生成嵌入，那么从向量空间上，不同租户的文档本质上是混杂在一起的，仅靠元数据过滤就像用一张薄纸分隔房间，存在理论上的泄漏风险（尽管实际检索相关性可能不高）。
- 索引分区策略：一些向量数据库支持基于元数据字段的索引分区。如果未能正确配置按
tenant_id分区，那么所有租户的向量在索引底层可能是交织存储的，不仅影响隔离性，还可能影响查询性能。
4.2 状态存储泄漏：会话、流程与中间结果的混乱
AIAgent通常是有状态的，需要记住多轮对话的上下文、执行长期任务的进度等。这些状态通常存储在Redis或数据库中。
- 键名冲突：如果使用简单的键如
session:{sessionId}，那么理论上不同租户有可能生成相同的sessionId（虽然概率极低但并非不可能），导致状态覆盖。必须将tenant_id作为键的一部分，如tenant:{tenantId}:session:{sessionId}。 - 全局查询操作误用：例如，运维人员或某个后台功能使用了
KEYS *或SCAN命令来统计全局会话数，如果没有在应用逻辑中先按租户过滤，就会导出所有租户的状态信息。 - 广播式消息：如果使用Redis的Pub/Sub或Stream做消息总线，向某个频道发送消息时，需要确保订阅该频道的消费者都属于同一个租户，或者消息本身包含租户ID且消费者会进行过滤。
4.3 加固策略：从数据写入到查询的闭环校验
防御向量库和状态存储的泄漏，需要建立一个从数据写入、存储到查询访问的闭环安全模型。
策略一：强制性的租户标识注入在数据写入层进行强制校验。无论是文档切片向量化后存入向量库，还是将会话状态存入Redis，都必须有一个不可绕过的逻辑层来注入当前请求上下文中的tenantId。我们通过编写统一的存储客户端封装类来实现。
// 示例：向量库客户端封装 public class TenantAwareVectorClient { private VectorDatabaseClient rawClient; public void upsert(String collection, List<Document> docs, AgentRequestContext ctx) { if (ctx == null || StringUtils.isBlank(ctx.getTenantId())) { throw new IllegalStateException("Tenant context is missing for vector operation."); } // 为每个文档的metadata注入tenant_id List<Document> tenantDocs = docs.stream() .map(doc -> doc.toBuilder() .metadata(mergeMetadata(doc.getMetadata(), "tenant_id", ctx.getTenantId())) .build()) .collect(Collectors.toList()); rawClient.upsert(collection, tenantDocs); } public SearchResult search(String collection, float[] embedding, int topK, AgentRequestContext ctx) { // 构建强制性的过滤器 Map<String, Object> filter = Map.of("tenant_id", Map.of("$eq", ctx.getTenantId())); return rawClient.search(collection, embedding, topK, filter); } }策略二：实施查询前置校验在到达向量库或Redis之前，所有查询请求必须经过一个“查询门面”（Query Facade）的检查。这个门面负责：
- 验证请求是否携带有效的租户上下文。
- 将租户ID自动拼接到查询条件中。
- 对于管理类或运维类查询（如获取所有会话），强制要求显式提供租户ID列表，否则拒绝执行。
策略三：定期审计与异常检测利用OpenTelemetry收集的所有向量库和缓存查询的追踪数据，我们可以定期执行审计分析。例如，编写脚本分析Span日志，查找那些过滤器（filter）中不包含tenant_id条件的查询操作，即使它们可能因为结果为空而未引发问题，但这本身就是一个高危行为。也可以设置监控告警，当发现某个查询返回的结果集中包含多个租户的ID时，立即触发告警。
5. 漏洞四：Agent工作流与工具执行中的权限逃逸
AIAgent的强大之处在于其能自主调用外部工具（Tools）或API来完成复杂工作流，如发送邮件、查询数据库、操作日历。在多租户环境下，如果Agent工作流引擎或工具执行层没有严格的租户边界，就会发生“权限逃逸”：一个租户的Agent可能触发了本应属于另一个租户的工具操作。
5.1 工作流引擎的上下文丢失
许多工作流引擎（如Camunda、Flowable）或自定义的状态机在处理异步、长时间运行的任务时，其执行上下文与最初的HTTP请求线程是分离的。当工作流执行到一个节点，需要调用一个工具（例如，“查询该客户的最近订单”），如果这个工具调用依赖当前的租户信息来定位正确的数据库，那么工作流引擎必须有能力在任务恢复时，提供正确的租户上下文。
常见陷阱：将租户ID仅仅作为业务变量（processVariable）存储在工作流实例中。但当工作流调用一个通用的、被所有租户共享的“查询订单”服务时，如果该服务从ThreadLocal或安全上下文中获取租户ID，而此时这个上下文是空的或错误的，就会导致查询错乱。
5.2 工具执行层的授权漏洞
在LangChain、LangChain4j或自定义Agent框架中，工具（Tool）通常被设计成无状态的函数。例如，一个QueryDatabaseTool，它的输入是SQL语句。框架本身通常不负责校验这条SQL应该在哪个租户的数据库上执行。如果前端或Prompt构造不当，导致恶意或错误的SQL被传入，就可能查询到其他租户的数据。
更隐晦的风险在于工具的动态加载。有些系统允许租户上传自定义工具（Python函数或API描述）。如果这些工具代码在共享的运行时（如一个Python解释器或JVM）中执行，且没有做好沙箱隔离，一个租户的工具代码可能会直接访问到其他租户的内存数据或文件。
5.3 构建租户感知的工作流与工具沙箱
对于工作流引擎，解决方案是建立租户上下文与流程实例的强绑定。在工作流实例创建时，不仅要将tenantId作为业务变量存储，更要将其作为流程实例的“标签”或“分类键”存入引擎元数据。当引擎的任何外部任务（External Task）被触发或定时器到期时，负责执行该任务的Worker必须能够从流程实例中获取到tenantId，并在执行前将其恢复到当前执行线程的上下文中。许多现代工作流引擎支持“租户标识（Tenant Identifier）”的概念，应优先使用这种原生支持。
对于工具执行层，必须实施两层校验：
- 声明式租户绑定：在每个工具的定义中，显式声明其所需的数据资源范围。例如，
QueryMyOrdersTool隐式绑定到当前租户的订单库。在工具执行器的核心逻辑里，强制从当前线程绑定的TenantContext中取出tenantId，并将其作为参数传递给底层的数据访问层。 - 运行时资源解析：建立一个“资源解析器”（Resource Resolver），它根据
tenantId和工具类型，动态决定工具操作的实际目标。例如，对于数据库查询工具，资源解析器根据tenantId返回对应的数据源连接池；对于发送邮件的工具，它返回配置了该租户SMTP服务器和发件人地址的邮件客户端实例。
// 示例：租户感知的工具执行器 public class TenantAwareToolExecutor { @Resource private ResourceResolver resourceResolver; public Object executeTool(String toolName, Map<String, Object> toolInput) { AgentRequestContext ctx = TenantContextHolder.get(); // 1. 校验上下文存在 if (ctx == null) { throw ... } // 2. 根据工具名和租户ID，获取具体的工具实例 Tool tool = resourceResolver.resolveTool(toolName, ctx.getTenantId()); // 3. 执行工具，工具内部已绑定正确的租户资源 return tool.execute(toolInput); } }实操心得：对于允许租户自定义工具的场景，必须采用严格的沙箱机制。可以考虑将每个租户的自定义工具运行在独立的轻量级容器（如WebAssembly沙箱、进程隔离）中，彻底杜绝运行时层面的交叉访问。同时，对所有工具的可执行操作进行白名单限制，禁止直接的文件系统访问、网络调用等高风险行为。
6. 漏洞五：日志、监控与可观测性数据中的信息混杂
即使应用层完美地实现了隔离，如果在可观测性层面（日志、指标、追踪）混合了所有租户的数据，那么从运维视角看，系统仍然是“透明”的。一个拥有日志访问权限的工程师（或一个日志分析系统漏洞）可能通过搜索日志，拼凑出不同租户的业务信息。这违反了数据最小化原则和合规要求。
6.1 日志中的敏感信息泄漏
这是最普遍的问题。例如，在记录大模型请求和响应时，如果日志模板是固定的，可能会将包含租户A客户个人信息的问题和答案完整记录到日志文件。当日志被集中收集到Elasticsearch等系统后，任何有权访问日志平台的人都可以看到所有数据。
// 危险日志示例 INFO - User question: “我的身份证号是510xxx，最近订单状态如何？” INFO - AI response: “尊敬的张三，您的订单123456已发货...”即使没有直接的个人信息，通过关联不同时间、IP的日志，也可能推断出租户的业务模式或活跃度。
6.2 指标聚合导致的租户行为暴露
监控指标（Metrics）通常是聚合的，比如“平均响应时长”、“每日请求量”。但如果聚合维度设计不当，也会泄露信息。例如，如果只为每个租户单独绘制“请求错误率”图表，那么当某个租户的错误率突然飙升时，其他租户的运维人员或管理层可能就会察觉该租户发生了业务异常或正在遭受攻击测试。在高度竞争或保密的B2B场景下，这可能也是不希望的。
6.3 利用OpenTelemetry构建可审计的多租户追踪体系
OpenTelemetry (OTel) 为解决这一问题提供了完美的框架。它统一了日志、指标和追踪（Traces）的生成与上下文传播。我们的目标是：在追踪链路中清晰标识租户，在日志和指标中按需聚合或过滤租户数据，同时确保原始数据在受控环境下可供安全审计。
第一步：在OTel Resource和Span中注入租户属性在应用启动时，将服务本身的信息（如服务名、实例ID）定义为OTel Resource。同时，在每个请求的根Span（Span）中，必须将tenant.id和user.id作为属性（Attributes）记录进去。这确保了整条调用链上的所有Span（数据库查询、HTTP调用、模型请求）都通过父子关系关联到这个租户上下文。
# 示例：OpenTelemetry Agent配置 (部分) # 通过环境变量或Java Agent参数注入资源属性 OTEL_RESOURCE_ATTRIBUTES=service.name=ai-agent-platform,service.instance.id=${HOSTNAME}在代码中，手动增强Span属性：
Span span = Span.current(); span.setAttribute("tenant.id", tenantContext.getTenantId()); span.setAttribute("user.id", tenantContext.getUserId()); // 可以添加业务属性，但需注意脱敏 span.setAttribute("agent.session.id", sessionId);第二步：实现结构化的、脱敏的日志记录摒弃传统的非结构化日志，采用JSON等结构化格式输出日志，并与OTel TraceID进行关联。在日志框架（如Logback、Log4j2）的布局（Layout）或过滤器（Filter）中，自动从TenantContext中获取租户ID并写入日志事件。同时，必须集成脱敏组件，对日志消息体中的敏感模式（如身份证号、邮箱、手机号）进行实时掩码处理。
<!-- 示例：Logback配置，使用logstash编码器输出结构化JSON，并添加MDC中的租户信息 --> <encoder class="net.logstash.logback.encoder.LogstashEncoder"> <customFields>{"service":"${SERVICE_NAME}","pod":"${HOSTNAME}"}</customFields> <includeMdcKeyName>tenantId</includeMdcKeyName> <includeMdcKeyName>traceId</includeMdcKeyName> </encoder>第三步：设计租户维度的指标与安全视图在暴露指标时，区分“运营指标”和“租户指标”。
- 运营指标：面向平台运维团队，反映系统整体健康度，如服务总QPS、容器CPU/内存使用率、全局错误率。这些指标不应包含租户标签，避免信息泄露。
- 租户指标：面向租户自身或平台的管理后台，如“租户A的每日Token消耗量”、“租户B的对话平均响应时长”。这些指标需要包含
tenant_id标签，但它们的查询和访问必须受到严格的权限控制。在Prometheus中，可以使用tenant_id标签，但通过抓取配置或记录规则，将不同租户的指标数据路由到不同的监控租户空间。
第四步：提供安全可控的追踪数据审计接口追踪（Trace）数据包含了最详细的请求链路信息，是事后审计和安全调查的黄金数据。我们需要提供专门的审计查询接口。这个接口不应直接暴露原始的Jaeger或Zipkin界面，而应该是一个封装层，它强制要求查询者必须指定tenant_id，并且系统会校验该查询者是否有权查看该租户的数据。在后台，查询会被转换为对追踪存储（如Elasticsearch）的带租户过滤条件的查询。
7. 可审计的OpenTelemetry追踪模板与落地实践
理论需要模板来落地。下面我分享一个基于Spring Boot和OpenTelemetry Java Instrumentation的可审计追踪配置模板，它实现了上述的多租户隔离与审计要求。
7.1 核心依赖配置
首先，在pom.xml中引入关键依赖。
<dependency> <groupId>io.opentelemetry.instrumentation</groupId> <artifactId>opentelemetry-spring-boot-starter</artifactId> <version>2.5.0</version> <!-- 请使用最新稳定版 --> </dependency> <!-- 用于在日志中输出TraceId --> <dependency> <groupId>io.opentelemetry.instrumentation</groupId> <artifactId>opentelemetry-logback-mdc-1.0</artifactId> <version>2.5.0</version> </dependency> <!-- TransmittableThreadLocal 支持 --> <dependency> <groupId>com.alibaba</groupId> <artifactId>transmittable-thread-local</artifactId> <version>2.14.5</version> </dependency>7.2 租户上下文传播与OTel Span属性注入
创建一个TenantContextFilter或Spring Interceptor，在所有请求入口处建立上下文，并自动注入Span属性。
@Component public class TenantContextFilter extends OncePerRequestFilter { private final TtlAgentRequestContextHolder contextHolder; @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ServletException, IOException { // 1. 从请求头、JWT或路径中解析租户ID和用户ID String tenantId = resolveTenantId(request); String userId = resolveUserId(request); String sessionId = generateOrGetSessionId(request); // 2. 构建上下文对象 AgentRequestContext context = new AgentRequestContext(tenantId, userId, sessionId); // 3. 将上下文存入TransmittableThreadLocal try { contextHolder.set(context); // 4. 获取当前Span并注入租户属性 (关键步骤) Span currentSpan = Span.current(); if (currentSpan != null && currentSpan.isRecording()) { currentSpan.setAttribute("tenant.id", tenantId); currentSpan.setAttribute("user.id", userId); currentSpan.setAttribute("agent.session.id", sessionId); // 设置Span名称，便于识别 currentSpan.updateName(request.getMethod() + " " + request.getRequestURI()); } // 5. 将TraceId也存入上下文，方便业务日志关联 String traceId = Span.current().getSpanContext().getTraceId(); context.setTraceId(traceId); MDC.put("traceId", traceId); // 用于日志MDC MDC.put("tenantId", tenantId); chain.doFilter(request, response); } finally { // 6. 请求结束后清理上下文，防止内存泄漏 contextHolder.remove(); MDC.clear(); } } private String resolveTenantId(HttpServletRequest request) { // 实现从Header、Token或子域名解析的逻辑 // 示例：从Header "X-Tenant-Id" 获取 String tenantId = request.getHeader("X-Tenant-Id"); if (StringUtils.isBlank(tenantId)) { throw new UnauthorizedException("Tenant identification is missing."); } return tenantId; } }7.3 关键组件的追踪增强配置
在application.yml中，配置OpenTelemetry导出器和采样率。为了审计，我们通常需要全量采样或高采样率来捕获问题。
management: tracing: sampling: probability: 1.0 # 生产环境可根据负载调整，但审计要求高，建议保持1.0或0.5以上 opentelemetry: instrumentation: methods: # 为关键的数据访问和外部服务调用方法添加自定义Span tenant-aware-vector-client: class: com.yourcompany.vector.TenantAwareVectorClient method: search span-name: vector.search model-cache-client: class: com.yourcompany.cache.ModelCacheClient method: get span-name: cache.model.get7.4 审计查询接口示例
提供一个安全的内部审计API，供授权人员查询特定租户的追踪数据。
@RestController @RequestMapping("/api/internal/audit/traces") @PreAuthorize("hasRole('AUDITOR')") // 严格的权限控制 public class TraceAuditController { @Autowired private TraceQueryService traceQueryService; @GetMapping public PageResult<TraceSummary> queryTraces( @RequestParam String tenantId, @RequestParam(required = false) Long startTime, @RequestParam(required = false) Long endTime, @RequestParam(required = false) String serviceName, @RequestParam(defaultValue = "0") int page, @RequestParam(defaultValue = "50") int size) { // 1. 校验当前用户是否有权审计该租户（实现略） checkAuditPermission(tenantId); // 2. 调用封装的查询服务，底层对接Jaeger或OTel Collector的查询API // 查询条件中必须强制包含 tenant.id = ${tenantId} return traceQueryService.queryTracesByTenant(tenantId, startTime, endTime, serviceName, page, size); } @GetMapping("/{traceId}") public TraceDetail getTraceDetail(@PathVariable String traceId, @RequestParam String tenantId) { checkAuditPermission(tenantId); // 查询详情时，同样需要传递tenantId，确保后端查询强制过滤 return traceQueryService.getTraceDetail(traceId, tenantId); } }7.5 部署与运维注意事项
- Span属性开销：在每个Span上添加自定义属性（如
tenant.id）会略微增加追踪数据的大小。需评估存储成本，对于极高吞吐量的服务，可以考虑仅在根Span和关键子Span上添加。 - 采样策略：全量采样（probability=1.0）在流量大时对采集器和存储压力大。可以采用头部采样（Head-based Sampling）结合动态配置，例如，对错误请求（status>=500）全采样，对成功请求按较低比率采样，同时确保来自特定重要租户或特定操作的请求全采样。
- 数据保留策略：出于合规和审计要求，追踪数据可能需要保留较长时间（如180天）。需要与存储方案（如使用Elasticsearch作为Trace后端）结合，设计按时间分片和冷热数据分离的策略，控制成本。
- 安全与访问控制：确保追踪数据存储（如Jaeger UI、Elasticsearch）的访问网络是隔离的，并且有严格的认证授权。避免生产环境的追踪数据被直接暴露在公网或内部不受限访问。
这套模板和实践中，最核心的思想是将租户隔离从一种业务逻辑提升为一种可观测性基础设施的固有属性。通过OpenTelemetry的标准化埋点，我们不仅能在出问题时快速定位，更能通过常态化的数据审计，主动发现潜在的隔离漏洞，防患于未然。在实际落地时，建议先从最核心的、涉及敏感数据的流程开始实施，逐步推广到全链路。
（支持资料、图片参考_相关定制）_)
