zsjz-ai/.qoder/repowiki/zh/content/系统架构设计/系统架构总览.md

系统架构总览

本文引用的文件

• readme.md
• ai-electron/README.zh-CN.md
• ai-gateway/README.md
• pom.xml
• 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 的粘性路由网关，负责用户绑定、节点健康检查和请求转发。

  graph TB
  Root["Maven 根工程<br/>com.zsjz:zsjz-ai"] --> Server["ai-server<br/>Spring Boot 业务服务"]
  Root --> Gateway["ai-gateway<br/>Spring Cloud Gateway 粘性路由"]
  

图示来源

• pom.xml:1-23

章节来源

• pom.xml:1-23

核心组件

组件	技术定位	主要职责
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

架构总览图

下图展示各层边界和主要交互关系。Electron 客户端通过浏览器网络栈访问网关；网关维护用户与 ai-server 节点的绑定关系；ai-server 节点直接读写 PostgreSQL、Redis、本机 DuckDB 和文件系统。

graph TB
    Client["Electron 桌面客户端<br/>UI、会话、地图、授权"] --> Bridge["Preload Bridge<br/>系统能力桥接"]
    Bridge --> Gateway["Spring Cloud Gateway<br/>粘性路由、用户绑定、健康检查"]
    Gateway --> Node1["ai-server 节点 1<br/>业务模块 + 本地数据源"]
    Gateway --> Node2["ai-server 节点 N<br/>业务模块 + 本地数据源"]
    Node1 --> PG["PostgreSQL<br/>用户、路由、配置、业务主数据"]
    Node2 --> PG
    Node1 --> Redis["Redis<br/>sa-token、网关缓存、健康状态"]
    Node2 --> Redis
    Node1 --> DuckDB["DuckDB<br/>节点本地案件数据源"]
    Node2 --> DuckDB
    Node1 --> FS["文件系统<br/>附件、Agent 记忆、技能、产物"]
    Node2 --> FS

图示来源

• ai-gateway/README.md:1-40

分层职责说明

桌面客户端层

• 使用 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
• ai-gateway/README.md:1-40

业务模块划分

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

数据流与边界

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

部署形态与平台

• 桌面客户端：基于 Electron，可打包为 Windows、macOS、Linux 及国产操作系统（UOS、Deepin、麒麟等）安装包。
• 后端服务：Java Spring Boot 应用，运行在服务器或容器中，可水平扩展多个 ai-server 节点。
• 网关：独立部署，对外暴露统一入口，对内维护节点列表、服务定义和用户绑定。
• 数据库与缓存：PostgreSQL 和 Redis 通常作为共享基础设施，供所有 ai-server 节点和网关访问。
• 数据源与文件：DuckDB 文件和调查工作目录必须按节点隔离，避免并发写入导致数据损坏。

产品目标是让公安、审计、风控调查员在一个统一的桌面环境中完成案件导入、数据清洗、线索分析、关系挖掘、轨迹追踪和报告输出，同时保障数据安全、可审计和可运维。

章节来源

• ai-electron/README.zh-CN.md:1-134
• readme.md:1-76
• ai-gateway/README.md:40-157

后续文档入口

本章是清鉴 AI 调查工具的顶层视图。后续子文档将分别深入以下主题：

• 桌面客户端：Electron 主进程、Preload Bridge、前端页面、会话管理、地图与授权机制。
• 网关：粘性路由决策、登录捕获、用户绑定、节点健康检查、管理接口和排障流程。
• 后端服务：各业务模块的职责、接口契约、数据模型和依赖关系。
• 数据流：案件数据从导入、清洗、入库、分析到可视化的完整链路。
• 部署与运维：环境准备、环境变量、服务启动、扩缩容、监控和故障恢复。