fix: keep manually set admin password, echo SSH input

- manual admin password no longer forces first-login change
- --generate still requires password change on first login
- add --mark-password-configured to repair legacy flag
- echo interactive username/password input in SSH terminal
- installer prints absolute admin-init path (sudo secure_path compat)
- use python3 pty helper for CI tests (no expect on Linux)
release: 1.2.9

.env.example

@@ -3,9 +3,6 @@ TALLYNOTE_PORT=3000
 TALLYNOTE_DATA_DIR=./data
 TALLYNOTE_TIMEZONE=Asia/Shanghai
 TALLYNOTE_PUBLIC_ORIGIN=http://127.0.0.1:3000
-# Optional additional browser Origins for an explicit reverse-proxy alias.
-# Keep the primary public origin above and list only trusted HTTPS origins.
-# TALLYNOTE_ALLOWED_ORIGINS=https://tally.example.com,https://tally.internal.example
 TALLYNOTE_TRUST_PROXY=false
 TALLYNOTE_COOKIE_SECURE=false
 # Set TALLYNOTE_HOST=0.0.0.0 and the server's real IP Origin for direct
@@ -34,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

.gitea/workflows/release.yml

@@ -17,6 +17,10 @@ jobs:
     steps:
       - name: Checkout tag
         uses: actions/checkout@v4
+        with:
+          # Release notes are derived from the previous version tag. A shallow
+          # checkout would leave only the synthetic release commit available.
+          fetch-depth: 0
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
@@ -26,10 +30,15 @@ jobs:
       - name: Verify tag and test gate
         run: |
           set -euo pipefail
-          test "$(node -p 'require("./package.json").version')" = "${GITHUB_REF_NAME#v}"
+          target_version="${GITHUB_REF_NAME#v}"
+          package_version="$(node -p 'require("./package.json").version')"
+          test "$package_version" = "$target_version"
           pnpm install --frozen-lockfile
           pnpm check
-          pnpm test
+          # better-sqlite3 is a native addon; a single Vitest worker avoids a
+          # Node cleanup race observed on the hosted runner while preserving
+          # the complete test suite.
+          pnpm test -- --pool=threads --poolOptions.threads.singleThread=true
           pnpm test:installer
       - name: Build Linux release
         run: pnpm release:build "${GITHUB_REF_NAME#v}" ./release

README.md

@@ -42,7 +42,7 @@ 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`。
 
@@ -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 状态和最近日志并回滚本次切换。
 
@@ -140,7 +146,7 @@ curl --proto '=https' --tlsv1.2 -fsSL https://git.awaioi.com/awaioi/TallyNote/ra
 
 卸载器会逐项输出停止、禁用和删除进度；每次 systemd/dbus 调用默认最多等待 30 秒，避免终端无限无响应。可通过 `TALLYNOTE_UNINSTALL_SYSTEMCTL_TIMEOUT_SECONDS` 调整超时时间。
 
-公网反代必须使用 HTTPS，并在环境文件中设置真实的 `TALLYNOTE_PUBLIC_ORIGIN=https://...`、`TALLYNOTE_COOKIE_SECURE=true` 和明确的 `TALLYNOTE_TRUST_PROXY` 跳数（不要使用生产值 `true`）。登录和所有写入请求会校验浏览器 `Origin`；反代必须原样转发 `Origin`，且访问地址必须与 `TALLYNOTE_PUBLIC_ORIGIN` 完全一致。若确实需要多个受信任域名，可用 `TALLYNOTE_ALLOWED_ORIGINS=https://a.example.com,https://b.example.com` 显式列出（只写 Origin，不含路径），不要把它设为任意来源。
+公网反代推荐使用 HTTPS，并在环境文件中设置真实的 `TALLYNOTE_PUBLIC_ORIGIN=https://...`、`TALLYNOTE_COOKIE_SECURE=true` 和明确的 `TALLYNOTE_TRUST_PROXY` 跳数（不要使用生产值 `true`）。反代只需把域名转发到 TallyNote 端口并保留 `Host`、`X-Forwarded-Proto`；应用不会因为代理缺少或改写浏览器 `Origin` 而拦截登录。已认证写请求仍使用会话 Cookie 与 CSRF 令牌保护。
 
 ### 构建发布包
 

artifacts/tallynote-update-workflow.json

@@ -0,0 +1,256 @@
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "TallyNote 平滑更新与应用内直连下载流程",
+    "subtitle": "告别外部守护等待 · 应用进程直连流式下载 · 原子热切换",
+    "output": "artifacts/tallynote-update-workflow.html",
+    "animation": "trace",
+    "quality_profile": "showcase",
+    "views": [
+      {
+        "id": "stream-download",
+        "label": "应用内流式下载",
+        "focus": [
+          "ui_render",
+          "stream_worker",
+          "verify_sha"
+        ],
+        "note": "Web 进程 0 延时直连 Gitea 流式拉取并比对哈希，彻底废除外部 systemd.path 调度等待。"
+      },
+      {
+        "id": "atomic-switch",
+        "label": "原子切换与秒级恢复",
+        "focus": [
+          "ui_ready",
+          "atomic_switch",
+          "health_probe",
+          "ui_refreshed"
+        ],
+        "note": "包就绪后秒级原子切换 current 软链接，30s 倒计时探活自动无缝恢复。"
+      }
+    ]
+  },
+  "lanes": [
+    {
+      "id": "ui",
+      "label": "管理控制台 (前端 UI)"
+    },
+    {
+      "id": "app",
+      "label": "Web 应用后端 (Node.js)"
+    },
+    {
+      "id": "system",
+      "label": "系统底层与运行时 (Linux / systemd)"
+    },
+    {
+      "id": "git",
+      "label": "Gitea 官方源 (HTTPS)"
+    }
+  ],
+  "phases": [
+    {
+      "id": "phase_check",
+      "label": "版本发现",
+      "fromCol": 0,
+      "toCol": 1
+    },
+    {
+      "id": "phase_download",
+      "label": "直连下载与校验",
+      "fromCol": 2,
+      "toCol": 3,
+      "variant": "emphasis"
+    },
+    {
+      "id": "phase_apply",
+      "label": "原子切换与自愈",
+      "fromCol": 4,
+      "toCol": 5,
+      "variant": "dashed"
+    }
+  ],
+  "groups": [
+    {
+      "id": "grp_stream",
+      "label": "应用内直接流式拉取 (无外部阻塞)",
+      "lane": "app",
+      "fromCol": 2,
+      "toCol": 3,
+      "variant": "emphasis"
+    }
+  ],
+  "mainPath": [
+    "ui_check",
+    "api_check",
+    "git_source",
+    "ui_render",
+    "stream_worker",
+    "verify_sha",
+    "ui_ready",
+    "atomic_switch",
+    "health_probe",
+    "ui_refreshed"
+  ],
+  "nodes": [
+    {
+      "id": "ui_check",
+      "lane": "ui",
+      "col": 0,
+      "type": "frontend",
+      "label": "检查更新",
+      "sublabel": "点击查询新版"
+    },
+    {
+      "id": "api_check",
+      "lane": "app",
+      "col": 0,
+      "type": "backend",
+      "label": "查询 Release",
+      "sublabel": "只读接口校验",
+      "tag": "只读"
+    },
+    {
+      "id": "git_source",
+      "lane": "git",
+      "col": 1,
+      "type": "external",
+      "label": "Gitea 官方源",
+      "sublabel": "返回最新元数据",
+      "tag": "HTTPS"
+    },
+    {
+      "id": "ui_render",
+      "lane": "ui",
+      "col": 1,
+      "type": "frontend",
+      "label": "版本看板呈现",
+      "sublabel": "日志与升级入口"
+    },
+    {
+      "id": "stream_worker",
+      "lane": "app",
+      "col": 2,
+      "type": "backend",
+      "label": "流式拉取",
+      "sublabel": "应用直连下载",
+      "tag": "实时进度"
+    },
+    {
+      "id": "verify_sha",
+      "lane": "app",
+      "col": 3,
+      "type": "security",
+      "label": "SHA-256 校验",
+      "sublabel": "比对并解压",
+      "tag": "完整性"
+    },
+    {
+      "id": "ui_ready",
+      "lane": "ui",
+      "col": 3,
+      "type": "frontend",
+      "label": "确认重启",
+      "sublabel": "更新包已就绪"
+    },
+    {
+      "id": "atomic_switch",
+      "lane": "system",
+      "col": 4,
+      "type": "cloud",
+      "label": "原子切换",
+      "sublabel": "切换软链接重载"
+    },
+    {
+      "id": "health_probe",
+      "lane": "app",
+      "col": 5,
+      "type": "backend",
+      "label": "健康探测探针",
+      "sublabel": "轮询探活至 200"
+    },
+    {
+      "id": "ui_refreshed",
+      "lane": "ui",
+      "col": 5,
+      "type": "frontend",
+      "label": "平滑上线刷新",
+      "sublabel": "自动进入新版本"
+    }
+  ],
+  "edges": [
+    {
+      "id": "e1",
+      "from": "ui_check",
+      "to": "api_check"
+    },
+    {
+      "id": "e2",
+      "from": "api_check",
+      "to": "git_source"
+    },
+    {
+      "id": "e3",
+      "from": "git_source",
+      "to": "ui_render",
+      "channelX": 250
+    },
+    {
+      "id": "e4",
+      "from": "ui_render",
+      "to": "stream_worker"
+    },
+    {
+      "id": "e5",
+      "from": "stream_worker",
+      "to": "verify_sha"
+    },
+    {
+      "id": "e6",
+      "from": "verify_sha",
+      "to": "ui_ready"
+    },
+    {
+      "id": "e7",
+      "from": "ui_ready",
+      "to": "atomic_switch"
+    },
+    {
+      "id": "e8",
+      "from": "atomic_switch",
+      "to": "health_probe"
+    },
+    {
+      "id": "e9",
+      "from": "health_probe",
+      "to": "ui_refreshed"
+    }
+  ],
+  "cards": [
+    {
+      "dot": "emerald",
+      "title": "核心升级点：消除外部调度依赖",
+      "items": [
+        "传统模式：Web 写入 JSON 队列，傻等外部 root 守护进程监听唤醒，导致常态化卡死在等待系统调度",
+        "新模式：Web 后端进程直接建立 HTTPS 流式管道下载，0 秒立即响应，进度条真实可见"
+      ]
+    },
+    {
+      "dot": "cyan",
+      "title": "透明化监控与错误拦截",
+      "items": [
+        "网络层直抓：DNS 失败、超时或 404 当场捕获，前端弹窗直接展示错误详情与重试按钮",
+        "进度实时计算：每 500ms 计算下载字节与传输速率（MB/s），无感后台拉取"
+      ]
+    },
+    {
+      "dot": "violet",
+      "title": "平滑原子切换与自愈",
+      "items": [
+        "文件完整校验后再切换软链接，绝不损坏现有运行中的实例",
+        "前端 30 秒倒计时探针自动检测服务就绪，服务重启完毕自动恢复会话"
+      ]
+    }
+  ]
+}

docs/release.md

@@ -12,6 +12,8 @@ TallyNote 的发布包必须在目标 Linux 架构上构建。`better-sqlite3`
 2. 由 `scripts/publish-gitea-release.sh` 计算所有归档的 `SHA256SUMS`。
 3. 如果提供 Ed25519 私钥则生成 `SHA256SUMS.sig`，通过 Gitea Releases API 创建/复用对应 Release，并幂等上传归档、清单和可选签名。
 
+发布脚本会根据当前 tag 与上一个版本 tag 之间的真实 Git 提交自动生成 Release 正文，按“新增功能、问题修复、优化与重构、文档与测试”分类，并以 Markdown 写入 Gitea。Gitea 页面会渲染这些标题和列表；更新中心读取同一份正文后再进行安全的 Markdown 子集渲染，不会显示 Markdown 源代码。旧版本曾使用单行占位正文 `TallyNote <版本>`，新版本发布时不会再使用该占位内容。
+
 在仓库的 Actions secrets 配置：
 
 - `GITEA_TOKEN`：仅授予当前仓库 Release 写权限的 token。
