chore: 初始化文档站仓库

2026-09-21 13:38:20 +08:00
commit a4ae7ac979
58 changed files with 4622 additions and 0 deletions
@@ -0,0 +1,96 @@
+# 构建与部署
+
+## 前置条件
+
+- **JDK 21**（Temurin 21 LTS）
+- **Node.js**（构建前端时需要）
+
+## 开发模式
+
+前后端分离，便于调试：
+
+```bash
+# 后端（默认 8080）
+cd finance-app
+set JAVA_HOME=D:\venv\jdk-21
+gradlew.bat bootRun
+
+# 前端（默认 5173，接口代理到 8080）
+cd finance-app/frontend
+npm run dev
+```
+
+- 后端地址：http://localhost:8080
+- 后端 API 文档：http://localhost:8080/doc.html
+- 前端地址：http://localhost:5173，接口经 Vite 代理到后端 8080
+
+## 打包可执行 jar（前后端一体化）
+
+`bootJar` 会先执行前端 `npm run build`，再把 `frontend/dist` 复制到 jar 内的 `BOOT-INF/classes/static/`，单文件同时提供页面与接口。
+
+```bash
+gradle bootJar
+# 或使用宿主机脚本
+./package.sh
+```
+
+输出：`build/libs/finance-app-0.0.1-SNAPSHOT.jar`
+
+启动（默认 8080，可另指定端口）：
+
+```bash
+java -jar build/libs/finance-app-0.0.1-SNAPSHOT.jar --server.port=18081
+```
+
+访问对应端口即可；刷新 `/dashboard` 等子路由由后端 `SpaErrorController` 回退到 `index.html`。
+
+::: tip 提示
+jar 内置的前端为生产构建，访问时与后端同源，无需额外的反向代理。
+:::
+
+构建任务链（`build.gradle`）：
+
+- `npmInstall`：安装前端依赖（`node_modules` 存在且 `package.json` 未变化时跳过）
+- `frontendBuild`：执行 `npm run build`
+- `bootJar`：依赖 `frontendBuild`，并将前端产物打入静态资源目录
+
+## Docker 部署
+
+`run/docker-compose.yml` 定义前后端两个服务，纯复用本地镜像、不构建新镜像：
+
+| 服务 | 镜像 | 端口 | 说明 |
+|---|---|---|---|
+| backend | `eclipse-temurin:21-jre` | 18080→8080 | 挂载 `run/backend/*.jar`，持久化 `config/`、`data/`、`logs/` |
+| front | `nginx:alpine` | 15180→80 | 挂载 `run/front/dist` 与 Nginx 配置 |
+
+环境变量 `DB_URL` / `DB_USERNAME` / `DB_PASSWORD` 仅作为首次启动的默认配置来源，也可在界面中完成数据库配置。
+
+## 桌面 GUI 启动器
+
+`launcher` 包提供系统托盘 + 控制窗口的桌面启动器（启动/停止服务、打开浏览器、查看日志），通过 `bootGuiJar` 打包：
+
+```bash
+gradle bootGuiJar
+```
+
+- 入口类：`cn.rosercode.finance.launcher.LauncherMain`
+- 依赖 JavaFX 与 dorkbox SystemTray，仅加入带 GUI 的 jar（`guiRuntime` 配置），普通 jar 不含这些依赖
+- 平台默认 Windows（可通过 `-PjavafxPlatform=linux` 本地验证）
+- JavaFX 与 JNA 原生库需 `requiresUnpack` 从嵌套 jar 解压
+
+> 注意：该启动器为规划中的能力，具体实现以当前源码为准。
+
+## 分发形态
+
+| 形态 | 说明 |
+|---|---|
+| jar | `bootJar`，需 JDK 21 运行 |
+| jar（带 GUI） | `bootGuiJar`，内含桌面启动器 |
+| 可执行文件（控制台 / GUI） | 规划中，计划采用 `jpackage`（JDK 自带，各平台分别构建） |
+| Docker 镜像 | 通过 `run/docker-compose.yml` 编排 |
+
+## 相关文档
+
+- [项目结构](/dev/project-structure)
+- [开发环境与规范](/dev/development)
+- [快速开始（使用文档）](/guide/getting-started)