# 快速开始
**本文引用的文件**
- [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)