本文引用的文件
本指南面向开发者、运维和一线支持人员,聚焦实际排障路径:从网关粘性路由、后端 LLM 与 RAG、pgvector 向量检索、地图加载、许可证校验到 Electron 主进程崩溃和前端资源加载异常。文档提供日志位置、请求链路检查点、复现步骤、诊断清单和恢复建议,帮助快速定位“登录成功仍 503”“Agent SSE 断连”“pgvector 无结果”等问题根因。
本项目由三个主要运行单元组成:
ai-electron/,负责桌面端窗口、生命周期、离线地图和前端资源。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"]
图示来源
章节来源
章节来源
粘性路由是本次调试的关键入口。它按以下顺序处理请求:
LoginRequestFilter,解析 username 并设置匿名轮询或候选节点。StickyRouteFilter 根据是否登录决定节点选择策略,并在普通请求中解析 x-token。X-Gateway-Node 响应头。若节点不存在、停用或健康检查失败,抛出 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 的核心职责是“按用户粘性选择节点并重写 URL”。它区分两类请求:
x-token 解析 userId,再查绑定节点;若找不到绑定且服务有默认节点,则尝试绑定默认节点;否则抛 503。关键检查点:
x-token 是否存在、非空。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["继续下游转发"]
图示来源
章节来源
LlmService 是“直连大模型”的服务:它不负责 Agent 工具链,而是把提示词交给模型并聚合流式分片。其关键行为包括:
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 事件流"
图示来源
章节来源
RagSchemaService 是向量索引查询门面,对外提供:
AiCleanTemplateVectorIndex 负责真实向量逻辑:
整体 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 : "可能通过嵌入提供者"
图示来源
章节来源
LicenseUtil 通过系统命令执行激活器,对 license.xlts 进行校验,并将结果缓存 60 秒。常见错误码映射为不同语义:
章节来源
前端地图模块支持两种 PMTiles 读取方式:
若未配置本机离线地图目录,前端会同时注册内置 china.pmtiles 作为兜底来源。
章节来源
粘性路由依赖多个内部组件:
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"]
图示来源
章节来源
[本节为通用性能讨论,不直接分析具体文件]
典型现象:
排查要点:
LoginRequestFilter 是否能解析 username;若解析失败,本次按匿名轮询,不会写绑定。LoginResponseFilter 是否能解析登录成功响应结构;若响应体超 256KB、非 JSON 或结构不符,会跳过绑定。gateway:token:{serviceId}:{token} 缓存。X-Gateway-Node 是否与预期一致。恢复建议:
code=200 且 data 包含 token、userId、username。章节来源
典型现象:
排查要点:
StickyUnavailableException,表示绑定节点不可用或未绑定。GatewayErrorHandler 是否输出 sticky route unavailable 日志。恢复建议:
LoginResponseFilter 完成绑定。章节来源
典型现象:
排查要点:
恢复建议:
章节来源
典型现象:
排查要点:
恢复建议:
章节来源
典型现象:
排查要点:
readBinaryFileRange 是否返回 success。恢复建议:
章节来源
典型现象:
排查要点:
恢复建议:
章节来源
典型现象:
排查要点:
main.ts 是否正常注册生命周期。恢复建议:
章节来源
典型现象:
排查要点:
恢复建议:
[本节为通用前端排查建议,不直接分析具体文件]
检查项:
X-Gateway-Node 响应头。附件上传由 AgentChatController.uploadAttachment 暴露,接收 multipart/form-data,并按 workspaceId、sessionId 和当前登录 userId 做归属校验。
排查建议:
章节来源
通用复现步骤:
恢复建议:
本项目的调试主线围绕“用户粘性路由、LLM 调用、RAG 向量检索、pgvector、地图资源和 Electron 环境”展开。排查时应优先确认请求是否被路由到正确节点,再逐层验证后端 LLM、RAG、向量索引和本地资源。对于 503,应重点检查用户绑定、节点健康和服务默认节点;对于 SSE 断连,应区分网关超时、上游连接问题和模型侧超时;对于 pgvector 无结果,应先确认索引状态和嵌入模型可用性;对于地图加载失败,应区分 Electron 本地读盘与 HTTP Range 两种路径。按照本文的诊断清单、复现步骤和恢复建议,可以快速缩小问题范围并定位根因。