@@ -28,7 +30,7 @@ GITEA_TOKEN=... \
   ./scripts/publish-gitea-release.sh v1.1.2 ./release
 ```
 
-发布资产名称必须包含当前平台，例如 `tallynote-1.1.2-linux-x64-glibc.tar.gz`。同一个 Release 只保留一个 `SHA256SUMS`；有签名时再保留一个 `SHA256SUMS.sig`，签名覆盖清单完整原文。
+发布资产名称必须包含当前平台，例如 `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`，签名覆盖清单完整原文。
 
 ## curl 安装
 
@@ -104,7 +106,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 的版本号、发布时间和更新说明，点击“下载更新包”；root 更新器会在主服务继续运行时下载、校验 SHA-256、解包并暂存。页面显示“下载完成，等待应用”后，管理员再点击“立即更新”。应用阶段才会短暂停止服务、备份数据、切换 release、启动并执行健康检查；页面显示重启倒计时并自动重试连接。浏览器只提交版本号、任务 ID 和确认标志，不能提交 URL 或文件路径。
+后台更新分为两个明确阶段。管理员先在“系统更新”读取最新 Release 的版本号、发布时间和更新说明，点击“下载更新包”；当前安装如果存在匹配的锁文件指纹，更新器会自动选择轻量 `update-<锁文件 SHA256>` 资产，仅下载 `dist`、迁移和版本元数据，并复用当前版本的 Node 与生产依赖；如果运行时指纹不匹配或轻量包不可用，则自动选择完整安装包。root 更新器会在主服务继续运行时下载、校验 SHA-256、解包并暂存。页面显示“下载完成，等待应用”后，管理员再点击“立即更新”。应用阶段才会短暂停止服务、备份数据、切换 release、启动并执行健康检查；页面显示重启倒计时并自动重试连接。浏览器只提交版本号、任务 ID 和确认标志，不能提交 URL 或文件路径。
 
 Web 进程把受保护的任务文件交给 root 的 `tallynote-update.path`/`tallynote-update.service`，root runner 会重新读取配置源并验证 metadata、清单和暂存目录，不信任队列文件中的 URL 或摘要。切换失败或健康检查失败会恢复旧版本；手动回滚：
 

index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#f5f7f5" />
-    <title>TallyNote · 采购报销记录</title>
+    <title>TallyNote · 采购报销协同管理平台</title>
   </head>
   <body>
     <div id="root"></div>

install.sh

@@ -230,26 +230,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 +258,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 +267,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<&-
@@ -1460,7 +1460,6 @@ main() {
   elif [[ -n "${TALLYNOTE_PUBLIC_ORIGIN+x}" ]]; then
     set_env_key TALLYNOTE_PUBLIC_ORIGIN "$INSTALL_PUBLIC_ORIGIN"
   fi
-  if [[ -n "${TALLYNOTE_ALLOWED_ORIGINS+x}" ]]; then set_env_key TALLYNOTE_ALLOWED_ORIGINS "$TALLYNOTE_ALLOWED_ORIGINS"; fi
   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"
@@ -1539,5 +1538,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.1.21",
+  "version": "1.2.9",
   "private": true,
   "type": "module",
   "packageManager": "pnpm@9.0.6",

scripts/build-release.sh

@@ -13,6 +13,8 @@ if [[ -z "$VERSION" ]]; then
 fi
 VERSION=${VERSION#v}
 [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$ ]] || { printf 'invalid version: %s\n' "$VERSION" >&2; exit 2; }
+PACKAGE_VERSION=$(node -p 'require("./package.json").version')
+[[ "$VERSION" == "$PACKAGE_VERSION" ]] || { printf 'version mismatch: release %s does not match package.json %s\n' "$VERSION" "$PACKAGE_VERSION" >&2; exit 2; }
 case "$(uname -m)" in
   x86_64|amd64) ARCH=x64 ;;
   aarch64|arm64) ARCH=arm64 ;;
@@ -27,7 +29,11 @@ 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"
-cp -a dist/. "$stage/dist/"
+# 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/"
+cp -a dist/shared "$stage/dist/"
+cp -a dist/web "$stage/dist/"
 cp -a migrations/. "$stage/migrations/"
 cp package.json pnpm-lock.yaml "$stage/"
 cp -a bin/. "$stage/bin/"
@@ -46,6 +52,9 @@ find "$stage" -type l -delete
 mkdir -p "$OUT_DIR"
 archive="$OUT_DIR/tallynote-${VERSION}-linux-${ARCH}-${LIBC}.tar.gz"
 tar -C "$stage" -czf "$archive" --owner=0 --group=0 --numeric-owner .
+
+# Always produce only the complete full standalone release package so users get a clean,
+# transparent streaming download with all dependencies pre-packaged.
 # Keep the sidecar useful when a caller builds more than one architecture into
 # the same directory. The publishing script recomputes this list immediately
 # before signing, so stale or hand-edited entries can never reach a Release.

scripts/publish-gitea-release.sh

@@ -24,6 +24,7 @@ DRY_RUN=0
 AUTH_CONFIG=''
 SUMS_TMP=''
 SIG_TMP=''
+RELEASE_NOTES_TMP=''
 SIGNATURE_GENERATED=0
 
 usage() {
@@ -43,6 +44,81 @@ EOF
 die() { printf 'release publisher: %s\n' "$*" >&2; exit 1; }
 log() { printf 'release publisher: %s\n' "$*"; }
 
+generate_release_notes() {
+  local current=${TAG#v} previous='' subject kind line count=0
+  local -a commits
+  commits=()
+
+  # A workflow checks out the tag with history. Prefer an explicitly supplied
+  # notes file for mirrors, then derive notes from the immutable tag range.
+  if [[ -n "${TALLYNOTE_RELEASE_NOTES_FILE:-}" && -f "$TALLYNOTE_RELEASE_NOTES_FILE" ]]; then
+    # Read at most the API's bounded notes size without a pipe that can turn a
+    # deliberately truncated input into a SIGPIPE failure under pipefail.
+    LC_ALL=C awk 'BEGIN { remaining = 65536 } { if (remaining <= 0) exit; line=$0; gsub(/[[:cntrl:]]/, "", line); bytes=length(line)+1; if (bytes > remaining) { print substr(line, 1, remaining); exit } print line; remaining-=bytes }' "$TALLYNOTE_RELEASE_NOTES_FILE"
+    return
+  fi
+
+  if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    while IFS= read -r line; do
+      [[ -n "$line" ]] || continue
+      [[ "$line" == "v${current}" ]] && continue
+      previous="$line"
+      break
+    done < <(git tag --sort=-version:refname --list 'v*')
+    if [[ -n "$previous" && "$previous" != "v${current}" ]]; then
+      while IFS= read -r line; do
+        [[ -n "$line" ]] && commits+=("$line")
+      done < <(git log --format='%s' "${previous}..${TAG}")
+    else
+      while IFS= read -r line; do
+        [[ -n "$line" ]] && commits+=("$line")
+      done < <(git log -n 30 --format='%s' "$TAG")
+    fi
+  fi
+
+  printf '# TallyNote %s\n\n' "$current"
+  if [[ -n "$previous" ]]; then
+    printf '> 从 `%s` 到 `%s` 的变更\n\n' "$previous" "v${current}"
+  else
+    printf '> 本版本变更\n\n'
+  fi
+
+  local -a features fixes improvements docs other
+  features=(); fixes=(); improvements=(); docs=(); other=()
+  for subject in "${commits[@]-}"; do
+    # Do not expose merge noise or the synthetic release commit in user notes.
+    [[ "$subject" != Merge\ * && "$subject" != release:* ]] || continue
+    kind=${subject%%:*}
+    if [[ "$subject" == *:* ]]; then subject=${subject#*: }; fi
+    subject=${subject# }
+    [[ -n "$subject" ]] || continue
+    case "$kind" in
+      feat|feature) features+=("$subject") ;;
+      fix|bugfix) fixes+=("$subject") ;;
+      refactor|perf|style|improvement) improvements+=("$subject") ;;
+      docs|doc|test|tests) docs+=("$subject") ;;
+      *) other+=("$subject") ;;
+    esac
+  done
+
+  print_group() {
+    local title=$1; shift
+    local item
+    (($# > 0)) || return 0
+    printf '## %s\n\n' "$title"
+    for item in "$@"; do printf -- '- %s\n' "$item"; done
+    printf '\n'
+  }
+  ((${#features[@]})) && print_group '新增功能' "${features[@]}"
+  ((${#fixes[@]})) && print_group '问题修复' "${fixes[@]}"
+  ((${#improvements[@]})) && print_group '优化与重构' "${improvements[@]}"
+  ((${#docs[@]})) && print_group '文档与测试' "${docs[@]}"
+  ((${#other[@]})) && print_group '其他变更' "${other[@]}"
+  if (( ${#features[@]} + ${#fixes[@]} + ${#improvements[@]} + ${#docs[@]} + ${#other[@]} == 0 )); then
+    printf '本版本包含内部维护更新。\n'
+  fi
+}
+
 validate_semver() {
   local value=$1 prerelease part
   [[ "$value" =~ ^v?(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$ ]] || return 1
@@ -128,7 +204,8 @@ fi
 [[ "$CURL_BIN" != *[[:space:]]* && "$CURL_BIN" != *[[:cntrl:]]* ]] || die 'curl executable path is invalid'
 command -v "$CURL_BIN" >/dev/null 2>&1 || die 'curl is required'
 
-assets=()
+full_assets=()
+update_assets=()
 for file in "$ASSET_DIR"/*.tar.gz; do
   [[ -f "$file" && ! -L "$file" ]] || continue
   name=$(basename -- "$file")
@@ -136,9 +213,16 @@ for file in "$ASSET_DIR"/*.tar.gz; do
   asset_version=${name#tallynote-}
   asset_version=${asset_version%%-linux-*}
   [[ "$asset_version" == "${TAG#v}" ]] || die "release asset version does not match tag: $name"
-  assets+=("$file")
+  if [[ "$name" =~ \.update-[a-f0-9]{64}\.tar\.gz$ ]]; then
+    update_assets+=("$file")
+  else
+    full_assets+=("$file")
+  fi
 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'
 
 SUMS_FILE="$ASSET_DIR/SHA256SUMS"
 SIG_FILE="$ASSET_DIR/SHA256SUMS.sig"
@@ -161,6 +245,7 @@ cleanup() {
   if [[ -n "$AUTH_CONFIG" ]]; then rm -f -- "$AUTH_CONFIG"; fi
   if [[ -n "$SUMS_TMP" ]]; then rm -f -- "$SUMS_TMP"; fi
   if [[ -n "$SIG_TMP" ]]; then rm -f -- "$SIG_TMP"; fi
+  if [[ -n "$RELEASE_NOTES_TMP" ]]; then rm -f -- "$RELEASE_NOTES_TMP"; fi
 }
 trap cleanup EXIT
 if [[ -n "$SIGNING_KEY_FILE" ]]; then
@@ -196,6 +281,13 @@ command -v jq >/dev/null 2>&1 || die 'jq is required for Gitea API publishing'
 write_auth_config
 unset TOKEN
 
+# Keep the release body deterministic and human-readable. Gitea renders this
+# Markdown in the Release page; the update API later exposes the same body as
+# text for the safe client-side Markdown renderer.
+RELEASE_NOTES_TMP=$(mktemp)
+generate_release_notes > "$RELEASE_NOTES_TMP"
+release_notes=$(<"$RELEASE_NOTES_TMP")
+
 api_curl() {
   "$CURL_BIN" --proto '=https' --tlsv1.2 --fail --silent --show-error --connect-timeout 15 --max-time 120 \
     --config "$AUTH_CONFIG" "$@"
@@ -213,8 +305,17 @@ release_json=$(mktemp)
 status=$(api_curl_status --max-time 30 -o "$release_json" -w '%{http_code}' "$API_ROOT/repos/$repo_path/releases/tags/$TAG") || die '无法读取 Gitea Release'
 if [[ "$status" == 200 ]]; then
   release_id=$(jq -r '.id // empty' "$release_json")
+  existing_body=$(jq -r '.body // ""' "$release_json")
+  # Older releases used a one-line placeholder. Upgrade that placeholder when
+  # a tag is republished, while leaving deliberately authored release notes
+  # untouched.
+  if [[ "$existing_body" == "TallyNote $TAG" || -z "$existing_body" ]]; then
+    patch_body=$(jq -cn --arg body "$release_notes" '{body:$body}')
+    patch_status=$(api_curl_status -X PATCH -H 'Content-Type: application/json' -d "$patch_body" -o /dev/null -w '%{http_code}' "$API_ROOT/repos/$repo_path/releases/$release_id") || die '无法更新 Gitea Release 日志'
+    [[ "$patch_status" == 2* ]] || die "无法更新 Gitea Release 日志（HTTP $patch_status）"
+  fi
 elif [[ "$status" == 404 ]]; then
-  body=$(jq -cn --arg tag "$TAG" --arg name "$TAG" --arg body "TallyNote $TAG" '{tag_name:$tag,name:$name,body:$body,draft:false,prerelease:false}')
+  body=$(jq -cn --arg tag "$TAG" --arg name "$TAG" --arg body "$release_notes" '{tag_name:$tag,name:$name,body:$body,draft:false,prerelease:false}')
   create_status=$(api_curl_status -H 'Content-Type: application/json' -d "$body" -o "$release_json" -w '%{http_code}' "$API_ROOT/repos/$repo_path/releases") || die '无法创建 Gitea Release'
   if [[ "$create_status" == 2* ]]; then
     release_id=$(jq -r '.id // empty' "$release_json")

scripts/tallynote-update-runner.sh

@@ -10,6 +10,8 @@ DATA_DIR=${TALLYNOTE_DATA_DIR:-/var/lib/tallynote}
 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 +21,72 @@ 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; }
+
+# 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 +100,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 +116,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 +135,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 +148,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 +185,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,6 +195,7 @@ 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
@@ -128,7 +208,7 @@ if [[ "$request_operation" == download ]]; then
   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 +219,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 +230,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
@@ -175,11 +254,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 +266,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
@@ -312,7 +399,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 +410,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,6 +434,7 @@ cleanup_after_update() {
   else
     systemctl stop "$SERVICE_NAME" || true
   fi
+  release_runner_lock
   return "$result"
 }
 trap cleanup_after_update EXIT
@@ -358,7 +446,7 @@ 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

server/app.ts

@@ -54,14 +54,17 @@ import {
   validateNewPassword,
   verifyPassword,
 } from "./security.js";
+import { isNewerVersion } from "./update.js";
 import {
   ACTIVE_UPDATE_STATUSES,
   checkForUpdate,
+  currentReleaseVersion,
   publicCheckFromCache,
   publicUpdateJob,
   reconcileOrphanedUpdateJobs,
   readCachedRelease,
   writeUpdateRequest,
+  cancelUpdateJob,
   type UpdateRequest,
 } from "./update-service.js";
 
@@ -648,19 +651,6 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
     return payload;
   });
 
-  app.addHook("onRequest", async (request) => {
-    if (!unsafeMethods.has(request.method) || !request.url.startsWith("/api/")) return;
-    const origin = request.headers.origin;
-    const allowed = new Set(config.allowedOrigins);
-    if (!config.isProduction) {
-      allowed.add("http://127.0.0.1:5173");
-      allowed.add("http://localhost:5173");
-    }
-    if (typeof origin !== "string" || !allowed.has(origin)) {
-      throw new AppError(403, "ORIGIN_FORBIDDEN", "请求来源不受信任");
-    }
-  });
-
   app.setErrorHandler((error, request, reply) => {
     if (error instanceof AppError) return reply.code(error.statusCode).send(errorPayload(request, error));
     if (error instanceof ZodError) {
@@ -943,15 +933,23 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
     reply.header("Cache-Control", "no-store");
     reconcileOrphanedUpdateJobs(database.sqlite, config);
     const cached = publicCheckFromCache(database.sqlite, config);
+    // Status is a live control surface, not an update history endpoint.
+    // Terminal failures/cancellations from a previous attempt must not be
+    // replayed as if the operator had just started an update. They remain in
+    // the database/audit log, while this endpoint exposes only an actionable
+    // task (or the latest successful completion for confirmation).
     const row = database.sqlite.prepare(`
       SELECT id, operation, status, version, platform, asset_name AS assetName,
+        asset_url AS assetUrl, release_url AS releaseUrl,
         size_bytes AS sizeBytes, error_message AS errorMessage,
         created_at AS createdAt, updated_at AS updatedAt, completed_at AS completedAt,
         downloaded_bytes AS downloadedBytes, download_started_at AS downloadStartedAt,
         download_speed_bps AS downloadSpeedBps,
         requested_at AS applyQueuedAt
