fix: allow service-owned data directory during uninstall

.env.example

@@ -5,6 +5,10 @@ TALLYNOTE_TIMEZONE=Asia/Shanghai
 TALLYNOTE_PUBLIC_ORIGIN=http://127.0.0.1:3000
 TALLYNOTE_TRUST_PROXY=false
 TALLYNOTE_COOKIE_SECURE=false
+# Set TALLYNOTE_HOST=0.0.0.0 and the server's real IP Origin for direct
+# access. HTTP on a non-local Origin is opt-in; use HTTPS behind a proxy in
+# production.
+TALLYNOTE_ALLOW_INSECURE_HTTP=false
 TALLYNOTE_SESSION_IDLE_HOURS=24
 TALLYNOTE_SESSION_ABSOLUTE_HOURS=168
 TALLYNOTE_EXPORT_TTL_MINUTES=15
@@ -32,4 +36,5 @@ TALLYNOTE_UPDATE_MAX_MB=512
 TALLYNOTE_UPDATE_REQUIRE_SIGNATURE=false
 # TALLYNOTE_UPDATE_PUBLIC_KEY_FILE=/etc/tallynote/update-signing-key.pub
 TALLYNOTE_UPDATE_CHECK_COOLDOWN_SECONDS=60
+TALLYNOTE_UPDATE_DOWNLOAD_COOLDOWN_SECONDS=15
 TALLYNOTE_UPDATE_APPLY_COOLDOWN_SECONDS=15

README.md

@@ -57,17 +57,61 @@ pnpm build:next
 curl --proto '=https' --tlsv1.2 -fsSL https://git.awaioi.com/awaioi/TallyNote/raw/branch/main/install.sh | sudo bash
 ```
 
+安装命令保持简洁。首次在 SSH/终端中安装时，安装器会交互询问监听方式、端口和公开访问地址：
+
+```bash
+curl --proto '=https' --tlsv1.2 -fsSL https://git.awaioi.com/awaioi/TallyNote/raw/branch/main/install.sh | sudo bash
+```
+
+监听方式有两个选项：`127.0.0.1` 仅本机访问（默认、更安全），或 `0.0.0.0` 允许通过局域网/公网 IP 访问。选择 `0.0.0.0` 后，请填写真实访问地址，例如 `http://203.0.113.10:3000` 或 `https://tallynote.example.com`；不能填写 `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`。
+
+安装器不会在已有安装的升级过程中反复询问网络配置，并会保留现有环境文件。自动化或无终端环境可使用 `--non-interactive`（默认安全配置 `127.0.0.1:3000`），也可以显式传入 `TALLYNOTE_HOST`、`TALLYNOTE_PORT`、`TALLYNOTE_PUBLIC_ORIGIN` 和 `TALLYNOTE_ALLOW_INSECURE_HTTP` 覆盖配置。
+
+非交互安装命令：
+
+```bash
+curl --proto '=https' --tlsv1.2 -fsSL https://git.awaioi.com/awaioi/TallyNote/raw/branch/main/install.sh | sudo bash -s -- --non-interactive
+```
+
 脚本会从公开仓库的 latest Release 获取当前架构归档和 `SHA256SUMS`，并在安装前始终校验 SHA-256。也可以通过 `TALLYNOTE_REPOSITORY_URL`、`TALLYNOTE_RELEASE_API_URL`、`TALLYNOTE_RELEASE_ALLOWED_HOSTS` 和 `--release-base-url` 指向自己的仓库或受信 CDN。需要固定版本或预览时，仍可使用 `TALLYNOTE_VERSION`、`--version` 或 `--dry-run` 等高级选项。
 
+安装过程会持续输出带统一前缀的阶段日志，不会在下载、校验或启动服务时静默等待。交互式 SSH/终端中会先显示网络配置选择，下载时还会显示 curl 进度条；非交互式运行（例如 CI）只输出干净的阶段日志。典型输出如下（版本号、架构和耗时会按实际环境变化）：
+
+```text
+tallynote installer: [阶段] 检查运行环境、权限和目标架构
+tallynote installer: [完成] 运行环境可用：x64/glibc
+tallynote installer: [阶段] 从 Release API 获取最新版本
+tallynote installer: [完成] 已解析最新版本：1.1.2
+tallynote installer: [完成] Release 下载地址已准备
+tallynote installer: [阶段] 获取发布包：tallynote-1.1.2-linux-x64-glibc.tar.gz
+tallynote installer: [完成] 发布包已下载并通过大小限制
+tallynote installer: [阶段] 获取 SHA-256 校验清单
+tallynote installer: [完成] SHA-256 校验清单已准备
+tallynote installer: [阶段] 校验 SHA-256 和发布签名
+tallynote installer: [完成] 发布包校验通过
+tallynote installer: [阶段] 解包、校验包结构并原子切换到版本 1.1.2
+tallynote installer: [完成] 版本 1.1.2 已切换为当前版本
+tallynote installer: [阶段] 安装 systemd 单元、更新辅助程序和卸载器
+tallynote installer: [完成] systemd 单元、更新辅助程序和卸载器已安装
+tallynote installer: [阶段] 重新加载 systemd 并启动 TallyNote
+tallynote installer: [完成] TallyNote 服务已启用并启动
+tallynote installer: [阶段] 清理旧版本并完成安装
+tallynote installer: [完成] 旧版本清理完成
+tallynote installer: [完成] 安装完成：TallyNote 1.1.2
+tallynote installer: 查看服务状态：systemctl status tallynote.service
+```
+
+任何阶段失败都会以 `tallynote installer:` 前缀写出原因并立即停止；不会把不完整版本切换为当前版本。
+
 如需额外启用签名校验，在环境中设置 `TALLYNOTE_INSTALL_REQUIRE_SIGNATURE=true` 并提供 `--signing-key`；不设置时不会要求公钥或 `SHA256SUMS.sig`。
 
 已有安装默认拒绝降级到不高于当前版本；确需回退时显式使用 `--allow-downgrade`，正常更新不会覆盖当前或更高版本。
 
-安装布局为 `/opt/tallynote/releases/<version>` 加 `/opt/tallynote/current` 符号链接；切换通过临时链接和原子重命名完成。root 更新器使用前缀下独立的 `/opt/tallynote/.update-work`（`0700 root:root`）和 `.update-state` 恢复标记，不会把 root 解包工作区放进应用可写暂存目录。SQLite 数据、附件、暂存、导出和更新队列始终在外置 `/var/lib/tallynote`，不会随版本包删除。服务单元位于 `/etc/systemd/system/tallynote.service`，配置文件为 `/etc/tallynote/tallynote.env`，默认仅监听 `127.0.0.1:3000`。
+安装布局为 `/opt/tallynote/releases/<version>` 加 `/opt/tallynote/current` 符号链接；切换通过临时链接和原子重命名完成。root 更新器使用前缀下独立的 `/opt/tallynote/.update-work`（`0700 root:root`）和 `.update-state` 恢复标记，不会把 root 解包工作区放进应用可写暂存目录。SQLite 数据、附件、暂存、导出和更新队列始终在外置 `/var/lib/tallynote`，不会随版本包删除。服务单元位于 `/etc/systemd/system/tallynote.service`，配置文件为 `/etc/tallynote/tallynote.env`；监听地址、端口和公开 Origin 由该环境文件控制，默认仍是 `127.0.0.1:3000`。
 
 升级有两种方式：
 
-1. 后台进入“系统更新”，点击“检查更新”后确认版本。应用只会把经过 HTTPS、主机白名单和 SHA-256 校验的请求写入队列；如果显式配置了公钥，再额外验证 Ed25519 签名。root 权限的 `tallynote-update.path`/`tallynote-update.service` 会重新获取配置源，再执行停机、备份、切换和健康检查。Web 进程没有 `systemctl` 权限，队列中的 URL、文件地址和摘要不会直接驱动 root 下载。
+1. 后台进入“系统更新”，点击“检查更新”后可先“下载更新包”，等待校验完成，再点击“立即更新”。应用只会把经过 HTTPS、主机白名单和 SHA-256 校验的请求写入队列；如果显式配置了公钥，再额外验证 Ed25519 签名。下载阶段主服务保持运行；应用阶段才会停机、备份、切换和健康检查，页面会显示重启倒计时并自动重试连接。Web 进程没有 `systemctl` 权限，队列中的 URL、文件地址和摘要不会直接驱动 root 下载。
 2. 手动执行 `sudo /usr/local/sbin/tallynote-update --rollback` 可切回上一份 release。更新失败会自动保留旧版本并尝试恢复；不要删除 `/var/lib/tallynote`。
 
 更新任务详情按发起管理员隔离；失败信息在浏览器中使用固定提示，不暴露服务器路径、命令输出或上游响应。系统同一时刻只允许一个更新任务。

docs/release.md

@@ -38,8 +38,37 @@ GITEA_TOKEN=... \
 curl --proto '=https' --tlsv1.2 -fsSL https://git.awaioi.com/awaioi/TallyNote/raw/branch/main/install.sh | sudo bash
 ```
 
+首次在交互式 SSH/终端中执行时，安装器会在下载前询问监听方式、端口和公开访问地址。可选择仅本机监听 `127.0.0.1`，或监听 `0.0.0.0` 以允许通过真实服务器 IP/域名访问；公网 HTTP 必须在提示中明确确认，公开地址不能填写通配监听地址。已有安装升级时不会重复询问，并保留现有环境文件。无终端或 CI 使用 `--non-interactive`（默认 `127.0.0.1:3000`），也可通过 `TALLYNOTE_HOST`、`TALLYNOTE_PORT`、`TALLYNOTE_PUBLIC_ORIGIN` 和 `TALLYNOTE_ALLOW_INSECURE_HTTP` 显式配置。
+
+非交互安装命令：
+
+```bash
+curl --proto '=https' --tlsv1.2 -fsSL https://git.awaioi.com/awaioi/TallyNote/raw/branch/main/install.sh | sudo bash -s -- --non-interactive
+```
+
 脚本会从 `https://git.awaioi.com/awaioi/TallyNote/releases/download/v<版本>/` 下载当前架构归档和 `SHA256SUMS`，限制 HTTPS 重定向只能落在配置的受信主机，校验压缩/展开大小、条目数量、路径和特殊文件，再原子切换 `/opt/tallynote/current`。自定义仓库时同时设置 `TALLYNOTE_REPOSITORY_URL`、`TALLYNOTE_RELEASE_API_URL` 和 `TALLYNOTE_RELEASE_ALLOWED_HOSTS`；若使用独立 CDN，必须把 CDN 主机显式加入白名单。需要预览时显式加 `--dry-run`，需要固定版本时使用 `--version`。
 
+安装器会在每个关键阶段输出统一格式的日志，便于在 SSH 或 systemd 安装会话中确认进度；交互式终端下载时还会显示 curl 进度条，CI 或日志重定向时则保持纯文本输出：
+
+```text
+tallynote installer: [阶段] 检查运行环境、权限和目标架构
+tallynote installer: [阶段] 从 Release API 获取最新版本
+tallynote installer: [阶段] 获取发布包：tallynote-<版本>-linux-x64-glibc.tar.gz
+tallynote installer: [阶段] 获取 SHA-256 校验清单
+tallynote installer: [阶段] 校验 SHA-256 和发布签名
+tallynote installer: [阶段] 解包、校验包结构并原子切换到版本 <版本>
+tallynote installer: [完成] 版本 <版本> 已切换为当前版本
+tallynote installer: [阶段] 安装 systemd 单元、更新辅助程序和卸载器
+tallynote installer: [完成] systemd 单元、更新辅助程序和卸载器已安装
+tallynote installer: [阶段] 重新加载 systemd 并启动 TallyNote
+tallynote installer: [完成] TallyNote 服务已启用并启动
+tallynote installer: [阶段] 清理旧版本并完成安装
+tallynote installer: [完成] 旧版本清理完成
+tallynote installer: [完成] 安装完成：TallyNote <版本>
+```
+
+每个阶段完成时会输出 `[完成]`；错误会立即以 `tallynote installer:` 前缀输出，不会静默等待或切换半成品版本。
+
 如需启用签名校验，设置 `TALLYNOTE_INSTALL_REQUIRE_SIGNATURE=true` 并提供 `--signing-key`；后台更新同样可通过 `TALLYNOTE_UPDATE_REQUIRE_SIGNATURE=true` 和 `TALLYNOTE_UPDATE_PUBLIC_KEY_FILE` 开启。默认关闭签名要求，方便公开自维护仓库直接更新。
 
 已有安装默认拒绝安装不高于当前版本的 release；只有在明确执行 `--allow-downgrade`（或设置 `TALLYNOTE_ALLOW_DOWNGRADE=true`）时才允许回退版本。
@@ -72,13 +101,15 @@ 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 签名。
 
-浏览器只能提交版本号和确认标志。Web 进程把受保护的任务文件交给 root 的 `tallynote-update.path`/`tallynote-update.service`，root runner 会重新读取配置源、重新下载并验证 metadata 和清单，不信任队列文件中的 URL 或摘要。更新前会备份数据，切换失败或健康检查失败会恢复旧版本；手动回滚：
+后台更新分为两个明确阶段。管理员先在“系统更新”读取最新 Release 的版本号、发布时间和更新说明，点击“下载更新包”；root 更新器会在主服务继续运行时下载、校验 SHA-256、解包并暂存。页面显示“下载完成，等待应用”后，管理员再点击“立即更新”。应用阶段才会短暂停止服务、备份数据、切换 release、启动并执行健康检查；页面显示重启倒计时并自动重试连接。浏览器只提交版本号、任务 ID 和确认标志，不能提交 URL 或文件路径。
+
+Web 进程把受保护的任务文件交给 root 的 `tallynote-update.path`/`tallynote-update.service`，root runner 会重新读取配置源并验证 metadata、清单和暂存目录，不信任队列文件中的 URL 或摘要。切换失败或健康检查失败会恢复旧版本；手动回滚：
 
 ```bash
 sudo /usr/local/sbin/tallynote-update --rollback
 ```
 
-更新检查和应用接口带有冷却时间（可用 `TALLYNOTE_UPDATE_CHECK_COOLDOWN_SECONDS`、`TALLYNOTE_UPDATE_APPLY_COOLDOWN_SECONDS` 调整），避免反复触发外部请求。服务单元默认仅监听 `127.0.0.1`，并使用最小化 systemd 权限；公网访问必须通过 HTTPS 反向代理，设置真实 `TALLYNOTE_PUBLIC_ORIGIN`、`TALLYNOTE_COOKIE_SECURE=true` 和明确的 `TALLYNOTE_TRUST_PROXY` 跳数。
+更新检查、下载和应用接口分别带有冷却时间（可用 `TALLYNOTE_UPDATE_CHECK_COOLDOWN_SECONDS`、`TALLYNOTE_UPDATE_DOWNLOAD_COOLDOWN_SECONDS`、`TALLYNOTE_UPDATE_APPLY_COOLDOWN_SECONDS` 调整），避免反复触发外部请求或重复排队。服务单元默认仅监听 `127.0.0.1`；首次安装时可在交互提示中选择 `0.0.0.0` 和真实的服务器 IP/域名。直连 HTTP 会暴露未加密的会话和数据，只适合受控网络；绑定域名后必须改为 HTTPS 反向代理，设置真实 `TALLYNOTE_PUBLIC_ORIGIN`、`TALLYNOTE_COOKIE_SECURE=true`、`TALLYNOTE_ALLOW_INSECURE_HTTP=false` 和明确的 `TALLYNOTE_TRUST_PROXY` 跳数。自动化安装可使用 `--non-interactive` 或显式网络环境变量。
 
 更新任务详情按发起管理员隔离，任务错误只返回固定提示，不会把服务器路径、命令输出或上游响应泄露到浏览器；同一时刻仍只允许一个系统更新任务。
 

install.sh

@@ -34,6 +34,20 @@ MAX_TIME=${TALLYNOTE_INSTALL_MAX_TIME_SECONDS:-300}
 RELEASE_ALLOWED_HOSTS=${TALLYNOTE_RELEASE_ALLOWED_HOSTS:-}
 OPENSSL_BIN=${TALLYNOTE_OPENSSL_BIN:-openssl}
 UNAME_BIN=${TALLYNOTE_UNAME_BIN:-uname}
+# Service network settings are written to the systemd EnvironmentFile on a
+# fresh install. Existing values are preserved unless the corresponding
+# TALLYNOTE_* variable is explicitly supplied to the installer.
+INSTALL_HOST=${TALLYNOTE_HOST-127.0.0.1}
+INSTALL_PORT=${TALLYNOTE_PORT-3000}
+INSTALL_PUBLIC_ORIGIN=${TALLYNOTE_PUBLIC_ORIGIN-}
+INSTALL_ALLOW_INSECURE_HTTP=${TALLYNOTE_ALLOW_INSECURE_HTTP-false}
+NON_INTERACTIVE=0
+
+# The production prompt uses the controlling terminal, even when the
+# installer itself is read from `curl | sudo bash`.
+PROMPT_INPUT=/dev/tty
+PROMPT_OUTPUT=/dev/tty
+PROMPT_REPLY=''
 
 INSTALL_SWITCHED=0
 INSTALL_COMMITTED=0
@@ -58,17 +72,126 @@ Usage: install.sh [--dry-run] [--version VERSION] [--release-base-url HTTPS_URL]
                   [--signature-format ed25519|gpg]
                   [--update-public-key-file FILE]
                   [--keep-releases N] [--allow-downgrade] [--allow-unsigned] [--apply]
+                  [--non-interactive]
 
 Without arguments, the installer resolves the latest compatible release and
 installs it. SHA-256 from SHA256SUMS is always required. Detached signature
 verification is optional by default; enable it with
 TALLYNOTE_INSTALL_REQUIRE_SIGNATURE=true and provide a public key. Use
 --dry-run to inspect the selected release without downloading or changing the
