前端构建说明

目录职责

目录	说明
`frontend-vue/`	前端源码（Vue 3 + Vite）
`src/main/resources/static/v2/`	前端构建产物，由 Vite 生成，不要手工修改

⚠️ static/v2/ 是自动生成目录，请勿直接手工编辑其中的文件，
应始终通过构建前端源码来更新。

本地开发

启动前端开发服务器（热重载，代理到后端 :8080）：

cd frontend-vue
npm install   # 首次或依赖变更时
npm run dev   # 启动 Vite dev server，访问 http://localhost:5173/v2/

Maven 打包（含前端构建）

项目使用 frontend-maven-plugin 绑定在 prepare-package 阶段，
只有 mvn package（及后续阶段）才会触发前端构建：

命令	前端构建
`mvn compile`	❌ 不触发
`mvn test`	❌ 不触发
`mvn package`	✅ 自动执行 `install-node（v20 LTS） → npm ci → npm run build`

# 完整打包（含前端构建，首次默认自动下载 Node）
mvn clean package -DskipTests

# 如果 nodejs.org 下载极慢或报错（如 Premature end of Content-Length），可指定国内镜像源：
mvn clean package -DskipTests -Dnode.download.root=https://npmmirror.com/mirrors/node/

# 跳过前端构建（前提：static/v2/ 中已存有最新的构建产物）
mvn clean package -DskipTests -Dskip.frontend.build=true

离线与缓存方案 (CI / 弱网环境)

由于默认全量打包依赖外网 Node.js 下载，当本地/CI环境无法直接访问外网或网络极其不稳定时，建议采用以下优化方案：

手动预缓存 Node.js 包（最稳妥的离线打包方案） 您可以直接手动下载对应平台的 Node 压缩包，并放置到本地 Maven 缓存目录中。以 Linux x64 平台为例：
- 下载对应版本的 Node 包：node-v20.11.0-linux-x64.tar.gz
- 保存到本地 Maven 仓库缓存路径下： ~/.m2/repository/com/github/eirslett/node/20.11.0/node-20.11.0-linux-x64.tar.gz
- 再次运行 mvn package 时，插件检测到该本地缓存文件存在，将直接读取该文件进行解压，不会发起任何外网下载请求。
切换镜像源 如果网络通畅但仅访问官方 nodejs.org 受限，可以使用 -Dnode.download.root 参数切换至其他镜像源：
- 阿里云镜像：-Dnode.download.root=https://npmmirror.com/mirrors/node/
- 华为云镜像：-Dnode.download.root=https://mirrors.huaweicloud.com/nodejs/
跳过前端构建 如果仅变更后端 Java 代码，不需要重新编译前端，可直接通过 -Dskip.frontend.build=true 跳过前端： mvn clean package -DskipTests -Dskip.frontend.build=true

Docker 构建（推荐生产方式）

make up

Dockerfile 使用多阶段构建：

Stage 1（frontend-builder）：node:22-alpine 执行 npm ci && npm run build
Stage 2（builder）：Maven 将前端产物 COPY 进来并打包 jar
Stage 3（runner）：最小 JRE 运行

首次配置 API Key 说明

服务启动后，如果未配置 API Key，/api/settings 返回：

{
  "apiKeyConfigured": false,
  "apiKeySource": "none"
}

这是正常状态，请前往设置页配置 DeepSeek API Key 或 OpenAI 兼容 API Key。

也可通过环境变量配置 DeepSeek API Key：

export DEEPSEEK_API_KEY=sk-xxxxxxxx

3.5 KiB Raw Blame History Unescape Escape