-      FROM update_jobs WHERE admin_id=? ORDER BY created_at DESC LIMIT 1
+      FROM update_jobs
-    `).get(request.auth!.admin.id) as Record<string, unknown> | undefined;
+      WHERE admin_id=? AND status IN (${[...ACTIVE_UPDATE_STATUSES, "completed"].map(() => "?").join(",")})
+      ORDER BY created_at DESC LIMIT 1
+    `).get(request.auth!.admin.id, ...ACTIVE_UPDATE_STATUSES, "completed") as Record<string, unknown> | undefined;
     return {
       ...cached,
       strategy: config.updateStrategy,
@@ -1016,6 +1014,15 @@ 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();
@@ -1188,11 +1195,23 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
     return reply.code(202).send({ job: { id, status: "queued", 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);
+    if (!result.cancelled) {
+      throw new AppError(409, "CANNOT_CANCEL", result.message || "无法取消当前更新任务");
+    }
+    reply.header("Cache-Control", "no-store");
+    return reply.send({ success: true, message: "已取消更新任务" });
+  });
+
   app.get("/api/update/jobs/:id", { preHandler: guard(database, config) }, async (request, reply) => {
     const id = z.string().uuid().parse((request.params as { id: string }).id);
     reconcileOrphanedUpdateJobs(database.sqlite, config);
     const row = database.sqlite.prepare(`
       SELECT id, operation, status, version, platform, asset_name AS assetName,
+        asset_url AS assetUrl, release_url AS releaseUrl,
         size_bytes AS sizeBytes, error_message AS errorMessage,
         created_at AS createdAt, updated_at AS updatedAt, completed_at AS completedAt,
         downloaded_bytes AS downloadedBytes, download_started_at AS downloadStartedAt,

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, ?)
+        VALUES (?, ?, ?, ?, ?, 'active', ?, 1, 1, ?)
-      `).run(id, username.normalize("NFKC").trim(), normalized, normalizedDisplayName, passwordHash, now);
+      `).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 { lstat, mkdir, mkdtemp, readFile, realpath, rm } from "node:fs/promises";
+import { cp, lstat, mkdir, mkdtemp, readFile, realpath, rm } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import type Database from "better-sqlite3";
@@ -10,6 +10,7 @@ import { writeAudit } from "../audit.js";
 import {
   atomicSwitchDirectory,
   atomicSwitchRelease,
+  applicationUpdateRuntimeHash,
   compareSemver,
   createSafeArchive,
   detectPlatform,
@@ -19,6 +20,7 @@ import {
   isNewerVersion,
   normalizeReleasePermissions,
   parseSemver,
+  runtimeHashFromLockfile,
   selectReleaseAsset,
   sanitizeAssetName,
   validateHttpsUrl,
@@ -161,7 +163,11 @@ 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=excluded.status, version=excluded.version, platform=excluded.platform,
+      -- 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),
       asset_url=excluded.asset_url,
@@ -173,6 +179,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,
@@ -212,14 +223,22 @@ 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);
+      : selectReleaseAsset(release, platform, runtimeHash);
     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,
     });
@@ -267,6 +286,7 @@ export async function runUpdate(options: UpdateRunOptions): Promise<UpdateRunRes
   const platform = options.platform ?? detectPlatform();
   const jobId = options.jobId ?? randomUUID();
   const operation = options.operation ?? "apply";
+  const sqlite = options.sqlite;
   let resolved: Awaited<ReturnType<typeof resolveRelease>> | undefined;
   try {
     resolved = await resolveRelease(options, platform);
@@ -290,7 +310,12 @@ export async function runUpdate(options: UpdateRunOptions): Promise<UpdateRunRes
     if (operation === "download") await mkdir(workspace, { recursive: false, mode: 0o700 });
     const archivePath = path.join(workspace, resolved.asset.name.endsWith(".gz") || resolved.asset.name.endsWith(".zip") ? resolved.asset.name : `${resolved.asset.name}.tar.gz`);
     try {
-      updateJob(options.sqlite, jobId, { operation, status: "downloading", version: resolved.version, platform: platform.target, releaseUrl: resolved.releaseUrl, assetName: resolved.asset.name, assetUrl: resolved.asset.url, expectedSha256, downloadPath: path.basename(archivePath), startedAt: Date.now() });
+      if (sqlite) {
+        const claim = sqlite.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(), path.basename(archivePath), Date.now(), jobId);
+        if (claim.changes !== 1) throw new Error("更新任务已取消或已被其他进程接管");
+      } else {
+        updateJob(options.sqlite, jobId, { operation, status: "downloading", version: resolved.version, platform: platform.target, releaseUrl: resolved.releaseUrl, assetName: resolved.asset.name, assetUrl: resolved.asset.url, expectedSha256, downloadPath: path.basename(archivePath), startedAt: Date.now() });
+      }
       const progressStartedAt = Date.now();
       let lastProgressWrite = 0;
       const downloaded = await downloadReleaseAsset(resolved.asset.url, archivePath, {
@@ -314,10 +339,26 @@ 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 });
+        }
+      }
       await normalizeReleasePermissions(stagedDir);
       const payloadInfo = await lstat(path.join(stagedDir, "dist")).catch(() => null);
       if (!payloadInfo?.isDirectory() || payloadInfo.isSymbolicLink()) throw new Error("发布包缺少 dist 目录");
-      updateJob(options.sqlite, jobId, { operation, status: "staged", version: resolved.version, platform: platform.target, releaseUrl: resolved.releaseUrl, assetName: resolved.asset.name, assetUrl: resolved.asset.url, expectedSha256, actualSha256: downloaded.sha256, sizeBytes: downloaded.size, downloadPath: workspace });
+      if (sqlite) {
+        const staged = sqlite.prepare("UPDATE update_jobs SET status='staged', 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) throw new Error("更新任务已取消，已停止继续处理");
+      } else {
+        updateJob(options.sqlite, jobId, { operation, status: "staged", version: resolved.version, platform: platform.target, releaseUrl: resolved.releaseUrl, assetName: resolved.asset.name, assetUrl: resolved.asset.url, expectedSha256, actualSha256: downloaded.sha256, sizeBytes: downloaded.size, downloadPath: workspace });
+      }
 
       if (operation === "download") {
         keepWorkspace = true;
@@ -366,19 +407,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,
@@ -537,6 +587,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

@@ -43,21 +43,6 @@ function csvEnv(name: string): string[] {
     .filter(Boolean);
 }
 
-function originListEnv(name: string, primary: string): string[] {
-  const values = [primary, ...csvEnv(name)];
-  const origins = new Set<string>();
-  for (const value of values) {
-    try {
-      const parsed = new URL(value);
-      if (!["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password || parsed.pathname !== "/" && parsed.pathname !== "" || parsed.search || parsed.hash) throw new Error();
-      origins.add(parsed.origin);
-    } catch {
-      throw new Error(`${name} 必须是逗号分隔的 HTTP(S) Origin（不含路径）`);
-    }
-  }
-  return [...origins];
-}
-
 function updatePublicKeyEnv(): string | undefined {
   const inline = process.env.TALLYNOTE_UPDATE_PUBLIC_KEY?.trim();
   const file = process.env.TALLYNOTE_UPDATE_PUBLIC_KEY_FILE?.trim();
@@ -113,7 +98,6 @@ export function loadConfig() {
     throw new Error("TALLYNOTE_PUBLIC_ORIGIN 不能使用通配监听地址，请填写服务器 IP 或域名");
   }
   const localOrigin = ["127.0.0.1", "localhost", "::1"].includes(publicHost);
-  const allowedOrigins = originListEnv("TALLYNOTE_ALLOWED_ORIGINS", parsedOrigin.origin);
   const appVersion = (() => {
     try {
       const packageJson = JSON.parse(readFileSync(path.join(projectRoot, "package.json"), "utf8")) as { version?: unknown };
@@ -143,7 +127,6 @@ export function loadConfig() {
     host,
     port,
     publicOrigin: parsedOrigin.origin,
-    allowedOrigins,
     timezone,
     trustProxy: trustProxyEnv(),
     cookieSecure,
@@ -164,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.

server/update-service.ts

@@ -13,6 +13,7 @@ import {
   fetchReleaseText,
   isNewerVersion,
   parseSemver,
+  runtimeHashFromLockfile,
   sanitizeAssetName,
   selectReleaseAsset,
   validateHttpsUrl,
@@ -22,6 +23,7 @@ import {
 } from "./update.js";
 import type { UpdateJobStatus } from "../shared/contracts.js";
 
+
 export const UPDATE_CACHE_KEY = "update.release.v1";
 export const ACTIVE_UPDATE_STATUSES: readonly UpdateJobStatus[] = [
   "queued",
@@ -37,6 +39,7 @@ export const ACTIVE_UPDATE_STATUSES: readonly UpdateJobStatus[] = [
 // a lease while doing long downloads/backups; only an expired lease permits
 // the server to reclaim an active row.
 export const ORPHANED_UPDATE_TIMEOUT_MS = 5 * 60 * 1000;
+export const QUEUED_UPDATE_TIMEOUT_MS = 25 * 1000;
 
 export type CachedRelease = {
   checkedAt: number;
@@ -151,19 +154,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);
       }
     }
@@ -180,6 +183,7 @@ function policy(config: AppConfig) {
     allowedHosts: config.updateAllowedHosts,
     baseUrl: config.updateMetadataUrl,
     maxRedirects: 3,
+    timeoutMs: config.updateTimeoutMs,
   } as const;
 }
 
@@ -204,13 +208,22 @@ export async function checkForUpdate(database: Database.Database, config: AppCon
   } catch {
     throw new AppError(502, "UPDATE_CHECK_FAILED", "暂时无法获取最新版本，请稍后重试");
   }
-  let asset = selectReleaseAsset(metadata, platform);
+  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
+  let asset = selectReleaseAsset(metadata, platform, undefined);
   let signatureVerified = false;
   if (asset) {
     const integrity = await attachSidecarHash(metadata, asset, {
       allowedHosts: config.updateAllowedHosts,
       baseUrl: metadataUrl,
       maxBytes: config.updateMaxBytes,
+      timeoutMs: config.updateTimeoutMs,
       publicKey: config.updatePublicKey,
       requireSignature: config.updateRequireSignature,
     });
@@ -338,6 +351,15 @@ export async function writeUpdateRequest(config: AppConfig, request: UpdateReque
   }
 }
 
+
+function safePublicErrorMessage(msg: unknown): string {
+  if (typeof msg !== "string" || !msg.trim()) return "更新失败，请查看服务器日志或重试";
+  if (msg.includes("/var/lib") || msg.includes("/opt/") || msg.includes("/etc/") || msg.includes("secret") || msg.includes("command-output")) {
+    return "更新失败，请查看服务器日志或重试";
+  }
+  return msg.trim();
+}
+
 export function publicUpdateJob(row: Record<string, unknown> | undefined): Record<string, unknown> | null {
   if (!row) return null;
   const hasError = typeof row.errorMessage === "string" && row.errorMessage.length > 0;
@@ -350,14 +372,13 @@ export function publicUpdateJob(row: Record<string, unknown> | undefined): Recor
     version: row.version,
     platform: row.platform,
     assetName: row.assetName ?? null,
+    assetUrl: row.assetUrl ?? null,
+    releaseUrl: row.releaseUrl ?? null,
     sizeBytes: row.sizeBytes ?? null,
     downloadedBytes: row.downloadedBytes ?? null,
     downloadStartedAt: row.downloadStartedAt ?? null,
     downloadSpeedBps: row.downloadSpeedBps ?? null,
-    // Do not expose filesystem paths, command output, or upstream response
+    errorMessage: hasError ? safePublicErrorMessage(row.errorMessage) : null,
-    // text through the authenticated status endpoint. Detailed diagnostics
-    // remain in the server journal for operators.
-    errorMessage: hasError ? "更新失败，请查看服务器日志或重试" : null,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
     completedAt: row.completedAt ?? null,
@@ -376,6 +397,14 @@ function markerMtime(filePath: string): number | null {
   }
 }
 
+function forceRemoveRequest(filePath: string): void {
+  try {
+    const info = lstatSync(filePath);
+    if (!info.isFile() && !info.isSymbolicLink()) return;
+    unlinkSync(filePath);
+  } catch {}
+}
+
 function removeExpiredRequest(filePath: string, now: number): void {
   try {
     const info = lstatSync(filePath);
@@ -399,7 +428,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);
@@ -433,6 +473,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
@@ -441,12 +487,81 @@ 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" && !matchingFreshState && now - row.updatedAt >= QUEUED_UPDATE_TIMEOUT_MS) {
+      if (matchingFreshRequest) continue;
+      const changed = database.transaction(() => {
+        const result = database.prepare(`
+          UPDATE update_jobs
+          SET status='failed', error_message=?, completed_at=?, updated_at=?
+          WHERE id=? AND status='queued' 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, version: row.version },
+          after: { status: "failed", version: row.version, reason: "runner_claim_timeout" },
+        });
+        return true;
+      })();
+      if (changed) {
+        reconciled += 1;
+        reconciledIds.add(row.id);
+      }
+      continue;
+    }
     if (typeof row.updatedAt !== "number" || now - row.updatedAt < ORPHANED_UPDATE_TIMEOUT_MS) continue;
     // The runner refreshes the state marker while a download is in flight.
     // 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;
+      if (row.operation !== "apply" || matchingFreshRequest || matchingFreshState) continue;
       const changed = database.transaction(() => {
         const result = database.prepare(`
           UPDATE update_jobs
@@ -472,7 +587,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(() => {
@@ -513,10 +628,54 @@ export function reconcileOrphanedUpdateJobs(database: Database.Database, config:
       && !reconciledIds.has(queuedRequest.id)
       && !(queuedRequest.status === "staged" && queuedRequest.operation === "download"),
   );
-  if (!stateFresh
+  if (!stateFresh && !requestStillNeeded) {
-    && (!requestPresent || (requestMtime !== null && now - requestMtime >= ORPHANED_UPDATE_TIMEOUT_MS))
+    forceRemoveRequest(config.updateRequestPath);
-    && !requestStillNeeded) {
+  } else if (!stateFresh && (!requestPresent || (requestMtime !== null && now - requestMtime >= ORPHANED_UPDATE_TIMEOUT_MS))) {
     removeExpiredRequest(config.updateRequestPath, now);
   }
   return reconciled;
 }
+
+export function cancelUpdateJob(
+  database: Database.Database,
+  config: AppConfig,
+  adminId: string,
+  requestId: string,
+  jobId?: string,
+): { cancelled: boolean; message?: string } {
+  const job = jobId
+    ? database.prepare("SELECT id, status, operation, version, admin_id AS adminId, download_path AS downloadPath FROM update_jobs WHERE id=? AND admin_id=?").get(jobId, adminId) 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 admin_id=? AND status IN ('queued', 'downloading') ORDER BY created_at DESC LIMIT 1").get(adminId) as { id: string; status: UpdateJobStatus; operation: string; version: string; adminId: string | null; downloadPath: string | null } | undefined;
+
+  if (!job) return { cancelled: false, message: "当前没有处于等待调度或下载中的更新任务" };
+  if (job.status !== "queued" && job.status !== "downloading") 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 admin_id=? AND status IN ('queued', 'downloading')").run(now, now, job.id, adminId);
+    if (result.changes !== 1) return false;
+    writeAudit(database, {
+      requestId,
+      actorAdminId: adminId,
+      action: "update.cancelled",
+      targetType: "update",
+      targetId: job.id,
+      outcome: "success",
+      before: { status: job.status, operation: job.operation, version: job.version },
+      after: { status: "cancelled", version: job.version },
+    });
+    return true;
+  })();
+
+  if (changed) {
+    // 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);
+    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(() => {});
+    }
+    return { cancelled: true };
+  }
+  return { cancelled: false, message: "取消失败，任务状态可能已改变" };
+}

server/update.ts

@@ -43,14 +43,38 @@ export type ReleaseMetadata = {
   assets: ReleaseAsset[];
 };
 
+const APPLICATION_UPDATE_ASSET = /\.update-([a-f0-9]{64})\.tar\.gz$/i;
+
+export function applicationUpdateRuntimeHash(assetName: string): string | undefined {
+  return APPLICATION_UPDATE_ASSET.exec(assetName)?.[1]?.toLowerCase();
+}
+
+export function runtimeHashFromLockfile(lockfile: string | Buffer): string {
+  return createHash("sha256").update(lockfile).digest("hex");
+}
+
 export type UrlPolicy = {
   /** Host names or HTTPS URLs which are allowed for requests. */
   allowedHosts?: readonly string[] | undefined;
   /** 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("更新版本号无效");
 }
@@ -147,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
@@ -200,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) {
@@ -223,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);
@@ -231,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);
@@ -318,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
@@ -346,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);
@@ -356,30 +421,35 @@ 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()): ReleaseAsset | undefined {
+export function selectReleaseAsset(release: ReleaseMetadata, platform = detectPlatform(), runtimeHash?: string): ReleaseAsset | undefined {
   const platformCandidates = release.assets.filter((asset) => {
     const name = asset.name.toLowerCase();
     return platform.aliases.filter((alias) => alias.toLowerCase().includes(platform.arch.toLowerCase())).some((alias) => name.includes(alias.toLowerCase()));
@@ -398,7 +468,12 @@ export function selectReleaseAsset(release: ReleaseMetadata, platform = detectPl
     const target = platform.target.toLowerCase();
     return Number(b.name.toLowerCase().includes(target)) - Number(a.name.toLowerCase().includes(target));
   });
-  return candidates[0];
+  const normalizedRuntimeHash = runtimeHash?.trim().toLowerCase();
+  if (normalizedRuntimeHash && /^[a-f0-9]{64}$/.test(normalizedRuntimeHash)) {
+    const applicationUpdate = candidates.find((asset) => applicationUpdateRuntimeHash(asset.name) === normalizedRuntimeHash);
+    if (applicationUpdate) return applicationUpdate;
+  }
+  return candidates.find((asset) => !applicationUpdateRuntimeHash(asset.name));
 }
 
 export function sanitizeAssetName(value: string): string {
@@ -423,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);
@@ -433,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;
@@ -460,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();
@@ -469,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") };
 }

shared/contracts.ts

@@ -107,7 +107,7 @@ export const updateApplySchema = z.object({
 
 export const updateDownloadSchema = z.object({
   version: z.string().trim().regex(/^v?(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/),
-  confirm: z.literal(true),
+  confirm: z.boolean().default(true).optional(),
 }).strict();
 
 export type ApiError = {

systemd/tallynote-update.service

@@ -1,8 +1,5 @@
 [Unit]
 Description=TallyNote privileged release updater
-After=network-online.target
-Wants=network-online.target
-
 [Service]
 Type=oneshot
 User=root
@@ -11,13 +8,13 @@ WorkingDirectory=/opt/tallynote/current
 EnvironmentFile=-/etc/tallynote/tallynote.env
 ExecStart=/usr/local/libexec/tallynote-update-runner
 Environment=PATH=/usr/sbin:/usr/bin:/sbin:/bin
+# The runner consumes queued requests immediately and applies its own bounded
+# phase timeouts while keeping full CLI diagnostics in the runner log.
 # Downloads, 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=32min
 NoNewPrivileges=true
-CapabilityBoundingSet=
-AmbientCapabilities=
 # Keep the updater compatible with the same Node/libuv interface discovery
 # path while retaining an explicit socket-family allowlist.
 RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
@@ -28,7 +25,6 @@ ProtectSystem=strict
 ProtectKernelTunables=true
 ProtectKernelModules=true
 ProtectKernelLogs=true
-ProtectControlGroups=true
 ProtectClock=true
 LockPersonality=true
 RestrictRealtime=true

systemd/tallynote.env.example

@@ -3,13 +3,13 @@ TALLYNOTE_PORT=3000
 TALLYNOTE_DATA_DIR=/var/lib/tallynote
 TALLYNOTE_INSTALL_PREFIX=/opt/tallynote
 TALLYNOTE_PUBLIC_ORIGIN=http://127.0.0.1:3000
-TALLYNOTE_ALLOWED_ORIGINS=http://127.0.0.1:3000
 TALLYNOTE_COOKIE_SECURE=false
 TALLYNOTE_ALLOW_INSECURE_HTTP=false
 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

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/api.test.ts

@@ -129,10 +129,10 @@ describe("TallyNote API", () => {
     }
   });
 
-  it("拒绝没有 Origin 的写请求", async () => {
+  it("反向代理缺少 Origin 时仍允许登录请求进入认证流程", async () => {
     const response = await app.inject({ method: "POST", url: "/api/auth/login", payload: { username: "x", password: "x" } });
-    expect(response.statusCode).toBe(403);
+    expect(response.statusCode).toBe(401);
-    expect(response.json().error.code).toBe("ORIGIN_FORBIDDEN");
+    expect(response.json().error.code).toBe("INVALID_CREDENTIALS");
   });
 
   it("将非法 JSON、伪造请求 ID 处理为结构化 400", async () => {

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/security.test.ts

@@ -5,7 +5,7 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { loadConfig, prepareDataDirectories } from "../server/config.js";
 
-const keys = ["TALLYNOTE_DATA_DIR", "TALLYNOTE_HOST", "TALLYNOTE_PORT", "TALLYNOTE_PUBLIC_ORIGIN", "TALLYNOTE_ALLOWED_ORIGINS", "TALLYNOTE_COOKIE_SECURE", "TALLYNOTE_ALLOW_INSECURE_HTTP", "TALLYNOTE_TRUST_PROXY", "NODE_ENV", "TALLYNOTE_ENV", "TALLYNOTE_UPDATE_STRATEGY", "TALLYNOTE_UPDATE_ALLOWED_HOSTS", "TALLYNOTE_UPDATE_REQUIRE_SIGNATURE", "TALLYNOTE_UPDATE_PUBLIC_KEY", "TALLYNOTE_UPDATE_PUBLIC_KEY_FILE"];
+const keys = ["TALLYNOTE_DATA_DIR", "TALLYNOTE_HOST", "TALLYNOTE_PORT", "TALLYNOTE_PUBLIC_ORIGIN", "TALLYNOTE_COOKIE_SECURE", "TALLYNOTE_ALLOW_INSECURE_HTTP", "TALLYNOTE_TRUST_PROXY", "NODE_ENV", "TALLYNOTE_ENV", "TALLYNOTE_UPDATE_STRATEGY", "TALLYNOTE_UPDATE_ALLOWED_HOSTS", "TALLYNOTE_UPDATE_REQUIRE_SIGNATURE", "TALLYNOTE_UPDATE_PUBLIC_KEY", "TALLYNOTE_UPDATE_PUBLIC_KEY_FILE"];
 
 afterEach(() => { for (const key of keys) delete process.env[key]; });
 
@@ -48,14 +48,6 @@ describe("部署安全配置", () => {
     expect(loadConfig().trustProxy).toBe(1);
   });
 
-  it("允许显式列出反向代理的多个可信 Origin", () => {
-    process.env.TALLYNOTE_PUBLIC_ORIGIN = "https://tally.example.test";
-    process.env.TALLYNOTE_COOKIE_SECURE = "true";
-    process.env.TALLYNOTE_ALLOWED_ORIGINS = "https://tally.example.test, https://tally.internal.test:8443";
-    expect(loadConfig().allowedOrigins).toEqual(["https://tally.example.test", "https://tally.internal.test:8443"]);
-    process.env.TALLYNOTE_ALLOWED_ORIGINS = "https://tally.example.test/app";
-    expect(() => loadConfig()).toThrow(/Origin/);
-  });
 
   it("systemd 更新必须绑定主机白名单，签名校验默认关闭", () => {
     process.env.TALLYNOTE_UPDATE_STRATEGY = "systemd";

tests/update-api.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { chmodSync, mkdtempSync, readFileSync, statSync, rmSync } from "node:fs";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, statSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
@@ -59,10 +59,10 @@ describe("更新 API", () => {
 
   function mockRelease() {
     const digest = "c".repeat(64);
-    const asset = `tallynote-1.2.0-${detectPlatform().target}-glibc.tar.gz`;
+    const asset = `tallynote-1.3.0-${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.2.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: "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;
   }
 
   it("检查 release、创建受保护请求文件并拒绝重复任务", async () => {
@@ -70,7 +70,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.2.0", compatible: true, integrityReady: true, isNewer: true });
+    expect(checked.json().latest).toMatchObject({ version: "1.3.0", 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,15 +82,15 @@ 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.2.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: "1.3.0", 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.2.0", expectedSha256: "c".repeat(64), currentLink: config.currentLink });
+    expect(request).toMatchObject({ jobId, version: "1.3.0", 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.2.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: "1.3.0", 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 } });
@@ -104,10 +104,10 @@ 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.2.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: "1.3.0", confirm: true } });
     expect(downloaded.statusCode).toBe(202);
     const downloadJobId = downloaded.json().job.id as string;
-    expect(downloaded.json().job).toMatchObject({ operation: "download", status: "queued", version: "1.2.0" });
+    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" });
@@ -116,34 +116,99 @@ describe("更新 API", () => {
     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.2.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);
+      .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.2.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: { jobId: stagedId, version: "1.3.0", 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.2.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: "1.3.0", 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.2.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: "1.3.0" } });
     expect(invalid.statusCode).toBe(400);
     process.env.TALLYNOTE_UPDATE_STRATEGY = "disabled";
     const disabledConfig = loadConfig();
     expect(disabledConfig.updateStrategy).toBe("disabled");
   });
 
