rosercode
b979c6e498
- 站点标题、首页与文档正文品牌名由「收支管理系统」改为「汇账 Ledgerly」 - package.json 包名改为 ledgerly-docs - 维护脚本环境变量由 FINANCE_* 改为 LEDGERLY_*，测试库路径与示例同步 - 项目结构、构建部署、开发环境等文档中的目录名与 jar 名改为 ledgerly - 保留在线体验域名与 OSS 截图前缀不变
97 lines
3.0 KiB
Markdown
97 lines
3.0 KiB
Markdown
# 构建与部署
|
||
|
||
## 前置条件
|
||
|
||
- **JDK 21**（Temurin 21 LTS）
|
||
- **Node.js**（构建前端时需要）
|
||
|
||
## 开发模式
|
||
|
||
前后端分离，便于调试：
|
||
|
||
```bash
|
||
# 后端（默认 8080）
|
||
cd ledgerly
|
||
set JAVA_HOME=D:\venv\jdk-21
|
||
gradlew.bat bootRun
|
||
|
||
# 前端（默认 5173，接口代理到 8080）
|
||
cd ledgerly/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/ledgerly-0.0.1-SNAPSHOT.jar`
|
||
|
||
启动（默认 8080，可另指定端口）：
|
||
|
||
```bash
|
||
java -jar build/libs/ledgerly-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)
|