调试与问题排查.md 28 KB

调试与问题排查

本文引用的文件

  • StickyRouteFilter.java
  • LoginRequestFilter.java
  • LoginResponseFilter.java
  • StickyUnavailableException.java
  • GatewayErrorHandler.java
  • LlmService.java
  • RagSchemaService.java
  • AiCleanTemplateVectorIndex.java
  • EmbeddingService.java
  • AgentChatController.java
  • LicenseUtil.java
  • offlineMap.ts
  • main.ts
  • lifecycle.ts

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论

简介

本指南面向开发者、运维和一线支持人员,聚焦实际排障路径:从网关粘性路由、后端 LLM 与 RAG、pgvector 向量检索、地图加载、许可证校验到 Electron 主进程崩溃和前端资源加载异常。文档提供日志位置、请求链路检查点、复现步骤、诊断清单和恢复建议,帮助快速定位“登录成功仍 503”“Agent SSE 断连”“pgvector 无结果”等问题根因。

项目结构

本项目由三个主要运行单元组成:

  • 前端与 Electron 客户端:ai-electron/,负责桌面端窗口、生命周期、离线地图和前端资源。
  • API 网关:ai-gateway/,负责登录预处理、粘性路由、节点选择、URL 重写和统一错误输出。
  • 业务服务端:ai-server/,承载 Agent 聊天、LLM 直调、RAG Schema 检索、向量索引、附件上传和许可证校验。

    graph TB
    Client["Electron 前端"] --> Gateway["API 网关<br/>StickyRouteFilter / LoginRequestFilter / LoginResponseFilter"]
    Gateway --> Server["业务服务<br/>AgentChatController / LlmService / RagSchemaService"]
    Server --> VectorDB["pgvector 向量表"]
    Server --> Embedding["本地或在线嵌入模型"]
    Server --> License["许可证校验工具"]
    Client --> MapSource["离线地图 PMTiles<br/>ElectronPmtilesSource / HttpPmtilesSource"]
    

图示来源

  • StickyRouteFilter.java:1-180
  • LoginRequestFilter.java:1-120
  • LoginResponseFilter.java:1-176
  • AgentChatController.java:1-170
  • LlmService.java:1-200
  • offlineMap.ts:1-200

章节来源

  • main.ts:1-19
  • lifecycle.ts:1-73

核心组件

  • 粘性路由过滤器:根据 token 或 username 解析用户并绑定到固定节点;若绑定节点不可用则返回 503,不自动切换。
  • 登录前置与后置过滤器:登录前缓存请求体并提取 username,登录后把 token、userId、username 写入绑定表和 token 缓存。
  • LLM 服务:直接调用大模型,支持文本问答、流式 SSE、超时与用量统计。
  • RAG Schema 服务:对外暴露可用状态、重建接口和自然语言选表检索。
  • pgvector 向量索引:将模板元数据向量化,支持增量更新、全量重建和 fail-open 降级。
  • 许可证工具:通过系统命令校验 license 文件,带 60 秒结果缓存。
  • 离线地图模块:优先使用本机 PMTiles 绝对路径,否则回退到内置静态资源 HTTP Range 读取。

章节来源

  • StickyRouteFilter.java:1-180
  • LoginRequestFilter.java:1-120
  • LoginResponseFilter.java:1-176
  • LlmService.java:1-200
  • RagSchemaService.java:1-181
  • AiCleanTemplateVectorIndex.java:1-200
  • LicenseUtil.java:1-163
  • offlineMap.ts:1-200

架构总览