+  it("首次进入状态页不会展示历史失败任务，也不会阻断新的检查", async () => {
+    const session = await login("update-history");
+    const admin = database.sqlite.prepare("SELECT id FROM admins WHERE username=?").get("update-history") as { id: string };
+    const now = Date.now();
+    database.sqlite.prepare(`
+      INSERT INTO update_jobs(id, admin_id, operation, status, version, platform, asset_url, error_message, created_at, updated_at)
+      VALUES (?, ?, 'download', 'failed', '1.1.0', ?, 'https://updates.example/old.tar.gz', 'old failure', ?, ?)
+    `).run(randomUUID(), admin.id, detectPlatform().target, now - 60_000, now - 60_000);
+    const initial = await app.inject({ method: "GET", url: "/api/update/status", headers: { cookie: session.cookies } });
+    expect(initial.statusCode).toBe(200);
+    expect(initial.json().job).toBeNull();
+
+    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 });
+  });
+
+  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 () => {
     const owner = await login("update-owner");
     const other = await login("update-other");
     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.2.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: "1.3.0", 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);
@@ -158,10 +223,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', '1.3.0', ?, '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.2.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: "1.3.0", 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.
@@ -172,4 +273,161 @@ describe("更新 API", () => {
     const audit = database.sqlite.prepare("SELECT outcome FROM audit_events WHERE action='update.apply_requested' ORDER BY id DESC LIMIT 1").get() as { outcome: string } | undefined;
     expect(audit?.outcome).toBe("failure");
   });
+
+  it("下载请求交由 systemd runner 接管，并保留可查询的排队状态", async () => {
+    const { createSafeArchive } = await import("../server/update.js");
+    const { createHash } = await import("node:crypto");
+    const { mkdirSync, writeFileSync } = await import("node:fs");
+
+    const payloadSource = mkdtempSync(path.join(tmpdir(), "tallynote-test-payload-"));
+    mkdirSync(path.join(payloadSource, "dist"), { recursive: true });
+    writeFileSync(path.join(payloadSource, "dist", "server.js"), "console.log(1);");
+    const archivePath = path.join(tmpdir(), `tallynote-archive-${randomUUID()}.tar.gz`);
+    await createSafeArchive(payloadSource, archivePath);
+
+    const archiveBytes = readFileSync(archivePath);
+    const digest = createHash("sha256").update(archiveBytes).digest("hex");
+    const assetName = `tallynote-1.3.0-${detectPlatform().target}-glibc.tar.gz`;
+
+    globalThis.fetch = (async (input: string | URL) => {
+      const url = input.toString();
+      if (url.endsWith("SHA256SUMS")) {
+        return new Response(`${digest}  ${assetName}\n`, { status: 200 });
+      }
+      if (url.endsWith(assetName)) {
+        return new Response(archiveBytes, { status: 200, headers: { "content-length": String(archiveBytes.length) } });
+      }
+      return new Response(JSON.stringify({
+        tag_name: "v1.3.0",
+        assets: [
+          { name: "SHA256SUMS", browser_download_url: "https://updates.example/SHA256SUMS" },
+          { name: assetName, browser_download_url: `https://updates.example/${assetName}` }
+        ]
+      }), { status: 200 });
+    }) as typeof fetch;
+
+    const session = await login("update-inprocess");
+    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 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();
+
+    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",
+      operation: "download",
+      assetName,
+      assetUrl: `https://updates.example/${assetName}`,
+    });
+
+    rmSync(payloadSource, { recursive: true, force: true });
+    rmSync(archivePath, { force: true });
+  });
+
+
+  it("管理员可取消 systemd 下载任务并清理请求文件", async () => {
+    const { createSafeArchive } = await import("../server/update.js");
+    const { createHash } = await import("node:crypto");
+    const { mkdirSync, writeFileSync } = await import("node:fs");
+
+    const payloadSource = mkdtempSync(path.join(tmpdir(), "tallynote-cancel-payload-"));
+    mkdirSync(path.join(payloadSource, "dist"), { recursive: true });
+    writeFileSync(path.join(payloadSource, "dist", "server.js"), "console.log(1);");
+    const archivePath = path.join(tmpdir(), `tallynote-cancel-${randomUUID()}.tar.gz`);
+    await createSafeArchive(payloadSource, archivePath);
+
+    const archiveBytes = readFileSync(archivePath);
+    const digest = createHash("sha256").update(archiveBytes).digest("hex");
+    const assetName = `tallynote-1.3.0-${detectPlatform().target}-glibc.tar.gz`;
+
+    // Mock a slow stream
+    let fetchAborted = false;
+    globalThis.fetch = (async (input: string | URL, init?: any) => {
+      const url = input.toString();
+      if (url.endsWith("SHA256SUMS")) {
+        return new Response(`${digest}  ${assetName}\n`, { status: 200 });
+      }
+      if (url.endsWith(assetName)) {
+        init?.signal?.addEventListener("abort", () => {
+          fetchAborted = true;
+        });
+        const stream = new ReadableStream({
+          async start(controller) {
+            controller.enqueue(archiveBytes.slice(0, 50));
+            // Simulate hanging network until aborted
+            await new Promise((resolve) => {
+              if (init?.signal?.aborted) return resolve(undefined);
+              init?.signal?.addEventListener("abort", () => resolve(undefined));
+            });
+            controller.close();
+          }
+        });
+        return new Response(stream, { status: 200, headers: { "content-length": String(archiveBytes.length) } });
+      }
+      return new Response(JSON.stringify({
+        tag_name: "v1.3.0",
+        assets: [
+          { name: "SHA256SUMS", browser_download_url: "https://updates.example/SHA256SUMS" },
+          { name: assetName, browser_download_url: `https://updates.example/${assetName}` }
+        ]
+      }), { status: 200 });
+    }) as typeof fetch;
+
+    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 downloadJobId = downloaded.json().job.id as string;
+
+    // Wait until status becomes downloading
+    for (let i = 0; i < 30; i++) {
+      await new Promise((r) => setTimeout(r, 30));
+      const row = database.sqlite.prepare("SELECT status FROM update_jobs WHERE id=?").get(downloadJobId) as any;
+      if (row?.status === "downloading") break;
+    }
+
+    const cancelRes = await app.inject({
+      method: "POST",
+      url: "/api/update/cancel",
+      headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf },
+      payload: { jobId: downloadJobId }
+    });
+
+    expect(cancelRes.statusCode).toBe(200);
+    expect(cancelRes.json().success).toBe(true);
+
+    const cancelledRow = database.sqlite.prepare("SELECT status FROM update_jobs WHERE id=?").get(downloadJobId) as any;
+    expect(cancelledRow?.status).toBe("cancelled");
+    expect(fetchAborted).toBe(false);
+
+    rmSync(payloadSource, { recursive: true, force: true });
+    rmSync(archivePath, { force: true });
+  });
+
+  it("管理员可主动取消排队中的更新任务并清理请求文件", async () => {
+    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 } });
+    expect(applied.statusCode).toBe(202);
+    expect(existsSync(config.updateRequestPath)).toBe(true);
+
+    const cancelRes = await app.inject({ method: "POST", url: "/api/update/cancel", headers: { origin: config.publicOrigin, cookie: session.cookies, "x-csrf-token": session.csrf }, payload: {} });
+    expect(cancelRes.statusCode).toBe(200);
+    expect(cancelRes.json().success).toBe(true);
+    expect(existsSync(config.updateRequestPath)).toBe(false);
+
+    const statusRes = await app.inject({ method: "GET", url: "/api/update/status", headers: { cookie: session.cookies } });
+    expect(statusRes.statusCode).toBe(200);
+    expect(statusRes.json().job).toBeNull();
+  });
 });

tests/update.test.ts

@@ -6,6 +6,7 @@ import path from "node:path";
 import { createHash, generateKeyPairSync, randomUUID, sign } from "node:crypto";
 import {
   atomicSwitchRelease,
+  applicationUpdateRuntimeHash,
   createSafeArchive,
   detectPlatform,
   downloadReleaseAsset,
@@ -16,6 +17,7 @@ import {
   normalizeReleasePermissions,
   sanitizeAssetName,
   selectReleaseAsset,
+  runtimeHashFromLockfile,
   validateHttpsUrl,
 } from "../server/update.js";
 import { finalizeUpdateJob, runUpdate } from "../server/cli/update.js";
@@ -38,18 +40,29 @@ 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.2.0",
+      version: "1.3.0",
       assets: [
-        { name: "tallynote-1.2.0-linux-arm64-glibc.tar.gz", url: "https://updates.example/arm" },
+        { name: "tallynote-1.3.0-linux-arm64-glibc.tar.gz", url: "https://updates.example/arm" },
-        { name: "tallynote-1.2.0-linux-x64-glibc.tar.gz", url: "https://updates.example/x64" },
+        { name: "tallynote-1.3.0-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.2.0", assets: [{ name: "tallynote-1.2.0-linux-arm64-glibc.tar.gz", url: "https://updates.example/arm" }] }, detectPlatform("linux", "x86_64"))).toBeUndefined();
+    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(() => 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] };
+    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);
+    expect(applicationUpdateRuntimeHash(full.name)).toBeUndefined();
+  });
+
   it("验证 SHA256SUMS 的 Ed25519 detached signature", () => {
     const { publicKey, privateKey } = generateKeyPairSync("ed25519");
     const payload = "a".repeat(64) + "  tallynote.tar.gz\n";
@@ -89,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.2.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: "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(`${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.2.0");
+    expect(metadata.version).toBe("1.3.0");
     expect((await fetchReleaseText("https://updates.example/SHA256SUMS", { allowedHosts: ["updates.example"] })).trim()).toContain(digest);
   });
 
