feat: add staged release updates

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

@@ -142,6 +142,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,

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,
   };
 }