开发者指南.md 36 KB

开发者指南

本文引用的文件

  • pom.xml
  • ai-gateway/pom.xml
  • ai-server/pom.xml
  • ai-gateway/src/main/resources/application.yaml
  • ai-gateway/src/main/resources/application-dev.yaml
  • ai-server/src/main/resources/application.yaml
  • ai-server/src/main/resources/application-dev.yaml
  • deploy/env.sh
  • cmd/uninstall.sh
  • cmd/uninstall.bat
  • readme.md
  • ai-electron/package.json
  • ai-electron/frontend/package.json
  • ai-electron/frontend/eslint.config.mjs
  • ai-electron/frontend/.prettierrc.mjs
  • ai-electron/frontend/stylelint.config.mjs
  • ai-electron/frontend/README.md
  • ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java
  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java
  • ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java
  • ai-gateway/src/main/java/com/zsjz/gateway/route/NodeSelector.java
  • ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminController.java
  • ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java
  • ai-server/src/main/java/com/zsjz/ai/module/agent/insight/controller/InsightController.java
  • ai-electron/frontend/src/api/sys/menu.ts

目录

  1. 简介
  2. 项目结构
  3. 开发环境准备
  4. 常用命令
  5. 新增后端模块
  6. 新增前端页面
  7. 新增 IPC 接口
  8. 新增数据库表与变更脚本
  9. 代码风格与检查
  10. 提交规范与分支策略
  11. 架构总览
  12. 关键组件分析
  13. 依赖关系分析
  14. 性能注意事项
  15. 调试技巧
  16. 常见问题排查
  17. 结论

简介

本项目是清鉴 AI 调查工具,采用多模块 Maven 后端 + Electron 桌面客户端 + Vue 3 前端的组合:

层级 位置 职责
网关层 ai-gateway Spring Cloud Gateway WebFlux,按用户粘性路由转发请求,管理后端节点与用户绑定关系
业务层 ai-server Spring Boot 业务服务,承载认证、Agent、图谱、清洗、向量检索、案件库等能力
桌面层 ai-electron Electron 主进程、预加载桥接、打包脚本
前端层 ai-electron/frontend Vite + Vue 3 + TypeScript + Ant Design Vue 管理界面
数据层 PostgreSQL + Redis + Elasticsearch + Neo4j 平台库、缓存、全文检索、图谱(可选)
部署层 deploy/env.sh、cmd/* Linux 环境变量下发、卸载清理

根 pom.xml 把 ai-server 和 ai-gateway 作为 Spring Boot 子模块统一管理。

章节来源

  • pom.xml:1-23

项目结构

graph TB
    Root["根工程<br/>pom.xml"] --> Gateway["ai-gateway<br/>Spring Cloud Gateway"]
    Root --> Server["ai-server<br/>Spring Boot 业务服务"]
    Root --> Electron["ai-electron<br/>Electron 桌面客户端"]
    Electron --> Frontend["ai-electron/frontend<br/>Vue 3 + Vite"]

    subgraph "网关"
        GWApp["GatewayApplication"]
        Sticky["StickyRouteFilter<br/>粘性路由过滤器"]
        Admin["AdminController<br/>管理接口"]
    end

    subgraph "后端"
        Auth["AuthController<br/>登录/登出/信息"]
        Insight["InsightController<br/>AI 研判 SSE"]
    end

    subgraph "前端"
        ApiMenu["api/sys/menu.ts<br/>菜单 API 示例"]
    end

    Root --> Gateway
    Root --> Server
    Root --> Electron
    Electron --> Frontend
    Gateway --> Auth
    Gateway --> Insight
    Frontend --> Auth

图表来源

  • pom.xml:1-23
  • ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java:1-23
  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java:1-180
  • ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminController.java:1-153
  • ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java:1-82
  • ai-server/src/main/java/com/zsjz/ai/module/agent/insight/controller/InsightController.java:1-127
  • ai-electron/frontend/src/api/sys/menu.ts:1-50

章节来源

  • pom.xml:1-23
  • ai-electron/frontend/README.md:1-120

开发环境准备

后端要求

项目 版本或说明
Java 25
Maven 用于聚合构建 ai-server 与 ai-gateway
PostgreSQL 必须安装 pgvector 扩展
Redis sa-token 登录态与网关路由缓存硬依赖
Elasticsearch 全文检索,默认单节点
Neo4j 可选,仅图谱能力需要

后端配置统一写在 YAML 中,并大量使用 ${ENV_NAME:默认值} 占位符;Linux 部署时通过 deploy/env.sh 提供环境变量覆盖。

前端要求

项目 版本或说明
Node.js `>=20.19
pnpm 包管理器,已锁定版本
Vite 开发服务器与构建工具
Vue 3 + TypeScript 主要技术栈
Ant Design Vue UI 组件库

章节来源

  • ai-gateway/pom.xml:1-30
  • ai-server/pom.xml:1-30
  • ai-electron/frontend/package.json:120-162
  • ai-server/src/main/resources/application.yaml:1-40
  • ai-server/src/main/resources/application-dev.yaml:1-25
  • deploy/env.sh:1-30

常用命令

Maven 构建

根目录执行:

mvn clean compile
mvn package
mvn test

父 POM 将 ai-server 与 ai-gateway 作为子模块参与构建。ai-gateway 的构建阶段会把仓库根 sql/gateway.sql 复制到 classpath:db/gateway.sql,供 Spring SQL init 启动建表。

章节来源

  • pom.xml:1-23
  • ai-gateway/pom.xml:85-120

前端开发命令

进入 ai-electron/frontend 目录:

命令 作用
pnpm dev 启动 Vite 开发服务器
pnpm serve 等同于 pnpm dev
pnpm build 生产构建
pnpm build:tomcat 输出 Tomcat 可部署产物
pnpm preview 本地预览构建产物
pnpm type:check TypeScript 类型检查
pnpm lint:eslint ESLint 修复
pnpm lint:prettier Prettier 格式化检查
pnpm lint:stylelint Stylelint 修复
pnpm lint:all 完整校验链:安装、类型检查、ESLint、Prettier、Stylelint
pnpm reinstall 删除 lock 和 node_modules 后重装

章节来源

  • ai-electron/frontend/package.json:1-40

Electron 打包命令

在 ai-electron 目录执行:

命令 作用
pnpm dev 通过 ee-bin 启动开发模式
pnpm start 启动已构建的 Electron 应用
pnpm build 构建前端、Electron 并执行加密
pnpm dev-frontend 只以 ee-bin 方式启动前端
pnpm dev-electron 只以 ee-bin 方式启动 Electron
pnpm build-w 构建 Windows 64 位
pnpm build-we 构建 Windows Electron 版本
pnpm build-m 构建 macOS
pnpm build-m-x86 构建 macOS x86
pnpm build-m-arm64 构建 macOS arm64
pnpm build-l 构建 Linux

章节来源

  • ai-electron/package.json:1-42

安装与卸载

路径 作用
ai-electron/frontend/bin/install.sh / install.bat 前端安装脚本
ai-electron/frontend/bin/startup.sh / startup.bat 前端启动脚本
ai-electron/frontend/bin/build.sh / build.bat 前端构建脚本
cmd/uninstall.sh Linux 卸载清理脚本,终止 qingjian-client 进程并删除用户数据目录
cmd/uninstall.bat Windows 卸载脚本(二进制内容,不直接展开)

Linux 卸载脚本会:

  1. 检查 $HOME 是否为空;
  2. 强制终止 qingjian-client 进程;
  3. 递归删除 ~/.config/qingjian-client、~/.local/share/QingJian、~/.qingjian-client 等目录。

章节来源

  • cmd/uninstall.sh:1-53
  • cmd/uninstall.bat:1-1

新增后端模块

目标

新增一个 Spring Boot 业务模块,包含 Controller、Service、Entity、Mapper 和对应 XML。

步骤

  1. 在 ai-server/src/main/java/com/zsjz/ai/module/<domain> 下创建包,例如 module/order。
  2. 新建 controller/OrderController.java,使用 @RestController 和 @RequestMapping 暴露接口。
  3. 新建 service/OrderService.java 及其实现类,封装业务逻辑。
  4. 新建 entity/Order.java,放在 com.zsjz.ai.common.model.<domain>.entity 别名包下,以便 MyBatis Plus 自动扫描。
  5. 新建 mapper/OrderMapper.java,继承 MyBatis Plus Mapper。
  6. 新建 resources/mappers/order/OrderMapper.xml,编写 SQL。
  7. 如需新表,新增数据库变更脚本到 sql/ 目录。
  8. 若涉及跨域、认证、异常包装,复用已有 common 层的 Result、Sa-Token、CorsFilter 等基础设施,不要重复实现。

约束

  • 控制器统一返回 Result,除非像 /insight/** 这样明确为 SSE 裸返回。
  • 所有阻塞型 JDBC 操作应交给连接池或线程池,避免占用事件循环(网关侧已用 boundedElastic 隔离)。
  • 敏感配置走 ${ENV_NAME:默认值},不要在源码里写死密码。
  • 实体别名包已启用,新增实体不得与其他域实体重名。

章节来源

  • ai-server/src/main/resources/application.yaml:160-193
  • ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java:1-82
  • ai-server/src/main/java/com/zsjz/ai/module/agent/insight/controller/InsightController.java:1-40

新增前端页面

目标

新增一个 Vue 3 + TypeScript 页面,并通过菜单系统注册。

步骤

  1. 在 ai-electron/frontend/src 下按功能模块组织页面,例如 src/case/xxx.vue。
  2. 新增页面 API 调用方法,参考 ai-electron/frontend/src/api/sys/menu.ts 的写法:
    • 使用 defHttp 发起 HTTP 请求;
    • 使用 useGlobSetting() 获取 adminPath;
    • 定义响应类型接口;
    • 导出命名函数。
  3. 在菜单系统中注册页面,使导航可见。
  4. 如需样式,优先使用 UnoCSS 或 Less/SCSS,并在 Stylelint 规则内书写。
  5. 运行 pnpm lint:all 保证 ESLint、Prettier、Stylelint 均通过。

前端 API 约定

menu.ts 展示了典型模式:

  • 使用相对模块路径引入 defHttp;
  • 从全局设置取 adminPath;
  • 对每个后端接口导出一个函数;
  • 使用 TypeScript 接口描述返回模型。

章节来源

  • ai-electron/frontend/src/api/sys/menu.ts:1-50
  • ai-electron/frontend/README.md:120-200

新增 IPC 接口

定位

IPC 接口位于 Electron 主进程与渲染进程之间,由 ai-electron/electron 下的主进程代码和 preload 桥接共同承担。当前仓库结构中,主进程控制层包括:

  • ai-electron/electron/controller/downloadCtl.js
  • ai-electron/electron/controller/osCtl.js
  • ai-electron/electron/controller/windowCtl.ts
  • ai-electron/electron/preload/bridge.ts
  • ai-electron/electron/preload/index.ts
  • ai-electron/electron/preload/lifecycle.ts

建议流程

  1. 在主进程控制器中新增方法,负责操作系统、下载、窗口等原生能力。
  2. 在 preload 的 bridge 中暴露安全的方法映射,避免渲染进程直接访问 Node.js 或 Electron 危险 API。
  3. 前端通过预加载桥接调用 IPC 方法,而不是直接操作主进程。
  4. 新增 IPC 接口要尽量幂等、可失败恢复,并记录必要日志。
  5. 如果 IPC 触发的是后端任务,应异步处理,避免阻塞主进程事件循环。

由于仓库未展示这些文件的完整内容,新增时应遵循“最小暴露面、强类型、错误可观测”的原则。

章节来源

  • ai-electron/electron/controller/downloadCtl.js:1-1
  • ai-electron/electron/controller/osCtl.js:1-1
  • ai-electron/electron/controller/windowCtl.ts:1-1
  • ai-electron/electron/preload/bridge.ts:1-1
  • ai-electron/electron/preload/index.ts:1-1
  • ai-electron/electron/preload/lifecycle.ts:1-1

新增数据库表与变更脚本

原则

  • 所有 DDL 变更脚本放入 sql/ 目录。
  • 脚本应幂等:使用 CREATE TABLE IF NOT EXISTS、ALTER TABLE ... ADD COLUMN IF NOT EXISTS 等语法,允许重复执行。
  • 网关相关表结构维护在 sql/gateway.sql,由 ai-gateway/pom.xml 的 copy-gateway-sql 构建阶段复制到 classpath。
  • 其他业务表没有统一的 Flyway/Liquibase 迁移框架,因此脚本命名和顺序由团队约定。
  • 向量相关表依赖 PostgreSQL 的 pgvector 扩展。

向量表维度约定

本地嵌入模型声明维度由 zsjz.embedding.dimensions 控制,默认 1024;实际向量长度必须与配置一致,否则插入时报错。

章节来源

  • ai-gateway/pom.xml:85-120
  • ai-server/src/main/resources/application.yaml:80-120
  • ai-server/src/main/resources/application-dev.yaml:1-20

代码风格与检查

Java

  • 使用 Lombok 生成 getter/setter、构造器等。
  • 使用 SLF4J 日志,不使用 System.out。
  • 使用 Spring Boot 3 + Java 25。
  • 使用 MyBatis Plus 作为 ORM。
  • 使用 Sa-Token 做认证。
  • 使用动态数据源 Starter 管理主从和数据源切换。

TypeScript/Vue

  • 使用 TypeScript + Vue 3 <script setup> 风格。
  • ESLint 基于 eslint.config.mjs,支持 .vue、.ts、.tsx、.js。
  • Prettier 基于 .prettierrc.mjs,行宽 120,双引号关闭、单引号开启,末尾逗号全开。
  • Stylelint 基于 stylelint.config.mjs,支持 HTML/Vue、Less、SCSS。

SQL

  • 使用 PostgreSQL 语法。
  • 向量字段使用 pgvector 类型。
  • 脚本应幂等,便于重复执行。

Shell/Batch

  • Shell 脚本以 #!/usr/bin/env bash 开头。
  • 变量使用前检查是否为空。
  • 删除目录前判断存在性。
  • 禁止直接假设 $HOME 存在。

前端检查命令

配置 入口
ESLint ai-electron/frontend/eslint.config.mjs
Prettier ai-electron/frontend/.prettierrc.mjs
Stylelint ai-electron/frontend/stylelint.config.mjs

ESLint 关闭了部分严格规则,如 no-unused-vars、no-explicit-any、ban-ts-comment 等,以适配现有业务代码。

Prettier 启用了 prettier-plugin-packagejson,可对 package.json 格式化。

Stylelint 启用了 stylelint-prettier,让 CSS 格式与 Prettier 保持一致,同时放宽了 UnoCSS、Ant Design Vue 相关的伪类和 at-rule。

章节来源

  • ai-gateway/pom.xml:1-40
  • ai-server/pom.xml:1-60
  • ai-electron/frontend/eslint.config.mjs:1-177
  • ai-electron/frontend/.prettierrc.mjs:1-32
  • ai-electron/frontend/stylelint.config.mjs:1-121

提交规范与分支策略

分支策略

根据 Git 状态信息,当前工作分支为 dev_4,主干分支为 master。推荐策略:

  • master:稳定发布分支。
  • dev_*:开发集成分支,功能合并到此分支后再回归测试。
  • 功能分支:feat/<模块>-<简述>,例如 feat/auth-login-check。
  • 修复分支:fix/<模块>-<简述>,例如 fix/server-datasource-release。
  • 文档分支:docs/<简述>。
  • 重构分支:refactor/<模块>-<简述>。

提交消息建议

结合最近提交,建议采用类似 Angular 提交规范:

类型 含义
feat 新功能
fix 缺陷修复
refactor 代码重构
docs 文档变更
chore 构建、脚本、依赖更新
perf 性能优化
test 测试用例变更

示例:

feat(auth): 登录前校验账号是否正在使用,确认后才强制登录
fix(server): 账号被顶下线/踢下线后释放其全部案件数据源
feat(config): 后端配置支持环境变量覆盖,新增 Linux 环境变量脚本

分支合并建议

  • 功能开发完成后先合入 dev_*。
  • dev_* 验证通过后合入 master。
  • 紧急修复可直接合入 master,再同步回 dev_*。
  • 合并前至少完成一次本地构建和前端 lint 检查。

章节来源

  • gitStatus:1-10

架构总览

sequenceDiagram
    participant Browser as "浏览器或 Electron 渲染进程"
    participant Gateway as "ai-gateway<br/>StickyRouteFilter"
    participant Redis as "Redis<br/>sa-token / 路由缓存"
    participant DB as "PostgreSQL<br/>gateway_* 表"
    participant Server as "ai-server<br/>AuthController / InsightController"

    Browser->>Gateway: "POST /auth/login"
    Gateway->>DB: "查询用户名绑定的节点"
    alt 已绑定
        DB-->>Gateway: "nodeId"
    else 未绑定
        Gateway->>Server: "转发登录请求"
        Server-->>Gateway: "返回 token 和用户信息"
        Gateway->>DB: "写入用户→节点绑定"
    end
    Gateway-->>Browser: "登录成功,携带 token"

    Browser->>Gateway: "业务请求 + x-token"
    Gateway->>Redis: "解析 userId"
    Gateway->>DB: "查找 userId 绑定节点"
    Gateway->>Server: "转发请求"
    Server-->>Gateway: "返回结果或 SSE 流"
    Gateway-->>Browser: "透传响应"

图表来源

  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java:1-180
  • ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java:1-117
  • ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java:1-82

关键组件分析

网关粘性路由

网关的核心职责不是业务鉴权,而是把每个用户的请求固定转发到该用户绑定的 ai-server 节点。

核心类关系

classDiagram
    class GatewayApplication {
        +main(args) void
    }

    class StickyRouteFilter {
        +filter(exchange, chain) Mono<Void>
        +order() int
        -decideForLogin(exchange, service) Mono<String>
        -decideForNormal(exchange, service) Mono<String>
        -route(exchange, chain, service, nodeId) Mono<Void>
        +buildTargetUri(baseUrl, requestUri) URI
    }

    class UserRouteService {
        +findNodeIdByUserId(serviceId, userId) Mono<String>
        +findNodeIdByUsername(serviceId, username) Mono<String>
        +bindIfAbsent(serviceId, userId, username, nodeId) Mono<String>
        +evictUserCache(serviceId, userId, username) Mono<Void>
    }

    class NodeSelector {
        +select(service) NodeInfo
    }

    class AdminController {
        +status() Mono<ApiResult>
        +services() Mono<ApiResult>
        +createService(dto) Mono<ApiResult>
        +updateService(id, dto) Mono<ApiResult>
        +deleteService(id) Mono<ApiResult>
        +routes(serviceId, keyword, page, size) Mono<ApiResult>
        +bind(dto) Mono<ApiResult>
        +unbind(id) Mono<ApiResult>
        +reload() Mono<ApiResult>
    }

    class AuthController {
        +login(dto) Result
        +logout() Result
        +info() Result
        +changePwd(dto) Result
        +verifyPwd(dto) Result
    }

    GatewayApplication --> StickyRouteFilter : "启动后生效"
    StickyRouteFilter --> UserRouteService : "读写用户绑定"
    StickyRouteFilter --> NodeSelector : "匿名轮询"
    AdminController --> UserRouteService : "管理绑定关系"
    StickyRouteFilter --> AuthController : "转发登录请求"

图表来源

  • ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java:1-23
  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java:1-180
  • ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java:1-117
  • ai-gateway/src/main/java/com/zsjz/gateway/route/NodeSelector.java:1-45
  • ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminController.java:1-153
  • ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java:1-82

粘性路由决策流程

flowchart TD
    Start(["请求进入 StickyRouteFilter"]) --> CheckRoute["检查是否匹配服务路由"]
    CheckRoute --> IsLogin{"是否登录请求"}
    IsLogin -->|是| FindByName["按用户名查绑定节点"]
    FindByName --> HasBound{"是否已绑定"}
    HasBound -->|是| ChooseBound["使用已绑定节点"]
    HasBound -->|否| SelectCandidate["从健康节点轮询选候选"]
    IsLogin -->|否| ParseToken["从 x-token 解析 userId"]
    ParseToken --> TokenValid{"token 是否有效"}
    TokenValid -->|是| FindByUser["按 userId 查绑定节点"]
    FindByUser --> BoundOrDefault{"是否绑定"}
    BoundOrDefault -->|是| ChooseBound
    BoundOrDefault -->|否| BindDefault["绑定 default-node"]
    TokenValid -->|否| Anonymous["按匿名请求轮询节点"]
    SelectCandidate --> ValidateNode["校验节点可用"]
    ChooseBound --> ValidateNode
    BindDefault --> ValidateNode
    Anonymous --> ValidateNode
    ValidateNode --> RewriteUrl["重写目标 URL 为节点地址"]
    RewriteUrl --> Forward["NettyRoutingFilter 流式转发"]
    Forward --> End(["返回响应"])

图表来源

  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java:1-180
  • ai-gateway/src/main/java/com/zsjz/gateway/route/NodeSelector.java:1-45

章节来源

  • ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java:1-23
  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java:1-180
  • ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java:1-117
  • ai-gateway/src/main/java/com/zsjz/gateway/route/NodeSelector.java:1-45
  • ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminController.java:1-153

认证与会话

AuthController 提供登录、登出、用户信息、修改密码、密码校验接口。登录后前端通过 x-token 请求头传递令牌,网关和后端共享 Redis 中的 sa-token 键。

  • 登录接口为 /auth/login;
  • 登出接口为 /auth/logout;
  • 用户信息接口为 /auth/info;
  • 网关在登录成功后才落库用户与节点的绑定关系;
  • 非登录请求由 StickyRouteFilter 按 token → userId → nodeId 选择节点。

章节来源

  • ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java:1-82
  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java:60-140

AI 研判与 SSE 流

InsightController 是 AI 研判场景的控制器,采用裸返回而非 Result<T>,以便前端 SSE 解析器复用。

主要接口:

方法 路径 说明
POST /insight/sessions 创建研判会话
POST /insight/stream 流式分析,SSE
GET /insight/sessions 列出会话
GET /insight/sessions/{id} 获取会话详情
GET /insight/sessions/{id}/messages 分页消息
GET /insight/messages/{messageId}/trace 消息执行明细
GET /insight/sessions/{id}/delete 删除会话
GET /insight/clues 线索聚合

SSE 事件类型与聊天流一致,新增 insight 一帧用于结构化产物。

章节来源

  • ai-server/src/main/java/com/zsjz/ai/module/agent/insight/controller/InsightController.java:1-127

依赖关系分析

graph LR
    A["根 pom.xml"] --> B["ai-gateway/pom.xml"]
    A --> C["ai-server/pom.xml"]
    A --> D["ai-electron/package.json"]
    D --> E["ai-electron/frontend/package.json"]

    B --> F["Spring Cloud Gateway"]
    B --> G["PostgreSQL"]
    B --> H["Redis Reactive"]
    B --> I["sa-token Reactor"]

    C --> J["Spring Web"]
    C --> K["MyBatis Plus"]
    C --> L["Dynamic DataSource"]
    C --> M["pgvector"]
    C --> N["ONNX Runtime"]
    C --> O["Elasticsearch"]
    C --> P["Neo4j"]

图表来源

  • pom.xml:1-23
  • ai-gateway/pom.xml:1-70
  • ai-server/pom.xml:1-60
  • ai-electron/package.json:1-42
  • ai-electron/frontend/package.json:1-60

章节来源

  • pom.xml:1-23
  • ai-gateway/pom.xml:1-70
  • ai-server/pom.xml:1-60

性能注意事项

调度线程池

后端默认单线程调度器上运行多个定时任务,包括 SSE 心跳、数据源回收、AI 清洗看门狗、附件孤儿清理等。配置项 spring.task.scheduling.pool.size 默认扩容为 4,避免批量任务拖住心跳导致全服空闲 SSE 断开。

DuckDB 案件库预算

DuckDB 每个案件实例都有内存和线程预算。配置中改为按 max-open-cases 分摊总预算,避免多人同时开案时资源叠加。

向量模型加载

本地嵌入模型权重常驻堆外内存约 2.5~3GB,首次加载可能耗时 20~60 秒。可通过 eager-load=true 提前预热,或使用懒加载。

网关 Netty 事件循环

网关中所有阻塞型 JDBC 操作都通过 boundedElastic 调度,避免阻塞 WebFlux 事件循环。新增网关逻辑也应遵循这一原则。

章节来源

  • ai-server/src/main/resources/application.yaml:20-40
  • ai-server/src/main/resources/application.yaml:40-80
  • ai-server/src/main/resources/application.yaml:80-120
  • ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminController.java:130-153

调试技巧

Gateway 粘性路由日志

定位网关问题时,关注以下点:

  1. 登录请求是否命中正确节点;
  2. 普通请求是否按 x-token 解析出 userId;
  3. 用户是否已绑定节点;
  4. 绑定节点是否健康;
  5. 管理端 /gateway/admin/routes 是否正确;
  6. Redis 中 gateway:route:user:* 和 gateway:route:name:* 是否一致。

若用户未绑定且服务没有 default-node,网关会返回 503。

章节来源

  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java:60-140
  • ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java:1-117
  • ai-gateway/src/main/resources/application.yaml:40-81

Agent SSE 调试

SSE 流式接口返回 Flux<ServerSentEvent<String>>,前端直接使用原始流解析。调试要点:

  • 确认后端接口返回 TEXT_EVENT_STREAM_VALUE;
  • 确认网关没有误开跨域过滤造成响应头重复;
  • 确认后端调度线程池足够大,不会被长任务阻塞心跳;
  • 确认网关连接后端超时没有过短;
  • 确认前端使用的是裸返回解析逻辑,不走 Result<T> 包装。

章节来源

  • ai-server/src/main/java/com/zsjz/ai/module/agent/insight/controller/InsightController.java:60-90
  • ai-gateway/src/main/resources/application.yaml:10-30

pgvector 向量检索验证

验证链路:

  1. 确认 PostgreSQL 已安装 pgvector 扩展;
  2. 确认 zsjz.embedding.enabled 与模型配置一致;
  3. 确认 zsjz.embedding.dimensions 与实际模型输出维度一致;
  4. 确认向量表存在且维度正确;
  5. 调用嵌入调试接口或模板索引重建接口;
  6. 使用余弦相似度或内积近似验证检索结果。

如果本地模型未启用或未找到模型目录,向量能力应降级为不可用,而不是静默崩溃。

章节来源

  • ai-server/src/main/resources/application.yaml:80-120
  • ai-server/src/main/resources/application-dev.yaml:1-20
  • ai-server/src/main/resources/application-dev.yaml:60-87

地图与许可证问题定位

仓库 readme.md 提供了离线地图和许可证相关参考:

  • 地图使用 PMTiles 离线瓦片;
  • 地图配置包含 sources 和 layers;
  • 激活工具 regInfo.exe 支持读取机器码、校验许可证、显示字段;
  • 许可证错误码包括文件无效、过期、机器码不匹配等。

常见问题:

现象 排查方向
地图不显示 检查 PMTiles 路径、metadata.json、pmtiles 转换命令
许可证校验失败 使用 regInfo.exe read licensefile 查看信息
机器码不匹配 使用 regInfo.exe machinecode 对比
许可证过期 检查 overdatetime 字段

章节来源

  • readme.md:1-76

常见问题排查

登录失败或 401

常见原因:

  • Redis 不可用,sa-token 无法解析 token;
  • 前端 authenticationHeader 与后端 sa-token.token-name 不一致;
  • 网关与后端 sa-token 配置不一致;
  • 用户 token 被顶下线;
  • 用户未绑定节点且服务没有 default-node。

排查顺序:

  1. 检查 Redis 连通性;
  2. 检查 x-token 是否随请求发送;
  3. 检查网关 /gateway/admin/status;
  4. 检查用户路由绑定;
  5. 检查后端登录接口是否返回正常结果。

章节来源

  • ai-server/src/main/resources/application-dev.yaml:40-87
  • ai-gateway/src/main/resources/application-dev.yaml:1-14
  • ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java:80-140

前端构建内存不足

前端构建脚本显式设置 NODE_OPTIONS=--max_old_space_size=4096。若仍失败,可增加内存或减少并行构建体积。

章节来源

  • ai-electron/frontend/package.json:1-20

Linux 部署环境变量未生效

确认:

  1. 启动前执行 set -a; source deploy/env.sh; set + a;
  2. 或通过 systemd EnvironmentFile 加载;
  3. 确认 SPRING_PROFILES_ACTIVE 设置正确;
  4. 确认数据库、Redis、Elasticsearch 地址和端口正确;
  5. 确认 STORAGE_LOCAL_BASE_URL 与 server.port、context-path 一致。

章节来源

  • deploy/env.sh:1-40
  • ai-server/src/main/resources/application.yaml:1-20

向量索引重建失败

可能原因:

  • 本地模型开关打开但模型目录不存在;
  • 模型输出维度与配置不一致;
  • pgvector 扩展未安装;
  • 模板数量过多,单次重建超出 max-documents-per-rebuild;
  • 在线 embedding 模型配额耗尽。

章节来源

  • ai-server/src/main/resources/application.yaml:80-140

结论

贡献者新增功能时,应优先理解三层边界:

  • 网关只做粘性路由和节点管理,不复制业务逻辑;
  • 后端负责认证、业务、向量检索、Agent 能力;
  • 前端通过 API 和 IPC 与后端及 Electron 主进程交互。

新增代码应遵守:

  • Java 使用 Spring Boot、MyBatis Plus、Sa-Token;
  • 前端使用 Vue 3、TypeScript、Vite、pnpm;
  • SQL 脚本幂等;
  • Shell 脚本安全地处理路径和进程;
  • 所有前端代码通过 ESLint、Prettier、Stylelint;
  • 提交消息清晰表达变更范围;
  • 分支合入 dev_*,稳定后再合入 master。