-host. --apply is accepted for backwards compatibility.
+host. For direct IP access, pass TALLYNOTE_HOST=0.0.0.0 and an actual
+TALLYNOTE_PUBLIC_ORIGIN such as http://203.0.113.10:3000; HTTP also requires
+TALLYNOTE_ALLOW_INSECURE_HTTP=true. On a fresh terminal install, the listener
+and public URL can be selected interactively. Use --non-interactive (or
+TALLYNOTE_NON_INTERACTIVE=true) for automation. --apply is accepted for
+backwards compatibility.
 EOF
 }
 die() { printf 'tallynote installer: %s\n' "$*" >&2; exit 1; }
 log() { printf 'tallynote installer: %s\n' "$*"; }
+stage() { log "[阶段] $*"; }
+stage_done() { log "[完成] $*"; }
+
+case "${TALLYNOTE_NON_INTERACTIVE:-false}" in
+  true|1) NON_INTERACTIVE=1 ;;
+  false|0) ;;
+  *) die 'TALLYNOTE_NON_INTERACTIVE 必须是 true 或 false' ;;
+esac
+
+prompt_value() {
+  local label=$1 default=${2-} reply
+  if [[ -n "$default" ]]; then
+    printf '%s [%s]: ' "$label" "$default" > "$PROMPT_OUTPUT"
+  else
+    printf '%s: ' "$label" > "$PROMPT_OUTPUT"
+  fi
+  if ! IFS= read -r reply <&9; then
+    die '无法读取终端输入；请使用 --non-interactive 或通过环境变量配置'
+  fi
+  PROMPT_REPLY=${reply:-$default}
+}
+
+has_network_environment() {
+  [[ -n "${TALLYNOTE_HOST+x}" || -n "${TALLYNOTE_PORT+x}" || -n "${TALLYNOTE_PUBLIC_ORIGIN+x}" || -n "${TALLYNOTE_ALLOW_INSECURE_HTTP+x}" ]]
+}
+
+interactive_network_available() {
+  (( APPLY )) || return 1
+  (( NON_INTERACTIVE == 0 )) || return 1
+  has_network_environment && return 1
+  [[ ! -e "$CONFIG_DIR/tallynote.env" && ! -L "$CONFIG_DIR/tallynote.env" ]] || return 1
+  [[ -r "$PROMPT_INPUT" && -w "$PROMPT_OUTPUT" ]] || return 1
+  return 0
+}
+
+configure_network_interactively() {
+  interactive_network_available || return 0
+
+  exec 9<"$PROMPT_INPUT" || die '无法打开终端输入；请使用 --non-interactive 或通过环境变量配置'
+
+  stage '配置服务网络监听（可直接回车使用默认值）'
+  {
+    printf '\nTallyNote 服务监听配置\n'
+    printf '  1) 仅本机访问：127.0.0.1（更安全）\n'
+    printf '  2) 局域网/公网访问：0.0.0.0（需要填写实际访问地址）\n'
+  } > "$PROMPT_OUTPUT"
+
+  local choice selected_port origin answer
+  while :; do
+    prompt_value '请选择监听方式 1/2' '1'
+    choice=$PROMPT_REPLY
+    case "$choice" in
+      1|2) break ;;
+      *) printf '请输入 1 或 2。\n' > "$PROMPT_OUTPUT" ;;
+    esac
+  done
+
+  while :; do
+    prompt_value '监听端口' "$INSTALL_PORT"
+    selected_port=$PROMPT_REPLY
+    if [[ "$selected_port" =~ ^[1-9][0-9]*$ && "$selected_port" -le 65535 ]]; then
+      break
+    fi
+    printf '端口必须是 1-65535 的整数，请重试。\n' > "$PROMPT_OUTPUT"
+  done
+
+  if [[ "$choice" == 1 ]]; then
+    INSTALL_HOST=127.0.0.1
+    INSTALL_PORT=$selected_port
+    INSTALL_PUBLIC_ORIGIN="http://127.0.0.1:${selected_port}"
+    INSTALL_ALLOW_INSECURE_HTTP=false
+  else
+    INSTALL_HOST=0.0.0.0
+    INSTALL_PORT=$selected_port
+    while :; do
+      prompt_value '实际访问地址（例如 http://203.0.113.10:3000 或 https://tallynote.example.com）' ''
+      origin=$PROMPT_REPLY
+      if validate_env_value "$origin" '公开访问地址' >/dev/null 2>&1 && validate_public_origin "$origin" >/dev/null 2>&1; then
+        INSTALL_PUBLIC_ORIGIN=$origin
+        break
+      fi
+      printf '地址无效：请输入不含路径、凭据或通配监听地址的 http:// 或 https:// 地址。\n' > "$PROMPT_OUTPUT"
+    done
+    INSTALL_ALLOW_INSECURE_HTTP=false
+    if [[ "$INSTALL_PUBLIC_ORIGIN" == http://* ]]; then
+      {
+        printf '\n警告：直连 HTTP 不加密，登录信息和账目数据可能被窃听。\n'
+        printf '仅在受控局域网或你明确接受风险时继续。\n'
+      } > "$PROMPT_OUTPUT"
+      while :; do
+        prompt_value '确认允许公网 HTTP？输入 yes 继续，其他内容取消' 'no'
+        answer=$PROMPT_REPLY
+        case "$answer" in
+          yes|YES|Yes|y|Y) INSTALL_ALLOW_INSECURE_HTTP=true; break ;;
+          no|NO|No|n|N|'') die '已取消：公网 HTTP 必须明确确认；请改用 HTTPS 或重新运行安装器' ;;
+          *) printf '请输入 yes 或 no。\n' > "$PROMPT_OUTPUT" ;;
+        esac
+      done
+    fi
+  fi
+  exec 9<&-
+  stage_done "网络配置已选择：${INSTALL_HOST}:${INSTALL_PORT}"
+}
 
 [[ "$REQUIRE_SIGNATURE" == true || "$REQUIRE_SIGNATURE" == false ]] || die 'TALLYNOTE_INSTALL_REQUIRE_SIGNATURE 必须是 true 或 false'
 [[ "$ALLOW_DOWNGRADE" == true || "$ALLOW_DOWNGRADE" == false ]] || die 'TALLYNOTE_ALLOW_DOWNGRADE 必须是 true 或 false'
@@ -104,6 +227,7 @@ while (($#)); do
     --keep-releases) KEEP_RELEASES=${2:?missing value for --keep-releases}; shift ;;
     --allow-downgrade) ALLOW_DOWNGRADE=true ;;
     --allow-unsigned) ALLOW_UNSIGNED=1; REQUIRE_SIGNATURE=false ;;
+    --non-interactive) NON_INTERACTIVE=1 ;;
     -h|--help) usage; exit 0 ;;
     *) die "unknown option: $1" ;;
   esac
