# 构建命令与脚本 **本文引用的文件** - [pom.xml](file://pom.xml) - [ai-gateway/pom.xml](file://ai-gateway/pom.xml) - [ai-server/pom.xml](file://ai-server/pom.xml) - [ai-electron/package.json](file://ai-electron/package.json) - [ai-electron/frontend/package.json](file://ai-electron/frontend/package.json) - [deploy/env.sh](file://deploy/env.sh) - [cmd/uninstall.bat](file://cmd/uninstall.bat) - [cmd/uninstall.sh](file://cmd/uninstall.sh) - [ai-gateway/src/main/resources/application.yaml](file://ai-gateway/src/main/resources/application.yaml) - [ai-server/src/main/resources/application.yaml](file://ai-server/src/main/resources/application.yaml) - [ai-electron/cmd/builder.json](file://ai-electron/cmd/builder.json) - [ai-electron/electron/config/config.default.ts](file://ai-electron/electron/config/config.default.ts) - [ai-electron/electron/config/windowOptions.ts](file://ai-electron/electron/config/windowOptions.ts) ## 目录 1. [引言](#引言) 2. [项目结构概览](#项目结构概览) 3. [Maven 后端构建命令](#maven-后端构建命令) 4. [前端与 Electron 客户端构建命令](#前端与-electron-客户端构建命令) 5. [Electron 打包产物与输出路径](#electron-打包产物与输出路径) 6. [安装、启动与卸载脚本](#安装启动与卸载脚本) 7. [环境变量覆盖后端配置](#环境变量覆盖后端配置) 8. [典型工作流](#典型工作流) 9. [常见错误与解决方法](#常见错误与解决方法) 10. [结论](#结论) ## 引言 本仓库是一个包含 Java 后端与 Electron 桌面客户端的多模块工程。整体分为三层: - **Maven 父工程**:统一管理 `ai-server` 与 `ai-gateway` 两个 Spring Boot 子模块。 - **Java 后端服务**: - `ai-gateway`:基于 Spring Cloud Gateway WebFlux 的转发网关,端口默认 `8080`。 - `ai-server`:业务后端,端口默认 `8980`,上下文路径 `/js/a`。 - **Electron 客户端**:基于 ElectronEgg 框架,前端使用 Vue + Vite + pnpm,打包目标为 Windows、macOS、Linux。 开发者通常同时运行 Gateway、ai-server 和 Electron 客户端;运维或打包人员则使用 Maven 构建后端 Jar,并使用 Electron 打包命令生成安装包。 ```mermaid graph TB Dev["开发者终端"] --> Maven["Maven 父工程
zsjz-ai"] Dev --> Pnpm["pnpm 前端命令
ai-electron/frontend"] Dev --> Electron["Electron 客户端命令
ai-electron"] Maven --> Gateway["ai-gateway
Spring Cloud Gateway
端口 8080"] Maven --> Server["ai-server
Spring Boot
端口 8980
上下文 /js/a"] Electron --> Frontend["Vite 前端开发服务器"] Electron --> Main["Electron 主进程"] Frontend --> Gateway Main --> Gateway Gateway --> Server ``` **图示来源** - [pom.xml:1-23](file://pom.xml#L1-L23) - [ai-gateway/src/main/resources/application.yaml:1-20](file://ai-gateway/src/main/resources/application.yaml#L1-L20) - [ai-server/src/main/resources/application.yaml:1-10](file://ai-server/src/main/resources/application.yaml#L1-L10) - [ai-electron/package.json:1-25](file://ai-electron/package.json#L1-L25) ## 项目结构概览 | 模块 | 类型 | 主要职责 | 关键入口 | |---|---|---|---| | 根目录 `pom.xml` | Maven 父工程 | 声明 `ai-server`、`ai-gateway` 两个模块 | `mvn` 聚合命令 | | `ai-gateway` | Spring Boot 子模块 | 按用户粘性路由转发到 ai-server | 端口 `8080`,上下文路径不强制 | | `ai-server` | Spring Boot 子模块 | 业务逻辑、数据库、Redis、向量模型、AI 能力 | 端口 `8980`,上下文路径 `/js/a` | | `ai-electron` | Electron 客户端 | 桌面应用入口、打包、加密、更新 | `package.json` scripts | | `ai-electron/frontend` | Vue + Vite 前端 | 开发、构建、预览、代码检查 | `pnpm dev`、`pnpm build` | | `deploy/env.sh` | Bash 环境变量脚本 | 统一设置 ai-server 运行时环境变量 | 通过 `source` 或 systemd `EnvironmentFile` 加载 | | `cmd/uninstall.*` | 卸载脚本 | 清理客户端进程与用户数据目录 | Linux/macOS 用 shell,Windows 用 bat | **章节来源** - [pom.xml:12-23](file://pom.xml#L12-L23) - [ai-gateway/src/main/resources/application.yaml:1-20](file://ai-gateway/src/main/resources/application.yaml#L1-L20) - [ai-server/src/main/resources/application.yaml:1-10](file://ai-server/src/main/resources/application.yaml#L1-L10) - [ai-electron/package.json:1-25](file://ai-electron/package.json#L1-L25) - [ai-electron/frontend/package.json:1-30](file://ai-electron/frontend/package.json#L1-L30) - [deploy/env.sh:1-30](file://deploy/env.sh#L1-L30) - [cmd/uninstall.sh:1-10](file://cmd/uninstall.sh#L1-L10) ## Maven 后端构建命令 ### 父工程与子模块关系 根 `pom.xml` 是 Spring Boot Starter Parent 的子工程,类型为 `pom`,包含两个模块: | 模块 | groupId | artifactId | 说明 | |---|---|---|---| | 父工程 | `com.zsjz` | `zsjz-ai` | 聚合构建,不产 Jar | | 网关 | `com.zsjz` | `ai-gateway` | Spring Cloud Gateway WebFlux | | 后端 | `com.zsjz` | `ai-server` | 业务后端 | 两者都继承 `com.zsjz:zsjz-ai:1.0`,Java 版本要求为 `25`。 ```mermaid flowchart TD Parent["Maven 父工程
zsjz-ai:1.0"] --> GatewayPom["ai-gateway/pom.xml"] Parent --> ServerPom["ai-server/pom.xml"] GatewayPom --> GatewayJar["ai-gateway.jar"] ServerPom --> ServerJar["ai-server.jar"] ``` **图示来源** - [pom.xml:1-23](file://pom.xml#L1-L23) - [ai-gateway/pom.xml:1-20](file://ai-gateway/pom.xml#L1-L20) - [ai-server/pom.xml:1-25](file://ai-server/pom.xml#L1-L25) ### 常用 Maven 命令 | 场景 | 命令 | 说明 | |---|---|---| | 在父工程构建全部后端 | `mvn clean package -DskipTests` | 编译并打包 `ai-gateway` 与 `ai-server` | | 仅构建网关 | `mvn -pl ai-gateway clean package -DskipTests` | 跳过测试,生成 `ai-gateway.jar` | | 仅构建后端 | `mvn -pl ai-server clean package -DskipTests` | 跳过测试,生成 `ai-server.jar` | | 本地调试后端 | `mvn -pl ai-server spring-boot:run` | 以 Spring Boot 方式直接运行 | | 本地调试网关 | `mvn -pl ai-gateway spring-boot:run` | 以 Spring Boot 方式直接运行 | | 只编译不打包 | `mvn -pl ai-server,ai-gateway compile` | 适合 IDE 同步 | 注意:`ai-gateway` 在构建阶段会把根目录 `sql/gateway.sql` 复制到 `classpath:db/gateway.sql`,因此首次 `package` 前需要确保该 SQL 文件存在。 ### 构建依赖与环境要求 - **JDK**:`java.version=25`,父工程与两个子模块均声明此版本。 - **Maven**:能解析 Spring Boot 3.5.16 与 Spring Cloud 2025.0.1。 - **网络**:需访问 Maven 中央仓库下载 Spring、PostgreSQL、sa-token、AgentScope、DJL、ONNX Runtime 等依赖。 - **测试环境**:如需运行测试,可能还需要 Redis、PostgreSQL、Elasticsearch、Neo4j 等外部服务,但普通构建可跳过测试。 **章节来源** - [pom.xml:1-23](file://pom.xml#L1-L23) - [ai-gateway/pom.xml:1-30](file://ai-gateway/pom.xml#L1-L30) - [ai-gateway/pom.xml:100-148](file://ai-gateway/pom.xml#L100-L148) - [ai-server/pom.xml:1-40](file://ai-server/pom.xml#L1-L40) ## 前端与 Electron 客户端构建命令 ### 前端模块 前端位于 `ai-electron/frontend`,使用 pnpm、Vite、Vue 3、TypeScript。 | 命令 | 作用 | 备注 | |---|---|---| | `pnpm bootstrap` | 执行 `pnpm install` 安装依赖 | 预安装脚本强制使用 pnpm | | `pnpm dev` | 启动 Vite 开发服务器 | 默认监听开发端口,支持热更新 | | `pnpm serve` | 等同于 `pnpm dev` | 别名命令 | | `pnpm build` | 生产构建前端资源 | 启用内存限制,输出到 `dist` | | `pnpm build:tomcat` | 构建为 Tomcat 部署模式 | 清空输出目录 | | `pnpm preview` | 构建后预览生产产物 | 默认端口 `3100` | | `pnpm type:check` | TypeScript 类型检查 | 不输出文件 | | `pnpm lint:all` | 安装依赖、类型检查、ESLint、Prettier、Stylelint | 完整代码质量流程 | | `pnpm reinstall` | 删除锁文件和依赖后重装 | 依赖损坏时可用 | | `pnpm uninstall` | 删除 `node_modules` | 清理依赖目录 | 前端引擎要求 Node.js 版本满足 `>=20.19 || >=22.12`,包管理器锁定为 pnpm `10.25.0`。 ### Electron 客户端模块 Electron 客户端位于 `ai-electron`,其 `package.json` 提供两类命令: | 命令 | 作用 | 说明 | |---|---|---| | `pnpm dev` | 启动 Electron 开发模式 | 实际调用 `ee-bin dev` | | `pnpm start` | 启动已构建的 Electron 客户端 | 实际调用 `ee-bin start` | | `pnpm build` | 构建前端、构建 Electron、加密 | 等价于先 `build-frontend`,再 `build-electron`,最后 `encrypt` | | `pnpm dev-frontend` | 仅启动前端开发服务 | 参数 `--serve=frontend` | | `pnpm dev-electron` | 仅启动 Electron 开发服务 | 参数 `--serve=electron` | | `pnpm build-frontend` | 构建前端资源 | 调用 ee-bin 并移动前端产物 | | `pnpm build-electron` | 构建 Electron 部分 | 调用 ee-bin 构建 Electron 层 | | `pnpm test` | 运行 Vitest 单测 | 使用 electron 相关测试工具 | | `pnpm test:watch` | 监听模式运行测试 | 开发时调试测试用例 | | `pnpm typecheck` | TypeScript 类型检查 | 不输出文件 | | `pnpm re-sqlite` | 重建 better-sqlite3 原生模块 | 平台变化后可能需要 | ### 打包命令 Electron 客户端提供各平台打包命令: | 命令 | 平台 | 说明 | |---|---|---| | `pnpm build-w` | Windows x64 | 构建 Windows 安装包 | | `pnpm build-we` | Windows | 构建 Windows 扩展或增强产物 | | `pnpm build-m` | macOS ARM64 | 构建 Apple Silicon Mac 安装包 | | `pnpm build-m-x86` | macOS x86_64 | 构建 Intel Mac 安装包 | | `pnpm build-m-arm64` | macOS ARM64 | 同上,ARM64 专用别名 | | `pnpm build-l` | Linux | 构建 Linux 安装包 | 这些命令最终委托给 `ee-bin build --cmds=`,由 ElectronEgg 框架完成打包流程。 **章节来源** - [ai-electron/frontend/package.json:1-40](file://ai-electron/frontend/package.json#L1-L40) - [ai-electron/frontend/package.json:140-162](file://ai-electron/frontend/package.json#L140-L162) - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) ## Electron 打包产物与输出路径 ### 输出目录 Electron 打包输出目录由 `ai-electron/cmd/builder.json` 中的 `directories.output` 指定为 `out`。也就是说,所有安装包和展开目录都会放在 `ai-electron/out` 下。 ```mermaid flowchart TD Build["pnpm build-*"] --> Builder["electron-builder / ee-bin"] Builder --> OutDir["ai-electron/out"] OutDir --> WinExe["qingjian-ai-client-win-200.0.0-x64.exe"] OutDir --> Unpacked["win-unpacked/"] OutDir --> Latest["latest.yml"] OutDir --> Config["builder-effective-config.yaml"] OutDir --> Debug["builder-debug.yml"] ``` **图示来源** - [ai-electron/cmd/builder.json:1-20](file://ai-electron/cmd/builder.json#L1-L20) ### Windows 产物 Windows 使用 NSIS 打包器,产物包括: | 产物 | 含义 | |---|---| | `qingjian-ai-client-win-200.0.0-x64.exe` | 可分发的安装包 | | `qingjian-ai-client-win-200.0.0-x64.exe.blockmap` | 增量更新校验文件 | | `win-unpacked/qingjian-ai-client.exe` | 未打包的可执行程序 | | `win-unpacked/resources/app.asar` | 应用代码包 | | `win-unpacked/resources/app-update.yml` | 自动更新配置 | | `win-unpacked/locales/zh-CN.pak` | 中文界面语言包 | | `latest.yml` | 最新版本信息(通用发布) | NSIS 安装器允许非一键安装、允许提权、允许修改安装目录,并创建桌面快捷方式和开始菜单快捷方式。 ### macOS 与 Linux 产物 - macOS:根据命令生成 ARM64 或 x86_64 架构的安装包。 - Linux:默认目标是 `deb` 包,分类为 `Utility`。 - 应用名称:`qingjian-ai-client`。 - 应用标识:`com.zsjz.qingjian.client`。 - 打包时排除 `cmd/`、`data/`、`electron/`、`frontend/`、`logs/`、`out/`、`go/`、`python/` 等目录,避免把源码和中间产物打入安装包。 ### 前端开发模式下的页面加载 Electron 默认从 `file://` 协议加载前端,索引页路径为 `/public/dist/index.html`。这意味着: - 开发时前端必须先构建出 `public/dist/index.html`。 - 浏览器中访问后端接口属于跨域请求,因此后端必须开启跨域。 - Electron 主窗口启用了 `nodeIntegration=true` 且关闭 `contextIsolation`,以便渲染进程直接调用 IPC。 ```mermaid sequenceDiagram participant User as "用户" participant Electron as "Electron 主进程" participant Renderer as "渲染进程" participant Gateway as "Gateway :8080" participant Server as "ai-server :8980" User->>Electron: 启动客户端 Electron->>Renderer: 打开 file:///public/dist/index.html Renderer->>Gateway: 发起 /js/a 后端请求 Gateway->>Server: 转发到 http://localhost:8980/js/a Server-->>Gateway: 返回 JSON Gateway-->>Renderer: 返回响应 Renderer-->>User: 显示界面 ``` **图示来源** - [ai-electron/electron/config/config.default.ts:1-50](file://ai-electron/electron/config/config.default.ts#L1-L50) - [ai-electron/electron/config/windowOptions.ts:1-20](file://ai-electron/electron/config/windowOptions.ts#L1-L20) - [ai-gateway/src/main/resources/application.yaml:1-20](file://ai-gateway/src/main/resources/application.yaml#L1-L20) - [ai-server/src/main/resources/application.yaml:1-10](file://ai-server/src/main/resources/application.yaml#L1-L10) **章节来源** - [ai-electron/cmd/builder.json:1-57](file://ai-electron/cmd/builder.json#L1-L57) - [ai-electron/electron/config/config.default.ts:1-50](file://ai-electron/electron/config/config.default.ts#L1-L50) - [ai-electron/electron/config/windowOptions.ts:1-41](file://ai-electron/electron/config/windowOptions.ts#L1-L41) ## 安装、启动与卸载脚本 ### 前端安装脚本 `ai-electron/frontend/bin/install.sh` 是一个简短的辅助脚本: 1. 切换到 `ai-electron/frontend` 目录。 2. 执行 `pnpm install`。 3. 返回 `bin` 目录。 它只是对 `cd .. && pnpm install` 的封装,方便从 `bin` 目录直接执行。 ### 前端启动脚本 `ai-electron/frontend/bin/startup.sh` 的作用: 1. 切换到 `ai-electron/frontend` 目录。 2. 执行 `pnpm dev`。 3. 返回 `bin` 目录。 适合在类 Unix 系统中双击或通过终端快速启动前端开发服务器。 ### 前端构建脚本 `ai-electron/frontend/bin/build.sh` 的作用: 1. 切换到 `ai-electron/frontend` 目录。 2. 执行 `pnpm build`。 3. 返回 `bin` 目录。 用于在 Linux 或 macOS 上构建前端生产资源。 ### Linux/macOS 卸载脚本 `cmd/uninstall.sh` 是 QingJian 客户端的卸载清理脚本,行为如下: | 步骤 | 行为 | |---|---| | 安全检查 | 如果 `$HOME` 为空,直接报错退出 | | 终止进程 | 使用 `pkill -9 -f "qingjian-client"` 强制结束客户端进程 | | 等待释放 | 若进程被成功终止,等待 2 秒让文件句柄释放 | | 清理数据目录 | 递归删除三个可能的用户数据目录 | | 报告结果 | 对每个目录输出是否删除、不存在或权限失败 | 需要清理的目录包括: | 目录 | 用途 | |---|---| | `$HOME/.config/qingjian-client` | 客户端配置目录 | | `$HOME/.local/share/QingJian` | 客户端共享数据目录 | | `$HOME/.qingjian-client` | 客户端历史数据目录 | ```mermaid flowchart TD Start["执行 uninstall.sh"] --> CheckHome["检查 $HOME 是否为空"] CheckHome --> HomeEmpty{"$HOME 为空?"} HomeEmpty -->|是| ExitError["打印错误并退出"] HomeEmpty -->|否| KillProc["终止 qingjian-client 进程"] KillProc --> WaitFiles{"是否找到进程?"} WaitFiles -->|是| Sleep["等待 2 秒释放文件句柄"] WaitFiles -->|否| SkipKill["提示未发现进程"] Sleep --> CleanDirs["遍历并删除用户数据目录"] SkipKill --> CleanDirs CleanDirs --> Done["输出清理完成"] ``` **图示来源** - [cmd/uninstall.sh:1-53](file://cmd/uninstall.sh#L1-L53) ### Windows 卸载脚本 `cmd/uninstall.bat` 是 Windows 平台的卸载脚本。虽然当前仓库内容无法以 UTF-8 正常读取,但从命名和位置可以确定其用途是配合 Windows 客户端进行卸载或清理操作。实际使用时应通过管理员终端或右键“以管理员身份运行”执行,以避免权限不足。 **章节来源** - [ai-electron/frontend/bin/install.sh:1-5](file://ai-electron/frontend/bin/install.sh#L1-L5) - [ai-electron/frontend/bin/startup.sh:1-5](file://ai-electron/frontend/bin/startup.sh#L1-L5) - [ai-electron/frontend/bin/build.sh:1-5](file://ai-electron/frontend/bin/build.sh#L1-L5) - [cmd/uninstall.sh:1-53](file://cmd/uninstall.sh#L1-L53) - [cmd/uninstall.bat](file://cmd/uninstall.bat) ## 环境变量覆盖后端配置 ### 设计原则 `ai-server/src/main/resources/application.yaml` 中的配置项大多采用 `${ENV_NAME:默认值}` 的形式。例如: - `app.cors.enabled=${APP_CORS_ENABLED:true}` - `spring.task.scheduling.pool.size=${SPRING_TASK_SCHEDULING_POOL_SIZE:4}` - `spring.servlet.multipart.max-file-size=${SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE:200MB}` 这意味着:**环境变量优先级高于 YAML 默认值**。如果设置了同名环境变量,Spring Boot 会优先使用环境变量值。 ### env.sh 的作用 `deploy/env.sh` 是专门为 Linux 部署设计的后端环境变量脚本。它的核心作用有三点: 1. **集中暴露变量**:把所有可覆盖的环境变量列在一个文件中,便于逐项修改。 2. **保持默认行为一致**:即使不设置任何环境变量,脚本中的默认值也与 `application-dev.yaml` 的开发环境行为保持一致。 3. **方便系统级注入**:既可以在 shell 中 `source`,也可以作为 systemd 的 `EnvironmentFile`。 脚本注释明确指出:端口 `8980`、上下文路径 `/js/a`、应用名 `ai-server` 是硬编码在 `application.yaml` 中的,不参与环境变量参数化,因此不会出现在 `env.sh` 中。 ### 加载方式 脚本文档给出两种标准用法: | 场景 | 用法 | |---|---| | 手动启动 | `set -a; source deploy/env.sh; set +a`,然后 `java -jar ai-server.jar` | | systemd 服务 | 在单元文件中添加 `EnvironmentFile=/opt/zsjz-ai/deploy/env.sh` | `set -a` 的作用是使后续赋值自动导出为环境变量,`set +a` 恢复默认行为。这样 `source` 后执行的 `java -jar` 就能读到这些变量。 ### 关键环境变量分类 | 类别 | 示例变量 | 说明 | |---|---|---| | 跨域 | `APP_CORS_ENABLED`、`APP_CORS_ALLOWED_ORIGIN_PATTERNS` | 桌面客户端通过 `file://` 加载前端,必须允许跨域 | | Spring 基础 | `SPRING_TASK_SCHEDULING_POOL_SIZE`、`SPRING_HTTP_CODECS_MAX_IN_MEMORY_SIZE` | 控制调度线程池、HTTP 大小限制 | | PostgreSQL | `SPRING_DATASOURCE_DYNAMIC_*` | 平台数据库连接,必须安装 pgvector 扩展 | | Redis | `SPRING_DATA_REDIS_HOST`、`SPRING_DATA_REDIS_PORT` | sa-token 登录态硬依赖 | | Elasticsearch | `SPRING_ELASTICSEARCH_*` | 全文检索,可选鉴权用户名密码 | | 本地存储 | `STORAGE_LOCAL_ROOT_PATH`、`STORAGE_LOCAL_BASE_URL` | 相对 JVM 工作目录 | | Neo4j | `NEO4J_URI`、`NEO4J_USERNAME`、`NEO4J_PASSWORD` | 可选图谱能力 | | RAG | `ETL_RAG_ENABLED`、`ETL_RAG_TOP_K`、`ETL_RAG_SCORE_THRESHOLD` | Agent 表结构语义检索 | | AI 研判 | `ZSJZ_INSIGHT_*` | 会话数、保留天数、消息分页等 | | DuckDB | `ZSJZ_DUCKDB_*` | 案件库并发、内存比例、回收间隔 | | 文件 AI | `ZSJZ_FILE_AI_*` | 非表格文件 AI 识别并发与超时 | | 向量模型 | `ZSJZ_EMBEDDING_*` | 本地 ONNX 模型开关、路径、维度、批大小 | | AI 清洗 | `ZSJZ_AI_CLEAN_*` | 模板向量索引、重建策略、召回阈值 | | 对话附件 | `ZSJZ_CHAT_ATTACHMENT_*` | 文档大小、分块、RAG 召回 | | 登录安全 | `ZSJZ_AUTH_IN_USE_WINDOW_MINUTES` | “账号正在使用”判定窗口 | ### 环境变量与配置文件的关系 ```mermaid flowchart TD EnvFile["deploy/env.sh
环境变量定义"] --> Shell["shell 或 systemd 注入"] Shell --> SpringBoot["Spring Boot 应用启动"] SpringBoot --> Yaml["application.yaml
${ENV_NAME:默认值}"] Yaml --> EffectiveConfig["最终生效配置"] ExternalDb["PostgreSQL / Redis / Elasticsearch / Neo4j"] --> EffectiveConfig ``` **图示来源** - [deploy/env.sh:1-30](file://deploy/env.sh#L1-L30) - [ai-server/src/main/resources/application.yaml:1-40](file://ai-server/src/main/resources/application.yaml#L1-L40) ### 执行权限与安全要求 脚本注释明确要求: - 文件包含数据库口令,部署时应设置为 `chmod 600`,即只有所有者可读。 - 在 Linux 上执行脚本前,需要确认具有执行权限。 - 生产部署时必须逐项确认标注为“按环境修改”的配置项。 - `SPRING_PROFILES_ACTIVE` 默认不启用生产 profile,可通过取消注释改为 `pro`。 **章节来源** - [deploy/env.sh:1-172](file://deploy/env.sh#L1-L172) - [ai-server/src/main/resources/application.yaml:1-60](file://ai-server/src/main/resources/application.yaml#L1-L60) ## 典型工作流 ### 拉取代码 推荐使用 Git 克隆仓库,并在 `dev_4` 分支上工作。克隆后进入仓库根目录执行后续命令。 ### 安装后端依赖 后端使用 Maven 管理依赖。推荐在仓库根目录执行: ```bash mvn clean package -DskipTests ``` 这会构建 `ai-gateway` 和 `ai-server`。如果只想构建其中一个模块,可以使用 `-pl` 参数。 ### 安装前端依赖 前端位于 `ai-electron/frontend`,必须使用 pnpm: ```bash cd ai-electron/frontend pnpm bootstrap ``` 或直接执行: ```bash pnpm install ``` ### 启动 Gateway Gateway 默认端口 `8080`,需要先启动 ai-server,再启动 Gateway,因为 Gateway 会转发到 ai-server。 ```bash mvn -pl ai-server spring-boot:run ``` 然后另一个终端启动 Gateway: ```bash mvn -pl ai-gateway spring-boot:run ``` 或者先生成 Jar 后运行: ```bash mvn -pl ai-server,ai-gateway package -DskipTests java -jar ai-server/target/ai-server.jar java -jar ai-gateway/target/ai-gateway.jar ``` ### 启动 ai-server ai-server 默认端口 `8980`,上下文路径 `/js/a`。生产或 Linux 部署时建议先加载环境变量: ```bash set -a source deploy/env.sh set +a java -jar ai-server/target/ai-server.jar ``` 如果不需要自定义环境变量,可以直接运行 Jar 文件。 ### 启动 Electron 客户端 Electron 客户端有两种开发模式: #### 全栈开发模式 ```bash cd ai-electron pnpm dev ``` 这会根据 ElectronEgg 框架启动前后端联合开发流程。 #### 仅前端开发模式 ```bash cd ai-electron/frontend pnpm dev ``` #### 仅 Electron 开发模式 ```bash cd ai-electron pnpm dev-electron ``` #### 仅前端构建 ```bash cd ai-electron/frontend pnpm build ``` ### 打包 Windows 安装包 ```bash cd ai-electron pnpm build-w ``` 产物位于 `ai-electron/out/qingjian-ai-client-win-200.0.0-x64.exe`。 ### 打包 macOS 安装包 Apple Silicon: ```bash cd ai-electron pnpm build-m ``` Intel Mac: ```bash cd ai-electron pnpm build-m-x86 ``` ### 打包 Linux 安装包 ```bash cd ai-electron pnpm build-l ``` 产物通常是 deb 包,位于 `ai-electron/out`。 ### 完整工作流示意 ```mermaid flowchart TD Clone["git clone 仓库"] --> Backend["Maven 构建后端"] Clone --> Frontend["pnpm bootstrap"] Backend --> RunServer["启动 ai-server"] Backend --> RunGateway["启动 ai-gateway"] Frontend --> RunClient["启动 Electron 客户端"] RunServer --> Test["浏览器或客户端访问 /js/a"] RunGateway --> Test RunClient --> Test Test --> Package["pnpm build-* 打包安装包"] ``` [本节为工作流说明,不直接分析具体代码片段] ## 常见错误与解决方法 ### 端口冲突 | 现象 | 原因 | 解决方法 | |---|---|---| | ai-server 启动失败 | 端口 `8980` 已被占用 | 关闭占用端口的进程,或修改 `ai-server` 的 `server.port` | | ai-gateway 启动失败 | 端口 `8080` 已被占用 | 关闭占用端口的进程,或修改 `ai-gateway` 的 `server.port` | | 前端预览端口冲突 | 预览命令使用 `3100` | 修改前端预览端口或关闭占用 `3100` 的进程 | | Electron 无法加载页面 | 前端未构建或路径不正确 | 先执行 `pnpm build`,确保 `public/dist/index.html` 存在 | Gateway 默认端口为 `8080`,ai-server 默认端口为 `8980`,上下文路径为 `/js/a`。如果修改了 ai-server 的端口,也要相应调整 Gateway 中 ai-server 节点配置的 `base-url`。 ### 依赖缺失 | 现象 | 原因 | 解决方法 | |---|---|---| | Maven 构建失败 | JDK 版本不是 `25` | 安装并切换 JDK 25 | | Maven 无法下载依赖 | 网络或镜像问题 | 配置国内 Maven 镜像或代理 | | 前端依赖安装失败 | 使用了 npm/yarn 而非 pnpm | 使用 `pnpm bootstrap` 或 `pnpm install` | | 前端报 Node 版本错误 | Node.js 版本不满足 `>=20.19 \|\| >=22.12` | 升级 Node.js | | Electron 原生模块构建失败 | 缺少 Python、C++ 构建工具或平台 SDK | 安装 Electron 原生模块所需构建工具链 | | SQLite 原生模块构建失败 | 平台变化后 native 模块失效 | 执行 `pnpm re-sqlite` | ### 数据库与中间件连接失败 | 现象 | 原因 | 解决方法 | |---|---|---| | ai-server 启动时报数据库连接错误 | PostgreSQL 地址、端口、用户名、密码不正确 | 修改 `deploy/env.sh` 中 PostgreSQL 相关变量 | | Redis 连接失败 | Redis 不可用或地址端口不一致 | 检查 `SPRING_DATA_REDIS_HOST` 与 `SPRING_DATA_REDIS_PORT` | | Elasticsearch 连接失败 | ES 未启动或 URI 配置错误 | 检查 `SPRING_ELASTICSEARCH_URIS` | | Neo4j 连接失败 | Neo4j 未启动或认证失败 | 检查 `NEO4J_URI`、`NEO4J_USERNAME`、`NEO4J_PASSWORD` | | 向量能力不可用 | 本地模型目录缺失或 pgvector 未安装 | 检查 `ZSJZ_EMBEDDING_MODEL_PATH` 与 PG 是否安装 pgvector | ### 跨域导致前端无法访问后端 Electron 通过 `file://` 加载前端,后端独立部署时会触发浏览器跨域限制。如果后端关闭跨域,Electron 客户端将无法获取数据。 解决方法: - 保持 `APP_CORS_ENABLED=true`。 - 将 `APP_CORS_ALLOWED_ORIGIN_PATTERNS` 设置为允许的来源,例如固定域名或 `*`。 - 不要同时在 Gateway 和业务后端重复开启跨域,否则可能出现重复响应头。 ### 环境变量未生效 | 现象 | 原因 | 解决方法 | |---|---|---| | 修改 `deploy/env.sh` 后无效 | 没有重新 `source` 或重启服务 | 重新加载脚本并重启 ai-server | | systemd 服务仍用旧配置 | systemd 缓存或没有重载 | 执行 `systemctl daemon-reload` 并重启服务 | | 某些配置仍未覆盖 | 该配置不使用环境变量占位符 | 检查对应 YAML 配置是否确实使用 `${ENV_NAME:默认值}` | | profile 未切换 | 未设置 `SPRING_PROFILES_ACTIVE` | 取消注释或设置 `SPRING_PROFILES_ACTIVE=pro` | ### 打包失败 | 现象 | 原因 | 解决方法 | |---|---|---| | `pnpm build` 找不到前端资源 | 前端未构建 | 先执行 `pnpm build-frontend` 或 `pnpm build` | | Windows 安装包构建失败 | 缺少 NSIS、签名文件或图标 | 检查 `build/icons/icon.ico` 和相关打包依赖 | | macOS 打包失败 | 缺少 macOS 签名工具或证书 | 安装 Xcode 命令行工具并配置签名 | | Linux 打包失败 | 缺少 deb 打包依赖 | 安装 `dpkg`、`fakeroot` 等 Linux 打包工具 | | 输出目录为空 | 构建中途失败 | 查看 `ai-electron/out/builder-debug.yml` 和控制台日志 | ### 客户端卸载后仍有残留 如果 `cmd/uninstall.sh` 执行后仍存在残留目录,可能是: - 客户端进程仍在后台运行。 - 文件被其他程序占用。 - 当前用户没有删除权限。 解决方法: 1. 先手动结束 `qingjian-client` 进程。 2. 以管理员或 root 权限运行卸载脚本。 3. 再次执行脚本,确认输出中没有“权限问题或文件被占用”的警告。 **章节来源** - [ai-gateway/src/main/resources/application.yaml:1-20](file://ai-gateway/src/main/resources/application.yaml#L1-L20) - [ai-server/src/main/resources/application.yaml:1-20](file://ai-server/src/main/resources/application.yaml#L1-L20) - [deploy/env.sh:1-172](file://deploy/env.sh#L1-L172) - [ai-electron/frontend/package.json:1-30](file://ai-electron/frontend/package.json#L1-L30) - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) - [ai-electron/cmd/builder.json:1-57](file://ai-electron/cmd/builder.json#L1-L57) - [cmd/uninstall.sh:1-53](file://cmd/uninstall.sh#L1-L53) ## 结论 这个项目的构建体系可以概括为: - **后端**:使用 Maven 父工程统一管理 `ai-gateway` 与 `ai-server`,分别负责网关转发和业务逻辑。 - **前端**:使用 pnpm + Vite + Vue 3,提供 `dev`、`build`、`preview` 等命令。 - **Electron 客户端**:通过 `ee-bin` 和 `electron-builder` 完成前端构建、Electron 构建、加密和各平台打包。 - **环境变量**:通过 `deploy/env.sh` 集中覆盖 ai-server 的运行时配置,适合 Linux 手动启动和 systemd 部署。 - **卸载**:Linux/macOS 使用 shell 脚本清理进程和数据目录,Windows 使用 bat 脚本。 典型开发顺序是:先安装 Maven 和 JDK 25,再安装 pnpm 和 Node.js,随后依次启动 ai-server、Gateway 和 Electron 客户端;打包时分别使用 Maven 构建后端,使用 pnpm 命令构建各平台安装包。遇到问题时,应优先检查端口占用、JDK 与 Node 版本、外部中间件连通性、环境变量加载方式以及 Electron 构建日志。