Drsakura
1ffcc1ea07
Add isolated update jobs with database backups, progress logs and application rollback. Remove default account hints and prevent default admin recreation after renaming. Enforce customer and order search scopes, secure session cookies, fix quotation rounding and amount wording, and update backend dependencies. Add API and deployment regression coverage.
63 lines
4.4 KiB
Markdown
63 lines
4.4 KiB
Markdown
# 管理员网页更新
|
|
|
|
管理员进入「设置 → 系统与更新」，检查新版本后输入当前密码，点击「安装」。任务进度和日志会在网页显示；重启过程中连接短暂中断，页面会自动重试，完成后点击「刷新使用新版本」。普通账号只能检查版本，不能安装或读取更新日志。
|
|
|
|
## 首次启用
|
|
|
|
这项功能需要先把包含网页更新功能的版本部署到服务器一次。之后通过 GitHub 发布更高版本的 Release 或 tag 即可在网页安装。发布标签与仓库顶层 `package.json` 的版本必须一致；版本号必须高于当前版本。更新不自动跟随 main 的每一次提交。
|
|
|
|
运行条件：
|
|
|
|
- Linux + systemd、Node.js 22 或更高版本、Git、npm。
|
|
- 应用目录为 Git 工作副本，没有未提交的修改或未跟踪文件（已忽略的数据、依赖和构建目录不受影响）。
|
|
- ERP 服务账号可以创建 systemd 临时单元、启停 ERP 服务，并读写应用目录和数据目录。现有 root 运行的 `erp.service` 满足此权限条件。
|
|
- 服务器能够访问 GitHub、npm registry 和项目依赖来源。
|
|
- 磁盘可容纳临时源码、两套后端依赖、前端构建和一份数据库备份。
|
|
|
|
默认服务名为 `erp`，对应 `erp.service`。如服务名不同，在 ERP 的 systemd 配置中增加：
|
|
|
|
```ini
|
|
[Service]
|
|
Environment=HAPPY_UPDATE_SERVICE=your-service-name
|
|
Environment=SECURE_COOKIE=1
|
|
```
|
|
|
|
服务名不含 `.service` 后缀。应用代码仍由现有 ERP 单元启动，更新任务用相同的 Node 可执行文件运行，并将该 Node 所在目录放在 PATH 首位，避免服务器旧 Node 抢先被使用。
|
|
|
|
更新源默认是 `Drsakura/happy-export`，可以通过服务器环境变量 `HAPPY_UPDATE_REPO=owner/repo` 配置；网页不能临时指定其他安装来源。当前自动安装从 GitHub 公共 HTTPS 仓库获取版本，不提供私有仓库令牌配置。
|
|
|
|
## 执行过程
|
|
|
|
1. 管理员权限校验、当前密码验证、并发更新锁和工作目录检查。
|
|
2. 读取配置仓库的最新 Release/tag，获取指定标签的提交，在独立 Git worktree 准备新版本。
|
|
3. 后端 `npm ci --omit=dev --ignore-scripts`，前端 `npm ci --include=dev`，再构建前端。
|
|
4. 使用 SQLite 在线备份 API 备份数据库，包含 WAL 中尚未合并的数据。
|
|
5. 再次确认运行目录没有发生代码修改，切换后端依赖、前端构建和 Git 提交。
|
|
6. 重启 ERP 服务，核验健康状态及实际版本，成功后删除旧依赖和旧前端构建。
|
|
|
|
下载、安装或构建失败不会切换正在运行的应用。切换后重启或健康检查失败，会尝试恢复旧 Git 提交、后端依赖和前端构建并重启。任务通过独立 systemd 临时服务执行，因此 ERP 重启不会终止更新任务。
|
|
|
|
## 日志、备份与恢复
|
|
|
|
每次任务的日志和数据库备份保存在：
|
|
|
|
```text
|
|
<DATA_DIR>/system-update/<任务ID>/update.log
|
|
<DATA_DIR>/system-update/<任务ID>/trade-before-update.db
|
|
<DATA_DIR>/system-update/status.json
|
|
```
|
|
|
|
日志与备份不会自动过期，管理员可按自己的备份策略清理。状态接口只向管理员返回日志末尾 12 KB。
|
|
|
|
自动恢复只回退应用代码与依赖，不自动覆盖业务数据库，以保留更新期间的业务写入。后续发布应保持数据库迁移向后兼容；如果新版本迁移了不兼容的数据结构，需要管理员停服后从备份恢复数据库，恢复时同时处理旧 WAL/SHM。
|
|
|
|
意外断电或更新任务被终止后，网页会识别任务已停止并提示失败。若残留 `backend/node_modules.update-old` 或 `frontend/dist.update-old`，新任务会停止并提示人工检查；先确认服务实际运行版本和数据库，再决定恢复或清理这些目录，避免覆盖恢复所需文件。
|
|
|
|
Windows 本地环境支持检查更新，安装按钮会提示只支持 Linux systemd 部署。
|
|
|
|
## 用户名修改
|
|
|
|
「个人资料 → 修改用户名」输入新用户名和当前密码即可。新用户名为 3–50 位字母、数字或 `_ . @ -`，以字母、数字或下划线开头；不能与其他用户的用户名重名（不区分大小写）。修改保留当前会话，其他会话失效，之后用新用户名登录。业务归属使用用户 ID，不会随用户名变化。
|
|
|
|
初始管理员只在用户表为空时创建；管理员改名之后，重新启动不会重新生成默认账号。登录页面不展示默认用户名或密码。
|