粘性路由是本次调试的关键入口。它按以下顺序处理请求:

  1. 登录请求先经过 LoginRequestFilter,解析 username 并设置匿名轮询或候选节点。
  2. StickyRouteFilter 根据是否登录决定节点选择策略,并在普通请求中解析 x-token。
  3. 选中节点后重写目标 URL,设置 X-Gateway-Node 响应头。
  4. 若节点不存在、停用或健康检查失败,抛出 StickyUnavailableException,由 GatewayErrorHandler 统一输出 503。

    sequenceDiagram
    participant FE as "前端"
    participant GW as "网关 StickyRouteFilter"
    participant SRV as "后端服务"
    participant DB as "pgvector / 数据库"
    participant LM as "本地或在线模型"
    
    FE->>GW: "POST 登录"
    GW->>SRV: "转发登录请求"
    SRV-->>GW: "Result{code=200, data.token, userId, username}"
    GW->>GW: "LoginResponseFilter 解析并绑定节点"
    GW-->>FE: "登录成功"
    
    FE->>GW: "携带 x-token 的业务请求"
    GW->>GW: "token→userId→查找绑定节点"
    GW->>SRV: "转发到固定节点"
    SRV->>DB: "RAG 向量检索"
    SRV->>LM: "LLM 调用"
    SRV-->>FE: "SSE 或 JSON 结果"
    

图示来源

  • StickyRouteFilter.java:1-180
  • LoginResponseFilter.java:1-176
  • AgentChatController.java:1-170

章节来源

  • StickyUnavailableException.java:1-25
  • GatewayErrorHandler.java:1-98

详细组件分析

粘性路由与登录流程

StickyRouteFilter 的核心职责是“按用户粘性选择节点并重写 URL”。它区分两类请求:

  • 登录请求:如果 username 已绑定,则复用该节点;未绑定时轮询一个健康候选节点,但不在登录阶段写库。
  • 普通请求:从 x-token 解析 userId,再查绑定节点;若找不到绑定且服务有默认节点,则尝试绑定默认节点;否则抛 503。

关键检查点:

  • 请求头 x-token 是否存在、非空。
  • 登录请求是否命中配置的 loginFullPath。
  • 登录响应是否为 Result{code=200, data:{token, userId, username}}。
  • 最终响应头 X-Gateway-Node 是否包含期望节点 ID。
  • 目标 URL 是否由节点 origin + 原始 rawPath + rawQuery 拼接而成。

    flowchart TD
    Start["收到请求"] --> CheckRoute["检查路由与服务是否启用"]
    CheckRoute --> IsLogin{"是否登录请求?"}
    IsLogin -->|是| DecideLogin["按 username 查绑定节点<br/>未绑定则轮询候选"]
    IsLogin -->|否| ReadToken["读取 x-token"]
    ReadToken --> TokenValid{"token 能解析出 userId?"}
    TokenValid -->|否| Anonymous["匿名轮询健康节点"]
    TokenValid -->|是| FindBind["按 userId 查绑定节点"]
    FindBind --> Bound{"是否有绑定节点?"}
    Bound -->|否| DefaultNode{"服务是否有 defaultNodeId?"}
    DefaultNode -->|是| BindDefault["绑定默认节点"]
    DefaultNode -->|否| Error503["抛 503:用户未绑定节点"]
    Bound -->|是| RouteCheck["校验节点存在、启用、健康"]
    BindDefault --> RouteCheck
    Anonymous --> RouteCheck
    DecideLogin --> RouteCheck
    RouteCheck --> RewriteUrl["重写 GATEWAY_REQUEST_URL_ATTR<br/>设置 X-Gateway-Node"]
    RewriteUrl --> End["继续下游转发"]
    

图示来源

  • StickyRouteFilter.java:1-180
  • LoginRequestFilter.java:1-120
  • LoginResponseFilter.java:1-176

章节来源

  • StickyRouteFilter.java:1-180
  • LoginRequestFilter.java:1-120
  • LoginResponseFilter.java:1-176
  • StickyUnavailableException.java:1-25
  • GatewayErrorHandler.java:1-98

LLM 调用与 Agent SSE

LlmService 是“直连大模型”的服务:它不负责 Agent 工具链,而是把提示词交给模型并聚合流式分片。其关键行为包括:

  • 参数校验失败返回 400。
  • 模型不存在返回 404。
  • 模型调用失败返回 500。
  • 流式超时返回 504,且明确区分“片间超时”和“总时长超时”。
  • 记录输入输出 token 和耗时。

