26 更新产品开发文档

讲解官方热更新机制与发布/回滚流程，对应 UpgradeService 与后台「系统更新」。

版本号约定

定义在 app\common\Version：

常量	当前值	作用
NAME	可得财务	系统名
SLUG	kede-finance	英文标识（检查更新时上报）
EDITION	正式版	发行标注
VERSION	1.0.4	语义化版本
BUILD	191	构建序号，热更新按此递增比对
display()	正式版1.0.4	后台「系统更新 / 系统设置」展示名

判断「是否有更新」只看 BUILD：远端 build > 本地 BUILD 即有更新。发布新版务必递增 BUILD；对外展示用 Version::display()（正式版 + 版本号）。

热更新流程（UpgradeService）

检查 check() → 下载 → 校验(SHA256/验签) → 备份 → 应用(解压覆盖) → 迁移(SQL) → 写日志

1. 检查更新

GET {UPGRADE_SERVER}/api/upgrade/check?slug=&version=&build=
→ { status:200, data:{ version, build, notes, download_url, sha256, signature, force } }

更新服务器地址优先取后台配置 general.upgrade_server，否则 .env 的 APP.UPGRADE_SERVER。

2. 应用更新

UpgradeService::apply() 依次：

1. 下载 download_url 的 zip（120s 超时）；
2. 完整性：强制执行 sha256 比对（hash_equals）；若配置了 RELEASE_PUBLIC_KEY，更新清单必须提供 signature 并通过 RSA 验签；
3. 备份：打包当前 app/、config/、route/、后台 SPA、前台 SPA、登录/注册兼容入口到 runtime/backup/backup_<build>_<时间>.zip；
4. 应用：解压覆盖到项目根；
5. 迁移：执行包内 upgrade/*.sql（文件名升序，支持 {PREFIX} 占位替换表前缀），执行后删除；
6. 记录：写 kd_upgrade_logs，触发钩子 AfterUpgrade。

任一步失败抛 \RuntimeException 并把原因写入日志、原样透出（不静默兜底）。

3. 回滚

UpgradeService::rollback(backupFile) 从 runtime/backup/ 取指定备份解压覆盖，触发 AfterRollback。basename() 防目录穿越。

后台接口

操作	接口
当前版本	GET /admin/upgrade/index
检查更新	POST /admin/upgrade/check
应用更新	POST /admin/upgrade/apply
回滚	POST /admin/upgrade/rollback（参数 backup_file）

需要 upgrade 权限模块。

发布更新包（官方侧）

更新包是一个 zip，解压后覆盖项目根目录，约定包含：

更新包.zip
├── app/                 # 变更的后端代码
├── public/admin/        # 变更的后台 SPA 产物（如有）
├── public/assets/       # 变更的前台 SPA 产物（如有）
├── public/index.html    # 前台入口（如有）
└── upgrade/             # 本次升级的增量 SQL
    └── 0002_xxx.sql     # 用 {PREFIX} 占位表前缀，按文件名升序执行

发布步骤建议：

1. 递增 Version::BUILD（必要时升 VERSION）；
2. 构建前端产物（deploy/package.sh 或单独 npm run build）；
3. 仅打包变更文件 + upgrade/*.sql 成 zip；
4. 计算 sha256（客户端强制校验），如启用验签则用私钥对包体签名（base64），并在客户端 .env 的 [APP] 段填写 RELEASE_PUBLIC_KEY；
5. 在更新服务器登记：version、build、notes、download_url、sha256、signature、force。

部署版与更新版同步发布

每次发布必须使用同一次前端构建产物，同时生成首次部署包和增量更新包：

.\deploy\release\build-release.ps1 `
  -Version '1.0.3' `
  -Build 124 `
  -Notes '本次更新说明'

产物目录示例：releases/kede-finance-v1.0.3-build-124/。

脚本会新建 releases/kede-finance-v<version>-build-<build>/，并同时生成：

• kede-finance-deploy-*.zip：首次安装使用，不包含 .env、安装锁、运行日志、依赖目录和 upgrade/；
• kede-finance-update-*.zip：后台系统更新使用，包含程序文件、前端构建产物和 upgrade/*.sql；
• manifest.json、SHA256SUMS、release-notes.txt；
• update-server/ Ubuntu 更新服务脚本和 release-guide.md 发布教程。

禁止只手工修改其中一个 ZIP。新版本应先递增 VERSION/BUILD、补齐幂等迁移，再统一执行上述脚本。

SQL 迁移编写规范

• 文件放更新包 upgrade/ 下，命名带递增序号（如 0002_add_xxx.sql）；
• 表名用 {PREFIX} 占位（运行时替换为实际前缀，如 kd_）；
• 语句以 ;\n 分隔；保持幂等（ADD COLUMN IF NOT EXISTS 思路或先判断）；
• 与代码侧 SchemaPatch 二选一：紧急补列可放 SchemaPatch（自动幂等补丁），版本化结构变更走更新包 SQL。

后台界面

入口：系统更新（需 upgrade 权限）。

区域	说明
当前版本	展示 display（如正式版1.0.2）与 build
检查更新	调用更新服务器；有新版显示说明与「立即更新」
可用备份	列表中可「回滚」到指定 backup_*.zip
升级历史	kd_upgrade_logs 记录

另可在 系统管理 → 系统设置 查看当前版本，并自定义后台访问路径（如 /admin666/，写入 .env 的 ADMIN_PATH 并镜像 SPA）。

注意事项

• 应用更新会覆盖代码，自定义改动应做成插件/主题或单独保管，避免被覆盖；
• 更新前确保 runtime/ 与项目根可写；
• 生产更新建议低峰执行并先确认备份生成；
• 更新包解压前会拒绝绝对路径、../ 和 Windows 盘符路径，避免恶意压缩包越界覆盖；
• force=true 的强制更新用于安全修复，前端应提示用户尽快更新；
• 自定义后台路径后，请同步宝塔伪静态中的后台 SPA location（可参考安装后生成的 public/nginx-admin-path.conf）。

---

下一篇：27 错误码大全