Halaman utama Jelajahi Bantuan
Daftar Masuk
vectorSeek
/
zsjz-ai
5
0
Fork 0
Berkas Masalah 0 Permintaan Tarik 0 Wiki
Pohon: 13f7dd126a
Ranting Tag
zsjz-ai
/
.qoder
/
repowiki
/
zh
/
content
/
快速开始.md

快速开始.md 17 KB
Riwayat Mentahan

快速开始

本文引用的文件

  • readme.md
  • AI_AGENT.md
  • pom.xml
  • deploy/env.sh
  • ai-server/src/main/resources/application.yaml
  • ai-server/src/main/resources/application-dev.yaml
  • ai-gateway/src/main/resources/application.yaml
  • ai-gateway/src/main/resources/application-dev.yaml
  • sql/gateway.sql
  • ai-electron/frontend/package.json
  • ai-electron/frontend/.env.development

目录

  1. 简介
  2. 前置环境
  3. 项目结构速览
  4. 数据库与脚本初始化
  5. 后端服务启动顺序
  6. 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
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
  • pom.xml:1-23

项目结构速览

graph TB
    Client["Electron 客户端<br/>Vite 开发服务器"] --> Gateway["ai-gateway<br/>端口 8080"]
    Client --> Server["ai-server<br/>端口 8980，上下文 /js/a"]
    Gateway --> Server
    Server --> PG["PostgreSQL + pgvector<br/>平台主库"]
    Server --> Redis["Redis<br/>Sa-Token 会话"]
    Server --> Duck["DuckDB<br/>案件分析库"]
    PG --> GTables["gateway_service<br/>gateway_node<br/>gateway_user_route"]

图表来源

  • ai-gateway/src/main/resources/application.yaml:1-81
  • ai-server/src/main/resources/application.yaml:1-60
  • ai-gateway/src/main/resources/application-dev.yaml:1-14
  • sql/gateway.sql:1-107

章节来源

  • AI_AGENT.md:1-120
  • ai-gateway/src/main/resources/application.yaml:1-81
  • ai-server/src/main/resources/application.yaml:1-60

数据库与脚本初始化

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
  • deploy/env.sh:1-172
  • AI_AGENT.md:1-120

后端服务启动顺序

推荐顺序：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
  • ai-gateway/src/main/resources/application.yaml:1-81
  • ai-gateway/src/main/resources/application-dev.yaml:1-14
  • deploy/env.sh:1-172

Electron 客户端首次运行

1. 进入前端目录

cd ai-electron/frontend

2. 安装依赖

项目强制使用 pnpm：

pnpm install

如果提示不允许 npm/yarn，请安装 pnpm 后重试。

3. 启动开发服务器

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
  • ai-electron/frontend/.env.development:1-23
  • AI_AGENT.md:60-120

首次登录、激活授权与水印流程

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
  • ai-gateway/src/main/resources/application.yaml:40-81
  • ai-server/src/main/resources/application-dev.yaml:40-87

常见启动失败排查

现象 可能原因 处理建议
启动时报 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
  • ai-server/src/main/resources/application.yaml:1-60
  • ai-server/src/main/resources/application-dev.yaml:1-87
  • ai-gateway/src/main/resources/application.yaml:1-81
  • ai-electron/frontend/.env.development:1-23
  • readme.md:1-76

开发建议

  • 首次本地开发建议先跳过 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
  • ai-gateway/src/main/resources/application.yaml:1-81
  • ai-gateway/src/main/resources/application-dev.yaml:1-14
  • ai-electron/frontend/package.json:1-60