ERP-Team/kaidi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 35 Wiki Activity

feat: support Baota manual deployment and managed updates
Release / release (push) Canceled after 0s
Details

Browse Source
This commit is contained in:
Qiufeng
2026-08-18 03:08:28 +08:00
parent fa4517c263
commit cfdc0fed44
13 changed files with 765 additions and 269 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+105 -197
View File
@@ -41,20 +41,11 @@ npm run build
./scripts/export-openapi.sh http://127.0.0.1:18080
```
## R1 Preview 一键安装
## R1 Preview 手动部署
代码仓库和 Release 已公开，Linux 服务器不需要 Gitea Token。安装器读取
`https://git.awaioi.com/api/v1/repos/ERP-Team/kaidi/releases/latest`，生产机不执行 `git pull` 或现场编译。
安装脚本内置固定的发布公钥指纹，下载的应用包、清单、SBOM 和更新脚本仍须通过 RSA 签名与 SHA-256 校验。
Gitea API 只用于确认 Release tag 和资产名称；下载地址由受信 API 域名、仓库路径和 tag 重新构造，不采用
Gitea 响应中可能错误指向内网地址的 `browser_download_url`。
本版只支持由运维人员预先准备的外部 MySQL 8.4.x；安装器不会安装 MySQL、创建数据库容器或修改现有
PostgreSQL 18。PostgreSQL 兼容开发已冻结，不属于本次 Preview 发布范围。
执行命令的机器需预装 `bash`、`sudo`、`curl`、`mktemp` 和 `sha256sum`，并能访问目标 Gitea；`jq` 和 Java
由安装器补齐；Java 17 优先使用服务器已有运行时，没有合适版本时才从官方 Azul 下载。数据库服务和数据库客户端均不会被安装。默认首次安装向导直接使用 JDBC 连接浏览器中填写的
外部数据库，不需要服务器安装 MySQL CLI。应用固定安装到 `/opt/kaidi`、`/var/lib/kaidi`、
`/var/lib/kaidi-update` 和 `/etc/kaidi`。安装器不安装、不启动也不修改 Nginx、Caddy、宝塔或其他反向代理。
代码仓库和 Release 已公开。本版交付物是签名的应用压缩包，部署方式固定为“下载、校验、解压、运行本地初始化脚本、
在宝塔创建 Spring Boot 项目”；不再使用 `curl | bash` 一键安装。程序不会安装 MySQL、JDK、Nginx 或其他第三方服务，
也不会修改宝塔和反向代理配置。数据库只支持运维人员预先准备的外部 MySQL 8.4.x，PostgreSQL 18 兼容工作继续冻结。
### 彻底清理旧安装
@@ -76,201 +67,125 @@ curl -fsSL https://git.awaioi.com/ERP-Team/kaidi/releases/download/v1.0.0-previe
`0600`，确认新安装及数据无误后再由 root 删除。脚本不删除外部 MySQL、系统 Java、Nginx 或宝塔站点配置；
新安装必须连接一个新的空 MySQL 数据库，旧数据库保留用于回滚。
### 直接 curl 安装
### Preview.25 直链与宝塔手动部署
本版不使用一键安装脚本。发布物是一个不带顶层目录的压缩包，下载后直接解压到版本目录，再由宝塔面板创建
Spring Boot 项目。数据库、JDK、Nginx 和宝塔本身都由运维人员准备；程序不会自动安装 MySQL 或任何第三方服务。
下载地址：
`https://git.awaioi.com/ERP-Team/kaidi/releases/download/v1.0.0-preview.25/kaidi-finance-1.0.0-preview.25.tar.gz`
校验文件：`https://git.awaioi.com/ERP-Team/kaidi/releases/download/v1.0.0-preview.25/SHA256SUMS`
服务器要求：Linux + systemd、Java 17（宝塔项目选择 JDK 17）、可访问外部 MySQL 8.4.x；32 位 Linux 需要宿主机
已经提供可运行的 32 位 Java 17。程序只连接已有数据库，不安装数据库客户端或数据库服务。初始化只需要
`bash`、`openssl`、`sha256sum` 和基础 Linux 工具；启用在线更新前，另行准备 `curl`、`jq`、`flock`、`gzip`、`runuser`
以及与外部 MySQL 兼容的 `mysqldump`。程序不会替你安装这些依赖。
#### 1. 下载、校验、解压
以下命令只做文件下载和解压，不执行远程脚本。`VERSION` 必须替换成发布版本；归档内的 `app.jar`、`public/`、`ops/`
必须直接位于 `RELEASE_ROOT`，不能再嵌套一层目录。
```bash
curl -fsSL https://git.awaioi.com/ERP-Team/kaidi/releases/download/v1.0.0-preview.24/install.sh | sudo bash
VERSION=1.0.0-preview.25
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"
```
这条命令会提示填写 Java 应用端口，直接回车使用 `18080`；随后安装最新签名 Release，并默认进入 `/setup`
安装向导。Java 默认只监听 `127.0.0.1:所选端口`，前端页面、API 和健康检查均由同一端口提供。无人值守安装可直接指定：
如果服务器没有 `wget`，可使用浏览器下载后上传同一文件；`curl -fL URL -o FILE` 也只用于下载压缩包，不能替代初始化脚本。
#### 2. 执行本地初始化
初始化脚本来自已下载的归档，并在本机以 root 运行。它创建 `kaidi` 启动用户、受保护配置、在线更新监听器和一次性
安装码；不会下载 Java、安装 MySQL 或修改反向代理。端口参数可改为 `1024-65535` 中的空闲端口，默认 `18080`。
```bash
curl -fsSL https://git.awaioi.com/ERP-Team/kaidi/releases/download/v1.0.0-preview.24/install.sh \
| sudo env KAIDI_APP_PORT=19090 bash
sudo "$RELEASE_ROOT/ops/baota-init.sh" 18080
sudo cat /root/kaidi-first-login.txt
```
端口必须在 `1024-65535` 范围且未被其他程序监听；安装器会在安装前检查冲突。只有明确需要让其他主机直连 Java
时才设置 `KAIDI_SERVER_ADDRESS=0.0.0.0`，通常应保持默认回环绑定并由本机反向代理访问。需要在执行前独立校验安装脚本时使用：
初始化失败会回滚本次写入的配置、unit 和 `current` 链接，可以直接修正原因后重试；已经存在正式安装时不要重复执行，先按“彻底清理旧安装”流程处理。
```bash
curl -fsSL https://git.awaioi.com/ERP-Team/kaidi/releases/download/v1.0.0-preview.24/install.sh -o /tmp/kaidi-install.sh
printf '%s %s\n' 6256b05025aa314d4c02e7c0f5d2ca530f28ec5d10f833504b34c09ada6e02a5 /tmp/kaidi-install.sh | sha256sum -c -
sudo bash /tmp/kaidi-install.sh
rm -f /tmp/kaidi-install.sh
```
#### 3. 宝塔 Spring Boot 项目字段
### 从固定 Git tag 拉取后安装
在宝塔面板创建项目，类型选择 **Spring Boot**，不要选择 Tomcat。填写如下：
需要保留源码快照时，可以拉取与 Release 对应的固定 tag，再运行仓库内包装器。公共仓库不要求凭据，
包装器会在 `sudo` 前校验 `deploy/install.sh` 的固定 SHA-256，再按同一公钥信任链安装最新签名 Release。
| 字段 | 填写值 |
| --- | --- |
| 项目路径 | `/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/` |
| 进程守护 | 开启 |
| 项目意外重启 | 勾选 |
```bash
git clone --branch v1.0.0-preview.24 --depth 1 https://git.awaioi.com/ERP-Team/kaidi.git kaidi-preview
cd kaidi-preview
./deploy/install-from-git.sh
```
**环境变量全部留空，不要创建 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` 参数中。
首次安装使用向导时不要传 `KAIDI_DB_URL`、`KAIDI_DB_USERNAME` 或 `KAIDI_DB_PASSWORD`；这些值在浏览器中填写。
只有已完成安装的修复性重装才从运行时配置读取数据库值，详见下文。
#### 4. 首次向导与反向代理
安装器会完成以下动作：
- 仅在 Linux + systemd 环境执行；首版 32 位支持基线为带 systemd 的 Debian/Ubuntu x86 32 位 Linux。
- 不安装或创建数据库；在 `/setup` 中连接运维人员预先准备的外部 MySQL 8.4.x。
- 识别 `x86_64`、`aarch64`、`armv7` 或 32 位 `i386/i486/i586/i686`；已有 Java 17 直接复用，否则校验 SHA-256 后下载对应的官方 Azul Java 17 JRE。
- 使用安装器内置的 SHA-256 指纹校验 Release 公钥，再用该公钥验证发布清单 RSA 签名。
- 首次安装默认启用 `/setup` 向导，不在命令行保存数据库密码；向导只接受 MySQL 8.4.x，并在提交前验证完整迁移权限。
- 安装签名 Release 到 `/opt/kaidi/releases/<version>`，以 `/opt/kaidi/current` 原子切换当前版本。
- 安装 `kaidi-finance.service`、更新监听服务和健康检查；Java 同时托管 TDesign 前端静态资源及 Vue 路由回退。
- 向导只初始化一个由操作者填写的 `SYSTEM_ADMIN` 管理员，不创建项目、财务、资料或演示账号。
- 安装器把一次性安装码写入仅 root 可读的 `/root/kaidi-first-login.txt`；完成向导后写入锁定标记并切换正式应用。
### 环境变量与密钥安全
首次安装不需要在命令行或宝塔项目中填写数据库环境变量。数据库地址、账号和密码只在 `/setup` 向导中提交，
完成后写入 `/var/lib/kaidi/setup/application.env`；字段加密密钥由安装器生成并写入
`/etc/kaidi/kaidi.env`。两个文件不会把秘密放进 Java 启动参数或 `ps` 输出，并由 Linux 文件权限限制为
root 或专用 `kaidi` 服务账号读取。运行中的 Java 仍必须持有这些值，因此 root 和该服务账号始终属于受信边界。
不要通过公网 HTTP 提交数据库密码。应先为域名配置有效 HTTPS，或通过 SSH 端口转发访问本机回环地址完成向导：
启动宝塔项目后，访问 `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`。向导完成后自动锁定，安装码不能再次使用。
安装完成后先执行 `sudo cat /root/kaidi-first-login.txt`，其中会显示准确的反向代理目标和一次性安装码。配置反向代理后，
通过域名的 `/setup` 完成数据库和管理员配置，再访问域名根路径登录。Preview 使用 HTTP 时安装器默认设置
`SESSION_COOKIE_SECURE=false`；配置 HTTPS 反向代理后，应在 `/etc/kaidi/kaidi.env` 改为
`SESSION_COOKIE_SECURE=true` 并执行 `sudo systemctl restart kaidi-finance`。
以安装端口 `19090` 为例，Nginx 只需代理到 Java，不需要单独托管前端文件：
本机浏览器打开 `http://127.0.0.1:18080/setup`。反向代理只需把整个 `/` 转发到 `http://127.0.0.1:18080`，并保留以下请求头：
```nginx
location / {
proxy_pass http://127.0.0.1:19090;
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_connect_timeout 10s;
proxy_read_timeout 120s;
client_max_body_size 500m;
}
```
宝塔、Caddy 或云网关使用同一个上游地址 `http://127.0.0.1:所选端口`。安装后执行以下命令确认应用和首次登录信息：
```bash
curl -fsS http://127.0.0.1:19090/actuator/health | jq -e '.status == "UP"'
sudo systemctl --no-pager --full status kaidi-finance kaidi-update.path
sudo cat /root/kaidi-first-login.txt
```
### Linux 32 位
应用已按 Java 17 字节码构建，安装器会在 32 位 Linux 下载 `i686` JRE。MySQL 8.4 没有可用于该部署方式的
32 位服务端镜像，因此 32 位主机需要预先连接一台 MySQL 8.4 数据库，之后仍然只执行一个安装命令：
```bash
curl -fsSL https://git.awaioi.com/ERP-Team/kaidi/releases/download/v1.0.0-preview.24/install.sh | sudo bash
```
无论主机架构如何，安装器都不会安装 MySQL、数据库客户端或创建数据库容器。在打开向导前，需要预先创建 `kaidi_finance`，并授予安装账号该库的
完整迁移权限。向导会连接数据库、核验 MySQL 8.4.x 版本，并实际探测建表、改表、索引、外键、存储过程、
临时表及读写权限；专用数据库不是 `utf8mb4/utf8mb4_0900_ai_ci` 时，向导会在迁移前自动统一默认字符集和
排序规则，全部通过后 Flyway 才会建表。
数据库管理员可在 MySQL 8.4 中按实际应用服务器地址执行以下基线 SQL：
```sql
CREATE DATABASE kaidi_finance CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
CREATE USER 'kaidi'@'KAIDI_SERVER_IP' IDENTIFIED BY 'DB_PASSWORD';
GRANT ALL PRIVILEGES ON kaidi_finance.* TO 'kaidi'@'KAIDI_SERVER_IP';
```
### 修复性重装
正常升级统一使用后台“在线更新”。只有安装文件损坏且后台更新不可用时，才在原服务器执行修复性重装；
安装器会优先读取向导完成后生成的 `/var/lib/kaidi/setup/application.env`，再回退到 `/etc/kaidi/kaidi.env`，保留数据库、字段加密密钥、
管理员数据和运维人员新增的环境变量：
```bash
curl -fsSL https://git.awaioi.com/ERP-Team/kaidi/releases/download/v1.0.0-preview.24/install.sh \
| sudo env KAIDI_REINSTALL=true KAIDI_SETUP_WIZARD=false bash
```
没有显式设置 `KAIDI_APP_PORT` 时，修复性重装会沿用 `/etc/kaidi/kaidi.env` 中的原端口。重装失败会恢复原应用链接、Java 运行时、环境文件和 systemd 单元；脚本会明确报告回滚不完整，
不会把恢复失败吞掉。新版本安装器在 `KAIDI_REINSTALL=true` 时默认使用生产修复模式，显式的
`KAIDI_SETUP_WIZARD=false` 仅用于兼容旧版本安装器。
如果安装器已完成但向导尚未提交，可执行下面的命令重新生成一次性安装码；该恢复路径只接受仍处于向导模式且未锁定的安装，正式模式不会被覆盖。
```bash
curl -fsSL https://git.awaioi.com/ERP-Team/kaidi/releases/download/v1.0.0-preview.24/install.sh \
| sudo env KAIDI_REINSTALL=true KAIDI_SETUP_WIZARD=true bash
```
### 宝塔面板手动部署
宝塔使用 **Spring Boot** 项目类型。发布物是包含嵌入式 Tomcat 的可执行 JAR，不使用外置 Tomcat 项目。
先下载并解压签名 Release；项目目录必须指向同时包含 `app.jar`、`VERSION`、`public/` 和 `ops/` 的目录。
推荐采用版本目录加 `current` 软链接：
```bash
VERSION=1.0.0-preview.24
RELEASE_ROOT=/www/wwwroot/kaidi/releases/$VERSION
sudo install -d -o root -g kaidi -m 0750 "$RELEASE_ROOT"
curl -fL "https://git.awaioi.com/ERP-Team/kaidi/releases/download/v$VERSION/kaidi-finance-$VERSION.tar.gz" \
-o "/tmp/kaidi-finance-$VERSION.tar.gz"
sudo tar -xzf "/tmp/kaidi-finance-$VERSION.tar.gz" -C "$RELEASE_ROOT"
sudo chown -R root:kaidi "$RELEASE_ROOT"
sudo find "$RELEASE_ROOT" -type d -exec chmod 0750 {} +
sudo find "$RELEASE_ROOT" -type f -exec chmod 0640 {} +
sudo chmod 0750 "$RELEASE_ROOT/ops/baota-start.sh"
sudo ln -sfn "$RELEASE_ROOT" /www/wwwroot/kaidi/current.next
sudo mv -Tf /www/wwwroot/kaidi/current.next /www/wwwroot/kaidi/current
```
宝塔 Java 项目字段：
| 字段 | 值 |
| --- | --- |
| 项目类型 | Spring Boot |
| 项目路径 | `/www/wwwroot/kaidi/current` |
| 项目名称 | `kaidi-finance` |
| 项目 JDK | JDK 17 |
| 项目启动命令 | `/www/wwwroot/kaidi/current/ops/baota-start.sh` |
| 启动用户 | `kaidi`，禁止使用 root |
| 项目端口 | `18080` |
| 绑定域名 | 实际业务域名，例如 `fi.awaioi.com` |
| 后端路由 | `/` |
| 前端资源 | 留空，由 Spring Boot 提供 `public/` |
| 进程守护 | 开启 |
| 项目意外重启 | 勾选 |
环境变量按 `ops/baota.env.example` 填入宝塔。已完成安装的服务器必须沿用
`/var/lib/kaidi/setup/application.env` 中的 `DB_URL`、`DB_USERNAME`、`DB_PASSWORD`，以及
`/etc/kaidi/kaidi.env` 中的 `FIELD_ENCRYPTION_KEY`；不要生成新的字段加密密钥。HTTP Preview 使用
`SESSION_COOKIE_SECURE=false`，切换到 HTTPS 后改为 `true`。宝塔模式固定设置
`FINANCE_UPDATE_ENABLED=false`，版本更新通过上传新目录、切换 `current`、重启项目完成。
启用宝塔守护前停用原 systemd 进程，避免两个进程管理器反复争用端口或互相重启：
```bash
sudo systemctl disable --now kaidi-update.path kaidi-finance.service
sudo systemctl stop kaidi-update.service
```
启动后在服务器验证 Java 上游，再配置域名反向代理：
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
systemctl is-enabled kaidi-update.path
```
#### 5. 后台在线更新
初始化脚本已启用 `kaidi-update.path`，后台“系统治理 → 系统更新”流程保持不变：点击“获取更新”下载并验签，确认后点击“立即重启”。
root 更新器原子切换 `/www/wwwroot/kaidi/current`，向当前 Java 进程发送停止信号；宝塔的意外重启守护随后按新 `current` 链接拉起 Java，
健康检查通过后页面等待 10 秒并自动刷新。更新器不会安装或启动 `kaidi-finance.service`，也不会修改 Nginx。
更新前请在服务器预装与外部 MySQL 兼容的 `mysqldump`，更新器只生成权限为 `0600` 的备份，不会自动安装 MySQL。迁移失败时恢复旧应用版本并保留数据库备份和事务证据，遵循至少一个版本向后兼容的迁移规则。
后续版本仍按同样方式直接下载并解压到新的 `releases/<VERSION>`；不要手工删除 `current`，在线更新负责原子切换和回滚。
### Linux 32 位
压缩包本身不绑定 CPU 架构，关键是宝塔项目选用可运行的 32 位 Java 17。32 位主机不能在本机运行 64 位 JDK，也不应尝试在本机安装
MySQL 8.4；提前准备外部 MySQL，完成上述手动解压、初始化和向导即可。
### 停用并移除程序
以下命令移除应用程序和服务，但保留 `/var/lib/kaidi`、`/var/lib/kaidi-update`、`/etc/kaidi` 以及数据库，
@@ -303,42 +218,36 @@ act_runner 提供 `ubuntu-24.04` 标签，并在 tag 发布时执行后端、前
Preview 属性由 SemVer 版本名表达。之后推送 tag 即会构建、测试、签名并发布：
```bash
git tag v1.0.0-preview.24
git push origin v1.0.0-preview.24
git tag v1.0.0-preview.25
git push origin v1.0.0-preview.25
```
在线更新使用独立的 TDesign 页面：隔离的系统管理员进入“系统治理 → 系统更新”。权限与配置页只管理用户、角色、数据范围、表单模板和参数版本，不配置系统名称或域名。
更新源由 root 在 `/etc/kaidi/update.env` 固定为公共 Gitea Latest Release API；页面和普通 API 不能提交
URL、Token、脚本或命令。更新流程固定为：
在线更新仍使用独立的 TDesign 页面：系统管理员进入“系统治理 → 系统更新”。更新源由 root 在
`/etc/kaidi/update.env` 固定为公共 Gitea Latest Release API；页面和普通 API 不能提交 URL、Token、脚本或命令。
宝塔模式下，root 更新器只负责下载、验签、切换 `current` 和停止旧 Java，**不创建或重启
`kaidi-finance.service`**；宝塔项目的“项目意外重启”负责按新链接拉起 Java。
1. 点击“获取更新”，后端先读取 Release 元数据，再自动排队 `DOWNLOAD`；root 更新器从 Gitea 下载 manifest、签名和应用包，执行 RSA、
SHA-256、版本、文件名和压缩包路径校验后缓存到 `/var/lib/kaidi-update/cache/<version>`。业务服务不停机。
3. 页面显示 `READY/等待重启` 后才出现“立即重启”；管理员点击后提交安装。未缓存或版本不一致
的包不能进入安装。
4. 安装请求持久领取到 `/var/lib/kaidi-update/processing`；进程或主机中断后由 systemd 恢复未完成事务。
5. root 更新器重新验签和验哈希，确认 `mysqldump` 成功并生成权限为 `0600` 的备份，默认保留最近 5 份。安装器不安装
`mysqldump`；启用在线更新前，运维人员须自行在应用服务器预装与外部 MySQL 兼容的 `mysqldump`。
6. 校验更新脚本和 systemd 单元后，在旧 Java 仍运行时原子切换版本链接，再由 systemd 执行一次 `restart`，不修改反向代理。
7. 同时检查 Java 健康端点和 Java 托管的静态首页。全部通过后页面显示 10 秒倒计时并自动
刷新；刷新或短暂断线发生在安装中时，页面会恢复 3 秒轮询。任一检查失败则恢复并验证上一版本。
更新流程固定为：
忙碌期间检查、下载和安装按钮保持禁用，防止重复请求；这就是更新执行冷却。10 秒只用于成功后的页面刷新，
不会延迟服务端切换。失败请求会被归档且不会由 systemd 自动重试，避免同一事务反复停止业务服务。
1. 点击“获取更新”，后端排队 `DOWNLOAD`；更新器下载 manifest、签名和应用包，执行 RSA、SHA-256、版本、文件名和压缩包路径校验，
通过后缓存到 `/var/lib/kaidi-update/cache/<version>`，业务服务继续运行。
2. 页面显示 `READY/等待重启` 后才出现“立即重启”；未缓存或版本不一致的包不能进入安装。
3. 管理员点击“立即重启”，更新器预先调用宿主机已有的 `mysqldump`，备份权限为 `0600`，默认保留最近 5 份；程序不会安装 MySQL 或客户端。
4. 更新器安装并保护新版本目录，原子切换 `/www/wwwroot/kaidi/current`，校验旧 Java 的受控 PID 后发送停止信号；宝塔守护自动启动新版本。
5. 健康端点、静态首页和运行版本全部通过后，页面等待 10 秒自动刷新；期间断线由前端轮询恢复。任一检查失败则切回上一应用版本，
保留数据库备份和事务证据供人工处理。
安装器会把公共 API 地址写入 root-only 的 `/etc/kaidi/kaidi.env` 与 `/etc/kaidi/update.env`，两者权限均为
`0600`：前者供 Java 后端“检查更新”读取，后者供 root 更新器下载资产。默认 Token 为空；如改接私有镜像，
可由运维人员在这两个文件中配置独立只读 Token，Token 不写入页面、状态 JSON、审计参数或更新日志。
数据库迁移必须保持至少一个版本的向后兼容。查看状态和日志：
忙碌期间检查、下载和安装按钮保持禁用，防止重复请求；10 秒只用于成功后的页面刷新，不延迟服务端切换。数据库迁移必须至少保持一个版本向后兼容。
查看状态和日志：
```bash
sudo systemctl status kaidi-finance kaidi-update.path
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
```
如果 `status.json` 显示 `FAILED` 且日志提示回滚未完成，失败请求会归档到
`/var/lib/kaidi-update/failed`，活动事务保留在 `transactions/active`，系统不会自动再次执行。修复日志所示的
`/var/lib/kaidi-update/failed`，活动事务保留在 `transactions/active`，系统不会自动重复安装。修复日志所示的
磁盘、权限或旧版本健康问题后，才明确执行一次：
```bash
@@ -356,7 +265,7 @@ cat /var/lib/kaidi-update/status.json
```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.24
./scripts/package-release.sh 1.0.0-preview.25
KAIDI_TRUSTED_RELEASE_PUBLIC_KEY_SHA256=807c6aec1dc3f7ce494db16aa9d763c66f292033c38f328afd0390d2715a8cd9 \
./scripts/verify-release.sh dist/release
```
@@ -367,5 +276,4 @@ SBOM、首次安装指纹文件和完整应用压缩包。
JAR、两个 SBOM、签名清单或 tag 的版本只要有一项不一致，发布即失败。
签名清单同时绑定应用包、两份 SBOM、安装器、公钥、bootstrap 指纹和 Git 源码修订；本地脏工作区会明确记录
`source.dirty=true`，tag 工作流只接受干净 checkout 并记录 `source.dirty=false`。
发布命令同时在终端输出 `Trusted release public-key SHA-256` 与 `Installer SHA-256`；把这两个值写入
受控部署记录，再替换上述一键安装命令中的占位符。
发布命令同时输出 Release 公钥和归档校验值；将压缩包 SHA-256 写入直链部署说明后再发布。