Spring Boot 4 + Sa-Token 跑 Agent:登录态怎么跨线程活着
一个真实踩坑:请求线程里能拿到
userId,Agent 线程里拿不到。
问题出在换线程的那一刻
Web 请求进来,Sa-Token 的拦截器先跑,把 token 解析成登录态。业务代码里 LoginHelper.getUserId() 随时能取到值,因为它读的是当前线程的请求上下文。
然后我们把活交给 Agent:
java
Mono.fromCallable(() -> routeOrchestrator.executePinned(route))
.subscribeOn(Schedulers.boundedElastic())
.subscribe(...);boundedElastic 是另一个线程。进去之后,LoginHelper 读不到任何东西——Sa-Token 的登录态挂在当前线程上,线程一换,上下文就是空的。
这不是 Sa-Token 的问题,也不是 Reactor 的问题。ThreadLocal 本来就是这个语义。
方案一:把上下文塞进 Reactor Context(不推荐)
Reactor 有 contextWrite / deferContextual,理论上能传。但 Agent 执行不是一条纯 Reactor 链:工具回调、HITL 暂停、恢复续跑、SSE 桥接、阻塞式编排,每跨一层都要确认 Context 还在不在。漏一处就是空指针,最后没走这条路。
方案二:在边界处取值,随 RuntimeContext 传下去
做法很朴素:在请求线程里把身份取出来,变成一个普通对象,跟着 Agent 的运行期上下文走。
java
Long userId = LoginHelper.getUserId();
Long deptId = entryAgent ? LoginHelper.getDeptId() : null;
RuntimeContext ctx = RuntimeContext.builder()
.userId(String.valueOf(userId))
.sessionId(String.valueOf(sessionId))
.put(AiRouteContext.class, route)
.build();RuntimeContext 是 AgentScope 的运行期上下文,跨线程传递由框架保证。下游拿的是 ctx.userId(),不是 LoginHelper.getUserId()。
这一步的分水岭在于:身份从"当前线程的状态"变成"这次执行的入参"。入参可测试,日志里能看到,单测里能直接构造。
Agent 内部:所有用户维度都从入参算
进入 Agent 之后,还有一批逻辑要按用户算:候选专家、会话级资源、继承槽位、记忆归属、知识库可见范围。
这些逻辑统一从 route.userId()、ctx.userId() 取,不再回头读 SaHolder。
看 AiRouteOrchestrator 里构造子任务上下文的代码,user_id 是从 route 里带的,而不是现场取的:
java
return RuntimeContext.builder()
.userId(String.valueOf(route.userId))
.sessionId(String.valueOf(route.sessionId))
.build();这条约束如果破了,问题会很隐蔽:大部分请求正常,只有走到异步分支时,用户维度变成 null 或者上一个请求的值——串数据比报错更难查。
我们的做法是把这条写进评审清单:异步分支里不允许出现 LoginHelper。
HITL 恢复:新请求,旧身份
人工确认是个容易踩的坑。
用户在确认卡片上点“允许”,前端发一个新的 HTTP 请求。这个请求本身是有登录态的,LoginHelper 能取到值。
但业务上需要的是原始会话的归属人,不是“谁点的确认”。这两个值在多用户场景下可能不一样:管理员代确认、共享会话、渠道消息。
所以恢复段构造上下文时,用户 ID 来自暂存,不来自身份工具:
java
Long userId = pending.userId();确认接口只校验“当前登录人有没有权限处理这条确认”,不拿当前登录人替换业务身份。
还有一处细节:恢复段的重建上下文要标 resumed = true,否则收尾时会把空的决策、空的动作覆盖回 ai_route_run,把首段的路由记录抹掉。
无人值守:根本没有登录态
定时任务和渠道消息没有人在线,自然也没有 token。
这类链路的身份从任务定义里来:创建人、所属部门、系统账号。代码里不能调 LoginHelper,调了就是空。
权限上也不能复用 Web 那套。source=task 的写工具默认全部 DENY,只放行白名单里的工具编码。这条规则在权限决策里追加,而不是靠定时任务配置“记得别调写工具”。
两层权限,别混在一起
Sa-Token 管接口和菜单:能不能访问 /ai/agent/task、能不能看到某个配置页。
Agent 管工具执行:这个工具本次能不能调、要不要人工确认、无人值守是否放行。
一个是人的属性,登录时确定;一个是这次执行的属性,每轮按来源(chat / task / channel)、工具类型、白名单重算。
混用的典型写法是在工具里查菜单权限来决定能不能发公告——同一个人从对话页能发、从定时任务发不了,规则没人说得清。分开之后,接口层拦人,执行层拦动作。
坑清单
写这类组合时,下面几处基本都会遇到:
SSE 超时。 流式响应默认超时比普通请求短,长任务容易在中间断掉。项目把 SSE 超时单独配到了 24 小时(sse-timeout),否则 HITL 等待期间连接就被容器回收了。
日志串号。 请求线程的 MDC 不会自动带到 Reactor 线程。日志里要么显式打印 userId、sessionId,要么在切换线程时手动拷贝 MDC。我们选了前者——多打两个字段,比追一天日志便宜。
审计落库。 工具调用、路由决策、链路追踪都要带 user_id。如果这个值来自 LoginHelper,异步写入时就是空的。所以审计表里的 user_id 必须从上下文对象取。
单测拿不到登录态。 LoginHelper 依赖 Sa-Token 的上下文,纯单测里直接调用会抛异常。把身份变成入参之后,单测构造一个 userId 就行,不需要起 Web 环境。这是方案二的额外收益。
并发登录。 开了 is-concurrent: true 后同一账号多端在线,别把"当前 token"当身份来源,用 userId。
Spring Boot 4 里要注意的两点
Boot 4 基于 Spring Framework 7 和 Jakarta EE 11,Sa-Token 的 starter 与拦截器注册方式没变,WebMvcConfigurer 里照旧注册。
相关的是虚拟线程:开了 spring.threads.virtual.enabled,ThreadLocal 语义不变,每个虚拟线程有自己的副本。虚拟线程只是让线程更便宜,解决不了跨线程丢上下文。SSE 的异步超时也建议按业务单独设,别用默认值。
收尾
这类问题的根因不在框架,在假设:默认“当前线程”和“当前请求”是一回事。
同步代码里它们确实是。一旦引入异步执行、响应式流、定时任务,这个假设就不成立了。
把身份做成入参,改动不大:
- 边界处取一次:
LoginHelper只在请求线程出现; - 传下去:
RuntimeContext.userId; - 内部只用入参:异步分支禁止
LoginHelper; - 恢复段用暂存身份:
pending.userId()。
代码入口:AiChatFacade(首段与恢复段)、AiRouteOrchestrator(子任务上下文)、AiExpertResumeDriver(确认续跑)。
关于 BizBuddy
BizBuddy 是一个全量开源(MIT)的企业级智能体平台:Spring Boot 4.1 + AgentScope Java Harness,前端 开源中后台底座,PostgreSQL 14 与 MySQL 8.0 双栈等价交付。本文涉及的边界取身份、两层权限、HITL 暂存身份、无人值守白名单与六类审计,仓库里都能直接对照。
仓库地址:https://gitee.com/zl3624/biz-buddy
bash
cd code/back-end && ./mvnw clean package -DskipTests
cd ../front-end && pnpm install && pnpm build:prod
cd ../../deploy/deploy-pg && docker compose up -d --build # 或 deploy-mysql登录 http://localhost,在「模型配置」补齐对话与向量模型的 Key;改完代码跑 node e2e/http/run.mjs 回归。如果你也在做多线程跑 Agent、接企业 SSO、给写操作加确认这类事,欢迎拿这套代码对照,设计上不合理的地方直接提 issue。