@@ -197,15 +321,23 @@ assert_allowed_url() {
 download() {
   local url=$1 out=$2 max_bytes=${3:-$((MAX_RELEASE_MB * 1024 * 1024))}
   local current="$url" headers status location actual origin scheme authority
+  local -a curl_args=(--proto '=https' --tlsv1.2 --fail --show-error --max-redirs 0
+    --connect-timeout "$CONNECT_TIMEOUT" --max-time "$MAX_TIME" --max-filesize "$max_bytes"
+    --retry 2 --retry-connrefused)
+  # Keep CI and journal output clean, while showing curl's standard progress
+  # bar during an interactive SSH/terminal installation.
+  if [[ -t 2 ]]; then
+    curl_args+=(--progress-bar)
+  else
+    curl_args+=(--silent)
+  fi
   require_https "$url"
   assert_allowed_url "$url"
   [[ ! -L "$out" && ! -e "$out" ]] || die "download destination already exists: $out"
   for _redirect in 0 1 2 3; do
     headers="${out}.headers-${RANDOM}-$$"
-    status=$(curl --proto '=https' --tlsv1.2 --fail --silent --show-error --max-redirs 0 \
-      --connect-timeout "$CONNECT_TIMEOUT" --max-time "$MAX_TIME" --max-filesize "$max_bytes" \
-      --retry 2 --retry-connrefused --output "$out" --dump-header "$headers" \
-      --write-out '%{http_code}' "$current" 2>/dev/null) || status=000
+    status=$(curl "${curl_args[@]}" --output "$out" --dump-header "$headers" \
+      --write-out '%{http_code}' "$current") || status=000
     if [[ "$status" =~ ^2[0-9][0-9]$ ]]; then
       rm -f -- "$headers"
       break
@@ -611,6 +743,66 @@ validate_env_value() {
   [[ ${#value} -le 4096 ]] || die "$label 过长"
 }
 
+validate_listen_host() {
+  local value=$1 label=${2:-监听地址}
+  validate_env_value "$value" "$label"
+  if [[ "$value" == *:* ]]; then
+    [[ "$value" =~ ^[0-9A-Fa-f:]+$ ]] || die "$label 必须是有效的 IPv6 地址或主机名"
+  elif [[ "$value" =~ ^[0-9.]+$ ]]; then
+    [[ "$value" =~ ^([0-9]{1,3}\.){3}[0-9]{1,3}$ ]] || die "$label 必须是有效的 IPv4 地址或主机名"
+    local octet
+    IFS='.' read -r -a _host_octets <<< "$value"
+    for octet in "${_host_octets[@]}"; do
+      (( octet <= 255 )) || die "$label 必须是有效的 IPv4 地址或主机名"
+    done
+  else
+    [[ "$value" =~ ^[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$ ]] || die "$label 必须是有效的 IPv4、IPv6 地址或主机名"
+    [[ "$value" != *..* && "$value" != *.-* && "$value" != *-.* ]] || die "$label 包含不受支持的主机名"
+  fi
+}
+
+validate_listen_port() {
+  local value=$1 label=${2:-监听端口}
+  [[ "$value" =~ ^[1-9][0-9]*$ && "$value" -le 65535 ]] || die "$label 必须是 1-65535 的整数"
+}
+
+validate_public_origin() {
+  local value=$1 authority host path_part origin_port suffix
+  case "$value" in
+    http://*|https://*) ;;
+    *) die '公开访问地址必须是 http:// 或 https:// 地址' ;;
+  esac
+  [[ "$value" != *[[:space:]]* && "$value" != *[[:cntrl:]]* && "$value" != *'@'* && "$value" != *'?'* && "$value" != *'#'* ]] || die '公开访问地址包含不受支持的字符'
+  authority=${value#*://}
+  authority=${authority%%/*}
+  [[ -n "$authority" ]] || die '公开访问地址缺少主机名'
+  if [[ "$authority" == \[*\]* ]]; then
+    host=${authority#\[}; host=${host%%\]*}
+    suffix=${authority#*\]}
+    if [[ -n "$suffix" ]]; then
+      [[ "$suffix" =~ ^:([0-9]+)$ ]] || die '公开访问地址端口无效'
+      origin_port=${BASH_REMATCH[1]}
+    fi
+  else
+    if [[ "$authority" == *:* ]]; then
+      [[ "$authority" =~ ^([^:]+):([0-9]+)$ ]] || die '公开访问地址端口无效'
+      host=${BASH_REMATCH[1]}
+      origin_port=${BASH_REMATCH[2]}
+    else
+      host=$authority
+    fi
+  fi
+  [[ -n "$host" ]] || die '公开访问地址缺少主机名'
+  [[ "$host" != 0.0.0.0 && "$host" != :: && "$host" != \* ]] || die '公开访问地址不能使用通配监听地址，请填写服务器 IP 或域名'
+  [[ "$host" =~ ^[A-Za-z0-9.-]+$ || "$host" =~ ^[0-9A-Fa-f:]+$ ]] || die '公开访问地址主机名无效'
+  if [[ -n "$origin_port" ]]; then
+    [[ "$origin_port" =~ ^[0-9]{1,5}$ && "$origin_port" -ge 1 && "$origin_port" -le 65535 ]] || die '公开访问地址端口必须是 1-65535 的整数'
+  fi
+  path_part=${value#*://}
+  path_part=${path_part#"$authority"}
+  [[ -z "$path_part" || "$path_part" == "/" ]] || die '公开访问地址不能包含路径'
+}
+
 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
@@ -630,14 +822,14 @@ validate_install_path() {
 }
 
 validate_existing_env() {
-  local file=$1 value metadata_host
+  local file=$1 value metadata_host host port origin allow_insecure cookie_secure
   [[ ! -L "$file" && -f "$file" ]] || die '现有环境文件不是普通文件'
   [[ "$(stat_uid "$file")" == 0 ]] || die '现有环境文件必须由 root 拥有'
   local mode_bits
   mode_bits=$(stat_mode_bits "$file")
   (( (mode_bits & 18) == 0 )) || die '环境文件不能被组或其他用户写入'
   local key key_count
-  for key in TALLYNOTE_INSTALL_PREFIX TALLYNOTE_DATA_DIR TALLYNOTE_UPDATE_REQUIRE_SIGNATURE TALLYNOTE_UPDATE_METADATA_URL TALLYNOTE_UPDATE_ALLOWED_HOSTS TALLYNOTE_UPDATE_PUBLIC_KEY_FILE; do
+  for key in TALLYNOTE_INSTALL_PREFIX TALLYNOTE_DATA_DIR TALLYNOTE_HOST TALLYNOTE_PORT TALLYNOTE_PUBLIC_ORIGIN TALLYNOTE_ALLOW_INSECURE_HTTP TALLYNOTE_COOKIE_SECURE TALLYNOTE_UPDATE_REQUIRE_SIGNATURE TALLYNOTE_UPDATE_METADATA_URL TALLYNOTE_UPDATE_ALLOWED_HOSTS TALLYNOTE_UPDATE_PUBLIC_KEY_FILE; do
     key_count=$(env_key_count "$file" "$key")
     [[ "$key_count" =~ ^[0-9]+$ && "$key_count" -le 1 ]] || die "环境文件包含重复配置：$key"
   done
@@ -647,6 +839,59 @@ validate_existing_env() {
   [[ -z "$value" || "${value%/}" == "${DATA_DIR%/}" ]] || die '环境文件中的数据目录与本次安装不一致'
   value=$(read_env_value "$file" TALLYNOTE_UPDATE_REQUIRE_SIGNATURE)
   [[ -z "$value" || "$value" == true || "$value" == false ]] || die '环境文件中的签名校验配置必须是 true 或 false'
+  if (( $(env_key_count "$file" TALLYNOTE_HOST) )); then
+    host=$(read_env_value "$file" TALLYNOTE_HOST)
+    validate_listen_host "$host" '环境文件中的监听地址'
+  else
+    host=127.0.0.1
+  fi
+  if (( $(env_key_count "$file" TALLYNOTE_PORT) )); then
+    port=$(read_env_value "$file" TALLYNOTE_PORT)
+    validate_listen_port "$port" '环境文件中的监听端口'
+  else
+    port=3000
+  fi
+  if (( $(env_key_count "$file" TALLYNOTE_ALLOW_INSECURE_HTTP) )); then
+    allow_insecure=$(read_env_value "$file" TALLYNOTE_ALLOW_INSECURE_HTTP)
+    [[ "$allow_insecure" == true || "$allow_insecure" == false ]] || die '环境文件中的公网 HTTP 开关必须是 true 或 false'
+  else
+    allow_insecure=false
+  fi
+  if (( $(env_key_count "$file" TALLYNOTE_COOKIE_SECURE) )); then
+    cookie_secure=$(read_env_value "$file" TALLYNOTE_COOKIE_SECURE)
+    [[ "$cookie_secure" == true || "$cookie_secure" == false ]] || die '环境文件中的安全 Cookie 配置必须是 true 或 false'
+  else
+    cookie_secure=''
+  fi
+  if (( $(env_key_count "$file" TALLYNOTE_PUBLIC_ORIGIN) )); then
+    origin=$(read_env_value "$file" TALLYNOTE_PUBLIC_ORIGIN)
+    validate_env_value "$origin" '环境文件中的公开访问地址'
+  else
+    origin="http://${host}:${port}"
+  fi
+  validate_public_origin "$origin"
+  local origin_host=${origin#*://}
+  if [[ "$origin_host" == \[*\]* ]]; then
+    origin_host=${origin_host#\[}
+    origin_host=${origin_host%%\]*}
+  else
+    origin_host=${origin_host%%:*}
+  fi
+  if [[ "$origin" == http://* && "$allow_insecure" != true ]]; then
+    case "$origin_host" in
+      127.0.0.1|localhost|::1) ;;
+      *) die '环境文件中的公网 HTTP 访问必须显式设置 TALLYNOTE_ALLOW_INSECURE_HTTP=true' ;;
+    esac
+  fi
+  if [[ "$origin" == http://* && "$cookie_secure" == true ]]; then
+    case "$origin_host" in
+      127.0.0.1|localhost|::1) ;;
+      *) die '环境文件中的公网 HTTP 公开地址不能启用安全 Cookie' ;;
+    esac
+  fi
+  if [[ "$origin" == https://* && "$cookie_secure" == false ]]; then
+    die '环境文件中的 HTTPS 公开地址必须启用安全 Cookie'
+  fi
   value=$(read_env_value "$file" TALLYNOTE_UPDATE_METADATA_URL)
   if [[ -n "$value" ]]; then
     validate_env_value "$value" '环境文件更新源'
@@ -715,6 +960,7 @@ prune_releases() {
 }
 
 main() {
+  stage '检查运行环境、权限和目标架构'
   # These variables are useful for isolated tests, but a root install must
   # never execute an untrusted PATH entry supplied through sudo's environment.
   if (( APPLY )) || [[ -n "${TALLYNOTE_UNAME_BIN+x}" ]]; then
@@ -724,6 +970,32 @@ main() {
     validate_trusted_tool "$OPENSSL_BIN" 'openssl'
   fi
   detect_platform
+  configure_network_interactively
+  validate_listen_host "$INSTALL_HOST"
+  validate_listen_port "$INSTALL_PORT"
+  if [[ -n "${TALLYNOTE_PUBLIC_ORIGIN+x}" && -z "$INSTALL_PUBLIC_ORIGIN" ]]; then
+    die 'TALLYNOTE_PUBLIC_ORIGIN 不能是空值；省略该变量以使用默认 Origin'
+  fi
+  [[ "$INSTALL_ALLOW_INSECURE_HTTP" == true || "$INSTALL_ALLOW_INSECURE_HTTP" == false ]] || die 'TALLYNOTE_ALLOW_INSECURE_HTTP 必须是 true 或 false'
+  if [[ -n "$INSTALL_PUBLIC_ORIGIN" ]]; then
+    validate_env_value "$INSTALL_PUBLIC_ORIGIN" '公开访问地址'
+    validate_public_origin "$INSTALL_PUBLIC_ORIGIN"
+    if [[ "$INSTALL_PUBLIC_ORIGIN" == http://* && "$INSTALL_ALLOW_INSECURE_HTTP" != true ]]; then
+      public_host=${INSTALL_PUBLIC_ORIGIN#http://}
+      if [[ "$public_host" == \[*\]* ]]; then
+        public_host=${public_host#\[}
+        public_host=${public_host%%\]*}
+      else
+        public_host=${public_host%%:*}
+      fi
+      case "$public_host" in
+        127.0.0.1|localhost|::1) ;;
+        *) die '公网 HTTP 访问必须显式设置 TALLYNOTE_ALLOW_INSECURE_HTTP=true' ;;
+      esac
+    fi
+  elif [[ "$INSTALL_HOST" != 127.0.0.1 && "$INSTALL_HOST" != localhost && "$INSTALL_HOST" != ::1 ]]; then
+    die '监听非本机地址时必须提供 TALLYNOTE_PUBLIC_ORIGIN（例如 http://服务器IP:3000）'
+  fi
   [[ "$KEEP_RELEASES" =~ ^[1-9][0-9]*$ ]] || die '--keep-releases must be a positive integer'
   validate_install_path "$PREFIX" '安装目录'
   validate_install_path "$DATA_DIR" '数据目录'
@@ -737,14 +1009,21 @@ main() {
   # TALLYNOTE_RELEASE_ALLOWED_HOSTS when the operator has reviewed it.
   append_allowed_host "$(url_host "$RELEASE_API_URL")"
   append_allowed_host "$(url_host "$REPOSITORY_URL")"
+  stage_done "运行环境可用：${TALLYNOTE_ARCH}/${TALLYNOTE_LIBC}"
   if [[ "$VERSION" == "latest" ]]; then
     if (( ! APPLY )); then
       [[ -z "$RELEASE_BASE_URL" ]] || require_https "$RELEASE_BASE_URL"
+      stage '预览最新版本解析（dry-run 不访问 Release）'
       log 'version: latest (release lookup skipped in dry-run)'
       log 'dry-run: pass --version VERSION to preview an exact artifact'
+      stage_done 'dry-run 预览完成：不会下载、解包或修改 systemd'
       return 0
     fi
+    stage '从 Release API 获取最新版本'
     resolve_latest_version
+    stage_done "已解析最新版本：${VERSION#v}"
+  else
+    stage "使用指定版本：${VERSION#v}"
   fi
   validate_semver "$VERSION" || die 'version must be a semantic version (for example 1.2.3)'
   VERSION=${VERSION#v}
@@ -755,15 +1034,21 @@ main() {
       die "拒绝安装不高于当前版本的 release：当前 $current_version，候选 $VERSION（如确需降级请使用 --allow-downgrade）"
     fi
   fi
+  stage '准备 Release 下载地址和发布包'
   release_urls
   local artifact archive checksum signature artifact_url work release_dir
   artifact=${RELEASE_FILE:+$(basename -- "$RELEASE_FILE")}
   artifact=${artifact:-tallynote-${VERSION}-linux-${TALLYNOTE_ARCH}-${TALLYNOTE_LIBC}.tar.gz}
   [[ "$artifact" =~ ^[A-Za-z0-9][A-Za-z0-9._+\-]*\.(tar\.gz|tgz|tar)$ ]] || die 'release 文件名无效'
   artifact_url="$RELEASE_BASE_URL/$artifact"
+  stage_done 'Release 下载地址已准备'
   log "platform: ${TALLYNOTE_ARCH}/${TALLYNOTE_LIBC}; release: ${VERSION#v}"
   log "layout: $PREFIX/releases + atomic $PREFIX/current; data: $DATA_DIR"
-  if (( ! APPLY )); then log 'dry-run: no download, extraction, or systemd changes'; return 0; fi
+  if (( ! APPLY )); then
+    log 'dry-run: no download, extraction, or systemd changes'
+    stage_done 'dry-run 预览完成：不会下载、解包或修改 systemd'
+    return 0
+  fi
   [[ "$("$UNAME_BIN" -s)" == Linux ]] || die '安装器只允许在 Linux 上执行'
   [[ $EUID -eq 0 ]] || die '安装必须以 root 运行'
   for command_name in curl sha256sum tar install sed awk find systemctl; do
@@ -777,6 +1062,7 @@ main() {
   INSTALL_BACKUP_DIR="$work/original"
   trap rollback_install_if_needed EXIT
   archive="$work/$artifact"
+  stage "获取发布包：$artifact"
   if [[ -n "$RELEASE_FILE" && -f "$RELEASE_FILE" && ! -L "$RELEASE_FILE" ]]; then
     cp -- "$RELEASE_FILE" "$archive"
     chmod 600 "$archive"
@@ -785,8 +1071,10 @@ main() {
     [[ -z "$RELEASE_FILE" ]] || die '本地 release 文件不存在或是符号链接'
     download "$artifact_url" "$archive"
   fi
+  stage_done '发布包已下载并通过大小限制'
   checksum="$work/SHA256SUMS"
   SHA256_URL=${SHA256_URL:-$RELEASE_BASE_URL/SHA256SUMS}
+  stage '获取 SHA-256 校验清单'
   if [[ -n "$SHA256_FILE" && -f "$SHA256_FILE" && ! -L "$SHA256_FILE" ]]; then
     cp -- "$SHA256_FILE" "$checksum"
     chmod 600 "$checksum"
@@ -795,9 +1083,11 @@ main() {
     [[ -z "$SHA256_FILE" ]] || die '本地 SHA256SUMS 文件不存在或是符号链接'
     download "$SHA256_URL" "$checksum" $((2 * 1024 * 1024))
   fi
+  stage_done 'SHA-256 校验清单已准备'
   SIGNING_KEY=${SIGNING_KEY:-$UPDATE_PUBLIC_KEY_FILE}
   signature=''
   if [[ "$REQUIRE_SIGNATURE" == true || -n "$SIGNATURE_URL" || -n "$SIGNING_KEY" ]]; then
+    stage '获取发布签名'
     if [[ "$SIGNATURE_FORMAT" == gpg ]]; then
       SIGNATURE_URL=${SIGNATURE_URL:-$RELEASE_BASE_URL/$artifact.asc}
       signature="$work/$artifact.asc"
@@ -806,10 +1096,14 @@ main() {
       signature="$work/SHA256SUMS.sig"
     fi
     download "$SIGNATURE_URL" "$signature" $((64 * 1024))
+    stage_done '发布签名已准备'
   fi
+  stage '校验 SHA-256 和发布签名'
   verify_archive "$archive" "$checksum" "$signature" "$SIGNING_KEY"
+  stage_done '发布包校验通过'
   [[ "$PREFIX" = /* && "$DATA_DIR" = /* && "$CONFIG_DIR" = /* ]] || die '安装、数据和配置目录必须是绝对路径'
   [[ ! -L "$DATA_DIR" && ! -L "$PREFIX" && ! -L "$CONFIG_DIR" ]] || die 'installation/data/config paths must not be symlinks'
+  stage '停止旧服务并准备安装、配置和数据目录'
   id tallynote >/dev/null 2>&1 || useradd --system --user-group --home-dir "$DATA_DIR" --shell /usr/sbin/nologin tallynote
   backup_install_files "$INSTALL_BACKUP_DIR"
   stop_existing_services
@@ -821,10 +1115,14 @@ main() {
   if [[ -e "$CONFIG_DIR/tallynote.env" ]]; then
     validate_existing_env "$CONFIG_DIR/tallynote.env"
   fi
+  stage_done '目录、权限和旧服务状态已准备'
+  stage "解包、校验包结构并原子切换到版本 ${VERSION#v}"
   install_release "$archive" "$VERSION"
+  stage_done "版本 ${VERSION#v} 已切换为当前版本"
   release_dir="$PREFIX/releases/$VERSION"
   [[ -f "$release_dir/systemd/tallynote.service" && -f "$release_dir/systemd/tallynote-update.service" && -f "$release_dir/systemd/tallynote-update.path" ]] || die 'release package is missing systemd unit files'
   [[ -f "$release_dir/systemd/tallynote.env.example" && -f "$release_dir/scripts/tallynote-update-runner.sh" && -x "$release_dir/uninstall.sh" ]] || die 'release package is missing update/uninstall support files'
+  stage '安装 systemd 单元、更新辅助程序和卸载器'
   install -d -m 755 /usr/local/libexec /etc/systemd/system
   local unit_tmp
   unit_tmp=$(mktemp -d)
@@ -839,10 +1137,12 @@ main() {
   install -o root -g root -m 755 "$release_dir/scripts/tallynote-update-runner.sh" /usr/local/libexec/tallynote-update-runner
   install -o root -g root -m 755 "$release_dir/uninstall.sh" /usr/local/sbin/tallynote-uninstall
   ensure_root_directory "$(dirname -- "$DATA_DIR")/tallynote-backups" 700
+  local env_created=0
   if [[ ! -f "$CONFIG_DIR/tallynote.env" ]]; then
     sed "s#/opt/tallynote#$PREFIX#g; s#/var/lib/tallynote#$DATA_DIR#g" "$release_dir/systemd/tallynote.env.example" > "$CONFIG_DIR/tallynote.env"
     chown root:root "$CONFIG_DIR/tallynote.env"
     chmod 640 "$CONFIG_DIR/tallynote.env"
+    env_created=1
   fi
   ensure_env_key() {
     local key=$1 value=$2
@@ -855,6 +1155,40 @@ main() {
       printf '%s=%s\n' "$key" "$value" >> "$CONFIG_DIR/tallynote.env"
     fi
   }
+  set_env_key() {
+    local key=$1 value=$2 escaped tmp
+    [[ "$key" =~ ^[A-Z0-9_]+$ ]] || die '环境变量名无效'
+    validate_env_value "$value" "$key"
+    escaped=${value//\\/\\\\}
+    escaped=${escaped//&/\\&}
+    escaped=${escaped//|/\\|}
+    if grep -qE "^${key}=" "$CONFIG_DIR/tallynote.env"; then
+      sed -i "s|^${key}=.*|${key}=${escaped}|" "$CONFIG_DIR/tallynote.env"
+    else
+      if [[ -s "$CONFIG_DIR/tallynote.env" && "$(tail -c 1 "$CONFIG_DIR/tallynote.env")" != $'\n' ]]; then
+        printf '\n' >> "$CONFIG_DIR/tallynote.env"
+      fi
+      printf '%s=%s\n' "$key" "$value" >> "$CONFIG_DIR/tallynote.env"
+    fi
+  }
+  # A fresh install gets the requested network settings. On upgrades, only
+  # explicitly supplied values change the existing administrator config.
+  if (( env_created )) || [[ -n "${TALLYNOTE_HOST+x}" ]]; then set_env_key TALLYNOTE_HOST "$INSTALL_HOST"; fi
+  if (( env_created )) || [[ -n "${TALLYNOTE_PORT+x}" ]]; then set_env_key TALLYNOTE_PORT "$INSTALL_PORT"; fi
+  if (( env_created )); then
+    if [[ -n "$INSTALL_PUBLIC_ORIGIN" ]]; then
+      set_env_key TALLYNOTE_PUBLIC_ORIGIN "$INSTALL_PUBLIC_ORIGIN"
+    elif [[ -n "${TALLYNOTE_HOST+x}" || -n "${TALLYNOTE_PORT+x}" ]]; then
+      local generated_origin_host=$INSTALL_HOST
+      [[ "$generated_origin_host" == *:* && "$generated_origin_host" != \[* ]] && generated_origin_host="[$generated_origin_host]"
+      set_env_key TALLYNOTE_PUBLIC_ORIGIN "http://${generated_origin_host}:${INSTALL_PORT}"
+    fi
+    if [[ "$INSTALL_PUBLIC_ORIGIN" == https://* ]]; then set_env_key TALLYNOTE_COOKIE_SECURE true; fi
+    set_env_key TALLYNOTE_ALLOW_INSECURE_HTTP "$INSTALL_ALLOW_INSECURE_HTTP"
+  elif [[ -n "${TALLYNOTE_PUBLIC_ORIGIN+x}" ]]; then
+    set_env_key TALLYNOTE_PUBLIC_ORIGIN "$INSTALL_PUBLIC_ORIGIN"
+  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"
   ensure_env_key TALLYNOTE_UPDATE_STRATEGY systemd
@@ -879,15 +1213,21 @@ main() {
       printf 'TALLYNOTE_UPDATE_PUBLIC_KEY_FILE=%s\n' "$CONFIG_DIR/update-signing-key.pub" >> "$CONFIG_DIR/tallynote.env"
     fi
   fi
+  stage_done 'systemd 单元、更新辅助程序和卸载器已安装'
+  stage '重新加载 systemd 并启动 TallyNote'
   chown root:root "$CONFIG_DIR/tallynote.env"
   chmod 640 "$CONFIG_DIR/tallynote.env"
   systemctl daemon-reload
   systemctl enable --now tallynote.service tallynote-update.path
+  stage_done 'TallyNote 服务已启用并启动'
+  stage '清理旧版本并完成安装'
   prune_releases
+  stage_done '旧版本清理完成'
   INSTALL_COMMITTED=1
   trap - EXIT
   rm -rf -- "$INSTALL_WORK_DIR" 2>/dev/null || true
   INSTALL_WORK_DIR=''
-  log 'installed; inspect with systemctl status tallynote.service'
+  stage_done "安装完成：TallyNote ${VERSION#v}"
+  log '查看服务状态：systemctl status tallynote.service'
 }
 main "$@"

migrations/0004_update_download_apply.sql

@@ -0,0 +1,2 @@
+ALTER TABLE update_jobs ADD COLUMN operation TEXT NOT NULL DEFAULT 'apply' CHECK(operation IN ('download','apply'));
+CREATE INDEX IF NOT EXISTS update_jobs_operation_idx ON update_jobs(operation, status, created_at);

package.json

@@ -1,6 +1,6 @@
 {
   "name": "tallynote",
-  "version": "1.1.2",
+  "version": "1.1.6",
   "private": true,
   "type": "module",
   "packageManager": "pnpm@9.0.6",

scripts/tallynote-update-runner.sh

@@ -13,6 +13,10 @@ STATE_FILE="$PREFIX/.update-state"
 SERVICE_NAME=${TALLYNOTE_SERVICE_NAME:-tallynote.service}
 HOST=${TALLYNOTE_HOST:-127.0.0.1}
 PORT=${TALLYNOTE_PORT:-3000}
+HEALTH_HOST=$HOST
+if [[ "$HEALTH_HOST" == 0.0.0.0 ]]; then HEALTH_HOST=127.0.0.1; fi
+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; }
 [[ ${EUID:-$(id -u)} -eq 0 ]] || die 'must run as root'
@@ -22,6 +26,26 @@ die() { printf 'tallynote update runner: %s\n' "$*" >&2; exit 1; }
 old_target=$(readlink -f -- "$CURRENT_LINK")
 [[ "$old_target" == "$PREFIX/releases/"* && -d "$old_target" ]] || die 'current release target is invalid'
 
+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)
+  [[ "$request_operation" == download || "$request_operation" == apply ]] || request_operation='apply'
+fi
+
+# 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.
+if [[ "$request_operation" == download ]]; then
+  node_bin="$CURRENT_LINK/runtime/bin/node"
+  [[ -x "$node_bin" ]] || node_bin=$(command -v node || true)
+  [[ -n "$node_bin" ]] || die 'node runtime not found'
+  cli="$CURRENT_LINK/dist/server/cli/update.js"
+  [[ -f "$cli" ]] || die 'update CLI not found in current release'
+  "$node_bin" "$cli" --request-file "$REQUEST_FILE" || exit $?
+  rm -f -- "$REQUEST_FILE"
+  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
@@ -202,7 +226,7 @@ write_update_state health-check || exit 1
 systemctl start "$SERVICE_NAME"
 healthy=0
 for _ in $(seq 1 30); do
-  if curl --proto '=http' --max-time 2 --silent --show-error "http://$HOST:$PORT/health" >/dev/null 2>&1; then healthy=1; break; fi
+  if curl --proto '=http' --max-time 2 --silent --show-error "http://$HEALTH_HOST:$PORT/health" >/dev/null 2>&1; then healthy=1; break; fi
   sleep 1
 done
 

scripts/test-installer.sh

@@ -4,12 +4,37 @@ root=$(cd "$(dirname "$0")/.." && pwd)
 bash -n "$root/install.sh" "$root/scripts/tallynote-update.sh"
 output=$(bash "$root/install.sh" --dry-run --release-base-url https://releases.example.test/releases)
 grep -q 'dry-run' <<<"$output"
+grep -q '\[阶段\] 检查运行环境' <<<"$output"
+grep -q '\[完成\] dry-run 预览完成' <<<"$output"
 output=$(bash "$root/install.sh" --dry-run --version 1.2.3 --release-base-url https://releases.example.test/releases)
 grep -q 'release: 1.2.3' <<<"$output"
+grep -q '\[阶段\] 使用指定版本：1.2.3' <<<"$output"
 if bash "$root/install.sh" --dry-run --release-base-url http://insecure.example.test/releases >/dev/null 2>&1; then
   echo 'expected non-HTTPS URL to fail' >&2
   exit 1
 fi
+if TALLYNOTE_HOST=0.0.0.0 bash "$root/install.sh" --dry-run --release-base-url https://releases.example.test/releases >/dev/null 2>&1; then
+  echo 'expected non-local listener without public origin to fail' >&2
+  exit 1
+fi
+output=$(TALLYNOTE_HOST=0.0.0.0 TALLYNOTE_PORT=3000 \
+  TALLYNOTE_PUBLIC_ORIGIN=http://203.0.113.10:3000 \
+  TALLYNOTE_ALLOW_INSECURE_HTTP=true \
+  bash "$root/install.sh" --dry-run --version 1.2.3 --release-base-url https://releases.example.test/releases)
+grep -q 'release: 1.2.3' <<<"$output"
+output=$(TALLYNOTE_HOST=::1 TALLYNOTE_PORT=3443 \
+  bash "$root/install.sh" --dry-run --version 1.2.3 --release-base-url https://releases.example.test/releases)
+grep -q 'release: 1.2.3' <<<"$output"
+if TALLYNOTE_HOST=0.0.0.0 TALLYNOTE_PORT=65536 TALLYNOTE_PUBLIC_ORIGIN=http://203.0.113.10:3000 TALLYNOTE_ALLOW_INSECURE_HTTP=true \
+  bash "$root/install.sh" --dry-run --release-base-url https://releases.example.test/releases >/dev/null 2>&1; then
+  echo 'expected invalid listener port to fail' >&2
+  exit 1
+fi
+if TALLYNOTE_HOST=0.0.0.0 TALLYNOTE_PUBLIC_ORIGIN=http://203.0.113.10:3000 \
+  bash "$root/install.sh" --dry-run --release-base-url https://releases.example.test/releases >/dev/null 2>&1; then
+  echo 'expected public HTTP without explicit opt-in to fail' >&2
+  exit 1
+fi
 tmp=$(mktemp -d)
 cleanup_tmp() {
   if [[ -d "$tmp" ]]; then
@@ -77,6 +102,182 @@ bash -c '
   fi
 ' _ "$installer_lib" "$duplicate_env"
 
+# Existing installations must validate the network settings they preserve on
+# upgrade, including the direct-IP HTTP combination used by the documented
+# installer command.
+network_env="$tmp/network.env"
+printf '%s\n' \
+  'TALLYNOTE_HOST=0.0.0.0' \
+  'TALLYNOTE_PORT=3000' \
+  'TALLYNOTE_PUBLIC_ORIGIN=http://203.0.113.10:3000' \
+  'TALLYNOTE_ALLOW_INSECURE_HTTP=true' > "$network_env"
+bash -c '
+  script=$1
+  env_file=$2
+  set --
+  source "$script"
+  PREFIX=/opt/tallynote
+  DATA_DIR=/var/lib/tallynote
+  stat_uid() { printf "0"; }
+  stat_mode_bits() { printf "384"; }
+  validate_existing_env "$env_file"
+' _ "$installer_lib" "$network_env"
+if sed 's/^TALLYNOTE_PORT=.*/TALLYNOTE_PORT=65536/' "$network_env" > "$tmp/invalid-port.env"; then
+  if bash -c '
+    script=$1
+    env_file=$2
+    set --
+    source "$script"
+    PREFIX=/opt/tallynote
+    DATA_DIR=/var/lib/tallynote
+    stat_uid() { printf "0"; }
+    stat_mode_bits() { printf "384"; }
+    validate_existing_env "$env_file"
+  ' _ "$installer_lib" "$tmp/invalid-port.env" >/dev/null 2>&1; then
+    echo 'expected invalid existing listener port to fail' >&2
+    exit 1
+  fi
+fi
+printf '%s\n' \
+  'TALLYNOTE_HOST=0.0.0.0' \
+  'TALLYNOTE_PORT=3000' \
+  'TALLYNOTE_PUBLIC_ORIGIN=http://203.0.113.10:3000' \
+  'TALLYNOTE_ALLOW_INSECURE_HTTP=false' > "$tmp/public-http-without-opt-in.env"
+if bash -c '
+  script=$1
+  env_file=$2
+  set --
+  source "$script"
+  PREFIX=/opt/tallynote
+  DATA_DIR=/var/lib/tallynote
+  stat_uid() { printf "0"; }
+  stat_mode_bits() { printf "384"; }
+  validate_existing_env "$env_file"
+' _ "$installer_lib" "$tmp/public-http-without-opt-in.env" >/dev/null 2>&1; then
+  echo 'expected public HTTP without opt-in in existing env to fail' >&2
+  exit 1
+fi
+bash -c '
+  script=$1
+  set --
+  source "$script"
+  PREFIX=/opt/tallynote
+  DATA_DIR=/var/lib/tallynote
+  stat_uid() { printf "0"; }
+  stat_mode_bits() { printf "384"; }
+  validate_public_origin "http://[2001:db8::10]:3000"
+' _ "$installer_lib"
+printf '%s\n' \
+  'TALLYNOTE_HOST=0.0.0.0' \
+  'TALLYNOTE_PORT=3000' \
+  'TALLYNOTE_PUBLIC_ORIGIN=https://tallynote.example.com' \
+  'TALLYNOTE_COOKIE_SECURE=true' > "$tmp/public-https.env"
+bash -c '
+  script=$1
+  env_file=$2
+  set --
+  source "$script"
+  PREFIX=/opt/tallynote
+  DATA_DIR=/var/lib/tallynote
+  stat_uid() { printf "0"; }
+  stat_mode_bits() { printf "384"; }
+  validate_existing_env "$env_file"
+' _ "$installer_lib" "$tmp/public-https.env"
+if bash -c '
+  script=$1
+  set --
+  source "$script"
+  validate_public_origin "http://example.test:65536"
+' _ "$installer_lib" >/dev/null 2>&1; then
+  echo 'expected invalid public origin port to fail' >&2
+  exit 1
+fi
+
+# A fresh interactive install reads from the controlling terminal even when
+# the installer script itself is piped from curl. The test substitutes files
+# for that terminal and verifies both listener choices without touching the
+# host filesystem.
+interactive_dir="$tmp/interactive"
+mkdir -p "$interactive_dir/config"
+printf '\n\n' > "$interactive_dir/local-input"
+: > "$interactive_dir/local-output"
+env -u TALLYNOTE_HOST -u TALLYNOTE_PORT -u TALLYNOTE_PUBLIC_ORIGIN -u TALLYNOTE_ALLOW_INSECURE_HTTP \
+  bash -c '
+    script=$1
+    dir=$2
+    set --
+    source "$script"
+    APPLY=1
+    NON_INTERACTIVE=0
+    CONFIG_DIR="$dir/config"
+    PROMPT_INPUT="$dir/local-input"
+    PROMPT_OUTPUT="$dir/local-output"
+    configure_network_interactively
+    [[ "$INSTALL_HOST" == 127.0.0.1 ]]
+    [[ "$INSTALL_PORT" == 3000 ]]
+    [[ "$INSTALL_PUBLIC_ORIGIN" == http://127.0.0.1:3000 ]]
+    [[ "$INSTALL_ALLOW_INSECURE_HTTP" == false ]]
+  ' _ "$installer_lib" "$interactive_dir"
+
+printf '2\n3443\nhttp://203.0.113.10:3443\nyes\n' > "$interactive_dir/public-input"
+: > "$interactive_dir/public-output"
+env -u TALLYNOTE_HOST -u TALLYNOTE_PORT -u TALLYNOTE_PUBLIC_ORIGIN -u TALLYNOTE_ALLOW_INSECURE_HTTP \
+  bash -c '
+    script=$1
+    dir=$2
+    set --
+    source "$script"
+    APPLY=1
+    NON_INTERACTIVE=0
+    CONFIG_DIR="$dir/config"
+    PROMPT_INPUT="$dir/public-input"
+    PROMPT_OUTPUT="$dir/public-output"
+    configure_network_interactively
+    [[ "$INSTALL_HOST" == 0.0.0.0 ]]
+    [[ "$INSTALL_PORT" == 3443 ]]
+    [[ "$INSTALL_PUBLIC_ORIGIN" == http://203.0.113.10:3443 ]]
+    [[ "$INSTALL_ALLOW_INSECURE_HTTP" == true ]]
+  ' _ "$installer_lib" "$interactive_dir"
+
+printf '2\n3000\nhttp://203.0.113.10:3000\nno\n' > "$interactive_dir/refuse-input"
+: > "$interactive_dir/refuse-output"
+if env -u TALLYNOTE_HOST -u TALLYNOTE_PORT -u TALLYNOTE_PUBLIC_ORIGIN -u TALLYNOTE_ALLOW_INSECURE_HTTP \
+  bash -c '
+    script=$1
+    dir=$2
+    set --
+    source "$script"
+    APPLY=1
+    NON_INTERACTIVE=0
+    CONFIG_DIR="$dir/config"
+    PROMPT_INPUT="$dir/refuse-input"
+    PROMPT_OUTPUT="$dir/refuse-output"
+    configure_network_interactively
+  ' _ "$installer_lib" "$interactive_dir" >/dev/null 2>&1; then
+  echo 'expected public HTTP confirmation refusal to stop configuration' >&2
+  exit 1
+fi
+
+# Explicit environment variables take precedence over the prompt, including
+# when a terminal is available.
+env -u TALLYNOTE_PUBLIC_ORIGIN -u TALLYNOTE_ALLOW_INSECURE_HTTP \
+  TALLYNOTE_HOST=0.0.0.0 TALLYNOTE_PORT=3000 \
+  bash -c '
+    script=$1
+    dir=$2
+    set --
+    source "$script"
+    APPLY=1
+    NON_INTERACTIVE=0
+    CONFIG_DIR="$dir/config"
+    PROMPT_INPUT="$dir/local-input"
+    PROMPT_OUTPUT="$dir/local-output"
+    if interactive_network_available; then
+      echo "expected explicit network environment to skip prompt" >&2
+      exit 1
+    fi
+  ' _ "$installer_lib" "$interactive_dir"
+
 # A release archive is extracted under umask 077, then explicitly normalized
 # so the tallynote system user can traverse and execute the shipped tree.
 source_tmp="$tmp/source"

scripts/test-uninstaller.sh

@@ -98,6 +98,20 @@ run_uninstall "$fixture" --purge-data --yes --purge-config
 [[ ! -e "$fixture/var/lib/tallynote" && ! -e "$fixture/var/lib/tallynote-backups" ]]
 [[ ! -e "$fixture/etc/tallynote" ]]
 
+# In production the service user owns the data directory. The target itself
+# must be accepted while its parent directories remain root-owned. This test
+# is meaningful only when the suite runs as root on a host with that account;
+# ordinary developer runs continue with the portable fixture coverage above.
+tallynote_uid=$(id -u tallynote 2>/dev/null || true)
+if [[ "$EUID" == 0 && -n "$tallynote_uid" && "$tallynote_uid" != "$(id -u)" ]]; then
+  fixture="$tmp/service-user-data"
+  make_fixture "$fixture"
+  make_systemctl "$fixture"
+  chown -R "$tallynote_uid" "$fixture/var/lib/tallynote"
+  TALLYNOTE_UNINSTALL_TEST_DATA_OWNER_UID="$tallynote_uid" run_uninstall "$fixture" --purge-data --yes
+  [[ ! -e "$fixture/var/lib/tallynote" ]]
+fi
+
 # A custom data path must not overlap the release prefix; otherwise removing
 # releases could destroy data that the default uninstall promises to keep.
 fixture="$tmp/overlap"

server/app.ts

@@ -23,6 +23,7 @@ import {
   permanentDeleteSchema,
   statusUpdateSchema,
   updateApplySchema,
+  updateDownloadSchema,
   versionSchema,
   type AttachmentKind,
   type ExpenseStatus,
@@ -94,7 +95,7 @@ const unsafeMethods = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 const sessionCookie = "tally_session";
 const csrfCookie = "tally_csrf";
 
-type UpdateRateState = { checkedAt: number; appliedAt: number };
+type UpdateRateState = { checkedAt: number; downloadedAt: number; appliedAt: number };
 const updateRateStates = new WeakMap<DatabaseContext["sqlite"], Map<string, UpdateRateState>>();
 
 function updateRateState(database: DatabaseContext["sqlite"], adminId: string): UpdateRateState {
@@ -105,7 +106,7 @@ function updateRateState(database: DatabaseContext["sqlite"], adminId: string):
   }
   let state = states.get(adminId);
   if (!state) {
-    state = { checkedAt: 0, appliedAt: 0 };
+    state = { checkedAt: 0, downloadedAt: 0, appliedAt: 0 };
     states.set(adminId, state);
   }
   return state;
@@ -115,13 +116,13 @@ function enforceUpdateCooldown(
   database: DatabaseContext["sqlite"],
   config: AppConfig,
   adminId: string,
-  operation: "check" | "apply",
+  operation: "check" | "download" | "apply",
   reply: FastifyReply,
 ): void {
   const state = updateRateState(database, adminId);
   const now = Date.now();
-  const previous = operation === "check" ? state.checkedAt : state.appliedAt;
-  const cooldown = operation === "check" ? config.updateCheckCooldownMs : config.updateApplyCooldownMs;
+  const previous = operation === "check" ? state.checkedAt : operation === "download" ? state.downloadedAt : state.appliedAt;
+  const cooldown = operation === "check" ? config.updateCheckCooldownMs : operation === "download" ? config.updateDownloadCooldownMs : config.updateApplyCooldownMs;
   if (cooldown > 0 && previous > 0 && now - previous < cooldown) {
     const retryAfter = Math.max(1, Math.ceil((cooldown - (now - previous)) / 1000));
     reply.header("Retry-After", retryAfter);
@@ -130,6 +131,7 @@ function enforceUpdateCooldown(
       : "更新操作过于频繁，请稍后再试");
   }
   if (operation === "check") state.checkedAt = now;
+  else if (operation === "download") state.downloadedAt = now;
   else state.appliedAt = now;
 }
 
@@ -932,9 +934,10 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
     reply.header("Cache-Control", "no-store");
     const cached = publicCheckFromCache(database.sqlite, config);
     const row = database.sqlite.prepare(`
-      SELECT id, status, version, platform, asset_name AS assetName,
+      SELECT id, operation, status, version, platform, asset_name AS assetName,
         size_bytes AS sizeBytes, error_message AS errorMessage,
-        created_at AS createdAt, updated_at AS updatedAt, completed_at AS completedAt
+        created_at AS createdAt, updated_at AS updatedAt, completed_at AS completedAt,
+        requested_at AS applyQueuedAt
       FROM update_jobs WHERE admin_id=? ORDER BY created_at DESC LIMIT 1
     `).get(request.auth!.admin.id) as Record<string, unknown> | undefined;
     return {
@@ -988,6 +991,37 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
     if (config.updateStrategy !== "systemd") {
       throw new AppError(503, "UPDATE_NOT_AVAILABLE", "当前安装方式未启用一键更新，请使用命令行更新");
     }
+    if (input.jobId) {
+      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", "更新任务尚未完成下载");
+      if (staged.operation === "apply") throw new AppError(409, "UPDATE_IN_PROGRESS", "更新任务正在处理中，请稍候");
+      enforceUpdateCooldown(database.sqlite, config, request.auth!.admin.id, "apply", reply);
+      const now = Date.now();
+      const active = database.sqlite.transaction(() => {
+        const conflictRow = database.sqlite.prepare(`SELECT id FROM update_jobs WHERE status IN (${ACTIVE_UPDATE_STATUSES.map(() => "?").join(",")}) AND id<>? LIMIT 1`).get(...ACTIVE_UPDATE_STATUSES, stagedJobId) as { id: string } | undefined;
+        if (conflictRow) throw new AppError(409, "UPDATE_IN_PROGRESS", "已有更新任务正在进行，请等待完成");
+        const changed = database.sqlite.prepare("UPDATE update_jobs SET operation='apply', error_message=NULL, requested_at=?, request_id=?, updated_at=? WHERE id=? AND status='staged' AND operation='download'").run(now, request.id, now, stagedJobId);
+        if (changed.changes !== 1) throw new AppError(409, "UPDATE_IN_PROGRESS", "更新任务正在处理中，请稍候");
+        writeAudit(database.sqlite, { requestId: request.id, actorAdminId: request.auth!.admin.id, actorUsername: request.auth!.admin.username, action: "update.apply_requested", targetType: "update", targetId: stagedJobId, after: { version: staged.version, staged: true } });
+        return { id: stagedJobId, now };
+      }).immediate();
+      applyAuditTarget = stagedJobId;
+      if (!staged.expectedSha256 || !/^[a-f0-9]{64}$/i.test(staged.expectedSha256)) {
+        database.sqlite.prepare("UPDATE update_jobs SET operation='download', error_message=?, updated_at=? WHERE id=? AND status='staged' AND operation='apply'").run("暂存更新缺少有效校验值", Date.now(), active.id);
+        throw new AppError(409, "UPDATE_NOT_VERIFIED", "暂存更新缺少有效校验值，请重新下载");
+      }
+      try {
+        await writeUpdateRequest(config, { jobId: active.id, operation: "apply", version: staged.version, metadataUrl: config.updateMetadataUrl, assetUrl: staged.assetUrl, assetName: staged.assetName ?? "staged", expectedSha256: staged.expectedSha256, requestedAt: active.now, currentLink: config.currentLink, releasesDir: config.releasesDir, dataDir: config.dataDir });
+      } catch {
+        database.sqlite.prepare("UPDATE update_jobs SET operation='download', error_message=?, updated_at=? WHERE id=? AND status='staged' AND operation='apply'").run("无法创建系统更新请求", Date.now(), active.id);
+        applyAuditRecorded = true;
+        writeAudit(database.sqlite, { requestId: request.id, actorAdminId: request.auth!.admin.id, actorUsername: request.auth!.admin.username, action: "update.apply_requested", targetType: "update", targetId: active.id, outcome: "failure" });
+        throw new AppError(503, "UPDATE_QUEUE_FAILED", "无法提交更新请求，请检查服务安装权限");
+      }
+      reply.header("Cache-Control", "no-store");
+      return reply.code(202).send({ job: { id: active.id, status: "staged", version: staged.version, operation: "apply", applyQueuedAt: active.now, restartWindowSeconds: 30 } });
+    }
     // Preserve the actionable in-progress response for duplicate clicks before
     // applying the per-admin cooldown.
     const activeBeforeCheck = database.sqlite.prepare(`
@@ -1055,8 +1089,9 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
       return { id, now };
     }).immediate();
     applyAuditTarget = active.id;
-    const updateRequest: UpdateRequest = {
-      jobId: active.id,
+      const updateRequest: UpdateRequest = {
+        jobId: active.id,
+        operation: "apply",
       version: requestedVersion,
       metadataUrl: cached.metadataUrl,
       assetUrl: releaseAsset.url,
@@ -1084,7 +1119,7 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
       throw new AppError(503, "UPDATE_QUEUE_FAILED", "无法提交更新请求，请检查服务安装权限");
     }
     reply.header("Cache-Control", "no-store");
-    return reply.code(202).send({ job: { id: active.id, status: "queued", version: requestedVersion } });
+    return reply.code(202).send({ job: { id: active.id, status: "queued", version: requestedVersion, operation: "apply", applyQueuedAt: active.now, restartWindowSeconds: 30 } });
     } catch (error) {
       if (!applyAuditRecorded) {
         writeAudit(database.sqlite, {
@@ -1101,12 +1136,43 @@ export async function buildApp(database: DatabaseContext, config: AppConfig) {
     }
   });
 
+  app.post("/api/update/download", { preHandler: guard(database, config), bodyLimit: 32 * 1024 }, async (request, reply) => {
+    const input = updateDownloadSchema.parse(request.body);
+    if (config.updateStrategy !== "systemd") throw new AppError(503, "UPDATE_NOT_AVAILABLE", "当前安装方式未启用一键更新，请使用命令行更新");
+    const active = database.sqlite.prepare(`SELECT id FROM update_jobs WHERE status IN (${ACTIVE_UPDATE_STATUSES.map(() => "?").join(",")}) LIMIT 1`).get(...ACTIVE_UPDATE_STATUSES) as { id: string } | undefined;
+    if (active) throw new AppError(409, "UPDATE_IN_PROGRESS", "已有更新任务正在进行，请等待完成");
+    enforceUpdateCooldown(database.sqlite, config, request.auth!.admin.id, "download", reply);
+    const checked = await checkForUpdate(database.sqlite, config);
+    const version = input.version.replace(/^v/i, "");
+    if (!checked.latest || checked.latest.version !== version || !checked.latest.isNewer || !checked.latest.compatible || !checked.latest.integrityReady) throw new AppError(409, "UPDATE_NOT_AVAILABLE", "该版本已不可用，请重新检查更新");
+    const cached = readCachedRelease(database.sqlite, config);
+    const cachedAsset = cached?.asset;
+    if (!cached || !cachedAsset?.sha256 || cached.version !== version) throw new AppError(409, "UPDATE_NOT_VERIFIED", "发布文件缺少 SHA-256 校验值，无法更新");
+    const now = Date.now();
+    const id = randomUUID();
+    database.sqlite.transaction(() => {
+      const conflict = database.sqlite.prepare(`SELECT id FROM update_jobs WHERE status IN (${ACTIVE_UPDATE_STATUSES.map(() => "?").join(",")}) LIMIT 1`).get(...ACTIVE_UPDATE_STATUSES) as { id: string } | undefined;
+      if (conflict) throw new AppError(409, "UPDATE_IN_PROGRESS", "已有更新任务正在进行，请等待完成");
+      database.sqlite.prepare(`INSERT INTO update_jobs(id, admin_id, session_hash, request_id, requested_at, operation, status, version, platform, release_url, asset_name, asset_url, expected_sha256, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'download', 'queued', ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, request.auth!.admin.id, request.auth!.tokenHash, request.id, now, version, checked.platform.target, cached.metadataUrl, cachedAsset.name, cachedAsset.url, cachedAsset.sha256, now, now);
+      writeAudit(database.sqlite, { requestId: request.id, actorAdminId: request.auth!.admin.id, actorUsername: request.auth!.admin.username, action: "update.download_requested", targetType: "update", targetId: id, after: { version } });
+    }).immediate();
+    try {
+      await writeUpdateRequest(config, { jobId: id, operation: "download", version, metadataUrl: cached.metadataUrl, assetUrl: cachedAsset.url, assetName: cachedAsset.name, expectedSha256: cachedAsset.sha256, requestedAt: now, currentLink: config.currentLink, releasesDir: config.releasesDir, dataDir: config.dataDir });
+    } catch {
+      database.sqlite.prepare("UPDATE update_jobs SET status='failed', error_message=?, updated_at=? WHERE id=?").run("无法创建系统更新请求", Date.now(), id);
+      throw new AppError(503, "UPDATE_QUEUE_FAILED", "无法提交更新请求，请检查服务安装权限");
+    }
+    reply.header("Cache-Control", "no-store");
+    return reply.code(202).send({ job: { id, status: "queued", operation: "download", version } });
+  });
+
   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);
     const row = database.sqlite.prepare(`
-      SELECT id, status, version, platform, asset_name AS assetName,
+      SELECT id, operation, status, version, platform, asset_name AS assetName,
         size_bytes AS sizeBytes, error_message AS errorMessage,
-        created_at AS createdAt, updated_at AS updatedAt, completed_at AS completedAt
+        created_at AS createdAt, updated_at AS updatedAt, completed_at AS completedAt,
+        requested_at AS applyQueuedAt
       FROM update_jobs WHERE id=? AND admin_id=?
     `).get(id, request.auth!.admin.id) as Record<string, unknown> | undefined;
     if (!row) notFound("更新任务不存在");

server/cli/update.ts

@@ -31,6 +31,7 @@ import type { UpdateJobStatus } from "../../shared/contracts.js";
 
 const updateRequestFileSchema = z.object({
   jobId: z.string().uuid(),
+  operation: z.enum(["download", "apply"]).default("apply"),
   version: z.string().regex(/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/),
   metadataUrl: z.string().url(),
   assetUrl: z.string().url(),
@@ -96,6 +97,8 @@ export type UpdateRunOptions = UrlPolicy & {
   jobId?: string | undefined;
   publicKey?: string | undefined;
   requireSignature?: boolean | undefined;
+  operation?: "download" | "apply" | undefined;
+  stagedPath?: string | undefined;
 };
 
 export type UpdateRunResult = {
@@ -140,21 +143,24 @@ function writeJob(sqlite: Database.Database | undefined, jobId: string, values:
   requestId?: string | undefined;
   requestedAt?: number | undefined;
   startedAt?: number | undefined;
+  operation?: "download" | "apply" | undefined;
 }): void {
   if (!sqlite) return;
   const now = Date.now();
+  const effectiveOperation = values.operation ?? (sqlite.prepare("SELECT operation FROM update_jobs WHERE id=?").get(jobId) as { operation?: "download" | "apply" } | undefined)?.operation ?? "apply";
   sqlite.prepare(`
     INSERT INTO update_jobs(id, admin_id, session_hash, request_id, requested_at, started_at,
-      status, version, platform, release_url, asset_name, asset_url,
+      operation, status, version, platform, release_url, asset_name, asset_url,
       expected_sha256, actual_sha256, download_path, backup_path, size_bytes, error_message,
       created_at, updated_at, completed_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT(id) DO UPDATE SET
       admin_id=COALESCE(excluded.admin_id, update_jobs.admin_id),
       session_hash=COALESCE(excluded.session_hash, update_jobs.session_hash),
       request_id=COALESCE(excluded.request_id, update_jobs.request_id),
       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,
       release_url=COALESCE(excluded.release_url, update_jobs.release_url),
       asset_name=COALESCE(excluded.asset_name, update_jobs.asset_name),
@@ -174,6 +180,7 @@ function writeJob(sqlite: Database.Database | undefined, jobId: string, values:
     values.requestId ?? null,
     values.requestedAt ?? null,
     values.startedAt ?? null,
+    effectiveOperation,
     values.status,
     values.version,
     values.platform,
@@ -238,9 +245,28 @@ async function ensurePrivilegedWorkspace(directory: string): Promise<string> {
   return resolved;
 }
 
+/** Validate a queued staged directory before a root process consumes it. */
+async function validateStagedWorkspacePath(candidate: string, workspaceRoot: string): Promise<string> {
+  const rootResolved = path.resolve(workspaceRoot);
+  const rootInfo = await lstat(rootResolved).catch(() => null);
+  const uid = typeof process.getuid === "function" ? process.getuid() : -1;
+  if (!rootInfo?.isDirectory() || rootInfo.isSymbolicLink() || (rootInfo.mode & 0o077) !== 0 || rootInfo.uid !== 0 || uid !== 0) {
+    throw new Error("更新工作目录权限无效");
+  }
+  const root = await realpath(rootResolved).catch(() => { throw new Error("更新工作目录无效"); });
+  const resolved = path.resolve(candidate);
+  if (resolved === rootResolved || !resolved.startsWith(`${rootResolved}${path.sep}`)) throw new Error("更新暂存路径无效");
+  const info = await lstat(resolved).catch(() => null);
+  if (!info?.isDirectory() || info.isSymbolicLink() || (info.mode & 0o077) !== 0 || info.uid !== 0) throw new Error("更新暂存目录权限无效");
+  const real = await realpath(resolved).catch(() => { throw new Error("更新暂存目录无效"); });
+  if (real !== resolved || !real.startsWith(`${root}${path.sep}`)) throw new Error("更新暂存路径无效");
+  return real;
+}
+
 export async function runUpdate(options: UpdateRunOptions): Promise<UpdateRunResult> {
   const platform = options.platform ?? detectPlatform();
   const jobId = options.jobId ?? randomUUID();
+  const operation = options.operation ?? "apply";
   let resolved: Awaited<ReturnType<typeof resolveRelease>> | undefined;
   try {
     resolved = await resolveRelease(options, platform);
@@ -250,27 +276,36 @@ export async function runUpdate(options: UpdateRunOptions): Promise<UpdateRunRes
     if (!expectedSha256) throw new Error("发布信息缺少 SHA-256 校验值");
     if (options.currentVersion && !isNewerVersion(options.currentVersion, resolved.version)) throw new Error("更新版本不是较新版本");
     writeJob(options.sqlite, jobId, {
-      status: "queued", version: resolved.version, platform: platform.target,
+      operation, status: "queued", version: resolved.version, platform: platform.target,
       releaseUrl: resolved.releaseUrl, assetName: resolved.asset.name, assetUrl: resolved.asset.url,
       expectedSha256, adminId: options.adminId, sessionHash: options.sessionHash,
       requestId: options.requestId, requestedAt: Date.now(),
     });
 
     await mkdir(options.stagingDir, { recursive: true, mode: 0o700 });
-    const workspace = await mkdtemp(path.join(path.resolve(options.stagingDir), `update-${jobId}-`));
+    let keepWorkspace = false;
+    const workspace = operation === "download"
+      ? path.join(path.resolve(options.stagingDir), `update-${jobId}`)
+      : await mkdtemp(path.join(path.resolve(options.stagingDir), `update-${jobId}-`));
+    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, { 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() });
+      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 downloaded = await downloadReleaseAsset(resolved.asset.url, archivePath, options);
       if (expectedSha256 && downloaded.sha256 !== expectedSha256) throw new Error("更新文件 SHA-256 校验失败");
-      updateJob(options.sqlite, jobId, { status: "verifying", 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: path.basename(archivePath) });
+      updateJob(options.sqlite, jobId, { operation, status: "verifying", 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: path.basename(archivePath) });
       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 });
       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, { 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: archivePath });
+      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;
+        return { jobId, version: resolved.version, asset: resolved.asset, archivePath };
+      }
 
       let backupArchivePath: string | undefined;
       if (options.dataBackupArchivePath && options.dataBackupSource) {
@@ -295,8 +330,10 @@ export async function runUpdate(options: UpdateRunOptions): Promise<UpdateRunRes
       updateJob(options.sqlite, jobId, { status: options.deferCompletion ? "applying" : "completed", 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: path.basename(archivePath), backupPath: switchedBackup ?? backupArchivePath, ...(options.deferCompletion ? {} : { completedAt }) });
       return { jobId, version: resolved.version, asset: resolved.asset, archivePath, ...(backupArchivePath ? { backupArchivePath } : {}), ...(switchedBackup ? { backupDir: switchedBackup } : {}) };
     } finally {
-      await rm(workspace, { recursive: true, force: true });
-      clearTransientJobPath(options.sqlite, jobId);
+      if (!keepWorkspace) {
+        await rm(workspace, { recursive: true, force: true });
+        clearTransientJobPath(options.sqlite, jobId);
+      }
     }
   } catch (error) {
     const fallbackVersion = resolved?.version ?? options.version ?? "0.0.0";
@@ -335,6 +372,59 @@ export function finalizeUpdateJob(
   })();
 }
 
+export async function applyStagedUpdate(options: {
+  sqlite: Database.Database;
+  jobId: string;
+  version: string;
+  stagedPath: string;
+  currentDir: string;
+  currentLink: string;
+  releasesDir: string;
+  backupArchivePath?: string;
+  dataBackupArchivePath?: string;
+  dataBackupSource?: string;
+  maxBytes?: number;
+  dataBackupMaxBytes?: number;
+  workspaceRoot?: string;
+}): Promise<void> {
+  const row = options.sqlite.prepare(`SELECT status, operation, version, platform, release_url AS releaseUrl, asset_name AS assetName, asset_url AS assetUrl, expected_sha256 AS expectedSha256, actual_sha256 AS actualSha256, size_bytes AS sizeBytes FROM update_jobs WHERE id=?`).get(options.jobId) as Record<string, unknown> | undefined;
+  if (!row || row.status !== "staged" || row.operation !== "apply") throw new Error("更新任务未处于待应用状态");
+  if (typeof row.version === "string" && row.version !== options.version) throw new Error("更新版本不一致");
+  const stagedPath = options.workspaceRoot
+    ? await validateStagedWorkspacePath(options.stagedPath, options.workspaceRoot)
+    : options.stagedPath;
+  const payload = path.join(stagedPath, "payload");
+  const payloadInfo = await lstat(payload).catch(() => null);
+  if (!payloadInfo?.isDirectory() || payloadInfo.isSymbolicLink()) throw new Error("更新暂存内容无效");
+  await normalizeReleasePermissions(payload);
+  let switchedBackup: string | undefined;
+  let committed = false;
+  try {
+    if (options.dataBackupArchivePath && options.dataBackupSource) {
+      updateJob(options.sqlite, options.jobId, { operation: "apply", status: "backing_up", version: options.version, platform: String(row.platform), releaseUrl: row.releaseUrl as string | undefined, assetName: row.assetName as string | undefined, assetUrl: String(row.assetUrl), expectedSha256: row.expectedSha256 as string | undefined, actualSha256: row.actualSha256 as string | undefined, sizeBytes: row.sizeBytes as number | undefined, downloadPath: stagedPath, backupPath: options.dataBackupArchivePath });
+      await createSafeArchive(options.dataBackupSource, options.dataBackupArchivePath, { maxBytes: options.dataBackupMaxBytes ?? 2 * 1024 * 1024 * 1024 });
+    }
+    if (options.backupArchivePath) {
+      updateJob(options.sqlite, options.jobId, { operation: "apply", status: "backing_up", version: options.version, platform: String(row.platform), releaseUrl: row.releaseUrl as string | undefined, assetName: row.assetName as string | undefined, assetUrl: String(row.assetUrl), expectedSha256: row.expectedSha256 as string | undefined, actualSha256: row.actualSha256 as string | undefined, sizeBytes: row.sizeBytes as number | undefined, downloadPath: stagedPath, backupPath: options.backupArchivePath });
+      const source = await realpath(options.currentDir).catch(() => options.currentDir);
+      await createSafeArchive(source, options.backupArchivePath, { maxBytes: options.maxBytes ?? 512 * 1024 * 1024 });
+    }
+    updateJob(options.sqlite, options.jobId, { operation: "apply", status: "applying", version: options.version, platform: String(row.platform), releaseUrl: row.releaseUrl as string | undefined, assetName: row.assetName as string | undefined, assetUrl: String(row.assetUrl), expectedSha256: row.expectedSha256 as string | undefined, actualSha256: row.actualSha256 as string | undefined, sizeBytes: row.sizeBytes as number | undefined, downloadPath: stagedPath, backupPath: options.backupArchivePath, startedAt: Date.now() });
+    switchedBackup = (await atomicSwitchRelease(payload, options.currentLink, options.releasesDir, options.version)).previousTarget;
+    committed = true;
+    await rm(stagedPath, { recursive: true, force: true }).catch(() => undefined);
+  } catch (error) {
+    if (!committed) {
+      await rm(stagedPath, { recursive: true, force: true }).catch(() => undefined);
+      updateJob(options.sqlite, options.jobId, { operation: "apply", status: "failed", version: options.version, platform: String(row.platform), assetUrl: String(row.assetUrl), errorMessage: safeErrorMessage(error) });
+      clearTransientJobPath(options.sqlite, options.jobId);
+    }
+    throw error;
+  }
+  updateJob(options.sqlite, options.jobId, { operation: "apply", status: "applying", version: options.version, platform: String(row.platform), assetUrl: String(row.assetUrl), expectedSha256: row.expectedSha256 as string | undefined, actualSha256: row.actualSha256 as string | undefined, sizeBytes: row.sizeBytes as number | undefined, backupPath: switchedBackup ?? options.backupArchivePath });
+  clearTransientJobPath(options.sqlite, options.jobId);
+}
+
 function arg(name: string): string | undefined {
   const index = process.argv.indexOf(name);
   return index >= 0 ? process.argv[index + 1] : undefined;
@@ -379,9 +469,36 @@ export async function main(config: AppConfig = loadConfig()): Promise<void> {
   prepareDataDirectories(config);
   if (request) await ensurePrivilegedWorkspace(stagingDir);
   else await mkdir(stagingDir, { recursive: true, mode: 0o700 });
-  const release = acquireInstanceLock(config);
+  // The download phase intentionally runs beside the live app so users keep
+  // access while the archive is fetched and staged. SQLite WAL plus the
+  // configured busy timeout serializes writes; the exclusive process lock is
+  // reserved for apply/rollback, when the service is stopped by systemd.
+  const release = request?.operation === "download" ? () => undefined : acquireInstanceLock(config);
   const database = openDatabase(config);
   try {
+    if (request?.operation === "apply") {
+      const staged = database.sqlite.prepare("SELECT download_path AS downloadPath, version FROM update_jobs WHERE id=? AND status='staged' AND operation='apply'").get(request.jobId) as { downloadPath: string | null; version: string } | undefined;
+      if (!staged?.downloadPath || staged.version !== request.version) throw new Error("更新暂存任务无效");
+      const root = path.resolve(config.updateWorkspaceDir);
+      const candidate = await validateStagedWorkspacePath(staged.downloadPath, root);
+      await applyStagedUpdate({
+        sqlite: database.sqlite,
+        jobId: request.jobId,
+        version: request.version,
+        stagedPath: candidate,
+        currentDir,
+        currentLink: request.currentLink,
+        releasesDir: request.releasesDir,
+        workspaceRoot: root,
+        ...(backupArchive ? { backupArchivePath: backupArchive } : {}),
+        ...(dataBackupArchive ? { dataBackupArchivePath: dataBackupArchive } : {}),
+        dataBackupSource: config.dataDir,
+        maxBytes: config.updateMaxBytes,
+        dataBackupMaxBytes: config.maxTotalBytes,
+      });
+      console.log(`更新已切换：${request.version}`);
+      return;
+    }
     const result = await runUpdate({
       ...(effectiveMetadataUrl ? { metadataUrl: effectiveMetadataUrl } : {}),
       ...(effectiveAssetUrl ? { assetUrl: effectiveAssetUrl } : {}),
@@ -398,6 +515,7 @@ export async function main(config: AppConfig = loadConfig()): Promise<void> {
       dataBackupMaxBytes: config.maxTotalBytes,
       currentVersion: config.appVersion,
       ...(deferCompletion ? { deferCompletion: true } : {}),
+      ...(request?.operation === "download" ? { operation: "download" as const } : {}),
       ...(request ? { jobId: request.jobId } : {}),
       publicKey: config.updatePublicKey,
       requireSignature: config.updateRequireSignature,

server/config.ts

@@ -69,7 +69,8 @@ export function loadConfig() {
   const installPrefix = path.resolve(process.env.TALLYNOTE_INSTALL_PREFIX ?? (updateStrategyRaw === "systemd" ? path.dirname(projectRoot) : projectRoot));
   const host = process.env.TALLYNOTE_HOST ?? "127.0.0.1";
   const port = integerEnv("TALLYNOTE_PORT", 3000, 1);
-  const publicOrigin = process.env.TALLYNOTE_PUBLIC_ORIGIN ?? `http://${host}:${port}`;
+  const originHost = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+  const publicOrigin = process.env.TALLYNOTE_PUBLIC_ORIGIN ?? `http://${originHost}:${port}`;
   let parsedOrigin: URL;
   try {
     parsedOrigin = new URL(publicOrigin);
@@ -88,7 +89,14 @@ export function loadConfig() {
 
   const isProduction = process.env.NODE_ENV === "production" || process.env.TALLYNOTE_ENV === "production";
   const cookieSecure = booleanEnv("TALLYNOTE_COOKIE_SECURE", parsedOrigin.protocol === "https:");
+  // Direct IP access is useful during a first deployment, but it is not
+  // encrypted. Keep this explicitly opt-in so a public install cannot
+  // accidentally expose session cookies over HTTP.
+  const allowInsecureHttp = booleanEnv("TALLYNOTE_ALLOW_INSECURE_HTTP", false);
   const publicHost = parsedOrigin.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  if (["0.0.0.0", "::"].includes(publicHost)) {
+    throw new Error("TALLYNOTE_PUBLIC_ORIGIN 不能使用通配监听地址，请填写服务器 IP 或域名");
+  }
   const localOrigin = ["127.0.0.1", "localhost", "::1"].includes(publicHost);
   const appVersion = (() => {
     try {
@@ -122,6 +130,7 @@ export function loadConfig() {
     timezone,
     trustProxy: trustProxyEnv(),
     cookieSecure,
+    allowInsecureHttp,
     appVersion,
     updateMetadataUrl,
     updateAllowedHosts,
@@ -142,6 +151,7 @@ export function loadConfig() {
     // cooldown so an authenticated account cannot turn the endpoint into an
     // outbound request flood; set to 0 only for controlled test environments.
     updateCheckCooldownMs: nonNegativeIntegerEnv("TALLYNOTE_UPDATE_CHECK_COOLDOWN_SECONDS", 60) * 1000,
+    updateDownloadCooldownMs: nonNegativeIntegerEnv("TALLYNOTE_UPDATE_DOWNLOAD_COOLDOWN_SECONDS", 15) * 1000,
     updateApplyCooldownMs: nonNegativeIntegerEnv("TALLYNOTE_UPDATE_APPLY_COOLDOWN_SECONDS", 15) * 1000,
     isLocalOrigin: localOrigin,
     dataDir,
@@ -165,7 +175,13 @@ export function loadConfig() {
     isProduction,
   };
 
-  if (!localOrigin && (parsedOrigin.protocol !== "https:" || !cookieSecure)) {
+  if (!localOrigin && parsedOrigin.protocol !== "https:" && !allowInsecureHttp) {
+    throw new Error("公网 HTTP 访问必须显式启用 TALLYNOTE_ALLOW_INSECURE_HTTP=true；生产环境建议使用 HTTPS");
+  }
+  if (!localOrigin && parsedOrigin.protocol !== "https:" && cookieSecure) {
+    throw new Error("HTTP public origin 不能启用安全 Cookie");
+  }
+  if (!localOrigin && parsedOrigin.protocol === "https:" && !cookieSecure) {
     throw new Error("公网部署必须使用 HTTPS 并启用安全 Cookie");
   }
   if (parsedOrigin.protocol === "https:" && !cookieSecure) {

server/db/schema.ts

@@ -136,6 +136,7 @@ export const updateJobs = sqliteTable("update_jobs", {
   adminId: text("admin_id").references(() => admins.id, { onDelete: "set null" }),
   sessionHash: text("session_hash"),
   requestId: text("request_id"),
+  operation: text("operation", { enum: ["download", "apply"] }).notNull().default("apply"),
   status: text("status", { enum: ["queued", "downloading", "verifying", "staged", "backing_up", "applying", "completed", "failed", "cancelled"] }).notNull(),
   version: text("version").notNull(),
   platform: text("platform").notNull(),

server/update-service.ts

@@ -14,6 +14,7 @@ import {
   sanitizeAssetName,
   selectReleaseAsset,
   validateHttpsUrl,
+  RELEASE_NOTES_MAX_BYTES,
   type ReleaseAsset,
   type ReleaseMetadata,
 } from "./update.js";
@@ -34,7 +35,10 @@ export type CachedRelease = {
   metadataUrl: string;
   version: string;
   tagName?: string;
+  releaseName?: string;
   publishedAt?: string;
+  notes?: string;
+  releaseUrl?: string;
   platform: string;
   signatureVerified?: boolean;
   asset?: {
@@ -53,7 +57,10 @@ export type UpdateCheckResult = {
   latest: {
     version: string;
     tagName?: string;
+    releaseName?: string;
     publishedAt?: string;
+    notes?: string;
+    releaseUrl?: string;
     compatible: boolean;
     integrityReady: boolean;
     signatureReady: boolean;
@@ -65,6 +72,7 @@ export type UpdateCheckResult = {
 
 export type UpdateRequest = {
   jobId: string;
+  operation?: "download" | "apply";
   version: string;
   metadataUrl: string;
   assetUrl: string;
@@ -76,6 +84,7 @@ export type UpdateRequest = {
   currentLink: string;
   releasesDir: string;
   dataDir: string;
+  stagedPath?: string;
 };
 
 function setting(database: Database.Database, key: string): string | undefined {
@@ -206,7 +215,10 @@ export async function checkForUpdate(database: Database.Database, config: AppCon
     metadataUrl,
     version: safeVersion,
     ...(metadata.tagName ? { tagName: metadata.tagName } : {}),
+    ...(metadata.releaseName ? { releaseName: metadata.releaseName } : {}),
     ...(metadata.publishedAt ? { publishedAt: metadata.publishedAt } : {}),
+    ...(metadata.notes ? { notes: metadata.notes } : {}),
+    ...(metadata.releaseUrl ? { releaseUrl: metadata.releaseUrl } : {}),
     platform: platform.target,
     signatureVerified,
     ...(asset ? {
@@ -227,7 +239,10 @@ export async function checkForUpdate(database: Database.Database, config: AppCon
     latest: {
       version: safeVersion,
       ...(metadata.tagName ? { tagName: metadata.tagName } : {}),
+      ...(metadata.releaseName ? { releaseName: metadata.releaseName } : {}),
       ...(metadata.publishedAt ? { publishedAt: metadata.publishedAt } : {}),
+      ...(metadata.notes ? { notes: metadata.notes } : {}),
+      ...(metadata.releaseUrl ? { releaseUrl: metadata.releaseUrl } : {}),
       compatible: Boolean(asset),
       integrityReady: Boolean(asset?.sha256 && (!config.updateRequireSignature || signatureVerified)),
       signatureReady: !config.updateRequireSignature || signatureVerified,
@@ -245,6 +260,9 @@ export function readCachedRelease(database: Database.Database, config: AppConfig
     if (!value || typeof value !== "object" || typeof value.version !== "string" || typeof value.metadataUrl !== "string" || typeof value.platform !== "string") return null;
     parseSemver(value.version);
     const metadataUrl = validateHttpsUrl(value.metadataUrl, policy(config)).toString();
+    if (value.releaseName !== undefined && (typeof value.releaseName !== "string" || value.releaseName.length > 200 || /[\u0000-\u001f\u007f]/.test(value.releaseName))) return null;
+    if (value.notes !== undefined && (typeof value.notes !== "string" || Buffer.byteLength(value.notes, "utf8") > RELEASE_NOTES_MAX_BYTES)) return null;
+    if (value.releaseUrl !== undefined) validateHttpsUrl(value.releaseUrl, policy(config));
     if (value.signatureVerified !== undefined && typeof value.signatureVerified !== "boolean") return null;
     if (value.asset) {
       if (typeof value.asset.name !== "string" || typeof value.asset.url !== "string") return null;
@@ -266,7 +284,10 @@ export function publicCheckFromCache(database: Database.Database, config: AppCon
     return { configured: config.updateStrategy !== "disabled", currentVersion: config.appVersion, platform, checkedAt: cached?.checkedAt ?? 0, latest: cached ? {
       version: cached.version,
       ...(cached.tagName ? { tagName: cached.tagName } : {}),
+      ...(cached.releaseName ? { releaseName: cached.releaseName } : {}),
       ...(cached.publishedAt ? { publishedAt: cached.publishedAt } : {}),
+      ...(cached.notes ? { notes: cached.notes } : {}),
+      ...(cached.releaseUrl ? { releaseUrl: cached.releaseUrl } : {}),
       compatible,
       integrityReady: compatible && Boolean(cached.asset?.sha256) && (!config.updateRequireSignature || cached.signatureVerified === true),
       signatureReady: !config.updateRequireSignature || cached.signatureVerified === true,
@@ -282,7 +303,10 @@ export function publicCheckFromCache(database: Database.Database, config: AppCon
     latest: {
       version: cached.version,
       ...(cached.tagName ? { tagName: cached.tagName } : {}),
+      ...(cached.releaseName ? { releaseName: cached.releaseName } : {}),
       ...(cached.publishedAt ? { publishedAt: cached.publishedAt } : {}),
+      ...(cached.notes ? { notes: cached.notes } : {}),
+      ...(cached.releaseUrl ? { releaseUrl: cached.releaseUrl } : {}),
       compatible: Boolean(cached.asset),
       integrityReady: Boolean(cached.asset?.sha256) && (!config.updateRequireSignature || cached.signatureVerified === true),
       signatureReady: !config.updateRequireSignature || cached.signatureVerified === true,
@@ -309,8 +333,11 @@ export async function writeUpdateRequest(config: AppConfig, request: UpdateReque
 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;
+  const updatedAt = typeof row.updatedAt === "number" ? row.updatedAt : null;
+  const expectedRecoveryAt = row.status === "applying" && updatedAt !== null ? updatedAt + 30_000 : null;
   return {
     id: row.id,
+    operation: row.operation ?? "apply",
     status: row.status,
     version: row.version,
     platform: row.platform,
@@ -323,5 +350,8 @@ export function publicUpdateJob(row: Record<string, unknown> | undefined): Recor
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
     completedAt: row.completedAt ?? null,
+    ...(row.applyQueuedAt ? { applyQueuedAt: row.applyQueuedAt } : {}),
+    ...(expectedRecoveryAt ? { expectedRecoveryAt } : {}),
+    ...(row.status === "applying" ? { restartWindowSeconds: 30 } : {}),
   };
 }

server/update.ts

@@ -35,7 +35,11 @@ export type ReleaseAsset = {
 export type ReleaseMetadata = {
   version: string;
   tagName?: string;
+  releaseName?: string;
   publishedAt?: string;
+  /** Plain-text release notes, bounded to keep API/cache payloads small. */
+  notes?: string;
+  releaseUrl?: string;
   assets: ReleaseAsset[];
 };
 
@@ -143,6 +147,57 @@ function metadataError(): Error {
 }
 
 const DEFAULT_METADATA_MAX_BYTES = 2 * 1024 * 1024;
+export const RELEASE_NOTES_MAX_BYTES = 64 * 1024;
+
+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
+  // endpoint/version. Keep the browser contract text-only and bounded.
+  const text = value
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/p\s*>/gi, "\n\n")
+    .replace(/<[^>]*>/g, "")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'")
+    .replace(/\r\n?/g, "\n")
+    .trim();
+  const bytes = Buffer.from(text, "utf8");
+  if (bytes.length <= RELEASE_NOTES_MAX_BYTES) return text;
+  return bytes.subarray(0, RELEASE_NOTES_MAX_BYTES).toString("utf8").replace(/\uFFFD$/u, "") + "\n[内容已截断]";
+}
+
+function releaseNameText(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const text = value.replace(/[\u0000-\u001f\u007f]/g, " ").trim();
+  return text.length > 0 ? text.slice(0, 200) : undefined;
+}
+
+/** Gitea installations behind a reverse proxy sometimes emit internal HTTP
+ * asset URLs. Rebind those URLs to the already trusted HTTPS release origin,
+ * while continuing to reject arbitrary HTTPS hosts and credentials. */
+function releaseResourceUrl(value: string, current: URL, options: UrlPolicy): string {
+  let candidate: URL;
+  try {
+    candidate = new URL(value, current);
+  } catch {
+    throw new Error("更新地址无效");
+  }
+  if (candidate.username || candidate.password) throw new Error("更新地址不允许携带凭据");
+  try {
+    return validateHttpsUrl(candidate, { ...options, baseUrl: current }).toString();
+  } catch {
+    if (candidate.protocol !== "http:") throw new Error("更新地址必须使用 HTTPS");
+    const rebound = new URL(current);
+    rebound.pathname = candidate.pathname;
+    rebound.search = candidate.search;
+    rebound.hash = "";
+    return validateHttpsUrl(rebound, { ...options, baseUrl: current }).toString();
+  }
+}
 
 /** Read a fetch body without ever buffering more than the caller's bound. */
 async function readBoundedResponse(response: Response, maxBytes: number, tooLargeMessage: string): Promise<Buffer> {
@@ -227,12 +282,24 @@ export async function fetchReleaseMetadata(
       const candidate = digest.replace(/^sha256:/i, "").toLowerCase();
       if (/^[a-f0-9]{64}$/.test(candidate)) sha256 = candidate;
     }
-    assets.push({ name, url: validateHttpsUrl(url, { ...options, baseUrl: current }).toString(), ...(sha256 ? { sha256 } : {}), ...(typeof asset.size === "number" && Number.isSafeInteger(asset.size) && asset.size >= 0 ? { size: asset.size } : {}) });
+    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,
   };
 }

shared/contracts.ts

@@ -93,12 +93,21 @@ export const updateJobStatusSchema = z.enum([
 ]);
 export type UpdateJobStatus = z.infer<typeof updateJobStatusSchema>;
 
+export const updateOperationSchema = z.enum(["download", "apply"]);
+export type UpdateOperation = z.infer<typeof updateOperationSchema>;
+
 /** The browser never supplies release URLs or filesystem paths. */
 export const updateApplySchema = z.object({
   // Keep the browser contract aligned with server/update.ts' SemVer parser,
   // including optional prerelease and build metadata segments.
   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),
+  jobId: z.string().uuid().optional(),
+}).strict();
+
+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),
 }).strict();
 
 export type ApiError = {

systemd/tallynote.env.example

@@ -4,12 +4,14 @@ TALLYNOTE_DATA_DIR=/var/lib/tallynote
 TALLYNOTE_INSTALL_PREFIX=/opt/tallynote
 TALLYNOTE_PUBLIC_ORIGIN=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_REQUIRE_SIGNATURE=false
 TALLYNOTE_UPDATE_CHECK_COOLDOWN_SECONDS=60
+TALLYNOTE_UPDATE_DOWNLOAD_COOLDOWN_SECONDS=15
 TALLYNOTE_UPDATE_APPLY_COOLDOWN_SECONDS=15
 # Optional: configure a root-managed Ed25519 public key and set
 # TALLYNOTE_UPDATE_REQUIRE_SIGNATURE=true to require detached signatures.

tests/migration.test.ts

@@ -41,9 +41,10 @@ describe("数据库迁移", () => {
         { name: "0001_invoice_missing_reason.sql" },
         { name: "0002_update_jobs.sql" },
         { name: "0003_update_job_ownership.sql" },
+        { name: "0004_update_download_apply.sql" },
       ]);
       const updateColumns = migrated.sqlite.prepare("PRAGMA table_info(update_jobs)").all() as Array<{ name: string }>;
-      expect(updateColumns.map((column) => column.name)).toEqual(expect.arrayContaining(["admin_id", "session_hash", "request_id", "requested_at", "started_at"]));
+      expect(updateColumns.map((column) => column.name)).toEqual(expect.arrayContaining(["admin_id", "session_hash", "request_id", "requested_at", "started_at", "operation"]));
       expect(migrated.sqlite.prepare("SELECT note, invoice_missing_reason AS reason FROM expenses WHERE id='00000000-0000-4000-8000-000000000099'").get()).toEqual({ note: "旧账目", reason: null });
       migrated.sqlite.close();
       migrated = openDatabase(config);

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_PUBLIC_ORIGIN", "TALLYNOTE_COOKIE_SECURE", "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]; });
 
@@ -13,11 +13,32 @@ describe("部署安全配置", () => {
   it("公网 HTTP 或 HTTPS 非安全 Cookie 一律拒绝", () => {
     process.env.TALLYNOTE_PUBLIC_ORIGIN = "http://example.test";
     expect(() => loadConfig()).toThrow(/HTTPS/);
+    process.env.TALLYNOTE_ALLOW_INSECURE_HTTP = "true";
+    expect(loadConfig().allowInsecureHttp).toBe(true);
+    process.env.TALLYNOTE_COOKIE_SECURE = "true";
+    expect(() => loadConfig()).toThrow(/安全 Cookie/);
     process.env.TALLYNOTE_PUBLIC_ORIGIN = "https://example.test";
     process.env.TALLYNOTE_COOKIE_SECURE = "false";
     expect(() => loadConfig()).toThrow(/安全 Cookie/);
   });
 
+  it("允许显式配置服务器 IP 的直连 HTTP，并拒绝通配 Origin", () => {
+    process.env.TALLYNOTE_HOST = "0.0.0.0";
+    process.env.TALLYNOTE_PORT = "3000";
+    process.env.TALLYNOTE_PUBLIC_ORIGIN = "http://192.0.2.10:3000";
+    process.env.TALLYNOTE_ALLOW_INSECURE_HTTP = "true";
+    process.env.TALLYNOTE_COOKIE_SECURE = "false";
+    expect(loadConfig()).toMatchObject({ host: "0.0.0.0", port: 3000, publicOrigin: "http://192.0.2.10:3000", allowInsecureHttp: true });
+    process.env.TALLYNOTE_PUBLIC_ORIGIN = "http://0.0.0.0:3000";
+    expect(() => loadConfig()).toThrow(/通配监听地址/);
+  });
+
+  it("为 IPv6 监听地址生成合法的默认 Origin", () => {
+    process.env.TALLYNOTE_HOST = "::1";
+    process.env.TALLYNOTE_PORT = "3000";
+    expect(loadConfig().publicOrigin).toBe("http://[::1]:3000");
+  });
+
   it("生产环境不接受任意 trust proxy", () => {
     process.env.NODE_ENV = "production";
     process.env.TALLYNOTE_TRUST_PROXY = "true";

tests/update-api.test.ts

@@ -59,10 +59,10 @@ describe("更新 API", () => {
 
   function mockRelease() {
     const digest = "c".repeat(64);
-    const asset = `tallynote-1.1.3-${detectPlatform().target}-glibc.tar.gz`;
+    const asset = `tallynote-1.1.7-${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.1.3", 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.1.7", 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,21 +70,21 @@ 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.1.3", compatible: true, integrityReady: true, isNewer: true });
+    expect(checked.json().latest).toMatchObject({ version: "1.1.7", 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);
     expect(tooSoon.headers["retry-after"]).toBeDefined();
 
-    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.1.3", 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.1.7", 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.1.3", expectedSha256: "c".repeat(64), currentLink: config.currentLink });
+    expect(request).toMatchObject({ jobId, version: "1.1.7", 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.1.3", 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.1.7", 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 } });
@@ -93,9 +93,38 @@ describe("更新 API", () => {
     expect(audit.map((row) => row.action)).toEqual(expect.arrayContaining(["update.checked", "update.apply_requested"]));
   });
 
+  it("先下载并暂存更新包，再由同一管理员认领应用", async () => {
+    const session = await login("update-staged");
+    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.1.7", 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.1.7" });
+    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" });
+    database.sqlite.prepare("UPDATE update_jobs SET status='failed', error_message='test', updated_at=? WHERE id=?").run(Date.now(), downloadJobId);
+
+    const stagedId = randomUUID();
+    const now = Date.now();
+    database.sqlite.prepare(`INSERT INTO update_jobs(id, admin_id, session_hash, request_id, requested_at, operation, status, version, platform, release_url, asset_name, asset_url, expected_sha256, actual_sha256, download_path, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'download', 'staged', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+      .run(stagedId, (await database.sqlite.prepare("SELECT id FROM admins WHERE username=?").get("update-staged") as { id: string }).id, "session", "staged-request", now, "1.1.7", 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.1.7", 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.1.7", 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.1.3" } });
+    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.1.7" } });
     expect(invalid.statusCode).toBe(400);
     process.env.TALLYNOTE_UPDATE_STRATEGY = "disabled";
     const disabledConfig = loadConfig();
@@ -108,7 +137,7 @@ describe("更新 API", () => {
     mockRelease();
     const checked = await app.inject({ method: "POST", url: "/api/update/check", headers: { origin: config.publicOrigin, cookie: owner.cookies, "x-csrf-token": owner.csrf }, payload: {} });
     expect(checked.statusCode).toBe(200);
-    const applied = await app.inject({ method: "POST", url: "/api/update/apply", headers: { origin: config.publicOrigin, cookie: owner.cookies, "x-csrf-token": owner.csrf }, payload: { version: "1.1.3", 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.1.7", 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);
@@ -126,7 +155,7 @@ describe("更新 API", () => {
   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.1.3", 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.1.7", confirm: true } });
     expect(response.statusCode).toBe(502);
     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");

tests/update.test.ts

@@ -273,17 +273,17 @@ describe("更新元数据缓存", () => {
     prepareDataDirectories(config);
     const database = openDatabase(config);
     const digest = "b".repeat(64);
-    const platformAsset = `tallynote-1.1.3-${detectPlatform().target}-glibc.tar.gz`;
+    const platformAsset = `tallynote-1.1.7-${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.1.3", 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.1.7", 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.1.3", compatible: true, integrityReady: true, signatureReady: true, isNewer: true });
+      expect(result.latest).toMatchObject({ version: "1.1.7", compatible: true, integrityReady: true, signatureReady: true, isNewer: true });
       const cached = database.sqlite.prepare("SELECT value FROM system_settings WHERE key='update.release.v1'").get() as { value: string };
       expect(JSON.parse(cached.value).asset.sha256).toBe(digest);
     } finally {

uninstall.sh

@@ -10,6 +10,7 @@ umask 077
 
 TEST_MODE=${TALLYNOTE_UNINSTALL_TEST_MODE:-false}
 TEST_ROOT=${TALLYNOTE_UNINSTALL_ROOT:-}
+TEST_DATA_OWNER_UID=${TALLYNOTE_UNINSTALL_TEST_DATA_OWNER_UID:-}
 PREFIX=${TALLYNOTE_PREFIX:-/opt/tallynote}
 DATA_DIR=${TALLYNOTE_DATA_DIR:-/var/lib/tallynote}
 CONFIG_DIR=${TALLYNOTE_CONFIG_DIR:-/etc/tallynote}
@@ -103,7 +104,7 @@ allowed_data_owner() {
   local path=$1 uid tallynote_uid
   uid=$(stat_uid "$path")
   if [[ "$TEST_MODE" == true ]]; then
-    [[ "$uid" == "$(id -u)" || "$uid" == 0 ]]
+    [[ "$uid" == "$(id -u)" || "$uid" == 0 || ( -n "$TEST_DATA_OWNER_UID" && "$uid" == "$TEST_DATA_OWNER_UID" ) ]]
     return
   fi
   [[ "$uid" == 0 ]] && return 0
@@ -130,7 +131,13 @@ validate_parent_chain() {
     if [[ -L "$current" ]]; then die "路径不能包含符号链接：$current"; fi
     if [[ -e "$current" ]]; then
       [[ -d "$current" ]] || die "路径不是目录：$current"
-      allowed_owner "$current" || die "路径目录的所有者不受信任：$current"
+      # The target itself is checked by validate_target with its path-specific
+      # owner policy (data may belong to the tallynote service user). Keep all
+      # ancestor directories root-owned, but do not apply that policy twice to
+      # the final target.
+      if [[ "$current" != "$target" ]]; then
+        allowed_owner "$current" || die "路径目录的所有者不受信任：$current"
+      fi
       local mode_bits
       mode_bits=$(stat_mode_bits "$current")
       (( (mode_bits & 18) == 0 || (mode_bits & 512) != 0 )) || die "路径目录权限过宽：$current"

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

@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from "react";
-import { AlertCircle, CheckCircle2, Download, RefreshCw, Server, ShieldCheck, Terminal } from "lucide-react";
+import { AlertCircle, CheckCircle2, Download, RefreshCw, Server, ShieldCheck, Terminal, Zap } from "lucide-react";
 import { Button, Dialog, Tag } from "tdesign-react";
 import { ApiError, api } from "../../services/api";
 import { dateText } from "../expenses/date";
@@ -7,10 +7,23 @@ import { ErrorBanner, Page, Surface } from "../common";
 import type { Notify } from "../expenses/types";
 
 type JobStatus = "queued" | "downloading" | "verifying" | "staged" | "backing_up" | "applying" | "completed" | "failed" | "cancelled";
-type UpdateJob = { id: string; status: JobStatus; version: string; platform: string; assetName?: string | null; sizeBytes?: number | null; errorMessage?: string | null; createdAt: number; updatedAt: number; completedAt?: number | null };
-type UpdateInfo = { configured: boolean; strategy: "disabled" | "systemd"; currentVersion: string; platform: { target: string; os: string; arch: string }; checkedAt: number; latest: { version: string; tagName?: string; publishedAt?: string; compatible: boolean; integrityReady: boolean; signatureReady: boolean; isNewer: boolean; assetName?: string; assetSize?: number } | null; job: UpdateJob | null };
+type UpdateJob = { id: string; operation?: "download" | "apply"; status: JobStatus; version: string; platform: string; assetName?: string | null; sizeBytes?: number | null; errorMessage?: string | null; createdAt?: number; updatedAt?: number; completedAt?: number | null; applyQueuedAt?: number | string | null; restartWindowSeconds?: number | null; restartDeadline?: number | string | null; restartAt?: number | string | null; expectedRecoveryAt?: number | string | null };
+type LatestRelease = { version: string; tagName?: string; releaseName?: string; publishedAt?: string; compatible: boolean; integrityReady: boolean; signatureReady: boolean; isNewer: boolean; assetName?: string; assetSize?: number; notes?: string | null; releaseNotes?: string | null; body?: string | null; htmlUrl?: string | null };
+type UpdateInfo = { configured: boolean; strategy: "disabled" | "systemd"; currentVersion: string; platform: { target: string; os: string; arch: string }; checkedAt: number; latest: LatestRelease | null; job: UpdateJob | null };
 const active = new Set<JobStatus>(["queued", "downloading", "verifying", "staged", "backing_up", "applying"]);
-const labels: Record<JobStatus, string> = { queued: "等待系统服务", downloading: "下载中", verifying: "校验文件", staged: "准备完成", backing_up: "备份数据", applying: "切换并检查服务", completed: "已完成", failed: "失败", cancelled: "已取消" };
+const pollable = new Set<JobStatus>(["queued", "downloading", "verifying", "backing_up", "applying"]);
+const labels: Record<JobStatus, string> = { queued: "等待系统服务", downloading: "下载中", verifying: "校验文件", staged: "下载完成，等待应用", backing_up: "备份数据", applying: "切换并检查服务", completed: "已完成", failed: "失败", cancelled: "已取消" };
+
+function timestamp(value: number | string | null | undefined): number | null {
+  if (value === null || value === undefined || value === "") return null;
+  const n = typeof value === "number" ? value : Date.parse(value);
+  if (!Number.isFinite(n)) return null;
+  return n < 10_000_000_000 ? n * 1000 : n;
+}
+function notesFor(latest: LatestRelease): string | null {
+  const value = latest.notes ?? latest.releaseNotes ?? latest.body;
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
 
 export default function UpdatePage({ timezone = "Asia/Shanghai", notify }: { timezone?: string; notify?: Notify }) {
   const [info, setInfo] = useState<UpdateInfo | null>(null);
@@ -19,95 +32,91 @@ export default function UpdatePage({ timezone = "Asia/Shanghai", notify }: { tim
   const [error, setError] = useState("");
   const [pollError, setPollError] = useState("");
   const [confirmVersion, setConfirmVersion] = useState<string | null>(null);
-  const [applying, setApplying] = useState(false);
+  const [confirmAction, setConfirmAction] = useState<"download" | "apply">("download");
+  const [actionBusy, setActionBusy] = useState(false);
   const [reloadReady, setReloadReady] = useState(false);
+  const [now, setNow] = useState(() => Date.now());
   const announced = useRef<string | null>(null);
   const checkInFlight = useRef(false);
-  const applyInFlight = useRef(false);
+  const actionInFlight = useRef(false);
+  const disconnected = useRef(false);
+  const recoveredNotice = useRef(false);
 
   const load = async () => { setLoading(true); setError(""); try { setInfo(await api<UpdateInfo>("/api/update/status")); } catch (e) { setError((e as Error).message); } finally { setLoading(false); } };
   useEffect(() => { void load(); }, []);
+  const job = info?.job;
+  const applyQueuedAt = timestamp(job?.applyQueuedAt);
+  const restartAt = timestamp(job?.restartDeadline)
+    ?? timestamp(job?.restartAt)
+    ?? timestamp(job?.expectedRecoveryAt)
+    ?? (job?.operation === "apply" && applyQueuedAt ? applyQueuedAt + (job.restartWindowSeconds ?? 30) * 1000 : null)
+    ?? (job?.status === "applying" && job.updatedAt ? timestamp(job.updatedAt)! + 30_000 : null);
+  const restartSeconds = restartAt ? Math.max(0, Math.ceil((restartAt - now) / 1000)) : null;
+  useEffect(() => { if (!restartAt) return; const timer = window.setInterval(() => setNow(Date.now()), 1000); return () => window.clearInterval(timer); }, [restartAt]);
+
   useEffect(() => {
-    const job = info?.job;
-    if (!job) { setPollError(""); return; }
-    const announceCompletion = (completedJob: UpdateJob) => {
-      if (completedJob.status === "completed" && announced.current !== completedJob.id) {
-        announced.current = completedJob.id;
-        setReloadReady(true);
-        notify?.("更新完成，请重新加载页面", "success");
-      }
-    };
-    if (job.status === "completed") {
-      setPollError("");
-      announceCompletion(job);
-      return;
-    }
-    if (!active.has(job.status)) { setPollError(""); return; }
-    let disposed = false;
-    let timer: number | undefined;
-    let failureCount = 0;
+    const shouldPoll = Boolean(job && (pollable.has(job.status) || (job.status === "staged" && job.operation === "apply")));
+    if (!shouldPoll || !job) { setPollError(""); return; }
+    let disposed = false; let timer: number | undefined; let failures = 0;
     const schedule = (delay: number) => { timer = window.setTimeout(() => void poll(), delay); };
     const poll = async () => {
       try {
         const result = await api<{ job: UpdateJob }>(`/api/update/jobs/${job.id}`);
         if (disposed) return;
-        failureCount = 0;
-        setPollError("");
+        failures = 0;
+        if (disconnected.current && !recoveredNotice.current) { recoveredNotice.current = true; notify?.("服务已恢复，更新状态已刷新", "success"); }
+        disconnected.current = false; setPollError("");
         setInfo(current => current ? { ...current, job: result.job } : current);
-        announceCompletion(result.job);
-        if (active.has(result.job.status)) schedule(1500);
-      } catch (caught) {
+        if (result.job.status === "completed" && announced.current !== result.job.id) { announced.current = result.job.id; setReloadReady(true); notify?.("更新完成，请重新加载页面", "success"); }
+        if (pollable.has(result.job.status) || (result.job.status === "staged" && result.job.operation === "apply")) schedule(1500);
+      } catch {
         if (disposed) return;
-        failureCount += 1;
-        setPollError(`${(caught as Error).message}。更新任务仍在后台运行，页面会自动重试。`);
-        schedule(Math.min(1500 * (2 ** Math.min(failureCount, 3)), 12_000));
+        failures += 1; disconnected.current = true; recoveredNotice.current = false;
+        setPollError(`服务暂时不可用${restartSeconds !== null ? `，预计 ${restartSeconds} 秒后恢复` : "，页面会自动重试"}。更新任务仍在后台运行。`);
+        schedule(Math.min(1500 * (2 ** Math.min(failures, 3)), 12_000));
       }
     };
     void poll();
     return () => { disposed = true; if (timer !== undefined) window.clearTimeout(timer); };
-  }, [info?.job?.id, info?.job?.status, notify]);
+  }, [job?.id, job?.status, job?.operation, notify]);
+
   const check = async () => {
     if (checkInFlight.current) return;
-    checkInFlight.current = true;
-    setChecking(true);
-    setError("");
+    checkInFlight.current = true; setChecking(true); setError("");
     try {
       const result = await api<Omit<UpdateInfo, "job"> & { job?: UpdateJob | null }>("/api/update/check", { method: "POST", body: "{}" });
-      setInfo(current => ({ ...result, job: result.job ?? current?.job ?? null }));
-      notify?.(result.latest?.isNewer ? "发现新版本" : "当前已是最新版本", "success");
+      setInfo(current => ({ ...result, job: result.job ?? current?.job ?? null })); notify?.(result.latest?.isNewer ? "发现新版本" : "当前已是最新版本", "success");
     } catch (caught) {
-      // A configured release source is intentionally rate-limited. A repeated
-      // click should still be useful: show the cached status instead of a
-      // blocking error, while preserving the server-side flood protection.
-      if (caught instanceof ApiError && caught.code === "UPDATE_RATE_LIMITED") {
-        try {
-          await load();
-          const seconds = caught.retryAfter ? `，请 ${caught.retryAfter} 秒后再检查` : "，请稍后再检查";
-          notify?.(`已显示最近一次检查结果${seconds}`, "info");
-          return;
-        } catch {
-          // Fall through to the normal error surface if the status read fails.
-        }
-      }
+      if (caught instanceof ApiError && caught.code === "UPDATE_RATE_LIMITED") { try { await load(); notify?.(`已显示最近一次检查结果${caught.retryAfter ? `，请 ${caught.retryAfter} 秒后再检查` : "，请稍后再检查"}`, "info"); return; } catch { /* fall through */ } }
       setError((caught as Error).message);
-    } finally {
-      checkInFlight.current = false;
-      setChecking(false);
-    }
+    } finally { checkInFlight.current = false; setChecking(false); }
+  };
+  const submitAction = async () => {
+    if (!confirmVersion || actionInFlight.current) return;
+    actionInFlight.current = true; setActionBusy(true); setError("");
+    try {
+      const endpoint = confirmAction === "download" ? "/api/update/download" : "/api/update/apply";
+      const body = confirmAction === "download" ? { version: confirmVersion, confirm: true } : { jobId: job?.id, version: confirmVersion, confirm: true };
+      const result = await api<{ job: UpdateJob }>(endpoint, { method: "POST", body: JSON.stringify(body) });
+      setConfirmVersion(null); setReloadReady(false); setInfo(current => current ? { ...current, job: result.job } : current); notify?.(confirmAction === "download" ? "更新包下载已开始" : "更新已开始，服务会短暂重启", "info");
+    } catch (caught) { setError((caught as Error).message); } finally { actionInFlight.current = false; setActionBusy(false); }
   };
-  const apply = async () => { if (!confirmVersion || applyInFlight.current) return; applyInFlight.current = true; setApplying(true); setError(""); try { const result = await api<{ job: UpdateJob }>("/api/update/apply", { method: "POST", body: JSON.stringify({ version: confirmVersion, confirm: true }) }); setConfirmVersion(null); setInfo(current => current ? { ...current, job: result.job } : current); notify?.("更新请求已提交，服务会短暂重启", "info"); } catch (e) { setError((e as Error).message); } finally { applyInFlight.current = false; setApplying(false); } };
-  const latest = info?.latest; const job = info?.job; const canApply = Boolean(info?.strategy === "systemd" && latest?.isNewer && latest.compatible && latest.integrityReady && !job || info?.strategy === "systemd" && latest?.isNewer && latest.compatible && latest.integrityReady && job && !active.has(job.status));
-  const progress = job ? ({ queued: 8, downloading: 28, verifying: 48, staged: 65, backing_up: 80, applying: 92 } as Partial<Record<JobStatus, number>>)[job.status] ?? 100 : 0;
 
-  return <Page title="系统更新" subtitle="检查受信任的 Release；更新前会校验文件并保护现有数据。" actions={<Button variant="outline" onClick={() => void check()} disabled={checking || loading} icon={<RefreshCw size={15} />}>{checking ? "检查中…" : "检查更新"}</Button>}>
-    {error && <ErrorBanner message={error} onRetry={() => void load()} />}
-    {pollError && <ErrorBanner message={pollError} />}
+  const latest = info?.latest; const hasActiveJob = Boolean(job && active.has(job.status));
+  const sameCompleted = Boolean(job?.status === "completed" && latest && job.version === latest.version);
+  const canDownload = Boolean(info?.strategy === "systemd" && latest?.isNewer && latest.compatible && latest.integrityReady && !hasActiveJob && !sameCompleted && (!job || job.version !== latest.version || job.status === "failed" || job.status === "cancelled"));
+  const canApply = Boolean(info?.strategy === "systemd" && latest?.isNewer && latest.compatible && latest.integrityReady && job?.operation === "download" && job.status === "staged" && job.version === latest.version);
+  const progress = job ? ({ queued: 8, downloading: 28, verifying: 48, staged: 65, backing_up: 80, applying: 92 } as Partial<Record<JobStatus, number>>)[job.status] ?? 100 : 0;
+  const notes = latest ? notesFor(latest) : null;
+
+  return <Page title="系统更新" subtitle="检查受信任的 Release；更新前会校验文件并保护现有数据。" actions={<Button variant="outline" onClick={() => void check()} disabled={checking || loading || hasActiveJob} icon={<RefreshCw size={15} />}>{checking ? "检查中…" : "检查更新"}</Button>}>
+    {error && <ErrorBanner message={error} onRetry={() => void load()} />}{pollError && <ErrorBanner message={pollError} />}
     {loading ? <div className="tn-empty" role="status" aria-live="polite">正在读取版本信息…</div> : info && <>
       <div className="tn-update-grid"><Surface className="tn-update-block"><Server size={20} /><span className="tn-eyebrow">当前版本</span><strong className="tn-update-value">v{info.currentVersion}</strong><small>运行平台：{info.platform.target}</small></Surface><Surface className="tn-update-block"><ShieldCheck size={20} /><span className="tn-eyebrow">更新方式</span><strong>{info.strategy === "systemd" ? "后台一键更新" : "手动命令行更新"}</strong><small>{info.strategy === "systemd" ? (info.configured ? "由 systemd 更新服务执行" : "尚未配置发布源") : "当前安装未启用后台更新"}</small></Surface></div>
-      {latest ? <Surface className="tn-update-release"><div className="tn-update-release-head"><div><span className="tn-eyebrow">最新 Release</span><h2>{latest.tagName || `v${latest.version}`}</h2>{latest.publishedAt && <small>发布时间：{dateText(Date.parse(latest.publishedAt), timezone)}</small>}</div><Tag theme={latest.isNewer ? "primary" : "success"}>{latest.isNewer ? "有新版本" : "已是最新"}</Tag></div><div className="tn-facts"><div><span>平台文件</span><strong>{latest.compatible ? latest.assetName : "无匹配文件"}</strong></div><div><span>完整性</span><strong className={latest.integrityReady ? "text-success" : "text-danger"}>{latest.integrityReady ? "SHA-256 + 签名可验证" : "不可验证"}</strong></div><div><span>文件大小</span><strong>{latest.assetSize ? `${(latest.assetSize / 1024 / 1024).toFixed(1)} MB` : "-"}</strong></div></div>{latest.isNewer && !latest.compatible && <div className="tn-inline-error"><AlertCircle size={16} />当前平台没有可安装的 Release 文件。</div>}{latest.isNewer && latest.compatible && !latest.integrityReady && <div className="tn-inline-error"><AlertCircle size={16} />发布文件缺少完整校验，已禁用更新。</div>}<div className="tn-page-actions">{canApply && <Button theme="primary" onClick={() => setConfirmVersion(latest.version)} disabled={applying} icon={<Download size={16} />}>更新到 v{latest.version}</Button>}{reloadReady && <Button theme="primary" onClick={() => window.location.reload()}>重新加载</Button>}</div></Surface> : <div className="tn-empty">点击“检查更新”获取最新 Release。</div>}
+      {latest ? <Surface className="tn-update-release"><div className="tn-update-release-head"><div><span className="tn-eyebrow">最新 Release</span><h2>{latest.releaseName || latest.tagName || `v${latest.version}`}</h2>{latest.publishedAt && <small>发布时间：{dateText(Date.parse(latest.publishedAt), timezone)}</small>}</div><Tag theme={latest.isNewer ? "primary" : "success"}>{latest.isNewer ? "有新版本" : "已是最新"}</Tag></div>{notes && <div className="tn-release-notes"><span className="tn-eyebrow">Release notes</span><div>{notes}</div></div>}<div className="tn-facts"><div><span>平台文件</span><strong>{latest.compatible ? latest.assetName : "无匹配文件"}</strong></div><div><span>完整性</span><strong className={latest.integrityReady ? "text-success" : "text-danger"}>{latest.integrityReady ? "SHA-256 + 签名可验证" : "不可验证"}</strong></div><div><span>文件大小</span><strong>{latest.assetSize ? `${(latest.assetSize / 1024 / 1024).toFixed(1)} MB` : "-"}</strong></div></div>{latest.isNewer && !latest.compatible && <div className="tn-inline-error"><AlertCircle size={16} />当前平台没有可安装的 Release 文件。</div>}{latest.isNewer && latest.compatible && !latest.integrityReady && <div className="tn-inline-error"><AlertCircle size={16} />发布文件缺少完整校验，已禁用更新。</div>}<div className="tn-page-actions">{canDownload && <Button theme="primary" onClick={() => { setConfirmAction("download"); setConfirmVersion(latest.version); }} disabled={actionBusy} loading={actionBusy && confirmAction === "download"} icon={<Download size={16} />}>下载更新包</Button>}{canApply && <Button theme="primary" onClick={() => { setConfirmAction("apply"); setConfirmVersion(latest.version); }} disabled={actionBusy} loading={actionBusy && confirmAction === "apply"} icon={<Zap size={16} />}>立即更新</Button>}{reloadReady && <Button theme="primary" onClick={() => window.location.reload()}>重新加载</Button>}</div></Surface> : <div className="tn-empty">点击“检查更新”获取最新 Release。</div>}
       {!info.configured && <div className="tn-update-explainer"><Terminal size={17} /><div><strong>当前为手动更新模式</strong><p>源码安装默认不启用后台更新。需要更新时，在服务器拉取对应 Release 后重新构建并重启服务；安装器部署并配置 systemd 后，才会显示后台一键更新。</p></div></div>}
-      {job && <Surface className="tn-update-release"><span className="tn-sr-only" aria-live="polite">更新任务状态：{labels[job.status]}</span><div className="tn-update-release-head"><div><span className="tn-eyebrow">最近任务</span><h2>v{job.version}</h2></div><Tag theme={job.status === "completed" ? "success" : job.status === "failed" ? "danger" : "primary"}>{labels[job.status]}</Tag></div>{active.has(job.status) && <><div className="tn-progress" role="progressbar" aria-label="系统更新进度" aria-valuemin={0} aria-valuemax={100} aria-valuenow={progress}><span style={{ width: `${progress}%` }} /></div><small>更新服务正在后台运行，页面会自动刷新状态。</small></>}{job.status === "failed" && job.errorMessage && <div className="tn-inline-error" role="alert">{job.errorMessage}</div>}{job.status === "completed" && <div className="tn-inline-info"><CheckCircle2 size={16} />新版本已通过健康检查，数据和附件保持不变。</div>}</Surface>}
+      {job && <Surface className="tn-update-release"><span className="tn-sr-only" aria-live="polite">更新任务状态：{labels[job.status]}</span><div className="tn-update-release-head"><div><span className="tn-eyebrow">最近任务</span><h2>v{job.version}</h2></div><Tag theme={job.status === "completed" ? "success" : job.status === "failed" ? "danger" : "primary"}>{labels[job.status]}</Tag></div>{active.has(job.status) && <><div className="tn-progress" role="progressbar" aria-label="系统更新进度" aria-valuemin={0} aria-valuemax={100} aria-valuenow={progress}><span style={{ width: `${progress}%` }} /></div><small>{job.status === "staged" && job.operation === "download" ? "更新包已下载并校验，可以立即应用。" : job.status === "staged" && job.operation === "apply" ? "立即更新请求已提交，服务即将重启。" : "更新服务正在后台运行，页面会自动刷新状态。"}</small>{restartSeconds !== null && (job.status === "applying" || disconnected.current) && <div className="tn-restart-countdown" role="status">服务正在重启，预计 {restartSeconds} 秒后恢复</div>}</>}{job.status === "failed" && job.errorMessage && <div className="tn-inline-error" role="alert">{job.errorMessage}</div>}{job.status === "completed" && <div className="tn-inline-info"><CheckCircle2 size={16} />新版本已通过健康检查，数据和附件保持不变。</div>}</Surface>}
     </>}
-    <Dialog visible={Boolean(confirmVersion)} header="确认系统更新" confirmBtn={{ content: "确认更新", theme: "primary", loading: applying, disabled: applying }} cancelBtn="取消" onClose={() => { if (!applying) setConfirmVersion(null); }} onConfirm={() => void apply()} onCancel={() => { if (!applying) setConfirmVersion(null); }}>将更新到 v{confirmVersion}。服务会短暂重启，更新前会备份数据目录；账目、附件、回收站和审计记录不会被删除。</Dialog>
+    <Dialog visible={Boolean(confirmVersion)} header={confirmAction === "download" ? "下载更新包" : "确认立即更新"} confirmBtn={{ content: confirmAction === "download" ? "开始下载" : "立即更新", theme: "primary", loading: actionBusy, disabled: actionBusy }} cancelBtn="取消" onClose={() => { if (!actionBusy) setConfirmVersion(null); }} onConfirm={() => void submitAction()} onCancel={() => { if (!actionBusy) setConfirmVersion(null); }}>{confirmAction === "download" ? `将下载并校验 v${confirmVersion}，完成后可选择立即更新。` : `将应用已下载的 v${confirmVersion}。服务会短暂重启，更新前会备份数据目录。`}</Dialog>
   </Page>;
 }

web-next/src/styles/theme.css

@@ -278,6 +278,8 @@ input:focus-visible, textarea:focus-visible, select:focus-visible {
 .tn-update-release .t-card__body { padding: 20px; }
 .tn-update-release-head { display: flex; align-items: flex-start; justify-content: space-between; gap: 14px; }
 .tn-update-release h2 { margin: 3px 0 5px; color: var(--tn-text); font-size: 21px; }
+.tn-release-notes { margin: 16px 0; padding: 12px 14px; border-left: 3px solid var(--td-brand-color-3); background: #f7f9fc; color: var(--tn-text-secondary); font-size: 13px; line-height: 1.6; white-space: pre-wrap; overflow-wrap: anywhere; }
+.tn-release-notes .tn-eyebrow { display: block; margin-bottom: 4px; color: var(--tn-navy-900); }
 .tn-facts { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 14px; margin: 18px 0; padding: 14px 0; border-top: 1px solid var(--tn-border-subtle); border-bottom: 1px solid var(--tn-border-subtle); }
 .tn-facts span { display: block; margin-bottom: 4px; color: var(--tn-text-secondary); font-size: 12px; }
 .tn-facts strong { overflow-wrap: anywhere; color: #344054; font-size: 14px; }
@@ -344,6 +346,7 @@ input:focus-visible, textarea:focus-visible, select:focus-visible {
 .tn-inline-error, .tn-inline-info { display: flex; align-items: center; gap: 7px; margin-top: 10px; padding: 9px 11px; border-radius: 3px; font-size: 13px; }
 .tn-inline-error { color: #a33a3a; background: #fff0f0; }
 .tn-inline-info { color: #246044; background: #eaf7ef; }
+.tn-restart-countdown { margin-top: 10px; color: var(--tn-warning); font-size: 12px; font-variant-numeric: tabular-nums; }
 .tn-update-explainer { display: flex; align-items: flex-start; gap: 10px; margin: 0 0 14px; padding: 13px 15px; border: 1px solid var(--td-brand-color-2); border-radius: 4px; color: var(--tn-navy-900); background: var(--td-brand-color-1); }
 .tn-update-explainer > svg { flex: 0 0 auto; margin-top: 1px; color: var(--td-brand-color); }
 .tn-update-explainer strong { display: block; font-size: 13px; }