面向新加入的开发者:从零把后端
ai-server和前端ai-frontend跑起来。 编码约定、分层落位、Agent 子系统等改代码前必读的内容见 AI_AGENT.md,本文只讲「怎么跑起来」。
zsjz-ai/
├─ pom.xml # 父 POM(packaging=pom,Spring Boot 3.5.16),只聚合 ai-server
├─ ai-server/ # 后端:Spring Boot 3 + MyBatis-Plus + AgentScope
├─ ai-frontend/ # 前端:Vue3 + Vite7 + TS + Ant Design Vue(JeeSite 血统)
├─ sql/ # 建表 / 初始化脚本(手工执行,项目无 Flyway / Liquibase)
├─ qingjian/
│ ├─ system/ # 程序资产:conf / 模板库 / license / rocksdb / 基站库 / 模型
│ └─ data/ # 业务数据:cases/{caseId} / users / tmp / index(备份只备这个)
业务闭环:多源数据导入 → 清洗治理(dm)→ 建模分析(话单 / 资金 / 轨迹 / 画像 / 图谱)→ 可视化 → AI 对话式研判。
| 项 | 版本 | 校验命令 |
|---|---|---|
| JDK | 25(ai-server/pom.xml 的 java.version) |
java -version |
| Maven | 3.9.x+ | mvn -v |
| Node | >=20.19 \|\| >=22.12(package.json engines) |
node -v |
| pnpm | 10.x(只能用 pnpm,preinstall: only-allow pnpm) |
pnpm -v |
| SQLite 平台库 | 无需安装,加密 SQLite 文件 + JDBC 驱动内嵌(qingjian/system/db/plat) |
— |
| DuckDB | 无需安装,JDBC 驱动内嵌(案件分析库) | — |
| PostgreSQL | 14+ 且必须装 pgvector,但仅 ai-gateway 需要,ai-server 不用 | — |
| Redis | 任意近期版本,仅 ai-gateway 需要 | — |
| Neo4j | 可选,仅在配置图谱能力时需要 | — |
| ffmpeg + Vosk 中文模型 | 可选,仅音视频转写需要(图片/扫描件 OCR 不需要任何外部资产) | ffmpeg -version;模型目录含 am/ |
依赖服务的硬/软关系:
- SQLite(master) 是加密文件库
qingjian/system/db/plat,存平台元数据(table_info/table_field/case_info/ 银行卡与运营商字典 /lunar)与 AI 清洗元数据(ai_clean_*)。文件不存在时DataSourceConfig直接启动失败,不会静默新建空库。- ai-gateway 是独立进程,仍依赖 PostgreSQL(+pgvector) 与 Redis(
sa-token-redis-jackson已装配,Redis 不可用则所有StpUtil.*抛异常,无降级实现)。只跑 ai-server 时这两者都不需要。- 全文检索(
module/search)是进程内嵌入式 Lucene,索引落在各案件目录data/cases/{caseId}/lucene,不依赖任何外部检索服务。- DuckDB(slave) 是按案件/工作空间切换的文件库,不是常驻服务。
- 图片/扫描件 OCR 用 PP-OCRv4,模型随
rapidocr4jjar 分发、OpenCV 原生库在openpnp:opencvjar 内 —— 无需安装 tesseract、无需下载模型;Linux 需 glibc ≥ 2.27。- 音视频转写依赖外部 ffmpeg 与 Vosk 模型目录,缺失时只有音视频上传会以可读原因失败。Linux 一键安装:
sudo bash deploy/install-media-deps.sh;细节见 docs/design/ai-media-ocr-asr.md。
ai-server 的主库是一个加密 SQLite 文件,不是数据库服务:
| 项 | 值 |
|---|---|
| 文件 | qingjian/system/db/plat(PathConst.PLAT_DB_PATH) |
| 驱动 | org.sqlite.JDBC,由 io.github.willena:sqlite-jdbc:3.51.1.0 提供(SQLiteMC 分支,org.xerial 原版不支持加密) |
| 加密参数 | cipher=aes256cbc&key=xcj7xymg |
| 并发参数 | busy_timeout=15000&transaction_mode=IMMEDIATE(journal_mode 保持库原有的 delete,不改 WAL) |
配置写在 ai-server/src/main/resources/application-dev.yaml(pro 同结构):
spring.datasource.dynamic.datasource.master:
url: jdbc:sqlite:file:qingjian/system/db/plat?cipher=aes256cbc&key=xcj7xymg&busy_timeout=15000&transaction_mode=IMMEDIATE
driver-class-name: org.sqlite.JDBC
url 里的路径只是占位:DataSourceConfig 会按 PathConst.PLAT_DB_PATH 换成绝对路径,并在文件不存在时直接抛异常终止启动 —— 否则 SQLite 会静默新建一个空加密库,应用照常起来然后满屏 no such table。
该文件随
qingjian/一起被.gitignore忽略,新环境需从已有环境拷贝(见 §3.2)。 拿到文件后还要补建 AI 清洗元数据表,见 §4。
ai-gateway 另算:它是独立进程,仍连 PostgreSQL(+pgvector) 与 Redis,配置在 ai-gateway/src/main/resources/application-dev.yaml,与上面这套无关。
根目录统一小写 qingjian/,严格分两部分:
qingjian/
├─ system/ # 程序资产与系统状态(升级时可整体替换)
└─ data/ # 业务数据(唯一需要备份的目录),storage.local.root-path 默认 ./qingjian/data
com.zsjz.ai.common.constants.PathConst 以 项目根(自动探测 user.dir 或其父目录下的 qingjian/)为基准拼出 qingjian/system/...:
| 路径 | 用途 |
|---|---|
qingjian/system/conf/*.json |
系统配置 / AI 配置(SystemConfManager 读写) |
qingjian/system/rocksdb/d5e03ad1/ |
内置银行卡 BIN、手机号运营商 RocksDB |
qingjian/system/rocksdb/uy76tkp8/data.db |
RogueMap 数据 |
qingjian/system/db/5w8mf4kf |
基础案件库模板(保持原名);system/db/ 同时放平台库与临时库 |
qingjian/system/libs/cell/ |
基站库 BSSinfo_sc.bin + libCell.dll/.so(JNI,路径固定在 PathConst.CELL_TOWER_PATH_BIN) |
qingjian/system/libs/7zip/ |
7z 解压工具 |
qingjian/system/license/ |
授权文件 license.xlts 与 regInfo 工具 |
qingjian/system/models/ |
bge-m3、vosk-model |
qingjian/system/native/ |
OpenCV 原生库 |
业务数据按案件隔离在 qingjian/data/cases/{caseId}/(案件库、导入原件、EDS 材料、对话附件、AI 产物、Python 输出、图谱历史),完整目录树见 docs/design/storage-layout.md。
.gitignore 里 /qingjian/ 被忽略,这些资产不在版本库中,新环境需找同事单独拷贝或用 deploy/storage-layout-init.sh 从旧目录迁入;缺了它们启动后置任务(AppLoadEndEventListener 初始化 RocksDB / 基站库)会失败。
项目没有自动建表机制,sql/ 下只有部分脚本,需手工执行:
| 脚本 | 目标库 | 内容 |
|---|---|---|
sql/ai_clean_sqlite.sql |
平台库(加密 SQLite) | 6 张 ai_clean_* 表 + 11 个索引 + 17 条内置同义词,幂等可重复执行 |
sql/plat.sql |
— | 历史参考脚本,严禁执行:以 drop table 开头,会删掉平台库在用的表;且含已删除模块的 chat_* / knowledge_* 旧表 |
sql/ai_clean.sql |
— | PG 时代参考,列集合与 ai_clean_sqlite.sql 一致,不再对运行期库执行 |
sql/external_tables.sql / external_table_field.sql |
案件库(DuckDB) + 元数据 | 13 张外部数据表建表 + table_info/table_field 登记 |
sql/case_table*.sql、create_table_2.sql、table_data_1.sql |
案件库(DuckDB) | 案件业务表与初始配置 |
sql/ 下其余 agent_* / insight_* / knowledge_* / gateway.sql / revert-user-system.sql 属已删除模块或 ai-gateway,ai-server 不需要执行。
plat 文件里已有平台元数据表与字典数据(table_info / table_field / case_info / system_info / lunar / phone_isp / bank_card_issuer_info),这些表一律不动。需要补建的只有 6 张 ai_clean_*。
本机没有 sqlite3 CLI,Python 也打不开加密库,用驱动 jar + jshell 执行(先停 ai-server,并先备份 plat 文件):
cd E:/workspace/zsjz-ai
cp qingjian/system/db/plat qingjian/system/db/plat.bak-$(date +%Y%m%d)
jshell --class-path "D:/soft/repository/io/github/willena/sqlite-jdbc/3.51.1.0/sqlite-jdbc-3.51.1.0.jar" --feedback silent - <<'EOF'
import java.sql.*; import java.nio.file.*;
Connection c = DriverManager.getConnection("jdbc:sqlite:file:E:/workspace/zsjz-ai/qingjian/system/db/plat?cipher=aes256cbc&key=xcj7xymg");
String sql = Files.readString(Path.of("sql/ai_clean_sqlite.sql"));
c.setAutoCommit(false);
for (String s : sql.split(";")) { String t = s.replaceAll("(?m)^\\s*--.*$", "").trim(); if (!t.isEmpty()) c.createStatement().execute(t); }
c.commit(); c.close();
/exit
EOF
jar 路径按本机 Maven 仓库调整(本项目是
D:/soft/repository,不是~/.m2)。 脚本按;切分逐条执行 —— SQLite JDBC 对多语句串只执行第一条,整篇灌进去不会生效。 复核:6 张新表 + 11 个索引存在,ai_clean_synonym17 行、其余 5 张 0 行,原有表行数不变。
案件库按案件隔离,建案时由 CaseInfoService#create 从模板 qingjian/system/db/5w8mf4kf 复制生成,无需手工初始化。
⚠️ 平台库的
table_info/table_field元数据是清洗与治理树的真源,新环境必须从已有可用环境拷贝整个plat文件,sql/目录不自带这套数据。 改表结构时务必补sql/脚本,并同步table_info/table_field元数据链路。 升级包(POST /sys/uploadUpgrade)不再覆盖平台库、也不对它执行建表脚本,只逐案执行案件库升级 SQL。
cd E:/workspace/zsjz-ai # ★ 推荐在仓库根执行;PathConst 会自动探测 qingjian/ 所在目录
mvn -pl ai-server -am clean compile # 编译
mvn -pl ai-server spring-boot:run # 运行
mvn -pl ai-server test # 跑测试
mvn -pl ai-server -am clean package -DskipTests # 打包
IDEA 里直接跑 com.zsjz.ai.App,Working directory 建议设为仓库根目录;即使误设为模块目录,PathConst 也会向上找到 qingjian/,数据不会写到 ai-server/ 下。
上面四条命令都在仓库根执行;
cd ai-server后单模块构建也能解析到父 POM,且运行时路径会按项目根解析,不会产生第二套数据。
启动后:
curl http://localhost:8980/js/a/sys/health # 免登录健康检查
关键地址(server.port=8980,server.servlet.context-path=/js/a):
| 端点 | 说明 |
|---|---|
POST /js/a/auth/login |
登录,返回 token;body: {username, password} 明文 JSON |
GET /js/a/sys/health |
就绪探测(白名单,免登录) |
POST /js/a/chat/stream |
Agent 对话 SSE |
生效配置只有
application.yaml+application-dev.yaml(resources下没有别的 yaml)。context-path必须写成/js/a(以/开头、不能以/结尾),原 Solon 写法!/js/a/会让 Tomcat 直接抛IllegalArgumentException起不来。
Agent 用的模型与厂商信息存平台库 agent_model / agent_model_provider,通过前端「模型管理」界面(后端 module/agent 的 /models/**)维护,不是写在 yaml 里。想跑通 AI 研判,先在这个界面上配好一个可用的 Provider(DashScope / OpenAI 兼容 / Ollama,三套 AgentScope 扩展都已在 pom 引入)。
cd ai-frontend
pnpm install # = pnpm bootstrap
pnpm dev # http://localhost:3100
.env 与 .env.development 关键项(默认值已可用):
VITE_PORT = 3100 # dev server 端口
VITE_PROXY = [["/js","http://127.0.0.1:8980/js",false]] # 代理到本地后端
VITE_GLOB_API_URL_PREFIX = /js
VITE_GLOB_ADMIN_PATH = /a
后端换地址时只改 VITE_PROXY 一行(不能换行)。浏览器打开 http://localhost:3100,用 admin / admin123 登录。
日常命令:
pnpm type:check # vue-tsc --noEmit
pnpm lint:eslint # 自动修复
pnpm lint:all # 全量(含 install)
pnpm build # 生产构建(--mode production)
pnpm build:tomcat # tomcat 模式,输出到 .env.tomcat 的 VITE_OUTPUT_DIR
pnpm preview:dist # 预览构建产物 :3100
.npmrc里配了@jeesite私有源;装不动私有包时先确认网络/镜像可达。
/js/a/... = urlPrefix(/js) + adminPath(/a) + 后端 context-path。前端 defHttp 自动补 /js,代码里写 url: adminPath + '/xxx';不走 defHttp(fetch / <img src>)时手动拼 glob.apiUrl + glob.urlPrefix + glob.adminPath + path。这三处必须同步改。token-name: x-token、is-read-cookie: false(仅 Header)。defHttp 自动注入;fetch 场景要手动带 'x-token': getToken()。原生 EventSource 无法自定义请求头,SSE 一律用 fetch + body.getReader() 读增量。body.code = 401(不是 HTTP 401),前端据此跳登录页。module/agent 的 /chat/**(含 /chat/results/**)是裸返回,调它们必须传 { isTransformResponse: false };/models/** 是 Result<T> 包装,用默认 transform。is-concurrent 默认 false),后登录顶掉前登录 —— 两个浏览器窗口同时登录,前一个会 401,这是设计行为不是 bug。联调需要同账号多端时,启动加 SA_TOKEN_CONCURRENT=true。LicenseFilter 当前是透传实现,授权校验下沉在 SystemService 的 /sys/info、/sys/checkAuth。它被 Spring 自动注册为 /* 全局过滤器,doFilter 里的 chain.doFilter 绝不能删 —— 删了表现为所有接口返回 200 + Content-Length: 0 空白,连 404 都没有,日志无异常。uno.config.ts 的 content.pipeline.include 只扫 **/*.{vue,tsx,ts},menu.json 不在扫描范围,而 Icon 组件是运行时拼 i-<collection>:<name> 类名的 → 新图标要把完整 i- 类名加进 uno.config.ts 的 safelist。src/core/router/helper/routeHelper.ts 的 explicitDynamicViewMap 加显式映射,默认的 import.meta.glob('**/views/**') 会命中 node_modules 里的同名 views。com.zsjz.ai.*。历史上包名迁移漏改 XML(com.qingjian.*)会让 MyBatis 启动即炸。src/<domain>/api/types/{dto,query}.ts。@Tool(description=...) / @ToolParam,并同步更新 AgentToolRegistryTest#TOTAL_BUSINESS_TOOLS 的数量断言。# 后端
mvn -pl ai-server -am clean compile
# 前端
cd ai-frontend && pnpm type:check && pnpm lint:eslint
sql/ 补脚本 + table_info / table_field 元数据同步StpUtil.getLoginIdAsLong() 归属校验System.out.println 残留| 现象 | 原因 / 处置 |
|---|---|
启动即 ContextPath must start with '/'... |
application.yaml 的 context-path 被改成了 !/js/a/ 或带尾斜杠 → 改回 /js/a |
Failed to parse mapping resource: mappers/... |
XML 的 namespace/resultType 仍是 com.qingjian.* → 改 com.zsjz.ai.* |
PSQLException: 关系 "table_info" 不存在 |
平台库结构未导入(见 §4 已知缺口) |
登录必失败 / 所有 StpUtil 抛异常 |
Redis 不可达(硬依赖,无降级) |
| 所有接口返回空白 200 | LicenseFilter.doFilter 漏了 chain.doFilter |
| 前端请求 404 | /js 代理指向错、或后端 context-path 与前端 urlPrefix+adminPath 不一致 |
| SSE 收不到 / 401 | 用了原生 EventSource(带不了 header),或漏传 isTransformResponse:false |
| 菜单图标缺失 | 图标类名未进 uno.config.ts 的 safelist |
npm install 被拒 |
项目 preinstall: only-allow pnpm,只能用 pnpm |
| 上传大文件失败 | max-file-size: 200MB / max-request-size: 500MB(application.yaml) |
| 文档 | 说明 |
|---|---|
| AI_AGENT.md | 仓库级编码约定:分层落位、命名规范、Agent 工具清单与硬约束、前后端渲染契约 |
ai-server/CODE_WIKI.md |
模块级说明,⚠️ 部分章节仍是 Solon / com.qingjian 时代内容(app.yml、contextPath !/js/a/、启动类 Solon.start()),以代码和本文配置为准 |
docs/design/continuous-insight-plan.md、docs/design/tool-call-detail-plan.md 等 |
各特性设计稿(根目录 *-plan.md / *.md) |
readme.md |
离线栅格地图(pmtiles 转换)与 regInfo 授权工具的零散说明 |