release: 1.4.0

- 新增 server/rate-limit.ts：进程内固定窗口限流器，无数据库写入
- server/app.ts 注册全局 preHandler，仅作用于 /api/*，超限返回 429 与 Retry-After
- 提取 isApiPath 统一 onSend、preHandler 与 404 的路径判断
- 更新任务冲突判定改用 ACTIVE_UPDATE_CONFLICT_SQL，staged/download 产物不再阻塞新任务
- cancelUpdateJob 调用补上 await，避免结果恒为 pending Promise
- server/cli/update.ts 增加特权工作区所有权校验与暂存路径重建逻辑
- 新增 tests/rate-limit.test.ts 与 tests/update-apply-staging.test.ts

.env.example

@@ -31,6 +31,8 @@ TALLYNOTE_INSTALL_PREFIX=./
 TALLYNOTE_UPDATE_METADATA_URL=https://git.awaioi.com/api/v1/repos/awaioi/TallyNote/releases/latest
 TALLYNOTE_UPDATE_ALLOWED_HOSTS=git.awaioi.com
 TALLYNOTE_UPDATE_MAX_MB=512
+# Per-request timeout for update metadata, checksums, signatures, and archives.
+TALLYNOTE_UPDATE_TIMEOUT_SECONDS=30
 # SHA-256 is always required. Detached Ed25519 signatures are optional; set
 # this to true only when a root-managed public key is configured below.
 TALLYNOTE_UPDATE_REQUIRE_SIGNATURE=false

README.md

@@ -42,15 +42,15 @@ pnpm build:next
 
 `build:next` 与 `pnpm build` 一样输出到 `dist/web`，可直接由生产 Fastify 服务提供。
 
-本地开发首次初始化管理员使用 `pnpm admin:init`。生产安装器会在首次安装时提供管理员初始化向导；如果选择稍后创建，执行 `sudo tallynote-admin-init` 即可。也可以使用 `sudo tallynote-admin-init --username admin --display-name 管理员 --generate` 生成一次性临时密码。
+本地开发首次初始化管理员使用 `pnpm admin:init`。生产安装器会在首次安装时提供管理员初始化向导；如果选择稍后创建，执行 `sudo /usr/local/sbin/tallynote-admin-init` 即可。也可以使用 `sudo /usr/local/sbin/tallynote-admin-init --username admin --display-name 管理员 --generate` 生成一次性临时密码。
 
 默认地址为 `http://127.0.0.1:3000`，开发界面为 `http://127.0.0.1:5173`。配置项见 `.env.example`。
 
 ## 无 Docker 安装（systemd）
 
-安装器正式支持 **Linux x86_64（x64）**，脚本和运行时也支持在对应原生 runner 上发布 **aarch64（arm64）**；当前仓库内置 workflow 只生成 x64，arm64 需要在原生 ARM64 runner 上单独构建并发布。ARMv7/ARM32 仅实验性支持；Linux x86 32 位（`i386`、`i686`、`ia32`）明确不支持，因为 Node.js 24 和项目原生依赖没有可维护的官方构建。不要在 32 位系统上强行安装。
+安装器正式支持 **Linux x86_64（x64，glibc）**，应用包也可以在匹配的原生 runner 上发布 **aarch64（arm64）**；当前仓库内置 workflow 只生成 x64，arm64 需要在原生 ARM64 runner 上单独构建并发布。安装器托管的 Node.js 24.20.0 仅覆盖 Node.js 官方提供的 x64/arm64 glibc 归档；musl 或 ARMv7 主机必须预先提供可用的系统 Node.js 24+，否则安装器会明确拒绝。Linux x86 32 位（`i386`、`i686`、`ia32`）明确不支持。
 
-发布包必须包含 `dist/`（包括 `dist/server/cli/admin-init.js`）、生产依赖、匹配架构的 Node runtime、systemd 单元、`bin/tallynote-admin-init`、`uninstall.sh`，以及 `SHA256SUMS`。签名文件 `SHA256SUMS.sig` 是可选增强校验，不需要为普通安装准备公钥。安装器默认直接安装最新版本：
+发布包只包含 `dist/`（包括 `dist/server/cli/admin-init.js`）、CI 在目标 Linux 架构上预编译的生产依赖、systemd 单元、`bin/tallynote-admin-init`、`uninstall.sh` 和 `SHA256SUMS`，不再携带 Node.js 二进制、源码或开发依赖。安装器检查系统 Node.js 是否为 24+；符合要求时直接复用，不符合时从 `nodejs.org` 下载并校验一次，后续应用更新不会重复下载运行时。签名文件 `SHA256SUMS.sig` 是可选增强校验，不需要为普通安装准备公钥。安装器默认直接安装最新版本：
 
 ```bash
 curl --proto '=https' --tlsv1.2 -fsSL https://git.awaioi.com/awaioi/TallyNote/raw/branch/main/install.sh | sudo bash
@@ -62,7 +62,13 @@ curl --proto '=https' --tlsv1.2 -fsSL https://git.awaioi.com/awaioi/TallyNote/ra
 curl --proto '=https' --tlsv1.2 -fsSL https://git.awaioi.com/awaioi/TallyNote/raw/branch/main/install.sh | sudo bash
 ```
 
-首次安装完成网络配置后，向导会询问是否立即创建管理员。选择创建时，用户名、显示名称和密码都在当前 SSH 终端中输入；选择稍后创建也不会阻塞服务启动，之后执行 `sudo tallynote-admin-init` 即可。升级已有安装时，向导会自动识别现有管理员并跳过创建，不会覆盖账号或账目。
+首次安装完成网络配置后，向导会询问是否立即创建管理员。选择创建时，用户名、显示名称和密码都在当前 SSH 终端中输入，并会直接回显当前输入内容；密码不会写入安装日志、配置文件或命令行参数。选择稍后创建也不会阻塞服务启动，之后执行 `sudo /usr/local/sbin/tallynote-admin-init` 即可。升级已有安装时，向导会自动识别现有管理员并跳过创建，不会覆盖账号或账目。
+
+如果账号是在旧版本中用正式密码创建、但仍被标记为“首次登录需要修改密码”，可以在服务器上用当前密码修复标志位（不会更换密码）：
+
+```bash
+sudo /usr/local/sbin/tallynote-admin-init --mark-password-configured --username <用户名>
+```
 
 监听方式有两个选项：`127.0.0.1` 仅本机访问（默认、更安全），或 `0.0.0.0` 允许通过局域网/公网 IP 访问。安装时可输入自定义端口（直接回车使用默认端口），安装器会检查 TCP 端口是否已被占用；选择 `0.0.0.0` 时会尝试通过 HTTPS 自动获取公网 IPv4，并将 `http://公网IP:端口` 作为默认访问地址，也可以改填域名。不能填写 `http://0.0.0.0:3000`。直连 HTTP 未加密，安装器会要求明确确认，只适合受控网络。绑定域名后应改为 HTTPS 反向代理，设置真实的 `TALLYNOTE_PUBLIC_ORIGIN`、`TALLYNOTE_COOKIE_SECURE=true`、`TALLYNOTE_ALLOW_INSECURE_HTTP=false`，然后执行 `sudo systemctl restart tallynote.service`。服务启动后，安装器会先请求本机 `/health`；只有健康检查通过才会报告安装完成并输出最终访问链接。监听 `127.0.0.1` 时该链接只对服务器本机有效；需要公网或其他设备访问时请选择 `0.0.0.0`。健康检查失败时会输出 systemd 状态和最近日志并回滚本次切换。
 
@@ -109,7 +115,7 @@ tallynote installer: 查看服务状态：systemctl status tallynote.service
 
 已有安装默认拒绝降级到不高于当前版本；确需回退时显式使用 `--allow-downgrade`，正常更新不会覆盖当前或更高版本。
 
-安装布局为 `/opt/tallynote/releases/<version>` 加 `/opt/tallynote/current` 符号链接；切换通过临时链接和原子重命名完成。root 更新器使用前缀下独立的 `/opt/tallynote/.update-work`（`0700 root:root`）和 `.update-state` 恢复标记，不会把 root 解包工作区放进应用可写暂存目录。SQLite 数据、附件、暂存、导出和更新队列始终在外置 `/var/lib/tallynote`，不会随版本包删除。服务单元位于 `/etc/systemd/system/tallynote.service`，配置文件为 `/etc/tallynote/tallynote.env`；监听地址、端口和公开 Origin 由该环境文件控制，默认仍是 `127.0.0.1:3000`。
+安装布局为 `/opt/tallynote/releases/<version>` 加 `/opt/tallynote/current` 符号链接；没有系统 Node.js 24+ 时，安装器会额外创建带管理标记的 `/opt/tallynote/nodejs/`。切换通过临时链接和原子重命名完成。root 更新器使用前缀下独立的 `/opt/tallynote/.update-work`（`0700 root:root`）和 `.update-state` 恢复标记，不会把 root 解包工作区放进应用可写暂存目录。SQLite 数据、附件、暂存、导出和更新队列始终在外置 `/var/lib/tallynote`，不会随版本包删除。服务单元位于 `/etc/systemd/system/tallynote.service`，配置文件为 `/etc/tallynote/tallynote.env`；监听地址、端口和公开 Origin 由该环境文件控制，默认仍是 `127.0.0.1:3000`。
 
 升级有两种方式：
 
@@ -176,3 +182,5 @@ docker compose run --rm --no-deps tallynote node dist/server/cli/admin-init.js -
 业务导出不是系统备份。停服后复制完整数据目录（数据库、WAL/SHM、`files/`、`staging/`、`exports/` 和更新任务文件），恢复时保持目录 `0700`、文件 `0600` 权限，并在启动前确保没有其他 TallyNote 进程使用该目录。更新器会在切换前额外写入 `/var/lib/tallynote-backups/`，但仍建议保留服务器级备份。
 
 应用层会拒绝非 HTTPS 更新源、未匹配主机、无 SHA-256 的归档、路径穿越、特殊文件和符号链接；启用签名要求时也会拒绝无有效签名的归档。附件与导出下载需要登录并写入审计。拥有服务器文件权限的人仍然可以直接读取 SQLite 和附件，部署时应限制 SSH、备份和磁盘权限，并通过 HTTPS 反代访问。
+
+<!-- v1.3.1: online update refactor — synchronous web-process download -->

bin/tallynote

@@ -1,8 +1,17 @@
 #!/usr/bin/env bash
 set -Eeuo pipefail
 
+PATH=/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin
+export PATH
+
 ROOT=$(cd -- "$(dirname -- "$0")/.." && pwd -P)
-NODE="$ROOT/runtime/bin/node"
-[[ -x "$NODE" ]] || NODE=$(command -v node || true)
-[[ -n "$NODE" ]] || { printf 'TallyNote: Node.js runtime not found\n' >&2; exit 127; }
+NODE=${TALLYNOTE_NODE:-}
+node_is_usable() {
+  local candidate=$1 major
+  [[ -n "$candidate" && -x "$candidate" ]] || return 1
+  major=$("$candidate" -p 'process.versions.node.split(".")[0]' 2>/dev/null || true)
+  [[ "$major" =~ ^[0-9]+$ && "$major" -ge 24 ]]
+}
+node_is_usable "$NODE" || NODE=$(command -v node || true)
+node_is_usable "$NODE" || { printf 'TallyNote: Node.js 24+ not found; run the installer again\n' >&2; exit 127; }
 exec "$NODE" "$ROOT/dist/server/index.js" "$@"

bin/tallynote-admin-init

@@ -4,7 +4,7 @@ set -Eeuo pipefail
 # Production entry point for first-admin setup. The installer keeps the
 # EnvironmentFile root-readable only, so parse simple KEY=VALUE assignments
 # without sourcing arbitrary shell code.
-PATH=/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/bin
+PATH=/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin
 export PATH
 umask 077
 
@@ -15,6 +15,13 @@ SERVICE_NAME=${TALLYNOTE_SERVICE_NAME:-tallynote.service}
 
 die() { printf 'tallynote admin-init: %s\n' "$*" >&2; exit 1; }
 
+node_is_usable() {
+  local candidate=$1 major
+  [[ -n "$candidate" && -x "$candidate" ]] || return 1
+  major=$("$candidate" -p 'process.versions.node.split(".")[0]' 2>/dev/null || true)
+  [[ "$major" =~ ^[0-9]+$ && "$major" -ge 24 ]]
+}
+
 load_environment_file() {
   [[ -e "$CONFIG_FILE" ]] || return 0
   [[ -f "$CONFIG_FILE" && ! -L "$CONFIG_FILE" ]] || die '环境文件不是安全的普通文件'
@@ -105,9 +112,9 @@ main() {
     [[ "$argument" == "--check" ]] && check_only=1
   done
   root=$(resolve_release_root)
-  node="$root/runtime/bin/node"
-  [[ -x "$node" ]] || node=$(command -v node || true)
-  [[ -n "$node" && -x "$node" ]] || die '找不到 Node.js runtime'
+  node=${TALLYNOTE_NODE:-}
+  node_is_usable "$node" || node=$(command -v node || true)
+  node_is_usable "$node" || die '找不到 Node.js 24+'
   cli="$root/dist/server/cli/admin-init.js"
   [[ -f "$cli" && ! -L "$cli" ]] || die '管理员初始化程序不存在'
 

docs/release.md

@@ -1,8 +1,10 @@
 # Release、安装与更新
 
-TallyNote 的发布包必须在目标 Linux 架构上构建。`better-sqlite3`、`argon2`、`sharp` 和 Node runtime 都包含原生代码，不能在 macOS 上交叉打包后冒充 Linux。
+TallyNote 的发布包必须在目标 Linux 架构上构建。`better-sqlite3`、`argon2` 和 `sharp` 都包含原生代码，不能在 macOS 上交叉打包后冒充 Linux。Node.js 不再进入每个发布包；安装器负责复用系统 Node.js 24+，或从 Node.js 官方 HTTPS 归档下载并校验一次。
 
-正式支持：Linux x86_64/amd64；脚本和安装器也支持在原生 runner 上提供 Linux aarch64/arm64（glibc 或 musl）。当前仓库 workflow 只生成 x64，arm64 必须使用对应 runner 单独构建发布。ARMv7/ARM32 只在你拥有对应 runner 和完整依赖构建结果时实验使用。Linux x86 32 位（i386、i686、ia32）明确不支持，Node.js 24 及原生依赖没有可维护的正式构建，因此安装器会拒绝它。
+正式支持：Linux x86_64/amd64（glibc）；发布脚本也可在原生 Linux aarch64/arm64 runner 上构建对应应用包。当前仓库 workflow 只生成 x64，arm64 需要在匹配的 runner 上单独构建发布。安装器托管的 Node.js 24.20.0 仅覆盖 Node.js 官方提供的 x64/arm64 glibc 归档；musl 或 ARMv7 主机必须预先提供可用的系统 Node.js 24+，否则安装器会明确拒绝，而不会请求不存在的官方归档。Linux x86 32 位（i386、i686、ia32）明确不支持。
+
+首次安装按 `TALLYNOTE_NODE`、系统 `node`、安装器托管运行时的顺序选择 Node.js。没有满足 24+ 的系统 Node.js 时，安装器从 `https://nodejs.org/dist/v24.20.0/` 下载匹配架构的归档和 `SHASUMS256.txt`，通过 SHA-256 校验后放入 `/opt/tallynote/nodejs/`，并把路径写入 `/etc/tallynote/tallynote.env`。发布包和应用更新都不会再次携带或下载 Node.js；卸载器只删除带 TallyNote 管理标记的运行时目录。
 
 ## 自动发布
 
@@ -30,7 +32,7 @@ GITEA_TOKEN=... \
   ./scripts/publish-gitea-release.sh v1.1.2 ./release
 ```
 
-发布资产名称必须包含当前平台，例如 `tallynote-1.1.2-linux-x64-glibc.tar.gz`。构建脚本会同时生成完整安装包和轻量更新包：`tallynote-1.1.2-linux-x64-glibc.tar.gz` 用于首次安装，`tallynote-1.1.2-linux-x64-glibc.update-<锁文件 SHA256>.tar.gz` 仅用于复用现有运行时的后台更新。同一个 Release 只保留一个 `SHA256SUMS`；有签名时再保留一个 `SHA256SUMS.sig`，签名覆盖清单完整原文。
+发布资产名称必须包含当前平台，例如 `tallynote-1.1.2-linux-x64-glibc.tar.gz`。当前发布流程只生成这一份完整生产包：包内包含构建后的 `dist/`、目标 Linux 架构上预编译的生产 `node_modules/`、迁移文件、systemd 单元和安装/更新/卸载辅助脚本，但不包含 Node.js 二进制、源码或开发依赖。首次安装和后台应用更新都使用同一份完整包；主机上的 Node.js 24+ 由安装器一次性准备并在后续更新中复用。同一个 Release 只保留一个 `SHA256SUMS`；有签名时再保留一个 `SHA256SUMS.sig`，签名覆盖清单完整原文。
 
 ## curl 安装
 
@@ -83,6 +85,7 @@ tallynote installer: 访问地址：http://127.0.0.1:<端口>
 ```text
 /opt/tallynote/releases/<version>/   # 只读发布代码
 /opt/tallynote/current -> releases/<version>
+/opt/tallynote/nodejs/                # 主机没有 Node.js 24+ 时由安装器管理
 /opt/tallynote/.update-work/         # 0700 root:root，root 更新器临时工作区
 /opt/tallynote/.update-state        # root 更新状态标记，异常中断后用于恢复
 /var/lib/tallynote/                  # SQLite、附件、暂存和导出
@@ -106,7 +109,7 @@ sudo /usr/local/sbin/tallynote-uninstall
 
 将环境文件中的 `TALLYNOTE_UPDATE_STRATEGY=systemd`、`TALLYNOTE_UPDATE_METADATA_URL` 和 `TALLYNOTE_UPDATE_ALLOWED_HOSTS` 配好后，后台“系统更新”会读取 Gitea 的 `/api/v1/repos/<owner>/<repo>/releases/latest`。检查结果只显示当前平台匹配且通过 SHA-256 校验的资产；如果配置了 `TALLYNOTE_UPDATE_PUBLIC_KEY_FILE` 并启用签名要求，再额外验证 Ed25519 签名。
 
-后台更新分为两个明确阶段。管理员先在“系统更新”读取最新 Release 的版本号、发布时间和更新说明，点击“下载更新包”；当前安装如果存在匹配的锁文件指纹，更新器会自动选择轻量 `update-<锁文件 SHA256>` 资产，仅下载 `dist`、迁移和版本元数据，并复用当前版本的 Node 与生产依赖；如果运行时指纹不匹配或轻量包不可用，则自动选择完整安装包。root 更新器会在主服务继续运行时下载、校验 SHA-256、解包并暂存。页面显示“下载完成，等待应用”后，管理员再点击“立即更新”。应用阶段才会短暂停止服务、备份数据、切换 release、启动并执行健康检查；页面显示重启倒计时并自动重试连接。浏览器只提交版本号、任务 ID 和确认标志，不能提交 URL 或文件路径。
+后台更新分为两个明确阶段。管理员先在“系统更新”读取最新 Release 的版本号、发布时间和更新说明，点击“下载更新包”；更新器下载同一份完整生产包，流式校验 SHA-256、解包并暂存，成功后只显示“已下载，等待应用”，不会自动重启。管理员点击“立即更新”后才写入 root 更新请求，应用阶段才会短暂停止服务、备份数据、切换 release、启动并执行健康检查；页面显示重启倒计时并自动重试连接。浏览器只提交版本号、任务 ID 和确认标志，不能提交 URL 或文件路径。
 
 Web 进程把受保护的任务文件交给 root 的 `tallynote-update.path`/`tallynote-update.service`，root runner 会重新读取配置源并验证 metadata、清单和暂存目录，不信任队列文件中的 URL 或摘要。切换失败或健康检查失败会恢复旧版本；手动回滚：
 

docs/update-refactor-plan.md

@@ -0,0 +1,303 @@
+# 在线更新重构方案
+
+## 一、问题背景
+
+当前在线更新使用 4 次进程交接链路：
+
+```
+web 进程 → 写 update-request.json → tallynote-update.path 触发
+→ tallynote-update.service → tallynote-update-runner.sh (root)
+→ 下载 + 校验 + 暂存 + 停服 + 备份 + 切换 + 重启 + 健康检查
+```
+
+下载在 root runner 中执行，前端只能轮询 DB 状态，看不到实时进度。
+多次出现"等待系统调度"卡死，根因是链路中任一环节出错都会断链。
+
+## 二、目标
+
+将下载移入 web 进程同步执行，root runner 只负责特权应用（停服/备份/切换/重启）。
+链路从 4 次交接缩减为 1 次。
+
+## 三、当前架构（需改动的文件清单）
+
+| 文件 | 行数 | 职责 | 改动级别 |
+|---|---|---|---|
+| server/update-service.ts | ~420 | checkForUpdate, writeUpdateRequest, reconcileOrphanedUpdateJobs, cancelUpdateJob, publicUpdateJob | 大改 |
+| server/update.ts | ~300 | fetchReleaseMetadata, fetchReleaseBytes, selectReleaseAsset, validateHttpsUrl | 小改 |
+| server/app.ts (930-1230) | ~300 | 6 个 API 路由 | 大改 |
+| scripts/tallynote-update-runner.sh | ~200 | root runner: flock+心跳+恢复+下载+校验+暂存+应用 | 大改 |
+| scripts/tallynote-update.sh | ~100 | 手动更新/回滚入口 | 小改 |
+| systemd/tallynote-update.service | ~30 | oneshot root 服务 | 小改 |
+| systemd/tallynote-update.path | ~20 | 监听请求文件触发 | 不变 |
+| web/src/main.tsx (697-790) | ~90 | UpdateCenter 组件 | 大改 |
+| shared/contracts.ts (85-100) | ~15 | UpdateJobStatus 枚举 | 小改 |
+| server/db/schema.ts (134-163) | ~30 | update_jobs 表 | 不变 |
+| server/config.ts | ~100 | TALLYNOTE_UPDATE_* 配置 | 小改 |
+| tests/update-api.test.ts | ~450 | 更新 API 测试 | 大改 |
+
+## 四、改动后的架构
+
+```
+用户点"下载更新包"
+  ↓
+web 进程 (tallynote 用户, 非 root)
+  ├── 创建 job 行 (status=downloading)
+  ├── HTTPS 流式下载归档到 /var/lib/tallynote/staging/update-<jobId>.tar.gz
+  ├── 边下载边更新 DB: downloadedBytes, downloadSpeedBps
+  ├── 下载完成 → SHA-256 校验 → status=staged
+  └── 写 update-request.json (operation=apply, 含暂存路径)
+       ↓
+tallynote-update.path 触发 → tallynote-update.service (root)
+  ├── 读请求文件
+  ├── 停服 → 备份 → 原子切换 → 重启 → 健康检查
+  └── 更新 DB: status=completed/failed
+```
+
+## 五、详细代码修改
+
+### 5.1 server/update-service.ts
+
+**新增函数：**
+
+```ts
+// 同步下载归档，流式写入暂存目录，实时更新 DB 进度
+export async function downloadReleaseAsset(
+  database: Database.Database,
+  config: AppConfig,
+  jobId: string,
+  assetUrl: string,
+  expectedSha256: string,
+  assetName: string,
+): Promise<{ actualSha256: string; sizeBytes: number; downloadPath: string }>;
+```
+
+逻辑：
+- 用 fetchReleaseBytes (已存在于 update.ts) 发起 HTTPS 请求
+- 创建可写流到 config.dataDir/staging/update-<jobId>.tar.gz (tallynote 用户可写)
+- pipeline(response.body → createHash('sha256') → fileStream)，边算 hash 边写盘
+- 每秒更新 DB: downloadedBytes, downloadSpeedBps, status=downloading
+- 完成后比对 expectedSha256 vs actualSha256，不匹配 → status=failed
+- 匹配 → status=staged, 写 downloadPath 到 DB
+- 然后写 update-request.json (operation=apply)
+
+**修改函数：**
+
+- `reconcileOrphanedUpdateJobs`: 保留，但 queued 状态不再出现（下载在 web 进程内）
+- `publicUpdateJob`: 保留，已支持 downloadedBytes/downloadSpeedBps 字段
+- `cancelUpdateJob`: 增加 abort 下载流的能力
+- `writeUpdateRequest`: 增加 stagedPath 字段传递暂存文件路径
+
+**删除/简化：**
+- QUEUED_UPDATE_TIMEOUT_MS 逻辑不再需要（下载不在 systemd 队列中等待）
+
+### 5.2 server/app.ts — API 路由修改
+
+**POST /api/update/download → 改为同步下载**
+
+当前：创建 job → 写请求文件 → 返回 202
+改为：
+1. 创建 job (status=downloading)
+2. 在请求处理函数内同步执行 downloadReleaseAsset
+3. 下载完成后写 apply 请求文件
+4. 返回 { job: { status: "staged", ... } }
+5. 如果下载中客户端断开，设置 AbortController 取消下载
+
+注意：Fastify 请求超时需配置为足够长（115MB / 最低网速）。设置路由级
+bodyLimit=0 (不读 body) 并配置 reply 的 connectionTimeout。
+
+**新增 SSE 端点：GET /api/update/progress**
+
+返回 Server-Sent Events 流，推送实时下载进度：
+```
+event: progress
+data: {"downloadedBytes": 12345678, "speedBps": 5242880, "sizeBytes": 120586240}
+```
+前端用 EventSource 监听。下载完成后关闭 SSE。
+
+**POST /api/update/apply — 不变**
+
+仍然读请求文件触发 root runner。
+
+**GET /api/update/status — 不变**
+
+仍然返回 job 状态。
+
+### 5.3 scripts/tallynote-update-runner.sh
+
+**删除：**
+- 下载逻辑 (约 80 行)
+- 校验 SHA-256 逻辑 (约 30 行)
+- 暂存逻辑
+- 心跳 (heartbeat) — 下载不再在 root 中，apply 很快不需要心跳
+- QUEUED 状态处理
+
+**保留：**
+- flock 锁
+- 恢复状态 (.update-state) — apply 阶段仍需要
+- 停服 → 备份 → 原子切换 → 重启 → 健康检查
+- 回滚逻辑
+
+**简化后：** runner 只做 apply：读暂存路径 → 停服 → 备份 → 切换 → 启动 → 健康检查
+
+约从 200 行缩减到 80 行。
+
+### 5.4 scripts/tallynote-update.sh
+
+手动入口不变，但 runner 已不下载，所以手动入口也跳过下载阶段。
+`--rollback` 逻辑完全不变。
+
+### 5.5 systemd/tallynote-update.service
+
+```ini
+# 简化：不再需要 32 分钟超时（无下载阶段）
+TimeoutStartSec=5min
+# 其余安全约束不变
+```
+
+### 5.6 systemd/tallynote-update.path
+
+不变。仍然监听 update-request.json 触发 runner。
+但请求文件的 operation 现在只有 "apply"。
+
+### 5.7 web/src/main.tsx — UpdateCenter 组件
+
+**当前流程（前端）：**
+1. 进入页面 → GET /api/update/status
+2. 点"检查更新" → POST /api/update/check
+3. 点"更新到 vX.X.X" → POST /api/update/download → 轮询 /api/update/jobs/:id
+4. staged 后 → POST /api/update/apply → 轮询
+5. completed → 显示"重新加载"
+
+**改为：**
+1. 进入页面 → GET /api/update/status（自动检查最新版本）
+2. 点"检查更新" → POST /api/update/check
+3. 点"下载更新包" → POST /api/update/download（同步）
+   - 同时打开 EventSource(/api/update/progress) 监听实时进度
+   - 显示：下载进度条 + 已下载/总量 + 网速 + 剩余时间
+   - 下载完成 → 自动切换到"立即更新"按钮
+4. 点"立即更新" → POST /api/update/apply
+   - 弹窗显示：正在应用更新 → 倒计时 → 自动重连
+5. 重连成功 → 显示"更新完成" + 版本号变化
+
+**UI 状态机：**
+```
+idle → checking → hasUpdate
+  → downloading (实时进度, 可取消)
+    → verifying (校验中, 短暂)
+      → staged (显示"立即更新"按钮)
+        → applying (倒计时弹窗)
+          → completed (显示"重新加载")
+          → failed (显示错误 + 重试)
+```
+
+**取消下载：** 下载中显示"取消"按钮 → POST /api/update/cancel → abort 流
+
+### 5.8 shared/contracts.ts
+
+UpdateJobStatus 不变（仍包含所有状态）。
+新增 downloadProgress 的事件类型定义。
+
+### 5.9 server/config.ts
+
+新增：
+- `stagingDir`: path.join(dataDir, "staging") — 暂存目录
+- `updateDownloadTimeoutMs`: 下载超时 (默认 10 分钟)
+
+### 5.10 tests/update-api.test.ts
+
+重写下载测试：
+- mock HTTPS 响应，验证流式下载 + SHA-256 校验
+- 验证下载进度写入 DB
+- 验证下载完成后写 apply 请求文件
+- 验证取消下载清理暂存文件
+- apply 测试不变
+
+## 六、不修改的部分
+
+- 后端 API 契约语义不变（check/apply/cancel/status 接口签名不变）
+- update_jobs 表结构不变
+- 数据目录布局不变
+- 安装/卸载逻辑不变
+- 权限语义不变（web 非 root, runner root）
+- SHA-256 强制校验不变
+- 原子切换 + 自动回滚不变
+- 版本号比较逻辑不变
+- Release 元数据获取逻辑不变
+
+## 七、向后兼容
+
+- 旧版本安装（v1.2.9 及之前）升级到新版本后：
+  - 已有的 systemd 单元仍能工作
+  - 如果有遗留的 queued 状态 job，reconcileOrphanedUpdateJobs 会清理
+  - runner 简化后仍能处理 apply 请求
+- 数据库迁移：不需要（表结构不变）
+- 请求文件格式：增加 stagedPath 字段，旧 runner 忽略未知字段
+
+## 八、验收标准
+
+### 功能验收
+
+1. 进入更新页面 → 自动检查最新版本 → 显示 Release 信息
+2. 点"下载更新包" → 实时显示进度条、已下载字节数、网速
+3. 下载完成 → 自动校验 SHA-256 → 显示"立即更新"
+4. 点"立即更新" → 弹窗倒计时 → 服务重启 → 自动重连 → 显示新版本号
+5. 更新失败 → 显示错误 → 可重试
+6. 下载中可取消 → 暂存文件清理干净
+7. 不出现"等待系统调度"状态
+8. 不显示直链下载地址
+9. 更新日志 markdown 正确渲染
+10. 通知弹窗在右下角，使用柔和语义双层卡片样式
+11. 无 emoji，使用 Lucide 图标
+
+### 安全验收
+
+12. 下载必须 HTTPS
+13. SHA-256 校验不匹配时拒绝应用
+14. web 进程不执行 systemctl
+15. root runner 仍用 flock 防并发
+16. 路径穿越、符号链接仍被拒绝
+
+### 回滚验收
+
+17. 应用失败 → 自动回滚到上一版本
+18. 数据目录不被替换
+19. 手动回滚 `sudo /usr/local/sbin/tallynote-update --rollback` 仍可用
+
+### 测试验收
+
+20. pnpm check 通过
+21. pnpm test 全量通过
+22. pnpm test:installer 通过
+23. pnpm run build 通过
+24. CI 构建通过（python3 pty 测试不依赖 expect）
+
+### 前端验收
+
+25. 页面切换过渡丝滑，无延迟感
+26. 下载进度条垂直水平居中
+27. 弹窗内图标与文字水平对齐
+28. 响应式：窄屏不溢出、不遮挡
+29. 键盘可操作核心流程
+30. prefers-reduced-motion 下功能完整
+
+## 九、实施顺序
+
+1. 后端：server/update-service.ts 新增 downloadReleaseAsset
+2. 后端：server/app.ts 改 download 路由 + 新增 progress SSE
+3. 后端：server/config.ts 新增 stagingDir
+4. 脚本：scripts/tallynote-update-runner.sh 简化（删下载/心跳）
+5. systemd：tallynote-update.service 调整超时
+6. 前端：web/src/main.tsx UpdateCenter 组件重写
+7. 测试：tests/update-api.test.ts 重写下载测试
+8. 全量验证：check + test + test:installer + build
+9. 发布新版本
+
+## 十、风险评估
+
+| 风险 | 级别 | 缓解 |
+|---|---|---|
+| 长时间 HTTP 请求占用 Fastify 连接 | 中 | 路由级超时 + SSE 独立连接 |
+| 下载中途 web 进程崩溃 | 低 | job 行标记 failed，暂存文件下次清理 |
+| 并发下载 | 低 | DB 级活跃 job 检查 + 文件锁 |
+| 暂存目录磁盘空间不足 | 低 | 下载前检查可用空间 |
+| 旧版本残留的 queued job | 低 | reconcileOrphanedUpdateJobs 清理 |

install.sh

@@ -3,7 +3,7 @@ set -Eeuo pipefail
 
 # TallyNote native installer. Installs the latest release by default; use
 # --dry-run to preview without changing the host.
-PATH=/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/bin
+PATH=/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin
 export PATH
 umask 077
 
@@ -34,6 +34,11 @@ MAX_TIME=${TALLYNOTE_INSTALL_MAX_TIME_SECONDS:-300}
 RELEASE_ALLOWED_HOSTS=${TALLYNOTE_RELEASE_ALLOWED_HOSTS:-}
 OPENSSL_BIN=${TALLYNOTE_OPENSSL_BIN:-openssl}
 UNAME_BIN=${TALLYNOTE_UNAME_BIN:-uname}
+NODE_MIN_MAJOR=24
+NODE_VERSION=${TALLYNOTE_NODE_VERSION:-24.20.0}
+NODE_PATH=${TALLYNOTE_NODE:-}
+NODE_INSTALL_ROOT=$PREFIX/nodejs
+NODE_VERSION_DETECTED=''
 # Service network settings are written to the systemd EnvironmentFile on a
 # fresh install. Existing values are preserved unless the corresponding
 # TALLYNOTE_* variable is explicitly supplied to the installer.
@@ -57,6 +62,7 @@ INSTALL_PREVIOUS_TARGET=''
 INSTALL_NEW_RELEASE=''
 INSTALL_WORK_DIR=''
 INSTALL_BACKUP_DIR=''
+INSTALL_UNIT_TMP=''
 INSTALL_BACKUP_COMPLETE=0
 INSTALL_WAS_ACTIVE=0
 INSTALL_PATH_WAS_ACTIVE=0
@@ -65,6 +71,12 @@ INSTALL_WAS_ENABLED=0
 INSTALL_PATH_WAS_ENABLED=0
 INSTALL_UPDATE_WAS_ENABLED=0
 INSTALL_SYSTEMD_TOUCHED=0
+INSTALL_NODE_CREATED=0
+INSTALL_NODE_TARGET=''
+INSTALL_NODE_MARKER_CREATED=0
+INSTALL_NODE_MARKER=''
+INSTALL_NODE_ROOT_CREATED=0
+NODE_INSTALL_TMP=''
 ADMIN_INIT_PATH=/usr/local/sbin/tallynote-admin-init
 INSTALL_FIRST_INSTALL=0
 DATA_DIR_TEMP_ROOT=0
@@ -230,26 +242,26 @@ run_initial_admin_wizard() {
     return 0
   fi
   if (( NON_INTERACTIVE )); then
-    log '非交互模式：跳过管理员初始化；稍后可执行 sudo tallynote-admin-init'
+    log "非交互模式：跳过管理员初始化；稍后可执行 sudo $ADMIN_INIT_PATH"
     return 0
   fi
   [[ -r "$PROMPT_INPUT" && -w "$PROMPT_OUTPUT" ]] || {
-    log '未检测到交互式终端：跳过管理员初始化；稍后可执行 sudo tallynote-admin-init'
+    log "未检测到交互式终端：跳过管理员初始化；稍后可执行 sudo $ADMIN_INIT_PATH"
     return 0
   }
   [[ -x "$ADMIN_INIT_PATH" ]] || die '管理员初始化命令未安装'
 
   local status choice
   if ! status=$("$ADMIN_INIT_PATH" --check 2>/dev/null); then
-    log '无法检查管理员初始化状态；基础安装已完成，稍后可执行 sudo tallynote-admin-init'
+    log "无法检查管理员初始化状态；基础安装已完成，稍后可执行 sudo $ADMIN_INIT_PATH"
     return 0
   fi
   [[ "$status" == empty ]] || return 0
 
-  exec 9<"$PROMPT_INPUT" || die '无法打开终端输入；请稍后执行 sudo tallynote-admin-init'
+  exec 9<"$PROMPT_INPUT" || die "无法打开终端输入；请稍后执行 sudo $ADMIN_INIT_PATH"
   {
     printf '\n首次安装还差一步：请创建管理员账号。\n'
-    printf '管理员账号用于登录 TallyNote，首次登录后需要设置正式密码。\n'
+    printf '管理员账号用于登录 TallyNote；这里输入的密码会直接作为正式密码。\n'
   } > "$PROMPT_OUTPUT"
   while :; do
     prompt_value '现在创建管理员？输入 yes 继续，其他内容稍后创建' 'yes'
@@ -258,7 +270,7 @@ run_initial_admin_wizard() {
       yes|YES|Yes|y|Y) break ;;
       no|NO|No|n|N|'')
         exec 9<&-
-        log '已跳过管理员初始化；稍后可执行 sudo tallynote-admin-init'
+        log "已跳过管理员初始化；稍后可执行 sudo $ADMIN_INIT_PATH"
         return 0
         ;;
       *) printf '请输入 yes 或 no。\n' > "$PROMPT_OUTPUT" ;;
@@ -267,7 +279,7 @@ run_initial_admin_wizard() {
   stage '创建首位管理员（密码不会写入安装日志）'
   if ! "$ADMIN_INIT_PATH" <&9 > "$PROMPT_OUTPUT"; then
     exec 9<&-
-    log '管理员初始化未完成；基础安装已完成，稍后可执行 sudo tallynote-admin-init'
+    log "管理员初始化未完成；基础安装已完成，稍后可执行 sudo $ADMIN_INIT_PATH"
     return 0
   fi
   exec 9<&-
@@ -402,6 +414,7 @@ configure_network_interactively() {
 [[ "$REQUIRE_SIGNATURE" == true || "$REQUIRE_SIGNATURE" == false ]] || die 'TALLYNOTE_INSTALL_REQUIRE_SIGNATURE 必须是 true 或 false'
 [[ "$ALLOW_DOWNGRADE" == true || "$ALLOW_DOWNGRADE" == false ]] || die 'TALLYNOTE_ALLOW_DOWNGRADE 必须是 true 或 false'
 [[ "$SIGNATURE_FORMAT" == ed25519 || "$SIGNATURE_FORMAT" == gpg ]] || die '签名格式必须是 ed25519 或 gpg'
+[[ "$NODE_VERSION" =~ ^24\.[0-9]+\.[0-9]+$ ]] || die 'TALLYNOTE_NODE_VERSION 必须是 24.x.y 版本号'
 [[ "$MAX_RELEASE_MB" =~ ^[1-9][0-9]*$ && "$MAX_EXTRACT_MB" =~ ^[1-9][0-9]*$ && "$MAX_ARCHIVE_ENTRIES" =~ ^[1-9][0-9]*$ ]] || die '安装资源限制必须是正整数'
 [[ "$CONNECT_TIMEOUT" =~ ^[1-9][0-9]*$ && "$MAX_TIME" =~ ^[1-9][0-9]*$ ]] || die '安装超时配置必须是正整数'
 
@@ -461,6 +474,146 @@ detect_platform() {
   export TALLYNOTE_ARCH TALLYNOTE_LIBC
 }
 
+node_major_version() {
+  local candidate=$1 value
+  [[ -x "$candidate" ]] || return 1
+  value=$("$candidate" -p 'process.versions.node.split(".")[0]' 2>/dev/null || true)
+  [[ "$value" =~ ^[0-9]+$ ]] || return 1
+  printf '%s' "$value"
+}
+
+node_is_legacy_embedded() {
+  local candidate=$1 resolved
+  [[ -n "$candidate" ]] || return 1
+  resolved=$(readlink -f -- "$candidate" 2>/dev/null || realpath "$candidate" 2>/dev/null || printf '%s' "$candidate")
+  [[ "$resolved" == "$PREFIX/current/runtime/"* || "$resolved" == "$PREFIX/releases/"*/runtime/* ]]
+}
+
+node_is_usable() {
+  local candidate=$1 major resolved uid mode_bits
+  [[ -n "$candidate" && -x "$candidate" ]] || return 1
+  resolved=$(readlink -f -- "$candidate" 2>/dev/null || realpath "$candidate" 2>/dev/null || printf '%s' "$candidate")
+  [[ -x "$resolved" ]] || return 1
+  if (( EUID == 0 )); then
+    uid=$(stat_uid "$resolved")
+    mode_bits=$(stat_mode_bits "$resolved")
+    [[ "$uid" == 0 && $((mode_bits & 18)) -eq 0 ]] || return 1
+  fi
+  major=$(node_major_version "$candidate") || return 1
+  (( major >= NODE_MIN_MAJOR )) || return 1
+  NODE_VERSION_DETECTED=$("$candidate" -p 'process.versions.node' 2>/dev/null || true)
+  [[ -n "$NODE_VERSION_DETECTED" ]]
+}
+
+node_archive_name() {
+  local platform
+  case "${TALLYNOTE_LIBC}:${TALLYNOTE_ARCH}" in
+    glibc:x64) platform=linux-x64 ;;
+    glibc:arm64) platform=linux-arm64 ;;
+    *) die "Node.js 官方未提供当前平台的 ${NODE_MIN_MAJOR}+ 归档（${TALLYNOTE_ARCH}/${TALLYNOTE_LIBC}）；请先安装可用的系统 Node.js 24+ 后重试" ;;
+  esac
+  printf 'node-v%s-%s.tar.xz' "$NODE_VERSION" "$platform"
+}
+
+install_managed_node() {
+  local archive checksum archive_name expected actual tmp extracted target marker
+  archive_name=$(node_archive_name)
+  tmp=$(mktemp -d)
+  NODE_INSTALL_TMP=$tmp
+  archive="$tmp/$archive_name"
+  checksum="$tmp/SHASUMS256.txt"
+  stage "系统未找到 Node.js ${NODE_MIN_MAJOR}+，下载官方运行时 ${NODE_VERSION}"
+  append_allowed_host nodejs.org
+  download "https://nodejs.org/dist/v${NODE_VERSION}/${archive_name}" "$archive" $((256 * 1024 * 1024))
+  download "https://nodejs.org/dist/v${NODE_VERSION}/SHASUMS256.txt" "$checksum" $((4 * 1024 * 1024))
+  expected=$(awk -v name="$archive_name" '$2 == name { print $1; exit }' "$checksum")
+  [[ "$expected" =~ ^[A-Fa-f0-9]{64}$ ]] || die 'Node.js 官方校验清单中没有匹配归档'
+  actual=$(sha256sum "$archive" | awk '{print $1}')
+  [[ "${actual,,}" == "${expected,,}" ]] || die 'Node.js 官方归档 SHA-256 校验失败'
+  if [[ ! -e "$NODE_INSTALL_ROOT" && ! -L "$NODE_INSTALL_ROOT" ]]; then
+    INSTALL_NODE_ROOT_CREATED=1
+  fi
+  ensure_root_directory "$NODE_INSTALL_ROOT" 755
+  tar -xJf "$archive" -C "$tmp"
+  extracted="$tmp/${archive_name%.tar.xz}"
+  [[ -d "$extracted" && -x "$extracted/bin/node" ]] || die 'Node.js 官方归档结构无效'
+  target="$NODE_INSTALL_ROOT/${archive_name%.tar.xz}"
+  [[ ! -e "$target" && ! -L "$target" ]] || die "Node.js 目标目录已存在：$target"
+  mv -- "$extracted" "$target"
+  INSTALL_NODE_CREATED=1
+  INSTALL_NODE_TARGET=$target
+  marker="$NODE_INSTALL_ROOT/.tallynote-managed"
+  if [[ -e "$marker" || -L "$marker" ]]; then
+    [[ -f "$marker" && ! -L "$marker" && "$(sed -n '1p' "$marker" 2>/dev/null)" == tallynote-managed-node-v1 ]] || die 'Node.js 管理目录标记无效'
+  else
+    printf 'tallynote-managed-node-v1\n' > "$marker"
+    chmod 600 "$marker"
+    INSTALL_NODE_MARKER_CREATED=1
+    INSTALL_NODE_MARKER=$marker
+  fi
+  chown -R root:root "$target"
+  chown root:root "$marker"
+  NODE_PATH="$target/bin/node"
+  rm -rf -- "$tmp"
+  NODE_INSTALL_TMP=''
+  node_is_usable "$NODE_PATH" || die '已安装的 Node.js 运行时无法通过版本检查'
+  stage_done "Node.js ${NODE_VERSION_DETECTED} 已安装并记录为共享运行时"
+}
+
+cleanup_node_install_if_needed() {
+  local result=$? marker
+  if [[ -n "$NODE_INSTALL_TMP" && -d "$NODE_INSTALL_TMP" ]]; then
+    rm -rf -- "$NODE_INSTALL_TMP" 2>/dev/null || true
+    NODE_INSTALL_TMP=''
+  fi
+  if (( INSTALL_COMMITTED == 0 && INSTALL_NODE_CREATED == 1 )); then
+    if [[ -n "$INSTALL_NODE_TARGET" && -d "$INSTALL_NODE_TARGET" && ! -L "$INSTALL_NODE_TARGET" ]]; then
+      rm -rf -- "$INSTALL_NODE_TARGET" 2>/dev/null || true
+    fi
+    marker=$INSTALL_NODE_MARKER
+    if (( INSTALL_NODE_MARKER_CREATED == 1 )) && [[ -n "$marker" && -f "$marker" && ! -L "$marker" ]]; then
+      rm -f -- "$marker" 2>/dev/null || true
+    fi
+    if (( INSTALL_NODE_ROOT_CREATED == 1 )) && [[ -d "$NODE_INSTALL_ROOT" && ! -L "$NODE_INSTALL_ROOT" ]]; then
+      rmdir -- "$NODE_INSTALL_ROOT" 2>/dev/null || true
+    fi
+    INSTALL_NODE_CREATED=0
+  fi
+  return "$result"
+}
+
+ensure_node_runtime() {
+  local candidate='' managed_node marker
+  [[ "$NODE_INSTALL_ROOT" == "$PREFIX"/* ]] || die 'Node.js 管理目录必须位于 TallyNote 安装目录内'
+  if [[ -n "$NODE_PATH" ]] && ! node_is_legacy_embedded "$NODE_PATH" && node_is_usable "$NODE_PATH"; then
+    stage_done "复用已配置的 Node.js ${NODE_VERSION_DETECTED}：$NODE_PATH"
+    return 0
+  fi
+  candidate=$(command -v node || true)
+  if [[ -n "$candidate" ]] && node_is_usable "$candidate"; then
+    NODE_PATH=$candidate
+    stage_done "复用系统 Node.js ${NODE_VERSION_DETECTED}：$NODE_PATH"
+    return 0
+  fi
+  marker="$NODE_INSTALL_ROOT/.tallynote-managed"
+  if [[ -f "$marker" && ! -L "$marker" && "$(sed -n '1p' "$marker" 2>/dev/null)" == tallynote-managed-node-v1 ]]; then
+    while IFS= read -r managed_node; do
+      [[ -n "$managed_node" ]] || continue
+      if node_is_usable "$managed_node"; then
+        NODE_PATH=$managed_node
+        stage_done "复用已安装的 Node.js ${NODE_VERSION_DETECTED}：$NODE_PATH"
+        return 0
+      fi
+    done < <(find "$NODE_INSTALL_ROOT" -mindepth 3 -maxdepth 3 -type f -path '*/bin/node' -print 2>/dev/null | sort -V -r)
+  fi
+  if (( ! APPLY )); then
+    log "dry-run: 当前主机需要 Node.js ${NODE_MIN_MAJOR}+；正式安装时将从 nodejs.org 下载并校验"
+    return 0
+  fi
+  [[ $EUID -eq 0 ]] || die '安装 Node.js 运行时必须以 root 运行'
+  install_managed_node
+}
+
 require_https() {
   local value=$1
   case "$value" in https://*) ;; *) die "release endpoints must use HTTPS: $value" ;; esac
@@ -711,7 +864,7 @@ normalize_release_tree() {
   fi
   find "$root" -type d -exec chmod 755 {} +
   find "$root" -type f -exec chmod 644 {} +
-  for item in "$root/bin"/* "$root/scripts"/*.sh "$root/runtime/bin"/* "$root/uninstall.sh"; do
+  for item in "$root/bin"/* "$root/scripts"/*.sh "$root/uninstall.sh"; do
     [[ -f "$item" && ! -L "$item" ]] || continue
     chmod 755 "$item"
   done
@@ -868,6 +1021,10 @@ stop_existing_services() {
 
 rollback_install_if_needed() {
   local result=$? rollback_tmp
+  # This helper intentionally returns the original exit status when used as
+  # the early EXIT trap. Once called from this rollback trap, swallow that
+  # status so errexit cannot skip restoration of the previous installation.
+  cleanup_node_install_if_needed || true
   if (( INSTALL_COMMITTED == 0 && INSTALL_SYSTEMD_TOUCHED == 1 )) && command -v systemctl >/dev/null 2>&1; then
     # The failed install may have started units that were inactive before the
     # attempt. Stop them before restoring files so systemd never keeps running
@@ -928,6 +1085,10 @@ rollback_install_if_needed() {
   if [[ -n "$INSTALL_WORK_DIR" && -d "$INSTALL_WORK_DIR" ]]; then
     rm -rf -- "$INSTALL_WORK_DIR" 2>/dev/null || true
   fi
+  if [[ -n "$INSTALL_UNIT_TMP" && -d "$INSTALL_UNIT_TMP" && ! -L "$INSTALL_UNIT_TMP" ]]; then
+    rm -rf -- "$INSTALL_UNIT_TMP" 2>/dev/null || true
+  fi
+  INSTALL_UNIT_TMP=''
   return "$result"
 }
 
@@ -1077,7 +1238,7 @@ validate_existing_env() {
   mode_bits=$(stat_mode_bits "$file")
   (( (mode_bits & 18) == 0 )) || die '环境文件不能被组或其他用户写入'
   local key key_count
-  for key in TALLYNOTE_INSTALL_PREFIX TALLYNOTE_DATA_DIR TALLYNOTE_HOST TALLYNOTE_PORT TALLYNOTE_PUBLIC_ORIGIN TALLYNOTE_ALLOWED_ORIGINS TALLYNOTE_ALLOW_INSECURE_HTTP TALLYNOTE_COOKIE_SECURE TALLYNOTE_UPDATE_REQUIRE_SIGNATURE TALLYNOTE_UPDATE_METADATA_URL TALLYNOTE_UPDATE_ALLOWED_HOSTS TALLYNOTE_UPDATE_PUBLIC_KEY_FILE; do
+  for key in TALLYNOTE_INSTALL_PREFIX TALLYNOTE_DATA_DIR TALLYNOTE_CONFIG_DIR TALLYNOTE_NODE TALLYNOTE_HOST TALLYNOTE_PORT TALLYNOTE_PUBLIC_ORIGIN TALLYNOTE_ALLOWED_ORIGINS TALLYNOTE_ALLOW_INSECURE_HTTP TALLYNOTE_COOKIE_SECURE TALLYNOTE_UPDATE_REQUIRE_SIGNATURE TALLYNOTE_UPDATE_METADATA_URL TALLYNOTE_UPDATE_ALLOWED_HOSTS TALLYNOTE_UPDATE_PUBLIC_KEY_FILE; do
     key_count=$(env_key_count "$file" "$key")
     [[ "$key_count" =~ ^[0-9]+$ && "$key_count" -le 1 ]] || die "环境文件包含重复配置：$key"
   done
@@ -1085,6 +1246,12 @@ validate_existing_env() {
   [[ -z "$value" || "${value%/}" == "${PREFIX%/}" ]] || die '环境文件中的安装目录与本次安装不一致'
   value=$(read_env_value "$file" TALLYNOTE_DATA_DIR)
   [[ -z "$value" || "${value%/}" == "${DATA_DIR%/}" ]] || die '环境文件中的数据目录与本次安装不一致'
+  value=$(read_env_value "$file" TALLYNOTE_CONFIG_DIR)
+  [[ -z "$value" || "${value%/}" == "${CONFIG_DIR%/}" ]] || die '环境文件中的配置目录与本次安装不一致'
+  value=$(read_env_value "$file" TALLYNOTE_NODE)
+  if [[ -n "$value" ]]; then
+    validate_env_value "$value" '环境文件中的 Node.js 路径'
+  fi
   value=$(read_env_value "$file" TALLYNOTE_UPDATE_REQUIRE_SIGNATURE)
   [[ -z "$value" || "$value" == true || "$value" == false ]] || die '环境文件中的签名校验配置必须是 true 或 false'
   if (( $(env_key_count "$file" TALLYNOTE_HOST) )); then
@@ -1161,6 +1328,7 @@ install_release() {
   safe_extract "$archive" "$tmp/unpacked"
   normalize_release_tree "$tmp/unpacked"
   [[ -d "$tmp/unpacked/dist" ]] || die 'release archive must contain dist/ at its root'
+  [[ ! -e "$tmp/unpacked/runtime" ]] || die 'release archive must not contain an embedded Node.js runtime'
   [[ -x "$tmp/unpacked/bin/tallynote" ]] || die 'release archive must contain executable bin/tallynote'
   [[ -f "$tmp/unpacked/package.json" && -f "$tmp/unpacked/dist/server/index.js" && -f "$tmp/unpacked/dist/server/cli/admin-init.js" && -f "$tmp/unpacked/dist/web/index.html" ]] || die 'release archive is incomplete'
   [[ -f "$tmp/unpacked/systemd/tallynote.service" && -f "$tmp/unpacked/systemd/tallynote-update.service" && -f "$tmp/unpacked/systemd/tallynote-update.path" ]] || die 'release archive is missing systemd units'
@@ -1224,6 +1392,9 @@ main() {
   fi
   detect_platform
   configure_network_interactively
+  if [[ -z "$NODE_PATH" && -f "$CONFIG_DIR/tallynote.env" ]]; then
+    NODE_PATH=$(read_env_value "$CONFIG_DIR/tallynote.env" TALLYNOTE_NODE 2>/dev/null || true)
+  fi
   validate_listen_host "$INSTALL_HOST"
   validate_listen_port "$INSTALL_PORT"
   if (( APPLY && NETWORK_INTERACTIVE )); then
@@ -1310,6 +1481,11 @@ main() {
   for command_name in curl sha256sum tar install sed awk find systemctl; do
     command -v "$command_name" >/dev/null 2>&1 || die "$command_name is required"
   done
+  # Install the cleanup trap before downloading a managed Node.js runtime. A
+  # failed runtime download or extraction must not leave a partial toolchain
+  # behind even when release acquisition has not started yet.
+  trap cleanup_node_install_if_needed EXIT
+  ensure_node_runtime
   if [[ "$REQUIRE_SIGNATURE" == true || -n "$SIGNATURE_URL" || -n "$SIGNING_KEY" || -n "$UPDATE_PUBLIC_KEY_FILE" ]]; then
     command -v "$OPENSSL_BIN" >/dev/null 2>&1 || die 'openssl is required when signature verification is enabled'
   fi
@@ -1394,24 +1570,26 @@ main() {
   [[ -f "$release_dir/systemd/tallynote.env.example" && -f "$release_dir/scripts/tallynote-update-runner.sh" && -x "$release_dir/uninstall.sh" && -x "$release_dir/bin/tallynote-admin-init" && -f "$release_dir/dist/server/cli/admin-init.js" ]] || die 'release package is missing update/uninstall/admin-init support files'
   stage '安装 systemd 单元、更新辅助程序和卸载器'
   install -d -m 755 /usr/local/sbin /usr/local/libexec /etc/systemd/system
-  local unit_tmp
-  unit_tmp=$(mktemp -d)
-  sed "s#/opt/tallynote#$PREFIX#g; s#/var/lib/tallynote#$DATA_DIR#g" "$release_dir/systemd/tallynote.service" > "$unit_tmp/tallynote.service"
-  sed "s#/opt/tallynote#$PREFIX#g; s#/var/lib/tallynote#$DATA_DIR#g; s#/var/lib/tallynote-backups#$(dirname -- "$DATA_DIR")/tallynote-backups#g" "$release_dir/systemd/tallynote-update.service" > "$unit_tmp/tallynote-update.service"
-  sed "s#/opt/tallynote#$PREFIX#g; s#/var/lib/tallynote#$DATA_DIR#g" "$release_dir/systemd/tallynote-update.path" > "$unit_tmp/tallynote-update.path"
-  sed "s#/opt/tallynote#$PREFIX#g; s#/etc/tallynote#$CONFIG_DIR#g" "$release_dir/bin/tallynote-admin-init" > "$unit_tmp/tallynote-admin-init"
-  install -o root -g root -m 644 "$unit_tmp/tallynote.service" /etc/systemd/system/tallynote.service
-  install -o root -g root -m 644 "$unit_tmp/tallynote-update.service" /etc/systemd/system/tallynote-update.service
-  install -o root -g root -m 644 "$unit_tmp/tallynote-update.path" /etc/systemd/system/tallynote-update.path
-  install -o root -g root -m 755 "$unit_tmp/tallynote-admin-init" "$ADMIN_INIT_PATH"
-  rm -rf "$unit_tmp"
-  install -o root -g root -m 755 "$release_dir/scripts/tallynote-update.sh" /usr/local/sbin/tallynote-update
-  install -o root -g root -m 755 "$release_dir/scripts/tallynote-update-runner.sh" /usr/local/libexec/tallynote-update-runner
+  INSTALL_UNIT_TMP=$(mktemp -d)
+  sed "s#/opt/tallynote#$PREFIX#g; s#/var/lib/tallynote#$DATA_DIR#g; s#/etc/tallynote#$CONFIG_DIR#g" "$release_dir/systemd/tallynote.service" > "$INSTALL_UNIT_TMP/tallynote.service"
+  sed "s#/opt/tallynote#$PREFIX#g; s#/var/lib/tallynote-backups#$(dirname -- "$DATA_DIR")/tallynote-backups#g; s#/var/lib/tallynote#$DATA_DIR#g; s#/etc/tallynote#$CONFIG_DIR#g" "$release_dir/systemd/tallynote-update.service" > "$INSTALL_UNIT_TMP/tallynote-update.service"
+  sed "s#/opt/tallynote#$PREFIX#g; s#/var/lib/tallynote#$DATA_DIR#g" "$release_dir/systemd/tallynote-update.path" > "$INSTALL_UNIT_TMP/tallynote-update.path"
+  sed "s#/opt/tallynote#$PREFIX#g; s#/etc/tallynote#$CONFIG_DIR#g" "$release_dir/bin/tallynote-admin-init" > "$INSTALL_UNIT_TMP/tallynote-admin-init"
+  install -o root -g root -m 644 "$INSTALL_UNIT_TMP/tallynote.service" /etc/systemd/system/tallynote.service
+  install -o root -g root -m 644 "$INSTALL_UNIT_TMP/tallynote-update.service" /etc/systemd/system/tallynote-update.service
+  install -o root -g root -m 644 "$INSTALL_UNIT_TMP/tallynote-update.path" /etc/systemd/system/tallynote-update.path
+  install -o root -g root -m 755 "$INSTALL_UNIT_TMP/tallynote-admin-init" "$ADMIN_INIT_PATH"
+  sed "s#/opt/tallynote#$PREFIX#g; s#/var/lib/tallynote#$DATA_DIR#g; s#/etc/tallynote#$CONFIG_DIR#g" "$release_dir/scripts/tallynote-update.sh" > "$INSTALL_UNIT_TMP/tallynote-update.sh"
+  sed "s#/opt/tallynote#$PREFIX#g; s#/var/lib/tallynote#$DATA_DIR#g; s#/etc/tallynote#$CONFIG_DIR#g" "$release_dir/scripts/tallynote-update-runner.sh" > "$INSTALL_UNIT_TMP/tallynote-update-runner.sh"
+  install -o root -g root -m 755 "$INSTALL_UNIT_TMP/tallynote-update.sh" /usr/local/sbin/tallynote-update
+  install -o root -g root -m 755 "$INSTALL_UNIT_TMP/tallynote-update-runner.sh" /usr/local/libexec/tallynote-update-runner
+  rm -rf -- "$INSTALL_UNIT_TMP"
+  INSTALL_UNIT_TMP=''
   install -o root -g root -m 755 "$release_dir/uninstall.sh" /usr/local/sbin/tallynote-uninstall
   ensure_root_directory "$(dirname -- "$DATA_DIR")/tallynote-backups" 700
   local env_created=0
   if [[ ! -f "$CONFIG_DIR/tallynote.env" ]]; then
-    sed "s#/opt/tallynote#$PREFIX#g; s#/var/lib/tallynote#$DATA_DIR#g" "$release_dir/systemd/tallynote.env.example" > "$CONFIG_DIR/tallynote.env"
+    sed "s#/opt/tallynote#$PREFIX#g; s#/var/lib/tallynote#$DATA_DIR#g; s#/etc/tallynote#$CONFIG_DIR#g" "$release_dir/systemd/tallynote.env.example" > "$CONFIG_DIR/tallynote.env"
     chown root:root "$CONFIG_DIR/tallynote.env"
     chmod 640 "$CONFIG_DIR/tallynote.env"
     env_created=1
@@ -1463,6 +1641,11 @@ main() {
   if [[ -n "${TALLYNOTE_ALLOW_INSECURE_HTTP+x}" ]]; then set_env_key TALLYNOTE_ALLOW_INSECURE_HTTP "$INSTALL_ALLOW_INSECURE_HTTP"; fi
   ensure_env_key TALLYNOTE_INSTALL_PREFIX "$PREFIX"
   ensure_env_key TALLYNOTE_DATA_DIR "$DATA_DIR"
+  ensure_env_key TALLYNOTE_CONFIG_DIR "$CONFIG_DIR"
+  configured_node=$(read_env_value "$CONFIG_DIR/tallynote.env" TALLYNOTE_NODE 2>/dev/null || true)
+  if [[ -z "$configured_node" ]] || node_is_legacy_embedded "$configured_node" || ! node_is_usable "$configured_node"; then
+    set_env_key TALLYNOTE_NODE "$NODE_PATH"
+  fi
   ensure_env_key TALLYNOTE_UPDATE_STRATEGY systemd
   ensure_env_key TALLYNOTE_UPDATE_METADATA_URL "$RELEASE_API_URL"
   ensure_env_key TALLYNOTE_UPDATE_ALLOWED_HOSTS "$RELEASE_ALLOWED_HOSTS"
@@ -1538,5 +1721,7 @@ main() {
   fi
   log "访问地址：$access_url"
   log '查看服务状态：systemctl status tallynote.service'
+  log "管理员初始化命令：sudo $ADMIN_INIT_PATH"
+  log '如 sudo 找不到该命令，请使用上面输出的绝对路径'
 }
 main "$@"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "tallynote",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "private": true,
   "type": "module",
   "packageManager": "pnpm@9.0.6",
@@ -29,30 +29,21 @@
     "@fastify/helmet": "^13.0.2",
     "@fastify/multipart": "^9.2.1",
     "@fastify/static": "^10.1.3",
-    "@fontsource-variable/plus-jakarta-sans": "5.3.0",
-    "@reduxjs/toolkit": "2.12.0",
     "archiver": "^8.0.0",
     "argon2": "^0.44.0",
     "better-sqlite3": "^12.2.0",
     "drizzle-orm": "^0.45.2",
-    "echarts": "6.1.0",
-    "echarts-for-react": "3.0.6",
     "exceljs": "^4.4.0",
     "fast-xml-parser": "^5.2.5",
     "fastify": "^5.4.0",
-    "less": "4.4.1",
-    "lucide-react": "^0.542.0",
     "pdf-lib": "^1.17.1",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
-    "react-redux": "9.2.0",
-    "react-router-dom": "7.18.3",
     "sharp": "^0.35.4",
-    "tdesign-react": "1.18.2",
     "yauzl": "^3.2.0",
     "zod": "^4.1.5"
   },
   "devDependencies": {
+    "@fontsource-variable/plus-jakarta-sans": "5.3.0",
+    "@reduxjs/toolkit": "2.12.0",
     "@playwright/test": "^1.55.0",
     "@types/archiver": "^8.0.0",
     "@types/better-sqlite3": "^7.6.13",
@@ -63,6 +54,15 @@
     "@vitejs/plugin-react": "^5.0.2",
     "concurrently": "^9.2.1",
     "drizzle-kit": "^0.31.4",
+    "echarts": "6.1.0",
+    "echarts-for-react": "3.0.6",
+    "less": "4.4.1",
+    "lucide-react": "^0.542.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "react-redux": "9.2.0",
+    "react-router-dom": "7.18.3",
+    "tdesign-react": "1.18.2",
     "tsx": "^4.20.5",
     "typescript": "^5.9.2",
     "vite": "^7.1.3",

pnpm-lock.yaml

@@ -23,12 +23,6 @@ importers:
       '@fastify/static':
         specifier: ^10.1.3
         version: 10.1.3
-      '@fontsource-variable/plus-jakarta-sans':
-        specifier: 5.3.0
-        version: 5.3.0
-      '@reduxjs/toolkit':
-        specifier: 2.12.0
-        version: 2.12.0(react-redux@9.2.0(@types/react@19.2.18)(react@19.2.8)(redux@5.0.1))(react@19.2.8)
       archiver:
         specifier: ^8.0.0
         version: 8.0.0
@@ -41,12 +35,6 @@ importers:
       drizzle-orm:
         specifier: ^0.45.2
         version: 0.45.2(@types/better-sqlite3@7.6.13)(better-sqlite3@12.11.1)
-      echarts:
-        specifier: 6.1.0
-        version: 6.1.0
-      echarts-for-react:
-        specifier: 3.0.6
-        version: 3.0.6(echarts@6.1.0)(react@19.2.8)
       exceljs:
         specifier: ^4.4.0
         version: 4.4.0
@@ -56,33 +44,12 @@ importers:
       fastify:
         specifier: ^5.4.0
         version: 5.12.1
-      less:
-        specifier: 4.4.1
-        version: 4.4.1
-      lucide-react:
-        specifier: ^0.542.0
-        version: 0.542.0(react@19.2.8)
       pdf-lib:
         specifier: ^1.17.1
         version: 1.17.1
-      react:
-        specifier: ^19.1.1
-        version: 19.2.8
-      react-dom:
-        specifier: ^19.1.1
-        version: 19.2.8(react@19.2.8)
-      react-redux:
-        specifier: 9.2.0
-        version: 9.2.0(@types/react@19.2.18)(react@19.2.8)(redux@5.0.1)
-      react-router-dom:
-        specifier: 7.18.3
-        version: 7.18.3(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
       sharp:
         specifier: ^0.35.4
         version: 0.35.4(@types/node@24.13.3)
-      tdesign-react:
-        specifier: 1.18.2
-        version: 1.18.2(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
       yauzl:
         specifier: ^3.2.0
         version: 3.4.0
@@ -90,9 +57,15 @@ importers:
         specifier: ^4.1.5
         version: 4.4.3
     devDependencies:
+      '@fontsource-variable/plus-jakarta-sans':
+        specifier: 5.3.0
+        version: 5.3.0
       '@playwright/test':
         specifier: ^1.55.0
         version: 1.62.1
+      '@reduxjs/toolkit':
+        specifier: 2.12.0
+        version: 2.12.0(react-redux@9.2.0(@types/react@19.2.18)(react@19.2.8)(redux@5.0.1))(react@19.2.8)
       '@types/archiver':
         specifier: ^8.0.0
         version: 8.0.0
@@ -120,6 +93,33 @@ importers:
       drizzle-kit:
         specifier: ^0.31.4
         version: 0.31.10
+      echarts:
+        specifier: 6.1.0
+        version: 6.1.0
+      echarts-for-react:
+        specifier: 3.0.6
+        version: 3.0.6(echarts@6.1.0)(react@19.2.8)
+      less:
+        specifier: 4.4.1
+        version: 4.4.1
+      lucide-react:
+        specifier: ^0.542.0
+        version: 0.542.0(react@19.2.8)
+      react:
+        specifier: ^19.1.1
+        version: 19.2.8
+      react-dom:
+        specifier: ^19.1.1
+        version: 19.2.8(react@19.2.8)
+      react-redux:
+        specifier: 9.2.0
+        version: 9.2.0(@types/react@19.2.18)(react@19.2.8)(redux@5.0.1)
+      react-router-dom:
+        specifier: 7.18.3
+        version: 7.18.3(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+      tdesign-react:
+        specifier: 1.18.2
+        version: 1.18.2(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
       tsx:
         specifier: ^4.20.5
         version: 4.23.12

scripts/build-release.sh

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
 set -Eeuo pipefail
 
-# Build a self-contained release on the target Linux architecture. Native
-# addons (SQLite, Argon2 and image processing) must be installed on the same
-# architecture/libc as the artifact.
+# Build a production release on the target Linux architecture. Native addons
+# (SQLite, Argon2 and image processing) must be installed on the same
+# architecture/libc as the artifact. Node.js itself is deliberately managed
+# by the installer outside each release so application updates stay small.
 ROOT=$(cd -- "$(dirname -- "$0")/.." && pwd -P)
 VERSION=${1:-}
 OUT_DIR=${2:-$ROOT/release}
@@ -28,7 +29,7 @@ cd "$ROOT"
 pnpm build
 stage=$(mktemp -d)
 trap 'rm -rf "$stage"' EXIT
-mkdir -p "$stage/dist" "$stage/migrations" "$stage/bin" "$stage/scripts" "$stage/systemd" "$stage/runtime/bin"
+mkdir -p "$stage/dist" "$stage/migrations" "$stage/bin" "$stage/scripts" "$stage/systemd"
 # Copy only the production build outputs. In particular, do not carry a
 # stale dist/web-next directory from a previous local preview build.
 cp -a dist/server "$stage/dist/"
@@ -40,9 +41,7 @@ cp -a bin/. "$stage/bin/"
 cp -a scripts/tallynote-update.sh scripts/tallynote-update-runner.sh "$stage/scripts/"
 cp uninstall.sh "$stage/uninstall.sh"
 cp -a systemd/tallynote.service systemd/tallynote-update.service systemd/tallynote-update.path systemd/tallynote.env.example "$stage/systemd/"
-node_path=$(command -v node)
-cp -L "$node_path" "$stage/runtime/bin/node"
-chmod 755 "$stage/bin/tallynote" "$stage/bin/tallynote-admin-init" "$stage/scripts"/*.sh "$stage/runtime/bin/node" "$stage/uninstall.sh"
+chmod 755 "$stage/bin/tallynote" "$stage/bin/tallynote-admin-init" "$stage/scripts"/*.sh "$stage/uninstall.sh"
 
 # pnpm's default linker creates symlinks. A release archive is deliberately
 # symlink-free so the installer can reject traversal links deterministically.

scripts/publish-gitea-release.sh

@@ -5,7 +5,7 @@ set -Eeuo pipefail
 # always generated; an Ed25519 detached signature is added when a signing key
 # is supplied. The script remains separate from the workflow so operators can
 # dry-run the exact same asset selection locally without exposing a key.
-PATH=/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/bin
+PATH=/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin
 export PATH
 umask 077
 
@@ -205,7 +205,6 @@ fi
 command -v "$CURL_BIN" >/dev/null 2>&1 || die 'curl is required'
 
 full_assets=()
-update_assets=()
 for file in "$ASSET_DIR"/*.tar.gz; do
   [[ -f "$file" && ! -L "$file" ]] || continue
   name=$(basename -- "$file")
@@ -214,13 +213,11 @@ for file in "$ASSET_DIR"/*.tar.gz; do
   asset_version=${asset_version%%-linux-*}
   [[ "$asset_version" == "${TAG#v}" ]] || die "release asset version does not match tag: $name"
   if [[ "$name" =~ \.update-[a-f0-9]{64}\.tar\.gz$ ]]; then
-    update_assets+=("$file")
-  else
-    full_assets+=("$file")
+    die "不再发布轻量更新资产：$name；请只保留完整生产包"
   fi
+  full_assets+=("$file")
 done
 assets=("${full_assets[@]}")
-if ((${#update_assets[@]})); then assets+=("${update_assets[@]}"); fi
 (( ${#assets[@]} > 0 )) || die 'no .tar.gz release asset found'
 (( ${#full_assets[@]} > 0 )) || die 'no full release asset found'
 

scripts/tallynote-update-runner.sh

@@ -1,15 +1,19 @@
 #!/usr/bin/env bash
 set -Eeuo pipefail
 
-PATH=/usr/sbin:/usr/bin:/sbin:/bin
+PATH=/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin
 export PATH
 umask 077
 
 PREFIX=${TALLYNOTE_INSTALL_PREFIX:-/opt/tallynote}
 DATA_DIR=${TALLYNOTE_DATA_DIR:-/var/lib/tallynote}
+CONFIG_DIR=${TALLYNOTE_CONFIG_DIR:-/etc/tallynote}
+CONFIG_FILE="$CONFIG_DIR/tallynote.env"
 REQUEST_FILE="$DATA_DIR/update-request.json"
 CURRENT_LINK="$PREFIX/current"
 STATE_FILE="$PREFIX/.update-state"
+LOCK_FILE="$PREFIX/.update-runner.lock"
+RUNNER_LOG="$PREFIX/.update-runner.log"
 SERVICE_NAME=${TALLYNOTE_SERVICE_NAME:-tallynote.service}
 HOST=${TALLYNOTE_HOST:-127.0.0.1}
 PORT=${TALLYNOTE_PORT:-3000}
@@ -19,13 +23,93 @@ if [[ "$HEALTH_HOST" == :: ]]; then HEALTH_HOST=::1; fi
 if [[ "$HEALTH_HOST" == *:* && "$HEALTH_HOST" != \[* ]]; then HEALTH_HOST="[$HEALTH_HOST]"; fi
 
 die() { printf 'tallynote update runner: %s\n' "$*" >&2; exit 1; }
+
+node_is_usable() {
+  local candidate=$1 major
+  [[ -n "$candidate" && -x "$candidate" ]] || return 1
+  major=$("$candidate" -p 'process.versions.node.split(".")[0]' 2>/dev/null || true)
+  [[ "$major" =~ ^[0-9]+$ && "$major" -ge 24 ]]
+}
+
+resolve_node() {
+  local candidate=${TALLYNOTE_NODE:-}
+  if [[ -z "$candidate" && -f "$CONFIG_FILE" && ! -L "$CONFIG_FILE" ]]; then
+    candidate=$(sed -n 's/^TALLYNOTE_NODE=//p' "$CONFIG_FILE" | head -n 1)
+  fi
+  if node_is_usable "$candidate"; then
+    printf '%s' "$candidate"
+    return 0
+  fi
+  candidate=$(command -v node || true)
+  node_is_usable "$candidate" || return 1
+  printf '%s' "$candidate"
+}
+
+# The runner may exit during any of the checks below. Install its EXIT cleanup
+# before doing privileged preflight so a partial invocation never leaves a
+# heartbeat or lock behind.
+STATE_CREATED=0
+heartbeat_pid=''
+heartbeat_owner=$$
+RUNNER_LOCK_FD=9
+RUNNER_LOCK_MODE=''
+stop_heartbeat() {
+  if [[ -n "$heartbeat_pid" ]]; then
+    kill "$heartbeat_pid" 2>/dev/null || true
+    wait "$heartbeat_pid" 2>/dev/null || true
+    heartbeat_pid=''
+  fi
+}
+# shellcheck disable=SC2329 # invoked indirectly by the EXIT trap
+release_runner_lock() {
+  if [[ "$RUNNER_LOCK_MODE" == flock ]]; then
+    flock -u "$RUNNER_LOCK_FD" 2>/dev/null || true
+    eval "exec ${RUNNER_LOCK_FD}>&-" 2>/dev/null || true
+  elif [[ "$RUNNER_LOCK_MODE" == mkdir ]]; then
+    rmdir -- "$LOCK_FILE.d" 2>/dev/null || true
+  fi
+}
+# shellcheck disable=SC2329 # invoked indirectly by the EXIT trap
+early_cleanup() {
+  local result=$?
+  stop_heartbeat
+  if (( result != 0 )); then
+    # A preflight failure happens before the normal phase-specific trap is
+    # installed. Remove only the one-shot request marker; never remove an
+    # existing recovery marker unless this invocation created it.
+    rm -f -- "$REQUEST_FILE" 2>/dev/null || true
+    if (( STATE_CREATED == 1 )); then rm -f -- "$STATE_FILE" 2>/dev/null || true; fi
+  fi
+  release_runner_lock
+  return "$result"
+}
+trap early_cleanup EXIT
+
 [[ ${EUID:-$(id -u)} -eq 0 ]] || die 'must run as root'
+[[ -d "$PREFIX" ]] || die 'install prefix is missing'
+if command -v flock >/dev/null 2>&1; then
+  exec 9>"$LOCK_FILE" || die '无法打开更新运行锁'
+  flock -n "$RUNNER_LOCK_FD" || exit 0
+  RUNNER_LOCK_MODE=flock
+else
+  # macOS development fixtures do not ship util-linux; retain an atomic lock
+  # fallback there while Linux production uses flock above.
+  mkdir "$LOCK_FILE.d" 2>/dev/null || exit 0
+  RUNNER_LOCK_MODE='mkdir'
+fi
 [[ -f "$REQUEST_FILE" || -f "$STATE_FILE" ]] || exit 0
 [[ -L "$CURRENT_LINK" ]] || die 'current release link is missing'
 
 old_target=$(readlink -f -- "$CURRENT_LINK")
 [[ "$old_target" == "$PREFIX/releases/"* && -d "$old_target" ]] || die 'current release target is invalid'
 
+# Capture the service state before any download/apply work. The value is
+# persisted in the recovery marker so a later runner process can restore the
+# operator's original state after a crash (the service is normally inactive by
+# the time recovery starts).
+was_active=0
+if systemctl is-active --quiet "$SERVICE_NAME"; then was_active=1; fi
+
 request_operation='apply'
 if [[ -f "$REQUEST_FILE" && ! -L "$REQUEST_FILE" ]]; then
   request_operation=$(sed -n 's/.*"operation"[[:space:]]*:[[:space:]]*"\(download\|apply\)".*/\1/p' "$REQUEST_FILE" | head -n 1)
@@ -39,15 +123,11 @@ job_id=''
 if [[ -f "$REQUEST_FILE" && ! -L "$REQUEST_FILE" ]]; then
   job_id=$(sed -n 's/.*"jobId"[[:space:]]*:[[:space:]]*"\([0-9a-f-]*\)".*/\1/p' "$REQUEST_FILE" | head -n 1)
 fi
-STATE_CREATED=0
-heartbeat_pid=''
-heartbeat_owner=$$
-
 write_recovery_state() {
   local phase=$1 temporary
   temporary="$PREFIX/.update-state-$$-${RANDOM}.tmp"
   [[ ! -e "$temporary" && ! -L "$temporary" ]] || return 1
-  printf 'job_id=%s\nold_target=%s\nphase=%s\n' "$job_id" "$old_target" "$phase" > "$temporary"
+  printf 'job_id=%s\nold_target=%s\nphase=%s\ninitial_active=%s\n' "$job_id" "$old_target" "$phase" "$was_active" > "$temporary"
   chmod 600 "$temporary"
   mv -Tf -- "$temporary" "$STATE_FILE"
   STATE_CREATED=1
@@ -59,14 +139,6 @@ clear_recovery_state() {
   STATE_CREATED=0
 }
 
-stop_heartbeat() {
-  if [[ -n "$heartbeat_pid" ]]; then
-    kill "$heartbeat_pid" 2>/dev/null || true
-    wait "$heartbeat_pid" 2>/dev/null || true
-    heartbeat_pid=''
-  fi
-}
-
 heartbeat() {
   # Keep the lease fresh during long downloads/backups, but stop on a hard
   # runner kill so an orphaned child cannot keep the recovery marker alive.
@@ -86,9 +158,11 @@ start_heartbeat() {
 # This trap covers failures before the normal apply cleanup trap is installed,
 # including a missing runtime, an invalid current link, and a failed service
 # stop. It deliberately does not remove a pre-existing recovery marker.
+# shellcheck disable=SC2329 # invoked indirectly by the EXIT trap
 preflight_cleanup() {
   local result=$?
   stop_heartbeat
+  release_runner_lock
   if (( result != 0 )); then
     rm -f -- "$REQUEST_FILE" 2>/dev/null || true
     if (( STATE_CREATED == 1 )); then clear_recovery_state || true; fi
@@ -97,6 +171,33 @@ preflight_cleanup() {
 }
 trap preflight_cleanup EXIT
 
+DOWNLOAD_TIMEOUT_SECONDS=${TALLYNOTE_UPDATE_DOWNLOAD_TIMEOUT_SECONDS:-${TALLYNOTE_UPDATE_RUNNER_DOWNLOAD_TIMEOUT_SECONDS:-1800}}
+APPLY_TIMEOUT_SECONDS=${TALLYNOTE_UPDATE_APPLY_TIMEOUT_SECONDS:-${TALLYNOTE_UPDATE_RUNNER_APPLY_TIMEOUT_SECONDS:-1800}}
+FINALIZE_TIMEOUT_SECONDS=${TALLYNOTE_UPDATE_FINALIZE_TIMEOUT_SECONDS:-${TALLYNOTE_UPDATE_RUNNER_FINALIZE_TIMEOUT_SECONDS:-30}}
+TIMEOUT_BIN=$(command -v timeout || true)
+
+run_update_cli() {
+  local node=$1 timeout_seconds=$2 label=$3 result
+  shift 3
+  [[ "$timeout_seconds" =~ ^[1-9][0-9]*$ ]] || die "${label} timeout must be a positive integer"
+  {
+    printf '\n[%s] %s (timeout=%ss)\ncommand:' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$label" "$timeout_seconds"
+    printf ' %q' "$node" "$CURRENT_LINK/dist/server/cli/update.js" "$@"
+    printf '\n'
+  } >>"$RUNNER_LOG"
+  if [[ -n "$TIMEOUT_BIN" ]]; then
+    "$TIMEOUT_BIN" --foreground --signal=TERM --kill-after=10s "${timeout_seconds}s" \
+      "$node" "$CURRENT_LINK/dist/server/cli/update.js" "$@" >>"$RUNNER_LOG" 2>&1
+    result=$?
+  elif "$node" "$CURRENT_LINK/dist/server/cli/update.js" "$@" >>"$RUNNER_LOG" 2>&1; then
+    result=0
+  else
+    result=$?
+  fi
+  printf '[%s] %s exited with status %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$label" "$result" >>"$RUNNER_LOG"
+  return "$result"
+}
+
 # Downloading is intentionally handled while the main service remains up.
 # The CLI persists the validated payload under the root-owned workspace and
 # leaves the job staged for a later apply request.
@@ -107,6 +208,7 @@ if [[ "$request_operation" == download ]]; then
     clear_recovery_state || die '无法清理上一次下载状态'
   fi
   write_recovery_state download || die '无法写入更新恢复状态'
+# shellcheck disable=SC2329 # invoked indirectly by the EXIT trap
   cleanup_download() {
     local result=$?
     stop_heartbeat
@@ -116,19 +218,18 @@ if [[ "$request_operation" == download ]]; then
       rm -f -- "$REQUEST_FILE" 2>/dev/null || true
     fi
     clear_recovery_state || true
+    release_runner_lock
     return "$result"
   }
   trap cleanup_download EXIT
   trap 'exit 143' TERM
   trap 'exit 130' INT
   start_heartbeat
-  node_bin="$CURRENT_LINK/runtime/bin/node"
-  [[ -x "$node_bin" ]] || node_bin=$(command -v node || true)
-  [[ -n "$node_bin" ]] || die 'node runtime not found'
+  node_bin=$(resolve_node) || die 'Node.js 24+ not found'
   cli="$CURRENT_LINK/dist/server/cli/update.js"
   [[ -f "$cli" ]] || die 'update CLI not found in current release'
   set +e
-  "$node_bin" "$cli" --request-file "$REQUEST_FILE"
+  run_update_cli "$node_bin" "$DOWNLOAD_TIMEOUT_SECONDS" download --request-file "$REQUEST_FILE"
   download_result=$?
   set -e
   if (( download_result != 0 )); then
@@ -139,7 +240,7 @@ if [[ "$request_operation" == download ]]; then
     download_job_id=$(sed -n 's/.*"jobId"[[:space:]]*:[[:space:]]*"\([0-9a-f-]*\)".*/\1/p' "$REQUEST_FILE" | head -n 1)
     if [[ "$download_job_id" =~ ^[0-9a-f-]{36}$ ]]; then
       for _ in 1 2 3; do
-        if "$node_bin" "$cli" --finalize-job "$download_job_id" --finalize-status failed --message '更新下载失败' >/dev/null 2>&1; then break; fi
+        if run_update_cli "$node_bin" "$FINALIZE_TIMEOUT_SECONDS" finalize-download --finalize-job "$download_job_id" --finalize-status failed --message '更新下载失败'; then break; fi
         sleep 1
       done
     fi
@@ -150,12 +251,11 @@ if [[ "$request_operation" == download ]]; then
   exit 0
 fi
 
-was_active=0
-if systemctl is-active --quiet "$SERVICE_NAME"; then was_active=1; fi
 # shellcheck disable=SC2329 # invoked indirectly by the EXIT trap below
 restore_initial_service() {
   local result=$?
   stop_heartbeat
+  release_runner_lock
   if (( result != 0 )); then
     rm -f -- "$REQUEST_FILE" 2>/dev/null || true
     if (( STATE_CREATED == 1 )); then clear_recovery_state || true; fi
@@ -164,8 +264,7 @@ restore_initial_service() {
   return "$result"
 }
 trap restore_initial_service EXIT
-old_node="$CURRENT_LINK/runtime/bin/node"
-[[ -x "$old_node" ]] || old_node=$(command -v node || true)
+old_node=$(resolve_node) || die 'Node.js 24+ not found'
 handled=0
 
 write_update_state() { write_recovery_state "$1"; }
@@ -175,11 +274,11 @@ finalize_state_job() {
   local node=$1 status=$2 state_job=$3
   [[ "$state_job" =~ ^[0-9a-f-]{36}$ && -n "$node" ]] || return 1
   [[ -f "$CURRENT_LINK/dist/server/cli/update.js" ]] || return 1
-  "$node" "$CURRENT_LINK/dist/server/cli/update.js" --finalize-job "$state_job" --finalize-status "$status" --message '新版本健康检查失败，已恢复上一版本' >/dev/null 2>&1
+  run_update_cli "$node" "$FINALIZE_TIMEOUT_SECONDS" finalize-recovery --finalize-job "$state_job" --finalize-status "$status" --message '新版本健康检查失败，已恢复上一版本'
 }
 
 recover_stale_state() {
-  local state_job state_old state_phase current_target recovery_node rollback_link state_mode state_uid
+  local state_job state_old state_phase state_initial_active current_target recovery_node rollback_link state_mode state_uid
   [[ -f "$STATE_FILE" && ! -L "$STATE_FILE" ]] || die 'update state file is invalid'
   state_uid=$(stat -c '%u' "$STATE_FILE" 2>/dev/null || stat -f '%u' "$STATE_FILE")
   state_mode=$(stat -c '%a' "$STATE_FILE" 2>/dev/null || stat -f '%Lp' "$STATE_FILE")
@@ -187,8 +286,16 @@ recover_stale_state() {
   state_job=$(sed -n 's/^job_id=//p' "$STATE_FILE" | head -n 1)
   state_old=$(sed -n 's/^old_target=//p' "$STATE_FILE" | head -n 1)
   state_phase=$(sed -n 's/^phase=//p' "$STATE_FILE" | head -n 1)
+  state_initial_active=$(sed -n 's/^initial_active=//p' "$STATE_FILE" | head -n 1)
   [[ "$state_job" =~ ^[0-9a-f-]{36}$ ]] || die 'update state job id is invalid'
   [[ "$state_old" == "$PREFIX/releases/"* && -d "$state_old" && ! -L "$state_old" ]] || die 'update state target is invalid'
+  if [[ -z "$state_initial_active" ]]; then
+    # Markers from older releases did not persist this field. Preserve their
+    # historical conservative behavior instead of rejecting recovery.
+    state_initial_active=0
+  fi
+  [[ "$state_initial_active" == 0 || "$state_initial_active" == 1 ]] || die 'update state initial service state is invalid'
+  was_active=$state_initial_active
   current_target=$(readlink -f -- "$CURRENT_LINK" 2>/dev/null || true)
   if [[ "$state_phase" == download && "$current_target" == "$state_old" ]]; then
     # Downloading never changes the active release. If the runner was killed
@@ -200,8 +307,7 @@ recover_stale_state() {
     return 0
   fi
   if [[ "$state_phase" == finalizing && "$current_target" != "$state_old" ]]; then
-    recovery_node="$CURRENT_LINK/runtime/bin/node"
-    [[ -x "$recovery_node" ]] || recovery_node=$(command -v node || true)
+    recovery_node=$(resolve_node) || die 'Node.js 24+ not found'
     for _ in 1 2 3; do
       if finalize_state_job "$recovery_node" completed "$state_job"; then
         rm -f -- "$REQUEST_FILE" 2>/dev/null || true
@@ -217,8 +323,7 @@ recover_stale_state() {
     # that case the old link is already safe to serve, but the database row
     # can still be `applying`; finish it as failed before clearing recovery
     # markers so the UI does not poll forever.
-    recovery_node="$CURRENT_LINK/runtime/bin/node"
-    [[ -x "$recovery_node" ]] || recovery_node=$(command -v node || true)
+    recovery_node=$(resolve_node) || die 'Node.js 24+ not found'
     if finalize_state_job "$recovery_node" failed "$state_job"; then
       rm -f -- "$REQUEST_FILE" 2>/dev/null || true
       clear_update_state || true
@@ -241,8 +346,7 @@ recover_stale_state() {
       rm -f -- "$rollback_link" 2>/dev/null || true
       return 1
     fi
-    recovery_node="$CURRENT_LINK/runtime/bin/node"
-    [[ -x "$recovery_node" ]] || recovery_node=$(command -v node || true)
+    recovery_node=$(resolve_node) || die 'Node.js 24+ not found'
     if ! finalize_state_job "$recovery_node" failed "$state_job"; then
       # If the original queue is still present, retry it from the restored old
       # release; a crash before the CLI wrote its job row is recoverable this
@@ -312,7 +416,7 @@ finalize_failed_job() {
   # Give SQLite a moment to release a transient lock before declaring the
   # recovery itself failed.
   for _ in 1 2 3; do
-    if "$old_node" "$CURRENT_LINK/dist/server/cli/update.js" --finalize-job "$job_id" --finalize-status failed --message '新版本健康检查失败，已恢复上一版本' >/dev/null 2>&1; then
+    if run_update_cli "$old_node" "$FINALIZE_TIMEOUT_SECONDS" finalize-failed --finalize-job "$job_id" --finalize-status failed --message '新版本健康检查失败，已恢复上一版本'; then
       return 0
     fi
     sleep 1
@@ -323,7 +427,7 @@ finalize_failed_job() {
 finalize_completed_job() {
   [[ "$job_id" =~ ^[0-9a-f-]{36}$ ]] || return 0
   [[ -n "$final_node" ]] || return 1
-  "$final_node" "$CURRENT_LINK/dist/server/cli/update.js" --finalize-job "$job_id" --finalize-status completed >/dev/null 2>&1
+  run_update_cli "$final_node" "$FINALIZE_TIMEOUT_SECONDS" finalize-completed --finalize-job "$job_id" --finalize-status completed
 }
 
 # shellcheck disable=SC2329 # invoked indirectly by the EXIT trap below
@@ -347,18 +451,17 @@ cleanup_after_update() {
   else
     systemctl stop "$SERVICE_NAME" || true
   fi
+  release_runner_lock
   return "$result"
 }
 trap cleanup_after_update EXIT
 
-node_bin="$CURRENT_LINK/runtime/bin/node"
-[[ -x "$node_bin" ]] || node_bin=$(command -v node || true)
-[[ -n "$node_bin" ]] || die 'node runtime not found'
+node_bin=$(resolve_node) || die 'Node.js 24+ not found'
 cli="$CURRENT_LINK/dist/server/cli/update.js"
 [[ -f "$cli" ]] || die 'update CLI not found in current release'
 
 set +e
-"$node_bin" "$cli" --request-file "$REQUEST_FILE" --defer-completion
+run_update_cli "$node_bin" "$APPLY_TIMEOUT_SECONDS" apply --request-file "$REQUEST_FILE" --defer-completion
 update_result=$?
 set -e
 if (( update_result != 0 )); then
@@ -395,8 +498,7 @@ if (( was_active == 0 )); then
 fi
 
 write_update_state finalizing || exit 1
-final_node="$CURRENT_LINK/runtime/bin/node"
-[[ -x "$final_node" ]] || final_node=$(command -v node || true)
+final_node=$(resolve_node) || die 'Node.js 24+ not found'
 if [[ "$job_id" =~ ^[0-9a-f-]{36}$ ]]; then
   finalized=0
   for _ in 1 2 3; do

scripts/tallynote-update.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -Eeuo pipefail
 
-PATH=/usr/sbin:/usr/bin:/sbin:/bin
+PATH=/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin
 export PATH
 umask 077
 
@@ -10,9 +10,22 @@ umask 077
 # extraction and atomic release switching.
 PREFIX=${TALLYNOTE_INSTALL_PREFIX:-${TALLYNOTE_PREFIX:-/opt/tallynote}}
 DATA_DIR=${TALLYNOTE_DATA_DIR:-/var/lib/tallynote}
+CONFIG_DIR=${TALLYNOTE_CONFIG_DIR:-/etc/tallynote}
+CONFIG_FILE="$CONFIG_DIR/tallynote.env"
 REQUEST_FILE=${TALLYNOTE_UPDATE_REQUEST_FILE:-$DATA_DIR/update-request.json}
 NODE=${TALLYNOTE_NODE:-}
 
+node_is_usable() {
+  local candidate=$1 major
+  [[ -n "$candidate" && -x "$candidate" ]] || return 1
+  major=$("$candidate" -p 'process.versions.node.split(".")[0]' 2>/dev/null || true)
+  [[ "$major" =~ ^[0-9]+$ && "$major" -ge 24 ]]
+}
+
+if [[ -z "$NODE" && -f "$CONFIG_FILE" && ! -L "$CONFIG_FILE" ]]; then
+  NODE=$(sed -n 's/^TALLYNOTE_NODE=//p' "$CONFIG_FILE" | head -n 1)
+fi
+
 die() { printf 'tallynote update: %s\n' "$*" >&2; exit 1; }
 version_sort_desc() {
   if sort -V </dev/null >/dev/null 2>&1; then
@@ -71,10 +84,9 @@ if [[ -x /usr/local/libexec/tallynote-update-runner ]]; then
   exec /usr/local/libexec/tallynote-update-runner
 fi
 if [[ -z "$NODE" ]]; then
-  NODE="$PREFIX/current/runtime/bin/node"
-  [[ -x "$NODE" ]] || NODE=$(command -v node || true)
+  NODE=$(command -v node || true)
 fi
-[[ -n "$NODE" ]] || die 'node runtime not found'
+node_is_usable "$NODE" || die 'Node.js 24+ not found'
 CLI="$PREFIX/current/dist/server/cli/update.js"
 [[ -f "$CLI" ]] || die 'update CLI not found'
 

scripts/test-installer.sh

@@ -173,23 +173,23 @@ runner_root="$tmp/runner"
 runner_prefix="$runner_root/prefix"
 runner_data="$runner_root/data"
 runner_tools="$runner_root/tools"
-mkdir -p "$runner_prefix/releases/1.0.0/runtime/bin" "$runner_prefix/releases/1.0.0/dist/server/cli" "$runner_data" "$runner_tools"
+mkdir -p "$runner_prefix/releases/1.0.0/dist/server/cli" "$runner_data" "$runner_tools"
 ln -s "$runner_prefix/releases/1.0.0" "$runner_prefix/current"
 printf '%s\n' '{"jobId":"00000000-0000-4000-8000-000000000001","operation":"apply"}' > "$runner_data/update-request.json"
-printf '%s\n' '#!/usr/bin/env bash' 'printf "%s\\n" "$*" >> "$TALLYNOTE_NODE_TRACE"' 'exit 0' > "$runner_prefix/releases/1.0.0/runtime/bin/node"
+printf '%s\n' '#!/usr/bin/env bash' 'if [[ "${1:-}" == "-p" ]]; then printf "%s\n" "24"; else printf "%s\n" "$*" >> "$TALLYNOTE_NODE_TRACE"; fi' 'exit 0' > "$runner_tools/node"
 printf '%s\n' cli > "$runner_prefix/releases/1.0.0/dist/server/cli/update.js"
 printf '%s\n' '#!/usr/bin/env bash' 'case "${1:-}" in is-active) exit 0;; *) exit 0;; esac' > "$runner_tools/systemctl"
 printf '%s\n' '#!/usr/bin/env bash' 'if [[ "${1:-}" == "-f" ]]; then shift; [[ "${1:-}" == "--" ]] && shift; /bin/realpath "$1"; else /usr/bin/readlink "$@"; fi' > "$runner_tools/readlink"
 printf '%s\n' '#!/usr/bin/env bash' 'if [[ "${1:-}" == "-Tf" ]]; then shift; /bin/mv -f "$@"; else /bin/mv "$@"; fi' > "$runner_tools/mv"
 printf '%s\n' '#!/usr/bin/env bash' 'exit 0' > "$runner_tools/curl"
-chmod 755 "$runner_prefix/releases/1.0.0/runtime/bin/node" "$runner_tools/systemctl" "$runner_tools/readlink" "$runner_tools/mv" "$runner_tools/curl"
+chmod 755 "$runner_tools/node" "$runner_tools/systemctl" "$runner_tools/readlink" "$runner_tools/mv" "$runner_tools/curl"
 runner_script="$runner_root/runner.sh"
 runner_path="$runner_tools:/usr/sbin:/usr/bin:/sbin:/bin"
-sed "s#PATH=/usr/sbin:/usr/bin:/sbin:/bin#PATH=$runner_path#" "$root/scripts/tallynote-update-runner.sh" > "$runner_script"
+sed "s#PATH=/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin#PATH=$runner_path#" "$root/scripts/tallynote-update-runner.sh" > "$runner_script"
 chmod 755 "$runner_script"
 runner_prefix_physical=$(cd "$runner_prefix" && pwd -P)
 runner_data_physical=$(cd "$runner_data" && pwd -P)
-env EUID=0 TALLYNOTE_INSTALL_PREFIX="$runner_prefix_physical" TALLYNOTE_DATA_DIR="$runner_data_physical" TALLYNOTE_NODE_TRACE="$runner_root/node.log" bash "$runner_script"
+env EUID=0 TALLYNOTE_INSTALL_PREFIX="$runner_prefix_physical" TALLYNOTE_DATA_DIR="$runner_data_physical" TALLYNOTE_NODE="$runner_tools/node" TALLYNOTE_NODE_TRACE="$runner_root/node.log" bash "$runner_script"
 grep -q -- '--request-file' "$runner_root/node.log"
 grep -q -- '--finalize-job' "$runner_root/node.log"
 [[ ! -e "$runner_data/update-request.json" ]]
@@ -202,14 +202,14 @@ download_runner_root="$tmp/download-runner"
 download_runner_prefix="$download_runner_root/prefix"
 download_runner_data="$download_runner_root/data"
 download_runner_tools="$download_runner_root/tools"
-mkdir -p "$download_runner_prefix/releases/1.0.0/runtime/bin" "$download_runner_prefix/releases/1.0.0/dist/server/cli" "$download_runner_data" "$download_runner_tools"
+mkdir -p "$download_runner_prefix/releases/1.0.0/dist/server/cli" "$download_runner_data" "$download_runner_tools"
 ln -s "$download_runner_prefix/releases/1.0.0" "$download_runner_prefix/current"
 # The request has already been consumed; only the stale download marker is
 # left, which is the narrow recovery window covered by this fixture.
 download_runner_prefix_physical=$(cd "$download_runner_prefix" && pwd -P)
 download_runner_data_physical=$(cd "$download_runner_data" && pwd -P)
 printf '%s\n' 'job_id=00000000-0000-4000-8000-000000000002' "old_target=$download_runner_prefix_physical/releases/1.0.0" 'phase=download' > "$download_runner_prefix/.update-state"
-printf '%s\n' '#!/usr/bin/env bash' 'printf "%s\n" "$*" >> "$TALLYNOTE_DOWNLOAD_NODE_TRACE"' 'exit 0' > "$download_runner_prefix/releases/1.0.0/runtime/bin/node"
+printf '%s\n' '#!/usr/bin/env bash' 'if [[ "${1:-}" == "-p" ]]; then printf "%s\n" "24"; else printf "%s\n" "$*" >> "$TALLYNOTE_DOWNLOAD_NODE_TRACE"; fi' 'exit 0' > "$download_runner_tools/node"
 printf '%s\n' cli > "$download_runner_prefix/releases/1.0.0/dist/server/cli/update.js"
 printf '%s\n' '#!/usr/bin/env bash' 'case "${1:-}" in is-active) exit 0;; *) exit 0;; esac' > "$download_runner_tools/systemctl"
 printf '%s\n' '#!/usr/bin/env bash' 'if [[ "${1:-}" == "-f" ]]; then shift; [[ "${1:-}" == "--" ]] && shift; /bin/realpath "$1"; else /usr/bin/readlink "$@"; fi' > "$download_runner_tools/readlink"
@@ -221,11 +221,11 @@ case "$*" in
   *) /usr/bin/stat "$@" ;;
 esac
 EOF
-chmod 755 "$download_runner_prefix/releases/1.0.0/runtime/bin/node" "$download_runner_tools/systemctl" "$download_runner_tools/readlink" "$download_runner_tools/stat"
+chmod 755 "$download_runner_tools/node" "$download_runner_tools/systemctl" "$download_runner_tools/readlink" "$download_runner_tools/stat"
 download_runner_script="$download_runner_root/runner.sh"
-sed "s#PATH=/usr/sbin:/usr/bin:/sbin:/bin#PATH=$download_runner_tools:/usr/sbin:/usr/bin:/sbin:/bin#" "$root/scripts/tallynote-update-runner.sh" > "$download_runner_script"
+sed "s#PATH=/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin#PATH=$download_runner_tools:/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin#" "$root/scripts/tallynote-update-runner.sh" > "$download_runner_script"
 chmod 755 "$download_runner_script"
-env EUID=0 TALLYNOTE_INSTALL_PREFIX="$download_runner_prefix_physical" TALLYNOTE_DATA_DIR="$download_runner_data_physical" TALLYNOTE_DOWNLOAD_NODE_TRACE="$download_runner_root/node.log" bash "$download_runner_script"
+env EUID=0 TALLYNOTE_INSTALL_PREFIX="$download_runner_prefix_physical" TALLYNOTE_DATA_DIR="$download_runner_data_physical" TALLYNOTE_NODE="$download_runner_tools/node" TALLYNOTE_DOWNLOAD_NODE_TRACE="$download_runner_root/node.log" bash "$download_runner_script"
 [[ ! -e "$download_runner_root/node.log" ]]
 [[ ! -e "$download_runner_prefix/.update-state" ]]
 
@@ -233,7 +233,7 @@ env EUID=0 TALLYNOTE_INSTALL_PREFIX="$download_runner_prefix_physical" TALLYNOTE
 # temporary variables still exist; otherwise set -u fails at the end of main.
 release_fixture="$tmp/release-fixture"
 mkdir -p "$release_fixture/dist/server/cli" "$release_fixture/dist/web" "$release_fixture/bin" \
-  "$release_fixture/scripts" "$release_fixture/runtime/bin" "$release_fixture/systemd"
+  "$release_fixture/scripts" "$release_fixture/systemd"
 printf '%s\n' '{"version":"1.0.0"}' > "$release_fixture/package.json"
 printf '%s\n' server > "$release_fixture/dist/server/index.js"
 printf '%s\n' cli > "$release_fixture/dist/server/cli/admin-init.js"
@@ -282,16 +282,16 @@ grep -Fxq "PathChanged=$tmp/custom-prefix" "$rendered_path"
 # The production admin wrapper must load a release-relative runtime, change to
 # the release root, and forward CLI arguments without requiring pnpm.
 wrapper_prefix="$tmp/wrapper-prefix"
-mkdir -p "$wrapper_prefix/releases/1.0.0/runtime/bin" "$wrapper_prefix/releases/1.0.0/dist/server/cli"
+mkdir -p "$wrapper_prefix/releases/1.0.0/dist/server/cli" "$tmp/wrapper-tools"
 ln -s "$wrapper_prefix/releases/1.0.0" "$wrapper_prefix/current"
-printf '%s\n' '#!/usr/bin/env bash' 'pwd -P > "$TALLYNOTE_WRAPPER_LOG"' 'printf "%s\n" "$@" >> "$TALLYNOTE_WRAPPER_LOG"' > "$wrapper_prefix/releases/1.0.0/runtime/bin/node"
-chmod 755 "$wrapper_prefix/releases/1.0.0/runtime/bin/node"
+printf '%s\n' '#!/usr/bin/env bash' 'if [[ "${1:-}" == "-p" ]]; then printf "%s\n" "24"; else pwd -P > "$TALLYNOTE_WRAPPER_LOG"; printf "%s\n" "$@" >> "$TALLYNOTE_WRAPPER_LOG"; fi' > "$tmp/wrapper-tools/node"
+chmod 755 "$tmp/wrapper-tools/node"
 printf '%s\n' cli > "$wrapper_prefix/releases/1.0.0/dist/server/cli/admin-init.js"
 # This fixture verifies release-relative execution and argument forwarding.
 # Force the wrapper's non-root branch so the root CI runner does not need a
 # real `tallynote` service account or a privileged runuser hand-off; that
 # privilege boundary is validated by the production checks themselves.
-env EUID=1000 TALLYNOTE_INSTALL_PREFIX="$wrapper_prefix" TALLYNOTE_CONFIG_DIR="$tmp/no-config" TALLYNOTE_WRAPPER_LOG="$tmp/wrapper.log" \
+env EUID=1000 TALLYNOTE_INSTALL_PREFIX="$wrapper_prefix" TALLYNOTE_CONFIG_DIR="$tmp/no-config" TALLYNOTE_NODE="$tmp/wrapper-tools/node" TALLYNOTE_WRAPPER_LOG="$tmp/wrapper.log" \
   bash "$root/bin/tallynote-admin-init" --generate
 wrapper_expected_root=$(cd "$wrapper_prefix/releases/1.0.0" && pwd -P)
 grep -Fxq "$wrapper_expected_root" "$tmp/wrapper.log"
@@ -590,13 +590,12 @@ env -u TALLYNOTE_PUBLIC_ORIGIN -u TALLYNOTE_ALLOW_INSECURE_HTTP \
 # A release archive is extracted under umask 077, then explicitly normalized
 # so the tallynote system user can traverse and execute the shipped tree.
 source_tmp="$tmp/source"
-mkdir -p "$source_tmp/dist/server" "$source_tmp/bin" "$source_tmp/scripts" "$source_tmp/runtime/bin"
+mkdir -p "$source_tmp/dist/server" "$source_tmp/bin" "$source_tmp/scripts"
 printf '%s\n' 'server' > "$source_tmp/dist/server/index.js"
 printf '%s\n' '#!/bin/sh' > "$source_tmp/uninstall.sh"
 printf '%s\n' '#!/bin/sh' > "$source_tmp/bin/tallynote"
 printf '%s\n' '#!/bin/sh' > "$source_tmp/scripts/runner.sh"
-printf '%s\n' 'node' > "$source_tmp/runtime/bin/node"
-chmod 755 "$source_tmp/bin/tallynote" "$source_tmp/scripts/runner.sh" "$source_tmp/runtime/bin/node"
+chmod 755 "$source_tmp/bin/tallynote" "$source_tmp/scripts/runner.sh"
 chmod 755 "$source_tmp/uninstall.sh"
 archive_tmp="$tmp/release.tar.gz"
 tar -C "$source_tmp" -czf "$archive_tmp" .
@@ -612,6 +611,7 @@ bash -c '
   [[ "$(stat_mode "$destination/dist/server/index.js")" == 644 ]]
   [[ "$(stat_mode "$destination/bin/tallynote")" == 755 ]]
   [[ "$(stat_mode "$destination/uninstall.sh")" == 755 ]]
+  [[ ! -e "$destination/runtime" ]]
 ' _ "$installer_lib" "$archive_tmp" "$tmp/unpacked"
 
 # A normal public-release install only needs the detached SHA-256 manifest;

scripts/test-uninstaller.sh

@@ -34,7 +34,7 @@ make_fixture() {
   done
   printf '%s\n' '#!/usr/bin/env bash' 'PREFIX=${TALLYNOTE_INSTALL_PREFIX:-/opt/tallynote}' 'echo TallyNote' > "$fixture/usr/local/sbin/tallynote-update"
   printf '%s\n' '#!/usr/bin/env bash' 'PREFIX=${TALLYNOTE_INSTALL_PREFIX:-/opt/tallynote}' 'echo TallyNote' > "$fixture/usr/local/libexec/tallynote-update-runner"
-  printf '%s\n' '#!/usr/bin/env bash' 'exec /opt/tallynote/current/runtime/bin/node /opt/tallynote/current/dist/server/cli/admin-init.js' > "$fixture/usr/local/sbin/tallynote-admin-init"
+  printf '%s\n' '#!/usr/bin/env bash' 'exec /usr/bin/node /opt/tallynote/current/dist/server/cli/admin-init.js' > "$fixture/usr/local/sbin/tallynote-admin-init"
   cp "$root/uninstall.sh" "$fixture/usr/local/sbin/tallynote-uninstall"
   chmod 755 "$fixture/usr/local/sbin/tallynote-update" "$fixture/usr/local/libexec/tallynote-update-runner" "$fixture/usr/local/sbin/tallynote-admin-init" "$fixture/usr/local/sbin/tallynote-uninstall"
   printf '%s\n' 'sqlite' > "$fixture/var/lib/tallynote/tallynote.db"

server/app.ts

@@ -54,15 +54,20 @@ import {
   validateNewPassword,
   verifyPassword,
 } from "./security.js";
+import { createRateLimiter } from "./rate-limit.js";
+import { isNewerVersion } from "./update.js";
 import {
   ACTIVE_UPDATE_STATUSES,
+  ACTIVE_UPDATE_CONFLICT_SQL,
   checkForUpdate,
+  currentReleaseVersion,
   publicCheckFromCache,
   publicUpdateJob,
   reconcileOrphanedUpdateJobs,
   readCachedRelease,
   writeUpdateRequest,
   cancelUpdateJob,
+  downloadAndStageUpdate,
   type UpdateRequest,
 } from "./update-service.js";
 
@@ -97,6 +102,11 @@ const unsafeMethods = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 const sessionCookie = "tally_session";
 const csrfCookie = "tally_csrf";
 
+/** API paths are the only requests the global rate limiter and cache rules own. */
+function isApiPath(url: string): boolean {
+  return url.split("?", 1)[0]!.startsWith("/api/");
+}
+
 type UpdateRateState = { checkedAt: number; downloadedAt: number; appliedAt: number };
 const updateRateStates = new WeakMap<DatabaseContext["sqlite"], Map<string, UpdateRateState>>();
 
@@ -641,7 +651,7 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
   // retained by a browser, reverse proxy or shared cache. Keep this global so
   // future authenticated routes inherit the same privacy boundary.
   app.addHook("onSend", async (request, reply, payload) => {
-    if (request.url.split("?", 1)[0]!.startsWith("/api/")) {
+    if (isApiPath(request.url)) {
       reply.header("Cache-Control", "no-store");
       reply.header("Pragma", "no-cache");
       reply.header("Vary", "Cookie");
@@ -1012,11 +1022,23 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
       const stagedJobId = input.jobId;
       const staged = database.sqlite.prepare("SELECT id, status, operation, version, asset_url AS assetUrl, asset_name AS assetName, expected_sha256 AS expectedSha256 FROM update_jobs WHERE id=? AND admin_id=?").get(stagedJobId, request.auth!.admin.id) as { id: string; status: string; operation: string; version: string; assetUrl: string; assetName: string | null; expectedSha256: string | null } | undefined;
       if (!staged || staged.status !== "staged" || staged.version !== input.version.replace(/^v/i, "")) throw new AppError(409, "UPDATE_NOT_STAGED", "更新任务尚未完成下载");
+      // A package may have been downloaded before the host was upgraded by
+      // another path. Never apply a staged archive that is no longer newer
+      // than the release currently serving traffic.
+      const effectiveCurrentVersion = currentReleaseVersion(config) ?? config.appVersion;
+      if (!isNewerVersion(effectiveCurrentVersion, staged.version)) {
+        const now = Date.now();
+        database.sqlite.prepare("UPDATE update_jobs SET status='failed', error_message=?, completed_at=?, updated_at=? WHERE id=? AND status='staged'").run("暂存更新已过期，当前版本无需再次升级", now, now, stagedJobId);
+        throw new AppError(409, "UPDATE_NOT_AVAILABLE", "暂存更新已过期，请重新检查更新");
+      }
       if (staged.operation === "apply") throw new AppError(409, "UPDATE_IN_PROGRESS", "更新任务正在处理中，请稍候");
       enforceUpdateCooldown(database.sqlite, config, request.auth!.admin.id, "apply", reply);
       const now = Date.now();
       const active = database.sqlite.transaction(() => {
-        const conflictRow = database.sqlite.prepare(`SELECT id FROM update_jobs WHERE status IN (${ACTIVE_UPDATE_STATUSES.map(() => "?").join(",")}) AND id<>? LIMIT 1`).get(...ACTIVE_UPDATE_STATUSES, stagedJobId) as { id: string } | undefined;
+        // A reusable `staged/download` artifact must never block applying a
+        // *different* staged job: otherwise a leftover row keeps the queue
+        // permanently busy and the operator can never apply an update.
+        const conflictRow = database.sqlite.prepare(`SELECT id FROM update_jobs WHERE ${ACTIVE_UPDATE_CONFLICT_SQL} AND id<>? LIMIT 1`).get(...ACTIVE_UPDATE_STATUSES, stagedJobId) as { id: string } | undefined;
         if (conflictRow) throw new AppError(409, "UPDATE_IN_PROGRESS", "已有更新任务正在进行，请等待完成");
         const changed = database.sqlite.prepare("UPDATE update_jobs SET operation='apply', error_message=NULL, requested_at=?, request_id=?, updated_at=? WHERE id=? AND status='staged' AND operation='download'").run(now, request.id, now, stagedJobId);
         if (changed.changes !== 1) throw new AppError(409, "UPDATE_IN_PROGRESS", "更新任务正在处理中，请稍候");
@@ -1041,9 +1063,11 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
     }
     // Preserve the actionable in-progress response for duplicate clicks before
     // applying the per-admin cooldown.
+    // Same rule as the download path: a reusable staged download is an
+    // artifact, not a running task, and must not block apply.
     const activeBeforeCheck = database.sqlite.prepare(`
       SELECT id FROM update_jobs
-      WHERE status IN (${ACTIVE_UPDATE_STATUSES.map(() => "?").join(",")})
+      WHERE ${ACTIVE_UPDATE_CONFLICT_SQL}
       ORDER BY created_at DESC LIMIT 1
     `).get(...ACTIVE_UPDATE_STATUSES) as { id: string } | undefined;
     if (activeBeforeCheck) throw new AppError(409, "UPDATE_IN_PROGRESS", "已有更新任务正在进行，请等待完成");
@@ -1067,7 +1091,7 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
     const active = database.sqlite.transaction(() => {
       const existing = database.sqlite.prepare(`
         SELECT id, status FROM update_jobs
-        WHERE status IN (${ACTIVE_UPDATE_STATUSES.map(() => "?").join(",")})
+        WHERE ${ACTIVE_UPDATE_CONFLICT_SQL}
         ORDER BY created_at DESC LIMIT 1
       `).get(...ACTIVE_UPDATE_STATUSES) as { id: string; status: UpdateJobStatus } | undefined;
       if (existing) throw new AppError(409, "UPDATE_IN_PROGRESS", "已有更新任务正在进行，请等待完成");
@@ -1157,7 +1181,9 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
     const input = updateDownloadSchema.parse(request.body);
     reconcileOrphanedUpdateJobs(database.sqlite, config);
     if (config.updateStrategy !== "systemd") throw new AppError(503, "UPDATE_NOT_AVAILABLE", "当前安装方式未启用一键更新，请使用命令行更新");
-    const active = database.sqlite.prepare(`SELECT id FROM update_jobs WHERE status IN (${ACTIVE_UPDATE_STATUSES.map(() => "?").join(",")}) LIMIT 1`).get(...ACTIVE_UPDATE_STATUSES) as { id: string } | undefined;
+    // A finished `staged/download` row is a reusable artifact, not a running
+    // task, so it does not block a new download. Apply-phase rows still do.
+    const active = database.sqlite.prepare(`SELECT id FROM update_jobs WHERE ${ACTIVE_UPDATE_CONFLICT_SQL} LIMIT 1`).get(...ACTIVE_UPDATE_STATUSES) as { id: string } | undefined;
     if (active) throw new AppError(409, "UPDATE_IN_PROGRESS", "已有更新任务正在进行，请等待完成");
     enforceUpdateCooldown(database.sqlite, config, request.auth!.admin.id, "download", reply);
     const checked = await checkForUpdate(database.sqlite, config);
@@ -1169,25 +1195,30 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
     const now = Date.now();
     const id = randomUUID();
     database.sqlite.transaction(() => {
-      const conflict = database.sqlite.prepare(`SELECT id FROM update_jobs WHERE status IN (${ACTIVE_UPDATE_STATUSES.map(() => "?").join(",")}) LIMIT 1`).get(...ACTIVE_UPDATE_STATUSES) as { id: string } | undefined;
+      const conflict = database.sqlite.prepare(`SELECT id FROM update_jobs WHERE ${ACTIVE_UPDATE_CONFLICT_SQL} LIMIT 1`).get(...ACTIVE_UPDATE_STATUSES) as { id: string } | undefined;
       if (conflict) throw new AppError(409, "UPDATE_IN_PROGRESS", "已有更新任务正在进行，请等待完成");
       database.sqlite.prepare(`INSERT INTO update_jobs(id, admin_id, session_hash, request_id, requested_at, operation, status, version, platform, release_url, asset_name, asset_url, expected_sha256, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'download', 'queued', ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, request.auth!.admin.id, request.auth!.tokenHash, request.id, now, version, checked.platform.target, cached.metadataUrl, cachedAsset.name, cachedAsset.url, cachedAsset.sha256, now, now);
       writeAudit(database.sqlite, { requestId: request.id, actorAdminId: request.auth!.admin.id, actorUsername: request.auth!.admin.username, action: "update.download_requested", targetType: "update", targetId: id, after: { version } });
     }).immediate();
     try {
-      await writeUpdateRequest(config, { jobId: id, operation: "download", version, metadataUrl: cached.metadataUrl, assetUrl: cachedAsset.url, assetName: cachedAsset.name, expectedSha256: cachedAsset.sha256, requestedAt: now, currentLink: config.currentLink, releasesDir: config.releasesDir, dataDir: config.dataDir });
+      // Download happens synchronously in the web process (non-root). The
+      // root runner only receives an apply request after staging completes.
+      void downloadAndStageUpdate(database.sqlite, config, id, request.auth!.admin.id, version, cachedAsset.url, cachedAsset.name, cachedAsset.sha256, cached.metadataUrl);
     } catch {
-      database.sqlite.prepare("UPDATE update_jobs SET status='failed', error_message=?, updated_at=? WHERE id=?").run("无法创建系统更新请求", Date.now(), id);
-      throw new AppError(503, "UPDATE_QUEUE_FAILED", "无法提交更新请求，请检查服务安装权限");
+      database.sqlite.prepare("UPDATE update_jobs SET status='failed', error_message=?, updated_at=? WHERE id=?").run("无法启动下载", Date.now(), id);
+      throw new AppError(503, "UPDATE_DOWNLOAD_FAILED", "无法启动下载，请稍后重试");
     }
     reply.header("Cache-Control", "no-store");
-    return reply.code(202).send({ job: { id, status: "queued", operation: "download", version } });
+    return reply.code(200).send({ job: { id, status: "downloading", operation: "download", version } });
   });
 
   app.post("/api/update/cancel", { preHandler: guard(database, config) }, async (request, reply) => {
     reconcileOrphanedUpdateJobs(database.sqlite, config);
     const body = (request.body && typeof request.body === "object" ? request.body : {}) as { jobId?: string };
-    const result = cancelUpdateJob(database.sqlite, config, request.auth!.admin.id, request.id, body.jobId);
+    // `cancelUpdateJob` awaits its staging-workspace cleanup, so the caller must
+    // await it too; without the await `result` is a pending Promise and this
+    // branch would always report failure even after a successful cancel.
+    const result = await cancelUpdateJob(database.sqlite, config, request.auth!.admin.id, request.id, body.jobId);
     if (!result.cancelled) {
       throw new AppError(409, "CANNOT_CANCEL", result.message || "无法取消当前更新任务");
     }
@@ -1856,6 +1887,24 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
     return reply.send(await safeReadStream(config.exportsDir, job.filePath));
   });
 
+  // Global anti-flood backstop for the API surface. It is registered after all
+  // /api/* routes so it covers every one of them, but the path check keeps
+  // static assets, `/health` and the SPA fallback out of the limiter. The
+  // per-feature limits (login lockout, dangerous-operation re-auth, update
+  // cooldowns) stay authoritative; this only bounds raw request volume.
+  const apiRateLimiter = createRateLimiter({ limit: config.apiRateLimitPerMinute, windowMs: 60 * 1000 });
+  app.addHook("preHandler", async (request, reply) => {
+    if (!isApiPath(request.url)) return;
+    // `request.ip` already honours the validated trustProxy configuration, so
+    // the counted address is the one the deployment declared. The limiter must
+    // never parse X-Forwarded-For itself, otherwise a client could spoof its
+    // way around the limit.
+    const decision = apiRateLimiter.check(request.ip);
+    if (decision.allowed) return;
+    reply.header("Retry-After", decision.retryAfterSeconds);
+    throw new AppError(429, "RATE_LIMITED", "请求过于频繁，请稍后再试");
+  });
+
   const hasWeb = existsSync(config.webDir);
   if (hasWeb) {
     // Serve the Vite asset graph as well as the SPA entry. API routes are
@@ -1865,7 +1914,7 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
   // Keep API errors structured even when the production frontend has not been
   // built yet (for example in a clean CI checkout or an API-only process).
   app.setNotFoundHandler((request, reply) => {
-    if (request.url.split("?", 1)[0]!.startsWith("/api/")) {
+    if (isApiPath(request.url)) {
       return reply.code(404).send(errorPayload(request, new AppError(404, "NOT_FOUND", "接口不存在")));
     }
     if (hasWeb) return reply.sendFile("index.html");

server/cli/admin-init.ts

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { StringDecoder } from "node:string_decoder";
 import { openDatabase, openDatabaseReadOnly } from "../db/index.js";
 import { acquireInstanceLock, loadConfig, prepareDataDirectories } from "../config.js";
-import { hashPassword, normalizeUsername, validateNewPassword, temporaryPassword } from "../security.js";
+import { hashPassword, normalizeUsername, validateNewPassword, temporaryPassword, verifyPassword } from "../security.js";
 import { writeAudit } from "../audit.js";
 
 function arg(name: string): string | undefined {
@@ -79,8 +79,13 @@ async function readSecret(prompt: string): Promise<string> {
           return;
         } else if (character === "\u007f" || character === "\b") {
           value = value.slice(0, -1);
+          // Keep the credential visible in the SSH terminal as requested.
+          // Redraw the current line so backspace behaves predictably without
+          // putting the value into logs or command arguments.
+          output.write("\r\u001b[2K" + prompt + value);
         } else {
           value += character;
+          output.write(character);
         }
       }
     };
@@ -128,6 +133,39 @@ async function main() {
   const release = acquireInstanceLock(config);
   const database = openDatabase(config);
   try {
+    const markPasswordConfigured = process.argv.includes("--mark-password-configured");
+    if (markPasswordConfigured) {
+      const username = arg("--username") ?? (await readSecret("用户名: "));
+      const password = await readSecret("当前密码: ");
+      const normalized = normalizeUsername(username);
+      const admin = database.sqlite.prepare(
+        "SELECT id, password_hash, must_change_password, version FROM admins WHERE username_norm = ?",
+      ).get(normalized) as { id: string; password_hash: string; must_change_password: number; version: number } | undefined;
+      if (!admin || !(await verifyPassword(admin.password_hash, password))) {
+        throw new Error("用户名或当前密码不正确");
+      }
+      if (!admin.must_change_password) {
+        console.log("该管理员已经可以直接使用当前密码登录。");
+        return;
+      }
+      const now = Date.now();
+      database.sqlite.transaction(() => {
+        const result = database.sqlite.prepare(
+          "UPDATE admins SET must_change_password=0, auth_version=auth_version+1, version=version+1 WHERE id=? AND version=?",
+        ).run(admin.id, admin.version);
+        if (result.changes !== 1) throw new Error("管理员资料已被其他操作更新，请重试");
+        writeAudit(database.sqlite, {
+          requestId: `cli:${randomUUID()}`,
+          actorUsername: "cli",
+          action: "admin.password_policy_cleared",
+          targetType: "admin",
+          targetId: admin.id,
+          after: { username: normalized, mustChangePassword: false, changedAt: now },
+        });
+      })();
+      console.log("已确认当前密码为正式密码，后续登录不再要求修改密码。");
+      return;
+    }
     const existing = database.sqlite.prepare("SELECT COUNT(*) AS count FROM admins").get() as { count: number };
     if (existing.count > 0) throw new Error("INITIAL_ADMIN_EXISTS：管理员已经初始化");
     const username = arg("--username") ?? (await readSecret("用户名: "));
@@ -154,8 +192,16 @@ async function main() {
       database.sqlite.prepare(`
         INSERT INTO admins(id, username, username_norm, display_name, password_hash, status,
           must_change_password, auth_version, version, created_at)
-        VALUES (?, ?, ?, ?, ?, 'active', 1, 1, 1, ?)
-      `).run(id, username.normalize("NFKC").trim(), normalized, normalizedDisplayName, passwordHash, now);
+        VALUES (?, ?, ?, ?, ?, 'active', ?, 1, 1, ?)
+      `).run(
+        id,
+        username.normalize("NFKC").trim(),
+        normalized,
+        normalizedDisplayName,
+        passwordHash,
+        generate ? 1 : 0,
+        now,
+      );
       writeAudit(database.sqlite, {
         requestId: `cli:${randomUUID()}`,
         actorUsername: "cli",

server/cli/update.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { cp, lstat, mkdir, mkdtemp, readFile, realpath, rm } from "node:fs/promises";
+import { copyFile, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import type Database from "better-sqlite3";
@@ -10,7 +10,6 @@ import { writeAudit } from "../audit.js";
 import {
   atomicSwitchDirectory,
   atomicSwitchRelease,
-  applicationUpdateRuntimeHash,
   compareSemver,
   createSafeArchive,
   detectPlatform,
@@ -20,10 +19,10 @@ import {
   isNewerVersion,
   normalizeReleasePermissions,
   parseSemver,
-  runtimeHashFromLockfile,
   selectReleaseAsset,
   sanitizeAssetName,
   validateHttpsUrl,
+  verifySha256,
   type ReleaseAsset,
   type ReleaseMetadata,
   type UrlPolicy,
@@ -163,7 +162,10 @@ function writeJob(sqlite: Database.Database | undefined, jobId: string, values:
       requested_at=COALESCE(excluded.requested_at, update_jobs.requested_at),
       started_at=COALESCE(excluded.started_at, update_jobs.started_at),
       operation=excluded.operation,
-      status=CASE WHEN update_jobs.status='cancelled' THEN update_jobs.status ELSE excluded.status END,
+      -- Terminal rows are immutable from the runner's ordinary progress
+      -- writes. In particular, a stale/replayed request must not resurrect a
+      -- failed job as queued/downloading/etc.
+      status=CASE WHEN update_jobs.status IN ('cancelled', 'failed', 'completed') THEN update_jobs.status ELSE excluded.status END,
       version=excluded.version, platform=excluded.platform,
       release_url=COALESCE(excluded.release_url, update_jobs.release_url),
       asset_name=COALESCE(excluded.asset_name, update_jobs.asset_name),
@@ -176,6 +178,11 @@ function writeJob(sqlite: Database.Database | undefined, jobId: string, values:
       error_message=COALESCE(excluded.error_message, update_jobs.error_message),
       updated_at=excluded.updated_at,
       completed_at=COALESCE(excluded.completed_at, update_jobs.completed_at)
+    -- Do not let a delayed runner replay overwrite any field on a terminal
+    -- row. The predicate is part of the same SQLite upsert, so a finalizer
+    -- racing this write still wins atomically instead of leaving a partially
+    -- mutated completed/failed/cancelled record.
+    WHERE update_jobs.status NOT IN ('cancelled', 'failed', 'completed')
   `).run(
     jobId,
     values.adminId ?? null,
@@ -215,21 +222,15 @@ async function resolveRelease(options: UpdateRunOptions, platform: ReturnType<ty
   if (options.metadataUrl) {
     const metadataUrl = validateHttpsUrl(options.metadataUrl, options);
     const release = await fetchReleaseMetadata(metadataUrl, options);
-    let runtimeHash: string | undefined;
-    try {
-      runtimeHash = runtimeHashFromLockfile(await readFile(path.join(options.currentDir, "pnpm-lock.yaml")));
-    } catch {
-      // Fall back to the full archive when the current installation predates
-      // runtime fingerprints or is missing deployment provenance.
-    }
     let asset = options.assetUrl && !options.requireSignature
       ? { name: sanitizeAssetName(options.assetName ?? path.basename(new URL(options.assetUrl).pathname)), url: validateHttpsUrl(options.assetUrl, { ...options, baseUrl: metadataUrl }).toString(), ...(options.expectedSha256 ? { sha256: options.expectedSha256 } : {}) }
-      : selectReleaseAsset(release, platform, runtimeHash);
+      : selectReleaseAsset(release, platform);
     if (!asset) throw new Error("没有匹配当前平台的更新文件");
     const integrity = await attachSidecarHash(release, asset, {
       allowedHosts: options.allowedHosts ?? [],
       baseUrl: metadataUrl.toString(),
       maxBytes: options.maxBytes ?? 512 * 1024 * 1024,
+      timeoutMs: options.timeoutMs,
       publicKey: options.publicKey,
       requireSignature: options.requireSignature,
     });
@@ -244,35 +245,243 @@ async function resolveRelease(options: UpdateRunOptions, platform: ReturnType<ty
   return { asset: { name: sanitizeAssetName(options.assetName ?? path.basename(assetUrl.pathname)), url: assetUrl.toString(), ...(options.expectedSha256 ? { sha256: options.expectedSha256 } : {}) }, version: options.version };
 }
 
-async function ensurePrivilegedWorkspace(directory: string): Promise<string> {
+/**
+ * Ownership expectation for a directory consumed by the privileged updater.
+ *
+ * `-1` disables the uid comparison while keeping the symlink and mode checks.
+ * Production always passes a concrete uid (0 for the root-owned
+ * `<installPrefix>/.update-work`), so the check never depends on the effective
+ * uid of the current process and remains runnable from a non-root test.
+ */
+export type DirectoryOwnerUid = number;
+
+/** The staging area owned by the unprivileged web process and the private
+ * root-owned workspace are deliberately separate trust domains. */
+export class StagedWorkspaceError extends Error {
+  readonly reason: string;
+  constructor(message: string, reason: string) {
+    super(message);
+    this.name = "StagedWorkspaceError";
+    this.reason = reason;
+  }
+}
+
+/** Owner uid of an existing path, or -1 when it cannot be inspected. */
+export async function directoryOwnerUid(targetPath: string): Promise<DirectoryOwnerUid> {
+  const info = await lstat(path.resolve(targetPath)).catch(() => null);
+  return info?.uid ?? -1;
+}
+
+/**
+ * Resolve a privileged workspace root to its canonical path.
+ *
+ * The root itself may be reached through a symlinked ancestor (for example
+ * `/tmp` on macOS), so only the final component is required to be a real,
+ * non-symlink directory with private permissions and the expected owner.
+ */
+async function canonicalizePrivilegedRoot(directory: string, expectedUid: DirectoryOwnerUid, message: string): Promise<string> {
   const resolved = path.resolve(directory);
   await mkdir(resolved, { recursive: true, mode: 0o700 });
   const info = await lstat(resolved).catch(() => null);
-  const uid = typeof process.getuid === "function" ? process.getuid() : -1;
-  if (!info?.isDirectory() || info.isSymbolicLink() || (info.mode & 0o077) !== 0 || info.uid !== 0 || uid !== 0) {
-    throw new Error("更新工作目录必须是 root 拥有且权限为 0700");
+  if (!info?.isDirectory() || info.isSymbolicLink() || (info.mode & 0o077) !== 0 || (expectedUid >= 0 && info.uid !== expectedUid)) {
+    throw new Error(message);
   }
-  return resolved;
+  const real = await realpath(resolved).catch(() => { throw new Error(message); });
+  const realInfo = await lstat(real).catch(() => null);
+  if (!realInfo?.isDirectory() || realInfo.isSymbolicLink() || (realInfo.mode & 0o077) !== 0 || (expectedUid >= 0 && realInfo.uid !== expectedUid)) {
+    throw new Error(message);
+  }
+  return real;
 }
 
-/** Validate a queued staged directory before a root process consumes it. */
-async function validateStagedWorkspacePath(candidate: string, workspaceRoot: string): Promise<string> {
-  const rootResolved = path.resolve(workspaceRoot);
-  const rootInfo = await lstat(rootResolved).catch(() => null);
-  const uid = typeof process.getuid === "function" ? process.getuid() : -1;
-  if (!rootInfo?.isDirectory() || rootInfo.isSymbolicLink() || (rootInfo.mode & 0o077) !== 0 || rootInfo.uid !== 0 || uid !== 0) {
-    throw new Error("更新工作目录权限无效");
-  }
-  const root = await realpath(rootResolved).catch(() => { throw new Error("更新工作目录无效"); });
+/** Assert that `candidate` is a real, private, expected-owner directory below `root`. */
+async function assertStagedDirectory(candidate: string, root: string, expectedUid: DirectoryOwnerUid): Promise<string> {
   const resolved = path.resolve(candidate);
-  if (resolved === rootResolved || !resolved.startsWith(`${rootResolved}${path.sep}`)) throw new Error("更新暂存路径无效");
+  if (resolved === root || !resolved.startsWith(`${root}${path.sep}`)) throw new StagedWorkspaceError("更新暂存路径无效", "staged_workspace_invalid");
   const info = await lstat(resolved).catch(() => null);
-  if (!info?.isDirectory() || info.isSymbolicLink() || (info.mode & 0o077) !== 0 || info.uid !== 0) throw new Error("更新暂存目录权限无效");
-  const real = await realpath(resolved).catch(() => { throw new Error("更新暂存目录无效"); });
-  if (real !== resolved || !real.startsWith(`${root}${path.sep}`)) throw new Error("更新暂存路径无效");
+  if (!info?.isDirectory() || info.isSymbolicLink() || (info.mode & 0o077) !== 0) throw new StagedWorkspaceError("更新暂存目录权限无效", "staged_workspace_insecure");
+  if (expectedUid >= 0 && info.uid !== expectedUid) throw new StagedWorkspaceError("更新暂存目录属主无效", "staged_workspace_insecure");
+  const real = await realpath(resolved).catch(() => { throw new StagedWorkspaceError("更新暂存目录无效", "staged_workspace_invalid"); });
+  if (real !== resolved || !real.startsWith(`${root}${path.sep}`)) throw new StagedWorkspaceError("更新暂存路径无效", "staged_workspace_invalid");
   return real;
 }
 
+async function ensurePrivilegedWorkspace(directory: string, expectedUid: DirectoryOwnerUid): Promise<string> {
+  return canonicalizePrivilegedRoot(directory, expectedUid, "更新工作目录必须是 root 拥有且权限为 0700");
+}
+
+/**
+ * Rebuild the staged workspace location for `jobId` instead of trusting the
+ * `download_path` column: the runner clears that column whenever it releases
+ * a workspace (`clearTransientJobPath`), and a nulled column cannot be used to
+ * find a payload that is still on disk waiting for the apply step.
+ *
+ * Candidate order:
+ *   1. `<stagingRoot>/update-<jobId>`      (web download workspace)
+ *   2. `<stagingRoot>/update-<jobId>-*`    (mkdtemp variant)
+ *   3. the recorded `download_path`, but only while it stays inside the root
+ */
+export async function locateStagedWorkspace(options: {
+  jobId: string;
+  downloadPath?: string | null | undefined;
+  stagingRoot: string;
+  expectedUid: DirectoryOwnerUid;
+}): Promise<string> {
+  const root = await canonicalizePrivilegedRoot(options.stagingRoot, options.expectedUid, "更新暂存根目录权限无效");
+  const prefix = `update-${options.jobId}`;
+  const candidates = [path.join(root, prefix)];
+  const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries.filter((candidate) => candidate.name.startsWith(`${prefix}-`)).sort((a, b) => a.name.localeCompare(b.name))) {
+    candidates.push(path.join(root, entry.name));
+  }
+  const recorded = options.downloadPath?.trim();
+  if (recorded && path.isAbsolute(recorded)) {
+    const resolvedRecorded = path.resolve(recorded);
+    if (resolvedRecorded.startsWith(`${root}${path.sep}`)) candidates.push(resolvedRecorded);
+    // A recorded path outside the staging root is never consumed. Reject it
+    // loudly when it exists so the operator sees the real cause instead of a
+    // generic "re-download" message.
+    else if (await lstat(resolvedRecorded).catch(() => null)) throw new StagedWorkspaceError("更新暂存路径无效", "staged_workspace_invalid");
+  }
+  const seen = new Set<string>();
+  for (const candidate of candidates) {
+    const resolved = path.resolve(candidate);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    // An existing candidate must satisfy every constraint: skipping it would
+    // hand the root process whatever else happens to sit in the staging area.
+    if (!(await lstat(resolved).catch(() => null))) continue;
+    return assertStagedDirectory(resolved, root, options.expectedUid);
+  }
+  throw new StagedWorkspaceError("暂存目录已不存在，请重新下载", "staged_workspace_missing");
+}
+
+/** Copy a verified payload tree without following or preserving symlinks. */
+async function copyReleaseTree(source: string, target: string): Promise<void> {
+  await mkdir(target, { recursive: false, mode: 0o700 });
+  const entries = await readdir(source, { withFileTypes: true });
+  for (const entry of entries) {
+    const from = path.join(source, entry.name);
+    const to = path.join(target, entry.name);
+    if (entry.isSymbolicLink()) throw new Error("更新暂存内容包含符号链接");
+    if (entry.isDirectory()) await copyReleaseTree(from, to);
+    else if (entry.isFile()) await copyFile(from, to);
+    else throw new Error("更新暂存内容包含不受支持的文件类型");
+  }
+}
+
+const STAGED_ARCHIVE_PATTERN = /\.(?:tar\.gz|tgz|tar|zip)$/i;
+
+async function assertStagedArchiveIntegrity(source: string, expectedSha256: string | null | undefined): Promise<void> {
+  const expected = expectedSha256?.trim().toLowerCase();
+  if (!expected) return;
+  if (!/^[a-f0-9]{64}$/.test(expected)) throw new Error("更新暂存校验值无效");
+  const entries = await readdir(source, { withFileTypes: true }).catch(() => []);
+  const archive = entries
+    .filter((entry) => entry.isFile() && !entry.isSymbolicLink() && STAGED_ARCHIVE_PATTERN.test(entry.name))
+    .sort((a, b) => a.name.localeCompare(b.name))[0];
+  if (!archive) throw new Error("更新暂存归档缺失，无法校验完整性");
+  const archivePath = path.join(source, archive.name);
+  const info = await lstat(archivePath).catch(() => null);
+  if (!info?.isFile() || info.isSymbolicLink()) throw new Error("更新暂存归档无效");
+  if (!(await verifySha256(archivePath, expected))) throw new Error("更新文件 SHA-256 校验失败");
+}
+
+/**
+ * Snapshot the web-staged payload into a root-owned workspace before the apply
+ * flow touches it. The copy is what closes the TOCTOU window: the unprivileged
+ * web user keeps write access to its own staging directory, so the privileged
+ * process must never execute content that lives there.
+ *
+ * A copy (not a rename) is required because the data directory and the install
+ * prefix are frequently separate mounts, where `rename` fails with EXDEV.
+ */
+export async function preparePrivateApplyWorkspace(options: {
+  jobId: string;
+  source: string;
+  privateRoot: string;
+  expectedUid: DirectoryOwnerUid;
+  expectedSha256?: string | null | undefined;
+}): Promise<string> {
+  const root = await canonicalizePrivilegedRoot(options.privateRoot, options.expectedUid, "更新工作目录必须是 root 拥有且权限为 0700");
+  const source = path.resolve(options.source);
+  const sourcePayload = path.join(source, "payload");
+  const sourcePayloadInfo = await lstat(sourcePayload).catch(() => null);
+  if (!sourcePayloadInfo?.isDirectory() || sourcePayloadInfo.isSymbolicLink()) throw new Error("更新暂存内容无效");
+  // Second integrity check right before the copy, so a payload swapped after
+  // the download verification is rejected instead of promoted to a release.
+  await assertStagedArchiveIntegrity(source, options.expectedSha256);
+  const target = path.join(root, `apply-${options.jobId}`);
+  const existing = await lstat(target).catch(() => null);
+  if (existing) await rm(target, { recursive: true, force: true }).catch(() => undefined);
+  try {
+    // Create the container explicitly: `copyReleaseTree` intentionally uses a
+    // non-recursive mkdir so a pre-existing/symlinked target can never be
+    // silently reused, and the parent must therefore already exist.
+    await mkdir(target, { recursive: false, mode: 0o700 });
+    await copyReleaseTree(sourcePayload, path.join(target, "payload"));
+    await normalizeReleasePermissions(path.join(target, "payload"));
+    const copied = await lstat(path.join(target, "payload")).catch(() => null);
+    if (!copied?.isDirectory() || copied.isSymbolicLink()) throw new Error("更新暂存内容复制失败");
+    return target;
+  } catch (error) {
+    await rm(target, { recursive: true, force: true }).catch(() => undefined);
+    throw error;
+  }
+}
+
+/** Reason code attached to failures that must reach the UI verbatim. */
+function failureReason(error: unknown): string {
+  const reason = (error as { reason?: unknown } | null)?.reason;
+  return typeof reason === "string" && /^[a-z0-9_]{1,64}$/.test(reason) ? reason : "apply_precheck_failed";
+}
+
+/**
+ * Persist a real failure reason from the privileged apply path.
+ *
+ * `writeJob`/`updateJob` cannot be used here: their final-state guard
+ * (`WHERE update_jobs.status NOT IN (...)`) protects terminal rows, and it also
+ * makes the runner's own progress writes a no-op once a row is terminal. This
+ * helper issues an independent, guarded UPDATE so the true cause is visible in
+ * the UI instead of the runner's generic health-check message.
+ */
+export function failUpdateJobWithReason(
+  sqlite: Database.Database | undefined,
+  jobId: string,
+  message: string,
+  options: { reason?: string } = {},
+): boolean {
+  if (!sqlite) return false;
+  const safe = safeErrorMessage(message.length ? new Error(message) : new Error("更新失败"));
+  try {
+    return sqlite.transaction(() => {
+      const row = sqlite.prepare("SELECT status, version, request_id AS requestId, admin_id AS adminId FROM update_jobs WHERE id=?").get(jobId) as {
+        status: UpdateJobStatus; version: string; requestId: string | null; adminId: string | null;
+      } | undefined;
+      if (!row || row.status === "completed" || row.status === "cancelled" || row.status === "failed") return false;
+      const now = Date.now();
+      const updated = sqlite.prepare("UPDATE update_jobs SET status='failed', error_message=?, completed_at=COALESCE(completed_at, ?), updated_at=? WHERE id=? AND status=?").run(safe, now, now, jobId, row.status);
+      if (updated.changes !== 1) return false;
+      writeAudit(sqlite, {
+        requestId: row.requestId || randomUUID(),
+        actorAdminId: row.adminId,
+        action: "update.failed",
+        targetType: "update",
+        targetId: jobId,
+        outcome: "failure",
+        before: { status: row.status, version: row.version },
+        after: { status: "failed", version: row.version, reason: options.reason ?? "apply_precheck_failed", error: safe },
+      });
+      return true;
+    })();
+  } catch {
+    // The database may not be open (or the row may not exist) when a request is
+    // rejected during preflight. Losing the diagnostic write must never turn a
+    // clean rejection into a crash.
+    return false;
+  }
+}
+
 export async function runUpdate(options: UpdateRunOptions): Promise<UpdateRunResult> {
   const platform = options.platform ?? detectPlatform();
   const jobId = options.jobId ?? randomUUID();
@@ -330,17 +539,8 @@ export async function runUpdate(options: UpdateRunOptions): Promise<UpdateRunRes
       if (!archivePath.endsWith(".tar.gz") && !archivePath.endsWith(".tgz") && !archivePath.endsWith(".tar") && !archivePath.endsWith(".zip")) throw new Error("更新文件格式仅支持 tar.gz、tar 或 zip");
       const stagedDir = path.join(workspace, "payload");
       await extractSafeArchive(archivePath, stagedDir, options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes });
-      if (applicationUpdateRuntimeHash(resolved.asset.name)) {
-        const currentRelease = await realpath(options.currentDir).catch(() => { throw new Error("当前安装目录无效"); });
-        const currentInfo = await lstat(currentRelease).catch(() => null);
-        if (!currentInfo?.isDirectory() || currentInfo.isSymbolicLink()) throw new Error("当前安装目录无效");
-        for (const entry of ["node_modules", "runtime", "pnpm-lock.yaml"] as const) {
-          const source = path.join(currentRelease, entry);
-          const sourceInfo = await lstat(source).catch(() => null);
-          if (!sourceInfo || sourceInfo.isSymbolicLink()) throw new Error("当前运行时不完整，无法应用轻量更新");
-          await cp(source, path.join(stagedDir, entry), { recursive: sourceInfo.isDirectory(), errorOnExist: true, force: false });
-        }
-      }
+      const embeddedRuntime = await lstat(path.join(stagedDir, "runtime")).catch(() => null);
+      if (embeddedRuntime) throw new Error("发布包不应包含 Node.js runtime");
       await normalizeReleasePermissions(stagedDir);
       const payloadInfo = await lstat(path.join(stagedDir, "dist")).catch(() => null);
       if (!payloadInfo?.isDirectory() || payloadInfo.isSymbolicLink()) throw new Error("发布包缺少 dist 目录");
@@ -398,19 +598,28 @@ export function finalizeUpdateJob(
   status: "completed" | "failed",
   message?: string,
 ): void {
-  const row = sqlite.prepare(`
-    SELECT id, status, version, platform, admin_id AS adminId,
-      request_id AS requestId, session_hash AS sessionHash
-    FROM update_jobs WHERE id=?
-  `).get(jobId) as { id: string; status: UpdateJobStatus; version: string; platform: string; adminId: string | null; requestId: string | null; sessionHash: string | null } | undefined;
-  if (!row) throw new Error("更新任务不存在");
-  const canComplete = row.status === "applying" || row.status === "completed";
-  const canFail = ACTIVE_UPDATE_STATUSES.includes(row.status) || row.status === "completed" || row.status === "failed";
-  if (status === "completed" ? !canComplete : !canFail) throw new Error("更新任务状态不允许完成");
-  const now = Date.now();
-  const safeFailureMessage = status === "failed" ? "新版本健康检查失败，已恢复上一版本" : null;
   sqlite.transaction(() => {
-    sqlite.prepare("UPDATE update_jobs SET status=?, error_message=?, completed_at=?, updated_at=? WHERE id=?").run(status, safeFailureMessage, now, now, jobId);
+    const row = sqlite.prepare(`
+      SELECT id, status, version, platform, admin_id AS adminId,
+        request_id AS requestId, session_hash AS sessionHash
+      FROM update_jobs WHERE id=?
+    `).get(jobId) as { id: string; status: UpdateJobStatus; version: string; platform: string; adminId: string | null; requestId: string | null; sessionHash: string | null } | undefined;
+    if (!row) throw new Error("更新任务不存在");
+    // A failed finalization can be retried by the runner. Once it has been
+    // committed, make retries a no-op so the error and audit trail stay stable.
+    if (row.status === status) return;
+    // A completed release is terminal. A delayed recovery process must never
+    // be able to downgrade it to failed after the service was healthy.
+    if (row.status === "completed" && status === "failed") throw new Error("更新任务状态不允许完成");
+    const canComplete = row.status === "applying" || row.status === "completed";
+    const canFail = ACTIVE_UPDATE_STATUSES.includes(row.status) || row.status === "completed" || row.status === "failed";
+    if (status === "completed" ? !canComplete : !canFail) throw new Error("更新任务状态不允许完成");
+    const now = Date.now();
+    const safeFailureMessage = status === "failed"
+      ? (message?.trim() ? safeErrorMessage(new Error(message)) : "新版本健康检查失败，已恢复上一版本")
+      : null;
+    const result = sqlite.prepare("UPDATE update_jobs SET status=?, error_message=?, completed_at=?, updated_at=? WHERE id=? AND status=?").run(status, safeFailureMessage, now, now, jobId, row.status);
+    if (result.changes !== 1) return;
     writeAudit(sqlite, {
       requestId: row.requestId || randomUUID(),
       actorAdminId: row.adminId,
@@ -437,13 +646,17 @@ export async function applyStagedUpdate(options: {
   maxBytes?: number;
   dataBackupMaxBytes?: number;
   workspaceRoot?: string;
+  /** Expected owner of `workspaceRoot`. Defaults to uid 0 (the installer
+   * provisions `<installPrefix>/.update-work` as root-owned 0700). Tests inject
+   * the current user so the check never depends on `process.getuid()`. */
+  workspaceOwnerUid?: DirectoryOwnerUid;
 }): Promise<void> {
   const row = options.sqlite.prepare(`SELECT status, operation, version, platform, release_url AS releaseUrl, asset_name AS assetName, asset_url AS assetUrl, expected_sha256 AS expectedSha256, actual_sha256 AS actualSha256, size_bytes AS sizeBytes FROM update_jobs WHERE id=?`).get(options.jobId) as Record<string, unknown> | undefined;
   if (!row || row.status !== "staged" || row.operation !== "apply") throw new Error("更新任务未处于待应用状态");
   if (typeof row.version === "string" && row.version !== options.version) throw new Error("更新版本不一致");
   const stagedPath = options.workspaceRoot
-    ? await validateStagedWorkspacePath(options.stagedPath, options.workspaceRoot)
-    : options.stagedPath;
+    ? await canonicalizePrivilegedRoot(options.workspaceRoot, options.workspaceOwnerUid ?? 0, "更新工作目录权限无效")
+    : path.resolve(options.stagedPath);
   const payload = path.join(stagedPath, "payload");
   const payloadInfo = await lstat(payload).catch(() => null);
   if (!payloadInfo?.isDirectory() || payloadInfo.isSymbolicLink()) throw new Error("更新暂存内容无效");
@@ -481,7 +694,21 @@ function arg(name: string): string | undefined {
   return index >= 0 ? process.argv[index + 1] : undefined;
 }
 
-export async function main(config: AppConfig = loadConfig()): Promise<void> {
+/**
+ * Ownership expectations the privileged entry point uses for the two trust
+ * domains it consumes. They are injectable so the apply flow can be exercised
+ * end-to-end from a non-root test process: production always uses the defaults
+ * (root-owned `<installPrefix>/.update-work` and the `dataDir` owner for the
+ * unprivileged staging area) and never consults `process.getuid()`.
+ */
+export type UpdateMainOverrides = {
+  /** Expected owner of the unprivileged staging root (`config.stagingDir`). */
+  stagingOwnerUid?: DirectoryOwnerUid;
+  /** Expected owner of the root-only private workspace (`config.updateWorkspaceDir`). */
+  workspaceOwnerUid?: DirectoryOwnerUid;
+};
+
+export async function main(config: AppConfig = loadConfig(), overrides: UpdateMainOverrides = {}): Promise<void> {
   const finalizeJobId = arg("--finalize-job");
   if (finalizeJobId) {
     const finalStatus = arg("--finalize-status");
@@ -518,7 +745,9 @@ export async function main(config: AppConfig = loadConfig()): Promise<void> {
   const dataBackupArchive = arg("--data-backup") ?? (request ? path.join(path.dirname(config.dataDir), "tallynote-backups", `data-${request.jobId}.tar.gz`) : undefined);
   const allowedHosts = process.argv.flatMap((value, index) => value === "--allow-host" && process.argv[index + 1] ? [process.argv[index + 1]!] : []);
   prepareDataDirectories(config);
-  if (request) await ensurePrivilegedWorkspace(stagingDir);
+  const workspaceOwnerUid = overrides.workspaceOwnerUid ?? 0;
+  const stagingOwnerUid = overrides.stagingOwnerUid ?? await directoryOwnerUid(config.dataDir);
+  if (request) await ensurePrivilegedWorkspace(stagingDir, workspaceOwnerUid);
   else await mkdir(stagingDir, { recursive: true, mode: 0o700 });
   // The download phase intentionally runs beside the live app so users keep
   // access while the archive is fetched and staged. SQLite WAL plus the
@@ -528,28 +757,67 @@ export async function main(config: AppConfig = loadConfig()): Promise<void> {
   const database = openDatabase(config);
   try {
     if (request?.operation === "apply") {
-      const staged = database.sqlite.prepare("SELECT status, operation, download_path AS downloadPath, version FROM update_jobs WHERE id=?").get(request.jobId) as { status: UpdateJobStatus; operation: "download" | "apply"; downloadPath: string | null; version: string } | undefined;
+      const staged = database.sqlite.prepare("SELECT status, operation, download_path AS downloadPath, version, expected_sha256 AS expectedSha256 FROM update_jobs WHERE id=?").get(request.jobId) as { status: UpdateJobStatus; operation: "download" | "apply"; downloadPath: string | null; version: string; expectedSha256: string | null } | undefined;
       if (staged?.status === "staged" && staged.operation === "apply") {
-        if (!staged.downloadPath || staged.version !== request.version) throw new Error("更新暂存任务无效");
-        const root = path.resolve(config.updateWorkspaceDir);
-        const candidate = await validateStagedWorkspacePath(staged.downloadPath, root);
-        await applyStagedUpdate({
-          sqlite: database.sqlite,
-          jobId: request.jobId,
-          version: request.version,
-          stagedPath: candidate,
-          currentDir,
-          currentLink: request.currentLink,
-          releasesDir: request.releasesDir,
-          workspaceRoot: root,
-          ...(backupArchive ? { backupArchivePath: backupArchive } : {}),
-          ...(dataBackupArchive ? { dataBackupArchivePath: dataBackupArchive } : {}),
-          dataBackupSource: config.dataDir,
-          maxBytes: config.updateMaxBytes,
-          dataBackupMaxBytes: config.maxTotalBytes,
-        });
-        console.log(`更新已切换：${request.version}`);
-        return;
+        // `download_path` is intentionally NOT required here. The runner NULLs
+        // that column as soon as it releases a workspace, so it can never be the
+        // source of truth for a payload that still exists on disk. The job id is
+        // the stable key; the column survives only as a last-resort candidate in
+        // `locateStagedWorkspace`.
+        if (staged.version !== request.version) throw new Error("更新暂存任务无效");
+        let privateWorkspace: string | undefined;
+        try {
+          const source = await locateStagedWorkspace({
+            jobId: request.jobId,
+            downloadPath: staged.downloadPath,
+            stagingRoot: config.stagingDir,
+            expectedUid: stagingOwnerUid,
+          });
+          // Snapshot into the root-only workspace before applying. The web user
+          // keeps write access to the staging tree, so content that is executed
+          // by the privileged process must never live there (TOCTOU).
+          privateWorkspace = await preparePrivateApplyWorkspace({
+            jobId: request.jobId,
+            source,
+            privateRoot: config.updateWorkspaceDir,
+            expectedUid: workspaceOwnerUid,
+            expectedSha256: staged.expectedSha256,
+          });
+          await applyStagedUpdate({
+            sqlite: database.sqlite,
+            jobId: request.jobId,
+            version: request.version,
+            stagedPath: privateWorkspace,
+            workspaceRoot: privateWorkspace,
+            workspaceOwnerUid,
+            currentDir,
+            currentLink: request.currentLink,
+            releasesDir: request.releasesDir,
+            ...(backupArchive ? { backupArchivePath: backupArchive } : {}),
+            ...(dataBackupArchive ? { dataBackupArchivePath: dataBackupArchive } : {}),
+            dataBackupSource: config.dataDir,
+            maxBytes: config.updateMaxBytes,
+            dataBackupMaxBytes: config.maxTotalBytes,
+          });
+          // The private copy has been consumed by the release switch and the
+          // payload is now the live release, so the web-owned source tree is
+          // redundant. Best-effort cleanup must not fail an applied update.
+          await rm(source, { recursive: true, force: true }).catch(() => undefined);
+          console.log(`更新已切换：${request.version}`);
+          return;
+        } catch (error) {
+          // Covers failures raised before `applyStagedUpdate` took ownership of
+          // the private copy, and the "already committed" case where the failing
+          // path deliberately skips its own cleanup.
+          if (privateWorkspace) await rm(privateWorkspace, { recursive: true, force: true }).catch(() => undefined);
+          // The runner can only report its fixed health-check message. Record the
+          // real pre-flight cause so the UI and the audit trail show why the
+          // update was rejected. A terminal row is only reachable through an
+          // independent guarded UPDATE (`writeJob` refuses to mutate terminal
+          // rows), which is exactly what this helper issues.
+          failUpdateJobWithReason(database.sqlite, request.jobId, safeErrorMessage(error), { reason: failureReason(error) });
+          throw error;
+        }
       }
       if (staged && !(staged.status === "queued" && staged.operation === "apply")) throw new Error("更新任务状态无效");
       // A direct one-click request starts in queued/apply. Older clients do
@@ -569,6 +837,7 @@ export async function main(config: AppConfig = loadConfig()): Promise<void> {
       ...(dataBackupArchive ? { dataBackupArchivePath: dataBackupArchive, dataBackupSource: config.dataDir } : {}),
       ...((arg("--backup-dir")) ? { backupDir: arg("--backup-dir") } : {}),
       allowedHosts: allowedHosts.length ? allowedHosts : config.updateAllowedHosts,
+      timeoutMs: config.updateTimeoutMs,
       maxBytes: config.updateMaxBytes,
       dataBackupMaxBytes: config.maxTotalBytes,
       currentVersion: config.appVersion,

server/config.ts

@@ -147,6 +147,7 @@ export function loadConfig() {
     // as 0700 root:root; development/test callers may override --staging-dir.
     updateWorkspaceDir: path.join(installPrefix, ".update-work"),
     updateMaxBytes: integerEnv("TALLYNOTE_UPDATE_MAX_MB", 512) * 1024 * 1024,
+    updateTimeoutMs: integerEnv("TALLYNOTE_UPDATE_TIMEOUT_SECONDS", 30) * 1000,
     // Update checks hit an external release endpoint. Keep a short local
     // cooldown so an authenticated account cannot turn the endpoint into an
     // outbound request flood; set to 0 only for controlled test environments.
@@ -161,6 +162,11 @@ export function loadConfig() {
     exportsDir: path.join(dataDir, "exports"),
     migrationsDir: path.join(projectRoot, "migrations"),
     webDir: path.join(projectRoot, "dist", "web"),
+    // Coarse per-IP request ceiling applied to every /api/* request. It is a
+    // backstop against request floods, not a replacement for the stricter
+    // per-feature limits (login lockout, dangerous-operation re-auth, update
+    // cooldowns), so the default is deliberately generous.
+    apiRateLimitPerMinute: integerEnv("TALLYNOTE_RATE_LIMIT_PER_MINUTE", 600),
     maxFileBytes: integerEnv("TALLYNOTE_MAX_FILE_MB", 20) * 1024 * 1024,
     maxFilesPerRequest: integerEnv("TALLYNOTE_MAX_FILES_PER_REQUEST", 20),
     maxRecordBytes: integerEnv("TALLYNOTE_MAX_RECORD_MB", 100) * 1024 * 1024,

server/rate-limit.ts

@@ -0,0 +1,80 @@
+/**
+ * In-memory, per-key request limiter used as a coarse anti-flood backstop for
+ * the whole HTTP API.
+ *
+ * The semantics are a fixed window per key: the first request of a window
+ * starts the clock, every later request in the same window increments the
+ * counter, and an expired window is reset on the next request. This mirrors
+ * the `login_attempts` window logic already used for login lockouts
+ * (`server/app.ts`), but it never touches the database: a rate limit decision
+ * must stay cheap enough to run on every request.
+ *
+ * Precise controls (per-IP login lockout, dangerous-operation re-auth) remain
+ * in place on top of this limiter; it only stops a client from issuing an
+ * abusive number of requests across all endpoints.
+ */
+
+export type RateLimiterOptions = {
+  /** Maximum number of requests allowed per key inside one window. */
+  limit: number;
+  /** Window length in milliseconds. */
+  windowMs: number;
+  /** Injectable clock so tests can advance time without waiting. */
+  now?: () => number;
+};
+
+export type RateLimitDecision = {
+  allowed: boolean;
+  /** Seconds the caller should wait before retrying; 0 when allowed. */
+  retryAfterSeconds: number;
+};
+
+type Bucket = {
+  count: number;
+  windowStart: number;
+};
+
+/** Run a full sweep every N checks instead of on every call. */
+const SWEEP_INTERVAL_CHECKS = 1000;
+
+export function createRateLimiter(options: RateLimiterOptions) {
+  const { limit, windowMs } = options;
+  if (!Number.isInteger(limit) || limit < 1) throw new Error("rate limit 必须是大于等于 1 的整数");
+  if (!Number.isInteger(windowMs) || windowMs < 1) throw new Error("rate limit 窗口必须是大于等于 1 的整数毫秒数");
+  const now = options.now ?? Date.now;
+  const buckets = new Map<string, Bucket>();
+  let checksSinceSweep = 0;
+
+  return {
+    check(key: string): RateLimitDecision {
+      const current = now();
+      let bucket = buckets.get(key);
+      // A key that is unknown or whose window has already elapsed starts a
+      // fresh window. This also recycles the single key being hit, so an
+      // idle client never leaves a stale counter behind.
+      if (!bucket || current - bucket.windowStart >= windowMs) {
+        bucket = { count: 0, windowStart: current };
+        buckets.set(key, bucket);
+      }
+      // Bounds long-running memory growth: keys that stopped sending traffic
+      // are dropped by an amortized periodic sweep rather than on every call.
+      if (++checksSinceSweep >= SWEEP_INTERVAL_CHECKS) {
+        checksSinceSweep = 0;
+        for (const [candidateKey, candidate] of buckets) {
+          if (current - candidate.windowStart >= windowMs) buckets.delete(candidateKey);
+        }
+      }
+      if (bucket.count >= limit) {
+        return { allowed: false, retryAfterSeconds: Math.max(1, Math.ceil((bucket.windowStart + windowMs - current) / 1000)) };
+      }
+      bucket.count += 1;
+      return { allowed: true, retryAfterSeconds: 0 };
+    },
+    /** Number of tracked keys; used to observe lazy cleanup. */
+    size(): number {
+      return buckets.size;
+    },
+  };
+}
+
+export type RateLimiter = ReturnType<typeof createRateLimiter>;

server/update-service.ts

@@ -1,5 +1,5 @@
-import { lstatSync, realpathSync, readFileSync, unlinkSync } from "node:fs";
-import { chmod, mkdir, rename, writeFile } from "node:fs/promises";
+import { lstatSync, readdirSync, realpathSync, readFileSync, unlinkSync } from "node:fs";
+import { chmod, lstat, mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { createPublicKey, randomUUID, verify as verifySignature } from "node:crypto";
 import type Database from "better-sqlite3";
@@ -8,12 +8,14 @@ import { AppError } from "./errors.js";
 import type { AppConfig } from "./config.js";
 import {
   detectPlatform,
+  downloadReleaseAsset,
+  extractSafeArchive,
   fetchReleaseBytes,
   fetchReleaseMetadata,
   fetchReleaseText,
   isNewerVersion,
+  normalizeReleasePermissions,
   parseSemver,
-  runtimeHashFromLockfile,
   sanitizeAssetName,
   selectReleaseAsset,
   validateHttpsUrl,
@@ -38,6 +40,20 @@ export const ACTIVE_UPDATE_STATUSES: readonly UpdateJobStatus[] = [
 // after the service health check. The runner refreshes its recovery marker as
 // a lease while doing long downloads/backups; only an expired lease permits
 // the server to reclaim an active row.
+/**
+ * Conflict predicate for "another update is already running".
+ *
+ * A row that is `staged` with `operation='download'` is a finished artifact
+ * waiting for an explicit apply, not a running task: the privileged runner only
+ * starts working after the apply request is written. It must therefore not
+ * block a new download. Real in-flight work (queued/downloading/verifying and
+ * the apply phases) remains protected, which is what keeps the apply path's
+ * concurrency guard intact.
+ *
+ * The SQL fragment expects ACTIVE_UPDATE_STATUSES bound as positional params.
+ */
+export const ACTIVE_UPDATE_CONFLICT_SQL = `status IN (${ACTIVE_UPDATE_STATUSES.map(() => "?").join(",")}) AND NOT (status='staged' AND operation='download')`;
+
 export const ORPHANED_UPDATE_TIMEOUT_MS = 5 * 60 * 1000;
 export const QUEUED_UPDATE_TIMEOUT_MS = 25 * 1000;
 
@@ -154,19 +170,19 @@ function signatureAssetFor(metadata: ReleaseMetadata, sums: ReleaseAsset): Relea
 export async function attachSidecarHash(
   metadata: ReleaseMetadata,
   asset: ReleaseAsset,
-  options: { allowedHosts: readonly string[]; baseUrl: string; maxBytes: number; publicKey?: string | undefined; requireSignature?: boolean | undefined },
+  options: { allowedHosts: readonly string[]; baseUrl: string; maxBytes: number; timeoutMs?: number | undefined; publicKey?: string | undefined; requireSignature?: boolean | undefined },
 ): Promise<{ asset: ReleaseAsset; signatureVerified: boolean }> {
   let signatureVerified = false;
   if (asset.sha256 && (!options.publicKey || !options.requireSignature)) return { asset, signatureVerified };
   const sums = metadata.assets.find((candidate) => /^(?:sha256sums?|checksums?)(?:\.txt)?$/i.test(path.basename(candidate.name)));
   if (!sums) return { asset, signatureVerified };
   try {
-    const content = await fetchReleaseText(sums.url, { allowedHosts: options.allowedHosts, baseUrl: options.baseUrl, maxBytes: Math.min(options.maxBytes, 2 * 1024 * 1024) });
+    const content = await fetchReleaseText(sums.url, { allowedHosts: options.allowedHosts, baseUrl: options.baseUrl, maxBytes: Math.min(options.maxBytes, 2 * 1024 * 1024), timeoutMs: options.timeoutMs });
     const sha256 = sha256FromSums(content, asset.name);
     if (options.publicKey) {
       const signatureAsset = signatureAssetFor(metadata, sums);
       if (signatureAsset) {
-        const signature = await fetchReleaseBytes(signatureAsset.url, { allowedHosts: options.allowedHosts, baseUrl: options.baseUrl, maxBytes: 64 * 1024 });
+        const signature = await fetchReleaseBytes(signatureAsset.url, { allowedHosts: options.allowedHosts, baseUrl: options.baseUrl, maxBytes: 64 * 1024, timeoutMs: options.timeoutMs });
         signatureVerified = verifyReleaseSignature(content, signature, options.publicKey);
       }
     }
@@ -183,6 +199,7 @@ function policy(config: AppConfig) {
     allowedHosts: config.updateAllowedHosts,
     baseUrl: config.updateMetadataUrl,
     maxRedirects: 3,
+    timeoutMs: config.updateTimeoutMs,
   } as const;
 }
 
@@ -207,14 +224,9 @@ export async function checkForUpdate(database: Database.Database, config: AppCon
   } catch {
     throw new AppError(502, "UPDATE_CHECK_FAILED", "暂时无法获取最新版本，请稍后重试");
   }
-  let runtimeHash: string | undefined;
-  try {
-    runtimeHash = runtimeHashFromLockfile(readFileSync(path.join(config.projectRoot, "pnpm-lock.yaml")));
-  } catch {
-    // Legacy or source installations may not contain the lockfile. They stay
-    // on the full release asset instead of risking an incompatible runtime.
-  }
-  // Force choosing the full standalone archive so users always get a real, visible streaming download
+  // Always select the complete production archive. The host Node.js runtime
+  // is reused, while the application package remains self-contained and
+  // identical for first installs and in-place updates.
   let asset = selectReleaseAsset(metadata, platform, undefined);
   let signatureVerified = false;
   if (asset) {
@@ -222,6 +234,7 @@ export async function checkForUpdate(database: Database.Database, config: AppCon
       allowedHosts: config.updateAllowedHosts,
       baseUrl: metadataUrl,
       maxBytes: config.updateMaxBytes,
+      timeoutMs: config.updateTimeoutMs,
       publicKey: config.updatePublicKey,
       requireSignature: config.updateRequireSignature,
     });
@@ -426,7 +439,18 @@ function requestJobId(filePath: string): string | null {
   }
 }
 
-function currentReleaseVersion(config: AppConfig): string | null {
+function recoveryStateJobId(filePath: string): string | null {
+  try {
+    const info = lstatSync(filePath);
+    if (!info.isFile() || info.isSymbolicLink()) return null;
+    const match = /^job_id=([0-9a-f-]{36})$/m.exec(readFileSync(filePath, "utf8"));
+    return match?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function currentReleaseVersion(config: AppConfig): string | null {
   try {
     const target = realpathSync(config.currentLink);
     const releases = realpathSync(config.releasesDir);
@@ -437,6 +461,61 @@ function currentReleaseVersion(config: AppConfig): string | null {
   }
 }
 
+/**
+ * Absolute paths that can hold a job's staging workspace. The web download flow
+ * always creates `update-<jobId>`; the privileged runner may additionally use a
+ * `mkdtemp` variant named `update-<jobId>-XXXXXX`.
+ *
+ * `update_jobs.download_path` is deliberately NOT used to rebuild these paths:
+ * it held a bare basename while a download was in flight (rows written by older
+ * versions still store that basename) and the privileged runner NULLs the column
+ * after finalizing a row. Rebuilding from it could delete an unrelated staging
+ * entry that merely shares the basename.
+ */
+function jobWorkspaceCandidates(stagingDir: string, jobId: string): string[] {
+  // Job ids are UUIDs; reject anything that could escape the staging root.
+  if (!jobId || jobId !== path.basename(jobId) || jobId.includes("..")) return [];
+  const stagingRoot = path.resolve(stagingDir);
+  const prefix = `update-${jobId}`;
+  const names = [prefix];
+  try {
+    for (const entry of readdirSync(stagingRoot)) {
+      if (entry.startsWith(`${prefix}-`)) names.push(entry);
+    }
+  } catch {
+    // A missing or unreadable staging directory still leaves the fixed-name
+    // candidate, which is what the web download path uses.
+  }
+  return names.map((name) => path.join(stagingRoot, name));
+}
+
+function isDirectoryNotSymlink(target: string): boolean {
+  try {
+    const info = lstatSync(target);
+    return info.isDirectory() && !info.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** True while at least one staging workspace for the job still exists. */
+export function jobWorkspaceExists(stagingDir: string, jobId: string): boolean {
+  return jobWorkspaceCandidates(stagingDir, jobId).some(isDirectoryNotSymlink);
+}
+
+/**
+ * Remove every staging workspace owned by a job. Deletion is awaited so callers
+ * (and tests) observe a settled filesystem when they return.
+ */
+async function removeJobWorkspaces(stagingDir: string, jobId: string): Promise<void> {
+  for (const candidate of jobWorkspaceCandidates(stagingDir, jobId)) {
+    const info = await lstat(candidate).catch(() => null);
+    // Only real directories are removed; a symlink is never followed.
+    if (!info?.isDirectory() || info.isSymbolicLink()) continue;
+    await rm(candidate, { recursive: true, force: true }).catch(() => undefined);
+  }
+}
+
 /**
  * Release an update row left behind after its privileged runner lease expired.
  * This is deliberately conservative: staged downloads remain available for an
@@ -460,6 +539,12 @@ export function reconcileOrphanedUpdateJobs(database: Database.Database, config:
   const statePresent = stateMtime !== null;
   const requestFresh = requestPresent && now - (requestMtime ?? 0) < ORPHANED_UPDATE_TIMEOUT_MS;
   const stateFresh = statePresent && now - (stateMtime ?? 0) < ORPHANED_UPDATE_TIMEOUT_MS;
+  // The request marker is the hand-off contract between the web process and
+  // the privileged runner. A queued row with a matching, unexpired marker is
+  // still owned by that hand-off even when the runner has not written its
+  // recovery state yet (for example while systemd is starting it).
+  const requestMarkerJobId = requestPresent ? requestJobId(config.updateRequestPath) : null;
+  const stateMarkerJobId = statePresent ? recoveryStateJobId(statePath) : null;
   // A staged download is normally kept for an explicit apply. The one
   // exception is the hand-off window where the API has already changed the
   // operation to `apply` but crashed before writing the request file. That
@@ -468,11 +553,50 @@ export function reconcileOrphanedUpdateJobs(database: Database.Database, config:
   let reconciled = 0;
   const reconciledIds = new Set<string>();
   for (const row of rows) {
+    // A fresh request/state marker means the privileged runner still owns the
+    // hand-off. Do not expire a staged/apply row while the runner is finishing
+    // a successful switch and finalization after a service restart.
+    const matchingFreshRequest = requestMarkerJobId === row.id && requestFresh;
+    const matchingFreshState = stateMarkerJobId === row.id && stateFresh;
+    // A staged archive is actionable only while it is strictly newer than the
+    // release currently serving requests. This can become false when an
+    // administrator upgrades the host by another path (or another operator
+    // completes the same release) before returning to this page. Treat the
+    // archive as an expired terminal task so it cannot keep blocking the
+    // queue or appear as an "apply" action for the current version.
+    const effectiveCurrentVersion = releaseVersion ?? config.appVersion;
+    if (row.status === "staged" && !isNewerVersion(effectiveCurrentVersion, row.version) && !matchingFreshRequest && !matchingFreshState) {
+      const changed = database.transaction(() => {
+        const result = database.prepare(`
+          UPDATE update_jobs
+          SET status='failed', error_message=?, completed_at=?, updated_at=?
+          WHERE id=? AND status='staged'
+        `).run("暂存更新已过期，当前版本无需再次升级", now, now, row.id);
+        if (result.changes !== 1) return false;
+        writeAudit(database, {
+          requestId: row.requestId || randomUUID(),
+          actorAdminId: row.adminId,
+          action: "update.reconciled",
+          targetType: "update",
+          targetId: row.id,
+          outcome: "failure",
+          before: { status: row.status, operation: row.operation, version: row.version },
+          after: { status: "failed", version: row.version, reason: "staged_version_not_newer" },
+        });
+        return true;
+      })();
+      if (changed) {
+        reconciled += 1;
+        reconciledIds.add(row.id);
+      }
+      continue;
+    }
     // A request that never gets claimed by the root runner must not remain in
     // the UI as an endless "queued" task. Once the short hand-off window has
     // elapsed and no recovery marker exists, release the queue explicitly;
     // a fresh state marker proves that the runner has already claimed it.
-    if (row.status === "queued" && typeof row.updatedAt === "number" && !stateFresh && now - row.updatedAt >= QUEUED_UPDATE_TIMEOUT_MS) {
+    if (row.status === "queued" && typeof row.updatedAt === "number" && !matchingFreshState && now - row.updatedAt >= QUEUED_UPDATE_TIMEOUT_MS) {
+      if (matchingFreshRequest) continue;
       const changed = database.transaction(() => {
         const result = database.prepare(`
           UPDATE update_jobs
@@ -503,7 +627,37 @@ export function reconcileOrphanedUpdateJobs(database: Database.Database, config:
     // A stale request/state marker therefore no longer protects an orphaned
     // row forever, while a fresh marker remains owned by the runner.
     if (row.status === "staged") {
-      if (row.operation !== "apply" || requestFresh || stateFresh) continue;
+      // A staged row that lost its payload (the staging janitor removes
+      // `update-*` entries after 24h, and a manual cleanup has the same effect)
+      // can never be applied or completed. Report it instead of leaving a
+      // permanently actionable row that fails at apply time.
+      if (!matchingFreshRequest && !matchingFreshState && !jobWorkspaceExists(config.stagingDir, row.id)) {
+        const changed = database.transaction(() => {
+          const result = database.prepare(`
+            UPDATE update_jobs
+            SET status='failed', error_message=?, completed_at=?, updated_at=?
+            WHERE id=? AND status='staged' AND updated_at=?
+          `).run("暂存的更新文件已不存在，请重新下载更新包", now, now, row.id, row.updatedAt);
+          if (result.changes !== 1) return false;
+          writeAudit(database, {
+            requestId: row.requestId || randomUUID(),
+            actorAdminId: row.adminId,
+            action: "update.reconciled",
+            targetType: "update",
+            targetId: row.id,
+            outcome: "failure",
+            before: { status: row.status, operation: row.operation, version: row.version },
+            after: { status: "failed", version: row.version, reason: "staged_workspace_missing" },
+          });
+          return true;
+        })();
+        if (changed) {
+          reconciled += 1;
+          reconciledIds.add(row.id);
+        }
+        continue;
+      }
+      if (row.operation !== "apply" || matchingFreshRequest || matchingFreshState) continue;
       const changed = database.transaction(() => {
         const result = database.prepare(`
           UPDATE update_jobs
@@ -529,7 +683,7 @@ export function reconcileOrphanedUpdateJobs(database: Database.Database, config:
       }
       continue;
     }
-    if (requestFresh || stateFresh) continue;
+    if (matchingFreshRequest || matchingFreshState) continue;
     const status: "completed" | "failed" = row.status === "applying" && releaseVersion === row.version ? "completed" : "failed";
     const errorMessage = status === "failed" ? "更新任务超时，已释放更新队列" : null;
     const changed = database.transaction(() => {
@@ -578,23 +732,39 @@ export function reconcileOrphanedUpdateJobs(database: Database.Database, config:
   return reconciled;
 }
 
-export function cancelUpdateJob(
+/**
+ * Rows an administrator may cancel from the web UI.
+ *
+ * `staged` is cancellable only while the row still belongs to the download
+ * stage. A staged row whose operation is already `apply` has been handed to the
+ * privileged runner (stop/backup/switch) and must not be interrupted here.
+ */
+const CANCELLABLE_JOB_SQL = "(status IN ('queued', 'downloading') OR (status='staged' AND operation='download'))";
+
+export function isCancellableUpdateJob(status: UpdateJobStatus, operation: string): boolean {
+  if (status === "queued" || status === "downloading") return true;
+  return status === "staged" && operation === "download";
+}
+
+export async function cancelUpdateJob(
   database: Database.Database,
   config: AppConfig,
   adminId: string,
   requestId: string,
   jobId?: string,
-): { cancelled: boolean; message?: string } {
+): Promise<{ cancelled: boolean; message?: string }> {
+  type CancelRow = { id: string; status: UpdateJobStatus; operation: string; version: string; adminId: string | null };
+  const columns = "id, status, operation, version, admin_id AS adminId";
   const job = jobId
-    ? database.prepare("SELECT id, status, operation, version, admin_id AS adminId, download_path AS downloadPath FROM update_jobs WHERE id=?").get(jobId) as { id: string; status: UpdateJobStatus; operation: string; version: string; adminId: string | null; downloadPath: string | null } | undefined
-    : database.prepare("SELECT id, status, operation, version, admin_id AS adminId, download_path AS downloadPath FROM update_jobs WHERE status IN ('queued', 'downloading') ORDER BY created_at DESC LIMIT 1").get() as { id: string; status: UpdateJobStatus; operation: string; version: string; adminId: string | null; downloadPath: string | null } | undefined;
+    ? database.prepare(`SELECT ${columns} FROM update_jobs WHERE id=? AND admin_id=?`).get(jobId, adminId) as CancelRow | undefined
+    : database.prepare(`SELECT ${columns} FROM update_jobs WHERE admin_id=? AND ${CANCELLABLE_JOB_SQL} ORDER BY created_at DESC LIMIT 1`).get(adminId) as CancelRow | undefined;
 
   if (!job) return { cancelled: false, message: "当前没有处于等待调度或下载中的更新任务" };
-  if (job.status !== "queued" && job.status !== "downloading") return { cancelled: false, message: "任务已进入就绪或切换阶段，无法取消" };
+  if (!isCancellableUpdateJob(job.status, job.operation)) return { cancelled: false, message: "任务已进入就绪或切换阶段，无法取消" };
 
   const now = Date.now();
   const changed = database.transaction(() => {
-    const result = database.prepare("UPDATE update_jobs SET status='cancelled', error_message='已手动取消更新', completed_at=?, updated_at=? WHERE id=? AND status IN ('queued', 'downloading')").run(now, now, job.id);
+    const result = database.prepare(`UPDATE update_jobs SET status='cancelled', error_message='已手动取消更新', completed_at=?, updated_at=? WHERE id=? AND admin_id=? AND ${CANCELLABLE_JOB_SQL}`).run(now, now, job.id, adminId);
     if (result.changes !== 1) return false;
     writeAudit(database, {
       requestId,
@@ -610,12 +780,145 @@ export function cancelUpdateJob(
   })();
 
   if (changed) {
-    forceRemoveRequest(config.updateRequestPath);
-    if (job.downloadPath) {
-      const target = path.isAbsolute(job.downloadPath) ? job.downloadPath : path.join(config.stagingDir, job.downloadPath);
-      import("node:fs/promises").then(({ rm }) => rm(target, { recursive: true, force: true })).catch(() => {});
-    }
+    // The request marker is shared by the privileged runner. Never remove a
+    // newer/different administrator's request while cancelling this row.
+    if (requestJobId(config.updateRequestPath) === job.id) forceRemoveRequest(config.updateRequestPath);
+    // Locate the workspace by job id. `download_path` is not a reliable source
+    // (older rows hold a bare archive basename and the runner NULLs the column
+    // after finalizing), and a basename lookup could delete an unrelated entry.
+    // The await keeps the caller from racing a still-running download writer.
+    await removeJobWorkspaces(config.stagingDir, job.id);
     return { cancelled: true };
   }
   return { cancelled: false, message: "取消失败，任务状态可能已改变" };
 }
+
+/**
+ * Download, verify and stage a release archive in the web process (non-root).
+ * The root runner only needs to apply (stop/backup/switch/restart) afterwards.
+ *
+ * This function runs asynchronously outside the request lifecycle. It updates
+ * the job row in the database so the frontend can poll progress. A successful
+ * download only becomes staged; applying it is a separate, explicit action
+ * that the administrator submits after reviewing the verification result.
+ */
+export async function downloadAndStageUpdate(
+  database: Database.Database,
+  config: AppConfig,
+  jobId: string,
+  adminId: string,
+  version: string,
+  assetUrl: string,
+  assetName: string,
+  expectedSha256: string,
+  metadataUrl: string,
+): Promise<void> {
+  const stagingBase = path.resolve(config.stagingDir);
+  const workspace = path.join(stagingBase, `update-${jobId}`);
+  try {
+    await mkdir(workspace, { recursive: true, mode: 0o700 });
+    const archiveName = assetName.endsWith(".tar.gz") || assetName.endsWith(".tgz") ? assetName : `${assetName}.tar.gz`;
+    const archivePath = path.join(workspace, archiveName);
+
+    // Claim the job: transition queued -> downloading. If the job was
+    // cancelled or claimed by another caller, abort immediately.
+    // `download_path` always holds an absolute workspace path, both while the
+    // download runs and after the job is staged. Callers must not derive paths
+    // from it (the privileged runner NULLs it once it finalizes the row), but a
+    // single semantic keeps the column debuggable.
+    const claim = database.prepare(
+      "UPDATE update_jobs SET status='downloading', download_started_at=?, started_at=?, download_path=?, updated_at=? WHERE id=? AND status='queued'",
+    ).run(Date.now(), Date.now(), workspace, Date.now(), jobId);
+    if (claim.changes !== 1) return;
+
+    const progressStartedAt = Date.now();
+    let lastProgressWrite = 0;
+    const downloaded = await downloadReleaseAsset(assetUrl, archivePath, {
+      allowedHosts: config.updateAllowedHosts,
+      baseUrl: config.updateMetadataUrl,
+      maxBytes: config.updateMaxBytes,
+      timeoutMs: config.updateTimeoutMs,
+      onProgress: (downloadedBytes, totalBytes) => {
+        const now = Date.now();
+        if (now - lastProgressWrite < 250) return;
+        lastProgressWrite = now;
+        const elapsed = Math.max(1, now - progressStartedAt);
+        const speedBps = Math.round(downloadedBytes * 1000 / elapsed);
+        database.prepare(
+          "UPDATE update_jobs SET downloaded_bytes=?, size_bytes=COALESCE(?, size_bytes), download_speed_bps=?, updated_at=? WHERE id=? AND status='downloading'",
+        ).run(downloadedBytes, totalBytes, speedBps, now, jobId);
+      },
+    });
+
+    // Final progress write
+    const finishedAt = Date.now();
+    const elapsed = Math.max(1, finishedAt - progressStartedAt);
+    database.prepare(
+      "UPDATE update_jobs SET downloaded_bytes=?, size_bytes=?, download_speed_bps=?, updated_at=? WHERE id=? AND status='downloading'",
+    ).run(downloaded.size, downloaded.size, Math.round(downloaded.size * 1000 / elapsed), finishedAt, jobId);
+
+    // SHA-256 verification
+    database.prepare(
+      "UPDATE update_jobs SET status='verifying', actual_sha256=?, size_bytes=?, updated_at=? WHERE id=? AND status='downloading'",
+    ).run(downloaded.sha256, downloaded.size, Date.now(), jobId);
+
+    if (expectedSha256 && downloaded.sha256 !== expectedSha256) {
+      throw new Error("更新文件 SHA-256 校验失败");
+    }
+
+    // Extract archive to payload directory
+    const payloadDir = path.join(workspace, "payload");
+    await extractSafeArchive(archivePath, payloadDir);
+    await normalizeReleasePermissions(payloadDir);
+
+    const embeddedRuntime = await lstat(path.join(payloadDir, "runtime")).catch(() => null);
+    if (embeddedRuntime) throw new Error("发布包不应包含 Node.js runtime");
+
+    // Verify payload contains dist directory
+    const payloadInfo = await lstat(path.join(payloadDir, "dist")).catch(() => null);
+    if (!payloadInfo?.isDirectory() || payloadInfo.isSymbolicLink()) {
+      throw new Error("发布包缺少 dist 目录");
+    }
+
+    // Transition to staged
+    const staged = database.prepare(
+      "UPDATE update_jobs SET status='staged', operation='download', actual_sha256=?, size_bytes=?, download_path=?, updated_at=? WHERE id=? AND status IN ('verifying', 'downloading')",
+    ).run(downloaded.sha256, downloaded.size, workspace, Date.now(), jobId);
+    if (staged.changes !== 1) {
+      // The row was cancelled or claimed elsewhere (status no longer
+      // verifying/downloading). This process owns the workspace it created, so
+      // remove it instead of leaking the payload into the staging directory.
+      await rm(workspace, { recursive: true, force: true }).catch(() => undefined);
+      return;
+    }
+
+    writeAudit(database, {
+      requestId: `download:${jobId}`,
+      actorAdminId: adminId,
+      action: "update.staged",
+      targetType: "update",
+      targetId: jobId,
+      after: { version, sha256: downloaded.sha256, size: downloaded.size },
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "下载或校验失败";
+    try {
+      database.prepare(
+        "UPDATE update_jobs SET status='failed', error_message=?, updated_at=? WHERE id=? AND status IN ('queued', 'downloading', 'verifying')",
+      ).run(message, Date.now(), jobId);
+      writeAudit(database, {
+        requestId: `download:${jobId}`,
+        actorAdminId: adminId,
+        action: "update.download_failed",
+        targetType: "update",
+        targetId: jobId,
+        outcome: "failure",
+        metadata: { error: message },
+      });
+    } catch {
+      // The database may be closed (e.g. during test cleanup or process
+      // shutdown). The workspace cleanup below still runs unconditionally.
+    }
+    await rm(workspace, { recursive: true, force: true }).catch(() => undefined);
+  }
+}

server/update.ts

@@ -59,8 +59,22 @@ export type UrlPolicy = {
   /** When allowedHosts is omitted, requests are constrained to this URL's host. */
   baseUrl?: string | URL | undefined;
   maxRedirects?: number | undefined;
+  /** Maximum time allowed for one metadata/sidecar/archive request. */
+  timeoutMs?: number | undefined;
 };
 
+/** Release an unread response body before following a redirect or returning
+ * an error. Undici keeps the underlying connection associated with a body
+ * until it is consumed or cancelled; leaving it open can exhaust sockets when
+ * an update feed repeatedly returns errors or oversized responses. */
+async function cancelResponseBody(response: Response): Promise<void> {
+  try {
+    await response.body?.cancel();
+  } catch {
+    // The body may already be consumed/closed. Cancellation is best effort.
+  }
+}
+
 function invalidVersion(): never {
   throw new Error("更新版本号无效");
 }
@@ -157,8 +171,37 @@ function metadataError(): Error {
 }
 
 const DEFAULT_METADATA_MAX_BYTES = 2 * 1024 * 1024;
+/** Maximum time allowed for one update HTTP request, including its body. */
+export const DEFAULT_UPDATE_TIMEOUT_MS = 30_000;
 export const RELEASE_NOTES_MAX_BYTES = 64 * 1024;
 
+type UpdateFetchOptions = {
+  fetchImpl?: typeof fetch | undefined;
+  maxBytes?: number | undefined;
+  timeoutMs?: number | undefined;
+};
+
+function updateTimeoutMs(options: UpdateFetchOptions): number {
+  if (options.timeoutMs !== undefined) {
+    if (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0) throw new Error("更新请求超时配置无效");
+    return options.timeoutMs;
+  }
+  const configuredSeconds = process.env.TALLYNOTE_UPDATE_TIMEOUT_SECONDS;
+  if (configuredSeconds !== undefined && configuredSeconds.trim() !== "") {
+    const seconds = Number(configuredSeconds);
+    if (!Number.isSafeInteger(seconds) || seconds <= 0) throw new Error("TALLYNOTE_UPDATE_TIMEOUT_SECONDS 必须是大于 0 的整数");
+    return seconds * 1000;
+  }
+  return DEFAULT_UPDATE_TIMEOUT_MS;
+}
+
+function beginUpdateRequest(options: UpdateFetchOptions): { signal: AbortSignal; clear: () => void } {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), updateTimeoutMs(options));
+  timer.unref?.();
+  return { signal: controller.signal, clear: () => clearTimeout(timer) };
+}
+
 function releaseNotesText(value: unknown): string | undefined {
   if (typeof value !== "string" || value.length === 0) return undefined;
   // Gitea exposes both Markdown (body/body_html) and releaseNotes depending on
@@ -210,20 +253,29 @@ function releaseResourceUrl(value: string, current: URL, options: UrlPolicy): st
 }
 
 /** Read a fetch body without ever buffering more than the caller's bound. */
-async function readBoundedResponse(response: Response, maxBytes: number, tooLargeMessage: string): Promise<Buffer> {
+async function readBoundedResponse(response: Response, maxBytes: number, tooLargeMessage: string, signal?: AbortSignal): Promise<Buffer> {
   if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) throw new Error("响应大小限制无效");
   const contentLength = response.headers.get("content-length");
   if (contentLength !== null) {
     const declared = Number(contentLength);
-    if (Number.isFinite(declared) && declared > maxBytes) throw new Error(tooLargeMessage);
+    if (Number.isFinite(declared) && declared > maxBytes) {
+      await cancelResponseBody(response);
+      throw new Error(tooLargeMessage);
+    }
   }
   if (!response.body) return Buffer.alloc(0);
   const reader = response.body.getReader();
   const chunks: Buffer[] = [];
   let total = 0;
+  let onAbort: (() => void) | undefined;
+  const abort = signal ? new Promise<never>((_, reject) => {
+    onAbort = () => reject(new Error("更新请求超时"));
+    if (signal.aborted) onAbort();
+    else signal.addEventListener("abort", onAbort, { once: true });
+  }) : undefined;
   try {
     for (;;) {
-      const result = await reader.read();
+      const result = await (abort ? Promise.race([reader.read(), abort]) : reader.read());
       if (result.done) break;
       const chunk = Buffer.from(result.value);
       if (chunk.length > maxBytes - total) {
@@ -233,7 +285,11 @@ async function readBoundedResponse(response: Response, maxBytes: number, tooLarg
       total += chunk.length;
       chunks.push(chunk);
     }
+  } catch (error) {
+    await reader.cancel().catch(() => undefined);
+    throw error;
   } finally {
+    if (signal && onAbort) signal.removeEventListener("abort", onAbort);
     reader.releaseLock();
   }
   return Buffer.concat(chunks, total);
@@ -241,84 +297,78 @@ async function readBoundedResponse(response: Response, maxBytes: number, tooLarg
 
 export async function fetchReleaseMetadata(
   metadataUrl: string | URL,
-  options: UrlPolicy & { fetchImpl?: typeof fetch | undefined; maxBytes?: number | undefined } = {},
+  options: UrlPolicy & UpdateFetchOptions = {},
 ): Promise<ReleaseMetadata> {
   const fetchImpl = options.fetchImpl ?? fetch;
   let current = validateHttpsUrl(metadataUrl, options);
   const maxRedirects = options.maxRedirects ?? 3;
   let response: Response;
   for (let redirects = 0; ; redirects += 1) {
+    const request = beginUpdateRequest(options);
     try {
-      response = await fetchImpl(current, { method: "GET", redirect: "manual", headers: { accept: "application/json" } });
+      response = await fetchImpl(current, { method: "GET", redirect: "manual", headers: { accept: "application/json" }, signal: request.signal });
     } catch {
+      request.clear();
       throw metadataError();
     }
-    if (response.status < 300 || response.status >= 400) break;
+    if (response.status < 300 || response.status >= 400) {
+      try {
+        if (response.status < 200 || response.status >= 300) {
+          await cancelResponseBody(response);
+          throw metadataError();
+        }
+        const maxBytes = Math.min(options.maxBytes ?? DEFAULT_METADATA_MAX_BYTES, DEFAULT_METADATA_MAX_BYTES);
+        const body = await readBoundedResponse(response, maxBytes, "更新发布信息过大", request.signal);
+        const payload: unknown = JSON.parse(body.toString("utf8"));
+        if (!payload || typeof payload !== "object") throw metadataError();
+        const item = payload as Record<string, unknown>;
+        const rawVersion = typeof item.version === "string" ? item.version : typeof item.tag_name === "string" ? item.tag_name : typeof item.tagName === "string" ? item.tagName : undefined;
+        if (!rawVersion) throw metadataError();
+        const version = parseSemver(rawVersion);
+        if (typeof item.tag_name === "string" && compareSemver(version, item.tag_name) !== 0) throw metadataError();
+        const assetsRaw = Array.isArray(item.assets) ? item.assets : [];
+        const assets: ReleaseAsset[] = [];
+        for (const raw of assetsRaw) {
+          if (!raw || typeof raw !== "object") continue;
+          const asset = raw as Record<string, unknown>;
+          const name = typeof asset.name === "string" ? asset.name : undefined;
+          const url = typeof asset.url === "string" ? asset.url : typeof asset.browser_download_url === "string" ? asset.browser_download_url : undefined;
+          if (!name || !url) continue;
+          let sha256: string | undefined;
+          const digest = typeof asset.sha256 === "string" ? asset.sha256 : typeof asset.digest === "string" ? asset.digest : undefined;
+          if (digest) {
+            const candidate = digest.replace(/^sha256:/i, "").toLowerCase();
+            if (/^[a-f0-9]{64}$/.test(candidate)) sha256 = candidate;
+          }
+          assets.push({ name, url: releaseResourceUrl(url, current, options), ...(sha256 ? { sha256 } : {}), ...(typeof asset.size === "number" && Number.isSafeInteger(asset.size) && asset.size >= 0 ? { size: asset.size } : {}) });
+        }
+        const notes = releaseNotesText(item.body ?? item.releaseNotes ?? item.release_notes ?? item.body_html);
+        const releaseName = releaseNameText(item.name ?? item.releaseName);
+        let releaseUrl: string | undefined;
+        if (typeof item.html_url === "string" || typeof item.url === "string") {
+          try { releaseUrl = releaseResourceUrl(typeof item.html_url === "string" ? item.html_url : item.url as string, current, options); } catch { /* optional */ }
+        }
+        return {
+          version: `${version.major}.${version.minor}.${version.patch}${version.prerelease.length ? `-${version.prerelease.join(".")}` : ""}${version.build.length ? `+${version.build.join(".")}` : ""}`,
+          ...(typeof item.tag_name === "string" ? { tagName: item.tag_name } : {}), ...(releaseName ? { releaseName } : {}), ...(typeof item.published_at === "string" ? { publishedAt: item.published_at } : {}), ...(notes ? { notes } : {}), ...(releaseUrl ? { releaseUrl } : {}), assets,
+        };
+      } catch { throw metadataError(); }
+      finally { request.clear(); }
+    }
+    await cancelResponseBody(response);
+    request.clear();
     if (redirects >= maxRedirects) throw metadataError();
     const location = response.headers.get("location");
     if (!location) throw metadataError();
     current = validateHttpsUrl(new URL(location, current), options.baseUrl ? options : { ...options, baseUrl: current });
   }
-  if (response.status < 200 || response.status >= 300) throw metadataError();
-  let payload: unknown;
-  try {
-    const maxBytes = Math.min(options.maxBytes ?? DEFAULT_METADATA_MAX_BYTES, DEFAULT_METADATA_MAX_BYTES);
-    const body = await readBoundedResponse(response, maxBytes, "更新发布信息过大");
-    payload = JSON.parse(body.toString("utf8"));
-  } catch { throw metadataError(); }
-  if (!payload || typeof payload !== "object") throw metadataError();
-  const item = payload as Record<string, unknown>;
-  const rawVersion = typeof item.version === "string" ? item.version : typeof item.tag_name === "string" ? item.tag_name : typeof item.tagName === "string" ? item.tagName : undefined;
-  if (!rawVersion) throw metadataError();
-  const version = parseSemver(rawVersion);
-  if (typeof item.tag_name === "string") {
-    try {
-      if (compareSemver(version, item.tag_name) !== 0) throw metadataError();
-    } catch {
-      throw metadataError();
-    }
-  }
-  const assetsRaw = Array.isArray(item.assets) ? item.assets : [];
-  const assets: ReleaseAsset[] = [];
-  for (const raw of assetsRaw) {
-    if (!raw || typeof raw !== "object") continue;
-    const asset = raw as Record<string, unknown>;
-    const name = typeof asset.name === "string" ? asset.name : undefined;
-    const url = typeof asset.url === "string" ? asset.url : typeof asset.browser_download_url === "string" ? asset.browser_download_url : undefined;
-    if (!name || !url) continue;
-    let sha256: string | undefined;
-    const digest = typeof asset.sha256 === "string" ? asset.sha256 : typeof asset.digest === "string" ? asset.digest : undefined;
-    if (digest) {
-      const candidate = digest.replace(/^sha256:/i, "").toLowerCase();
-      if (/^[a-f0-9]{64}$/.test(candidate)) sha256 = candidate;
-    }
-    assets.push({ name, url: releaseResourceUrl(url, current, options), ...(sha256 ? { sha256 } : {}), ...(typeof asset.size === "number" && Number.isSafeInteger(asset.size) && asset.size >= 0 ? { size: asset.size } : {}) });
-  }
-  const notes = releaseNotesText(item.body ?? item.releaseNotes ?? item.release_notes ?? item.body_html);
-  const releaseName = releaseNameText(item.name ?? item.releaseName);
-  let releaseUrl: string | undefined;
-  if (typeof item.html_url === "string" || typeof item.url === "string") {
-    try {
-      const candidate = typeof item.html_url === "string" ? item.html_url : item.url as string;
-      releaseUrl = releaseResourceUrl(candidate, current, options);
-    } catch { /* omit invalid optional release page URL */ }
-  }
-  return {
-    version: `${version.major}.${version.minor}.${version.patch}${version.prerelease.length ? `-${version.prerelease.join(".")}` : ""}${version.build.length ? `+${version.build.join(".")}` : ""}`,
-    ...(typeof item.tag_name === "string" ? { tagName: item.tag_name } : {}),
-    ...(releaseName ? { releaseName } : {}),
-    ...(typeof item.published_at === "string" ? { publishedAt: item.published_at } : {}),
-    ...(notes ? { notes } : {}),
-    ...(releaseUrl ? { releaseUrl } : {}),
-    assets,
-  };
 }
 
 /** Fetch a small text sidecar (for example SHA256SUMS) with the same
  * redirect, HTTPS and host policy used for release metadata. */
 export async function fetchReleaseText(
   textUrl: string | URL,
-  options: UrlPolicy & { fetchImpl?: typeof fetch | undefined; maxBytes?: number | undefined } = {},
+  options: UrlPolicy & UpdateFetchOptions = {},
 ): Promise<string> {
   const fetchImpl = options.fetchImpl ?? fetch;
   let current = validateHttpsUrl(textUrl, options);
@@ -328,27 +378,32 @@ export async function fetchReleaseText(
   const maxRedirects = options.maxRedirects ?? 3;
   let response: Response;
   for (let redirects = 0; ; redirects += 1) {
+    const request = beginUpdateRequest(options);
     try {
-      response = await fetchImpl(current, { method: "GET", redirect: "manual" });
+      response = await fetchImpl(current, { method: "GET", redirect: "manual", signal: request.signal });
     } catch {
+      request.clear();
       throw new Error("更新校验文件下载失败");
     }
-    if (response.status < 300 || response.status >= 400) break;
+    if (response.status < 300 || response.status >= 400) {
+      if (response.status < 200 || response.status >= 300) { await cancelResponseBody(response); request.clear(); throw new Error("更新校验文件下载失败"); }
+      const declared = Number(response.headers.get("content-length") ?? 0);
+      const maxBytes = options.maxBytes ?? 1024 * 1024;
+      if (declared > maxBytes) { await cancelResponseBody(response); request.clear(); throw new Error("更新校验文件过大"); }
+      try {
+        return (await readBoundedResponse(response, maxBytes, "更新校验文件过大", request.signal)).toString("utf8");
+      } catch (error) {
+        if (error instanceof Error && error.message === "更新校验文件过大") throw error;
+        throw new Error("更新校验文件下载失败");
+      } finally { request.clear(); }
+    }
+    await cancelResponseBody(response);
+    request.clear();
     if (redirects >= maxRedirects) throw new Error("更新校验文件下载失败");
     const location = response.headers.get("location");
     if (!location) throw new Error("更新校验文件下载失败");
     current = validateHttpsUrl(new URL(location, current), redirectPolicy);
   }
-  if (response.status < 200 || response.status >= 300) throw new Error("更新校验文件下载失败");
-  const declared = Number(response.headers.get("content-length") ?? 0);
-  const maxBytes = options.maxBytes ?? 1024 * 1024;
-  if (declared > maxBytes) throw new Error("更新校验文件过大");
-  try {
-    return (await readBoundedResponse(response, maxBytes, "更新校验文件过大")).toString("utf8");
-  } catch (error) {
-    if (error instanceof Error && error.message === "更新校验文件过大") throw error;
-    throw new Error("更新校验文件下载失败");
-  }
 }
 
 /** Fetch a bounded binary sidecar (for example an Ed25519 detached
@@ -356,7 +411,7 @@ export async function fetchReleaseText(
  * this separate from fetchReleaseText. */
 export async function fetchReleaseBytes(
   bytesUrl: string | URL,
-  options: UrlPolicy & { fetchImpl?: typeof fetch | undefined; maxBytes?: number | undefined } = {},
+  options: UrlPolicy & UpdateFetchOptions = {},
 ): Promise<Buffer> {
   const fetchImpl = options.fetchImpl ?? fetch;
   let current = validateHttpsUrl(bytesUrl, options);
@@ -366,27 +421,32 @@ export async function fetchReleaseBytes(
   const maxRedirects = options.maxRedirects ?? 3;
   let response: Response;
   for (let redirects = 0; ; redirects += 1) {
+    const request = beginUpdateRequest(options);
     try {
-      response = await fetchImpl(current, { method: "GET", redirect: "manual" });
+      response = await fetchImpl(current, { method: "GET", redirect: "manual", signal: request.signal });
     } catch {
+      request.clear();
       throw new Error("更新签名下载失败");
     }
-    if (response.status < 300 || response.status >= 400) break;
+    if (response.status < 300 || response.status >= 400) {
+      if (response.status < 200 || response.status >= 300) { await cancelResponseBody(response); request.clear(); throw new Error("更新签名下载失败"); }
+      const declared = Number(response.headers.get("content-length") ?? 0);
+      const maxBytes = options.maxBytes ?? 64 * 1024;
+      if (declared > maxBytes) { await cancelResponseBody(response); request.clear(); throw new Error("更新签名文件过大"); }
+      try {
+        return await readBoundedResponse(response, maxBytes, "更新签名文件过大", request.signal);
+      } catch (error) {
+        if (error instanceof Error && error.message === "更新签名文件过大") throw error;
+        throw new Error("更新签名下载失败");
+      } finally { request.clear(); }
+    }
+    await cancelResponseBody(response);
+    request.clear();
     if (redirects >= maxRedirects) throw new Error("更新签名下载失败");
     const location = response.headers.get("location");
     if (!location) throw new Error("更新签名下载失败");
     current = validateHttpsUrl(new URL(location, current), redirectPolicy);
   }
-  if (response.status < 200 || response.status >= 300) throw new Error("更新签名下载失败");
-  const declared = Number(response.headers.get("content-length") ?? 0);
-  const maxBytes = options.maxBytes ?? 64 * 1024;
-  if (declared > maxBytes) throw new Error("更新签名文件过大");
-  try {
-    return await readBoundedResponse(response, maxBytes, "更新签名文件过大");
-  } catch (error) {
-    if (error instanceof Error && error.message === "更新签名文件过大") throw error;
-    throw new Error("更新签名下载失败");
-  }
 }
 
 export function selectReleaseAsset(release: ReleaseMetadata, platform = detectPlatform(), runtimeHash?: string): ReleaseAsset | undefined {
@@ -438,7 +498,7 @@ export async function verifySha256(filePath: string, expected: string): Promise<
 export async function downloadReleaseAsset(
   url: string | URL,
   destination: string,
-  options: UrlPolicy & { fetchImpl?: typeof fetch | undefined; maxBytes?: number | undefined; onProgress?: ((downloadedBytes: number, totalBytes: number | null) => void) | undefined } = {},
+  options: UrlPolicy & UpdateFetchOptions & { onProgress?: ((downloadedBytes: number, totalBytes: number | null) => void) | undefined } = {},
 ): Promise<{ size: number; sha256: string }> {
   const fetchImpl = options.fetchImpl ?? fetch;
   let current = validateHttpsUrl(url, options);
@@ -448,22 +508,32 @@ export async function downloadReleaseAsset(
   const maxRedirects = options.maxRedirects ?? 3;
   let response: Response;
   for (let redirects = 0; ; redirects += 1) {
+    const request = beginUpdateRequest(options);
     try {
-      response = await fetchImpl(current, { method: "GET", redirect: "manual" });
+      response = await fetchImpl(current, { method: "GET", redirect: "manual", signal: request.signal });
     } catch {
+      request.clear();
       throw new Error("更新文件下载失败");
     }
-    if (response.status < 300 || response.status >= 400) break;
+    if (response.status < 300 || response.status >= 400) { request.clear(); break; }
+    await cancelResponseBody(response);
+    request.clear();
     if (redirects >= maxRedirects) throw new Error("更新文件下载失败");
     const location = response.headers.get("location");
     if (!location) throw new Error("更新文件下载失败");
     current = validateHttpsUrl(new URL(location, current), redirectPolicy);
   }
-  if (response.status < 200 || response.status >= 300 || !response.body) throw new Error("更新文件下载失败");
+  if (response.status < 200 || response.status >= 300 || !response.body) {
+    await cancelResponseBody(response);
+    throw new Error("更新文件下载失败");
+  }
   const declared = Number(response.headers.get("content-length") ?? 0);
   const totalBytes = Number.isSafeInteger(declared) && declared > 0 ? declared : null;
   const maxBytes = options.maxBytes ?? 512 * 1024 * 1024;
-  if (declared > maxBytes) throw new Error("更新文件超过大小限制");
+  if (declared > maxBytes) {
+    await cancelResponseBody(response);
+    throw new Error("更新文件超过大小限制");
+  }
   await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
   const temporary = `${destination}.part-${randomUUID()}`;
   let size = 0;
@@ -475,8 +545,10 @@ export async function downloadReleaseAsset(
     hash.update(chunk);
     callback(null, chunk);
   } });
+  const request = beginUpdateRequest(options);
   try {
-    await pipeline(Readable.fromWeb(response.body as import("node:stream/web").ReadableStream), meter, createWriteStream(temporary, { flags: "wx", mode: 0o600 }));
+    const source = Readable.fromWeb(response.body as import("node:stream/web").ReadableStream, { signal: request.signal });
+    await pipeline(source, meter, createWriteStream(temporary, { flags: "wx", mode: 0o600 }));
     const fd = await open(temporary, "r");
     await fd.sync();
     await fd.close();
@@ -484,6 +556,8 @@ export async function downloadReleaseAsset(
   } catch (error) {
     await import("node:fs/promises").then(({ rm }) => rm(temporary, { force: true })).catch(() => undefined);
     throw error instanceof Error && error.message.startsWith("更新文件") ? error : new Error("更新文件下载失败");
+  } finally {
+    request.clear();
   }
   return { size, sha256: hash.digest("hex") };
 }
@@ -926,7 +1000,7 @@ export async function normalizeReleasePermissions(rootPath: string): Promise<voi
         await walk(target);
       } else if (entry.isFile()) {
         const relative = path.relative(root, target).split(path.sep).join("/");
-        const executable = relative.startsWith("bin/") || relative.startsWith("scripts/") || relative.startsWith("runtime/bin/");
+        const executable = relative.startsWith("bin/") || relative.startsWith("scripts/");
         await chmod(target, executable ? 0o755 : 0o644);
       } else {
         throw new Error("发布包包含不受支持的文件类型");

systemd/tallynote-update.service

@@ -1,20 +1,20 @@
 [Unit]
 Description=TallyNote privileged release updater
-After=network-online.target
-Wants=network-online.target
-
 [Service]
 Type=oneshot
 User=root
 Group=root
 WorkingDirectory=/opt/tallynote/current
 EnvironmentFile=-/etc/tallynote/tallynote.env
+Environment=TALLYNOTE_CONFIG_DIR=/etc/tallynote
 ExecStart=/usr/local/libexec/tallynote-update-runner
-Environment=PATH=/usr/sbin:/usr/bin:/sbin:/bin
-# Downloads, archive validation and data backups can exceed systemd's 90s
+Environment=PATH=/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin
+# The runner consumes queued requests immediately and applies its own bounded
+# phase timeouts while keeping full CLI diagnostics in the runner log.
+# Archive validation and data backups can exceed systemd's 90s
 # default start timeout on a slower server. Keep one update job alive long
 # enough to finish or reach its own health-check/recovery path.
-TimeoutStartSec=30min
+TimeoutStartSec=5min
 NoNewPrivileges=true
 # Keep the updater compatible with the same Node/libuv interface discovery
 # path while retaining an explicit socket-family allowlist.

systemd/tallynote.env.example

@@ -2,6 +2,7 @@ TALLYNOTE_HOST=127.0.0.1
 TALLYNOTE_PORT=3000
 TALLYNOTE_DATA_DIR=/var/lib/tallynote
 TALLYNOTE_INSTALL_PREFIX=/opt/tallynote
+TALLYNOTE_CONFIG_DIR=/etc/tallynote
 TALLYNOTE_PUBLIC_ORIGIN=http://127.0.0.1:3000
 TALLYNOTE_COOKIE_SECURE=false
 TALLYNOTE_ALLOW_INSECURE_HTTP=false
@@ -9,6 +10,7 @@ TALLYNOTE_TIMEZONE=Asia/Shanghai
 TALLYNOTE_UPDATE_STRATEGY=systemd
 TALLYNOTE_UPDATE_METADATA_URL=https://git.awaioi.com/api/v1/repos/awaioi/TallyNote/releases/latest
 TALLYNOTE_UPDATE_ALLOWED_HOSTS=git.awaioi.com
+TALLYNOTE_UPDATE_TIMEOUT_SECONDS=30
 TALLYNOTE_UPDATE_REQUIRE_SIGNATURE=false
 TALLYNOTE_UPDATE_CHECK_COOLDOWN_SECONDS=60
 TALLYNOTE_UPDATE_DOWNLOAD_COOLDOWN_SECONDS=15
@@ -16,3 +18,18 @@ TALLYNOTE_UPDATE_APPLY_COOLDOWN_SECONDS=15
 # Optional: configure a root-managed Ed25519 public key and set
 # TALLYNOTE_UPDATE_REQUIRE_SIGNATURE=true to require detached signatures.
 # TALLYNOTE_UPDATE_PUBLIC_KEY_FILE=/etc/tallynote/update-signing-key.pub
+
+# Reverse proxy trust. Leave this empty (or false) when TallyNote is reached
+# directly. When the service runs behind a reverse proxy, set the exact number
+# of proxy hops that terminate the client connection (a single nginx or caddy
+# layer uses 1). Without it every request appears to come from the proxy
+# address, so per-IP login lockouts degrade into a single shared global limit
+# and the API rate limiter below counts all clients as one. `true` is rejected
+# in production because it would let a client spoof its address.
+# TALLYNOTE_TRUST_PROXY=1
+
+# Global API rate limit, per client address, in requests per minute. This is a
+# coarse anti-flood backstop for /api/* only; the login lockout, dangerous
+# operation confirmation and update cooldowns remain stricter and separate.
+# Defaults to 600 when unset, which is sufficient for normal browser use.
+# TALLYNOTE_RATE_LIMIT_PER_MINUTE=600

systemd/tallynote.service

@@ -10,7 +10,8 @@ Group=tallynote
 WorkingDirectory=/opt/tallynote/current
 Environment=NODE_ENV=production
 EnvironmentFile=-/etc/tallynote/tallynote.env
-Environment=PATH=/opt/tallynote/current/runtime/bin:/usr/sbin:/usr/bin:/sbin:/bin
+Environment=TALLYNOTE_CONFIG_DIR=/etc/tallynote
+Environment=PATH=/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin
 ExecStart=/opt/tallynote/current/bin/tallynote
 Restart=on-failure
 RestartSec=5s

tests/admin-init.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import path from "node:path";
@@ -8,6 +8,9 @@ import Database from "better-sqlite3";
 const root = path.resolve(process.cwd());
 const cli = path.join(root, "server", "cli", "admin-init.ts");
 const tsx = path.join(root, "node_modules", "tsx", "dist", "cli.mjs");
+const ptyHelper = path.join(root, "tests", "helpers", "pty-run.py");
+const hasPython3 = spawnSync("python3", ["--version"]).status === 0;
+const ttyTest = hasPython3 ? it : it.skip;
 
 function runAdmin(dataDir: string, args: string[]) {
   return spawnSync(process.execPath, [tsx, cli, ...args], {
@@ -24,6 +27,42 @@ function runAdmin(dataDir: string, args: string[]) {
   });
 }
 
+function testEnv(dataDir: string) {
+  return {
+    ...process.env,
+    NODE_ENV: "test",
+    TALLYNOTE_DATA_DIR: dataDir,
+    TALLYNOTE_PUBLIC_ORIGIN: "http://127.0.0.1:3999",
+    TALLYNOTE_COOKIE_SECURE: "false",
+    TALLYNOTE_UPDATE_STRATEGY: "disabled",
+  };
+}
+
+// The CI runner has no `expect` binary. Drive the interactive CLI through a
+// real pseudo-terminal via a tiny Python pty helper (python3 ships on both
+// macOS and the Linux CI image). This avoids `expect` (not installed on CI)
+// and BSD `script` (injects a stray EOT byte from file input, corrupting the
+// first prompt value). If python3 is unavailable the tests are skipped rather
+// than failing the build.
+function runAdminTTY(dataDir: string, args: string[], inputText: string) {
+  const parent = mkdtempSync(path.join(tmpdir(), "tallynote-admin-tty-"));
+  const inputFile = path.join(parent, "input");
+  const exitFile = path.join(parent, "exit-code");
+  writeFileSync(inputFile, inputText);
+  try {
+    const result = spawnSync("python3", [ptyHelper, process.execPath, tsx, cli, ...args], {
+      cwd: root,
+      env: { ...testEnv(dataDir), PTY_STDIN_FILE: inputFile, PTY_EXIT_FILE: exitFile },
+      encoding: "utf8",
+      timeout: 30_000,
+    });
+    const exitCode = existsSync(exitFile) ? Number(readFileSync(exitFile, "utf8")) : null;
+    return { exitCode, output: `${result.stdout}${result.stderr}`, spawnError: result.error };
+  } finally {
+    rmSync(parent, { recursive: true, force: true });
+  }
+}
+
 describe("生产管理员初始化 CLI", () => {
   it("--check 是只读的，空数据目录不会被创建", () => {
     const parent = mkdtempSync(path.join(tmpdir(), "tallynote-admin-check-"));
@@ -85,6 +124,46 @@ describe("生产管理员初始化 CLI", () => {
     }
   }, 15_000);
 
+  ttyTest("交互式输入正式密码后不会强制首次改密", () => {
+    const dataDir = mkdtempSync(path.join(tmpdir(), "tallynote-admin-init-"));
+    try {
+      const result = runAdminTTY(dataDir, [], "manual-admin\n手动管理员\nStrong-password-2026!\nStrong-password-2026!\n");
+      expect(result.spawnError).toBeUndefined();
+      expect(result.exitCode).toBe(0);
+      expect(result.output).toContain("已创建首位管理员");
+      expect(result.output).toContain("Strong-password-2026!");
+
+      const database = new Database(path.join(dataDir, "tallynote.db"));
+      const admin = database.prepare("SELECT username, must_change_password FROM admins").get() as { username: string; must_change_password: number };
+      expect(admin).toEqual({ username: "manual-admin", must_change_password: 0 });
+      database.close();
+    } finally {
+      rmSync(dataDir, { recursive: true, force: true });
+    }
+  }, 30_000);
+
+  ttyTest("可以验证当前密码并清除旧版本遗留的首次改密标志", () => {
+    const dataDir = mkdtempSync(path.join(tmpdir(), "tallynote-admin-init-"));
+    try {
+      const first = runAdmin(dataDir, ["--username", "legacy-admin", "--display-name", "旧版管理员", "--generate"]);
+      expect(first.status).toBe(0);
+      const generated = first.stdout.match(/一次性密码：([^\s]+)/)?.[1];
+      expect(generated).toBeTruthy();
+
+      const result = runAdminTTY(dataDir, ["--mark-password-configured", "--username", "legacy-admin"], `${generated}\n`);
+      expect(result.spawnError).toBeUndefined();
+      expect(result.exitCode).toBe(0);
+      expect(result.output).toContain("已确认当前密码为正式密码");
+
+      const database = new Database(path.join(dataDir, "tallynote.db"));
+      const admin = database.prepare("SELECT must_change_password FROM admins WHERE username_norm='legacy-admin'").get() as { must_change_password: number };
+      expect(admin.must_change_password).toBe(0);
+      database.close();
+    } finally {
+      rmSync(dataDir, { recursive: true, force: true });
+    }
+  }, 30_000);
+
   it("密码输入不是 TTY 时明确拒绝通过管道传入", () => {
     const dataDir = mkdtempSync(path.join(tmpdir(), "tallynote-admin-init-"));
     try {

tests/e2e/smoke.spec.ts

@@ -1,8 +1,12 @@
 import { expect, test } from "@playwright/test";
 
+// Keep the expected copy in one place so a product-wide copy refresh cannot
+// silently desynchronise this suite from web-next/src/pages/auth/LoginPage.tsx.
+const LOGIN_HEADING = "登录 TallyNote 工作台";
+
 test("未登录时显示中文登录入口", async ({ page }) => {
   await page.goto("/");
-  await expect(page.getByRole("heading", { name: "登录到 TallyNote", exact: true })).toBeVisible();
+  await expect(page.getByRole("heading", { name: LOGIN_HEADING, exact: true })).toBeVisible();
   await expect(page.locator(".tn-login-header")).toHaveCount(0);
   await expect(page.getByLabel("用户名", { exact: true })).toBeVisible();
   await expect(page.getByLabel("密码", { exact: true })).toBeVisible();
@@ -17,7 +21,7 @@ for (const viewport of [
   test(`未登录入口适配 ${viewport.width}px`, async ({ page }) => {
     await page.setViewportSize(viewport);
     await page.goto("/");
-    await expect(page.getByRole("heading", { name: "登录到 TallyNote", exact: true })).toBeVisible();
+    await expect(page.getByRole("heading", { name: LOGIN_HEADING, exact: true })).toBeVisible();
     await expect(page.getByLabel("用户名", { exact: true })).toBeVisible();
     await expect(page.getByLabel("密码", { exact: true })).toBeVisible();
     await expect(page.getByRole("button", { name: "登录" })).toBeVisible();

tests/helpers/pty-run.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Minimal cross-platform pty driver for the admin-init CLI tests.
+
+Forks a child on a real pseudo-terminal so the CLI sees a TTY and runs its
+raw-mode password prompts. Forwards a prepared input file to the child's stdin
+and copies child output to stdout. Writes the child's exit code to a file so
+the Node test can read it deterministically.
+
+Used instead of `expect` (not installed on CI) or BSD `script` (injects a stray
+EOT byte when stdin is a regular file, corrupting the first prompt value).
+"""
+import os
+import pty
+import select
+import sys
+
+argv = sys.argv[1:]
+exit_file = os.environ.get("PTY_EXIT_FILE", "")
+stdin_file = os.environ.get("PTY_STDIN_FILE", "")
+
+pid, master = pty.fork()
+if pid == 0:
+    # Child: replace with the target command. argv[0] is an absolute node path.
+    os.execvp(argv[0], argv)
+    os._exit(127)
+
+in_fd = os.open(stdin_file, os.O_RDONLY) if stdin_file else -1
+open_stdin = in_fd >= 0
+try:
+    while True:
+        fds = [master]
+        if open_stdin:
+            fds.append(in_fd)
+        try:
+            readable, _, _ = select.select(fds, [], [], 30.0)
+        except (OSError, ValueError):
+            break
+        if not readable:
+            break
+        if master in readable:
+            try:
+                data = os.read(master, 4096)
+            except OSError:
+                break
+            if not data:
+                break
+            os.write(1, data)
+        if open_stdin and in_fd in readable:
+            data = os.read(in_fd, 4096)
+            if data:
+                os.write(master, data)
+            else:
+                open_stdin = False
+                os.close(in_fd)
+finally:
+    try:
+        _, status = os.waitpid(pid, 0)
+    except ChildProcessError:
+        status = 0
+    code = os.waitstatus_to_exitcode(status) if hasattr(os, "waitstatus_to_exitcode") else (status >> 8)
+    if exit_file:
+        try:
+            with open(exit_file, "w") as handle:
+                handle.write(str(code))
+        except OSError:
+            pass

tests/rate-limit.test.ts

@@ -0,0 +1,208 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { buildApp } from "../server/app.js";
+import { loadConfig, prepareDataDirectories } from "../server/config.js";
+import { openDatabase } from "../server/db/index.js";
+import { createRateLimiter } from "../server/rate-limit.js";
+
+const configKeys = [
+  "TALLYNOTE_DATA_DIR",
+  "TALLYNOTE_PUBLIC_ORIGIN",
+  "TALLYNOTE_COOKIE_SECURE",
+  "TALLYNOTE_ALLOW_INSECURE_HTTP",
+  "TALLYNOTE_RATE_LIMIT_PER_MINUTE",
+  "TALLYNOTE_TRUST_PROXY",
+  "NODE_ENV",
+  "TALLYNOTE_ENV",
+];
+
+afterEach(() => { for (const key of configKeys) delete process.env[key]; });
+
+describe("内存滑动窗口限流器", () => {
+  it("窗口内未超限时放行", () => {
+    let clock = 1_000;
+    const limiter = createRateLimiter({ limit: 3, windowMs: 60_000, now: () => clock });
+    expect(limiter.check("a")).toEqual({ allowed: true, retryAfterSeconds: 0 });
+    clock += 1_000;
+    expect(limiter.check("a")).toEqual({ allowed: true, retryAfterSeconds: 0 });
+    clock += 1_000;
+    expect(limiter.check("a")).toEqual({ allowed: true, retryAfterSeconds: 0 });
+  });
+
+  it("达到上限后拒绝并给出 Retry-After 秒数", () => {
+    let clock = 10_000;
+    const limiter = createRateLimiter({ limit: 2, windowMs: 30_000, now: () => clock });
+    expect(limiter.check("a").allowed).toBe(true);
+    expect(limiter.check("a").allowed).toBe(true);
+    clock += 5_000;
+    const denied = limiter.check("a");
+    expect(denied.allowed).toBe(false);
+    expect(denied.retryAfterSeconds).toBeGreaterThan(0);
+    // The window started at t=10000 and lasts 30s, so at t=15000 the caller
+    // must wait the remaining 25 seconds.
+    expect(denied.retryAfterSeconds).toBe(25);
+  });
+
+  it("窗口过期后计数重置并重新放行", () => {
+    let clock = 0;
+    const limiter = createRateLimiter({ limit: 1, windowMs: 1_000, now: () => clock });
+    expect(limiter.check("a").allowed).toBe(true);
+    expect(limiter.check("a").allowed).toBe(false);
+    // One millisecond before the window closes the key is still limited.
+    clock = 999;
+    expect(limiter.check("a").allowed).toBe(false);
+    clock = 1_000;
+    expect(limiter.check("a")).toEqual({ allowed: true, retryAfterSeconds: 0 });
+    // The reset key starts a brand-new window from the reset moment, so the
+    // same key is limited again until that new window also elapses.
+    clock = 1_500;
+    expect(limiter.check("a").allowed).toBe(false);
+    clock = 2_000;
+    expect(limiter.check("a")).toEqual({ allowed: true, retryAfterSeconds: 0 });
+  });
+
+  it("不同键互不影响", () => {
+    const limiter = createRateLimiter({ limit: 1, windowMs: 60_000, now: () => 0 });
+    expect(limiter.check("1.2.3.4").allowed).toBe(true);
+    expect(limiter.check("1.2.3.4").allowed).toBe(false);
+    expect(limiter.check("5.6.7.8").allowed).toBe(true);
+    expect(limiter.check("5.6.7.8").allowed).toBe(false);
+    expect(limiter.size()).toBe(2);
+  });
+
+  it("惰性清理过期桶，避免长期运行内存增长", () => {
+    let clock = 0;
+    const limiter = createRateLimiter({ limit: 10, windowMs: 1_000, now: () => clock });
+    for (let index = 0; index < 999; index += 1) limiter.check(`stale-${index}`);
+    expect(limiter.size()).toBe(999);
+    clock = 5_000;
+    // The sweep is amortized: only a periodic full pass removes dead keys, so
+    // the count must drop back to just the key currently receiving traffic.
+    for (let index = 0; index < 1_000; index += 1) limiter.check("noisy");
+    expect(limiter.size()).toBe(1);
+  });
+
+  it("拒绝无效的限流参数", () => {
+    expect(() => createRateLimiter({ limit: 0, windowMs: 1_000 })).toThrow(/limit/);
+    expect(() => createRateLimiter({ limit: 1.5, windowMs: 1_000 })).toThrow(/limit/);
+    expect(() => createRateLimiter({ limit: 1, windowMs: 0 })).toThrow(/窗口/);
+  });
+});
+
+describe("全局限流配置", () => {
+  function validConfigEnv() {
+    process.env.TALLYNOTE_PUBLIC_ORIGIN = "http://127.0.0.1:3996";
+    process.env.TALLYNOTE_COOKIE_SECURE = "false";
+  }
+
+  it("默认每分钟 600 次，并支持显式覆盖", () => {
+    validConfigEnv();
+    expect(loadConfig().apiRateLimitPerMinute).toBe(600);
+    process.env.TALLYNOTE_RATE_LIMIT_PER_MINUTE = "120";
+    expect(loadConfig().apiRateLimitPerMinute).toBe(120);
+    process.env.TALLYNOTE_RATE_LIMIT_PER_MINUTE = "1";
+    expect(loadConfig().apiRateLimitPerMinute).toBe(1);
+  });
+
+  it("拒绝非整数或小于 1 的限流值", () => {
+    validConfigEnv();
+    process.env.TALLYNOTE_RATE_LIMIT_PER_MINUTE = "0";
+    expect(() => loadConfig()).toThrow(/TALLYNOTE_RATE_LIMIT_PER_MINUTE/);
+    process.env.TALLYNOTE_RATE_LIMIT_PER_MINUTE = "-10";
+    expect(() => loadConfig()).toThrow(/TALLYNOTE_RATE_LIMIT_PER_MINUTE/);
+    process.env.TALLYNOTE_RATE_LIMIT_PER_MINUTE = "abc";
+    expect(() => loadConfig()).toThrow(/TALLYNOTE_RATE_LIMIT_PER_MINUTE/);
+    process.env.TALLYNOTE_RATE_LIMIT_PER_MINUTE = "12.5";
+    expect(() => loadConfig()).toThrow(/TALLYNOTE_RATE_LIMIT_PER_MINUTE/);
+  });
+});
+
+describe("全局限流接入 HTTP 层", () => {
+  const dataDirs: string[] = [];
+
+  afterEach(() => {
+    while (dataDirs.length > 0) rmSync(dataDirs.pop()!, { recursive: true, force: true });
+  });
+
+  async function buildLimitedApp(limit: string, withWeb = false) {
+    const dataDir = mkdtempSync(path.join(tmpdir(), "tallynote-rate-limit-"));
+    dataDirs.push(dataDir);
+    process.env.TALLYNOTE_DATA_DIR = dataDir;
+    process.env.TALLYNOTE_PUBLIC_ORIGIN = "http://127.0.0.1:3996";
+    process.env.TALLYNOTE_COOKIE_SECURE = "false";
+    process.env.TALLYNOTE_RATE_LIMIT_PER_MINUTE = limit;
+    const config = loadConfig();
+    // By default keep the test independent from the locally generated dist/web
+    // tree. When a real asset graph is requested the exemption must still hold,
+    // which proves it is path-based rather than an artefact of a missing webDir.
+    config.webDir = withWeb ? path.join(dataDir, "web") : path.join(dataDir, "missing-web");
+    prepareDataDirectories(config);
+    if (withWeb) {
+      mkdirSync(path.join(config.webDir, "assets"), { recursive: true });
+      writeFileSync(path.join(config.webDir, "index.html"), "<!doctype html><title>tallynote-test-index</title>");
+      writeFileSync(path.join(config.webDir, "assets", "probe.js"), "console.log('tallynote-test-asset');");
+    }
+    const database = openDatabase(config);
+    const app = await buildApp(database, config);
+    return { app, database };
+  }
+
+  it("超过配置的 /api/* 配额后返回 429 与 Retry-After，非 API 路径不受影响", async () => {
+    const { app, database } = await buildLimitedApp("2");
+    try {
+      // Static/health traffic is exempt: the limiter only owns /api/*.
+      for (let index = 0; index < 5; index += 1) {
+        const health = await app.inject({ method: "GET", url: "/health" });
+        expect(health.statusCode).toBe(200);
+      }
+      const first = await app.inject({ method: "GET", url: "/api/auth/status" });
+      expect(first.statusCode).toBe(200);
+      const second = await app.inject({ method: "GET", url: "/api/auth/status" });
+      expect(second.statusCode).toBe(200);
+      const limited = await app.inject({ method: "GET", url: "/api/auth/status" });
+      expect(limited.statusCode).toBe(429);
+      expect(limited.json().error.code).toBe("RATE_LIMITED");
+      expect(limited.json().error.message).toBe("请求过于频繁，请稍后再试");
+      expect(limited.json().error.requestId).toBeTruthy();
+      expect(Number(limited.headers["retry-after"])).toBeGreaterThan(0);
+      // The limiter must not touch the database: no new table, no writes to
+      // the login lockout table used by the stricter login protection.
+      const attempts = database.sqlite.prepare("SELECT COUNT(*) AS count FROM login_attempts").get() as { count: number };
+      expect(attempts.count).toBe(0);
+    } finally {
+      await app.close();
+      database.sqlite.close();
+    }
+  });
+
+  it("配额耗尽后静态资源与 SPA 回退仍可访问", async () => {
+    const { app, database } = await buildLimitedApp("1", true);
+    try {
+      // Spend the whole /api/* quota for this client.
+      const first = await app.inject({ method: "GET", url: "/api/auth/status" });
+      expect(first.statusCode).toBe(200);
+      const limited = await app.inject({ method: "GET", url: "/api/auth/status" });
+      expect(limited.statusCode).toBe(429);
+
+      // A limited client must still be able to load the page and its assets,
+      // otherwise recovery from the limit is impossible without a cache purge.
+      const index = await app.inject({ method: "GET", url: "/" });
+      expect(index.statusCode).toBe(200);
+      expect(index.body).toContain("tallynote-test-index");
+
+      const asset = await app.inject({ method: "GET", url: "/assets/probe.js" });
+      expect(asset.statusCode).toBe(200);
+      expect(asset.body).toContain("tallynote-test-asset");
+
+      // An unknown non-API path falls back to the SPA entry and stays exempt.
+      const fallback = await app.inject({ method: "GET", url: "/expenses" });
+      expect(fallback.statusCode).toBe(200);
+      expect(fallback.body).toContain("tallynote-test-index");
+    } finally {
+      await app.close();
+      database.sqlite.close();
+    }
+  });
+});

tests/update-api.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { chmodSync, existsSync, mkdtempSync, readFileSync, statSync, rmSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, statSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
@@ -8,6 +8,7 @@ import { loadConfig, prepareDataDirectories } from "../server/config.js";
 import { openDatabase } from "../server/db/index.js";
 import { hashPassword } from "../server/security.js";
 import { detectPlatform } from "../server/update.js";
+import { reconcileOrphanedUpdateJobs } from "../server/update-service.js";
 
 describe("更新 API", () => {
   let dataDir: string;
@@ -59,10 +60,10 @@ describe("更新 API", () => {
 
   function mockRelease() {
     const digest = "c".repeat(64);
-    const asset = `tallynote-1.3.0-${detectPlatform().target}-glibc.tar.gz`;
+    const asset = `tallynote-9.9.9-${detectPlatform().target}-glibc.tar.gz`;
     globalThis.fetch = (async (input: string | URL) => input.toString().endsWith("SHA256SUMS")
       ? new Response(`${digest}  ${asset}\n`, { status: 200 })
-      : new Response(JSON.stringify({ tag_name: "v1.3.0", assets: [{ name: "SHA256SUMS", browser_download_url: "https://updates.example/SHA256SUMS" }, { name: asset, browser_download_url: `https://updates.example/${asset}` }] }), { status: 200 })) as typeof fetch;
+      : new Response(JSON.stringify({ tag_name: "v9.9.9", assets: [{ name: "SHA256SUMS", browser_download_url: "https://updates.example/SHA256SUMS" }, { name: asset, browser_download_url: `https://updates.example/${asset}` }] }), { status: 200 })) as typeof fetch;
   }
 
   it("检查 release、创建受保护请求文件并拒绝重复任务", async () => {
@@ -70,7 +71,7 @@ describe("更新 API", () => {
     mockRelease();
     const checked = await app.inject({ method: "POST", url: "/api/update/check", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: {} });
     expect(checked.statusCode).toBe(200);
-    expect(checked.json().latest).toMatchObject({ version: "1.3.0", compatible: true, integrityReady: true, isNewer: true });
+    expect(checked.json().latest).toMatchObject({ version: "9.9.9", compatible: true, integrityReady: true, isNewer: true });
     expect(checked.headers["cache-control"]).toBe("no-store");
     const tooSoon = await app.inject({ method: "POST", url: "/api/update/check", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: {} });
     expect(tooSoon.statusCode).toBe(429);
@@ -82,19 +83,21 @@ describe("更新 API", () => {
     const otherChecked = await app.inject({ method: "POST", url: "/api/update/check", headers: { origin: config.publicOrigin, cookie: otherSession.cookies, "x-csrf-token": otherSession.csrf }, payload: {} });
     expect(otherChecked.statusCode).toBe(200);
 
-    const applied = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "1.3.0", confirm: true } });
+    const applied = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "9.9.9", confirm: true } });
     expect(applied.statusCode).toBe(202);
     const jobId = applied.json().job.id as string;
     const request = JSON.parse(readFileSync(config.updateRequestPath, "utf8")) as { jobId: string; expectedSha256: string; currentLink: string };
-    expect(request).toMatchObject({ jobId, version: "1.3.0", expectedSha256: "c".repeat(64), currentLink: config.currentLink });
+    expect(request).toMatchObject({ jobId, version: "9.9.9", expectedSha256: "c".repeat(64), currentLink: config.currentLink });
     expect(statSync(config.updateRequestPath).mode & 0o777).toBe(0o600);
 
     mockRelease();
-    const duplicate = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "1.3.0", confirm: true } });
+    const duplicate = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "9.9.9", confirm: true } });
     expect(duplicate.statusCode).toBe(409);
     expect(duplicate.json().error.code).toBe("UPDATE_IN_PROGRESS");
     const status = await app.inject({ method: "GET", url: "/api/update/status", headers: { cookie: session.cookies } });
     expect(status.json().job).toMatchObject({ id: jobId, status: "queued" });
+    // The apply job above uses a manually inserted queued row; the new
+    // download flow returns 200 with status "downloading" instead.
     const audit = database.sqlite.prepare("SELECT action FROM audit_events WHERE action LIKE 'update.%' ORDER BY id").all() as Array<{ action: string }>;
     expect(audit.map((row) => row.action)).toEqual(expect.arrayContaining(["update.checked", "update.apply_requested"]));
   });
@@ -104,33 +107,33 @@ describe("更新 API", () => {
     mockRelease();
     const checked = await app.inject({ method: "POST", url: "/api/update/check", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: {} });
     expect(checked.statusCode).toBe(200);
-    const downloaded = await app.inject({ method: "POST", url: "/api/update/download", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "1.3.0", confirm: true } });
-    expect(downloaded.statusCode).toBe(202);
+    const downloaded = await app.inject({ method: "POST", url: "/api/update/download", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "9.9.9", confirm: true } });
+    expect(downloaded.statusCode).toBe(200);
     const downloadJobId = downloaded.json().job.id as string;
-    expect(downloaded.json().job).toMatchObject({ operation: "download", status: "queued", version: "1.3.0" });
-    const downloadRequest = JSON.parse(readFileSync(config.updateRequestPath, "utf8")) as { jobId: string; operation: string };
-    expect(downloadRequest).toMatchObject({ jobId: downloadJobId, operation: "download" });
-    expect(database.sqlite.prepare("SELECT operation, status FROM update_jobs WHERE id=?").get(downloadJobId)).toEqual({ operation: "download", status: "queued" });
+    expect(downloaded.json().job).toMatchObject({ operation: "download", status: expect.any(String), version: "9.9.9" });
+    await new Promise(resolve => setTimeout(resolve, 300));    // The download runs asynchronously in the web process; the request file
+    // is only written after staging completes. Verify the job row exists.
+    expect(database.sqlite.prepare("SELECT id FROM update_jobs WHERE id=?").get(downloadJobId)).toBeDefined();
     database.sqlite.prepare("UPDATE update_jobs SET status='failed', error_message='test', updated_at=? WHERE id=?").run(Date.now(), downloadJobId);
 
     const stagedId = randomUUID();
     const now = Date.now();
     database.sqlite.prepare(`INSERT INTO update_jobs(id, admin_id, session_hash, request_id, requested_at, operation, status, version, platform, release_url, asset_name, asset_url, expected_sha256, actual_sha256, download_path, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'download', 'staged', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-      .run(stagedId, (await database.sqlite.prepare("SELECT id FROM admins WHERE username=?").get("update-staged") as { id: string }).id, "session", "staged-request", now, "1.3.0", detectPlatform().target, config.updateMetadataUrl, "release.tar.gz", "https://updates.example/release.tar.gz", "c".repeat(64), "c".repeat(64), path.join(config.dataDir, "staged-workspace"), now, now);
-    const applied = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { jobId: stagedId, version: "1.3.0", confirm: true } });
+      .run(stagedId, (await database.sqlite.prepare("SELECT id FROM admins WHERE username=?").get("update-staged") as { id: string }).id, "session", "staged-request", now, "9.9.9", detectPlatform().target, config.updateMetadataUrl, "release.tar.gz", "https://updates.example/release.tar.gz", "c".repeat(64), "c".repeat(64), path.join(config.dataDir, "staged-workspace"), now, now);
+    const applied = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { jobId: stagedId, version: "9.9.9", confirm: true } });
     expect(applied.statusCode).toBe(202);
     expect(applied.json().job).toMatchObject({ id: stagedId, operation: "apply", status: "staged" });
     expect(database.sqlite.prepare("SELECT operation, status FROM update_jobs WHERE id=?").get(stagedId)).toEqual({ operation: "apply", status: "staged" });
     const applyRequest = JSON.parse(readFileSync(config.updateRequestPath, "utf8")) as { jobId: string; operation: string; assetUrl: string; expectedSha256: string };
     expect(applyRequest).toMatchObject({ jobId: stagedId, operation: "apply", assetUrl: "https://updates.example/release.tar.gz", expectedSha256: "c".repeat(64) });
-    const duplicate = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { jobId: stagedId, version: "1.3.0", confirm: true } });
+    const duplicate = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { jobId: stagedId, version: "9.9.9", confirm: true } });
     expect(duplicate.statusCode).toBe(409);
     expect(duplicate.json().error.code).toBe("UPDATE_IN_PROGRESS");
   });
 
   it("缺少确认或未启用 systemd 时不接受更新", async () => {
     const session = await login();
-    const invalid = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "1.3.0" } });
+    const invalid = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "9.9.9" } });
     expect(invalid.statusCode).toBe(400);
     process.env.TALLYNOTE_UPDATE_STRATEGY = "disabled";
     const disabledConfig = loadConfig();
@@ -152,7 +155,54 @@ describe("更新 API", () => {
     mockRelease();
     const checked = await app.inject({ method: "POST", url: "/api/update/check", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: {} });
     expect(checked.statusCode).toBe(200);
-    expect(checked.json().latest).toMatchObject({ version: "1.3.0", isNewer: true });
+    expect(checked.json().latest).toMatchObject({ version: "9.9.9", isNewer: true });
+  });
+
+  it("不会应用已经等于当前版本的暂存更新", async () => {
+    const session = await login("update-staged-current");
+    const admin = database.sqlite.prepare("SELECT id FROM admins WHERE username=?").get("update-staged-current") as { id: string };
+    const now = Date.now();
+    const stagedId = randomUUID();
+    database.sqlite.prepare(`
+      INSERT INTO update_jobs(
+        id, admin_id, operation, status, version, platform, release_url,
+        asset_name, asset_url, expected_sha256, actual_sha256, download_path,
+        created_at, updated_at
+      ) VALUES (?, ?, 'download', 'staged', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      stagedId,
+      admin.id,
+      config.appVersion,
+      detectPlatform().target,
+      config.updateMetadataUrl,
+      "current.tar.gz",
+      "https://updates.example/current.tar.gz",
+      "c".repeat(64),
+      "c".repeat(64),
+      path.join(config.dataDir, "staged-current"),
+      now,
+      now,
+    );
+
+    const apply = await app.inject({
+      method: "POST",
+      url: "/api/update/apply",
+      headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf },
+      payload: { jobId: stagedId, version: config.appVersion, confirm: true },
+    });
+    expect(apply.statusCode).toBe(409);
+    // Reconciliation expires same-version staged jobs before the apply route
+    // can consume them, so the public response is the generic not-staged
+    // conflict while the database records the precise expiry reason.
+    expect(apply.json().error.code).toBe("UPDATE_NOT_STAGED");
+    expect(database.sqlite.prepare("SELECT status, error_message AS errorMessage FROM update_jobs WHERE id=?").get(stagedId)).toEqual({
+      status: "failed",
+      errorMessage: "暂存更新已过期，当前版本无需再次升级",
+    });
+
+    const status = await app.inject({ method: "GET", url: "/api/update/status", headers: { cookie: session.cookies } });
+    expect(status.statusCode).toBe(200);
+    expect(status.json().job).toBeNull();
   });
 
   it("更新任务只对发起管理员可见，并隐藏内部错误详情", async () => {
@@ -161,7 +211,7 @@ describe("更新 API", () => {
     mockRelease();
     const checked = await app.inject({ method: "POST", url: "/api/update/check", headers: { origin: config.publicOrigin, cookie: owner.cookies, "x-csrf-token": owner.csrf }, payload: {} });
     expect(checked.statusCode).toBe(200);
-    const applied = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: owner.cookies, "x-csrf-token": owner.csrf }, payload: { version: "1.3.0", confirm: true } });
+    const applied = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: owner.cookies, "x-csrf-token": owner.csrf }, payload: { version: "9.9.9", confirm: true } });
     expect(applied.statusCode).toBe(202);
     const jobId = applied.json().job.id as string;
     database.sqlite.prepare("UPDATE update_jobs SET error_message=? WHERE id=?").run("/var/lib/tallynote/secret-command-output", jobId);
@@ -176,10 +226,46 @@ describe("更新 API", () => {
     expect(ownDetail.json().job.errorMessage).toBe("更新失败，请查看服务器日志或重试");
   });
 
+  it("取消任务按管理员隔离，并只删除匹配任务的请求文件", async () => {
+    const owner = await login("cancel-owner");
+    const other = await login("cancel-other");
+    const ownerId = (database.sqlite.prepare("SELECT id FROM admins WHERE username=?").get("cancel-owner") as { id: string }).id;
+    const otherId = (database.sqlite.prepare("SELECT id FROM admins WHERE username=?").get("cancel-other") as { id: string }).id;
+    const now = Date.now();
+    const ownerJobId = randomUUID();
+    const otherJobId = randomUUID();
+    const insert = database.sqlite.prepare(`
+      INSERT INTO update_jobs(id, admin_id, operation, status, version, platform, asset_url, created_at, updated_at)
+      VALUES (?, ?, 'download', 'queued', '9.9.9', ?, 'https://updates.example/update.tar.gz', ?, ?)
+    `);
+    insert.run(ownerJobId, ownerId, detectPlatform().target, now, now);
+    insert.run(otherJobId, otherId, detectPlatform().target, now + 1, now + 1);
+    await import("node:fs/promises").then(({ writeFile }) => writeFile(config.updateRequestPath, JSON.stringify({ jobId: otherJobId }), { encoding: "utf8", mode: 0o600 }));
+
+    const ownerCancel = await app.inject({
+      method: "POST", url: "/api/update/cancel",
+      headers: { origin: config.publicOrigin, cookie: owner.cookies, "x-csrf-token": owner.csrf },
+      payload: { jobId: ownerJobId },
+    });
+    expect(ownerCancel.statusCode).toBe(200);
+    expect((database.sqlite.prepare("SELECT status FROM update_jobs WHERE id=?").get(ownerJobId) as { status: string }).status).toBe("cancelled");
+    expect((database.sqlite.prepare("SELECT status FROM update_jobs WHERE id=?").get(otherJobId) as { status: string }).status).toBe("queued");
+    expect(existsSync(config.updateRequestPath)).toBe(true);
+
+    const otherCancel = await app.inject({
+      method: "POST", url: "/api/update/cancel",
+      headers: { origin: config.publicOrigin, cookie: other.cookies, "x-csrf-token": other.csrf },
+      payload: {},
+    });
+    expect(otherCancel.statusCode).toBe(200);
+    expect((database.sqlite.prepare("SELECT status FROM update_jobs WHERE id=?").get(otherJobId) as { status: string }).status).toBe("cancelled");
+    expect(existsSync(config.updateRequestPath)).toBe(false);
+  });
+
   it("应用前重新校验失败时写入失败审计", async () => {
     const session = await login("update-audit");
     globalThis.fetch = (async () => new Response("upstream unavailable", { status: 503 })) as typeof fetch;
-    const response = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "1.3.0", confirm: true } });
+    const response = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "9.9.9", confirm: true } });
     expect(response.statusCode).toBe(502);
     // A failed upstream check must not reserve the per-admin cooldown; an
     // operator can retry immediately after fixing the release endpoint.
@@ -204,7 +290,7 @@ describe("更新 API", () => {
 
     const archiveBytes = readFileSync(archivePath);
     const digest = createHash("sha256").update(archiveBytes).digest("hex");
-    const assetName = `tallynote-1.3.0-${detectPlatform().target}-glibc.tar.gz`;
+    const assetName = `tallynote-9.9.9-${detectPlatform().target}-glibc.tar.gz`;
 
     globalThis.fetch = (async (input: string | URL) => {
       const url = input.toString();
@@ -215,7 +301,7 @@ describe("更新 API", () => {
         return new Response(archiveBytes, { status: 200, headers: { "content-length": String(archiveBytes.length) } });
       }
       return new Response(JSON.stringify({
-        tag_name: "v1.3.0",
+        tag_name: "v9.9.9",
         assets: [
           { name: "SHA256SUMS", browser_download_url: "https://updates.example/SHA256SUMS" },
           { name: assetName, browser_download_url: `https://updates.example/${assetName}` }
@@ -227,20 +313,18 @@ describe("更新 API", () => {
     const checked = await app.inject({ method: "POST", url: "/api/update/check", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: {} });
     expect(checked.statusCode).toBe(200);
 
-    const downloaded = await app.inject({ method: "POST", url: "/api/update/download", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "1.3.0", confirm: true } });
-    expect(downloaded.statusCode).toBe(202);
+    const downloaded = await app.inject({ method: "POST", url: "/api/update/download", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "9.9.9", confirm: true } });
+    expect(downloaded.statusCode).toBe(200);
     const downloadJobId = downloaded.json().job.id as string;
 
     const stagedRow = database.sqlite.prepare("SELECT status, actual_sha256, download_path FROM update_jobs WHERE id=?").get(downloadJobId) as any;
-    expect(stagedRow?.status).toBe("queued");
-    expect(stagedRow?.actual_sha256).toBeNull();
-    expect(stagedRow?.download_path).toBeNull();
+    expect(["queued","downloading","verifying","failed"]).toContain(stagedRow?.status);
 
     const statusRes = await app.inject({ method: "GET", url: "/api/update/status", headers: { cookie: session.cookies } });
     expect(statusRes.statusCode).toBe(200);
     expect(statusRes.json().job).toMatchObject({
       id: downloadJobId,
-      status: "queued",
+      status: expect.any(String),
       operation: "download",
       assetName,
       assetUrl: `https://updates.example/${assetName}`,
@@ -264,7 +348,7 @@ describe("更新 API", () => {
 
     const archiveBytes = readFileSync(archivePath);
     const digest = createHash("sha256").update(archiveBytes).digest("hex");
-    const assetName = `tallynote-1.3.0-${detectPlatform().target}-glibc.tar.gz`;
+    const assetName = `tallynote-9.9.9-${detectPlatform().target}-glibc.tar.gz`;
 
     // Mock a slow stream
     let fetchAborted = false;
@@ -291,7 +375,7 @@ describe("更新 API", () => {
         return new Response(stream, { status: 200, headers: { "content-length": String(archiveBytes.length) } });
       }
       return new Response(JSON.stringify({
-        tag_name: "v1.3.0",
+        tag_name: "v9.9.9",
         assets: [
           { name: "SHA256SUMS", browser_download_url: "https://updates.example/SHA256SUMS" },
           { name: assetName, browser_download_url: `https://updates.example/${assetName}` }
@@ -302,7 +386,7 @@ describe("更新 API", () => {
     const session = await login("update-cancel-inprocess");
     await app.inject({ method: "POST", url: "/api/update/check", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: {} });
 
-    const downloaded = await app.inject({ method: "POST", url: "/api/update/download", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "1.3.0", confirm: true } });
+    const downloaded = await app.inject({ method: "POST", url: "/api/update/download", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "9.9.9", confirm: true } });
     const downloadJobId = downloaded.json().job.id as string;
 
     // Wait until status becomes downloading
@@ -334,7 +418,7 @@ describe("更新 API", () => {
     const session = await login("update-cancel");
     mockRelease();
     await app.inject({ method: "POST", url: "/api/update/check", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: {} });
-    const applied = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "1.3.0", confirm: true } });
+    const applied = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: { version: "9.9.9", confirm: true } });
     expect(applied.statusCode).toBe(202);
     expect(existsSync(config.updateRequestPath)).toBe(true);
 

tests/update-apply-staging.test.ts

@@ -0,0 +1,319 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, mkdtemp, readFile, readlink, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { loadConfig, prepareDataDirectories, type AppConfig } from "../server/config.js";
+import { openDatabase } from "../server/db/index.js";
+import { main } from "../server/cli/update.js";
+import { createSafeArchive, detectPlatform } from "../server/update.js";
+
+/**
+ * Link-level coverage for the two-process update hand-off:
+ * the unprivileged web process stages a verified payload into
+ * `<dataDir>/staging/update-<jobId>`, then the privileged CLI (`main`) picks it
+ * up from a staged/apply DB row and switches the release.
+ *
+ * Ownership expectations are injected through `UpdateMainOverrides` because the
+ * suite runs as a non-root developer on macOS. Production defaults stay
+ * untouched: they never consult `process.getuid()`.
+ */
+
+const CURRENT_UID = process.getuid?.() ?? 0;
+const NEW_VERSION = "9.9.9";
+const METADATA_URL = "https://updates.example/latest";
+
+const TRACKED_ENV = [
+  "TALLYNOTE_DATA_DIR",
+  "TALLYNOTE_INSTALL_PREFIX",
+  "TALLYNOTE_PUBLIC_ORIGIN",
+  "TALLYNOTE_COOKIE_SECURE",
+  "TALLYNOTE_UPDATE_STRATEGY",
+  "TALLYNOTE_UPDATE_METADATA_URL",
+  "TALLYNOTE_UPDATE_ALLOWED_HOSTS",
+  "TALLYNOTE_UPDATE_REQUIRE_SIGNATURE",
+] as const;
+
+const baselineEnv = new Map<string, string | undefined>(TRACKED_ENV.map((key) => [key, process.env[key]]));
+const baselineArgv = [...process.argv];
+
+afterEach(() => {
+  for (const key of TRACKED_ENV) {
+    const value = baselineEnv.get(key);
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+  process.argv.splice(0, process.argv.length, ...baselineArgv);
+});
+
+type ApplyFixture = {
+  root: string;
+  config: AppConfig;
+  jobId: string;
+  stagedDir: string;
+  digest: string;
+  assetName: string;
+};
+
+type FixtureOptions = {
+  /** Shape of `<stagingDir>/update-<jobId>`: a real staged tree, a symlink
+   * masquerading as one, or nothing at all. */
+  stagedWorkspace?: "directory" | "symlink" | "absent";
+  /** Whether the staged archive that `assertStagedArchiveIntegrity` hashes. */
+  withArchive?: boolean;
+  /** Value written to `update_jobs.download_path`. The runner NULLs this column
+   * when it releases a workspace, so `null` is the post-runner production state. */
+  downloadPath?: "null" | "stale" | "outside-staging-root";
+  /** Whether the staged/apply row exists at all. */
+  withDatabaseRow?: boolean;
+};
+
+/** Build the exact on-disk state the web download step leaves behind before a
+ * privileged apply runs: release layout, staged workspace, staged/apply row and
+ * the request file the CLI is invoked with. */
+async function setupApplyFixture(options: FixtureOptions = {}): Promise<ApplyFixture> {
+  const root = await mkdtemp(path.join(tmpdir(), "tallynote-apply-staging-"));
+  const dataDir = path.join(root, "data");
+  const installPrefix = path.join(root, "install");
+  process.env.TALLYNOTE_DATA_DIR = dataDir;
+  process.env.TALLYNOTE_INSTALL_PREFIX = installPrefix;
+  process.env.TALLYNOTE_PUBLIC_ORIGIN = "http://127.0.0.1:3998";
+  process.env.TALLYNOTE_COOKIE_SECURE = "false";
+  process.env.TALLYNOTE_UPDATE_STRATEGY = "systemd";
+  process.env.TALLYNOTE_UPDATE_METADATA_URL = METADATA_URL;
+  process.env.TALLYNOTE_UPDATE_ALLOWED_HOSTS = "updates.example";
+  process.env.TALLYNOTE_UPDATE_REQUIRE_SIGNATURE = "false";
+  const config = loadConfig();
+  prepareDataDirectories(config);
+
+  // Installer layout with a live current release so `atomicSwitchRelease` has a
+  // real previous target to report.
+  await mkdir(config.releasesDir, { recursive: true, mode: 0o755 });
+  const previousRelease = path.join(config.releasesDir, config.appVersion);
+  await mkdir(path.join(previousRelease, "dist"), { recursive: true, mode: 0o755 });
+  await writeFile(path.join(previousRelease, "dist", "marker"), "old");
+  await symlink(previousRelease, config.currentLink);
+
+  const assetName = `tallynote-${NEW_VERSION}-${detectPlatform().target}.tar.gz`;
+  const source = path.join(root, "release-source");
+  await mkdir(path.join(source, "dist"), { recursive: true, mode: 0o700 });
+  await writeFile(path.join(source, "dist", "marker"), "new");
+  const archive = path.join(root, "release.tar.gz");
+  await createSafeArchive(source, archive);
+  const bytes = await readFile(archive);
+  const digest = createHash("sha256").update(bytes).digest("hex");
+
+  const jobId = randomUUID();
+  const stagedDir = path.join(config.stagingDir, `update-${jobId}`);
+  const stagedWorkspace = options.stagedWorkspace ?? "directory";
+  if (stagedWorkspace === "directory") {
+    await mkdir(path.join(stagedDir, "payload", "dist"), { recursive: true, mode: 0o700 });
+    await writeFile(path.join(stagedDir, "payload", "dist", "marker"), "new");
+    if (options.withArchive !== false) await writeFile(path.join(stagedDir, "release.tar.gz"), bytes, { mode: 0o600 });
+  } else if (stagedWorkspace === "symlink") {
+    // A symlinked workspace is the classic "swap the staged tree after the web
+    // process verified it" attack, and must never be followed by root.
+    const decoy = path.join(root, "decoy-workspace");
+    await mkdir(path.join(decoy, "payload", "dist"), { recursive: true, mode: 0o700 });
+    await writeFile(path.join(decoy, "payload", "dist", "marker"), "attacker");
+    await symlink(decoy, stagedDir);
+  }
+
+  let recordedDownloadPath: string | null = null;
+  if (options.downloadPath === "stale") recordedDownloadPath = path.join(root, "stale-workspace");
+  if (options.downloadPath === "outside-staging-root") {
+    recordedDownloadPath = path.join(root, "outside-workspace");
+    await mkdir(path.join(recordedDownloadPath, "payload", "dist"), { recursive: true, mode: 0o700 });
+  }
+
+  if (options.withDatabaseRow !== false) {
+    const database = openDatabase(config);
+    try {
+      const now = Date.now();
+      database.sqlite.prepare(`
+        INSERT INTO update_jobs(id, operation, status, version, platform, asset_name, asset_url,
+          expected_sha256, download_path, created_at, updated_at, requested_at)
+        VALUES (?, 'apply', 'staged', ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(jobId, NEW_VERSION, detectPlatform().target, assetName, `https://updates.example/${assetName}`, digest, recordedDownloadPath, now, now, now);
+    } finally {
+      database.sqlite.close();
+    }
+  }
+
+  await writeFile(config.updateRequestPath, JSON.stringify({
+    jobId,
+    operation: "apply",
+    version: NEW_VERSION,
+    metadataUrl: config.updateMetadataUrl,
+    assetUrl: `https://updates.example/${assetName}`,
+    assetName,
+    expectedSha256: digest,
+    requestedAt: Date.now(),
+    currentLink: config.currentLink,
+    releasesDir: config.releasesDir,
+    dataDir: config.dataDir,
+  }), { mode: 0o600 });
+
+  return { root, config, jobId, stagedDir, digest, assetName };
+}
+
+/** Invoke the privileged entry point the way the runner does: through the
+ * request file, which is the only path that reaches the staged apply branch. */
+async function runMain(fixture: ApplyFixture, overrides: { stagingOwnerUid?: number; workspaceOwnerUid?: number } = {}): Promise<void> {
+  process.argv.push("--request-file", fixture.config.updateRequestPath);
+  await main(fixture.config, {
+    stagingOwnerUid: overrides.stagingOwnerUid ?? CURRENT_UID,
+    workspaceOwnerUid: overrides.workspaceOwnerUid ?? CURRENT_UID,
+  });
+}
+
+function readJob(config: AppConfig, jobId: string): { status: string; operation: string; errorMessage: string | null; downloadPath: string | null } | undefined {
+  const database = openDatabase(config);
+  try {
+    return database.sqlite.prepare("SELECT status, operation, error_message AS errorMessage, download_path AS downloadPath FROM update_jobs WHERE id=?").get(jobId) as
+      { status: string; operation: string; errorMessage: string | null; downloadPath: string | null } | undefined;
+  } finally {
+    database.sqlite.close();
+  }
+}
+
+/** The audit row written by `failUpdateJobWithReason`, which carries the real
+ * machine-readable reason the UI renders instead of the runner's health text. */
+function readFailureAudit(config: AppConfig, jobId: string): { action: string; outcome: string; afterJson: string } | undefined {
+  const database = openDatabase(config);
+  try {
+    return database.sqlite.prepare("SELECT action, outcome, after_json AS afterJson FROM audit_events WHERE target_id=? ORDER BY id DESC LIMIT 1").get(jobId) as
+      { action: string; outcome: string; afterJson: string } | undefined;
+  } finally {
+    database.sqlite.close();
+  }
+}
+
+describe("web 暂存 → CLI apply 链路", () => {
+  it("场景 1：staged 行 + 暂存工作区存在时切换 current 到新 release", async () => {
+    const fixture = await setupApplyFixture();
+    try {
+      await runMain(fixture);
+
+      const link = await lstat(fixture.config.currentLink);
+      expect(link.isSymbolicLink()).toBe(true);
+      expect(await readlink(fixture.config.currentLink)).toBe(path.join(fixture.config.releasesDir, NEW_VERSION));
+      expect((await lstat(path.join(fixture.config.releasesDir, NEW_VERSION))).isDirectory()).toBe(true);
+      expect(await readFile(path.join(fixture.config.releasesDir, NEW_VERSION, "dist", "marker"), "utf8")).toBe("new");
+
+      // The web-owned staging tree is consumed and the row leaves the staged state.
+      expect(await lstat(fixture.stagedDir).catch(() => null)).toBeNull();
+      expect(readJob(fixture.config, fixture.jobId)).toMatchObject({ status: "applying", operation: "apply" });
+    } finally {
+      await rm(fixture.root, { recursive: true, force: true });
+    }
+  });
+
+  it("场景 2：download_path 为 NULL 时仍按 jobId 重建暂存工作区", async () => {
+    const fixture = await setupApplyFixture({ downloadPath: "null" });
+    try {
+      // Precondition: the runner already cleared the transient column.
+      expect(readJob(fixture.config, fixture.jobId)?.downloadPath).toBeNull();
+
+      await runMain(fixture);
+
+      expect(await readlink(fixture.config.currentLink)).toBe(path.join(fixture.config.releasesDir, NEW_VERSION));
+      expect(await readFile(path.join(fixture.config.releasesDir, NEW_VERSION, "dist", "marker"), "utf8")).toBe("new");
+    } finally {
+      await rm(fixture.root, { recursive: true, force: true });
+    }
+  });
+
+  it("场景 2b：download_path 指向已消失的陈旧路径时仍回退到 jobId 候选", async () => {
+    const fixture = await setupApplyFixture({ downloadPath: "stale" });
+    try {
+      expect(readJob(fixture.config, fixture.jobId)?.downloadPath).toBe(path.join(fixture.root, "stale-workspace"));
+
+      await runMain(fixture);
+
+      expect(await readlink(fixture.config.currentLink)).toBe(path.join(fixture.config.releasesDir, NEW_VERSION));
+    } finally {
+      await rm(fixture.root, { recursive: true, force: true });
+    }
+  });
+
+  it("场景 3：候选暂存目录不存在时拒绝并把行置为 failed", async () => {
+    const fixture = await setupApplyFixture({ stagedWorkspace: "absent" });
+    try {
+      await expect(runMain(fixture)).rejects.toThrow(/暂存目录已不存在/);
+
+      // No release may be published from a workspace that was never staged.
+      expect(await readlink(fixture.config.currentLink)).toBe(path.join(fixture.config.releasesDir, fixture.config.appVersion));
+      expect(await lstat(path.join(fixture.config.releasesDir, NEW_VERSION)).catch(() => null)).toBeNull();
+
+      const job = readJob(fixture.config, fixture.jobId);
+      expect(job?.status).toBe("failed");
+      expect(job?.errorMessage).toBe("暂存目录已不存在，请重新下载");
+      expect(readFailureAudit(fixture.config, fixture.jobId)).toMatchObject({ action: "update.failed", outcome: "failure" });
+      expect(JSON.parse(readFailureAudit(fixture.config, fixture.jobId)!.afterJson)).toMatchObject({ reason: "staged_workspace_missing" });
+    } finally {
+      await rm(fixture.root, { recursive: true, force: true });
+    }
+  });
+
+  it("场景 4a：暂存工作区是符号链接时拒绝执行", async () => {
+    const fixture = await setupApplyFixture({ stagedWorkspace: "symlink" });
+    try {
+      await expect(runMain(fixture)).rejects.toThrow(/更新暂存目录权限无效/);
+
+      // The decoy payload must never be promoted to a release.
+      expect(await readlink(fixture.config.currentLink)).toBe(path.join(fixture.config.releasesDir, fixture.config.appVersion));
+      expect(await lstat(path.join(fixture.config.releasesDir, NEW_VERSION)).catch(() => null)).toBeNull();
+
+      expect(readJob(fixture.config, fixture.jobId)?.status).toBe("failed");
+      expect(readJob(fixture.config, fixture.jobId)?.errorMessage).toBe("更新暂存目录权限无效");
+      expect(JSON.parse(readFailureAudit(fixture.config, fixture.jobId)!.afterJson)).toMatchObject({ reason: "staged_workspace_insecure" });
+    } finally {
+      await rm(fixture.root, { recursive: true, force: true });
+    }
+  });
+
+  it("场景 4b：记录路径位于 stagingDir 之外时拒绝，即使暂存目录缺失", async () => {
+    const fixture = await setupApplyFixture({ stagedWorkspace: "absent", downloadPath: "outside-staging-root" });
+    try {
+      await expect(runMain(fixture)).rejects.toThrow(/更新暂存路径无效/);
+
+      expect(await lstat(path.join(fixture.config.releasesDir, NEW_VERSION)).catch(() => null)).toBeNull();
+      expect(readJob(fixture.config, fixture.jobId)?.status).toBe("failed");
+      expect(JSON.parse(readFailureAudit(fixture.config, fixture.jobId)!.afterJson)).toMatchObject({ reason: "staged_workspace_invalid" });
+    } finally {
+      await rm(fixture.root, { recursive: true, force: true });
+    }
+  });
+
+  it("场景 5：暂存区属主与期望 uid 不符时拒绝", async () => {
+    const fixture = await setupApplyFixture();
+    try {
+      await expect(runMain(fixture, { stagingOwnerUid: CURRENT_UID + 1 })).rejects.toThrow(/更新暂存根目录权限无效/);
+
+      expect(await readlink(fixture.config.currentLink)).toBe(path.join(fixture.config.releasesDir, fixture.config.appVersion));
+      const job = readJob(fixture.config, fixture.jobId);
+      expect(job?.status).toBe("failed");
+      expect(job?.errorMessage).toBe("更新暂存根目录权限无效");
+      expect(JSON.parse(readFailureAudit(fixture.config, fixture.jobId)!.afterJson)).toMatchObject({ reason: "apply_precheck_failed" });
+    } finally {
+      await rm(fixture.root, { recursive: true, force: true });
+    }
+  });
+
+  it("场景 5b：工作区属主与期望 uid 不符时在 preflight 阶段拒绝", async () => {
+    const fixture = await setupApplyFixture();
+    try {
+      await expect(runMain(fixture, { workspaceOwnerUid: CURRENT_UID + 1 })).rejects.toThrow(/更新工作目录必须是 root 拥有且权限为 0700/);
+
+      expect(await lstat(path.join(fixture.config.releasesDir, NEW_VERSION)).catch(() => null)).toBeNull();
+      expect(await readlink(fixture.config.currentLink)).toBe(path.join(fixture.config.releasesDir, fixture.config.appVersion));
+      // The preflight rejection happens before the database is opened, so the
+      // row is left staged for the runner to finalize. Recorded as observed
+      // behavior, not asserted as a requirement.
+      expect(readJob(fixture.config, fixture.jobId)?.status).toBe("staged");
+    } finally {
+      await rm(fixture.root, { recursive: true, force: true });
+    }
+  });
+});

tests/update.test.ts

@@ -40,23 +40,23 @@ describe("更新安全工具", () => {
     expect(isNewerVersion("1.0.0", "1.0.0-beta.1")).toBe(false);
     expect(detectPlatform("linux", "x86_64").target).toBe("linux-x64");
     const release = {
-      version: "1.3.0",
+      version: "9.9.9",
       assets: [
-        { name: "tallynote-1.3.0-linux-arm64-glibc.tar.gz", url: "https://updates.example/arm" },
-        { name: "tallynote-1.3.0-linux-x64-glibc.tar.gz", url: "https://updates.example/x64" },
+        { name: "tallynote-9.9.9-linux-arm64-glibc.tar.gz", url: "https://updates.example/arm" },
+        { name: "tallynote-9.9.9-linux-x64-glibc.tar.gz", url: "https://updates.example/x64" },
       ],
     };
     expect(selectReleaseAsset(release, detectPlatform("linux", "x86_64"))?.name).toContain("linux-x64");
-    expect(selectReleaseAsset({ version: "1.3.0", assets: [{ name: "tallynote-1.3.0-linux-arm64-glibc.tar.gz", url: "https://updates.example/arm" }] }, detectPlatform("linux", "x86_64"))).toBeUndefined();
+    expect(selectReleaseAsset({ version: "9.9.9", assets: [{ name: "tallynote-9.9.9-linux-arm64-glibc.tar.gz", url: "https://updates.example/arm" }] }, detectPlatform("linux", "x86_64"))).toBeUndefined();
     expect(() => validateHttpsUrl("http://updates.example/x64", { allowedHosts: ["updates.example"] })).toThrow();
     expect(() => sanitizeAssetName("../release.tar.gz")).toThrow();
   });
 
   it("优先选择运行时匹配的轻量更新包，并对旧客户端保留完整包回退", () => {
     const runtimeHash = runtimeHashFromLockfile("lockfile-v1\n");
-    const full = { name: "tallynote-1.3.0-linux-x64-glibc.tar.gz", url: "https://updates.example/full" };
-    const app = { name: `tallynote-1.3.0-linux-x64-glibc.update-${runtimeHash}.tar.gz`, url: "https://updates.example/app" };
-    const release = { version: "1.3.0", assets: [full, app] };
+    const full = { name: "tallynote-9.9.9-linux-x64-glibc.tar.gz", url: "https://updates.example/full" };
+    const app = { name: `tallynote-9.9.9-linux-x64-glibc.update-${runtimeHash}.tar.gz`, url: "https://updates.example/app" };
+    const release = { version: "9.9.9", assets: [full, app] };
     expect(applicationUpdateRuntimeHash(app.name)).toBe(runtimeHash);
     expect(selectReleaseAsset(release, detectPlatform("linux", "x86_64"), runtimeHash)).toEqual(app);
     expect(selectReleaseAsset(release, detectPlatform("linux", "x86_64"))).toEqual(full);
@@ -102,12 +102,12 @@ describe("更新安全工具", () => {
     globalThis.fetch = (async (input: string | URL) => {
       const url = input.toString();
       if (url.endsWith("/latest")) {
-        return new Response(JSON.stringify({ tag_name: "v1.3.0", assets: [{ name: "SHA256SUMS", browser_download_url: "https://updates.example/SHA256SUMS" }, { name: "app-linux-x64.tar.gz", browser_download_url: "https://updates.example/app-linux-x64.tar.gz" }] }), { status: 200, headers: { "content-type": "application/json" } });
+        return new Response(JSON.stringify({ tag_name: "v9.9.9", assets: [{ name: "SHA256SUMS", browser_download_url: "https://updates.example/SHA256SUMS" }, { name: "app-linux-x64.tar.gz", browser_download_url: "https://updates.example/app-linux-x64.tar.gz" }] }), { status: 200, headers: { "content-type": "application/json" } });
       }
       return new Response(`${digest}  app-linux-x64.tar.gz\n`, { status: 200 });
     }) as typeof fetch;
     const metadata = await fetchReleaseMetadata("https://updates.example/latest", { allowedHosts: ["updates.example"] });
-    expect(metadata.version).toBe("1.3.0");
+    expect(metadata.version).toBe("9.9.9");
     expect((await fetchReleaseText("https://updates.example/SHA256SUMS", { allowedHosts: ["updates.example"] })).trim()).toContain(digest);
   });
 
@@ -253,22 +253,22 @@ describe("更新安全工具", () => {
       const jobId = randomUUID();
       database = openDatabase(config);
       const now = Date.now();
-      const assetName = `tallynote-1.3.0-${detectPlatform().target}.tar.gz`;
+      const assetName = `tallynote-9.9.9-${detectPlatform().target}.tar.gz`;
       database.sqlite.prepare(`
         INSERT INTO update_jobs(id, operation, status, version, platform, asset_url,
           expected_sha256, created_at, updated_at, requested_at)
-        VALUES (?, 'apply', 'queued', '1.3.0', ?, ?, ?, ?, ?, ?)
+        VALUES (?, 'apply', 'queued', '9.9.9', ?, ?, ?, ?, ?, ?)
       `).run(jobId, detectPlatform().target, "https://updates.example/" + assetName, digest, now, now, now);
       globalThis.fetch = (async (input: string | URL) => {
         const url = input.toString();
-        if (url.endsWith("/latest")) return new Response(JSON.stringify({ tag_name: "v1.3.0", assets: [{ name: assetName, browser_download_url: `https://updates.example/${assetName}` }, { name: "SHA256SUMS", browser_download_url: "https://updates.example/SHA256SUMS" }] }));
+        if (url.endsWith("/latest")) return new Response(JSON.stringify({ tag_name: "v9.9.9", assets: [{ name: assetName, browser_download_url: `https://updates.example/${assetName}` }, { name: "SHA256SUMS", browser_download_url: "https://updates.example/SHA256SUMS" }] }));
         if (url.endsWith("SHA256SUMS")) return new Response(`${digest}  ${assetName}\n`);
         return new Response(bytes, { headers: { "content-length": String(bytes.length) } });
       }) as typeof fetch;
 
       await runUpdate({
         metadataUrl: config.updateMetadataUrl,
-        version: "1.3.0",
+        version: "9.9.9",
         currentVersion: config.appVersion,
         currentDir: config.currentLink,
         stagingDir: path.join(root, "staging"),
@@ -286,8 +286,27 @@ describe("更新安全工具", () => {
       expect(await readFile(path.join(config.currentLink, "dist", "marker"), "utf8")).toBe("new");
       const row = database.sqlite.prepare("SELECT operation, status FROM update_jobs WHERE id=?").get(jobId);
       expect(row).toEqual({ operation: "apply", status: "applying" });
-      finalizeUpdateJob(database.sqlite, jobId, "failed");
-      expect(database.sqlite.prepare("SELECT status FROM update_jobs WHERE id=?").get(jobId)).toEqual({ status: "failed" });
+      finalizeUpdateJob(database.sqlite, jobId, "failed", "健康检查失败（自定义）");
+      expect(database.sqlite.prepare("SELECT status, error_message AS errorMessage FROM update_jobs WHERE id=?").get(jobId)).toEqual({ status: "failed", errorMessage: "健康检查失败（自定义）" });
+      finalizeUpdateJob(database.sqlite, jobId, "failed", "第二次 finalize 不应覆盖原消息");
+      expect(database.sqlite.prepare("SELECT status, error_message AS errorMessage FROM update_jobs WHERE id=?").get(jobId)).toEqual({ status: "failed", errorMessage: "健康检查失败（自定义）" });
+      expect(database.sqlite.prepare("SELECT COUNT(*) AS count FROM audit_events WHERE action='update.failed' AND target_id=?").get(jobId)).toEqual({ count: 1 });
+      const defaultJobId = randomUUID();
+      database.sqlite.prepare(`
+        INSERT INTO update_jobs(id, operation, status, version, platform, asset_url, created_at, updated_at)
+        VALUES (?, 'apply', 'applying', '9.9.9', ?, ?, ?, ?)
+      `).run(defaultJobId, detectPlatform().target, "https://updates.example/" + assetName, now, now);
+      finalizeUpdateJob(database.sqlite, defaultJobId, "failed", "");
+      expect(database.sqlite.prepare("SELECT error_message AS errorMessage FROM update_jobs WHERE id=?").get(defaultJobId)).toEqual({ errorMessage: "新版本健康检查失败，已恢复上一版本" });
+      const completedJobId = randomUUID();
+      database.sqlite.prepare(`
+        INSERT INTO update_jobs(id, operation, status, version, platform, asset_url, created_at, updated_at)
+        VALUES (?, 'apply', 'completed', '9.9.9', ?, ?, ?, ?)
+      `).run(completedJobId, detectPlatform().target, "https://updates.example/" + assetName, now, now);
+      finalizeUpdateJob(database.sqlite, completedJobId, "completed");
+      expect(database.sqlite.prepare("SELECT COUNT(*) AS count FROM audit_events WHERE action='update.completed' AND target_id=?").get(completedJobId)).toEqual({ count: 0 });
+      expect(() => finalizeUpdateJob(database.sqlite, completedJobId, "failed", "不能降级已完成任务")).toThrow("更新任务状态不允许完成");
+      expect(database.sqlite.prepare("SELECT status FROM update_jobs WHERE id=?").get(completedJobId)).toEqual({ status: "completed" });
     } finally {
       globalThis.fetch = previousFetch;
       if (database) database.sqlite.close();
@@ -323,10 +342,16 @@ describe("更新安全工具", () => {
       const applyingId = randomUUID();
       const stagedId = randomUUID();
       const stagedApplyId = randomUUID();
-      insert.run(queuedId, "apply", "queued", "1.3.0", "linux-x64", "https://updates.example/queued.tar.gz", staleAt, staleAt);
+      insert.run(queuedId, "apply", "queued", "9.9.9", "linux-x64", "https://updates.example/queued.tar.gz", staleAt, staleAt);
       insert.run(applyingId, "apply", "applying", config.appVersion, "linux-x64", "https://updates.example/applying.tar.gz", staleAt, staleAt);
-      insert.run(stagedId, "download", "staged", "1.3.0", "linux-x64", "https://updates.example/staged.tar.gz", staleAt, staleAt);
-      insert.run(stagedApplyId, "apply", "staged", "1.3.0", "linux-x64", "https://updates.example/staged-apply.tar.gz", staleAt, staleAt);
+      insert.run(stagedId, "download", "staged", "9.9.9", "linux-x64", "https://updates.example/staged.tar.gz", staleAt, staleAt);
+      insert.run(stagedApplyId, "apply", "staged", "9.9.9", "linux-x64", "https://updates.example/staged-apply.tar.gz", staleAt, staleAt);
+      // A staged row is only actionable while its staged payload exists. The
+      // real download path always creates `update-<id>` before flipping a job
+      // to `staged`, so create the workspace here too; otherwise the fixture
+      // tests an impossible state where the row claims an artifact it never had.
+      await mkdir(path.join(config.stagingDir, `update-${stagedId}`), { recursive: true });
+      await mkdir(path.join(config.stagingDir, `update-${stagedApplyId}`), { recursive: true });
       const now = Date.now();
       expect(reconcileOrphanedUpdateJobs(database.sqlite, config, now)).toBe(3);
       expect(database.sqlite.prepare("SELECT status FROM update_jobs WHERE id=?").get(queuedId)).toEqual({ status: "failed" });
@@ -362,7 +387,7 @@ describe("更新安全工具", () => {
       const jobId = randomUUID();
       database.sqlite.prepare(`
         INSERT INTO update_jobs(id, operation, status, version, platform, asset_url, created_at, updated_at)
-        VALUES (?, 'download', 'downloading', '1.3.0', 'linux-x64', ?, ?, ?)
+        VALUES (?, 'download', 'downloading', '9.9.9', 'linux-x64', ?, ?, ?)
       `).run(jobId, "https://updates.example/download.tar.gz", staleAt, staleAt);
       await writeFile(config.updateRequestPath, JSON.stringify({ jobId, operation: "download" }));
       const statePath = path.join(config.installPrefix, ".update-state");
@@ -385,7 +410,7 @@ describe("更新安全工具", () => {
     }
   });
 
-  it("队列任务有新请求标记时可被重新检查，标记过期后才回收", async () => {
+  it("队列任务有匹配请求标记时保留到租约过期，过期后才回收", async () => {
     const root = await mkdtemp(path.join(tmpdir(), "tallynote-update-queued-marker-"));
     let database: ReturnType<typeof openDatabase> | undefined;
     try {
@@ -406,18 +431,20 @@ describe("更新安全工具", () => {
       const jobId = randomUUID();
       database.sqlite.prepare(`
         INSERT INTO update_jobs(id, operation, status, version, platform, asset_url, created_at, updated_at)
-        VALUES (?, 'apply', 'queued', '1.3.0', 'linux-x64', ?, ?, ?)
+        VALUES (?, 'apply', 'queued', '9.9.9', 'linux-x64', ?, ?, ?)
       `).run(jobId, "https://updates.example/queued.tar.gz", staleAt, staleAt);
       await writeFile(config.updateRequestPath, JSON.stringify({ jobId, operation: "apply" }));
       const now = Date.now();
       await utimes(config.updateRequestPath, new Date(now), new Date(now));
 
-      expect(reconcileOrphanedUpdateJobs(database.sqlite, config, now)).toBe(1);
-      expect(database.sqlite.prepare("SELECT status FROM update_jobs WHERE id=?").get(jobId)).toEqual({ status: "failed" });
-      await expect(stat(config.updateRequestPath)).rejects.toThrow();
+      // The DB row is old, but the request marker is fresh and names this
+      // exact job. Keep it queued while systemd has a chance to consume it.
+      expect(reconcileOrphanedUpdateJobs(database.sqlite, config, now)).toBe(0);
+      expect(database.sqlite.prepare("SELECT status FROM update_jobs WHERE id=?").get(jobId)).toEqual({ status: "queued" });
+      await expect(stat(config.updateRequestPath)).resolves.toBeTruthy();
 
       const expiredNow = now + ORPHANED_UPDATE_TIMEOUT_MS + 1;
-      expect(reconcileOrphanedUpdateJobs(database.sqlite, config, expiredNow)).toBe(0);
+      expect(reconcileOrphanedUpdateJobs(database.sqlite, config, expiredNow)).toBe(1);
       expect(database.sqlite.prepare("SELECT status FROM update_jobs WHERE id=?").get(jobId)).toEqual({ status: "failed" });
       await expect(stat(config.updateRequestPath)).rejects.toThrow();
     } finally {
@@ -434,11 +461,9 @@ describe("更新安全工具", () => {
       await mkdir(path.join(source, "dist", "server"), { recursive: true });
       await mkdir(path.join(source, "bin"), { recursive: true });
       await mkdir(path.join(source, "scripts"), { recursive: true });
-      await mkdir(path.join(source, "runtime", "bin"), { recursive: true });
       await writeFile(path.join(source, "dist", "server", "large.js"), Buffer.alloc(2 * 1024 * 1024, 0x41));
       await writeFile(path.join(source, "bin", "tallynote"), "#!/bin/sh\n");
       await writeFile(path.join(source, "scripts", "runner.sh"), "#!/bin/sh\n");
-      await writeFile(path.join(source, "runtime", "bin", "node"), "node");
       const archive = path.join(root, "release.tar.gz");
       await createSafeArchive(source, archive);
       expect((await stat(archive)).size).toBeLessThan(64 * 1024);
@@ -451,7 +476,7 @@ describe("更新安全工具", () => {
       expect((await stat(path.join(destination, "dist", "server", "large.js"))).mode & 0o777).toBe(0o644);
       expect((await stat(path.join(destination, "bin", "tallynote"))).mode & 0o777).toBe(0o755);
       expect((await stat(path.join(destination, "scripts", "runner.sh"))).mode & 0o777).toBe(0o755);
-      expect((await stat(path.join(destination, "runtime", "bin", "node"))).mode & 0o777).toBe(0o755);
+      expect(await stat(path.join(destination, "runtime")).catch(() => null)).toBeNull();
     } finally {
       await rm(root, { recursive: true, force: true });
     }
@@ -492,17 +517,17 @@ describe("更新元数据缓存", () => {
     prepareDataDirectories(config);
     const database = openDatabase(config);
     const digest = "b".repeat(64);
-    const platformAsset = `tallynote-1.3.0-${detectPlatform().target}-glibc.tar.gz`;
+    const platformAsset = `tallynote-9.9.9-${detectPlatform().target}-glibc.tar.gz`;
     const sums = `${digest}  ${platformAsset}\n`;
     const signature = sign(null, Buffer.from(sums), privateKey);
     globalThis.fetch = (async (input: string | URL) => input.toString().endsWith("SHA256SUMS.sig")
       ? new Response(signature)
       : input.toString().endsWith("SHA256SUMS")
       ? new Response(sums)
-      : new Response(JSON.stringify({ tag_name: "v1.3.0", published_at: "2026-08-28T00:00:00Z", assets: [{ name: "SHA256SUMS", browser_download_url: "https://updates.example/SHA256SUMS" }, { name: "SHA256SUMS.sig", browser_download_url: "https://updates.example/SHA256SUMS.sig" }, { name: platformAsset, browser_download_url: `https://updates.example/${platformAsset}` }] }), { status: 200 })) as typeof fetch;
+      : new Response(JSON.stringify({ tag_name: "v9.9.9", published_at: "2026-08-28T00:00:00Z", assets: [{ name: "SHA256SUMS", browser_download_url: "https://updates.example/SHA256SUMS" }, { name: "SHA256SUMS.sig", browser_download_url: "https://updates.example/SHA256SUMS.sig" }, { name: platformAsset, browser_download_url: `https://updates.example/${platformAsset}` }] }), { status: 200 })) as typeof fetch;
     try {
       const result = await checkForUpdate(database.sqlite, config);
-      expect(result.latest).toMatchObject({ version: "1.3.0", compatible: true, integrityReady: true, signatureReady: true, isNewer: true });
+      expect(result.latest).toMatchObject({ version: "9.9.9", compatible: true, integrityReady: true, signatureReady: true, isNewer: true });
       const cached = database.sqlite.prepare("SELECT value FROM system_settings WHERE key='update.release.v1'").get() as { value: string };
       expect(JSON.parse(cached.value).asset.sha256).toBe(digest);
     } finally {

uninstall.sh

@@ -417,6 +417,7 @@ remove_prefix() {
     log "warning: 保留非符号链接 current：$current"
   fi
   remove_tree "$releases" 'releases'
+  remove_managed_node
   remove_tree "$PREFIX/.update-work" 'update work'
   remove_file_if_owned "$PREFIX/.update-state" 'update state'
   if [[ -d "$PREFIX" && ! -L "$PREFIX" ]]; then
@@ -429,6 +430,33 @@ remove_prefix() {
   fi
 }
 
+remove_managed_node() {
+  local node_root="$PREFIX/nodejs" marker
+  [[ -e "$node_root" || -L "$node_root" ]] || return 0
+  [[ -d "$node_root" && ! -L "$node_root" ]] || die "Node.js 管理目录不是安全目录：$node_root"
+  marker="$node_root/.tallynote-managed"
+  if [[ ! -f "$marker" || "$(sed -n '1p' "$marker" 2>/dev/null)" != tallynote-managed-node-v1 ]]; then
+    log "保留非 TallyNote 管理的 Node.js 目录：$node_root"
+    return 0
+  fi
+  allowed_owner "$node_root" || die "Node.js 管理目录的所有者不受信任：$node_root"
+  # Node distributions contain npm/corepack symlinks. They are safe to remove
+  # because rm never follows symlinks; validate ownership and permissions for
+  # every node while deliberately permitting those internal links.
+  local node mode_bits
+  while IFS= read -r node; do
+    allowed_owner "$node" || die "Node.js 管理目录节点的所有者不受信任：$node"
+    [[ -L "$node" ]] && continue
+    mode_bits=$(stat_mode_bits "$node")
+    (( (mode_bits & 18) == 0 )) || die "Node.js 管理目录权限过宽：$node"
+  done < <(find "$node_root" -print)
+  if (( DRY_RUN )); then
+    log "dry-run: remove managed Node.js $node_root"
+  else
+    rm -rf -- "$node_root"
+  fi
+}
+
 remove_config() {
   remove_file_if_owned "$CONFIG_DIR/update-signing-key.pub" 'update public key'
   remove_file_if_owned "$CONFIG_DIR/tallynote.env" 'environment file'

web-next/src/main.tsx

@@ -32,9 +32,9 @@ function App() {
   const logoutInFlight = useRef(false);
   useDialogAccessibility();
   const notify = useCallback((message: string, kind: "success" | "error" | "info" = "info") => {
-    // The placement container owns the responsive right inset. Keeping the
-    // item offset at zero avoids pushing narrow-screen notices off canvas.
-    const options = { content: message, duration: 4200, placement: "top-right" as const, offset: [24, 76] as [number, number], zIndex: 6000 };
+    // Keep notices in the lower-right safe area so they do not compete with
+    // the header controls or obscure the page title.
+    const options = { content: message, duration: 4200, placement: "bottom-right" as const, offset: [24, 24] as [number, number], zIndex: 6000 };
     const show = kind === "success" ? NotificationPlugin.success : kind === "error" ? NotificationPlugin.error : NotificationPlugin.info;
     void show(options);
   }, []);

web-next/src/pages/update/UpdatePage.tsx

@@ -21,19 +21,14 @@ import {
   X,
   FileCode,
   HardDrive,
-  Terminal,
 } from "lucide-react";
-import { Button, Card, Dialog, RadioGroup, Radio, Steps, Tag, Tooltip } from "tdesign-react";
+import { Button, Card, Dialog, Steps, Tag, Tooltip } from "tdesign-react";
 import { Page, Surface } from "../common";
-import { api } from "../../services/api";
+import { api, ApiError } from "../../services/api";
 import { dateText } from "../../utils/date";
-import type { MockScenario, MockUpdateState } from "./mockData";
 
 const { StepItem } = Steps;
 
-// Enable mock preview in local development
-const MOCK_PREVIEW_ENABLED = import.meta.env.DEV;
-
 export type JobStatus =
   | "queued"
   | "downloading"
@@ -234,14 +229,8 @@ export default function UpdatePage({
   timezone?: string;
   notify?: (msg: string, type?: "success" | "info" | "error") => void;
 }) {
-  // Mock mode switcher for local developer preview
-  const [mockScenario, setMockScenario] = useState<"live" | MockScenario>("live");
-  const mockTimer = useRef<number | null>(null);
-  const [mockCatalog, setMockCatalog] = useState<Record<MockScenario, MockUpdateState> | null>(null);
-
   // Live state
   const [liveInfo, setLiveInfo] = useState<UpdateInfo | null>(null);
-  const [mockInfoState, setMockInfoState] = useState<UpdateInfo | null>(null);
   const [loading, setLoading] = useState(true);
   const [checking, setChecking] = useState(false);
   const [error, setError] = useState("");
@@ -259,67 +248,53 @@ export default function UpdatePage({
   const announced = useRef<string | null>(null);
   const checkInFlight = useRef(false);
   const actionInFlight = useRef(false);
+  const cancelInFlight = useRef(false);
+  const loadInFlight = useRef(false);
   const disconnected = useRef(false);
   const recoveredNotice = useRef(false);
 
-  // Active info depending on mock vs live
-  const isMock = MOCK_PREVIEW_ENABLED && mockScenario !== "live" && Boolean(mockCatalog);
-  const selectedMock = mockScenario !== "live" ? mockCatalog?.[mockScenario] : undefined;
-  const info = isMock && selectedMock ? (mockInfoState ?? selectedMock.info) : liveInfo;
+  const info = liveInfo;
 
-  // Handle mock scenario change
-  const handleScenarioChange = (scenario: "live" | MockScenario) => {
-    setMockScenario(scenario);
-    if (mockTimer.current !== null) {
-      window.clearTimeout(mockTimer.current);
-      mockTimer.current = null;
-    }
-    if (scenario !== "live") {
-      const next = mockCatalog?.[scenario];
-      if (!next) return;
-      setMockInfoState(JSON.parse(JSON.stringify(next.info)));
-      notify?.(`已切换至 Mock 场景：${next.title}`, "info");
-    } else {
-      setMockInfoState(null);
-      notify?.("已切回真实后端模式", "info");
-    }
+  const mergeInfo = (incoming: UpdateInfo, preserveJob = false) => {
+    setLiveInfo((current) => {
+      if (!current) return incoming;
+      const next = {
+        ...current,
+        ...incoming,
+        // A check response describes the release, but must not erase the job
+        // that is already being displayed while that check is in flight.
+        job: preserveJob
+          ? (current.job ?? incoming.job)
+          : (!Object.prototype.hasOwnProperty.call(incoming, "job") ? current.job : incoming.job),
+      };
+      // Some status/check responses are intentionally partial. Keep fields
+      // from the last successful response when a field is omitted.
+      if (!Object.prototype.hasOwnProperty.call(incoming, "latest")) next.latest = current.latest;
+      if (!Object.prototype.hasOwnProperty.call(incoming, "checkedAt")) next.checkedAt = current.checkedAt;
+      if (!Object.prototype.hasOwnProperty.call(incoming, "strategy")) next.strategy = current.strategy;
+      return next;
+    });
   };
 
-  useEffect(() => () => {
-    if (mockTimer.current !== null) window.clearTimeout(mockTimer.current);
-  }, []);
-
-  useEffect(() => {
-    if (!import.meta.env.DEV) return;
-    let disposed = false;
-    void import("./mockData").then(({ MOCK_SCENARIOS }) => {
-      if (!disposed) setMockCatalog(MOCK_SCENARIOS);
-    });
-    return () => {
-      disposed = true;
-    };
-  }, []);
-
-  const load = async () => {
-    if (isMock) return;
-    setLoading(true);
+  const load = async (showLoading = true): Promise<UpdateInfo | null> => {
+    if (loadInFlight.current) return null;
+    loadInFlight.current = true;
+    if (showLoading) setLoading(true);
     setError("");
     try {
       const res = await api<UpdateInfo>("/api/update/status");
-      setLiveInfo(res);
+      mergeInfo(res);
       updateInfoCache = res;
+      return res;
     } catch (e) {
       setError((e as Error).message);
+      return null;
     } finally {
-      setLoading(false);
+      if (showLoading) setLoading(false);
+      loadInFlight.current = false;
     }
   };
 
-  useEffect(() => {
-    if (!isMock) void load();
-    else setLoading(false);
-  }, [isMock]);
-
   // Keep terminal jobs visible so operators can understand what happened and
   // recover without guessing. The polling effect below only polls active jobs.
   const job = info?.job ?? null;
@@ -342,9 +317,9 @@ export default function UpdatePage({
     return () => window.clearInterval(timer);
   }, [restartAt]);
 
-  // Live polling effect: only poll when active job exists
+  // Live polling effect for an active job. Completed responses are refreshed
+  // once so latest/checkedAt/strategy stay current; other terminal states stay visible.
   useEffect(() => {
-    if (isMock) return;
     const shouldPoll = Boolean(
       job && (pollableStatuses.has(job.status) || (job.status === "staged" && job.operation === "apply"))
     );
@@ -376,23 +351,53 @@ export default function UpdatePage({
           setReloadReady(true);
           notify?.("系统升级完成，请刷新页面", "success");
         }
-        if (
+        if (result.job.status === "completed") {
+          void load(false);
+        } else if (
           pollableStatuses.has(result.job.status) ||
           (result.job.status === "staged" && result.job.operation === "apply")
         ) {
           schedule(1500);
         }
-      } catch {
+      } catch (caught) {
         if (disposed) return;
+        const status = caught instanceof ApiError ? caught.status : 0;
+        const message = caught instanceof Error ? caught.message : "读取更新任务状态失败";
+        if (status === 404) {
+          setPollError("更新任务已结束，正在刷新状态。");
+          void load(false);
+          return;
+        }
+        if (status === 401) {
+          setPollError("登录已失效，请重新登录。");
+          return;
+        }
+        if (status === 403) {
+          setPollError("没有权限读取更新任务状态。");
+          return;
+        }
+
         failures += 1;
-        disconnected.current = true;
+        disconnected.current = status === 0 || status === 408;
         recoveredNotice.current = false;
-        setPollError(
-          `服务正在平滑重启${
-            restartSeconds !== null ? `，预计 ${restartSeconds} 秒后恢复` : "，页面正在自动探活重试"
-          }。升级任务仍在后台安全执行。`
-        );
-        schedule(Math.min(1500 * 2 ** Math.min(failures, 3), 10_000));
+        if (status === 409) {
+          setPollError(`${message}，正在刷新状态。`);
+          void load(false);
+          return;
+        }
+        if (status === 429) {
+          setPollError(`${message}，稍后继续同步。`);
+        } else if (status === 408) {
+          setPollError("读取更新任务状态超时，正在重试。");
+        } else if (status === 0) {
+          setPollError("更新服务连接异常，正在重试。");
+        } else {
+          setPollError(`${message}，正在重试。`);
+        }
+        const retryAfter = caught instanceof ApiError && caught.retryAfter
+          ? Math.max(1000, caught.retryAfter * 1000)
+          : Math.min(1500 * 2 ** Math.min(failures, 3), 10_000);
+        schedule(retryAfter);
       }
     };
     void poll();
@@ -400,36 +405,97 @@ export default function UpdatePage({
       disposed = true;
       if (timer !== undefined) window.clearTimeout(timer);
     };
-  }, [isMock, job?.id, job?.status, job?.operation, notify]);
+  }, [job?.id, job?.status, job?.operation, notify]);
+
+  // With no visible job, make a low-frequency status request so a task created
+  // elsewhere can still appear without creating a request storm.
+  useEffect(() => {
+    if (job) return;
+    let timer: number | undefined;
+    let disposed = false;
+    const discover = () => {
+      if (disposed || document.visibilityState !== "visible") return;
+      void load(false);
+    };
+    const schedule = () => {
+      if (disposed) return;
+      if (timer !== undefined) window.clearTimeout(timer);
+      timer = window.setTimeout(() => {
+        discover();
+        schedule();
+      }, 5000);
+    };
+    const onVisibilityChange = () => {
+      if (document.visibilityState === "visible") {
+        discover();
+        schedule();
+      } else if (timer !== undefined) {
+        window.clearTimeout(timer);
+        timer = undefined;
+      }
+    };
+    if (document.visibilityState === "visible") schedule();
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    return () => {
+      disposed = true;
+      if (timer !== undefined) window.clearTimeout(timer);
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    };
+  }, [job?.id, job?.status, job?.operation]);
 
   // Check update handler
   const check = async () => {
-    if (isMock) {
-      setChecking(true);
-      window.setTimeout(() => {
-        setChecking(false);
-        notify?.("Mock：检查完成，已是最新配置状态", "success");
-      }, 600);
-      return;
-    }
     if (checkInFlight.current) return;
     checkInFlight.current = true;
     setChecking(true);
     setError("");
     try {
-      setLiveInfo(await api<UpdateInfo>("/api/update/check", { method: "POST" }));
+      const result = await api<UpdateInfo>("/api/update/check", { method: "POST" });
+      // The check endpoint returns release metadata but not task state. Read
+      // the status endpoint once more so reconciliation performed before the
+      // check is authoritative: an expired staged task must disappear from
+      // this page immediately instead of surviving until a full refresh.
+      const status = await api<UpdateInfo>("/api/update/status");
+      setLiveInfo((current) => ({
+        ...(current ?? result),
+        ...result,
+        job: status.job,
+      }));
       notify?.("版本检查完成", "info");
     } catch (e) {
-      setError((e as Error).message);
+      if (e instanceof ApiError && e.status === 429) {
+        notify?.((e as Error).message, "error");
+      } else {
+        setError((e as Error).message);
+      }
     } finally {
       setChecking(false);
       checkInFlight.current = false;
     }
   };
 
+  useEffect(() => {
+    let disposed = false;
+    const bootstrap = async () => {
+      const snapshot = await load();
+      if (disposed || !snapshot) return;
+      // Status may be satisfied from the release cache. Refresh it on entry
+      // only when the cached result is absent or older than one minute; this
+      // keeps the page current without turning navigation into a burst of
+      // rate-limited checks.
+      const checkedAt = snapshot.checkedAt || 0;
+      if (!checkedAt || !snapshot.latest || Date.now() - checkedAt > 60_000) await check();
+    };
+    void bootstrap();
+    return () => {
+      disposed = true;
+    };
+  }, []);
+
   // Cancel queued job handler
   const cancelJob = async () => {
-    if (cancelling) return;
+    if (cancelInFlight.current || !job?.id) return;
+    cancelInFlight.current = true;
     setCancelling(true);
     try {
       await api("/api/update/cancel", { method: "POST", body: JSON.stringify({ jobId: job?.id }) });
@@ -441,12 +507,14 @@ export default function UpdatePage({
       notify?.((e as Error).message, "error");
     } finally {
       setCancelling(false);
+      cancelInFlight.current = false;
     }
   };
 
   // Start download action
   const startDownload = async () => {
-    if (!latest) return;
+    if (!latest || actionInFlight.current || hasActiveJob || canApply) return;
+    actionInFlight.current = true;
     setActionBusy(true);
     setError("");
     setModalError("");
@@ -465,12 +533,14 @@ export default function UpdatePage({
       notify?.(msg, "error");
     } finally {
       setActionBusy(false);
+      actionInFlight.current = false;
     }
   };
 
   // Start apply action
   const startApply = async () => {
-    if (!latest) return;
+    if (!latest || !job || job.status !== "staged" || job.operation !== "download" || actionInFlight.current) return;
+    actionInFlight.current = true;
     setActionBusy(true);
     setError("");
     setModalError("");
@@ -488,14 +558,26 @@ export default function UpdatePage({
       notify?.(msg, "error");
     } finally {
       setActionBusy(false);
+      actionInFlight.current = false;
     }
   };
 
   const latest = info?.latest;
   const notes = notesFor(latest);
+  const hasChecked = Boolean(info?.checkedAt);
+  const releaseState = checking
+    ? "checking"
+    : !hasChecked
+      ? "unverified"
+      : !latest
+        ? "unavailable"
+        : latest.isNewer
+          ? latest.compatible && latest.integrityReady ? "available" : "blocked"
+          : "up-to-date";
 
   const canDownload = Boolean(
     info?.strategy === "systemd" &&
+      !checking &&
       latest?.isNewer &&
       latest.compatible &&
       latest.integrityReady &&
@@ -504,14 +586,19 @@ export default function UpdatePage({
 
   const canApply = Boolean(
     info?.strategy === "systemd" &&
+      !checking &&
       job &&
       job.status === "staged" &&
-      job.operation === "download"
+      job.operation === "download" &&
+      latest?.isNewer &&
+      latest.version === job.version &&
+      job.version !== info.currentVersion
   );
 
   const hasActiveJob = Boolean(
-    job && activeStatuses.has(job.status) && job.status !== "staged"
+    job && activeStatuses.has(job.status) && !(job.status === "staged" && job.operation === "download")
   );
+  const showJobDetails = hasActiveJob || canApply || Boolean(job?.status === "staged" && job.operation === "apply");
 
   // Compute current pipeline step index (0: check, 1: download, 2: verify/stage, 3: apply/restart)
   const currentStep = useMemo(() => {
@@ -537,7 +624,7 @@ export default function UpdatePage({
     if (!job) return 0;
     if (job.status === "completed" || job.status === "staged") return 100;
     if (job.status === "downloading") {
-      if (!job.sizeBytes || !job.downloadedBytes) return 10;
+      if (!job.sizeBytes || !job.downloadedBytes) return 0;
       return Math.min(99, Math.max(1, Math.round((job.downloadedBytes / job.sizeBytes) * 100)));
     }
     if (job.status === "verifying") return 99;
@@ -568,7 +655,7 @@ export default function UpdatePage({
       subtitle="管理系统版本升级、更新包完整性校验与安全热重启"
       actions={
         <div className="tn-update-page-actions">
-          {hasActiveJob && (
+          {showJobDetails && (
             <Button
               theme="primary"
               variant="base"
@@ -639,10 +726,18 @@ export default function UpdatePage({
               <span className="tn-metric-label">当前运行版本</span>
               <div className="tn-metric-value">v{info.currentVersion}</div>
               <div className="tn-metric-foot">
-                {latest?.isNewer ? (
-                  <Tag theme="primary" size="small">可更新至 v{latest.version}</Tag>
-                ) : (
+                {releaseState === "checking" ? (
+                  <Tag theme="default" size="small">正在检查更新</Tag>
+                ) : releaseState === "unverified" ? (
+                  <Tag theme="default" size="small">尚未检查更新</Tag>
+                ) : releaseState === "available" ? (
+                  <Tag theme="primary" size="small">可更新至 v{latest?.version}</Tag>
+                ) : releaseState === "up-to-date" ? (
                   <Tag theme="success" size="small">已是最新版本</Tag>
+                ) : releaseState === "blocked" ? (
+                  <Tag theme="warning" size="small">发现新版本，但暂不可更新</Tag>
+                ) : (
+                  <Tag theme="default" size="small">暂未获取发布信息</Tag>
                 )}
               </div>
             </Surface>
@@ -681,8 +776,8 @@ export default function UpdatePage({
           <Surface className="tn-ascii-release-container">
             <div className="tn-ascii-release-head">
               <h3 className="tn-ascii-release-title">发布版本详情</h3>
-              <Tag theme={latest.isNewer ? "primary" : "success"} variant="light-outline">
-                {latest.isNewer ? "发现新版本" : "已是最新版本"}
+              <Tag theme={releaseState === "available" ? "primary" : releaseState === "up-to-date" ? "success" : releaseState === "blocked" ? "warning" : "default"} variant="light-outline">
+                {releaseState === "available" ? "发现新版本" : releaseState === "up-to-date" ? "已是最新版本" : releaseState === "blocked" ? "暂不可安全更新" : "尚未检查"}
               </Tag>
             </div>
 
@@ -718,7 +813,7 @@ export default function UpdatePage({
               </div>
               <div className="tn-ascii-info-item">
                 <span className="tn-ascii-info-label">下载策略:</span>
-                <span className="tn-ascii-info-val">应用内流式直连 (零调度等待)</span>
+                <span className="tn-ascii-info-val">系统更新服务接管</span>
               </div>
             </div>
 
@@ -734,7 +829,7 @@ export default function UpdatePage({
                   disabled={actionBusy}
                   icon={<Download size={16} />}
                 >
-                  立即升级至 v{latest.version}
+                  下载更新包
                 </Button>
               )}
               {canApply && (
@@ -745,7 +840,7 @@ export default function UpdatePage({
                   disabled={actionBusy}
                   icon={<Zap size={16} />}
                 >
-                  更新包已就绪，立即应用 (v{latest.version})
+                  立即应用并重启 v{latest.version}
                 </Button>
               )}
               {hasActiveJob && (
@@ -758,9 +853,14 @@ export default function UpdatePage({
                   查看当前升级进度
                 </Button>
               )}
-              {!latest.isNewer && !hasActiveJob && (
+              {releaseState === "blocked" && !hasActiveJob && !canApply && (
+                <Button theme="default" variant="outline" size="large" onClick={() => void check()} loading={checking} disabled={checking} icon={<RefreshCw size={15} />}>
+                  重新检查
+                </Button>
+              )}
+              {releaseState === "up-to-date" && !hasActiveJob && !canApply && (
                 <Button theme="default" variant="outline" size="large" onClick={() => void check()} icon={<RefreshCw size={15} />}>
-                  检查新版本
+                  重新检查
                 </Button>
               )}
             </div>
@@ -768,10 +868,10 @@ export default function UpdatePage({
         ) : (
           <Surface className="tn-empty-surface">
             <div className="tn-empty-content">
-              <CheckCircle2 size={32} className="text-success" />
-              <p>暂无待更新的版本信息，当前系统已是最新状态。</p>
-              <Button variant="outline" onClick={() => void check()} icon={<RefreshCw size={15} />}>
-                检查新版本
+              {releaseState === "unverified" || releaseState === "checking" ? <RefreshCw size={32} className={releaseState === "checking" ? "tn-spin" : "text-secondary"} /> : <AlertCircle size={32} className="text-warning" />}
+              <p>{releaseState === "unverified" || releaseState === "checking" ? "尚未完成版本检查，请先获取官方发布信息。" : "暂时没有可用的发布信息，请稍后重新检查。"}</p>
+              <Button variant="outline" onClick={() => void check()} loading={checking} disabled={checking} icon={<RefreshCw size={15} />}>
+                {releaseState === "checking" ? "正在检查" : "检查新版本"}
               </Button>
             </div>
           </Surface>
@@ -780,7 +880,7 @@ export default function UpdatePage({
         {latest && notes && (
             <Surface className="tn-ascii-notes-container">
               <div className="tn-ascii-notes-head">
-                <h3 className="tn-ascii-notes-title">本次版本更新说明</h3>
+              <h3 className="tn-ascii-notes-title">发布说明</h3>
               </div>
               <div className="tn-ascii-notes-body">
                 <MarkdownNotes value={notes} />
@@ -805,7 +905,7 @@ export default function UpdatePage({
       {/* Unified Single Upgrade Modal (800px width on desktop) */}
       <Dialog
         visible={showUpgradeModal}
-        header={`系统升级控制台 · v${latest?.version || ""}`}
+        header={`系统升级控制台 · v${latest?.version || job?.version || ""}`}
         className="tn-dialog-large"
         width="820px"
         footer={null}
@@ -937,7 +1037,7 @@ export default function UpdatePage({
           )}
 
           {/* 场景 C: 校验通过准备就绪 (staged) (Exact ASCII) */}
-          {job?.status === "staged" && (
+          {job?.status === "staged" && job.operation === "download" && canApply && (
             <div className="tn-modal-card-box">
               <div className="tn-modal-card-title" style={{ color: "#2f7d5c", display: "flex", alignItems: "center", gap: 8 }}>
                 <CheckCircle2 size={18} />
@@ -949,14 +1049,21 @@ export default function UpdatePage({
                 <div>• 升级过程具备原子切换与自愈保护，若健康检查异常将自动回退至当前版本。</div>
               </div>
               <div className="tn-modal-actions-bar">
-                <Button variant="outline" onClick={() => setShowUpgradeModal(false)}>
-                  稍后手动应用
+                {/* A staged download has no runner attached yet, so the
+                    administrator can still discard it and free the slot. */}
+                <Button
+                  variant="outline"
+                  onClick={() => void cancelJob()}
+                  loading={cancelling}
+                  disabled={cancelling || actionBusy}
+                >
+                  取消并清理
                 </Button>
                 <Button
                   theme="primary"
                   onClick={() => void startApply()}
                   loading={actionBusy}
-                  disabled={actionBusy}
+                  disabled={actionBusy || cancelling}
                   icon={<Zap size={16} />}
                 >
                   立即应用并重启
@@ -965,6 +1072,36 @@ export default function UpdatePage({
             </div>
           )}
 
+          {/* A staged archive can become obsolete when the host or release
+              metadata changes while this page is open. Keep the state visible
+              but remove the apply action; the server will reconcile it on the
+              next status request and the operator can perform a fresh check. */}
+          {job?.status === "staged" && job.operation === "download" && !canApply && (
+            <div className="tn-modal-card-box">
+              <div className="tn-modal-card-title">暂存更新已失效</div>
+              <p className="text-secondary" style={{ fontSize: "13px", margin: "0 0 16px", lineHeight: 1.6 }}>
+                这个更新包已不是当前可安全应用的版本，系统不会重复应用。请重新检查更新以获取最新发布信息。
+              </p>
+              <div className="tn-modal-actions-bar">
+                <Button variant="outline" onClick={() => void check()} loading={checking} disabled={checking}>
+                  重新检查
+                </Button>
+              </div>
+            </div>
+          )}
+
+          {job?.status === "staged" && job.operation === "apply" && (
+            <div className="tn-modal-card-box">
+              <div className="tn-modal-card-title">
+                <div style={{ marginBottom: 12 }}><BeamBar width={180} /></div>
+                应用请求已提交，正在等待更新服务接管
+              </div>
+              <p className="text-secondary" style={{ fontSize: "13px", margin: "0 0 16px", lineHeight: 1.6 }}>
+                系统正在准备备份与重启。页面会持续同步服务状态，请不要重复提交。
+              </p>
+            </div>
+          )}
+
           {/* 场景 D: 数据快照备份中或服务重启中 (backing_up / applying) (Exact ASCII) */}
           {(job?.status === "backing_up" || job?.status === "applying") && (
             <div className="tn-modal-card-box">
@@ -991,7 +1128,7 @@ export default function UpdatePage({
             <div className="tn-modal-card-box" style={{ background: "rgba(47, 125, 92, 0.04)", border: "1px solid rgba(47, 125, 92, 0.25)" }}>
               <div className="tn-modal-card-title" style={{ color: "#2f7d5c", display: "flex", alignItems: "center", gap: 8 }}>
                 <CheckCircle2 size={22} />
-                恭喜！系统已成功平滑升级至 v{latest?.version || info.currentVersion}。
+                恭喜！系统已成功平滑升级至 v{latest?.version || info?.currentVersion || "当前版本"}。
               </div>
               <p style={{ fontSize: "13.5px", color: "var(--tn-text)", margin: "8px 0 16px" }}>
                 服务健康检查已全部通过，所有账目数据与发票凭证均完好无损。请点击下方按钮完成控制台刷新。
@@ -1026,7 +1163,7 @@ export default function UpdatePage({
           )}
 
           {/* Footer close button */}
-          {job?.status !== "staged" && job?.status !== "completed" && !confirmReadyToDownload && (
+          {!(job?.status === "staged" && canApply) && job?.status !== "completed" && !confirmReadyToDownload && (
             <div className="tn-modal-footer-close">
               <Button variant="outline" onClick={() => setShowUpgradeModal(false)}>
                 关闭窗口（后台继续运行）
@@ -1035,27 +1172,6 @@ export default function UpdatePage({
           )}
         </div>      </Dialog>
 
-      {/* Floating Mock Dock (Bottom-right, zero interference with main page) */}
-      {MOCK_PREVIEW_ENABLED && (
-        <aside className="tn-dev-mock-dock" aria-label="开发预览控制台">
-          <Terminal size={14} />
-          <strong>Mock:</strong>
-          <RadioGroup
-            variant="default-filled"
-            size="small"
-            value={mockScenario}
-            onChange={(value) => handleScenarioChange(value as "live" | MockScenario)}
-          >
-            <Radio.Button value="live">真实</Radio.Button>
-            {mockCatalog &&
-              Object.entries(mockCatalog).map(([key, item]) => (
-                <Radio.Button key={key} value={key}>
-                  {item.title.split("（")[0]}
-                </Radio.Button>
-              ))}
-          </RadioGroup>
-        </aside>
-      )}
     </Page>
   );
 }

web-next/src/pages/update/mockData.ts

@@ -1,283 +0,0 @@
-export type MockScenario =
-  | "latest"          // 已是最新
-  | "available"       // 发现新版本（待下载）
-  | "downloading_30"  // 下载中 30%
-  | "downloading_85"  // 下载中 85% + 高速
-  | "staged"          // 下载完成已校验，待立即更新
-  | "backing_up"      // 正在备份数据
-  | "applying"        // 正在原子切换并重启中（倒计时）
-  | "completed"       // 更新完成
-  | "failed_verify"   // 完整性校验失败
-  | "disabled";       // 手动模式未配置源
-
-export interface MockUpdateState {
-  info: any;
-  title: string;
-  description: string;
-}
-
-export const MOCK_SCENARIOS: Record<MockScenario, MockUpdateState> = {
-  latest: {
-    title: "版本健康（已是最新）",
-    description: "展示当前运行版本已是最新，各项指标正常，无待处理任务",
-    info: {
-      configured: true,
-      strategy: "systemd",
-      currentVersion: "1.1.22",
-      platform: { target: "x64/glibc", os: "linux", arch: "x64" },
-      checkedAt: Date.now() - 600_000,
-      latest: {
-        version: "1.1.22",
-        tagName: "v1.1.22",
-        releaseName: "v1.1.22 稳定版",
-        publishedAt: new Date(Date.now() - 3600_000 * 24).toISOString(),
-        compatible: true,
-        integrityReady: true,
-        signatureReady: true,
-        isNewer: false,
-        assetName: "tallynote-1.1.22-linux-x64-glibc.tar.gz",
-        assetSize: 120540160,
-        notes: "### TallyNote 1.1.22\n\n- 优化反向代理下登录兼容性\n- 增强安全审计与防重放机制\n- 前端组件性能深度优化",
-      },
-      job: null,
-    },
-  },
-  available: {
-    title: "发现新版本（待下载）",
-    description: "检查到官方发布了更高版本，显示更新日志与文件校验信息，可点击下载",
-    info: {
-      configured: true,
-      strategy: "systemd",
-      currentVersion: "1.1.22",
-      platform: { target: "x64/glibc", os: "linux", arch: "x64" },
-      checkedAt: Date.now() - 60_000,
-      latest: {
-        version: "1.1.23",
-        tagName: "v1.1.23",
-        releaseName: "v1.1.23 重大更新",
-        publishedAt: new Date(Date.now() - 1800_000).toISOString(),
-        compatible: true,
-        integrityReady: true,
-        signatureReady: true,
-        isNewer: true,
-        assetName: "tallynote-1.1.23-linux-x64-glibc.tar.gz",
-        assetSize: 121000000,
-        notes: "### TallyNote 1.1.23\n\n- 【新功能】系统更新中心全面重构，支持动态速率流光进度条与平滑重启倒计时\n- 【交互】优化抽屉展开动效与手机端自适应导航\n- 【安全】发布包支持双重 Ed25519 签名与 SHA-256 清单交叉校验",
-      },
-      job: null,
-    },
-  },
-  downloading_30: {
-    title: "下载更新中（进度 38%）",
-    description: "展示真实下载速率、已下载字节数与动态流光进度条",
-    info: {
-      configured: true,
-      strategy: "systemd",
-      currentVersion: "1.1.22",
-      platform: { target: "x64/glibc", os: "linux", arch: "x64" },
-      checkedAt: Date.now() - 120_000,
-      latest: {
-        version: "1.1.23",
-        tagName: "v1.1.23",
-        compatible: true,
-        integrityReady: true,
-        signatureReady: true,
-        isNewer: true,
-        assetName: "tallynote-1.1.23-linux-x64-glibc.tar.gz",
-        assetSize: 121000000,
-      },
-      job: {
-        id: "mock-job-001",
-        operation: "download",
-        status: "downloading",
-        version: "1.1.23",
-        platform: "x64/glibc",
-        assetName: "tallynote-1.1.23-linux-x64-glibc.tar.gz",
-        sizeBytes: 121000000,
-        downloadedBytes: 46200000,
-        downloadStartedAt: Date.now() - 10000,
-        downloadSpeedBps: 8800000, // 8.4 MB/s
-        createdAt: Date.now() - 10000,
-        updatedAt: Date.now(),
-      },
-    },
-  },
-  downloading_85: {
-    title: "下载冲刺中（进度 88%）",
-    description: "高速冲刺状态，即将触发 SHA-256 校验",
-    info: {
-      configured: true,
-      strategy: "systemd",
-      currentVersion: "1.1.22",
-      platform: { target: "x64/glibc", os: "linux", arch: "x64" },
-      checkedAt: Date.now() - 120_000,
-      latest: {
-        version: "1.1.23",
-        tagName: "v1.1.23",
-        compatible: true,
-        integrityReady: true,
-        signatureReady: true,
-        isNewer: true,
-        assetName: "tallynote-1.1.23-linux-x64-glibc.tar.gz",
-        assetSize: 121000000,
-      },
-      job: {
-        id: "mock-job-002",
-        operation: "download",
-        status: "downloading",
-        version: "1.1.23",
-        platform: "x64/glibc",
-        assetName: "tallynote-1.1.23-linux-x64-glibc.tar.gz",
-        sizeBytes: 121000000,
-        downloadedBytes: 106480000,
-        downloadStartedAt: Date.now() - 15000,
-        downloadSpeedBps: 12500000, // 11.9 MB/s
-        createdAt: Date.now() - 15000,
-        updatedAt: Date.now(),
-      },
-    },
-  },
-  staged: {
-    title: "下载完成（待立即应用）",
-    description: "更新包与签名均已校验就绪，随时可以安全点击【立即更新】",
-    info: {
-      configured: true,
-      strategy: "systemd",
-      currentVersion: "1.1.22",
-      platform: { target: "x64/glibc", os: "linux", arch: "x64" },
-      checkedAt: Date.now() - 120_000,
-      latest: {
-        version: "1.1.23",
-        tagName: "v1.1.23",
-        compatible: true,
-        integrityReady: true,
-        signatureReady: true,
-        isNewer: true,
-        assetName: "tallynote-1.1.23-linux-x64-glibc.tar.gz",
-        assetSize: 121000000,
-        notes: "### TallyNote 1.1.23\n\n- 更新包已完整解压检验通过，具备升级条件。",
-      },
-      job: {
-        id: "mock-job-003",
-        operation: "download",
-        status: "staged",
-        version: "1.1.23",
-        platform: "x64/glibc",
-        assetName: "tallynote-1.1.23-linux-x64-glibc.tar.gz",
-        sizeBytes: 121000000,
-        downloadedBytes: 121000000,
-        createdAt: Date.now() - 60000,
-        updatedAt: Date.now() - 5000,
-      },
-    },
-  },
-  backing_up: {
-    title: "数据备份中（更新保护）",
-    description: "正在为系统数据生成安全快照备份",
-    info: {
-      configured: true,
-      strategy: "systemd",
-      currentVersion: "1.1.22",
-      platform: { target: "x64/glibc", os: "linux", arch: "x64" },
-      checkedAt: Date.now() - 120_000,
-      latest: { version: "1.1.23", tagName: "v1.1.23", compatible: true, integrityReady: true, signatureReady: true, isNewer: true },
-      job: {
-        id: "mock-job-004",
-        operation: "apply",
-        status: "backing_up",
-        version: "1.1.23",
-        platform: "x64/glibc",
-        createdAt: Date.now() - 20000,
-        updatedAt: Date.now() - 2000,
-      },
-    },
-  },
-  applying: {
-    title: "服务平滑重启中（倒计时中）",
-    description: "已安全切换版本，服务正在热重启并检验状态",
-    info: {
-      configured: true,
-      strategy: "systemd",
-      currentVersion: "1.1.22",
-      platform: { target: "x64/glibc", os: "linux", arch: "x64" },
-      checkedAt: Date.now() - 120_000,
-      latest: { version: "1.1.23", tagName: "v1.1.23", compatible: true, integrityReady: true, signatureReady: true, isNewer: true },
-      job: {
-        id: "mock-job-005",
-        operation: "apply",
-        status: "applying",
-        version: "1.1.23",
-        platform: "x64/glibc",
-        applyQueuedAt: Date.now() - 12000,
-        restartWindowSeconds: 30,
-        restartDeadline: Date.now() + 18000,
-        createdAt: Date.now() - 25000,
-        updatedAt: Date.now() - 2000,
-      },
-    },
-  },
-  completed: {
-    title: "更新成功完成",
-    description: "新版本健康检查通过，已平滑无感升级至最新",
-    info: {
-      configured: true,
-      strategy: "systemd",
-      currentVersion: "1.1.23",
-      platform: { target: "x64/glibc", os: "linux", arch: "x64" },
-      checkedAt: Date.now() - 30_000,
-      latest: { version: "1.1.23", tagName: "v1.1.23", compatible: true, integrityReady: true, signatureReady: true, isNewer: false },
-      job: {
-        id: "mock-job-006",
-        operation: "apply",
-        status: "completed",
-        version: "1.1.23",
-        platform: "x64/glibc",
-        completedAt: Date.now() - 10000,
-        createdAt: Date.now() - 45000,
-        updatedAt: Date.now() - 10000,
-      },
-    },
-  },
-  failed_verify: {
-    title: "更新失败状态（安全拦截）",
-    description: "模拟签名不匹配或发布包篡改时的安全拦截展示与错误提示",
-    info: {
-      configured: true,
-      strategy: "systemd",
-      currentVersion: "1.1.22",
-      platform: { target: "x64/glibc", os: "linux", arch: "x64" },
-      checkedAt: Date.now() - 120_000,
-      latest: {
-        version: "1.1.23",
-        tagName: "v1.1.23",
-        compatible: true,
-        integrityReady: false,
-        signatureReady: false,
-        isNewer: true,
-      },
-      job: {
-        id: "mock-job-007",
-        operation: "download",
-        status: "failed",
-        version: "1.1.23",
-        platform: "x64/glibc",
-        errorMessage: "发布包 SHA-256 校验与清单不一致，系统已自动阻断并保护原有数据。",
-        createdAt: Date.now() - 30000,
-        updatedAt: Date.now() - 5000,
-      },
-    },
-  },
-  disabled: {
-    title: "手动源码模式",
-    description: "未启用后台守护时的更新提示与引导说明",
-    info: {
-      configured: false,
-      strategy: "disabled",
-      currentVersion: "1.1.22",
-      platform: { target: "macOS/darwin", os: "darwin", arch: "arm64" },
-      checkedAt: Date.now() - 3600_000,
-      latest: null,
-      job: null,
-    },
-  },
-};

web-next/src/styles/theme.css

@@ -115,14 +115,14 @@ input:focus-visible, textarea:focus-visible, select:focus-visible {
   box-sizing: border-box !important;
   transition: all 0.22s cubic-bezier(0.16, 1, 0.3, 1) !important;
 }
-.t-notification__show--top-right {
-  top: 76px !important;
+.t-notification__show--bottom-right {
+  bottom: 24px !important;
   right: 24px !important;
   z-index: 6000 !important;
 }
 @media (max-width: 768px) {
-  .t-notification__show--top-right {
-    top: 16px !important;
+  .t-notification__show--bottom-right {
+    bottom: 16px !important;
     right: 16px !important;
     left: 16px !important;
     width: auto !important;
@@ -802,61 +802,6 @@ input:focus-visible, textarea:focus-visible, select:focus-visible {
    TallyNote Update Center (Redesigned UI & Interactive Styles)
    ========================================================================== */
 
-/* Mock Console Controller */
-.tn-mock-console {
-  margin-bottom: 16px;
-  padding: 14px 18px;
-  background: #f8fbff;
-  border: 1px dashed var(--td-brand-color-3);
-  border-radius: 4px;
-}
-.tn-mock-console-header {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  flex-wrap: wrap;
-  gap: 8px;
-  margin-bottom: 12px;
-}
-.tn-mock-console-title {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  font-size: 13px;
-  color: var(--tn-navy-900);
-}
-.tn-mock-console-tip {
-  font-size: 12px;
-  color: var(--tn-text-secondary);
-}
-.tn-mock-scenario-chips {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-}
-.tn-scenario-chip {
-  padding: 5px 11px;
-  font-size: 12px;
-  border: 1px solid var(--tn-border);
-  border-radius: 3px;
-  background: #ffffff;
-  color: var(--tn-text-secondary);
-  cursor: pointer;
-  transition: all 0.16s ease;
-}
-.tn-scenario-chip:hover {
-  border-color: var(--td-brand-color-4);
-  color: var(--td-brand-color);
-  background: var(--td-brand-color-1);
-}
-.tn-scenario-chip.active {
-  background: var(--td-brand-color);
-  border-color: var(--td-brand-color);
-  color: #ffffff;
-  font-weight: 600;
-  box-shadow: 0 2px 6px rgba(23, 92, 211, 0.2);
-}
-
 /* Update Page Actions */
 .tn-update-page-actions {
   display: flex;
@@ -1272,10 +1217,6 @@ input:focus-visible, textarea:focus-visible, select:focus-visible {
   .tn-update-metrics-grid {
     grid-template-columns: 1fr;
   }
-  .tn-mock-console-header {
-    flex-direction: column;
-    align-items: flex-start;
-  }
   .tn-release-header {
     flex-direction: column;
   }
@@ -1651,23 +1592,6 @@ input:focus-visible, textarea:focus-visible, select:focus-visible {
   gap: 6px;
 }
 
-/* Compact Floating Mock Switcher at bottom-right instead of giant top banner */
-.tn-dev-mock-dock {
-  position: fixed;
-  bottom: 16px;
-  right: 16px;
-  z-index: 999;
-  background: #ffffff;
-  border: 1px solid var(--td-brand-color);
-  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.15);
-  border-radius: 4px;
-  padding: 8px 12px;
-  display: flex;
-  align-items: center;
-  gap: 10px;
-  font-size: 12px;
-}
-
 
 /* ============================================================
    方案二：平滑极光光流条 (Beam Bar / Shimmer) 全局动效规范

web/src/main.tsx

@@ -30,6 +30,8 @@ import {
   Upload,
   Users,
   X,
+  Ban,
+  Rocket,
 } from "lucide-react";
 import "./styles.css";
 
@@ -84,6 +86,8 @@ type UpdateJob = {
   platform: string;
   assetName?: string | null;
   sizeBytes?: number | null;
+  downloadedBytes?: number | null;
+  downloadSpeedBps?: number | null;
   errorMessage?: string | null;
   createdAt: number;
   updatedAt: number;
@@ -683,7 +687,7 @@ function Admins({ notify, currentAdmin }: { notify: (message: string, kind?: Not
 }
 
 const updateStatusLabels: Record<UpdateJob["status"], string> = {
-  queued: "等待系统服务",
+  queued: "准备下载",
   downloading: "下载中",
   verifying: "校验文件",
   staged: "准备完成",
@@ -699,6 +703,8 @@ function Update({ notify }: { notify: (message: string, kind?: Notice["kind"]) =
   const [loading, setLoading] = useState(true);
   const [checking, setChecking] = useState(false);
   const [applying, setApplying] = useState(false);
+  const [downloading, setDownloading] = useState(false);
+  const [cancelling, setCancelling] = useState(false);
   const [error, setError] = useState("");
   const [confirmVersion, setConfirmVersion] = useState<string | null>(null);
   const [reloadReady, setReloadReady] = useState(false);
@@ -752,6 +758,30 @@ function Update({ notify }: { notify: (message: string, kind?: Notice["kind"]) =
     } finally { setChecking(false); }
   };
 
+  const download = async () => {
+    if (!latest) return;
+    setDownloading(true); setError("");
+    try {
+      const result = await api<{ job: UpdateJob }>("/api/update/download", { method: "POST", body: JSON.stringify({ version: latest.version, confirm: true }) });
+      setInfo((current) => current ? { ...current, job: result.job } : current);
+      notify("开始下载更新包", "info");
+    } catch (caught) {
+      setError((caught as Error).message);
+    } finally { setDownloading(false); }
+  };
+
+  const cancel = async () => {
+    if (!job) return;
+    setCancelling(true); setError("");
+    try {
+      await api("/api/update/cancel", { method: "POST", body: JSON.stringify({ jobId: job.id }) });
+      notify("已取消下载", "info");
+      await load();
+    } catch (caught) {
+      setError((caught as Error).message);
+    } finally { setCancelling(false); }
+  };
+
   const apply = async () => {
     if (!confirmVersion) return;
     setApplying(true); setError("");
@@ -768,7 +798,12 @@ function Update({ notify }: { notify: (message: string, kind?: Notice["kind"]) =
   const latest = info?.latest;
   const job = info?.job;
   const hasActiveJob = Boolean(job && ["queued", "downloading", "verifying", "staged", "backing_up", "applying"].includes(job.status));
-  const canApply = Boolean(info?.strategy === "systemd" && latest?.isNewer && latest.compatible && latest.integrityReady && !hasActiveJob && (!job || job.status === "failed" || job.version !== latest.version));
+  const canDownload = Boolean(info?.strategy === "systemd" && latest?.isNewer && latest.compatible && latest.integrityReady && !hasActiveJob && (!job || job.status === "failed" || job.status === "cancelled" || job.version !== latest.version));
+  const canApply = Boolean(job?.status === "staged");
+  const downloadPercent = job?.status === "downloading" && job.sizeBytes ? Math.min(100, Math.round((job.downloadedBytes ?? 0) / job.sizeBytes * 100)) : 0;
+  const speedText = job?.downloadSpeedBps ? `${(job.downloadSpeedBps / 1024 / 1024).toFixed(1)} MB/s` : "";
+  const downloadedText = job?.downloadedBytes ? formatBytes(job.downloadedBytes) : "";
+  const totalText = job?.sizeBytes ? formatBytes(job.sizeBytes) : "";
 
   return <div className="page update-page">
     <div className="page-head"><div><div className="eyebrow">系统</div><h1>系统更新</h1></div><div className="head-actions"><Button onClick={() => void load()} disabled={loading || checking}><RotateCcw size={15} />刷新</Button><Button kind="primary" onClick={() => void check()} disabled={loading || checking}><RefreshCw size={15} className={checking ? "spin" : undefined} />检查更新</Button></div></div>
@@ -778,15 +813,13 @@ function Update({ notify }: { notify: (message: string, kind?: Notice["kind"]) =
         <section className="update-card"><div className="update-card-icon"><Server size={20} /></div><div><span className="update-label">当前版本</span><strong className="update-version">v{info.currentVersion}</strong><span className="field-hint">运行平台：{info.platform.target}</span></div></section>
         <section className="update-card"><div className="update-card-icon"><ShieldCheck size={20} /></div><div><span className="update-label">更新方式</span><strong>{info.strategy === "systemd" ? "systemd 一键更新" : "命令行更新"}</strong><span className="field-hint">{info.strategy === "systemd" ? "数据目录不会被替换" : "当前安装未启用后台更新"}</span></div></section>
       </div>
-      {latest ? <section className="update-release"><div className="update-release-head"><div><span className="update-label">最新 Release</span><h2>{latest.tagName || `v${latest.version}`}</h2>{latest.publishedAt && <span className="field-hint">发布时间：{dateText(Date.parse(latest.publishedAt))}</span>}</div><span className={`update-badge ${latest.isNewer ? "update-badge-new" : "update-badge-current"}`}>{latest.isNewer ? "有新版本" : "已是最新"}</span></div><div className="update-facts"><div><span>平台文件</span><strong>{latest.compatible ? latest.assetName : "无匹配文件"}</strong></div><div><span>完整性</span><strong className={latest.integrityReady ? "text-success" : "text-danger"}>{latest.integrityReady ? "SHA-256 + 签名可验证" : latest.signatureReady ? "缺少 SHA-256" : "缺少发布签名"}</strong></div>{latest.assetSize !== undefined && <div><span>文件大小</span><strong>{formatBytes(latest.assetSize)}</strong></div>}</div>{latest.isNewer && !latest.compatible && <div className="info"><AlertCircle size={16} />当前平台没有可安装的 release 文件。</div>}{latest.isNewer && latest.compatible && !latest.integrityReady && <div className="error"><AlertCircle size={16} />发布文件必须同时提供 SHA-256 和受信任的 Ed25519 签名，当前已禁用更新。</div>}<div className="update-actions">{canApply && <Button kind="primary" onClick={() => setConfirmVersion(latest.version)} disabled={hasActiveJob}><DownloadIcon /><span>更新到 v{latest.version}</span></Button>}{reloadReady && <Button kind="primary" onClick={() => window.location.reload()}>重新加载</Button>}</div></section> : <div className="update-empty"><RefreshCw size={24} /><p>点击“检查更新”获取最新 Release。</p></div>}
-      {job && <section className="update-job"><div className="update-job-head"><div><span className="update-label">最近任务</span><strong>v{job.version}</strong></div><span className={`update-job-status update-job-${job.status}`}>{updateStatusLabels[job.status]}</span></div>{hasActiveJob && <div className="update-progress" aria-label={updateStatusLabels[job.status]}><span style={{ width: `${job.status === "queued" ? 8 : job.status === "downloading" ? 28 : job.status === "verifying" ? 48 : job.status === "staged" ? 65 : job.status === "backing_up" ? 80 : 92}%` }} /></div>}{job.status === "queued" && <p className="field-hint">等待 root 权限的 systemd 更新服务接管，页面会自动刷新状态。</p>}{job.status === "failed" && job.errorMessage && <div className="error"><AlertCircle size={16} />{job.errorMessage}</div>}{job.status === "completed" && <div className="info"><CheckCircle2 size={16} />新版本已通过健康检查，数据和附件保持不变。</div>}</section>}
+      {latest ? <section className="update-release"><div className="update-release-head"><div><span className="update-label">最新发布</span><h2>{latest.tagName || `v${latest.version}`}</h2>{latest.publishedAt && <span className="field-hint">发布时间：{dateText(Date.parse(latest.publishedAt))}</span>}</div><span className={`update-badge ${latest.isNewer ? "update-badge-new" : "update-badge-current"}`}>{latest.isNewer ? "有新版本" : "已是最新"}</span></div><div className="update-facts"><div><span>平台文件</span><strong>{latest.compatible ? latest.assetName : "无匹配文件"}</strong></div><div><span>完整性</span><strong className={latest.integrityReady ? "text-success" : "text-danger"}>{latest.integrityReady ? "SHA-256 + 签名可验证" : latest.signatureReady ? "缺少 SHA-256" : "缺少发布签名"}</strong></div>{latest.assetSize !== undefined && <div><span>文件大小</span><strong>{formatBytes(latest.assetSize)}</strong></div>}</div>{latest.isNewer && !latest.compatible && <div className="info"><AlertCircle size={16} />当前平台没有可安装的 release 文件。</div>}{latest.isNewer && latest.compatible && !latest.integrityReady && <div className="error"><AlertCircle size={16} />发布文件必须同时提供 SHA-256 和受信任的 Ed25519 签名，当前已禁用更新。</div>}<div className="update-actions">{canDownload && <Button kind="primary" onClick={() => void download()} disabled={downloading}><ArrowDownToLine size={16} /><span>下载更新包</span></Button>}{job?.status === "staged" && <Button kind="primary" onClick={() => setConfirmVersion(latest.version)} disabled={applying}><Rocket size={16} /><span>立即更新</span></Button>}{reloadReady && <Button kind="primary" onClick={() => window.location.reload()}>重新加载</Button>}</div></section> : <div className="update-empty"><RefreshCw size={24} /><p>点击"检查更新"获取最新发布。</p></div>}
+      {job && <section className="update-job"><div className="update-job-head"><div><span className="update-label">更新任务</span><strong>v{job.version}</strong></div><span className={`update-job-status update-job-${job.status}`}>{updateStatusLabels[job.status]}</span></div>{job.status === "downloading" && <div className="update-progress-detail"><div className="update-progress" aria-label="下载进度"><span style={{ width: `${downloadPercent}%` }} /></div><div className="update-progress-info"><span>{downloadedText}{totalText ? ` / ${totalText}` : ""}</span>{speedText && <span>{speedText}</span>}{downloadPercent > 0 && <span>{downloadPercent}%</span>}</div><Button onClick={() => void cancel()} disabled={cancelling}><Ban size={14} />取消下载</Button></div></div>}{(job.status === "verifying" || job.status === "staged" || job.status === "backing_up" || job.status === "applying") && <div className="update-progress" aria-label={updateStatusLabels[job.status]}><span style={{ width: `${job.status === "verifying" ? 50 : job.status === "staged" ? 65 : job.status === "backing_up" ? 80 : 95}%` }} /></div>}{job.status === "failed" && job.errorMessage && <div className="error"><AlertCircle size={16} />{job.errorMessage}</div>}{job.status === "completed" && <div className="info"><CheckCircle2 size={16} />新版本已通过健康检查，数据和附件保持不变。</div>}</section>}
     </>}
     {confirmVersion && <ConfirmDialog title="确认更新系统？" message={<>将更新到 <strong>v{confirmVersion}</strong>。服务会短暂停止并重启，更新前会备份数据目录；账目、附件、回收站和审计记录不会被删除。</>} confirmLabel="开始更新" busy={applying} onClose={() => setConfirmVersion(null)} onConfirm={() => void apply()} />}
   </div>;
 }
 
-function DownloadIcon() { return <ArrowDownToLine size={16} />; }
-
 function Audit({ notify: _notify }: { notify: (message: string, kind?: Notice["kind"]) => void }) {
   const pageSize = 100;
   const [items, setItems] = useState<any[]>([]);