# 系统架构总览 **本文引用的文件** - [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、前端页面、会话管理、地图与授权机制。 - 网关:粘性路由决策、登录捕获、用户绑定、节点健康检查、管理接口和排障流程。 - 后端服务:各业务模块的职责、接口契约、数据模型和依赖关系。 - 数据流:案件数据从导入、清洗、入库、分析到可视化的完整链路。 - 部署与运维:环境准备、环境变量、服务启动、扩缩容、监控和故障恢复。