关键数据流与应用生命周期.md 37 KB

关键数据流与应用生命周期

本文引用的文件

  • App.vue
  • serverSetting.ts
  • login.ts
  • license.ts
  • GatewayRegistry.java
  • ServiceInfo.java
  • NodeHealthRegistry.java
  • GatewayProperties.java
  • LoginRequestFilter.java
  • StickyRouteFilter.java
  • LoginResponseFilter.java
  • UserRouteService.java
  • TokenResolver.java
  • SaTokenWebConfig.java
  • SystemController.java
  • AgentChatController.java
  • AgentChatServiceImpl.java
  • LlmService.java

目录

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 典型用户工作流的数据流
  6. 详细组件分析
  7. 依赖关系分析
  8. 性能与容量特性
  9. 异常场景与排查指南
  10. 结论

引言

本文以清鉴 AI 调查工具的一个完整用户会话为主线,说明从客户端启动、绑定服务地址、获取授权单元、登录、Gateway 粘性路由、ai-server Sa-Token 校验,到 Agent 调用 LLM 与向量检索、图谱/统计结果返回前端渲染的关键数据流。文档同时给出时序图、状态图和流程图,标注“浏览器 → Gateway → ai-server → 外部模型/数据库”的跨进程、跨网络、跨服务边界,并覆盖 SSE 心跳保活、登录失效、节点不可用、Agent 流式响应等异常情况。

项目结构

清鉴系统在本仓库中主要包含三个运行时模块:

  • 前端 Electron 应用:负责服务地址绑定、授权信息展示、登录表单、Agent 对话和图谱渲染。
  • 网关 ai-gateway:Spring Cloud Gateway 实现,负责服务发现、健康检查、用户粘性路由、token 解析和后端转发。
  • 业务服务 ai-server:Spring Boot 应用,承载系统授权接口、Sa-Token 认证、Agent 聊天、LLM 调用、pgvector 向量检索和图谱服务。

    graph TB
    Browser["浏览器<br/>Electron 前端"] --> Gateway["网关 ai-gateway<br/>Spring Cloud Gateway"]
    Gateway --> Server["业务服务 ai-server<br/>Spring Boot"]
    Server --> DB["PostgreSQL<br/>业务库 + pgvector"]
    Server --> Redis["Redis<br/>会话 / 缓存"]
    Server --> LLM["外部大模型 API"]
    

图示来源

  • serverSetting.ts:1-120
  • GatewayRegistry.java:1-116
  • SaTokenWebConfig.java:1-65
  • AgentChatController.java:1-170

章节来源

  • serverSetting.ts:1-120
  • GatewayRegistry.java:1-116
  • GatewayProperties.java:1-81
  • SaTokenWebConfig.java:1-65

核心组件

章节来源

  • 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

架构总览

清鉴的工作流跨越四个边界:

  1. 浏览器进程内:Electron 前端读取 localStorage、组装请求、渲染 UI。
  2. 浏览器到网关:HTTP/HTTPS 请求,携带 x-token、Cookie 等。
  3. 网关到 ai-server:根据 ServiceInfo 中的 baseUrl 重写后转发。
  4. 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>>。服务端流程包括:

  1. 校验消息内容和会话权限;
  2. 通过会话级 Semaphore 保证同一会话只有一条流;
  3. 构建 AgentScope 的 RuntimeContext 和消息;
  4. 调用 AgentScope 的 streamEvents;
  5. 将 tool_call、tool_input、tool_result、token、done、error 事件映射为 SSE;
  6. 在 done 时持久化 assistant 回复;
  7. 工具链可能调用 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 内部:

  • 空消息直接返回 error 帧;
  • 订阅时解析会话,异常转为 error 帧;
  • 使用会话级 Semaphore 防止同一会话并发流;
  • 将 AgentScope 事件映射为 tool_call、tool_input、tool_result、token、done、error;
  • done 时保存 assistant 消息;
  • 错误时保存错误消息。

    flowchart TD
    StreamStart["收到 /chat/stream 请求"] --> Validate["校验消息内容与会话"]
    Validate --> Valid{"消息合法?"}
    Valid -->|否| ErrorFrame["返回 error SSE"]
    Valid -->|是| AcquireLock["tryAcquire 会话锁"]
    AcquireLock --> Locked{"获得锁?"}
    Locked -->|否| BusyFrame["返回 error:正在回复中"]
    Locked -->|是| BuildAgent["构建 AgentScope 会话与消息"]
    BuildAgent --> StreamEvents["streamEvents 获取事件流"]
    StreamEvents --> ToolCall["tool_call / tool_input / tool_result"]
    StreamEvents --> Token["token 增量"]
    StreamEvents --> Done["done 结束"]
    StreamEvents --> Error["error 异常"]
    Done --> PersistAssistant["持久化 assistant 消息"]
    Error --> PersistError["持久化错误消息"]
    

图示来源

  • 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。

排查步骤:

  1. 检查 Redis 中 gateway:token:{serviceId}:{token} 是否过期或被清理。
  2. 检查 Sa-Token 共享 Redis 中对应 token 是否仍有效。
  3. 确认是否发生单端登录顶号、强制下线或手动 logout。
  4. 观察 ai-server 是否抛出未登录异常并转为 code=401。

章节来源

  • TokenResolver.java:1-100
  • StickyRouteFilter.java:60-120
  • SaTokenWebConfig.java:1-65

节点不可用

现象:请求返回 503,提示用户未绑定节点或节点不可用。 数据流变化:

  • 已绑定节点 disabled 或不存在 → 503;
  • 已绑定节点健康状态为 DOWN → 503;
  • 无可用健康节点进行匿名轮询 → 503。

注意:粘性路由不会因节点 DOWN 自动切换用户绑定,因为业务数据位于该节点本地磁盘,迁移风险较高。

排查步骤:

  1. 检查 gateway_service 和 gateway_node 表中节点是否启用。
  2. 检查 NodeHealthRegistry 健康状态是否为 DOWN。
  3. 检查后端健康检查路径是否可达。
  4. 检查用户绑定是否指向预期节点。

章节来源

  • StickyRouteFilter.java:120-180
  • NodeHealthRegistry.java:1-68
  • NodeSelector.java:1-45

Agent 流式响应中断

现象:前端只收到部分 token,随后出现 error 或长时间无响应。 数据流变化:

  • 会话锁冲突 → 返回“正在回复中”的 error 帧;
  • AgentScope 或工具调用异常 → 返回 error 帧;
  • LLM 超时或模型返回异常 → 返回 504 或 500 语义错误;
  • 持久化 assistant 消息失败 → 日志报错,但仍可能已向前端推送过流。

排查步骤:

  1. 检查同一会话是否并发发送多条消息。
  2. 查看 AgentChatServiceImpl 的流式错误日志。
  3. 检查 GraphService、RAG/pgvector、Python 工具等外部依赖。
  4. 检查 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 状态逐步定位。

组件 职责 关键输入 关键输出
前端设置模块 读取并校验 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 文本、用量、耗时