docs: 同步汇账最新功能，新增智能查数、账单关系等文档
对照 ledgerly 自文档上次更新以来的全部改动，补充新功能文档、修正品牌与版本残留，并新增下载与安装页；配图已重新截取并上传 OSS，本地截图目录不纳入版本管理。 变更内容： - 新增「智能查数」「账单关系」两个使用文档页，并登记侧边栏与总览 - 设置页扩充为八个面板（账号安全、数据库实时进度、外观、导航等）并改为即时保存 - 收支记录补充关系列、批量操作、AI 搜索浮窗、可配置分页与「账单详情」弹窗 - 统计面板补充饼图/渠道图下钻与筛选双向联动；规则管理补充批量删除 - AI 能力补充智能查数与关系命名；新增下载与安装页 - 开发文档同步：AI 13 类调用、数据模型 24 张表、API、前端偏好、构建部署 - 统一「汇账 Ledgerly」品牌与「设置/日志」菜单文案，版本号对齐 0.1 - 截图脚本新增账单详情等场景并更新登记 说明： - download.md 的 OSS 下载链接保持待发布产物回填，暂不调整 - 已通过 npm run docs:build 与 npm run typecheck:scripts
This commit is contained in:
+96
-40
@@ -1,9 +1,12 @@
|
||||
# 构建与部署
|
||||
|
||||
本章介绍「汇账」的构建方式、分发形态与生产部署流程。
|
||||
|
||||
## 前置条件
|
||||
|
||||
- **JDK 21**（Temurin 21 LTS）
|
||||
- **JDK 21**（Temurin 21 LTS，含 `jpackage`）
|
||||
- **Node.js**（构建前端时需要）
|
||||
- 依赖仓库：本地 Nexus（Maven）与 verdaccio（npm）；构建时经 `-I nexus-init.gradle` 注入 Maven 私服地址
|
||||
|
||||
## 开发模式
|
||||
|
||||
@@ -12,85 +15,138 @@
|
||||
```bash
|
||||
# 后端（默认 8080）
|
||||
cd ledgerly
|
||||
set JAVA_HOME=D:\venv\jdk-21
|
||||
gradlew.bat bootRun
|
||||
./gradlew bootRun # Windows: 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
|
||||
- 后端地址：`http://localhost:8080`，接口文档 `http://localhost:8080/doc.html`
|
||||
- 前端地址：`http://localhost:5173`，`/api` 经 Vite 代理到后端 8080
|
||||
|
||||
## 打包可执行 jar（前后端一体化）
|
||||
## 构建可执行 jar（前后端一体化）
|
||||
|
||||
`bootJar` 会先执行前端 `npm run build`，再把 `frontend/dist` 复制到 jar 内的 `BOOT-INF/classes/static/`，单文件同时提供页面与接口。
|
||||
|
||||
```bash
|
||||
gradle bootJar
|
||||
# 或使用宿主机脚本
|
||||
# 普通 jar（无 GUI，不含 JavaFX）
|
||||
./gradlew -I nexus-init.gradle bootJar
|
||||
|
||||
# 带 GUI 启动器的 jar
|
||||
./gradlew -I nexus-init.gradle bootGuiJar
|
||||
|
||||
# 或使用宿主机脚本（一次产出两者）
|
||||
./package.sh
|
||||
```
|
||||
|
||||
输出：`build/libs/ledgerly-0.0.1-SNAPSHOT.jar`
|
||||
产物文件名携带目标 JDK 版本：
|
||||
|
||||
| 任务 | 产物 | 说明 |
|
||||
|---|---|---|
|
||||
| `bootJar` | `build/libs/ledgerly-0.1-jdk21.jar` | 普通服务 jar |
|
||||
| `bootGuiJar` | `build/libs/ledgerly-0.1-jdk21-gui.jar` | 入口为桌面启动器 |
|
||||
|
||||
启动（默认 8080，可另指定端口）：
|
||||
|
||||
```bash
|
||||
java -jar build/libs/ledgerly-0.0.1-SNAPSHOT.jar --server.port=18081
|
||||
java -jar build/libs/ledgerly-0.1-jdk21.jar --server.port=18081
|
||||
```
|
||||
|
||||
访问对应端口即可；刷新 `/dashboard` 等子路由由后端 `SpaErrorController` 回退到 `index.html`。
|
||||
构建任务链（`build.gradle`）：`npmInstall` → `frontendBuild` → `bootJar`。
|
||||
|
||||
::: tip 提示
|
||||
jar 内置的前端为生产构建，访问时与后端同源，无需额外的反向代理。
|
||||
:::
|
||||
|
||||
构建任务链（`build.gradle`）：
|
||||
为减小可执行 jar 体积，普通 jar 与 GUI jar 均做了裁剪：AI 调用改用 Spring `RestClient` 直连 OpenAI 兼容接口（不再打包 OpenAI Java SDK）；接口文档仅保留 `/v3/api-docs`（JSON），Knife4j 的 `doc.html` UI 依赖为 `developmentOnly`，不进生产 jar；普通 jar 通过 `exclude` 排除桌面启动器包，保持无 JavaFX 依赖。
|
||||
|
||||
- `npmInstall`：安装前端依赖（`node_modules` 存在且 `package.json` 未变化时跳过）
|
||||
- `frontendBuild`：执行 `npm run build`
|
||||
- `bootJar`：依赖 `frontendBuild`，并将前端产物打入静态资源目录
|
||||
运行时首次配置或切换数据库时，「测试连接」与「保存并应用」会通过 SSE **实时推送执行进度**（连接测试、建表、结构迁移、数据源切换等）。
|
||||
|
||||
## Docker 部署
|
||||
## 构建免安装应用（jpackage app-image）
|
||||
|
||||
`run/docker-compose.yml` 定义前后端两个服务，纯复用本地镜像、不构建新镜像：
|
||||
`jpackageAppImage` 聚合任务一次生成两个 app-image，自带精简运行时，双击即用；**仅能为当前操作系统生成**（Windows 上生成 Windows 产物，Linux 上生成 Linux 产物）。
|
||||
|
||||
| 服务 | 镜像 | 端口 | 说明 |
|
||||
```bash
|
||||
./gradlew -I nexus-init.gradle jpackageAppImage
|
||||
# 也可单独执行 jpackageServerAppImage / jpackageGuiAppImage
|
||||
```
|
||||
|
||||
| 任务 | 应用名 | 源 jar | 入口 |
|
||||
|---|---|---|---|
|
||||
| backend | `eclipse-temurin:21-jre` | 18080→8080 | 挂载 `run/backend/*.jar`，持久化 `config/`、`data/`、`logs/` |
|
||||
| front | `nginx:alpine` | 15180→80 | 挂载 `run/front/dist` 与 Nginx 配置 |
|
||||
| `jpackageServerAppImage` | `LedgerlyServer` | `bootJar` | `bin/LedgerlyServer`（Windows 为 `LedgerlyServer.exe`，附带控制台） |
|
||||
| `jpackageGuiAppImage` | `Ledgerly` | `bootGuiJar` | `bin/Ledgerly`（Windows 为 `Ledgerly.exe`） |
|
||||
|
||||
环境变量 `DB_URL` / `DB_USERNAME` / `DB_PASSWORD` 仅作为首次启动的默认配置来源，也可在界面中完成数据库配置。
|
||||
产物位于 `build/jpackage/LedgerlyServer/` 与 `build/jpackage/Ledgerly/`。
|
||||
|
||||
图标不随源码分发：打包时 `downloadAppIcon` 从 `src/main/resources/launcher/icon.url` 下载源图，再由 `tools/IconGen.java` 生成平台图标（`ico` / `icns` / `png`）；可用 `-PsourceIcon=<png>` 指定本地源图。
|
||||
|
||||
## 桌面 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 解压
|
||||
|
||||
> 注意：该启动器为规划中的能力，具体实现以当前源码为准。
|
||||
`cn.rosercode.ledgerly.launcher` 提供系统托盘 + 控制窗口的桌面启动器（进程内启停服务、设置端口、打开浏览器、实时查看日志、单实例运行），仅打入带 GUI 的 jar，普通 jar 不含 JavaFX 依赖。
|
||||
|
||||
## 分发形态
|
||||
|
||||
| 形态 | 说明 |
|
||||
|---|---|
|
||||
| jar | `bootJar`，需 JDK 21 运行 |
|
||||
| jar（带 GUI） | `bootGuiJar`，内含桌面启动器 |
|
||||
| 可执行文件（控制台 / GUI） | 规划中，计划采用 `jpackage`（JDK 自带，各平台分别构建） |
|
||||
| Docker 镜像 | 通过 `run/docker-compose.yml` 编排 |
|
||||
| 形态 | 构建方式 | 说明 |
|
||||
|---|---|---|
|
||||
| 普通 jar | `bootJar` | 需 JDK 21 运行，跨平台 |
|
||||
| 带 GUI 启动器 jar | `bootGuiJar` | 内含桌面启动器，跨平台（打包含 JavaFX 全平台原生库） |
|
||||
| Windows 免安装包 | `jpackageAppImage` | 在 Windows 上构建，zip 分发 |
|
||||
| Linux 免安装包 | `jpackageAppImage` | 在 Linux 上构建，tar.gz 分发 |
|
||||
|
||||
## 发布产物与下载地址
|
||||
|
||||
发布产物上传至阿里云 OSS（桶 `adccrac`，对象键前缀 `ledgerly/release/<版本>/`），通过 10 年有效的长期签名 URL 对外提供下载；每个文件同时提供 `.sha256` 校验文件与汇总清单 `SHA256SUMS`。
|
||||
|
||||
当前工程版本为 `0.1`；最新下载地址见使用文档的[下载与安装](/guide/download)（该页链接指向已上传的发布产物）。
|
||||
|
||||
上传方式：
|
||||
|
||||
- Linux 产物（jar 与 Linux app-image 包）：工作区根 `oss-release-upload.py`，需在带 `oss2` 的虚拟环境执行（如 `20260807_131528/oss-venv`），上传后输出长期签名 URL。
|
||||
- Windows 产物（Windows app-image 包）：在 Windows 主机上用 Node 脚本（`ali-oss` + STS）直接上传，不回传本地。
|
||||
|
||||
## 生产部署（云服务器）
|
||||
|
||||
服务部署在云服务器 `101.35.20.223` 的 `/opt/ledgerly` 目录，由 Docker Compose 编排：
|
||||
|
||||
| 容器 | 镜像 | 端口 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `ledgerly` | `eclipse-temurin:21-jre` | `127.0.0.1:15180 → 8080` | 挂载 `app/ledgerly-0.1.jar`、`config/`、`data/`，JVM `-Xmx512m` |
|
||||
| `ledgerly-docs` | `nginx:1.27` | `127.0.0.1:15181 → 80` | 挂载 `docs-dist/` 与 `docs/nginx.conf` |
|
||||
|
||||
云上 `nginx` 容器反代这两个回环端口并终止 HTTPS，证书由 `certbot` 容器负责续期：
|
||||
|
||||
- 服务：[https://finance.rosercode.cn](https://finance.rosercode.cn)
|
||||
- 文档：[https://docs.finance.rosercode.cn](https://docs.finance.rosercode.cn)
|
||||
|
||||
### 发布流程
|
||||
|
||||
服务（构建 → 复制 → 重启）：
|
||||
|
||||
```bash
|
||||
# 1) 本地构建 jar（见上）
|
||||
# 2) 复制到云端部署目录，目标文件名须与 compose 挂载一致
|
||||
scp -i ~/.ssh/id_ed25519_www.rosercode.cn \
|
||||
build/libs/ledgerly-0.1-jdk21.jar \
|
||||
root@101.35.20.223:/opt/ledgerly/app/ledgerly-0.1.jar
|
||||
# 3) 重启容器
|
||||
ssh -i ~/.ssh/id_ed25519_www.rosercode.cn root@101.35.20.223 \
|
||||
'cd /opt/ledgerly && docker compose restart'
|
||||
```
|
||||
|
||||
文档站（构建 → 覆盖 `docs-dist`，目录挂载即时生效）：
|
||||
|
||||
```bash
|
||||
cd doc-site && npm run docs:build
|
||||
scp -i ~/.ssh/id_ed25519_www.rosercode.cn -r .vitepress/dist/* \
|
||||
root@101.35.20.223:/opt/ledgerly/docs-dist/
|
||||
```
|
||||
|
||||
> 云服务器不能直连 DockerHub，新镜像需本地 `docker save | gzip` → `scp` → 云端 `docker load` 导入。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [项目结构](/dev/project-structure)
|
||||
- [开发环境与规范](/dev/development)
|
||||
- [下载与安装（使用文档）](/guide/download)
|
||||
- [快速开始（使用文档）](/guide/getting-started)
|
||||
|
||||
Reference in New Issue
Block a user