Agent SSE 由 AgentChatController.stream 暴露,前端按事件类型消费:tool_call、tool_input、tool_result、token、done、error。

sequenceDiagram
    participant FE as "前端"
    participant GW as "网关"
    participant Ctrl as "AgentChatController"
    participant LLM as "LlmService"
    participant Model as "外部模型"

    FE->>GW: "POST /chat/stream"
    GW->>Ctrl: "转发到具体节点"
    Ctrl->>LLM: "构建消息并流式调用"
    LLM->>Model: "stream(messages)"
    Model-->>LLM: "分片响应"
    LLM-->>Ctrl: "拼接文本、用量、耗时"
    Ctrl-->>FE: "ServerSentEvent 事件流"

图示来源

  • AgentChatController.java:1-170
  • LlmService.java:1-200

章节来源

  • LlmService.java:1-200
  • AgentChatController.java:1-170

RAG Schema 与 pgvector 向量检索

RagSchemaService 是向量索引查询门面,对外提供:

  • 能力可用性判断:需要开启 RAG 开关且底层向量索引可用。
  • 重建接口:幂等 DROP 并全量写入全局 pgvector 表。
  • 状态接口:status 为 SUCCESS 或 IDLE。
  • 自然语言选表检索:若索引为空,抛出 409 提示先重建;若查了但没命中,返回空列表。

AiCleanTemplateVectorIndex 负责真实向量逻辑:

  • 事实来源是两套模板元数据,不扫描案件 DuckDB。
  • 支持增量索引、删除、全量重建。
  • 启动时可按配置后台自举重建。
  • 整体 fail-open:嵌入模型或 pgvector 不可用时降级为无召回。

    classDiagram
    class RagSchemaService {
        +isAvailable() boolean
        +reindexWorkspace(workspaceId) RagIndexStatusVO
        +getStatus(workspaceId) RagIndexStatusVO
        +search(query, topK) List~RagSearchResultVO~
    }
    
    class AiCleanTemplateVectorIndex {
        +isAvailable() boolean
        +unavailableMessage() String
        +rebuildNow() int
        +searchTables(query, limit) List~TableSchemaHit~
        +status() IndexStatus
    }
    
    class EmbeddingService {
        +embed(text) float[]
        +embedBatch(texts) List~float[]~
        +cosineSimilarity(a,b) double
        +warmUpAsync() void
    }
    
    RagSchemaService --> AiCleanTemplateVectorIndex : "使用"
    AiCleanTemplateVectorIndex --> EmbeddingService : "可能通过嵌入提供者"
    

图示来源

  • RagSchemaService.java:1-181
  • AiCleanTemplateVectorIndex.java:1-200
  • EmbeddingService.java:1-200

章节来源

  • RagSchemaService.java:1-181
  • AiCleanTemplateVectorIndex.java:1-200
  • EmbeddingService.java:1-200

许可证校验

LicenseUtil 通过系统命令执行激活器,对 license.xlts 进行校验,并将结果缓存 60 秒。常见错误码映射为不同语义:

  • 0:有效。
  • 10001:许可证文件无效。
  • 10002:过期。
  • 10003:机器码不匹配。
  • 其他:未授权。

章节来源

  • LicenseUtil.java:1-163

地图加载与 PMTiles

前端地图模块支持两种 PMTiles 读取方式:

  • Electron 本地读盘:当样式 source url 为本机绝对路径时,通过 IPC 调用主进程按需读取字节范围。
  • HTTP Range:当 source url 为静态资源 URL 时,通过 fetch 的 Range 头读取。

若未配置本机离线地图目录,前端会同时注册内置 china.pmtiles 作为兜底来源。

章节来源

  • offlineMap.ts:1-200

依赖关系分析