@@ -240,22 +253,22 @@ describe("更新安全工具", () => {
       const jobId = randomUUID();
       database = openDatabase(config);
       const now = Date.now();
-      const assetName = `tallynote-1.2.0-${detectPlatform().target}.tar.gz`;
+      const assetName = `tallynote-1.3.0-${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.2.0', ?, ?, ?, ?, ?, ?)
+        VALUES (?, 'apply', 'queued', '1.3.0', ?, ?, ?, ?, ?, ?)
       `).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.2.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: "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("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.2.0",
+        version: "1.3.0",
         currentVersion: config.appVersion,
         currentDir: config.currentLink,
         stagingDir: path.join(root, "staging"),
@@ -273,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");
+      finalizeUpdateJob(database.sqlite, jobId, "failed", "健康检查失败（自定义）");
-      expect(database.sqlite.prepare("SELECT status FROM update_jobs WHERE id=?").get(jobId)).toEqual({ status: "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', '1.3.0', ?, ?, ?, ?)
+      `).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', '1.3.0', ?, ?, ?, ?)
+      `).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();
@@ -310,10 +342,10 @@ describe("更新安全工具", () => {
       const applyingId = randomUUID();
       const stagedId = randomUUID();
       const stagedApplyId = randomUUID();
-      insert.run(queuedId, "apply", "queued", "1.2.0", "linux-x64", "https://updates.example/queued.tar.gz", staleAt, staleAt);
+      insert.run(queuedId, "apply", "queued", "1.3.0", "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.2.0", "linux-x64", "https://updates.example/staged.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.2.0", "linux-x64", "https://updates.example/staged-apply.tar.gz", staleAt, staleAt);
+      insert.run(stagedApplyId, "apply", "staged", "1.3.0", "linux-x64", "https://updates.example/staged-apply.tar.gz", staleAt, staleAt);
       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" });
@@ -349,7 +381,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.2.0', 'linux-x64', ?, ?, ?)
+        VALUES (?, 'download', 'downloading', '1.3.0', '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");
@@ -372,7 +404,7 @@ describe("更新安全工具", () => {
     }
   });
 
-  it("队列任务有新请求标记时可被重新检查，标记过期后才回收", async () => {
+  it("队列任务有匹配请求标记时保留到租约过期，过期后才回收", async () => {
     const root = await mkdtemp(path.join(tmpdir(), "tallynote-update-queued-marker-"));
     let database: ReturnType<typeof openDatabase> | undefined;
     try {
@@ -393,15 +425,17 @@ 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.2.0', 'linux-x64', ?, ?, ?)
+        VALUES (?, 'apply', 'queued', '1.3.0', '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));
 
+      // 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" });
-      expect(await stat(config.updateRequestPath)).toBeTruthy();
+      await expect(stat(config.updateRequestPath)).resolves.toBeTruthy();
 
       const expiredNow = now + ORPHANED_UPDATE_TIMEOUT_MS + 1;
       expect(reconcileOrphanedUpdateJobs(database.sqlite, config, expiredNow)).toBe(1);
@@ -479,17 +513,17 @@ describe("更新元数据缓存", () => {
     prepareDataDirectories(config);
     const database = openDatabase(config);
     const digest = "b".repeat(64);
-    const platformAsset = `tallynote-1.2.0-${detectPlatform().target}-glibc.tar.gz`;
+    const platformAsset = `tallynote-1.3.0-${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.2.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: "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;
     try {
       const result = await checkForUpdate(database.sqlite, config);
-      expect(result.latest).toMatchObject({ version: "1.2.0", compatible: true, integrityReady: true, signatureReady: true, isNewer: true });
+      expect(result.latest).toMatchObject({ version: "1.3.0", 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 {

web-next/src/components/BeamLoading.tsx

@@ -0,0 +1,39 @@
+import type { ReactNode } from "react";
+
+export function BeamBar({
+  className = "",
+  width = 140,
+  height = 4,
+}: {
+  className?: string;
+  width?: number | string;
+  height?: number;
+}) {
+  return (
+    <div
+      className={`tn-beam-bar ${className}`}
+      style={{ width, height }}
+      role="progressbar"
+      aria-label="加载中"
+    />
+  );
+}
+
+export function BeamLoading({
+  text,
+  className = "",
+  width,
+}: {
+  text?: ReactNode;
+  className?: string;
+  width?: number | string;
+}) {
+  return (
+    <div className={`tn-beam-loading ${className}`} role="status" aria-live="polite">
+      <BeamBar width={width} />
+      {text && <span className="tn-beam-text">{text}</span>}
+    </div>
+  );
+}
+
+export default BeamLoading;

web-next/src/main.tsx

@@ -1,3 +1,4 @@
+import { BeamLoading } from "./components/BeamLoading";
 import { lazy, Suspense, useCallback, useEffect, useRef, useState } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import "tdesign-react/es/_util/react-19-adapter";
@@ -10,12 +11,12 @@ import { setAppTimezone } from "./utils/date";
 import { AppLayout } from "./layouts";
 import { DEFAULT_ROUTE_ID, isRouteId, routeIdFromPath, routePath, routeTitle, type RouteId } from "./router";
 import { LoginPage, ChangePasswordPage } from "./pages/auth";
-const ExpensesPage = lazy(() => import("./pages/expenses"));
+import ExpensesPage from "./pages/expenses";
-const DashboardPage = lazy(() => import("./pages/dashboard"));
+import DashboardPage from "./pages/dashboard";
-const TrashPage = lazy(() => import("./pages/trash").then(module => ({ default: module.TrashPage })));
+import { TrashPage } from "./pages/trash";
-const AdminsPage = lazy(() => import("./pages/admins").then(module => ({ default: module.AdminsPage })));
+import { AdminsPage } from "./pages/admins";
-const AuditPage = lazy(() => import("./pages/audit").then(module => ({ default: module.AuditPage })));
+import { AuditPage } from "./pages/audit";
-const UpdatePage = lazy(() => import("./pages/update").then(module => ({ default: module.UpdatePage })));
+import { UpdatePage } from "./pages/update";
 import { UnsavedChangesProvider, useUnsavedActions } from "./contexts/UnsavedChanges";
 import { useDialogAccessibility } from "./hooks/useDialogAccessibility";
 import "./styles/theme.css";
@@ -31,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
+    // Keep notices in the lower-right safe area so they do not compete with
-    // item offset at zero avoids pushing narrow-screen notices off canvas.
+    // the header controls or obscure the page title.
-    const options = { content: message, duration: 4200, placement: "top-right" as const, offset: [0, 76] as [number, number], zIndex: 5000 };
+    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);
   }, []);
@@ -87,10 +88,10 @@ function App() {
   // Keep the login form mounted for those requests so the user sees the
   // button's busy state instead of losing the entire form to a bootstrap
   // spinner. `bootstrapRequestId` is only set by the initial session check.
-  if (isSessionBootstrapping(session)) return <main className="tn-auth-shell" role="status" aria-live="polite"><Loading text="正在连接本地账本…" /></main>;
+  if (isSessionBootstrapping(session)) return <main className="tn-auth-shell" role="status" aria-live="polite"><BeamLoading text="正在进入系统…" /></main>;
-  if (session.status === "error") return <main className="tn-auth-shell"><div className="tn-auth-panel"><h1 className="tn-page-title">无法连接 TallyNote</h1><p className="tn-page-subtitle">{session.error || "请确认本地服务正在运行。"}</p><Button theme="primary" onClick={() => void dispatch(bootstrapSession())}>重新连接</Button></div></main>;
+  if (session.status === "error") return <main className="tn-auth-shell"><div className="tn-auth-panel"><h1 className="tn-page-title">无法连接服务</h1><p className="tn-page-subtitle">{session.error || "服务暂时无法连接，请稍后重试或检查网络状态。"}</p><Button theme="primary" onClick={() => void dispatch(bootstrapSession())}>重新连接</Button></div></main>;
   if (!session.admin) return <LoginPage
-    notice={session.initialized ? undefined : "首次安装还差一步：请在服务器执行 sudo tallynote-admin-init 创建管理员账号。"}
+    notice={session.initialized ? undefined : "系统尚未初始化管理员账号，请联系系统管理员完成初始配置后登录。"}
     onSuccess={() => setPasswordOpen(false)}
   />;
   if (session.admin.mustChangePassword) return <ChangePasswordPage admin={session.admin} firstLogin onSuccess={() => notify("密码已更新", "success")} />;
@@ -104,7 +105,7 @@ function App() {
     : page === "audit" ? <AuditPage timezone={session.timezone} />
     : <UpdatePage timezone={session.timezone} notify={notify} />;
 
-  return <AppLayout activeId={page} adminName={session.admin.displayName} adminUsername={session.admin.username} onNavigate={onNavigate} onLogout={onLogout} onOpenPassword={() => { if (!passwordOpen) requestDiscard(() => setPasswordOpen(true)); }}><Suspense fallback={<main className="tn-page-loading" role="status" aria-live="polite"><Loading text="正在打开页面…" /></main>}><div key={passwordOpen ? "password" : page} className="tn-page-transition">{content}</div></Suspense></AppLayout>;
+  return <AppLayout activeId={page} adminName={session.admin.displayName} adminUsername={session.admin.username} onNavigate={onNavigate} onLogout={onLogout} onOpenPassword={() => { if (!passwordOpen) requestDiscard(() => setPasswordOpen(true)); }}><Suspense fallback={<main className="tn-page-loading" role="status" aria-live="polite"><BeamLoading text="页面加载中…" /></main>}><div key={passwordOpen ? "password" : page} className="tn-page-transition">{content}</div></Suspense></AppLayout>;
 }
 
 function RouteErrorPage() {

web-next/src/pages/admins/AdminsPage.tsx

@@ -77,18 +77,18 @@ export default function AdminsPage({ currentAdmin, timezone = "Asia/Shanghai", n
     { colKey: "status", title: "状态", cell: ({ row }: any) => <StatusTag status={row.status} /> },
     { colKey: "lastLoginAt", title: "最近登录", cell: ({ row }: any) => row.lastLoginAt ? dateText(row.lastLoginAt, timezone) : "从未登录" },
     { colKey: "version", title: "版本", cell: ({ row }: any) => <span className="tn-code">v{row.version}</span> },
-    { colKey: "actions", title: "操作", width: 250, cell: ({ row }: any) => <Space className="tn-action-group"><Tooltip content={row.id === currentAdmin.id ? "当前账号请使用右上角修改密码" : "生成一次性临时密码"}><Button variant="outline" onClick={() => setAction({ kind: "reset", admin: row })} disabled={busy || row.id === currentAdmin.id} icon={<KeyRound size={15} />}>重置密码</Button></Tooltip><Button variant="outline" theme={row.status === "active" ? "danger" : "primary"} onClick={() => setAction({ kind: "toggle", admin: row })} disabled={busy || row.id === currentAdmin.id} icon={row.status === "active" ? <UserRoundX size={15} /> : <UserRoundCheck size={15} />}>{row.status === "active" ? "停用" : "启用"}</Button></Space> },
+    { colKey: "actions", title: "操作", width: 250, cell: ({ row }: any) => <Space className="tn-action-group"><Tooltip content={row.id === currentAdmin.id ? "当前账号请在个人菜单中修改密码" : "重置并生成临时登录密码"}><Button variant="outline" onClick={() => setAction({ kind: "reset", admin: row })} disabled={busy || row.id === currentAdmin.id} icon={<KeyRound size={15} />}>重置密码</Button></Tooltip><Button variant="outline" theme={row.status === "active" ? "danger" : "primary"} onClick={() => setAction({ kind: "toggle", admin: row })} disabled={busy || row.id === currentAdmin.id} icon={row.status === "active" ? <UserRoundX size={15} /> : <UserRoundCheck size={15} />}>{row.status === "active" ? "停用" : "启用"}</Button></Space> },
   ];
 
-  return <Page title="管理员" subtitle="多个等权管理员共享同一本地账目，停用会立即撤销该账号的现有会话。" actions={<Space><Button variant="outline" onClick={() => void load()} disabled={loading} icon={<RotateCcw size={15} />}>刷新</Button><Button theme="primary" onClick={() => { setForm({ username: "", displayName: "" }); setFormError(""); setFormFields({}); setShowCreate(true); }} icon={<Plus size={16} />}>新增管理员</Button></Space>}>
+  return <Page title="管理员" subtitle="管理员协同维护团队账单与报销凭据，停用后将立即限制该账号访问并注销其登录会话。" actions={<Space><Button variant="outline" onClick={() => void load()} disabled={loading} icon={<RotateCcw size={15} />}>刷新</Button><Button theme="primary" onClick={() => { setForm({ username: "", displayName: "" }); setFormError(""); setFormFields({}); setShowCreate(true); }} icon={<Plus size={16} />}>新增管理员</Button></Space>}>
     <AsyncState loading={loading} error={error} empty={items.length === 0 ? <div className="tn-empty"><UserRound size={30} /><p>暂无管理员</p></div> : undefined} onRetry={() => void load()}><div className="tn-table-wrap" role="region" aria-label="管理员列表，可横向滚动查看更多列"><Table rowKey="id" data={items} columns={columns as any} hover stripe /></div></AsyncState>
     <Drawer className="tn-content-drawer tn-admin-drawer" visible={showCreate} destroyOnClose placement="right" size="440px" header="新增管理员" onClose={() => { if (!busy) requestDiscard(() => setShowCreate(false)); }} footer={<Space><Button variant="outline" onClick={() => requestDiscard(() => setShowCreate(false))} disabled={busy}>取消</Button><Button theme="primary" type="button" onClick={() => void create()} disabled={busy} icon={busy ? <BusyIcon /> : <ShieldCheck size={15} />}>创建并生成临时密码</Button></Space>}>
       <Form id="admin-create-form" layout="vertical" onSubmit={() => { void create(); }}><Form.FormItem label="用户名" help={formFields.username || "至少 3 个字符"} status={formFields.username ? "error" : undefined} rules={[{ required: true, min: 3, max: 64, message: "用户名至少需要 3 个字符" }]}><AccessibleInput disabled={busy} inputAriaLabel="用户名" inputAriaInvalid={Boolean(formFields.username)} value={form.username} onChange={value => { setForm({ ...form, username: value }); setFormFields(current => ({ ...current, username: undefined })); setFormError(""); }} onEnter={(_, context) => { context.e.preventDefault(); void create(); }} maxlength={64} autocomplete="off" /></Form.FormItem><Form.FormItem label="显示名" help={formFields.displayName} status={formFields.displayName ? "error" : undefined} rules={[{ required: true, max: 80, message: "请输入显示名" }]}><AccessibleInput disabled={busy} inputAriaLabel="显示名" inputAriaInvalid={Boolean(formFields.displayName)} value={form.displayName} onChange={value => { setForm({ ...form, displayName: value }); setFormFields(current => ({ ...current, displayName: undefined })); setFormError(""); }} onEnter={(_, context) => { context.e.preventDefault(); void create(); }} maxlength={80} /></Form.FormItem>{formError && <div className="tn-inline-error" role="alert">{formError}</div>}</Form>
     </Drawer>
-    <Dialog visible={Boolean(action)} header={action?.kind === "reset" ? "重置管理员密码？" : action?.admin.status === "active" ? "停用管理员？" : "启用管理员？"} confirmBtn={{ content: action?.kind === "reset" ? "重置密码" : action?.admin.status === "active" ? "停用" : "启用", theme: action?.kind === "toggle" && action.admin.status === "active" ? "danger" : "primary", loading: busy, disabled: busy }} cancelBtn="取消" onClose={() => { if (!busy) setAction(null); }} onConfirm={() => void (action?.kind === "reset" ? reset() : toggle())} onCancel={() => { if (!busy) setAction(null); }}>
+    <Dialog width="540px" visible={Boolean(action)} header={action?.kind === "reset" ? "重置管理员密码？" : action?.admin.status === "active" ? "停用管理员？" : "启用管理员？"} confirmBtn={{ content: action?.kind === "reset" ? "重置密码" : action?.admin.status === "active" ? "停用" : "启用", theme: action?.kind === "toggle" && action.admin.status === "active" ? "danger" : "primary", loading: busy, disabled: busy }} cancelBtn="取消" onClose={() => { if (!busy) setAction(null); }} onConfirm={() => void (action?.kind === "reset" ? reset() : toggle())} onCancel={() => { if (!busy) setAction(null); }}>
-      {action?.kind === "reset" ? <>将生成一次性临时密码，并立即使“{action.admin.displayName}”的现有会话失效。</> : action?.admin.status === "active" ? "停用后该管理员的现有会话会立即失效。" : "启用后该管理员可以重新登录。"}
+      {action?.kind === "reset" ? <>将生成一次性临时密码，同时让管理员“{action.admin.displayName}”已登录的会话安全退出。</> : action?.admin.status === "active" ? "停用后该管理员将无法访问系统，已登录的会话会立即注销。" : "启用后该管理员可恢复系统访问并正常登录。"}
     </Dialog>
-    <Dialog visible={Boolean(secret)} header="临时密码已生成" confirmBtn="关闭" cancelBtn={null} onClose={() => setSecret("")} onConfirm={() => setSecret("")} onCancel={() => setSecret("")}><div className="tn-secret"><code>{secret}</code><Button variant="outline" icon={<Copy size={15} />} onClick={() => { void copySecret(secret); }}>复制</Button></div><p className="tn-dialog-note">请通过安全渠道交给管理员。首次登录必须修改密码。</p></Dialog>
+    <Dialog width="540px" visible={Boolean(secret)} header="临时密码已生成" confirmBtn="关闭" cancelBtn={null} onClose={() => setSecret("")} onConfirm={() => setSecret("")} onCancel={() => setSecret("")}><div className="tn-secret"><code>{secret}</code><Button variant="outline" icon={<Copy size={15} />} onClick={() => { void copySecret(secret); }}>复制</Button></div><p className="tn-dialog-note">请妥善保管并将临时密码交付给管理员，该密码在首次登录时会被强制更新。</p></Dialog>
   </Page>;
 
   async function copySecret(value: string) {

web-next/src/pages/audit/AuditPage.tsx

@@ -23,7 +23,7 @@ const ACTION_LABELS: Record<string, string> = {
   "auth.login_failed": "登录失败",
   "expense.created": "创建账目",
   "expense.updated": "更新账目",
-  "expense.status_changed": "切换报销状态",
+  "expense.status_changed": "更新报销状态",
   "expense.trashed": "移入回收站",
   "expense.restored": "恢复账目",
   "expense.purged": "永久删除账目",
@@ -133,8 +133,8 @@ export default function AuditPage({ timezone = "Asia/Shanghai" }: { timezone?: s
     { colKey: "outcome", title: "结果", cell: ({ row }: any) => <Tag theme={row.outcome === "success" || !row.outcome ? "success" : row.outcome === "denied" ? "warning" : "danger"}>{outcomeLabel(row.outcome)}</Tag> },
   ];
 
-  return <Page title="审计日志" subtitle="记录登录、账目、附件、导出、管理员和更新操作。日志只读，永久删除也不会清除它。" actions={<Button variant="outline" onClick={() => void load()} disabled={loading || loadingMore} icon={<RotateCcw size={15} />}>刷新</Button>}>
+  return <Page title="审计日志" subtitle="全量记录系统鉴权、账目变更、凭证管理、数据导出与维护行为，审计日志严格只读留存，确保财务追溯合规。" actions={<Button variant="outline" onClick={() => void load()} disabled={loading || loadingMore} icon={<RotateCcw size={15} />}>刷新</Button>}>
-    <form className="tn-toolbar tn-audit-toolbar" onSubmit={e => { e.preventDefault(); applyFilters(); }}><AccessibleInput inputAriaLabel="动作筛选" value={actionDraft} onChange={setActionDraft} maxlength={100} placeholder="动作，例如 expense.created" prefixIcon={<Search size={16} />} /><Select aria-label="目标类型" value={targetDraft} onChange={v => setTargetDraft(String(v))} options={[{ label: "全部目标", value: "" }, { label: "账目", value: "expense" }, { label: "管理员", value: "admin" }, { label: "导出", value: "export" }, { label: "会话", value: "session" }, { label: "更新任务", value: "update" }, { label: "系统检查", value: "system" }]} /><Button theme="primary" type="submit" icon={<Search size={15} />}>筛选</Button></form>
+    <form className="tn-toolbar tn-audit-toolbar" onSubmit={e => { e.preventDefault(); applyFilters(); }}><AccessibleInput inputAriaLabel="动作筛选" value={actionDraft} onChange={setActionDraft} maxlength={100} placeholder="输入操作行为筛选" prefixIcon={<Search size={16} />} /><Select aria-label="目标类型" value={targetDraft} onChange={v => setTargetDraft(String(v))} options={[{ label: "全部目标", value: "" }, { label: "账目", value: "expense" }, { label: "管理员", value: "admin" }, { label: "导出", value: "export" }, { label: "会话", value: "session" }, { label: "更新任务", value: "update" }, { label: "系统检查", value: "system" }]} /><Button theme="primary" type="submit" icon={<Search size={15} />}>筛选</Button></form>
     <AsyncState loading={loading} error={error} empty={items.length === 0 ? <div className="tn-empty"><Archive size={30} /><p>{action || targetType ? "没有符合当前筛选条件的审计记录" : "暂无审计记录"}</p>{(action || targetType) && <Button variant="outline" onClick={() => setSearchParams(new URLSearchParams())}>清除筛选</Button>}</div> : undefined} onRetry={() => void load()}><div className="tn-table-wrap tn-audit-table" role="region" aria-label="审计日志列表，可横向滚动查看更多列"><Table rowKey="id" data={items} columns={columns as any} hover stripe /></div>{hasMore && <div className="tn-table-more"><Button variant="outline" onClick={() => void load(true)} disabled={loadingMore} icon={<RotateCcw size={15} />}>{loadingMore ? "加载中…" : "加载更早记录"}</Button></div>}</AsyncState>
   </Page>;
 }

web-next/src/pages/auth/ChangePasswordPage.tsx

@@ -108,14 +108,14 @@ export default function ChangePasswordPage({ admin, onSuccess, onCancel, returnL
   </section>;
 
   if (!isFirstLogin) {
-    return <Page title="修改密码" subtitle="更新当前管理员的登录凭据。" actions={onCancel ? <Button variant="text" type="button" onClick={onCancel} icon={<ArrowLeft size={16} />}>{returnLabel}</Button> : undefined} className="tn-password-page">{panel}</Page>;
+    return <Page title="修改密码" subtitle="定期更新管理员账户登录密码，保障财务数据访问安全。" actions={onCancel ? <Button variant="text" type="button" onClick={onCancel} icon={<ArrowLeft size={16} />}>{returnLabel}</Button> : undefined} className="tn-password-page">{panel}</Page>;
   }
 
   return <main className="tn-login-page" data-page="change-password">
     <section className="tn-login-container tn-password-container">
       <div className="tn-login-heading">
-        <h1 id="password-title" className="tn-login-title">首次登录保护</h1>
+        <h1 id="password-title" className="tn-login-title">初始安全设置</h1>
-        <p className="tn-login-subtitle">管理员 {displayName} 需要先设置新密码。</p>
+        <p className="tn-login-subtitle">欢迎使用系统，管理员 {displayName}，为保障账户安全，首次登录请先设置新密码。</p>
       </div>
       {panel}
     </section>

web-next/src/pages/auth/LoginPage.tsx

@@ -76,7 +76,7 @@ export default function LoginPage({ notice, onSuccess }: LoginPageProps) {
     <main className="tn-login-page" data-page="login">
       <section className="tn-login-container" aria-labelledby="login-title">
         <div className="tn-login-heading">
-          <h1 id="login-title" className="tn-login-title">登录到 <span className="tn-login-title-brand">TallyNote</span></h1>
+          <h1 id="login-title" className="tn-login-title">登录 <span className="tn-login-title-brand">TallyNote</span> 工作台</h1>
         </div>
 
         <Form

web-next/src/pages/common.tsx

@@ -1,3 +1,4 @@
+import { BeamLoading, BeamBar } from "../components/BeamLoading";
 import type { ReactNode } from "react";
 import { AlertCircle, Loader2 } from "lucide-react";
 import { Alert, Button, Card, Loading, Space, Tag } from "tdesign-react";
@@ -26,10 +27,10 @@ export function AsyncState({ loading, error, empty, onRetry, children }: {
   onRetry?: () => void;
   children: ReactNode;
 }) {
-  if (loading && empty) return <div className="tn-empty" role="status" aria-live="polite"><Loading text="加载中…" /></div>;
+  if (loading && empty) return <div className="tn-empty" role="status" aria-live="polite"><BeamLoading text="数据加载中…" /></div>;
   if (error && empty) return <div className="tn-empty" role="alert"><AlertCircle size={28} /><p>{error}</p>{onRetry && <Button variant="outline" onClick={onRetry}>重试</Button>}</div>;
   return <>
-    {loading && <div className="tn-inline-loading" role="status"><Loader2 size={15} className="tn-spin" aria-hidden="true" />正在更新…</div>}
+    {loading && <div className="tn-inline-loading" role="status"><BeamBar className="tn-beam-bar-sm" /> 正在同步…</div>}
     {error && <ErrorBanner message={error} onRetry={onRetry} />}
     {empty || children}
   </>;

web-next/src/pages/dashboard/DashboardPage.tsx

@@ -1,3 +1,4 @@
+import { BeamLoading } from "../../components/BeamLoading";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { AlertCircle, ChevronLeft, ChevronRight, RefreshCw } from "lucide-react";
 import { Alert, Button, Card, DatePicker, Empty, Loading, Space, Statistic, Table, Tag, Tooltip } from "tdesign-react";
@@ -17,6 +18,8 @@ echarts.use([LineChart, GridComponent, LegendComponent, TooltipComponent, Canvas
 type Props = { timezone?: string; onNavigate?: (id: RouteId, search?: string) => void };
 type ExpenseResult = { items: Expense[]; summary: { count: number; amountCents: number } };
 
+let dashboardCache: { month: string; unreimbursed: ExpenseResult; reimbursed: ExpenseResult } | null = null;
+
 function prefersReducedMotion(): boolean {
   return typeof window !== "undefined" && typeof window.matchMedia === "function"
     ? window.matchMedia("(prefers-reduced-motion: reduce)").matches
@@ -28,11 +31,12 @@ export default function DashboardPage({ timezone = "Asia/Shanghai", onNavigate }
   const rawMonthParam = searchParams.get("month");
   const defaultMonth = monthNow(timezone);
   const month = rawMonthParam && /^\d{4}-(0[1-9]|1[0-2])$/.test(rawMonthParam) ? rawMonthParam : defaultMonth;
-  const [unreimbursed, setUnreimbursed] = useState<ExpenseResult>({ items: [], summary: { count: 0, amountCents: 0 } });
+  const isCached = dashboardCache?.month === month;
-  const [reimbursed, setReimbursed] = useState<ExpenseResult>({ items: [], summary: { count: 0, amountCents: 0 } });
+  const [unreimbursed, setUnreimbursed] = useState<ExpenseResult>(() => (isCached ? dashboardCache!.unreimbursed : { items: [], summary: { count: 0, amountCents: 0 } }));
-  const [loading, setLoading] = useState(true);
+  const [reimbursed, setReimbursed] = useState<ExpenseResult>(() => (isCached ? dashboardCache!.reimbursed : { items: [], summary: { count: 0, amountCents: 0 } }));
+  const [loading, setLoading] = useState(() => !isCached);
   const [error, setError] = useState("");
-  const [loadedMonth, setLoadedMonth] = useState<string | null>(null);
+  const [loadedMonth, setLoadedMonth] = useState<string | null>(() => (isCached ? month : null));
   const requestSequence = useRef(0);
   const [reducedMotion, setReducedMotion] = useState(prefersReducedMotion);
 
@@ -74,6 +78,7 @@ export default function DashboardPage({ timezone = "Asia/Shanghai", onNavigate }
       setUnreimbursed(pending);
       setReimbursed(done);
       setLoadedMonth(month);
+      dashboardCache = { month, unreimbursed: pending, reimbursed: done };
     } catch (caught) {
       if (sequence === requestSequence.current) setError((caught as Error).message);
     } finally {
@@ -140,7 +145,7 @@ export default function DashboardPage({ timezone = "Asia/Shanghai", onNavigate }
       <div className="tn-page-actions"><div className="tn-dashboard-actions"><div className="tn-dashboard-month-control"><Tooltip content="上个月"><Button variant="outline" shape="square" onClick={() => shiftMonth(-1)} aria-label="上个月" icon={<ChevronLeft size={16} />} /></Tooltip><DatePicker className="tn-dashboard-month" mode="month" format="YYYY-MM" value={month} onChange={(value: any) => { const next = String(value || "").slice(0, 7); if (/^\d{4}-\d{2}$/.test(next)) setDashboardMonth(next); }} inputProps={{ "aria-label": "仪表盘月份" } as any} /><Tooltip content="下个月"><Button variant="outline" shape="square" onClick={() => shiftMonth(1)} aria-label="下个月" icon={<ChevronRight size={16} />} /></Tooltip></div><div className="tn-dashboard-secondary-actions"><Button className="tn-dashboard-refresh" variant="outline" onClick={() => void load()} disabled={loading} icon={<RefreshCw size={15} />}>刷新</Button><Button className="tn-dashboard-view" theme="primary" onClick={() => onNavigate?.("expenses", expensesSearch)}>查看账目</Button></div></div></div>
     </div>
     {error && hasCurrentSnapshot && <Alert theme="error" icon={<AlertCircle size={16} />} message={`刷新失败：${error}。当前展示的是本月最近一次成功加载的数据。`} />}
-    {loading ? <div className="tn-empty" role="status" aria-live="polite"><Loading text="加载仪表盘…" /></div> : !hasCurrentSnapshot ? <div className="tn-empty" role="alert"><Alert theme="error" icon={<AlertCircle size={16} />} message={error || "暂时无法读取仪表盘数据"} /><Button variant="outline" onClick={() => void load()} icon={<RefreshCw size={15} />}>重新加载</Button></div> : <>
+    {loading && !hasCurrentSnapshot ? <div className="tn-empty" role="status" aria-live="polite"><BeamLoading text="正在汇总本月数据…" /></div> : !hasCurrentSnapshot ? <div className="tn-empty" role="alert"><Alert theme="error" icon={<AlertCircle size={16} />} message={error || "暂时无法读取仪表盘数据"} /><Button variant="outline" onClick={() => void load()} icon={<RefreshCw size={15} />}>重新加载</Button></div> : <>
       <div className="tn-dashboard-stats">
         <Card bordered className="tn-dashboard-stat tn-dashboard-stat-total"><Statistic title="本月总额" value={totalCents / 100} prefix="¥" decimalPlaces={2} /></Card>
         <Card bordered className="tn-dashboard-stat tn-dashboard-stat-count"><Statistic title="账目笔数" value={totalCount} suffix="笔" /></Card>

web-next/src/pages/expenses/ExpenseDetail.tsx

@@ -1,3 +1,4 @@
+import { BeamLoading } from "../../components/BeamLoading";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { AlertCircle, ArrowDownToLine, FileText, Image as ImageIcon, Loader2, Search, Settings, Trash2, X } from "lucide-react";
 import { Button, Dialog, Drawer, Loading, Space, Tag, Textarea, Tooltip } from "tdesign-react";
@@ -10,7 +11,7 @@ type Props = { expense: Expense; timezone?: string; onClose: () => void; onUpdat
 const TIMELINE_LABELS: Record<string, string> = {
   "expense.created": "创建账目",
   "expense.updated": "更新账目",
-  "expense.status_changed": "切换报销状态",
+  "expense.status_changed": "更新报销状态",
   "expense.trashed": "移入回收站",
   "expense.restored": "从回收站恢复",
   "attachment.added": "添加附件",
@@ -49,7 +50,7 @@ export default function ExpenseDetail({ expense, timezone = "Asia/Shanghai", onC
     const current = (caught.details as { current?: Expense } | undefined)?.current;
     if (!current) return false;
     setDetail(current);
-    setMessage("这笔账目刚被其他管理员修改，已加载最新版本，请确认后重试。");
+    setMessage("此笔账目已被其他管理员更新，已为您自动同步最新记录，请确认后重试。");
     return true;
   };
   const updateStatus = async () => { setBusy(true); try { const next = detail.status === "reimbursed" ? "unreimbursed" : "reimbursed"; const result = await api<{ expense: Expense }>(`/api/expenses/${detail.id}/status`, { method: "POST", body: JSON.stringify({ status: next, version: detail.version }) }); setDetail(result.expense); setAction(null); notify?.(next === "reimbursed" ? "已标记为已报销" : "已改回未报销", "success"); onUpdated(); } catch (caught) { if (!recoverConflict(caught, setError)) setError((caught as Error).message); setAction(null); } finally { setBusy(false); } };
@@ -57,16 +58,16 @@ export default function ExpenseDetail({ expense, timezone = "Asia/Shanghai", onC
   const remove = async () => { if (!removeTarget) return; const requires = removeTarget.kind === "invoice" && detail.invoiceCount <= 1 && !detail.invoiceMissingReason?.trim(); if (requires && !removeReason.trim()) { setRemoveError("请填写无发票原因"); return; } setBusy(true); setRemoveError(""); try { const body: { version: number; invoiceMissingReason?: string } = { version: detail.version }; if (requires) body.invoiceMissingReason = removeReason.trim(); const result = await api<{ expense: Expense }>(`/api/attachments/${removeTarget.id}`, { method: "DELETE", body: JSON.stringify(body) }); setDetail(result.expense); setRemoveTarget(null); notify?.("附件已删除", "success"); onUpdated(); } catch (caught) { if (!recoverConflict(caught, setRemoveError)) setRemoveError((caught as Error).message); } finally { setBusy(false); } };
   return <>
     <Drawer className="tn-content-drawer tn-detail-drawer" placement="right" size="520px" visible destroyOnClose header="账目详情" onClose={onClose} footer={<Space><Button onClick={() => setAction("status")} disabled={busy}>{detail.status === "reimbursed" ? "标记未报销" : "标记已报销"}</Button><Button theme="danger" onClick={() => setAction("trash")} disabled={busy}><Trash2 size={15} />移入回收站</Button></Space>}>
-      {loading ? <div role="status" aria-live="polite"><Loading text="加载详情…" /></div> : error ? <div role="alert" className="expense-error"><AlertCircle size={16} />{error}<Button variant="text" onClick={load}>重试</Button></div> : <div className="expense-detail">
+      {loading ? <div className="tn-drawer-loading-wrap" role="status" aria-live="polite"><BeamLoading text="正在加载账目详情…" /></div> : error ? <div role="alert" className="expense-error"><AlertCircle size={16} />{error}<Button variant="text" onClick={load}>重试</Button></div> : <div className="expense-detail">
         <div className="expense-detail-head"><strong>{money(detail.amountCents)}</strong><Button variant="outline" onClick={() => onRequestEdit(detail)}><Settings size={15} />编辑</Button></div>
         <dl><div><dt>支付时间</dt><dd>{dateText(detail.paidAt, timezone)}</dd></div><div><dt>发票</dt><dd>{detail.invoiceCount > 0 ? `${detail.invoiceCount} 张` : detail.invoiceMissingReason ? <><Tag theme="warning">无发票</Tag>：{detail.invoiceMissingReason}</> : <Tag theme="danger">未说明</Tag>}</dd></div><div><dt>状态</dt><dd><Tag theme={detail.status === "reimbursed" ? "success" : "warning"}>{detail.status === "reimbursed" ? "已报销" : "未报销"}</Tag></dd></div><div><dt>备注</dt><dd>{detail.note || "无"}</dd></div></dl>
         <h3>附件 <small>{detail.attachments?.length || 0}</small></h3><div className="expense-attachments">{(detail.attachments || []).map(a => { const protectsLastProof = a.kind === "payment_proof" && detail.paymentProofCount <= 1; return <div className="expense-attachment" key={a.id}><span title={a.originalName}>{a.mimeType.startsWith("image/") ? <ImageIcon size={16} /> : <FileText size={16} />} {a.originalName}<small>{formatBytes(a.sizeBytes)}</small></span><Space>{a.previewable && <Tooltip content="预览附件" placement="left"><Button variant="text" shape="circle" onClick={() => setPreview(a)} aria-label={`预览 ${a.originalName}`}><Search size={15} /></Button></Tooltip>}<Tooltip content="下载附件" placement="left"><Button variant="text" shape="circle" onClick={() => { window.location.href = `/api/attachments/${a.id}/content?download=1`; }} aria-label={`下载 ${a.originalName}`}><ArrowDownToLine size={15} /></Button></Tooltip><Tooltip content={protectsLastProof ? "至少保留一张付款凭证" : "删除附件"} placement="left"><Button variant="text" shape="circle" theme="danger" disabled={protectsLastProof} onClick={() => { setRemoveReason(""); setRemoveError(""); setRemoveTarget(a); }} aria-label={protectsLastProof ? `不可删除最后一张付款凭证 ${a.originalName}` : `删除 ${a.originalName}`}><Trash2 size={14} /></Button></Tooltip></Space></div>; })}</div>
         {timeline.length > 0 && <><h3>操作记录</h3><div className="expense-timeline">{timeline.slice(0, 12).map(t => <div key={t.id}><span>{dateText(t.occurredAt, timezone)}</span><strong title={t.action}>{TIMELINE_LABELS[t.action] || t.action}</strong><small>{t.actorUsername || "系统"}</small></div>)}</div></>}
       </div>}
     </Drawer>
-    <Dialog visible={action === "status"} header={detail.status === "reimbursed" ? "改回未报销？" : "标记为已报销？"} confirmBtn={{ content: "确认变更", loading: busy, disabled: busy }} cancelBtn="取消" onClose={() => { if (!busy) setAction(null); }} onConfirm={() => void updateStatus()} onCancel={() => { if (!busy) setAction(null); }}>{detail.status === "reimbursed" ? "这笔账目会重新出现在未报销列表。" : "确认这笔账目已完成报销，并从未报销列表移出？"}</Dialog>
+    <Dialog width="540px" visible={action === "status"} header={detail.status === "reimbursed" ? "改回未报销？" : "标记为已报销？"} confirmBtn={{ content: "确认变更", loading: busy, disabled: busy }} cancelBtn="取消" onClose={() => { if (!busy) setAction(null); }} onConfirm={() => void updateStatus()} onCancel={() => { if (!busy) setAction(null); }}>{detail.status === "reimbursed" ? "确认将该笔账目恢复为未报销状态？" : "确认该笔账目已完成报销审批与结算？"}</Dialog>
-    <Dialog visible={action === "trash"} header="移入回收站？" confirmBtn={{ content: "移入回收站", theme: "danger", loading: busy, disabled: busy }} cancelBtn="取消" onClose={() => { if (!busy) setAction(null); }} onConfirm={() => void trash()} onCancel={() => { if (!busy) setAction(null); }}>账目会从普通列表和导出结果中隐藏，附件会保留，可在回收站恢复。</Dialog>
+    <Dialog width="540px" visible={action === "trash"} header="移入回收站？" confirmBtn={{ content: "移入回收站", theme: "danger", loading: busy, disabled: busy }} cancelBtn="取消" onClose={() => { if (!busy) setAction(null); }} onConfirm={() => void trash()} onCancel={() => { if (!busy) setAction(null); }}>移入回收站后将不在正常列表中展示，关联附件会完整保留，可随时前往回收站恢复。</Dialog>
-    <Dialog visible={Boolean(removeTarget)} header="删除附件？" confirmBtn={{ content: "删除附件", theme: "danger", loading: busy, disabled: busy }} cancelBtn="取消" onClose={() => { if (!busy) setRemoveTarget(null); }} onConfirm={() => void remove()} onCancel={() => { if (!busy) setRemoveTarget(null); }}>{removeTarget && <><p>{removeTarget.kind === "payment_proof" ? "账目至少需要保留一张付款凭证。" : detail.invoiceCount <= 1 && !detail.invoiceMissingReason?.trim() ? "这是最后一张发票。删除后必须填写无发票原因。" : "将删除这张发票。"}</p>{removeTarget.kind === "invoice" && detail.invoiceCount <= 1 && !detail.invoiceMissingReason?.trim() && <Textarea disabled={busy} aria-label="无发票原因" aria-invalid={Boolean(removeError)} aria-describedby={removeError ? "remove-attachment-error" : undefined} value={removeReason} onChange={value => { setRemoveReason(value); setRemoveError(""); }} placeholder="例如：商家无法开具发票" maxlength={500} />}{removeError && <div id="remove-attachment-error" className="expense-error" role="alert"><AlertCircle size={16} />{removeError}</div>}</>}</Dialog>
+    <Dialog width="560px" visible={Boolean(removeTarget)} header="删除附件？" confirmBtn={{ content: "删除附件", theme: "danger", loading: busy, disabled: busy }} cancelBtn="取消" onClose={() => { if (!busy) setRemoveTarget(null); }} onConfirm={() => void remove()} onCancel={() => { if (!busy) setRemoveTarget(null); }}>{removeTarget && <><p>{removeTarget.kind === "payment_proof" ? "每笔账目至少需要保留一张有效的付款凭证。" : detail.invoiceCount <= 1 && !detail.invoiceMissingReason?.trim() ? "当前为该账目唯一的发票附件，删除后请补充说明无发票原因。" : "确认删除该发票附件？"}</p>{removeTarget.kind === "invoice" && detail.invoiceCount <= 1 && !detail.invoiceMissingReason?.trim() && <Textarea disabled={busy} aria-label="无发票原因" aria-invalid={Boolean(removeError)} aria-describedby={removeError ? "remove-attachment-error" : undefined} value={removeReason} onChange={value => { setRemoveReason(value); setRemoveError(""); }} placeholder="例如：商家无法开具发票" maxlength={500} />}{removeError && <div id="remove-attachment-error" className="expense-error" role="alert">{removeError}</div>}</>}</Dialog>
-    <Dialog visible={Boolean(preview)} header={preview?.originalName} onClose={() => setPreview(null)} cancelBtn="关闭" footer={null}>{preview && <div className="tn-preview">{preview.mimeType.startsWith("image/") ? <img src={`/api/attachments/${preview.id}/content`} alt={preview.originalName} /> : <iframe src={`/api/attachments/${preview.id}/content`} title={preview.originalName} />}</div>}</Dialog>
+    <Dialog width="880px" className="tn-dialog-xlarge" visible={Boolean(preview)} header={preview?.originalName} onClose={() => setPreview(null)} cancelBtn="关闭" footer={null}>{preview && <div className="tn-preview">{preview.mimeType.startsWith("image/") ? <img src={`/api/attachments/${preview.id}/content`} alt={preview.originalName} /> : <iframe src={`/api/attachments/${preview.id}/content`} title={preview.originalName} />}</div>}</Dialog>
   </>;
 }

web-next/src/pages/expenses/ExpenseDrawer.tsx

@@ -143,7 +143,7 @@ export default function ExpenseDrawer({ expense, timezone = "Asia/Shanghai", onC
         {error && <div role="alert" className="expense-error"><AlertCircle size={16} />{error}</div>}
       </form>
     </Drawer>
-    <Dialog visible={Boolean(conflict)} header="记录已被更新" confirmBtn="保留当前内容" cancelBtn="加载服务器版本" onClose={() => { setConflict(null); setError("冲突提示已关闭，请再次保存以重新确认最新版本。"); }} onConfirm={() => { if (conflict) { setVersion(conflict.version); setServerInvoiceCount(conflict.invoiceCount); setConflict(null); setError("当前内容已保留，请再次保存以覆盖服务器版本。"); } }} onCancel={() => { if (conflict) { setAmount((conflict.amountCents / 100).toFixed(2)); setNote(conflict.note); setPaidAt(dateInputValue(new Date(conflict.paidAt), timezone)); setVersion(conflict.version); setServerInvoiceCount(conflict.invoiceCount); setConflict(null); } }}>另一位管理员刚刚修改了这笔账目。请选择如何处理，系统不会静默覆盖。</Dialog>
+    <Dialog width="560px" visible={Boolean(conflict)} header="记录已被更新" confirmBtn="保留当前内容" cancelBtn="加载服务器版本" onClose={() => { setConflict(null); setError("已取消冲突提示，再次点击保存将重新确认最新数据。"); }} onConfirm={() => { if (conflict) { setVersion(conflict.version); setServerInvoiceCount(conflict.invoiceCount); setConflict(null); setError("已保留您当前编辑的内容，再次点击保存将更新此账目。"); } }} onCancel={() => { if (conflict) { setAmount((conflict.amountCents / 100).toFixed(2)); setNote(conflict.note); setPaidAt(dateInputValue(new Date(conflict.paidAt), timezone)); setVersion(conflict.version); setServerInvoiceCount(conflict.invoiceCount); setConflict(null); } }}>此笔账目已被其他管理员更新。为保障财务数据准确，请选择保留您当前的编辑并覆盖，或同步加载最新版本。</Dialog>
   </>;
 }
 function focusExpenseField(errors: Partial<Record<ExpenseField, string>>) {

web-next/src/pages/expenses/ExpensesPage.tsx

@@ -1,3 +1,4 @@
+import { BeamLoading } from "../../components/BeamLoading";
 import React, { useEffect, useMemo, useRef, useState } from "react";
 import { AlertCircle, ChevronLeft, ChevronRight, ClipboardList, FileDown, FileText, Pencil, Plus, RefreshCw, Search, Trash2, X } from "lucide-react";
 import { Button, Checkbox, DatePicker, Dialog, Loading, Radio, Space, Table, Tag, Tooltip } from "tdesign-react";
@@ -9,6 +10,8 @@ import AccessibleInput from "../../components/AccessibleInput";
 import { dateText, money, monthNow } from "./date";
 import type { Expense, Notify } from "./types";
 
+let expensesCache: { key: string; items: Expense[]; summary: { count: number; amountCents: number } } | null = null;
+
 type Props = { timezone?: string; notify?: Notify; sessionKey?: string };
 const EXPORT_JOB_STORAGE_KEY = "tallynote.exportJobId";
 
@@ -29,9 +32,14 @@ export default function ExpensesPage({ timezone: timezoneProp = "Asia/Shanghai",
   const query = rawQuery.slice(0, 200);
   const rawMissingInvoice = searchParams.get("missingInvoice");
   const missingInvoice = searchParams.get("missingInvoice") === "true";
-  const [queryDraft, setQueryDraft] = useState(query);
-  const [items, setItems] = useState<Expense[]>([]); const [summary, setSummary] = useState({ count: 0, amountCents: 0 }); const [loading, setLoading] = useState(false); const [error, setError] = useState(""); const [loadedFilterKey, setLoadedFilterKey] = useState<string | null>(null); const [selectedKeys, setSelectedKeys] = useState<string[]>([]); const [drawer, setDrawer] = useState<"new" | "detail" | "edit" | null>(null); const [selected, setSelected] = useState<Expense | null>(null); const [includeManifest, setIncludeManifest] = useState(false); const [exporting, setExporting] = useState<string | null>(() => savedExportJob(exportStorageKey)); const [exportIssue, setExportIssue] = useState(""); const [trashTarget, setTrashTarget] = useState<Expense | null>(null); const [trashing, setTrashing] = useState(false); const sequence = useRef(0); const exportStarting = useRef(false);
   const filterKey = `${month}|${status}|${query}|${missingInvoice ? "1" : "0"}`;
+  const isCached = expensesCache?.key === filterKey;
+  const [queryDraft, setQueryDraft] = useState(query);
+  const [items, setItems] = useState<Expense[]>(() => (isCached ? expensesCache!.items : []));
+  const [summary, setSummary] = useState(() => (isCached ? expensesCache!.summary : { count: 0, amountCents: 0 }));
+  const [loading, setLoading] = useState(() => !isCached);
+  const [error, setError] = useState("");
+  const [loadedFilterKey, setLoadedFilterKey] = useState<string | null>(() => (isCached ? filterKey : null)); const [selectedKeys, setSelectedKeys] = useState<string[]>([]); const [drawer, setDrawer] = useState<"new" | "detail" | "edit" | null>(null); const [selected, setSelected] = useState<Expense | null>(null); const [includeManifest, setIncludeManifest] = useState(false); const [exporting, setExporting] = useState<string | null>(() => savedExportJob(exportStorageKey)); const [exportIssue, setExportIssue] = useState(""); const [trashTarget, setTrashTarget] = useState<Expense | null>(null); const [trashing, setTrashing] = useState(false); const sequence = useRef(0); const exportStarting = useRef(false);
   useEffect(() => {
     const params = new URLSearchParams(searchParams);
     let changed = false;
@@ -54,8 +62,8 @@ export default function ExpensesPage({ timezone: timezoneProp = "Asia/Shanghai",
     if (next.missingInvoice ?? missingInvoice) params.set("missingInvoice", "true"); else params.delete("missingInvoice");
     setSearchParams(params);
   };
-  const load = async () => { const s = ++sequence.current; const requestedKey = filterKey; setLoading(true); setError(""); try { const result = await api<{ items: Expense[]; summary: typeof summary }>(`/api/expenses?month=${month}&status=${status}&query=${encodeURIComponent(query)}&missingInvoice=${missingInvoice}`); if (s === sequence.current) { setItems(result.items); setSummary(result.summary); setLoadedFilterKey(requestedKey); setSelectedKeys(keys => keys.filter(k => result.items.some(x => x.id === k))); } } catch (e) { if (s === sequence.current) { setItems([]); setSummary({ count: 0, amountCents: 0 }); setLoadedFilterKey(null); setError((e as Error).message); } } finally { if (s === sequence.current) setLoading(false); } };
+  const load = async () => { const s = ++sequence.current; const requestedKey = filterKey; setLoading(true); setError(""); try { const result = await api<{ items: Expense[]; summary: typeof summary }>(`/api/expenses?month=${month}&status=${status}&query=${encodeURIComponent(query)}&missingInvoice=${missingInvoice}`); if (s === sequence.current) { setItems(result.items); setSummary(result.summary); setLoadedFilterKey(requestedKey); setSelectedKeys(keys => keys.filter(k => result.items.some(x => x.id === k))); expensesCache = { key: requestedKey, items: result.items, summary: result.summary }; } } catch (e) { if (s === sequence.current) { setItems([]); setSummary({ count: 0, amountCents: 0 }); setLoadedFilterKey(null); setError((e as Error).message); } } finally { if (s === sequence.current) setLoading(false); } };
-  useEffect(() => { setSelectedKeys([]); setItems([]); setSummary({ count: 0, amountCents: 0 }); setLoadedFilterKey(null); void load(); }, [filterKey]);
+  useEffect(() => { setSelectedKeys([]); if (expensesCache?.key !== filterKey) { setItems([]); setSummary({ count: 0, amountCents: 0 }); setLoadedFilterKey(null); } void load(); }, [filterKey]);
   const selectedTotal = useMemo(() => items.filter(i => selectedKeys.includes(i.id)).reduce((sum, i) => sum + i.amountCents, 0), [items, selectedKeys]);
   const shiftMonth = (delta: number) => { const [rawYear, rawMonthNumber] = month.split("-").map(Number); const y = rawYear || new Date().getFullYear(); const m = rawMonthNumber || 1; const d = new Date(y, m - 1 + delta, 1); updateFilters({ month: `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}` }); };
   const rememberExportJob = (jobId: string | null) => {
@@ -92,14 +100,14 @@ export default function ExpensesPage({ timezone: timezoneProp = "Asia/Shanghai",
       } catch {
         if (disposed) return;
         failureCount += 1;
-        setExportIssue("网络连接不稳定，导出仍在后台进行，正在重新查询状态…");
+        setExportIssue("网络响应稍慢，数据导出仍在后台处理中，正在自动同步进度…");
         schedule(Math.min(1000 * (2 ** Math.min(failureCount, 3)), 8000));
       }
     };
     void poll();
     return () => { disposed = true; if (timer !== undefined) window.clearTimeout(timer); };
   }, [exporting, notify]);
-  const moveToTrash = async () => { if (!trashTarget) return; setTrashing(true); try { await api(`/api/expenses/${trashTarget.id}`, { method: "DELETE", body: JSON.stringify({ version: trashTarget.version }) }); notify?.("账目已移入回收站，可在回收站恢复", "success"); setTrashTarget(null); await load(); } catch (e) { notify?.((e as Error).message, "error"); } finally { setTrashing(false); } };
+  const moveToTrash = async () => { if (!trashTarget) return; setTrashing(true); try { await api(`/api/expenses/${trashTarget.id}`, { method: "DELETE", body: JSON.stringify({ version: trashTarget.version }) }); notify?.("账目已移入回收站，可随时在回收站恢复", "success"); setTrashTarget(null); await load(); } catch (e) { notify?.((e as Error).message, "error"); } finally { setTrashing(false); } };
   const columns = [
     { colKey: "row-select", type: "multiple" },
     { colKey: "paidAt", title: "支付时间", cell: ({ row }: any) => dateText(row.paidAt, timezone) },
@@ -122,10 +130,10 @@ export default function ExpensesPage({ timezone: timezoneProp = "Asia/Shanghai",
   return <div className="tn-page expenses-page"><div className="tn-page-head expenses-head"><div><h1 className="tn-page-title">账目列表</h1></div><div className="tn-page-actions"><Checkbox checked={includeManifest} onChange={setIncludeManifest}>包含 manifest.json</Checkbox><Button variant="outline" onClick={() => void exportAll()} disabled={Boolean(exporting) || (!selectedKeys.length && (!items.length || !dataReady))} icon={<FileDown size={16} />}>{exporting ? "导出中…" : selectedKeys.length ? `导出所选（${selectedKeys.length}）` : "导出筛选结果"}</Button><Button theme="primary" onClick={() => setDrawer("new")} icon={<Plus size={16} />}>新增账目</Button></div></div>
     <div className="tn-toolbar expenses-toolbar"><div className="tn-expense-month-controls"><Tooltip content="上个月"><Button variant="text" shape="square" onClick={() => shiftMonth(-1)} aria-label="上个月" icon={<ChevronLeft size={18} />} /></Tooltip><DatePicker className="tn-month-picker" mode="month" format="YYYY-MM" value={month} onChange={(value: any) => { const next = String(value || "").slice(0, 7); if (/^\d{4}-\d{2}$/.test(next)) updateFilters({ month: next }); }} placeholder="选择月份" inputProps={{ "aria-label": "账目月份" } as any} /><Tooltip content="下个月"><Button variant="text" shape="square" onClick={() => shiftMonth(1)} aria-label="下个月" icon={<ChevronRight size={18} />} /></Tooltip></div><Radio.Group className="tn-segmented" theme="button" variant="primary-filled" value={status} onChange={(value: any) => updateFilters({ status: value as "unreimbursed" | "reimbursed" })} aria-label="报销状态"><Radio.Button value="unreimbursed">未报销</Radio.Button><Radio.Button value="reimbursed">已报销</Radio.Button></Radio.Group><div className="tn-expense-search-controls"><AccessibleInput inputAriaLabel="搜索备注" className="tn-expense-search" value={queryDraft} onChange={setQueryDraft} onEnter={() => { if (queryDraft.trim() === query) void load(); else updateFilters({ query: queryDraft }); }} maxlength={200} placeholder="搜索备注" prefixIcon={<Search size={16} />} suffix={queryDraft ? <Tooltip content="清除搜索"><Button variant="text" shape="square" onClick={() => { setQueryDraft(""); updateFilters({ query: "" }); }} aria-label="清除搜索" icon={<X size={14} />} /></Tooltip> : undefined} /><Button variant="outline" onClick={() => { if (queryDraft.trim() === query) void load(); else updateFilters({ query: queryDraft }); }} disabled={loading} icon={<Search size={15} />}>搜索</Button></div><div className="tn-expense-filter-actions"><Checkbox checked={missingInvoice} onChange={checked => updateFilters({ missingInvoice: checked })}>缺发票</Checkbox><Tooltip content="刷新当前结果"><Button variant="outline" shape="square" onClick={() => void load()} disabled={loading} aria-label="刷新当前结果" icon={<RefreshCw size={15} />} /></Tooltip></div></div>
     <div className="tn-summary expenses-summary"><span>{summary.count} 笔</span><strong>{money(summary.amountCents)}</strong>{selectedKeys.length > 0 && <><span>已选 {selectedKeys.length} 笔，共 {money(selectedTotal)}</span><Button variant="text" onClick={() => setSelectedKeys([])}>清除选择</Button></>}</div>
-    {exportIssue && <div className="tn-export-status" role="status"><RefreshCw size={15} className="spin" /><span>{exportIssue}</span><Button variant="text" onClick={() => { setExportIssue(""); rememberExportJob(null); }}>停止等待</Button></div>}
+    {exportIssue && <div className="tn-export-status" role="status"><RefreshCw size={15} className="spin" /><span>{exportIssue}</span><Button variant="text" onClick={() => { setExportIssue(""); rememberExportJob(null); }}>关闭提示</Button></div>}
     {error && <div className="expense-error" role="alert"><AlertCircle size={16} />{error}<Button variant="text" onClick={() => void load()}>重试</Button></div>}
-    {error ? null : !dataReady || (loading && !items.length) ? <div className="tn-empty" role="status" aria-live="polite"><Loading text="加载中…" /></div> : !items.length ? emptyState : <div className="tn-table-wrap" role="region" aria-label="账目列表，可横向滚动查看更多列"><Table rowKey="id" data={items} columns={columns as any} selectedRowKeys={selectedKeys} onSelectChange={(keys: any[]) => setSelectedKeys(keys as string[])} hover stripe /></div>}
+    {error ? null : (!items.length && (loading || !dataReady)) ? <div className="tn-empty" role="status" aria-live="polite"><BeamLoading text="正在加载账目列表…" /></div> : !items.length ? emptyState : <div className="tn-table-wrap" role="region" aria-label="账目列表，可横向滚动查看更多列"><Table rowKey="id" data={items} columns={columns as any} selectedRowKeys={selectedKeys} onSelectChange={(keys: any[]) => setSelectedKeys(keys as string[])} hover stripe /></div>}
     {drawer === "new" && <ExpenseDrawer timezone={timezone} onClose={() => setDrawer(null)} onSaved={load} notify={notify} />}{drawer === "edit" && selected && <ExpenseDrawer timezone={timezone} expense={selected} onClose={() => setDrawer(null)} onSaved={load} notify={notify} />}{drawer === "detail" && selected && <ExpenseDetail timezone={timezone} expense={selected} onClose={() => setDrawer(null)} onUpdated={load} onRequestEdit={e => { setSelected(e); setDrawer("edit"); }} notify={notify} />}
-    {trashTarget && <Dialog visible header="移入回收站？" confirmBtn={{ content: "移入回收站", theme: "danger", loading: trashing, disabled: trashing }} cancelBtn="取消" onClose={() => { if (!trashing) setTrashTarget(null); }} onConfirm={() => void moveToTrash()} onCancel={() => { if (!trashing) setTrashTarget(null); }}>将“{trashTarget.note || `${dateText(trashTarget.paidAt, timezone)}的账目`}”移入回收站。它会从普通列表和导出结果中隐藏，附件会保留，可随时恢复。</Dialog>}
+    {trashTarget && <Dialog width="540px" visible header="移入回收站？" confirmBtn={{ content: "移入回收站", theme: "danger", loading: trashing, disabled: trashing }} cancelBtn="取消" onClose={() => { if (!trashing) setTrashTarget(null); }} onConfirm={() => void moveToTrash()} onCancel={() => { if (!trashing) setTrashTarget(null); }}>确认将“{trashTarget.note || `${dateText(trashTarget.paidAt, timezone)}的账目`}”移入回收站？移入后将不在正常列表中展示，关联附件将完整保留，可随时恢复。</Dialog>}
   </div>;
 }

web-next/src/pages/trash/TrashPage.tsx

@@ -53,12 +53,12 @@ export default function TrashPage({ timezone = "Asia/Shanghai", notify }: { time
     { colKey: "actions", title: "操作", width: 190, cell: ({ row }: any) => <Space className="tn-action-group"><Button variant="outline" onClick={() => void restore(row)} disabled={busy} icon={busy ? <BusyIcon /> : <RotateCcw size={15} />}>恢复</Button><Button theme="danger" variant="outline" onClick={() => { setPurgeTarget(row); setPassword(""); setPurgeError(""); }} disabled={busy} icon={<Trash2 size={15} />}>永久删除</Button></Space> },
   ];
 
-  return <Page title="回收站" subtitle="已删除的账目会保留附件，可恢复或经过密码确认后永久删除。" actions={<Button variant="outline" onClick={() => void load()} disabled={loading || busy} icon={<RotateCcw size={15} />}>刷新</Button>}>
+  return <Page title="回收站" subtitle="已标记删除的账目暂存于此，支持一键恢复或经安全验证后彻底清除。" actions={<Button variant="outline" onClick={() => void load()} disabled={loading || busy} icon={<RotateCcw size={15} />}>刷新</Button>}>
     <AsyncState loading={loading} error={error} empty={items.length === 0 ? <div className="tn-empty"><Trash2 size={30} /><p>回收站为空</p></div> : undefined} onRetry={() => void load()}>
       <div className="tn-table-wrap" role="region" aria-label="回收站账目列表，可横向滚动查看更多列"><Table rowKey="id" data={items} columns={columns as any} hover stripe /></div>
     </AsyncState>
-      <Dialog visible={Boolean(purgeTarget)} header="永久删除账目" confirmBtn={{ content: "永久删除", theme: "danger", loading: busy, disabled: busy }} cancelBtn="取消" onClose={() => { if (!busy) { setPurgeTarget(null); setPurgeError(""); } }} onConfirm={() => void purge()} onCancel={() => { if (!busy) { setPurgeTarget(null); setPurgeError(""); } }}>
+      <Dialog width="540px" visible={Boolean(purgeTarget)} header="永久删除账目" confirmBtn={{ content: "永久删除", theme: "danger", loading: busy, disabled: busy }} cancelBtn="取消" onClose={() => { if (!busy) { setPurgeTarget(null); setPurgeError(""); } }} onConfirm={() => void purge()} onCancel={() => { if (!busy) { setPurgeTarget(null); setPurgeError(""); } }}>
-      <p>此操作会移除账目和附件字节，完整审计内容仍会保留，且无法恢复。</p>
+      <p>此操作将永久清除该笔账目及其关联的所有凭证与发票附件，审计日志将予以留存，清除后不可恢复。</p>
       <p className="tn-dialog-note">请输入当前管理员密码确认。</p>
       <AccessibleInput inputAriaLabel="当前管理员密码" inputAriaInvalid={Boolean(purgeError)} inputAriaDescribedby={purgeError ? "trash-purge-error" : undefined} type="password" value={password} onChange={value => { setPassword(value); setPurgeError(""); }} placeholder="当前管理员密码" autocomplete="current-password" />
       {purgeError && <div id="trash-purge-error" className="tn-inline-error" role="alert">{purgeError}</div>}

web-next/src/services/api.ts

@@ -96,7 +96,7 @@ export async function api<T = unknown>(url: string, init: ApiRequestInit = {}):
       }
       throw new ApiError(
         response.status,
-        error?.message || `请求失败（${response.status}）`,
+        error?.message || (response.status >= 500 ? "服务器暂时繁忙，请稍后重试" : "操作未能完成，请稍后重试"),
         error?.code,
         error?.details,
         error?.requestId,
@@ -108,7 +108,7 @@ export async function api<T = unknown>(url: string, init: ApiRequestInit = {}):
     if (caught instanceof ApiError) throw caught;
     if (timedOut) throw new ApiError(408, "请求超时，请稍后重试", "REQUEST_TIMEOUT");
     if (externalSignal?.aborted) throw new ApiError(0, "请求已取消", "REQUEST_CANCELED");
-    throw new ApiError(0, "网络连接失败，请确认服务仍在运行");
+    throw new ApiError(0, "网络连接异常，请检查网络后重试");
   } finally {
     clearTimeout(timeout);
     externalSignal?.removeEventListener("abort", abortFromCaller);