本文引用的文件
本项目是清鉴 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 子模块统一管理。
章节来源
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
图表来源
章节来源
| 项目 | 版本或说明 |
|---|---|
| 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 组件库 |
章节来源
根目录执行:
mvn clean compile
mvn package
mvn test
父 POM 将 ai-server 与 ai-gateway 作为子模块参与构建。ai-gateway 的构建阶段会把仓库根 sql/gateway.sql 复制到 classpath:db/gateway.sql,供 Spring SQL init 启动建表。
章节来源
进入 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 目录执行:
| 命令 | 作用 |
|---|---|
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/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 卸载脚本会:
$HOME 是否为空;qingjian-client 进程;~/.config/qingjian-client、~/.local/share/QingJian、~/.qingjian-client 等目录。章节来源
新增一个 Spring Boot 业务模块,包含 Controller、Service、Entity、Mapper 和对应 XML。
ai-server/src/main/java/com/zsjz/ai/module/<domain> 下创建包,例如 module/order。controller/OrderController.java,使用 @RestController 和 @RequestMapping 暴露接口。service/OrderService.java 及其实现类,封装业务逻辑。entity/Order.java,放在 com.zsjz.ai.common.model.<domain>.entity 别名包下,以便 MyBatis Plus 自动扫描。mapper/OrderMapper.java,继承 MyBatis Plus Mapper。resources/mappers/order/OrderMapper.xml,编写 SQL。sql/ 目录。common 层的 Result、Sa-Token、CorsFilter 等基础设施,不要重复实现。Result,除非像 /insight/** 这样明确为 SSE 裸返回。boundedElastic 隔离)。${ENV_NAME:默认值},不要在源码里写死密码。章节来源
新增一个 Vue 3 + TypeScript 页面,并通过菜单系统注册。
ai-electron/frontend/src 下按功能模块组织页面,例如 src/case/xxx.vue。ai-electron/frontend/src/api/sys/menu.ts 的写法:
defHttp 发起 HTTP 请求;useGlobSetting() 获取 adminPath;pnpm lint:all 保证 ESLint、Prettier、Stylelint 均通过。menu.ts 展示了典型模式:
defHttp;adminPath;章节来源
IPC 接口位于 Electron 主进程与渲染进程之间,由 ai-electron/electron 下的主进程代码和 preload 桥接共同承担。当前仓库结构中,主进程控制层包括:
ai-electron/electron/controller/downloadCtl.jsai-electron/electron/controller/osCtl.jsai-electron/electron/controller/windowCtl.tsai-electron/electron/preload/bridge.tsai-electron/electron/preload/index.tsai-electron/electron/preload/lifecycle.ts由于仓库未展示这些文件的完整内容,新增时应遵循“最小暴露面、强类型、错误可观测”的原则。
章节来源
sql/ 目录。CREATE TABLE IF NOT EXISTS、ALTER TABLE ... ADD COLUMN IF NOT EXISTS 等语法,允许重复执行。sql/gateway.sql,由 ai-gateway/pom.xml 的 copy-gateway-sql 构建阶段复制到 classpath。本地嵌入模型声明维度由 zsjz.embedding.dimensions 控制,默认 1024;实际向量长度必须与配置一致,否则插入时报错。
章节来源
System.out。<script setup> 风格。eslint.config.mjs,支持 .vue、.ts、.tsx、.js。.prettierrc.mjs,行宽 120,双引号关闭、单引号开启,末尾逗号全开。stylelint.config.mjs,支持 HTML/Vue、Less、SCSS。#!/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。
章节来源
根据 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_*。章节来源
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-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 : "转发登录请求"
图表来源
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(["返回响应"])
图表来源
章节来源
AuthController 提供登录、登出、用户信息、修改密码、密码校验接口。登录后前端通过 x-token 请求头传递令牌,网关和后端共享 Redis 中的 sa-token 键。
/auth/login;/auth/logout;/auth/info;StickyRouteFilter 按 token → userId → nodeId 选择节点。章节来源
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 一帧用于结构化产物。
章节来源
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"]
图表来源
章节来源
后端默认单线程调度器上运行多个定时任务,包括 SSE 心跳、数据源回收、AI 清洗看门狗、附件孤儿清理等。配置项 spring.task.scheduling.pool.size 默认扩容为 4,避免批量任务拖住心跳导致全服空闲 SSE 断开。
DuckDB 每个案件实例都有内存和线程预算。配置中改为按 max-open-cases 分摊总预算,避免多人同时开案时资源叠加。
本地嵌入模型权重常驻堆外内存约 2.5~3GB,首次加载可能耗时 20~60 秒。可通过 eager-load=true 提前预热,或使用懒加载。
网关中所有阻塞型 JDBC 操作都通过 boundedElastic 调度,避免阻塞 WebFlux 事件循环。新增网关逻辑也应遵循这一原则。
章节来源
定位网关问题时,关注以下点:
x-token 解析出 userId;/gateway/admin/routes 是否正确;gateway:route:user:* 和 gateway:route:name:* 是否一致。若用户未绑定且服务没有 default-node,网关会返回 503。
章节来源
SSE 流式接口返回 Flux<ServerSentEvent<String>>,前端直接使用原始流解析。调试要点:
TEXT_EVENT_STREAM_VALUE;Result<T> 包装。章节来源
验证链路:
zsjz.embedding.enabled 与模型配置一致;zsjz.embedding.dimensions 与实际模型输出维度一致;如果本地模型未启用或未找到模型目录,向量能力应降级为不可用,而不是静默崩溃。
章节来源
仓库 readme.md 提供了离线地图和许可证相关参考:
sources 和 layers;regInfo.exe 支持读取机器码、校验许可证、显示字段;常见问题:
| 现象 | 排查方向 |
|---|---|
| 地图不显示 | 检查 PMTiles 路径、metadata.json、pmtiles 转换命令 |
| 许可证校验失败 | 使用 regInfo.exe read licensefile 查看信息 |
| 机器码不匹配 | 使用 regInfo.exe machinecode 对比 |
| 许可证过期 | 检查 overdatetime 字段 |
章节来源
常见原因:
authenticationHeader 与后端 sa-token.token-name 不一致;default-node。排查顺序:
x-token 是否随请求发送;/gateway/admin/status;章节来源
前端构建脚本显式设置 NODE_OPTIONS=--max_old_space_size=4096。若仍失败,可增加内存或减少并行构建体积。
章节来源
确认:
set -a; source deploy/env.sh; set + a;EnvironmentFile 加载;SPRING_PROFILES_ACTIVE 设置正确;STORAGE_LOCAL_BASE_URL 与 server.port、context-path 一致。章节来源
可能原因:
max-documents-per-rebuild;章节来源
贡献者新增功能时,应优先理解三层边界:
新增代码应遵守:
dev_*,稳定后再合入 master。