粘性路由依赖多个内部组件:

  • GatewayRegistry:服务注册信息。
  • NodeHealthRegistry:节点健康状态。
  • NodeSelector:从健康节点中选出候选。
  • TokenResolver:token 与 userId 的解析与缓存。
  • UserRouteService:用户与节点的绑定关系。
  • GatewayErrorHandler:统一错误输出。

    graph LR
    StickyRouteFilter["StickyRouteFilter"] --> GatewayRegistry["GatewayRegistry"]
    StickyRouteFilter --> NodeHealthRegistry["NodeHealthRegistry"]
    StickyRouteFilter --> NodeSelector["NodeSelector"]
    StickyRouteFilter --> TokenResolver["TokenResolver"]
    StickyRouteFilter --> UserRouteService["UserRouteService"]
    StickyRouteFilter --> ErrorHandler["GatewayErrorHandler"]
    

图示来源

  • StickyRouteFilter.java:1-180
  • GatewayErrorHandler.java:1-98

章节来源

  • StickyRouteFilter.java:1-180

性能考虑

  • LLM 流式调用避免一次性阻塞,但需同时关注片间超时和总时长超时。
  • 本地嵌入模型首次加载权重较大,可通过 eager-load 或预热提前加载。
  • 向量索引重建是全量覆盖操作,并发重建通过互斥保护。
  • 许可证校验使用 60 秒缓存,减少频繁执行系统命令的成本。

[本节为通用性能讨论,不直接分析具体文件]

故障排查指南

一、常见问题定位路径

1. Gateway 粘性路由无法绑定用户

典型现象:

  • 登录后再次请求返回 503,提示“用户未绑定节点”或“用户绑定的节点不存在或已停用”。
  • 同一用户在多节点部署下被路由到错误节点,导致会话或附件数据缺失。

排查要点:

  • 确认登录请求是否命中配置的 loginFullPath。
  • 检查 LoginRequestFilter 是否能解析 username;若解析失败,本次按匿名轮询,不会写绑定。
  • 检查 LoginResponseFilter 是否能解析登录成功响应结构;若响应体超 256KB、非 JSON 或结构不符,会跳过绑定。
  • 检查 token 是否进入 gateway:token:{serviceId}:{token} 缓存。
  • 检查用户绑定表是否落库,以及绑定节点是否 enabled 且健康。
  • 查看响应头 X-Gateway-Node 是否与预期一致。

恢复建议:

  • 重新登录一次,确保响应为 code=200 且 data 包含 token、userId、username。
  • 若节点被停用,联系管理员恢复节点或调整默认节点。
  • 若 token 失效或被顶下线,清理浏览器缓存后重新登录。

章节来源

  • LoginRequestFilter.java:1-120
  • LoginResponseFilter.java:1-176
  • StickyRouteFilter.java:1-180

2. 登录成功后仍 503

典型现象:

  • 登录成功,但后续请求直接返回 503。
  • 网关日志出现“sticky route unavailable”。

排查要点:

  • 503 通常来自 StickyUnavailableException,表示绑定节点不可用或未绑定。
  • 检查 GatewayErrorHandler 是否输出 sticky route unavailable 日志。
  • 检查用户是否真的被绑定到某个节点;若未绑定且没有 defaultNodeId,会抛 503。
  • 检查节点是否在注册中心启用,健康检查是否 DOWN。

恢复建议:

  • 重新触发登录,让 LoginResponseFilter 完成绑定。
  • 检查服务配置中的 defaultNodeId。
  • 恢复或重启后端节点,使健康检查变为 UP。

章节来源

  • StickyUnavailableException.java:1-25
  • GatewayErrorHandler.java:1-98

3. Agent SSE 断连或心跳异常

典型现象:

  • 聊天界面长时间无新 token。
  • 前端显示 tool_call 或 token 事件中断。
  • 后端日志出现模型调用超时或连接断开。

