322 lines
18 KiB
Markdown
322 lines
18 KiB
Markdown
# Kaidi 财务项目基础系统
|
||
|
||
本仓库当前处于 R1 开发执行阶段，需求基线见下方唯一总方案。
|
||
|
||
唯一需求、开发、测试和交付基线：
|
||
|
||
- [财务项目基础系统开发交付总方案](docs/财务系统开发交付总方案.md)
|
||
|
||
## 本地开发
|
||
|
||
本地开发数据库由环境变量显式指定，启动 Java 服务：
|
||
|
||
```bash
|
||
cd backend
|
||
SPRING_PROFILES_ACTIVE=local \
|
||
DB_URL='jdbc:mysql://127.0.0.1:3307/kaidi_finance?useUnicode=true&characterEncoding=utf8&connectionTimeZone=UTC&serverTimezone=UTC' \
|
||
DB_USERNAME=kaidi DB_PASSWORD=kaidi_local_2026 \
|
||
./mvnw spring-boot:run
|
||
```
|
||
|
||
前端使用官方 TDesign Vue Next Starter，来源记录见 [`frontend/UPSTREAM.md`](frontend/UPSTREAM.md)。
|
||
|
||
```bash
|
||
cd frontend
|
||
HUSKY=0 npm ci
|
||
npm run dev:linux -- --host 0.0.0.0 --port 3002
|
||
```
|
||
|
||
访问：<http://localhost:3002/>
|
||
|
||
本地 `local` profile 会创建 `admin`、`project`、`finance`、`archive`、`demo` 演示账号，初始密码均为
|
||
`LocalOnly@123`；该固定密码只用于本机开发，生产安装会生成随机管理员密码。
|
||
|
||
正式构建：
|
||
|
||
```bash
|
||
cd frontend
|
||
npm run build
|
||
```
|
||
|
||
后端运行后更新唯一 OpenAPI 机器制品：
|
||
|
||
```bash
|
||
./scripts/export-openapi.sh http://127.0.0.1:18080
|
||
```
|
||
|
||
## R1 Preview 部署方式
|
||
|
||
代码仓库和 Release 已公开，提供两种互斥方式：
|
||
|
||
1. **systemd 一键安装（推荐）**：程序独占 `/opt/kaidi` 和 `kaidi-finance.service`，不创建宝塔 Java 项目。
|
||
2. **宝塔手动部署**：下载压缩包后解压并运行本地初始化脚本，再创建 Spring Boot 项目。
|
||
|
||
两种方式不能同时运行在同一个端口。程序不会安装 MySQL，数据库只支持运维人员预先准备的外部 MySQL 8.4.x，
|
||
PostgreSQL 18 兼容工作继续冻结。
|
||
|
||
### 生产部署契约（先看这里）
|
||
|
||
- **生产机不执行 `git clone`、`git pull` 或远程脚本拼接。** 源码仓库是
|
||
`https://git.awaioi.com/ERP-Team/kaidi.git`，生产安装和后台更新使用同一仓库生成的公开 Gitea Release。
|
||
- 安装器先读取 Gitea Release API，再下载 `release-manifest.json`、签名、公钥和压缩包，校验固定公钥指纹、RSA 签名、版本、文件名和 SHA-256；校验失败不会安装。
|
||
- 后台“获取版本”只查询 Release；“下载”才下载并校验；“立即更新并重启”才备份数据库、切换 `current` 并重启服务。更新器下载的是 Release 制品，不是 Git 工作树。
|
||
- MySQL 是**已有数据库**，应用只通过向导写入的 `DB_URL`、`DB_USERNAME`、`DB_PASSWORD` 连接它；安装器不安装 MySQL、不创建数据库、不修改数据库服务。填写 `127.0.0.1` 表示 MySQL 与 Java 应用在同一台服务器，端口以实际监听端口为准，不默认假设 `3307`。
|
||
- `KAIDI_APP_PORT` 只决定 Java 回环监听端口，默认 `18080`；反向代理必须指向安装器输出的 `PROXY_TARGET`。安装器不会替你修改 Nginx 或宝塔站点配置。
|
||
- 发布归档使用无顶层目录的 `tar.gz`，只包含 `app.jar`、`public/`、`ops/`、`VERSION`；打包阶段禁用 macOS 扩展属性并拒绝开发数据库回退值。
|
||
|
||
### 32 位 Linux 支持边界
|
||
|
||
当前支持的是 **i386/i486/i586/i686 + glibc + systemd + 可运行的 32 位 Java 17**。安装器会校验用户空间位数、Java 架构、glibc 和 `/lib/ld-linux.so.2`（兼容 `/lib32`、`/lib/i386-linux-gnu` 路径）；musl 或缺少 32 位加载器的系统会在安装前明确失败，不会安装后才出现无法启动。
|
||
|
||
32 位服务器应使用首次访问 `/setup` 的向导输入外部 MySQL 8.4 连接信息，这条路径不需要在服务器安装 MySQL 客户端。在线更新前仍需准备与数据库兼容的 `mysqldump`；如果 32 位系统无法提供该客户端，应先关闭在线更新或从独立备份机执行数据库备份，不要在更新过程中临时安装数据库。
|
||
|
||
### systemd 一键安装（推荐）
|
||
|
||
先在宝塔面板停止并删除当前错误的 Java 项目，再执行：
|
||
|
||
```bash
|
||
curl -fsSL https://git.awaioi.com/ERP-Team/kaidi/releases/download/v1.0.0-preview.31/install.sh | sudo env KAIDI_APP_PORT=18080 bash
|
||
```
|
||
|
||
该命令只安装程序运行所需的 systemd 单元，自动创建 `kaidi` 用户并检测现有 Java 17（包括
|
||
`/www/server/java/*/bin/java`）；没有可用 Java 时才下载匹配架构的运行时。它不会安装 MySQL，也不会要求宝塔面板提供
|
||
`kaidi` 用户。安装完成后查看 `/root/kaidi-first-login.txt`，通过反向代理域名进入 `/setup`。
|
||
|
||
### 彻底清理旧安装
|
||
|
||
重新安装前先在宝塔面板停止并删除名为 `kaidi-finance` 的 Java 项目，避免面板守护进程重新拉起旧 Java。
|
||
随后执行一键清理：
|
||
|
||
```bash
|
||
curl -fsSL https://git.awaioi.com/ERP-Team/kaidi/releases/download/v1.0.0-preview.31/purge.sh \
|
||
-o /tmp/kaidi-purge.sh \
|
||
&& printf '%s %s\n' 44dbf10a9540aa9235bb8aff2dec603f1febbd45072cd8c4f6c40b25a6127801 /tmp/kaidi-purge.sh \
|
||
| sha256sum -c - \
|
||
&& sudo env KAIDI_PURGE_CONFIRM=DELETE_LOCAL_KAIDI_INSTALLATION bash /tmp/kaidi-purge.sh \
|
||
&& rm -f /tmp/kaidi-purge.sh
|
||
```
|
||
|
||
清理脚本会先停止 systemd 和遗留 Kaidi 进程，将旧配置、文件存储、安装码以及已有数据库备份归档到
|
||
`/root/kaidi-reinstall-backups/`，再删除 `/opt/kaidi`、`/www/wwwroot/kaidi`、`/etc/kaidi`、
|
||
`/var/lib/kaidi`、`/var/lib/kaidi-update`、`/var/log/kaidi` 和三个 systemd 单元。恢复包权限固定为
|
||
`0600`，确认新安装及数据无误后再由 root 删除。脚本不删除外部 MySQL、系统 Java、Nginx 或宝塔站点配置；
|
||
新安装必须连接一个新的空 MySQL 数据库，旧数据库保留用于回滚。
|
||
|
||
### Preview.31 直链与宝塔手动部署
|
||
|
||
本版不使用一键安装脚本。发布物是一个不带顶层目录的压缩包，下载后直接解压到版本目录，再由宝塔面板创建
|
||
Spring Boot 项目。数据库、JDK、Nginx 和宝塔本身都由运维人员准备；程序不会自动安装 MySQL 或任何第三方服务。
|
||
|
||
下载地址：
|
||
|
||
`https://git.awaioi.com/ERP-Team/kaidi/releases/download/v1.0.0-preview.31/kaidi-finance-1.0.0-preview.31.tar.gz`
|
||
|
||
校验文件：`https://git.awaioi.com/ERP-Team/kaidi/releases/download/v1.0.0-preview.31/SHA256SUMS`
|
||
|
||
服务器要求：Linux + systemd、Java 17（宝塔项目选择 JDK 17）、可访问外部 MySQL 8.4.x；32 位 Linux 需要宿主机
|
||
已经提供可运行的 32 位 Java 17。程序只连接已有数据库，不安装数据库客户端或数据库服务。初始化只需要
|
||
`bash`、`openssl`、`sha256sum` 和基础 Linux 工具；选择 systemd 在线更新前，另行准备 `curl`、`jq`、`flock`、`gzip`、`runuser`
|
||
以及与外部 MySQL 兼容的 `mysqldump`。程序不会替你安装这些依赖。
|
||
|
||
#### 1. 下载、校验、解压
|
||
|
||
以下命令只做文件下载和解压，不执行远程脚本。`VERSION` 必须替换成发布版本；归档内的 `app.jar`、`public/`、`ops/`
|
||
必须直接位于 `RELEASE_ROOT`，不能再嵌套一层目录。
|
||
|
||
```bash
|
||
VERSION=1.0.0-preview.31
|
||
APP_ROOT=/www/wwwroot/kaidi
|
||
RELEASE_ROOT="$APP_ROOT/releases/$VERSION"
|
||
sudo install -d -m 0755 "$RELEASE_ROOT"
|
||
wget -O "/tmp/kaidi-finance-$VERSION.tar.gz" \
|
||
"https://git.awaioi.com/ERP-Team/kaidi/releases/download/v$VERSION/kaidi-finance-$VERSION.tar.gz"
|
||
wget -O /tmp/kaidi-SHA256SUMS \
|
||
"https://git.awaioi.com/ERP-Team/kaidi/releases/download/v$VERSION/SHA256SUMS"
|
||
(cd /tmp && grep " kaidi-finance-$VERSION.tar.gz$" kaidi-SHA256SUMS | sha256sum -c -)
|
||
sudo tar -xzf "/tmp/kaidi-finance-$VERSION.tar.gz" -C "$RELEASE_ROOT"
|
||
```
|
||
|
||
如果服务器没有 `wget`，可使用浏览器下载后上传同一文件；`curl -fL URL -o FILE` 也只用于下载压缩包，不能替代初始化脚本。
|
||
|
||
#### 2. 执行本地初始化
|
||
|
||
初始化脚本来自已下载的归档，并在本机以 root 运行。它创建 `kaidi` 启动用户、受保护配置和一次性安装码；不会下载
|
||
Java、安装 MySQL 或修改反向代理。宝塔手动模式不会开放在线更新按钮。端口参数可改为 `1024-65535` 中的空闲端口，默认 `18080`。
|
||
|
||
```bash
|
||
sudo "$RELEASE_ROOT/ops/baota-init.sh" 18080
|
||
sudo cat /root/kaidi-first-login.txt
|
||
```
|
||
|
||
初始化失败会回滚本次写入的配置、unit 和 `current` 链接，可以直接修正原因后重试；已经存在正式安装时不要重复执行，先按“彻底清理旧安装”流程处理。
|
||
|
||
#### 3. 宝塔 Spring Boot 项目字段
|
||
|
||
在宝塔面板创建项目，类型选择 **Spring Boot**，不要选择 Tomcat。填写如下：
|
||
|
||
| 字段 | 填写值 |
|
||
| --- | --- |
|
||
| 项目路径 | `/www/wwwroot/kaidi/current` |
|
||
| 项目名称 | `kaidi-finance` |
|
||
| 项目 JDK | `JDK 17` |
|
||
| 项目启动命令 | `/www/wwwroot/kaidi/current/ops/baota-start.sh` |
|
||
| 启动用户 | `kaidi` |
|
||
| 项目端口 | `18080`（与初始化参数一致） |
|
||
| 绑定域名 | 业务域名，例如 `fi.awaioi.com` |
|
||
| 后端路由 | `/` |
|
||
| 前端资源 | 留空，Spring Boot 直接提供 `public/` |
|
||
| 进程守护 | 开启 |
|
||
| 项目意外重启 | 勾选 |
|
||
|
||
**环境变量全部留空，不要创建 DB_URL、DB_USERNAME、DB_PASSWORD 或 FIELD_ENCRYPTION_KEY。**
|
||
`ops/baota.env.example` 仅是说明文件，不能把其中的占位值粘贴到面板。启动器先读取 `/etc/kaidi/kaidi.env`，向导完成后
|
||
再读取 `/var/lib/kaidi/setup/application.env`；宝塔只有填写了非空覆盖值时才会覆盖受保护配置。数据库密码不会出现在
|
||
Java 启动命令或 `ps` 参数中。
|
||
|
||
#### 4. 首次向导与反向代理
|
||
|
||
启动宝塔项目后，访问 `https://业务域名/setup`，输入 `/root/kaidi-first-login.txt` 中的一次性安装码，填写外部 MySQL
|
||
连接信息和系统管理员账号密码。迁移完成后应用会退出一次，宝塔守护进程会自动拉起正式模式；再次访问域名根路径即可登录。
|
||
首次配置数据库密码必须使用 HTTPS；没有域名时通过 SSH 隧道访问回环端口：
|
||
|
||
```bash
|
||
ssh -L 18080:127.0.0.1:18080 root@SERVER_IP
|
||
```
|
||
|
||
本机浏览器打开 `http://127.0.0.1:18080/setup`。反向代理只需把整个 `/` 转发到 `http://127.0.0.1:18080`，并保留以下请求头：
|
||
|
||
```nginx
|
||
location / {
|
||
proxy_pass http://127.0.0.1:18080;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
proxy_read_timeout 120s;
|
||
client_max_body_size 500m;
|
||
}
|
||
```
|
||
|
||
HTTPS 启用后，在 `/etc/kaidi/kaidi.env` 将 `SESSION_COOKIE_SECURE` 设为 `true`，再从宝塔面板重启项目。健康检查：
|
||
|
||
```bash
|
||
curl -fsS http://127.0.0.1:18080/actuator/health
|
||
curl -fsS http://127.0.0.1:18080/ | head
|
||
```
|
||
|
||
#### 5. 手动部署模式的更新边界
|
||
|
||
宝塔手动部署不启用 Preview 的在线更新契约。需要升级时，先停止宝塔项目，下载并校验新的 Release 压缩包，
|
||
解压到新的 `releases/<VERSION>`，再由宝塔项目切换路径并启动；确认健康检查通过后再删除旧版本。
|
||
不要在宝塔项目仍运行时点击“系统治理 → 系统更新”，也不要让宝塔守护和 `kaidi-finance.service` 同时管理同一端口。
|
||
需要后台点击“获取版本 → 下载 → 立即更新并重启”的稳定流程时，使用上一节的 systemd 一键安装方式。
|
||
|
||
手动升级前请先由运维人员完成外部 MySQL 备份；程序不会安装 MySQL 或客户端，也不会修改反向代理配置。
|
||
|
||
后续版本仍按同样方式直接下载并解压到新的 `releases/<VERSION>`，保留可回滚的旧目录。
|
||
|
||
### Linux 32 位
|
||
|
||
压缩包本身不绑定 CPU 架构，关键是宿主机提供 glibc、systemd 和可运行的 32 位 Java 17。32 位主机不能在本机运行 64 位 JDK，也不应尝试在本机安装
|
||
MySQL 8.4；提前准备外部 MySQL，完成上述向导即可。选择 systemd 在线更新前，还必须确认宿主机能执行与数据库版本兼容的
|
||
`mysqldump`；宝塔手动模式只做手动制品替换和人工数据库备份。
|
||
|
||
### 停用并移除程序
|
||
|
||
以下命令移除应用程序和服务，但保留 `/var/lib/kaidi`、`/var/lib/kaidi-update`、`/etc/kaidi` 以及数据库，
|
||
便于审计、备份或重新安装。确认数据备份前不要删除这些保留目录或外部 MySQL 数据。
|
||
反向代理由运维人员独立管理，停用程序不会修改其配置。
|
||
|
||
```bash
|
||
sudo systemctl disable --now kaidi-update.path kaidi-update.service kaidi-finance.service
|
||
sudo rm -f /etc/systemd/system/kaidi-finance.service /etc/systemd/system/kaidi-update.service /etc/systemd/system/kaidi-update.path
|
||
sudo systemctl daemon-reload
|
||
sudo rm -rf /opt/kaidi
|
||
```
|
||
|
||
## Release 与在线更新
|
||
|
||
首次建立发布仓库时生成一次签名密钥：
|
||
|
||
```bash
|
||
./scripts/generate-release-key.sh release-signing-private.pem
|
||
base64 < release-signing-private.pem | tr -d '\n'
|
||
```
|
||
|
||
将私钥的 Base64 内容保存为 Gitea Actions Secret `RELEASE_SIGNING_KEY_B64`，并将命令输出的公钥 SHA-256
|
||
保存为 Gitea Actions Variable `KAIDI_RELEASE_PUBLIC_KEY_SHA256`。Gitea 发布 Token 只用于该工作流创建
|
||
Release；生产服务器从公共 Release 下载，不保存 Token。私钥不得提交到 Git。`.gitea/workflows/release.yml` 要求
|
||
act_runner 提供 `ubuntu-24.04` 标签，并在 tag 发布时执行后端、前端、OpenAPI、Shell、安装/更新和浏览器门禁。
|
||
|
||
工作流先建立不可见草稿，再显式上传并核对 10 个资产的名称和大小，最后才发布为 `/releases/latest`。Gitea 的
|
||
`latest` 会排除 `prerelease=true`，因此即使 tag 名含 `preview`，发布记录的 `prerelease` 也固定为 `false`；
|
||
Preview 属性由 SemVer 版本名表达。之后推送 tag 即会构建、测试、签名并发布：
|
||
|
||
```bash
|
||
git tag v1.0.0-preview.31
|
||
git push origin v1.0.0-preview.31
|
||
```
|
||
|
||
在线更新仍使用独立的 TDesign 页面：系统管理员进入“系统治理 → 系统更新”。更新源由 root 在
|
||
`/etc/kaidi/update.env` 固定为公共 Gitea Latest Release API；页面和普通 API 不能提交 URL、Token、脚本或命令。
|
||
**Preview 的稳定在线更新契约只支持 systemd 一键安装模式**：更新器由
|
||
`kaidi-update.service` 执行，直接停止、切换并重启 `kaidi-finance.service`，不依赖宝塔面板的意外重启。
|
||
宝塔手动部署仅用于手动启动和反向代理；其面板进程管理与 systemd 更新器不是同一套生命周期，暂不作为在线更新的稳定路径。
|
||
|
||
更新流程固定为：
|
||
|
||
1. 点击“获取版本”，只实时请求 Gitea Latest Release 版本、发布时间和发布说明，不排队下载。
|
||
2. 发现新版本后显示“立即更新”；管理员点击后才排队 `DOWNLOAD`。更新器下载 manifest、签名和应用包，执行 RSA、SHA-256、版本、
|
||
文件名和压缩包路径校验，通过后缓存到 `/var/lib/kaidi-update/cache/<version>`，业务服务继续运行。
|
||
3. 页面实时轮询并依次显示下载已排队、下载中、校验中和 `READY/下载完成`；只有下载完成后才显示“立即更新并重启”。
|
||
4. 管理员点击“立即更新并重启”，更新器预先调用宿主机已有的 `mysqldump`，备份权限为 `0600`，默认保留最近 5 份；程序不会安装 MySQL 或客户端。
|
||
5. 更新器安装并保护新版本目录，原子切换 `/opt/kaidi/current`（宝塔手动部署才使用
|
||
`/www/wwwroot/kaidi/current`），停止并重启 systemd 管理的应用服务。
|
||
6. 健康端点、静态首页和运行版本全部通过后，页面等待 10 秒自动刷新；期间断线或命令响应丢失由前端状态重同步恢复。任一检查失败则切回上一应用版本，
|
||
保留数据库备份和事务证据供人工处理。
|
||
|
||
忙碌期间检查、下载和安装按钮保持禁用，防止重复请求；10 秒只用于成功后的页面刷新，不延迟服务端切换。数据库迁移必须至少保持一个版本向后兼容。
|
||
查看状态和日志：
|
||
|
||
```bash
|
||
sudo systemctl status kaidi-update.path kaidi-update.service
|
||
sudo journalctl -u kaidi-update.service -n 100 --no-pager
|
||
cat /var/lib/kaidi-update/status.json
|
||
```
|
||
|
||
进程被中断时，`kaidi-update.path` 会根据 `processing/request.json` 或 `transactions/active` 自动恢复一次。
|
||
如果 `status.json` 显示 `RECOVERY_REQUIRED`，失败请求会归档到 `/var/lib/kaidi-update/failed`，事务证据会移到
|
||
`transactions/recovery-required*` 并退出自动触发路径，新下载和安装请求也会被拒绝。修复日志所示的磁盘、权限或
|
||
旧版本健康问题后，将唯一一份待恢复事务移回 `active`，再明确执行一次：
|
||
|
||
```bash
|
||
sudo mv /var/lib/kaidi-update/transactions/recovery-required /var/lib/kaidi-update/transactions/active
|
||
sudo systemctl reset-failed kaidi-update.service kaidi-update.path
|
||
sudo systemctl start kaidi-update.service
|
||
sudo journalctl -u kaidi-update.service -n 100 --no-pager
|
||
cat /var/lib/kaidi-update/status.json
|
||
```
|
||
|
||
如果目录带时间后缀，先通过 `ls -1d /var/lib/kaidi-update/transactions/recovery-required*` 确认唯一目录，再替换上面
|
||
命令中的源路径。只有状态恢复为 `SUCCEEDED`、`CURRENT` 或确定性的终态 `FAILED`，且 `transactions/active` 已处理
|
||
完成后，才算本次恢复结束。后台会保留真实失败状态，不会把待恢复请求误显示成普通排队。
|
||
|
||
## 手工生成 Release
|
||
|
||
```bash
|
||
KAIDI_RELEASE_SIGNING_KEY=/secure/release-signing-private.pem \
|
||
KAIDI_TRUSTED_RELEASE_PUBLIC_KEY_SHA256=807c6aec1dc3f7ce494db16aa9d763c66f292033c38f328afd0390d2715a8cd9 \
|
||
./scripts/package-release.sh 1.0.0-preview.31
|
||
KAIDI_TRUSTED_RELEASE_PUBLIC_KEY_SHA256=807c6aec1dc3f7ce494db16aa9d763c66f292033c38f328afd0390d2715a8cd9 \
|
||
./scripts/verify-release.sh dist/release
|
||
```
|
||
|
||
输出位于 `dist/release/`，包含安装脚本、彻底清理脚本、签名清单、公钥、SHA-256 清单、前后端 CycloneDX
|
||
SBOM、首次安装指纹文件和完整应用压缩包。
|
||
打包脚本会把 Maven `revision` 与 npm 包版本临时绑定到 Release SemVer，构建结束后恢复工作区源文件；
|
||
JAR、两个 SBOM、签名清单或 tag 的版本只要有一项不一致，发布即失败。
|
||
签名清单同时绑定应用包、两份 SBOM、安装器、公钥、bootstrap 指纹和 Git 源码修订；本地脏工作区会明确记录
|
||
`source.dirty=true`，tag 工作流只接受干净 checkout 并记录 `source.dirty=false`。
|
||
发布命令同时输出 Release 公钥和归档校验值；将压缩包 SHA-256 写入直链部署说明后再发布。
|