refactor: optimize security baseline, task logging, frontend maven packaging, and redirect root page to v2

2026-06-10 16:06:10 +08:00
parent 1b182c2930
commit 42214b33e3
10 changed files with 307 additions and 20 deletions
@@ -0,0 +1,100 @@
+# 前端构建说明
+
+## 目录职责
+
+| 目录 | 说明 |
+|------|------|
+| `frontend-vue/` | 前端源码（Vue 3 + Vite） |
+| `src/main/resources/static/v2/` | **前端构建产物**，由 Vite 生成，不要手工修改 |
+
+> ⚠️ `static/v2/` 是自动生成目录，请勿直接手工编辑其中的文件，  
+> 应始终通过构建前端源码来更新。
+
+---
+
+## 本地开发
+
+启动前端开发服务器（热重载，代理到后端 :8080）：
+
+```bash
+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` |
+```bash
+# 完整打包（含前端构建，首次默认自动下载 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环境无法直接访问外网或网络极其不稳定时，建议采用以下优化方案：
+
+1. **手动预缓存 Node.js 包（最稳妥的离线打包方案）**
+   您可以直接手动下载对应平台的 Node 压缩包，并放置到本地 Maven 缓存目录中。以 Linux x64 平台为例：
+   - 下载对应版本的 Node 包：[node-v20.11.0-linux-x64.tar.gz](https://nodejs.org/dist/v20.11.0/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` 时，插件检测到该本地缓存文件存在，将**直接读取该文件进行解压**，不会发起任何外网下载请求。
+
+2. **切换镜像源**
+   如果网络通畅但仅访问官方 nodejs.org 受限，可以使用 `-Dnode.download.root` 参数切换至其他镜像源：
+   - 阿里云镜像：`-Dnode.download.root=https://npmmirror.com/mirrors/node/`
+   - 华为云镜像：`-Dnode.download.root=https://mirrors.huaweicloud.com/nodejs/`
+
+3. **跳过前端构建**
+   如果仅变更后端 Java 代码，不需要重新编译前端，可直接通过 `-Dskip.frontend.build=true` 跳过前端：
+   `mvn clean package -DskipTests -Dskip.frontend.build=true`
+
+---
+
+## Docker 构建（推荐生产方式）
+
+```bash
+make up
+```
+
+Dockerfile 使用多阶段构建：
+1. Stage 1（`frontend-builder`）：`node:22-alpine` 执行 `npm ci && npm run build`
+2. Stage 2（`builder`）：Maven 将前端产物 COPY 进来并打包 jar
+3. Stage 3（`runner`）：最小 JRE 运行
+
+---
+
+## 首次配置 API Key 说明
+
+服务启动后，如果未配置 API Key，`/api/settings` 返回：
+
+```json
+{
+  "apiKeyConfigured": false,
+  "apiKeySource": "none"
+}
+```
+
+这是**正常状态**，请前往设置页配置 DeepSeek API Key 或 OpenAI 兼容 API Key。
+
+也可通过环境变量配置 DeepSeek API Key：
+
+```bash
+export DEEPSEEK_API_KEY=sk-xxxxxxxx
+```