# 系统架构总览
**本文引用的文件**
- [readme.md](file://readme.md)
- [ai-electron/README.zh-CN.md](file://ai-electron/README.zh-CN.md)
- [ai-gateway/README.md](file://ai-gateway/README.md)
- [pom.xml](file://pom.xml)
- [TowerListener.java](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/TowerListener.java)
## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览图](#架构总览图)
5. [分层职责说明](#分层职责说明)
6. [业务模块划分](#业务模块划分)
7. [数据流与边界](#数据流与边界)
8. [部署形态与平台](#部署形态与平台)
9. [后续文档入口](#后续文档入口)
## 引言
清鉴 AI 调查工具面向公安、审计、风控等调查场景,围绕“案件”组织多源数据、分析线索并输出研判结果。系统由跨平台桌面客户端、粘性路由网关和后端服务组成:桌面端提供用户界面、会话与地图能力;网关保证同一用户的请求始终落到拥有该案件数据的 ai-server 节点;服务端按业务域拆分为 plat、agent、aiclean、knowledge、graph、person、call、trans、track、govern、dm、otg、external 等模块,分别承担平台能力、智能体、数据清洗、知识检索、关系图谱、人员、通话、交易、轨迹、治理、数据模型、外部数据和在线工具等职责。
本章节是系统架构总览,仅描述边界、职责和数据流,不展开具体实现细节。
## 项目结构
仓库是一个 Maven 多模块工程,根 `pom.xml` 包含两个主要子模块:
- `ai-server`:Java 后端服务,承载业务模块、数据库访问、本地数据源管理和外部系统集成。
- `ai-gateway`:基于 Spring Cloud Gateway 的粘性路由网关,负责用户绑定、节点健康检查和请求转发。
```mermaid
graph TB
Root["Maven 根工程
com.zsjz:zsjz-ai"] --> Server["ai-server
Spring Boot 业务服务"]
Root --> Gateway["ai-gateway
Spring Cloud Gateway 粘性路由"]
```
**图示来源**
- [pom.xml:1-23](file://pom.xml#L1-L23)
**章节来源**
- [pom.xml:1-23](file://pom.xml#L1-L23)
## 核心组件
| 组件 | 技术定位 | 主要职责 |
|---|---|---|
| Electron 桌面客户端 | TypeScript + Vue 前端 + Electron 主进程 | 提供调查工作台 UI、会话管理、地图展示、授权与本地设置,并通过 Preload Bridge 调用系统能力 |
| Preload Bridge | Electron preload 脚本 | 在渲染进程与 Electron 主进程之间建立安全桥接,封装操作系统、窗口、下载、设置等能力 |
| Spring Cloud Gateway | Java WebFlux 网关 | 根据 token 解析 userId,把请求粘性路由到已绑定的 ai-server 节点,并在节点不可用时返回明确错误 |
| ai-server 业务模块 | Java Spring Boot 应用 | 按 plat/agent/aiclean/knowledge/graph/person/call/trans/track/govern/dm/otg/external 等模块组织业务能力,管理案件数据源、文件、Agent 记忆和技能 |
| PostgreSQL | 关系型数据库 | 存储用户、服务、节点、路由、平台配置、业务主数据等结构化信息 |
| Redis | 内存缓存与会话存储 | 保存 sa-token 登录态、网关路由缓存、服务注册与健康状态 |
| DuckDB | 每节点本地列式数据库 | 承载每个 ai-server 节点上的案件数据源,支持高性能查询和临时表操作 |
| 文件系统 | 节点本地磁盘 | 存放上传附件、Agent 记忆、技能、Python 产物、DuckDB 文件及调查工作目录 |
这些组件共同构成“桌面客户端 → 网关 → 后端节点 → 共享数据库与缓存 → 本地数据源与文件”的调查工具链。
**章节来源**
- [ai-gateway/README.md:1-40](file://ai-gateway/README.md#L1-L40)
## 架构总览图
下图展示各层边界和主要交互关系。Electron 客户端通过浏览器网络栈访问网关;网关维护用户与 ai-server 节点的绑定关系;ai-server 节点直接读写 PostgreSQL、Redis、本机 DuckDB 和文件系统。
```mermaid
graph TB
Client["Electron 桌面客户端
UI、会话、地图、授权"] --> Bridge["Preload Bridge
系统能力桥接"]
Bridge --> Gateway["Spring Cloud Gateway
粘性路由、用户绑定、健康检查"]
Gateway --> Node1["ai-server 节点 1
业务模块 + 本地数据源"]
Gateway --> Node2["ai-server 节点 N
业务模块 + 本地数据源"]
Node1 --> PG["PostgreSQL
用户、路由、配置、业务主数据"]
Node2 --> PG
Node1 --> Redis["Redis
sa-token、网关缓存、健康状态"]
Node2 --> Redis
Node1 --> DuckDB["DuckDB
节点本地案件数据源"]
Node2 --> DuckDB
Node1 --> FS["文件系统
附件、Agent 记忆、技能、产物"]
Node2 --> FS
```
**图示来源**
- [ai-gateway/README.md:1-40](file://ai-gateway/README.md#L1-L40)
## 分层职责说明
### 桌面客户端层
- 使用 Electron 构建 Windows、macOS、Linux 等跨平台桌面应用。
- 前端基于 Vue/Ant Design 等现代前端技术,承载调查工作台、案件列表、地图、图谱、对话、数据清洗、外部数据接入等功能页面。
- 通过 Preload Bridge 暴露有限、安全的系统 API,避免渲染进程直接访问 Electron 敏感接口。
- 负责用户登录、授权校验、会话上下文、本地缓存、地图资源加载等体验相关逻辑。
### 网关层
- 作为唯一对外入口,隐藏后端节点地址。
- 首次登录成功时为用户选择并绑定一个 ai-server 节点;普通请求通过 `x-token` 解析 userId,再查 Redis 或 PostgreSQL 得到目标节点。
- 对健康节点进行轮询探活;连续失败则标记 DOWN,并把该节点上用户的请求转为 503,防止误切到其他没有案件数据的节点。
- 向响应附加网关标识头,便于追踪请求落点。
### 业务服务层
- ai-server 按领域模块拆分职责,避免单体大泥球。
- 管理案件数据源生命周期:打开案件后注册到节点 JVM 内存,关闭或踢下线后释放对应数据源。
- 聚合多源数据,包括 PostgreSQL、Redis、DuckDB、外部系统和本地文件。
- 支撑 Agent、AI 数据清洗、知识检索、关系图谱、人员画像、通话分析、交易分析、轨迹分析、治理规则、数据模型、外部数据接入和在线工具等能力。
### 数据层
- PostgreSQL 提供强一致的结构化数据,包括用户、权限、服务、节点、路由、平台配置和业务主数据。
- Redis 提供低延迟缓存,用于登录态、路由缓存和服务健康快照。
- DuckDB 以“每节点一份”的方式保存案件数据源,适合大规模列式分析和临时表计算,但禁止多个节点共享同一个 DuckDB 文件。
- 文件系统保存非结构化或半结构化产物,如上传附件、Agent 记忆、技能、Python 产物和 DuckDB 数据文件。
**章节来源**
- [ai-electron/README.zh-CN.md:1-134](file://ai-electron/README.zh-CN.md#L1-L20)
- [ai-gateway/README.md:1-40](file://ai-gateway/README.md#L1-L40)
## 业务模块划分
ai-server 内部以 `module` 为业务域边界,常见模块如下:
| 模块 | 职责概览 |
|---|---|
| `plat` | 平台基础能力,包括系统信息、用户、表结构、案例元数据、基站转换、缓存管理等 |
| `agent` | 智能体能力,包括模型管理、聊天会话、意图识别、提示词、RAG 索引、工具注册等 |
| `aiclean` | AI 辅助数据清洗,包括模板匹配、规则计划、字段映射、错误日志、同义词管理等 |
| `knowledge` | 知识文档与索引,支撑检索增强生成和业务知识沉淀 |
| `graph` | 关系图谱建模与可视化相关的数据处理和查询 |
| `person` | 人员画像、亲密关系、常住人口、人群分组等 |
| `call` | 通话记录、夜间通话、连续通话、敏感通话、开号信息等 |
| `trans` | 交易流水、资金流向、大额交易、频繁交易、敏感交易、账户开户等 |
| `track` | 轨迹分析,包括基站、乘车、同住、同乘、同城、快递等 |
| `govern` | 治理规则、树形配置、结果处理器,支撑调查规则和治理流程 |
| `dm` | 数据模型、边缘配置、文件信息、数据质量与清理相关能力 |
| `otg` | 在线工具或特定运营工具相关功能 |
| `external` | 对接外部系统,如车辆违法、犯罪人员、同住人等第三方数据 |
这些模块不是孤立存在的:例如基站转换由 `plat` 中的监听器处理,随后可能被 `track`、`person` 或 `graph` 复用;数据清洗结果可能进入 `dm` 的数据模型,再由 `govern` 的规则驱动下游分析。
**章节来源**
- [TowerListener.java:1-80](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/TowerListener.java#L1-L80)
## 数据流与边界
```mermaid
sequenceDiagram
participant User as "调查员"
participant Client as "Electron 客户端"
participant Bridge as "Preload Bridge"
participant Gateway as "Spring Cloud Gateway"
participant Node as "ai-server 业务节点"
participant PG as "PostgreSQL"
participant Redis as "Redis"
participant DuckDB as "DuckDB"
participant FS as "文件系统"
User->>Client: "打开调查工作台"
Client->>Bridge: "发起登录与业务请求"
Bridge->>Gateway: "HTTP 请求"
Gateway->>Redis: "解析 token 或查找用户绑定"
alt "已有绑定且节点健康"
Gateway->>Node: "转发请求"
Node->>PG: "读取用户、平台、业务数据"
Node->>Redis: "读取缓存与会话"
Node->>DuckDB: "查询案件数据源"
Node->>FS: "读取附件、记忆或产物"
Node-->>Gateway: "业务响应"
Gateway-->>Client: "透传响应"
else "无绑定或节点不可用"
Gateway-->>Client: "返回未绑定或 503 错误"
end
```
关键边界规则:
- 客户端只暴露必要的前端能力,系统级能力走 Preload Bridge。
- 所有外部 HTTP 请求先经过网关,避免直连后端绕过粘性路由。
- 网关不持有案件数据,只维护“用户 → 节点”的路由关系。
- 案件数据源属于 ai-server 节点本地,不能跨节点共享。
- 结构化主数据放在 PostgreSQL,热路径缓存放在 Redis,分析型数据放在 DuckDB,非结构化产物放在文件系统。
**图示来源**
- [ai-gateway/README.md:1-40](file://ai-gateway/README.md#L1-L40)
## 部署形态与平台
- 桌面客户端:基于 Electron,可打包为 Windows、macOS、Linux 及国产操作系统(UOS、Deepin、麒麟等)安装包。
- 后端服务:Java Spring Boot 应用,运行在服务器或容器中,可水平扩展多个 ai-server 节点。
- 网关:独立部署,对外暴露统一入口,对内维护节点列表、服务定义和用户绑定。
- 数据库与缓存:PostgreSQL 和 Redis 通常作为共享基础设施,供所有 ai-server 节点和网关访问。
- 数据源与文件:DuckDB 文件和调查工作目录必须按节点隔离,避免并发写入导致数据损坏。
产品目标是让公安、审计、风控调查员在一个统一的桌面环境中完成案件导入、数据清洗、线索分析、关系挖掘、轨迹追踪和报告输出,同时保障数据安全、可审计和可运维。
**章节来源**
- [ai-electron/README.zh-CN.md:1-134](file://ai-electron/README.zh-CN.md#L1-L20)
- [readme.md:1-76](file://readme.md#L1-L76)
- [ai-gateway/README.md:40-157](file://ai-gateway/README.md#L40-L157)
## 后续文档入口
本章是清鉴 AI 调查工具的顶层视图。后续子文档将分别深入以下主题:
- 桌面客户端:Electron 主进程、Preload Bridge、前端页面、会话管理、地图与授权机制。
- 网关:粘性路由决策、登录捕获、用户绑定、节点健康检查、管理接口和排障流程。
- 后端服务:各业务模块的职责、接口契约、数据模型和依赖关系。
- 数据流:案件数据从导入、清洗、入库、分析到可视化的完整链路。
- 部署与运维:环境准备、环境变量、服务启动、扩缩容、监控和故障恢复。