排查要点:

  • 确认网关层是否返回 502/504,上游连接失败或超时会被网关捕获。
  • 检查 LLM 调用是否超时:片间超时和总时长超时都要看。
  • 检查 Agent SSE 事件序列是否完整:tool_call → tool_input → tool_result → token* → done/error。
  • 检查网络代理、防火墙是否中断长连接。

恢复建议:

  • 重试发送消息,观察是否恢复。
  • 调整模型超时配置。
  • 检查外部模型 API Key、限流和可用性。

章节来源

  • LlmService.java:1-200
  • AgentChatController.java:1-170
  • GatewayErrorHandler.java:1-98

4. pgvector 向量检索无结果

典型现象:

  • 调用 RAG Schema 检索返回空列表。
  • 状态接口 status 为 IDLE。
  • 重建接口报错或长时间无响应。

排查要点:

  • 检查 RAG 开关是否开启。
  • 检查向量索引状态是否为 IDLE,文档数是否为 0。
  • 检查嵌入模型是否可用:本地模型目录是否存在,或在线 embedding 是否配置。
  • 检查 pgvector 表是否存在,维度是否与当前模型一致。
  • 查看重建日志,确认是否发生连续失败熔断。

恢复建议:

  • 调用重建接口重建向量索引。
  • 修复嵌入模型配置或下载本地模型权重。
  • 修复 pgvector 连接、权限或表结构。

章节来源

  • RagSchemaService.java:1-181
  • AiCleanTemplateVectorIndex.java:1-200
  • EmbeddingService.java:1-200

5. 地图加载失败

典型现象:

  • 地图空白或瓦片不加载。
  • 控制台出现 Range 请求失败或 IPC 读取失败。

排查要点:

  • 检查离线地图目录是否配置,localStorage 中 key 是否正确。
  • 若使用本机路径,检查 IPC readBinaryFileRange 是否返回 success。
  • 若使用内置静态资源,检查 pmtiles 文件是否可被 HTTP Range 访问。
  • 检查样式 source url 与 source key 是否一致。

恢复建议:

  • 修正离线地图目录路径。
  • 重新放置 china.pmtiles 和样式 JSON。
  • 清除本地缓存后刷新页面。

章节来源

  • offlineMap.ts:1-200

6. 许可证校验失败

典型现象:

  • 应用提示未激活、过期或机器码不匹配。
  • 激活命令执行失败。

排查要点:

  • 检查 license.xlts 文件是否存在。
  • 检查激活器可执行文件路径是否正确。
  • 查看许可证校验日志中的授权码和错误消息。
  • 注意 60 秒缓存可能导致旧状态未及时刷新。

恢复建议:

  • 重新生成并安装正确的 license 文件。
  • 修复激活器权限或路径。
  • 等待缓存过期或重启服务。

章节来源

  • LicenseUtil.java:1-163

7. Electron 主进程崩溃

典型现象:

  • 应用闪退或主窗口无法打开。
  • 生命周期日志不完整。

排查要点:

  • 检查 Electron 主进程入口 main.ts 是否正常注册生命周期。
  • 检查 preload lifecycle 日志是否打印 ready、electron-app-ready、window-ready。
  • 检查主窗口配置、显示选项和 IPC 桥接是否初始化。
  • 收集 Electron 崩溃 dump 和标准输出/错误输出。

恢复建议:

  • 重启 Electron 应用。
  • 清理临时窗口状态或缓存。
  • 检查插件或 preload 脚本是否抛出未捕获异常。

章节来源

  • main.ts:1-19
  • lifecycle.ts:1-73

8. 前端资源加载异常

典型现象:

  • 页面白屏或静态资源 404。
  • Vite 开发服务器或 Electron 资源路径不正确。

排查要点:

  • 检查 BASE_URL 和资源路径拼接。
  • 检查打包后的 public/resource 目录是否包含地图 pmtiles 和样式文件。
  • 检查 Electron 主进程加载的前端资源地址。
  • 检查网络拦截、代理或跨域限制。

恢复建议:

  • 重新构建前端资源。
  • 修正打包配置和资源路径。
  • 关闭代理或调整跨域配置。

