# 构建与部署

## 前置条件

- **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)