本文以清鉴 AI 调查工具的一个完整用户会话为主线,说明从客户端启动、绑定服务地址、获取授权单元、登录、Gateway 粘性路由、ai-server Sa-Token 校验,到 Agent 调用 LLM 与向量检索、图谱/统计结果返回前端渲染的关键数据流。文档同时给出时序图、状态图和流程图,标注“浏览器 → Gateway → ai-server → 外部模型/数据库”的跨进程、跨网络、跨服务边界,并覆盖 SSE 心跳保活、登录失效、节点不可用、Agent 流式响应等异常情况。
| 组件 |
职责 |
关键输入 |
关键输出 |
| 前端设置模块 |
读取并校验 localStorage 中的服务地址,构造健康检查 URL |
用户输入的协议+主机+端口 |
规范化 origin、测试连接结果 |
| 授权模块 |
通过 /sys/info 拉取授权单元,显示水印和授权状态 |
已绑定的后端地址 |
授权单元文本、过期时间 |
| 登录接口封装 |
调用后端 /admin/login 等管理路径 |
用户名、加密密码 |
登录结果、会话上下文 |
| 网关注册表 |
加载 PostgreSQL 中的 service/node 配置,发布刷新事件 |
YAML 播种 + 数据库 |
ServiceInfo 内存快照 |
| 粘性路由过滤器 |
按 username/token 选择并固定 ai-server 节点,重写目标 URI |
请求头、属性、路由元数据 |
下游 NodeOrigin + rawPath + rawQuery |
| 登录请求过滤器 |
解析登录体中的 username,改写 Accept-Encoding |
POST 登录路径原始请求体 |
带 username 属性的请求 |
| 登录响应过滤器 |
成功登录后写入用户-节点绑定和 token 缓存 |
后端登录响应体 |
无(不修改响应) |
| 用户路由服务 |
Redis + PostgreSQL 两级缓存用户绑定 |
serviceId、userId、username |
nodeId |
| Token 解析器 |
x-token → userId,优先查网关本地缓存,兜底 Sa-Token |
serviceId、token |
userId |
| 健康注册表 |
内存记录每个节点的 UP/DOWN/UNKNOWN |
探活结果 |
isUp(nodeId) |
| Sa-Token Web 配置 |
白名单放行 + 登录态校验 + 活跃标记 |
所有受保护请求 |
未登录抛 401 |
| Agent 聊天控制器 |
暴露聊天、SSE 流式、图谱复原等接口 |
ChatRequestDTO |
Flux
|
| Agent 聊天服务 |
构建 AgentScope 会话、控制流互斥、映射事件为 SSE |
会话键、消息 |
流式 token/tool_call/done/error |
| LLM 服务 |
直连大模型,流式或批量返回 |
Model 配置 + prompt |
文本、用量、耗时 |
章节来源
- serverSetting.ts:1-200
- login.ts:1-152
- GatewayRegistry.java:1-116
- StickyRouteFilter.java:1-180
- LoginRequestFilter.java:1-120
- LoginResponseFilter.java:1-176
- UserRouteService.java:1-117
- TokenResolver.java:1-100
- NodeHealthRegistry.java:1-68
- SaTokenWebConfig.java:1-65
- AgentChatController.java:1-170
- AgentChatServiceImpl.java:345-574
- LlmService.java:1-200
架构总览
清鉴的工作流跨越四个边界:
- 浏览器进程内:Electron 前端读取 localStorage、组装请求、渲染 UI。
- 浏览器到网关:HTTP/HTTPS 请求,携带
x-token、Cookie 等。
- 网关到 ai-server:根据 ServiceInfo 中的 baseUrl 重写后转发。
ai-server 到外部依赖:PostgreSQL/pgvector、Redis、外部 LLM API。
sequenceDiagram
participant FE as "前端"
participant GW as "网关"
participant SV as "ai-server"
participant PG as "PostgreSQL/pgvector"
participant REDIS as "Redis"
participant LLM as "外部大模型"
FE->>GW: GET /js/a/admin/sys/info
GW->>SV: GET /sys/info
SV-->>GW: Result<SystemInfo>
GW-->>FE: Result<SystemInfo>
FE->>GW: POST /js/a/admin/login {username, pwd}
GW->>SV: POST /auth/login
SV->>REDIS: 创建 Sa-Token 会话
SV-->>GW: Result{token, userId, username}
GW->>REDIS: 缓存 gateway:token:{serviceId}:{token}
GW->>PG: 写入 user→node 绑定
GW-->>FE: 登录成功
FE->>GW: GET /js/a/chat/sessions (携带 x-token)
GW->>GW: x-token→userId → 查询绑定节点
GW->>SV: 转发到选定节点
SV->>PG: 查询会话
SV-->>GW: 会话列表
GW-->>FE: 会话列表
图示来源
- login.ts:100-152
- SystemController.java:1-120
- LoginRequestFilter.java:1-120
- LoginResponseFilter.java:1-176
- UserRouteService.java:1-117
- TokenResolver.java:1-100
典型用户工作流的数据流
第一阶段:客户端启动与服务地址绑定
前端在启动时检查是否需要绑定服务地址。若生产环境要求绑定且 localStorage 中没有 SERVER_BASE_URL__,则停留在地址页;否则从 localStorage 读取服务 origin,并通过构建后的 API 前缀访问后端。
flowchart TD
Start(["前端启动"]) --> CheckBinding["是否要求绑定服务地址?"]
CheckBinding -->|是且未绑定| ShowAddressPage["显示服务地址录入页"]
CheckBinding -->|否或已绑定| ReadOrigin["读取 localStorage 中的 SERVER_BASE_URL__"]
ReadOrigin --> HealthCheck["调用 buildHealthCheckUrl(origin)<br/>GET /js/a/admin/sys/health"]
HealthCheck --> Healthy{"后端健康检查通过?"}
Healthy -->|是| Ready["进入主界面"]
Healthy -->|否| ReportError["提示地址错误或后端未就绪"]
图示来源
- serverSetting.ts:1-200
- SystemController.java:40-80
章节来源
- serverSetting.ts:1-200
- SystemController.java:40-80
第二阶段:读取授权单元
进入主界面后,App.vue 尝试从页面缓存中读取授权单元;若为空且当前存在有效 API 源,则调用 /sys/info 拉取授权信息,再经 extractAuthorizationCache 提取授权单元,并作为水印展示。
sequenceDiagram
participant FE as "前端 App.vue"
participant License as "license.ts"
participant GW as "网关"
participant SV as "ai-server"
FE->>FE: 读取页面缓存 authorizationUnit
alt 已有授权单元
FE-->>FE: 直接渲染水印
else 未找到授权单元
FE->>GW: GET /js/a/admin/sys/info
GW->>SV: GET /sys/info
SV-->>GW: Result<SystemInfo>
GW-->>FE: Result<SystemInfo>
FE->>License: extractAuthorizationCache(res)
License-->>FE: {authorizationUnit, overDateTime, authorizationLabel}
FE->>FE: 设置水印
end
图示来源
- App.vue:1-85
- login.ts:120-152
- license.ts:1-124
- SystemController.java:80-120
章节来源
- App.vue:1-85
- login.ts:120-152
- license.ts:1-124
- SystemController.java:80-120
第三阶段:用户登录与粘性节点绑定
用户提交用户名和密码后,前端调用 loginApi,请求走 /admin/login。该请求由 Gateway 的 LoginRequestFilter 识别为登录路径,解析出 username,并在后续 StickyRouteFilter 中决定:
- 如果 username 已绑定节点,则固定转发到该节点;
- 如果未绑定,则按健康节点轮询选择一个候选节点,但不立即写库;
登录成功后,LoginResponseFilter 把 userId、username、token 和候选节点写入绑定表和 token 缓存。
sequenceDiagram
participant FE as "前端"
participant GW as "网关"
participant LR as "LoginRequestFilter"
participant SR as "StickyRouteFilter"
participant LS as "LoginResponseFilter"
participant SV as "ai-server"
participant PG as "PostgreSQL"
participant REDIS as "Redis"
FE->>GW: POST /js/a/admin/login {username, pwd}
GW->>LR: 解析 username
LR-->>SR: 标记 LOGIN_REQUEST + LOGIN_USERNAME
SR->>PG: 按 username 查找绑定节点
alt 已绑定
SR->>SV: 转发到已绑定节点
else 未绑定
SR->>SR: NodeSelector 轮询健康节点
SR->>SV: 转发到候选节点
end
SV->>REDIS: StpUtil.login(userId)
SV-->>GW: Result{code=200, data.token, data.userId, data.username}
GW->>LS: 捕获响应体
LS->>PG: bindIfAbsent(serviceId, userId, username, chosenNodeId)
LS->>REDIS: cacheToken(serviceId, token, userId)
GW-->>FE: 登录成功
图示来源
- login.ts:40-90
- LoginRequestFilter.java:1-120
- StickyRouteFilter.java:1-180
- LoginResponseFilter.java:1-176
- UserRouteService.java:1-117
- TokenResolver.java:1-100
章节来源
- LoginRequestFilter.java:1-120
- StickyRouteFilter.java:1-180
- LoginResponseFilter.java:1-176
- UserRouteService.java:1-117
- TokenResolver.java:1-100
第四阶段:后续请求通过 StickyRouteFilter 稳定转发
普通请求携带 x-token。Gateway 通过 TokenResolver 解析 userId,再查 UserRouteService 得到绑定节点;若用户有绑定,则始终转发到该节点,即使该节点 DOWN,也返回 503,而不是自动切换。匿名请求走 NodeSelector 轮询健康节点。
flowchart TD
Request["普通请求<br/>携带 x-token"] --> ResolveToken["TokenResolver 解析 userId"]
ResolveToken --> HasToken{"token 可解析?"}
HasToken -->|否| Anonymous["按匿名请求处理"]
HasToken -->|是| FindBind["UserRouteService 查询 userId→nodeId"]
FindBind --> Bound{"已绑定节点?"}
Bound -->|是| RouteBound["转发到绑定节点"]
Bound -->|否| DefaultNode["使用 defaultNodeId 兜底绑定"]
DefaultNode --> RouteBound
Anonymous --> SelectNode["NodeSelector 轮询健康节点"]
SelectNode --> RouteBound
RouteBound --> HealthCheck{"绑定节点可用?"}
HealthCheck -->|否| Error503["返回 503 用户未绑定或节点不可用"]
HealthCheck -->|是| Backend["转发到 ai-server"]
图示来源
- StickyRouteFilter.java:1-180
- NodeSelector.java:1-45
- UserRouteService.java:1-117
- TokenResolver.java:1-100
章节来源
- StickyRouteFilter.java:1-180
- NodeSelector.java:1-45
- UserRouteService.java:1-117
- TokenResolver.java:1-100
第五阶段:ai-server 校验 Sa-Token 会话
ai-server 通过 SaTokenWebConfig 注册拦截器,对所有非白名单路径执行 StpUtil.checkLogin()。白名单包括 /auth/login、/sys/health、/sys/checkAuth、/sys/info、/sys/code、/sys/noNet、/sys/map/** 和 /error。未登录时抛出未登录异常,最终被全局异常处理器转换为 HTTP 200 但 body.code=401,前端据此跳转到登录页。
flowchart TD
Inbound["ai-server 接收请求"] --> WhiteList{"路径在白名单?"}
WhiteList -->|是| Controller["直接到达 Controller"]
WhiteList -->|否| CheckLogin["SaInterceptor 调用 checkLogin()"]
CheckLogin --> LoggedIn{"已登录?"}
LoggedIn -->|是| TouchActivity["标记登录活跃"]
TouchActivity --> Controller
LoggedIn -->|否| Unauthorized["抛出未登录异常<br/>转成 code=401"]
图示来源
- SaTokenWebConfig.java:1-65
章节来源
- SaTokenWebConfig.java:1-65
第六阶段:Agent 调用 LLM 与 pgvector 向量检索
当用户在前端发送 Agent 消息时,请求进入 /chat/stream,返回 Flux<ServerSentEvent<String>>。服务端流程包括:
- 校验消息内容和会话权限;
- 通过会话级 Semaphore 保证同一会话只有一条流;
- 构建 AgentScope 的 RuntimeContext 和消息;
- 调用 AgentScope 的
streamEvents;
- 将 tool_call、tool_input、tool_result、token、done、error 事件映射为 SSE;
- 在 done 时持久化 assistant 回复;
工具链可能调用 GraphService 获取图谱数据,也可能通过 RAG/pgvector 做向量检索。
sequenceDiagram
participant FE as "前端"
participant GW as "网关"
participant AC as "AgentChatController"
participant AS as "AgentChatServiceImpl"
participant AG as "AgentScope/HarnessAgent"
participant GR as "GraphService"
participant PG as "PostgreSQL/pgvector"
FE->>GW: POST /js/a/chat/stream {sessionKey, messages}
GW->>AS: 转发到绑定 ai-server 节点
AS->>AS: 会话流互斥 Semaphore.tryAcquire
AS->>AG: streamEvents(messages, ctx)
AG-->>AS: tool_call / token / tool_result / done
AS->>GR: 需要图谱时查询节点边
GR->>PG: 查询图谱数据
PG-->>GR: nodeList / edgeList
GR-->>AS: 图谱结果
AS-->>GW: SSE event stream
GW-->>FE: 逐帧渲染 token 和工具结果
图示来源
- AgentChatController.java:120-170
- AgentChatServiceImpl.java:345-574
- LlmService.java:1-200
章节来源
- AgentChatController.java:120-170
- AgentChatServiceImpl.java:345-574
- LlmService.java:1-200
详细组件分析
网关粘性路由与用户绑定
粘性路由的核心是 StickyRouteFilter。它区分登录请求和普通请求:
- 登录请求:优先查 username 绑定;若无绑定,选一个健康候选节点,仅用于本次请求转发。
- 普通请求:解析
x-token;解析失败按匿名处理;解析成功查 userId 绑定;若无绑定则用 defaultNodeId 兜底绑定。
- 转发前检查节点是否存在、enabled、健康;否则抛出 503。
目标 URI 由 buildTargetUri 拼接 baseUrl + request.getRawPath() + request.getRawQuery(),避免二次编码。
classDiagram
class StickyRouteFilter {
+int getOrder()
+Mono<Void> filter(exchange, chain)
-Mono<String> decideForLogin(exchange, service)
-Mono<String> decideForNormal(exchange, service)
-Mono<String> anonymousNode(service)
-Mono<Void> route(exchange, chain, service, nodeId)
+URI buildTargetUri(baseUrl, requestUri)
}
class LoginRequestFilter {
+int getOrder()
+Mono<Void> filter(exchange, chain)
-String parseUsername(bytes)
}
class LoginResponseFilter {
+int getOrder()
+Mono<Void> filter(exchange, chain)
-Mono<Void> parseAndBind(serviceId, chosenNodeId, body)
+LoginSuccess parseLogin(body)
}
class UserRouteService {
+Mono<String> findNodeIdByUserId(serviceId, userId)
+Mono<String> findNodeIdByUsername(serviceId, username)
+Mono<String> bindIfAbsent(serviceId, userId, username, nodeId)
+Mono<Void> evictUserCache(serviceId, userId, username)
}
class TokenResolver {
+Mono<Long> resolveUserId(serviceId, token)
+Mono<Boolean> cacheToken(serviceId, token, userId)
+Mono<Long> resolveUserIdDirect(token)
}
StickyRouteFilter --> UserRouteService : "查询/写入绑定"
StickyRouteFilter --> TokenResolver : "x-token→userId"
LoginResponseFilter --> UserRouteService : "bindIfAbsent"
LoginResponseFilter --> TokenResolver : "cacheToken"
图示来源
- StickyRouteFilter.java:1-180
- LoginRequestFilter.java:1-120
- LoginResponseFilter.java:1-176
- UserRouteService.java:1-117
- TokenResolver.java:1-100
章节来源
- StickyRouteFilter.java:1-180
- LoginRequestFilter.java:1-120
- LoginResponseFilter.java:1-176
- UserRouteService.java:1-117
- TokenResolver.java:1-100
服务与节点注册表
GatewayRegistry 维护服务的内存快照,支持 YAML 首次播种、数据库对账、定时轮询和路由刷新事件。ServiceInfo 提供路径匹配、登录路径拼接和节点查找能力。NodeHealthRegistry 维护每个节点的 UP/DOWN/UNKNOWN 状态,DOWN 才视为不可用;UNKNOWN 在启动初期乐观放行。
classDiagram
class GatewayRegistry {
-volatile List<ServiceInfo> services
-boolean initialized
+void init()
+void seedFromYamlIfNeeded()
+boolean reload()
+void pollForChanges()
+Optional<ServiceInfo> getService(id)
+Optional<ServiceInfo> findServiceByPath(rawPath)
}
class ServiceInfo {
+String id
+String name
+String pathPrefix
+String loginPath
+String healthPath
+String defaultNodeId
+boolean enabled
+List<NodeInfo> nodes
+String loginFullPath()
+boolean matchesPath(rawPath)
+Optional<NodeInfo> findNode(nodeId)
}
class NodeHealthRegistry {
+enum State
+record Health(state, lastError, lastCheckedAt, consecutiveFailures)
+boolean isUp(nodeId)
+void recordSuccess(nodeId)
+void recordFailure(nodeId, error, threshold)
+Map<String, Health> snapshot()
}
GatewayRegistry --> ServiceInfo : "装载"
ServiceInfo --> NodeInfo : "包含节点"
图示来源
- GatewayRegistry.java:1-116
- ServiceInfo.java:1-32
- NodeHealthRegistry.java:1-68
- GatewayProperties.java:1-81
章节来源
- GatewayRegistry.java:1-116
- ServiceInfo.java:1-32
- NodeHealthRegistry.java:1-68
- GatewayProperties.java:1-81
Agent 流式响应与异常处理
AgentChatController.stream 返回 Flux<ServerSentEvent<String>>。AgentChatServiceImpl.stream 内部:
图示来源
- AgentChatController.java:120-170
- AgentChatServiceImpl.java:345-574
章节来源
- AgentChatController.java:120-170
- AgentChatServiceImpl.java:345-574
依赖关系分析
网关侧依赖 PostgreSQL 存储服务/节点和用户绑定,依赖 Redis 缓存用户绑定和 token;业务侧依赖 PostgreSQL/pgvector、Redis、AgentScope 和外部 LLM。
graph LR
FE["前端"] --> GW["网关"]
GW --> PG["PostgreSQL<br/>gateway_service / gateway_node / user_route"]
GW --> REDIS["Redis<br/>user_route / token_cache"]
GW --> SV["ai-server"]
SV --> PG
SV --> REDIS
SV --> LLM["外部大模型"]
图示来源
- UserRouteService.java:1-117
- TokenResolver.java:1-100
- SaTokenWebConfig.java:1-65
- LlmService.java:1-200
章节来源
- UserRouteService.java:1-117
- TokenResolver.java:1-100
- SaTokenWebConfig.java:1-65
- LlmService.java:1-200
性能与容量特性
- 粘性路由读路径:先 Redis 再 PostgreSQL,Redis 失败降级直查数据库,写缓存失败不影响正确性。
- Token 解析路径:优先读
gateway:token:{serviceId}:{token},TTL 24 小时;未命中再查 Sa-Token;缓存写失败只记日志。
- 健康探测:默认每 10 秒一次,连续失败阈值默认 3 次,1 次成功恢复 UP;UNKNOWN 视为可用,避免启动期全部 503。
- Agent 流式:会话级 Semaphore 保证单流,避免记忆污染;LLM 调用分片超时和总时长双重兜底,区分模型 401/429 与真正超时。
- 登录响应绑定:采用 fire-and-forget 模式,不阻塞客户端响应;绑定失败只记日志,下次登录补写。
章节来源
- UserRouteService.java:1-117
- TokenResolver.java:1-100
- GatewayProperties.java:20-60
- NodeHealthRegistry.java:1-68
- AgentChatServiceImpl.java:345-574
- LlmService.java:120-200
异常场景与排查指南
登录失效
现象:后续请求返回 code=401,前端跳转到登录页。
数据流变化:
TokenResolver.resolveUserId 无法解析 userId;
StickyRouteFilter.decideForNormal 按匿名请求处理;
- ai-server 的 Sa-Token 校验失败,返回 code=401。
排查步骤:
- 检查 Redis 中
gateway:token:{serviceId}:{token} 是否过期或被清理。
- 检查 Sa-Token 共享 Redis 中对应 token 是否仍有效。
- 确认是否发生单端登录顶号、强制下线或手动 logout。
- 观察 ai-server 是否抛出未登录异常并转为 code=401。
章节来源
- TokenResolver.java:1-100
- StickyRouteFilter.java:60-120
- SaTokenWebConfig.java:1-65
节点不可用
现象:请求返回 503,提示用户未绑定节点或节点不可用。
数据流变化:
- 已绑定节点 disabled 或不存在 → 503;
- 已绑定节点健康状态为 DOWN → 503;
- 无可用健康节点进行匿名轮询 → 503。
注意:粘性路由不会因节点 DOWN 自动切换用户绑定,因为业务数据位于该节点本地磁盘,迁移风险较高。
排查步骤:
- 检查
gateway_service 和 gateway_node 表中节点是否启用。
- 检查
NodeHealthRegistry 健康状态是否为 DOWN。
- 检查后端健康检查路径是否可达。
- 检查用户绑定是否指向预期节点。
章节来源
- StickyRouteFilter.java:120-180
- NodeHealthRegistry.java:1-68
- NodeSelector.java:1-45
Agent 流式响应中断
现象:前端只收到部分 token,随后出现 error 或长时间无响应。
数据流变化:
- 会话锁冲突 → 返回“正在回复中”的 error 帧;
- AgentScope 或工具调用异常 → 返回 error 帧;
- LLM 超时或模型返回异常 → 返回 504 或 500 语义错误;
- 持久化 assistant 消息失败 → 日志报错,但仍可能已向前端推送过流。
排查步骤:
- 检查同一会话是否并发发送多条消息。
- 查看 AgentChatServiceImpl 的流式错误日志。
- 检查 GraphService、RAG/pgvector、Python 工具等外部依赖。
- 检查 LLM 模型配置的超时时间和可用性。
章节来源
- AgentChatServiceImpl.java:345-574
- LlmService.java:120-200
SSE 心跳与保活
当前代码中,Agent 流式响应以 token、tool_call、tool_result、done、error 等事件帧推进;并没有看到显式的周期性心跳帧。因此,“心跳保活”更准确地说应理解为:
- 前端应认为长时间无事件可能是模型慢、工具执行慢或连接断开;
- 网关和代理层应保持长连接存活;
- 前端应在合适时机检测连接中断并重试。
排查建议:
- 观察 SSE 连接是否被反向代理或防火墙切断;
- 检查 Agent 工具链是否卡住;
- 检查 LLM 流式输出是否长时间无 token;
- 在前端增加空闲超时与重连策略。
章节来源
- AgentChatController.java:120-170
- AgentChatServiceImpl.java:345-574
应用生命周期状态图
stateDiagram-v2
[*] --> 未绑定服务地址
未绑定服务地址 --> 等待授权 : "服务地址可用"
等待授权 --> 已加载授权 : "/sys/info 成功"
等待授权 --> 未绑定服务地址 : "授权获取失败"
已加载授权 --> 未登录 : "进入主界面"
未登录 --> 已登录 : "POST /admin/login 成功"
已登录 --> 已登录 : "后续请求正常"
已登录 --> 未登录 : "token 失效或 Sa-Token 未登录"
已登录 --> 节点不可用 : "绑定节点 DOWN"
节点不可用 --> 已登录 : "管理员修复节点或重新登录"
[本图为概念状态图,不直接映射具体源码文件,故无图示来源]
结论
清鉴 AI 调查工具的应用生命周期由前端服务地址绑定、授权单元读取、Gateway 粘性登录、Sa-Token 会话校验、Agent 流式推理和图谱/统计结果渲染共同构成。其关键设计点在于:
- 通过
StickyRouteFilter 保证同一用户会话长期绑定到同一个 ai-server 节点;
- 通过 Redis + PostgreSQL 两级缓存降低用户绑定和 token 解析延迟;
- 通过
SaTokenWebConfig 白名单机制分离公开接口与受保护接口;
- 通过 AgentScope 事件流将 LLM 与工具链的输出实时推送到前端;
- 通过健康检查和 DOWN 语义避免自动切换已绑定节点,保障数据一致性。
在实际排障中,应优先区分“前端地址配置问题”“网关路由/健康状态问题”“Sa-Token 会话问题”“Agent 工具链或 LLM 调用问题”,并结合日志、Redis、PostgreSQL 和外部模型 API 状态逐步定位。