feat(epctl): add upgrade restart controls and rollback-safe deploy

wiki/EPCTL.en.md

@@ -86,6 +86,10 @@ Upgrade to a newer release:
 ./epctl upgrade --tag v1.0.9
 ```
 
+Running `./epctl upgrade --tag ...` directly restarts `epusdt` immediately after the files are replaced.
+If you want to replace files only, pass `--no-restart`.
+If you want an explicit confirmation step, pass `--prompt-restart`; in an interactive terminal the prompt is `[Y/n]`, so pressing Enter restarts by default.
+
 Inspect config, status, and logs:
 
 ```bash
@@ -136,6 +140,27 @@ When `.env` is auto-created, the script applies only the minimum bootstrap chang
 - `http_listen=<--listen, default 127.0.0.1:8000>`
 
 If `/opt/epusdt/.env` already exists, install and upgrade keep it unchanged.
+`/opt/epusdt/.env.example` is refreshed from the current release on every install / upgrade.
+
+## What Happens During Upgrade
+
+`upgrade` performs these steps:
+
+1. Detect the current CPU architecture and download the target GitHub Release archive
+2. Extract into `/tmp/epusdt/<tag>/extract/`
+3. Require the existing `/opt/epusdt/.env`; if it is missing, the command fails and tells you to run `install` first
+4. Replace `/opt/epusdt/epusdt`
+5. Replace `/opt/epusdt/.env.example`
+6. Keep the existing `/opt/epusdt/.env`
+7. Refresh `epusdt.service` and run `systemctl daemon-reload`
+8. Restart `epusdt` immediately by default
+
+Additional behavior:
+
+- `upgrade` no longer creates `.env` and no longer runs `systemctl enable`
+- `upgrade --no-restart` replaces files only and prints a manual restart warning
+- `upgrade --prompt-restart` asks whether to restart when an interactive terminal is available
+- if the restart fails after an upgrade, the script attempts to roll back the previous binary, `.env.example`, and unit file
 
 ## systemd Service Details
 
@@ -191,11 +216,12 @@ Examples:
 
 It performs these checks on the local machine:
 
-- builds an `ubuntu:24.04` + systemd test image
+- starts directly from `ubuntu:24.04` and installs systemd plus the test dependencies during container bootstrap
 - starts a privileged container
 - runs `epctl self-install` inside the container
 - downloads real GitHub Release artifacts
 - installs `epusdt`
+- when `upgrade-tag` is provided, verifies `upgrade --no-restart`, the default non-interactive `upgrade`, and both the `n` / Enter branches of `upgrade --prompt-restart`
 - verifies the systemd service, `www/index.html`, config output, logs, and status
 - verifies that `init-password` succeeds once and later returns `10040` after the admin password is changed
 

wiki/EPCTL.md

@@ -86,6 +86,10 @@ epctl
 ./epctl upgrade --tag v1.0.9
 ```
 
+直接执行 `./epctl upgrade --tag ...` 时，脚本会在文件替换完成后默认立即执行 `systemctl restart epusdt`。
+如果你只想替换文件而不重启，请显式传入 `--no-restart`。
+如果你希望人工确认，再传 `--prompt-restart`；交互终端下提示为 `[Y/n]`，直接回车默认重启。
+
 查看配置、状态、日志：
 
 ```bash
@@ -136,6 +140,27 @@ EPCTL_ASSUME_YES=1 ./epctl download
 - `http_listen=<--listen，默认 127.0.0.1:8000>`
 
 如果 `/opt/epusdt/.env` 已存在，则安装和升级都会保留它，不会覆盖。
+`/opt/epusdt/.env.example` 则会在每次 install / upgrade 时按当前 release 重新刷新。
+
+## 升级时会发生什么
+
+执行 `upgrade` 时，脚本会：
+
+1. 按当前机器架构下载目标 GitHub Release 压缩包
+2. 解压到 `/tmp/epusdt/<tag>/extract/`
+3. 要求现有 `/opt/epusdt/.env` 已存在；若不存在会直接失败，并提示先执行 `install`
+4. 覆盖 `/opt/epusdt/epusdt`
+5. 覆盖 `/opt/epusdt/.env.example`
+6. 保留现有 `/opt/epusdt/.env`
+7. 刷新 `epusdt.service` 并执行 `systemctl daemon-reload`
+8. 默认立即执行 `systemctl restart epusdt`
+
+补充行为：
+
+- `upgrade` 不会再补写 `.env`，也不会再执行 `systemctl enable`
+- `upgrade --no-restart` 只替换文件，不重启服务，并输出手动 restart 提示
+- `upgrade --prompt-restart` 会在交互终端下询问是否重启
+- 如果升级后的重启失败，脚本会尝试回滚旧的二进制、`.env.example` 和 unit 文件
 
 ## systemd 服务说明
 
@@ -191,11 +216,12 @@ GET /admin/api/v1/auth/init-password
 
 它会在本机：
 
-- 构建 `ubuntu:24.04` + systemd 测试镜像
+- 直接从 `ubuntu:24.04` 启动容器，并在容器启动阶段安装 systemd 与测试依赖
 - 启动一个特权容器
 - 在容器内执行 `epctl self-install`
 - 下载真实 GitHub Release
 - 安装 `epusdt`
+- 若传入 `upgrade-tag`，验证 `upgrade --no-restart`、默认 `upgrade`、以及 `upgrade --prompt-restart` 的 `n/回车` 分支
 - 检查 `systemd` 服务、`www/index.html`、配置文件、日志、状态输出
 - 验证 `init-password` 首次成功、修改管理员密码后再次请求返回 `10040`