[本节为通用前端排查建议,不直接分析具体文件]

二、StickyRouteFilter 调试清单

检查项:

  • 登录请求 body 中是否包含 username。
  • 登录响应是否为 code=200 且 data 包含 token、userId、username。
  • token 是否可解析为 userId。
  • 用户是否已绑定节点。
  • 绑定节点是否 enabled 且健康。
  • 是否设置了 X-Gateway-Node 响应头。
  • 目标 URL 是否由节点 origin + 原始 rawPath + rawQuery 拼接。
  • 网关错误日志是否包含 sticky route unavailable。

三、Agent LLM 调用验证步骤

  1. 使用默认模型发送一段简短提示词。
  2. 观察 LLM 日志是否记录 model、input tokens、output tokens、耗时。
  3. 使用流式接口发送相同内容,确认 token 事件持续到达。
  4. 故意传入非法参数,确认返回 400。
  5. 配置不存在的模型,确认返回 404。
  6. 模拟模型超时,确认返回 504。

四、RAG Schema 检索验证步骤

  1. 调用状态接口,确认 status 不是 IDLE。
  2. 若为 IDLE,调用重建接口。
  3. 等待重建完成后再次查询状态。
  4. 使用自然语言查询表结构,确认返回物理表名和列名。
  5. 若结果为空,先区分“索引为空”还是“语义未命中”。

五、Python 执行器和附件上传

附件上传由 AgentChatController.uploadAttachment 暴露,接收 multipart/form-data,并按 workspaceId、sessionId 和当前登录 userId 做归属校验。

排查建议:

  • 检查上传接口是否返回 attachmentVO。
  • 检查附件是否落盘成功。
  • 检查 Python 执行器是否能读取附件路径。
  • 检查 RAG 是否对附件做了索引或内联处理。

章节来源

  • AgentChatController.java:1-170

六、日志查看位置

  • 服务端日志:查看业务服务输出,重点关注 LLM 调用、RAG 重建、许可证校验、SSE 事件。
  • 网关日志:重点关注 sticky route unavailable、upstream connect failed、upstream timeout。
  • Electron 控制台:查看 preload lifecycle、IPC 调用、地图 PMTiles 读取结果。
  • 网络请求:检查登录接口、x-token、X-Gateway-Node、SSE 事件流、地图 Range 请求。

七、复现与恢复建议

通用复现步骤:

  1. 清理浏览器缓存和 token。
  2. 重新登录,记录登录请求和响应。
  3. 发起业务请求,记录响应头和响应体。
  4. 查看网关和服务端日志。
  5. 若是向量检索问题,先查状态,再重建。
  6. 若是地图问题,先查本地路径和内置资源。
  7. 若是许可证问题,先查 license 文件和激活器命令。
  8. 若是 Electron 崩溃,先收集主进程日志和崩溃 dump。

恢复建议:

  • 网关问题优先恢复节点健康和用户绑定。
  • LLM 问题优先检查模型配置和外部 API。
  • RAG 问题优先重建向量索引并修复嵌入模型。
  • 地图问题优先修复 PMTiles 文件或静态资源路径。
  • 许可证问题优先更换正确 license 文件。
  • Electron 问题优先重启应用并检查 preload 初始化。

结论

本项目的调试主线围绕“用户粘性路由、LLM 调用、RAG 向量检索、pgvector、地图资源和 Electron 环境”展开。排查时应优先确认请求是否被路由到正确节点,再逐层验证后端 LLM、RAG、向量索引和本地资源。对于 503,应重点检查用户绑定、节点健康和服务默认节点;对于 SSE 断连,应区分网关超时、上游连接问题和模型侧超时;对于 pgvector 无结果,应先确认索引状态和嵌入模型可用性;对于地图加载失败,应区分 Electron 本地读盘与 HTTP Range 两种路径。按照本文的诊断清单、复现步骤和恢复建议,可以快速缩小问题范围并定位根因。