# 快速开始 **本文引用的文件** - [readme.md](file://readme.md) - [AI_AGENT.md](file://AI_AGENT.md) - [pom.xml](file://pom.xml) - [deploy/env.sh](file://deploy/env.sh) - [ai-server/src/main/resources/application.yaml](file://ai-server/src/main/resources/application.yaml) - [ai-server/src/main/resources/application-dev.yaml](file://ai-server/src/main/resources/application-dev.yaml) - [ai-gateway/src/main/resources/application.yaml](file://ai-gateway/src/main/resources/application.yaml) - [ai-gateway/src/main/resources/application-dev.yaml](file://ai-gateway/src/main/resources/application-dev.yaml) - [sql/gateway.sql](file://sql/gateway.sql) - [ai-electron/frontend/package.json](file://ai-electron/frontend/package.json) - [ai-electron/frontend/.env.development](file://ai-electron/frontend/.env.development) ## 目录 1. [简介](#简介) 2. [前置环境](#前置环境) 3. [项目结构速览](#项目结构速览) 4. [数据库与脚本初始化](#数据库与脚本初始化) 5. [后端服务启动顺序](#后端服务启动顺序) 6. [Electron 客户端首次运行](#electron-客户端首次运行) 7. [首次登录、激活授权与水印流程](#首次登录激活授权与水印流程) 8. [常见启动失败排查](#常见启动失败排查) 9. [开发建议](#开发建议) 10. [附录:关键端口与路径](#附录关键端口与路径) ## 简介 清鉴(QingJian)是面向纪检监察与经侦场景的智能资金数据研判平台,提供多源数据导入、清洗治理、建模分析、可视化以及基于 Agent 的对话式研判能力。对本地开发者而言,最小可运行形态包含: - **PostgreSQL + pgvector**:平台元数据、用户、网关路由、向量索引等主库。 - **Redis**:Sa-Token 登录态缓存,未连接时登录相关接口会异常。 - **DuckDB**:按工作空间切换的案件分析库,Agent 只读执行 SQL。 - **ai-server**:Spring Boot 后端,默认监听 `8980`,上下文路径 `/js/a`。 - **ai-gateway**:Spring Cloud Gateway 网关,默认监听 `8080`,负责用户粘性路由。 - **Electron 客户端前端**:通过 `pnpm dev` 或构建命令启动,开发模式下代理到 `http://127.0.0.1:8980/js`。 本文目标是让第一次接触项目的开发者在 10–20 分钟内完成本地依赖准备、数据库初始化、后端启动和客户端首次运行。 ## 前置环境 | 组件 | 最低/推荐版本 | 说明 | |---|---:|---| | Java | **25** | ai-server 使用 Spring Boot 3.5.16;Java 25 下 ONNX Runtime 加载 native 库可能出现“受限方法”警告,可通过 JVM 参数 `--enable-native-access=ALL-UNNAMED` 消除,不影响运行。 | | Maven | 任意可用版本 | 用于聚合构建 ai-server 与 ai-gateway。 | | Node.js | `>=20.19 || >=22.12` | Electron 前端要求。 | | pnpm | `10.x` | 项目强制使用 pnpm,package.json 中设置了 `preinstall: only-allow pnpm`。 | | PostgreSQL | 支持扩展的版本 | 主库需安装 **pgvector** 扩展,用于表结构语义检索与 AI 清洗模板向量索引。 | | Redis | 任意可用版本 | Sa-Token 登录态硬依赖,不可用则登录功能全部异常。 | | DuckDB | 任意可用版本 | 作为 slave 数据源,按工作空间动态打开案件库。 | | Elasticsearch / Neo4j | 可选 | Elasticsearch 用于全文检索;Neo4j 仅图谱能力需要,非全链路强依赖。 | > 注意:仓库根文档明确声明后端 JDK 为 25,Node 要求为 `>=20.19 || >=22.12`,前端包管理器为 pnpm。 **章节来源** - [AI_AGENT.md:1-120](file://AI_AGENT.md#L1-L120) - [pom.xml:1-23](file://pom.xml#L1-L23) ## 项目结构速览 ```mermaid graph TB Client["Electron 客户端
Vite 开发服务器"] --> Gateway["ai-gateway
端口 8080"] Client --> Server["ai-server
端口 8980,上下文 /js/a"] Gateway --> Server Server --> PG["PostgreSQL + pgvector
平台主库"] Server --> Redis["Redis
Sa-Token 会话"] Server --> Duck["DuckDB
案件分析库"] PG --> GTables["gateway_service
gateway_node
gateway_user_route"] ``` **图表来源** - [ai-gateway/src/main/resources/application.yaml:1-81](file://ai-gateway/src/main/resources/application.yaml#L1-L81) - [ai-server/src/main/resources/application.yaml:1-60](file://ai-server/src/main/resources/application.yaml#L1-L60) - [ai-gateway/src/main/resources/application-dev.yaml:1-14](file://ai-gateway/src/main/resources/application-dev.yaml#L1-L14) - [sql/gateway.sql:1-107](file://sql/gateway.sql#L1-L107) **章节来源** - [AI_AGENT.md:1-120](file://AI_AGENT.md#L1-L120) - [ai-gateway/src/main/resources/application.yaml:1-81](file://ai-gateway/src/main/resources/application.yaml#L1-L81) - [ai-server/src/main/resources/application.yaml:1-60](file://ai-server/src/main/resources/application.yaml#L1-L60) ## 数据库与脚本初始化 ### 1. 准备 PostgreSQL - 创建平台数据库(例如 `zsjz-ai`)。 - 确保已启用 **pgvector** 扩展,否则向量检索、RAG 表结构语义检索、AI 清洗模板向量索引都会失败。 - 确认数据库地址、用户名、密码与配置一致。开发默认值指向 `jdbc:postgresql://192.168.0.106:5432/zsjz-ai`,用户名和密码均为 `postgres`。 ### 2. 准备 Redis - 启动 Redis,默认地址为 `192.168.0.106:6379`。 - 如果本地开发,请将 Redis 地址改为本机地址,例如 `localhost:6379`。 ### 3. 准备 DuckDB - DuckDB 由应用按工作空间动态管理,不需要提前建库;但需确保系统能正常加载 DuckDB 驱动。 ### 4. 初始化 SQL 脚本 SQL 脚本位于仓库根目录的 `sql/` 下,主要包括平台表、业务表、网关表、清洗模板及示例数据。本地快速跑通至少应关注: | 脚本范围 | 用途 | |---|---| | `sql/gateway.sql` | 网关服务定义、节点、用户粘性路由表,幂等建表,可重复执行。 | | `sql/user.sql`、`sql/plat.sql` | 平台基础表与初始用户数据。 | | `sql/agent_expert.sql`、`sql/agent_tool.sql` | Agent 专家与工具相关表结构。 | | `sql/ai_clean*.sql` | AI 清洗相关表、字段短名、行统计、同义词初始化。 | | `sql/external_tables.sql`、`sql/external_table_field.sql` | 外部表与字段元数据。 | | `sql/case_table*.sql`、`sql/table_data_1.sql` | 案例表与测试数据。 | | `sql/testSql/*` | 测试类 SQL,通常不纳入生产初始化。 | 推荐执行顺序: 1. 先执行 `sql/gateway.sql`,保证网关三张表存在。 2. 再执行平台与业务脚本,例如 `user.sql`、`plat.sql`、`agent_expert.sql`、`agent_tool.sql`、`ai_clean*.sql`、`external_tables.sql`、`external_table_field.sql`、`case_table*.sql`、`table_data_1.sql`。 3. 如需向量能力,确保 PostgreSQL 已安装 pgvector,并保留后续 AI 清洗向量索引重建逻辑。 > 若首次启动发现网关路由表不存在,可手动执行 `sql/gateway.sql`,或在 ai-gateway 启动后通过其管理接口维护服务与节点。 **章节来源** - [sql/gateway.sql:1-107](file://sql/gateway.sql#L1-L107) - [deploy/env.sh:1-172](file://deploy/env.sh#L1-L172) - [AI_AGENT.md:1-120](file://AI_AGENT.md#L1-L120) ## 后端服务启动顺序 推荐顺序:**ai-server → ai-gateway**。 原因:ai-gateway 会把请求转发给 ai-server,且网关配置文件中的默认节点地址可能不是本机。本地开发时,可以直接把客户端代理到 ai-server,也可以同时启动 ai-gateway 走完整链路。 ### 方式一:直接启动 ai-server(本地最快) 1. 在仓库根目录执行 Maven 构建或运行 ai-server 模块。 2. 后端默认监听: - 端口:`8980` - 上下文路径:`/js/a` 3. 验证接口:访问 `http://127.0.0.1:8980/js/a/sys/health`,若返回健康信息,说明后端基本可用。 ### 方式二:同时启动 ai-gateway 1. ai-gateway 默认监听 `8080`,并与 ai-server 共享同一个 PostgreSQL 和 Redis。 2. 首次启动时,若 `gateway_service` 为空,会根据 `ai-gateway/src/main/resources/application.yaml` 中的播种数据写入服务、节点与健康检查路径。 3. 本地联调时,建议将默认节点 `base-url` 修改为本机 `http://127.0.0.1:8980`,避免网关转发到内网其他机器。 ### 环境变量覆盖 后端所有配置项都写成 `${ENV_NAME:默认值}`,可通过环境变量覆盖。仓库提供 Linux 环境变量脚本 `deploy/env.sh`,其中列出了数据库、Redis、Elasticsearch、存储路径、DuckDB、向量模型、清洗、聊天附件、认证窗口等配置。Windows 开发可直接修改 `application-dev.yaml`,Linux 部署推荐通过 `set -a; source deploy/env.sh; set +a` 后再启动服务。 **章节来源** - [ai-server/src/main/resources/application.yaml:1-60](file://ai-server/src/main/resources/application.yaml#L1-L60) - [ai-gateway/src/main/resources/application.yaml:1-81](file://ai-gateway/src/main/resources/application.yaml#L1-L81) - [ai-gateway/src/main/resources/application-dev.yaml:1-14](file://ai-gateway/src/main/resources/application-dev.yaml#L1-L14) - [deploy/env.sh:1-172](file://deploy/env.sh#L1-L172) ## Electron 客户端首次运行 ### 1. 进入前端目录 ```bash cd ai-electron/frontend ``` ### 2. 安装依赖 项目强制使用 pnpm: ```bash pnpm install ``` 如果提示不允许 npm/yarn,请安装 pnpm 后重试。 ### 3. 启动开发服务器 ```bash pnpm dev ``` 该命令等价于 `pnpm serve`,内部调用 Vite 开发服务器,并通过 `.env.development` 中的代理规则将 `/js` 请求转发到 `http://127.0.0.1:8980/js`。 ### 4. 校验前端代理 - 浏览器打开开发服务器提供的地址。 - 页面应能加载管理界面,并在登录后尝试访问后端接口。 - 如果网络面板中出现大量 `/js/a/...` 请求,说明前端上下文路径 `/a` 与后端 `server.servlet.context-path` 匹配正确。 ### 5. 构建命令 - `pnpm build`:生产模式构建。 - `pnpm build:tomcat`:Tomcat 部署模式构建。 - `pnpm preview`:构建后预览。 - `pnpm preview:dist`:预览构建产物,默认端口 `3100`。 **章节来源** - [ai-electron/frontend/package.json:1-60](file://ai-electron/frontend/package.json#L1-L60) - [ai-electron/frontend/.env.development:1-23](file://ai-electron/frontend/.env.development#L1-L23) - [AI_AGENT.md:60-120](file://AI_AGENT.md#L60-L120) ## 首次登录、激活授权与水印流程 ### 1. 输入服务端地址 首次运行时,客户端通常需要输入后端服务地址。本地开发有两种选择: | 场景 | 服务端地址 | 说明 | |---|---|---| | 直连 ai-server | `http://127.0.0.1:8980` | 适合单机调试。 | | 经过 ai-gateway | `http://127.0.0.1:8080` | 适合模拟多节点粘性路由。 | 开发模式下,前端默认通过 Vite 代理访问 `http://127.0.0.1:8980/js`,因此即使客户端显示的服务端地址是网关地址,最终 API 仍会落到后端上下文路径 `/js/a`。 ### 2. 登录绑定 - 使用平台初始账号登录。 - 登录态保存在 Redis 中,由 Sa-Token 管理。 - 如果 Redis 不可用,登录相关接口会抛异常,无法获得有效 token。 - 网关会读取 Redis 中的 token 获取当前登录用户,并按用户进行粘性路由。 ### 3. 激活与授权单元 仓库根 `readme.md` 中包含激活说明,核心是 `cmd` 目录下的 `regInfo.exe`。它用于: - 获取本机唯一机器码。 - 读取授权文件内容。 - 校验授权是否有效、是否过期、机器码是否匹配。 - 输出名称、机器码、手机号、单位、授权时间、过期时间、更新时间等字段。 典型流程: 1. 使用 `regInfo.exe machinecode` 获取本机机器码。 2. 将机器码提供给授权方生成授权文件。 3. 使用 `regInfo.exe read licensefile` 查看授权信息。 4. 使用 `regInfo.exe -f licensefile -verify` 校验授权有效性。 5. 将生成的授权文件放入产品运行期工作空间,通常是仓库中的 `QingJian` 相关位置。 授权错误码包括: | 错误码 | 含义 | |---:|---| | `0` | 注册文件有效。 | | `10001` | 授权文件无效。 | | `10002` | 已过期。 | | `10004` | 机器码不匹配。 | ### 4. 水印 项目属于安全研判平台,运行期通常会结合授权信息与水印机制控制展示与导出行为。首次运行时应优先完成授权校验,否则可能出现功能受限、导出被拦截或水印缺失等问题。 **章节来源** - [readme.md:1-76](file://readme.md#L1-L76) - [ai-gateway/src/main/resources/application.yaml:40-81](file://ai-gateway/src/main/resources/application.yaml#L40-L81) - [ai-server/src/main/resources/application-dev.yaml:40-87](file://ai-server/src/main/resources/application-dev.yaml#L40-L87) ## 常见启动失败排查 | 现象 | 可能原因 | 处理建议 | |---|---|---| | 启动时报 Java 版本错误 | 使用了低于 25 的 JDK | 切换到 Java 25,或使用 SDK 管理器指定版本。 | | 端口 `8980` 冲突 | 已有 ai-server 或其他服务占用 | 停止占用进程,或修改 ai-server 的 `server.port`。 | | 端口 `8080` 冲突 | 已有网关、Tomcat 或其他 Web 服务占用 | 停止占用进程,或修改 ai-gateway 的 `server.port`。 | | 前端代理 404 | Vite 代理目标地址错误 | 检查 `.env.development` 中 `VITE_PROXY`,默认代理到 `http://127.0.0.1:8980/js`。 | | 登录后立即失败或无权限 | Redis 不可用 | 启动 Redis,并将 `SPRING_DATA_REDIS_HOST` 或 `application-dev.yaml` 中的 Redis 地址改为本机。 | | 向量检索、模板索引报错 | PostgreSQL 未安装 pgvector | 安装 pgvector 扩展,重启 ai-server 使向量能力生效。 | | 向量能力不可用 | 本地模型路径错误或模型未下载 | 检查 `ZSJZ_EMBEDDING_MODEL_PATH` 或 `application-dev.yaml` 中的 embedding model-path;也可关闭本地模型开关回退在线模型。 | | DuckDB 开案失败 | DuckDB 驱动不可用或内存不足 | 检查 DuckDB 依赖,适当调整 `zsjz.duckdb.max-open-cases` 与 `memory-ratio`。 | | 网关登录后找不到后端 | ai-gateway 默认节点地址不是本机 | 修改 `ai-gateway/src/main/resources/application.yaml` 中节点的 `base-url` 为 `http://127.0.0.1:8980`。 | | 跨域失败 | 桌面客户端以 `file://` 加载前端 | 确保后端 `app.cors.enabled=true`,不要误关跨域。 | | `regInfo.exe` 报权限错误 | Windows 权限不足或被杀毒软件拦截 | 右键以管理员身份运行,或将程序从隔离区恢复信任。 | | 授权校验失败 | 机器码不匹配或授权过期 | 重新生成授权文件,核对机器码、单位、有效期。 | | Elasticsearch 启动慢或连接失败 | ES 未启动或地址不对 | 启动 ES,或注释掉相关功能,避免影响核心登录流程。 | | Neo4j 启动失败 | Neo4j 未安装或端口不通 | 图谱非强依赖,可暂时忽略;需要时安装并配置 `neo4j.uri`。 | ### 启动前自检清单 1. `java -version` 是否为 Java 25。 2. `mvn -v` 是否可用。 3. `node -v` 是否为 `>=20.19 || >=22.12`。 4. `pnpm -v` 是否可用。 5. PostgreSQL 是否可连接,是否启用 pgvector。 6. Redis 是否可连接。 7. DuckDB 是否能正常使用。 8. `sql/gateway.sql` 是否已在平台库执行。 9. `8980` 与 `8080` 是否空闲。 10. `ai-electron/frontend/.env.development` 中的代理地址是否与后端一致。 **章节来源** - [AI_AGENT.md:1-120](file://AI_AGENT.md#L1-L120) - [ai-server/src/main/resources/application.yaml:1-60](file://ai-server/src/main/resources/application.yaml#L1-L60) - [ai-server/src/main/resources/application-dev.yaml:1-87](file://ai-server/src/main/resources/application-dev.yaml#L1-L87) - [ai-gateway/src/main/resources/application.yaml:1-81](file://ai-gateway/src/main/resources/application.yaml#L1-L81) - [ai-electron/frontend/.env.development:1-23](file://ai-electron/frontend/.env.development#L1-L23) - [readme.md:1-76](file://readme.md#L1-L76) ## 开发建议 - 首次本地开发建议先跳过 ai-gateway,直接让前端代理到 `http://127.0.0.1:8980`,减少网关路由带来的干扰。 - 不要把 `application-dev.yaml` 中的数据库密码、内网 IP 提交到公开仓库。 - 修改后端端口或上下文路径时,必须同步更新前端代理和文件访问基础地址。 - 向量能力依赖较多,首次跑通时可先关闭本地 embedding 模型,确认登录、数据库、网关链路正常后再逐步开启。 - 使用 `deploy/env.sh` 统一环境变量时,注意文件名权限,尤其是包含真实凭证的生产环境。 [本节为通用开发建议,不直接分析具体代码文件] ## 附录:关键端口与路径 | 组件 | 端口 | 路径或用途 | |---|---:|---| | ai-server | `8980` | Spring Boot 后端,上下文 `/js/a`。 | | ai-gateway | `8080` | 网关,默认节点地址需根据本机情况修改。 | | PostgreSQL | `5432` | 平台主库,需安装 pgvector。 | | Redis | `6379` | Sa-Token 登录态缓存。 | | Elasticsearch | `9200` | 全文检索,可选。 | | Neo4j | `7687` | 图谱,可选。 | | Electron 前端预览 | `3100` | `pnpm preview:dist` 默认端口。 | **章节来源** - [ai-server/src/main/resources/application.yaml:1-60](file://ai-server/src/main/resources/application.yaml#L1-L60) - [ai-gateway/src/main/resources/application.yaml:1-81](file://ai-gateway/src/main/resources/application.yaml#L1-L81) - [ai-gateway/src/main/resources/application-dev.yaml:1-14](file://ai-gateway/src/main/resources/application-dev.yaml#L1-L14) - [ai-electron/frontend/package.json:1-60](file://ai-electron/frontend/package.json#L1-L60)