Merge pull request '修复图片下载排队、中转速度和错误反馈' (#28) from codex/image-download-reliability-20261104 into main

app/api/canvas/download-image/route.ts

@@ -1,6 +1,9 @@
 import { resolveCanvasCdnDownload } from "@/lib/storage/canvas-cdn-download";
 import { isRetiredStorageUrl, RETIRED_STORAGE_MESSAGE } from "@/lib/storage/retired-storage";
-import { prepareImageArchiveDownload } from "@/lib/storage/image-download-preparation";
+import { scheduleImageDownloadPreparation } from "@/lib/storage/image-download-preparation";
+import { randomUUID } from "node:crypto";
+import { formatDownloadFailure, getDownloadFailure, type DownloadFailure } from "@/lib/canvas/download-error";
+import { createLogger } from "@/lib/observability/logger";
 import { after, NextRequest, NextResponse } from "next/server";
 import { auth } from "@/app/(auth)/auth";
 import { getDownloadPreparationQueue, type DownloadPreparationInput } from "@/lib/canvas/download-preparation";
@@ -13,6 +16,22 @@ import {
 
 export const runtime = "nodejs";
 export const maxDuration = 120;
+const logger = createLogger("canvas.download");
+
+function failed(failure: DownloadFailure, requestId: string) {
+  logger.warn("request_failed", { requestId, code: failure.code, status: failure.status });
+  return NextResponse.json({ success: false, error: formatDownloadFailure(failure, requestId), failure, requestId }, {
+    status: failure.status,
+    headers: { "Cache-Control": "no-store", ...(failure.status === 429 ? { "Retry-After": "3" } : {}) },
+  });
+}
+
+function preparing(requestId: string) {
+  return NextResponse.json({ delivery: "preparing", retryAfter: 2, requestId,
+    message: "正在准备原图，完成后将自动开始下载" }, {
+    status: 202, headers: { "Retry-After": "2", "Cache-Control": "no-store" },
+  });
+}
 
 async function prepareDownload(input: DownloadPreparationInput, signal: AbortSignal) {
   // A proxy candidate for the same original must not repeat the same slow
@@ -21,22 +40,25 @@ async function prepareDownload(input: DownloadPreparationInput, signal: AbortSig
     const source = extractImageProxySourceUrl(url) || url;
     return inferOriginalImageUrl(source) || source;
   }))];
-  for (let attempt = 0; attempt < 3; attempt++) {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < 2; attempt++) {
     signal.throwIfAborted();
     for (const url of sources) {
       signal.throwIfAborted();
       const result = await fetchCanvasDownloadAsset({
         file: { url, name: "original" }, index: 0,
         requestOrigin: input.requestOrigin, cookie: input.cookie,
-        includeSequencePrefix: false, timeoutMs: 12_000, retryCount: 1, signal,
+        includeSequencePrefix: false, timeoutMs: 60_000, retryCount: 1, signal,
       });
       if (result.ok) return { buffer: result.bytes, contentType: result.contentType };
+      lastError = result.error;
     }
     // Each pass resolves the latest archive URL inside fetchCanvasDownloadAsset.
     // No AI/model request is involved and a completed source fetch is shared.
-    if (attempt < 2) await new Promise(resolve => setTimeout(resolve, 1_000));
+    if (attempt < 1 && getDownloadFailure(lastError).retryable) await new Promise(resolve => setTimeout(resolve, 1_000));
+    else break;
   }
-  throw new Error("Original image sources unavailable");
+  throw new Error(String(lastError || "Original image sources unavailable"));
 }
 
 function getRequestOrigin(request: NextRequest): string {
@@ -76,31 +98,43 @@ function resolveDownloadUrls(body: Record<string, unknown>, origin: string): str
 }
 
 export async function POST(request: NextRequest) {
+  const requestId = randomUUID();
   try {
     const session = await auth();
     if (!session?.user?.id) {
-      return NextResponse.json({ success: false, error: "未登录" }, { status: 401 });
+      return failed(getDownloadFailure("未登录"), requestId);
     }
 
     const body = (await request.json().catch(() => ({}))) as Record<string, unknown>;
     const requestOrigin = getRequestOrigin(request);
     const candidates = resolveDownloadUrls(body, requestOrigin);
     if (candidates.length && candidates.every(isRetiredStorageUrl)) {
-      return NextResponse.json({ success: false, error: RETIRED_STORAGE_MESSAGE, code: "storage_retired" }, { status: 410 });
+      return failed(getDownloadFailure(RETIRED_STORAGE_MESSAGE), requestId);
     }
     const urls = candidates.filter(url => !isRetiredStorageUrl(url));
     const requestedUrls = [...urls];
     if (urls.length === 0) {
-      return NextResponse.json({ success: false, error: "图片地址无效" }, { status: 400 });
+      return failed(getDownloadFailure("图片地址无效"), requestId);
     }
 
     const name = sanitizeCanvasDownloadFileName(String(body.name || ""), "canvas-image");
     if (body.preferDirect === true) {
-      const { task, direct } = await resolveCanvasCdnDownload(urls, `${name}.png`).catch(() => ({ task: null, direct: null }));
+      const { task, direct, canPrepareDirect } = await resolveCanvasCdnDownload(urls, `${name}.png`).catch((error) => {
+        logger.warn("cdn_lookup_failed", error, { requestId });
+        return { task: null, direct: null, canPrepareDirect: false };
+      });
       if (direct) return NextResponse.json(direct, { headers: { "Cache-Control": "no-store" } });
+      if (task && canPrepareDirect && body.preparation === "async") {
+        const asset = (task.metadata as { downloadAsset?: { status?: string; failure?: DownloadFailure; retryAt?: string } } | null)?.downloadAsset;
+        if (asset?.status === "abandoned" || (asset?.status === "failed" && Date.parse(asset.retryAt || "") > Date.now())) {
+          return failed(asset.failure || getDownloadFailure(null), task.id);
+        }
+        scheduleImageDownloadPreparation(task.id);
+        return preparing(task.id);
+      }
       if (task?.targetUrl) {
         if (!urls.includes(task.targetUrl)) urls.unshift(task.targetUrl);
-        after(() => prepareImageArchiveDownload(task.id));
+        scheduleImageDownloadPreparation(task.id);
       }
     }
     const cookie = request.headers.get("cookie") || "";
@@ -109,13 +143,10 @@ export async function POST(request: NextRequest) {
         userId: session.user.id, urls: requestedUrls, requestOrigin, cookie,
       });
       if (result.status === "preparing") {
-        return NextResponse.json({ delivery: "preparing", retryAfter: 3,
+        return preparing(result.requestId);
-          message: "正在准备原图，完成后将自动下载" }, {
-          status: 202, headers: { "Retry-After": "3", "Cache-Control": "no-store" },
-        });
       }
       if (result.status === "failed") {
-        return NextResponse.json({ success: false, error: result.error }, { status: 502 });
+        return failed(result.failure, result.requestId);
       }
       return new NextResponse(new Uint8Array(result.asset.buffer), { headers: {
         "Content-Type": result.asset.contentType,
@@ -136,17 +167,14 @@ export async function POST(request: NextRequest) {
         includeSequencePrefix: false,
       });
       if (result.ok) break;
-      failures.push(`${url}: ${result.error}`);
+      failures.push(result.error);
     }
 
     if (!result?.ok) {
       if (failures.length > 0) {
-        console.warn("[CanvasDownloadImage] All candidates failed:", failures);
+        logger.warn("all_sources_failed", { requestId, failures });
       }
-      return NextResponse.json(
+      return failed(getDownloadFailure(result?.error), requestId);
-        { success: false, error: result?.error || "图片源文件暂时不可访问" },
-        { status: 502 }
-      );
     }
 
     return new NextResponse(result.bytes, {
@@ -159,7 +187,7 @@ export async function POST(request: NextRequest) {
       },
     });
   } catch (error) {
-    console.error("[CanvasDownloadImage] Failed:", error);
+    logger.error("download_failed", error, { requestId });
-    return NextResponse.json({ success: false, error: "图片下载失败" }, { status: 500 });
+    return failed(getDownloadFailure(error), requestId);
   }
 }

lib/canvas/download-error.ts

@@ -0,0 +1,30 @@
+export type DownloadFailure = {
+  code: string;
+  message: string;
+  recommendation: string;
+  status: number;
+  retryable: boolean;
+};
+
+export function getDownloadFailure(error: unknown): DownloadFailure {
+  const text = error && typeof error === "object" && "message" in error
+    ? `${"name" in error ? error.name : "Error"}: ${error.message}` : String(error || "");
+  const failure = (code: string, message: string, recommendation: string, status: number, retryable = false) =>
+    ({ code, message, recommendation, status, retryable });
+  if (/旧存储已停用|storage_retired/.test(text)) return failure("STORAGE_RETIRED", "原图所在的旧存储已停用。", "请重新上传原图；重试下载无法恢复该文件。", 410);
+  if (/HTTP (?:404|410)|SOURCE_NOT_FOUND/i.test(text)) return failure("SOURCE_NOT_FOUND", "原图链接已失效或源文件已被删除。", "请重新上传原图，或联系管理员核对归档副本；无需重新生成图片。", 404);
+  if (/HTTP (?:401|403)|SOURCE_FORBIDDEN/i.test(text)) return failure("SOURCE_FORBIDDEN", "图片源站拒绝访问原图。", "请联系管理员检查原图访问权限或链接有效期，并提供下载编号。", 403);
+  if (/queue.*busy|正在准备的原图较多|DOWNLOAD_BUSY/i.test(text)) return failure("DOWNLOAD_BUSY", "正在准备的下载较多。", "请等待当前下载完成后再试，避免同时重复点击。", 429, true);
+  if (/TimeoutError|AbortError|timeout|timed out|deadline|超时|HTTP (?:408|504|524)/i.test(text)) return failure("SOURCE_TIMEOUT", "读取原图或准备下载文件超时。", "请稍后再次下载；持续失败时联系管理员并提供下载编号，已归档的原图无需重新生成。", 504, true);
+  if (/fetch failed|failed to fetch|ECONN|ENOTFOUND|EAI_AGAIN|network|HTTP (?:429|5\d\d)/i.test(text)) return failure("SOURCE_UNAVAILABLE", "暂时无法连接图片源站。", "请稍后重试下载；持续失败时联系管理员检查取图线路，并提供下载编号。", 503, true);
+  if (/not.*image|error document|不是图片|无法识别图片|empty response|image is empty|Invalid prepared original/i.test(text)) return failure("INVALID_IMAGE", "源地址没有返回可用的图片文件。", "请重新上传可打开的原图；若原图正常，请联系管理员并提供下载编号。", 422);
+  if (/sharp|pngload|jpegload|unsupported image|无法解析图片|convert|转换/i.test(text)) return failure("IMAGE_CONVERSION_FAILED", "原图无法转换为下载所需的 PNG 文件。", "请保留原图并联系管理员提供下载编号，或重新上传 PNG/JPEG 图片。", 422);
+  if (/upload|存储桶|保存下载|STORAGE_WRITE_FAILED/i.test(text)) return failure("DOWNLOAD_STORAGE_FAILED", "下载文件保存失败，已归档的原图仍然保留。", "请稍后重试；持续失败时联系管理员检查存储，并提供下载编号。", 503, true);
+  if (/未登录/.test(text)) return failure("LOGIN_REQUIRED", "登录状态已失效。", "请重新登录后下载，当前图片不会因此删除。", 401);
+  if (/图片地址无效/.test(text)) return failure("INVALID_IMAGE_URL", "图片地址无效。", "请刷新画布后重新选择图片；仍然失败时请重新上传原图。", 400);
+  return failure("DOWNLOAD_FAILED", "下载准备未能完成。", "请联系管理员并提供下载编号，以便核对原图、转换和存储的具体错误；无需重新生成。", 500, true);
+}
+
+export function formatDownloadFailure(failure: DownloadFailure, requestId?: string) {
+  return `${failure.message}${failure.recommendation}${requestId ? `\n下载编号：${requestId}` : ""}`;
+}

lib/canvas/download-preparation.ts

@@ -1,6 +1,10 @@
 import "server-only";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { cacheImageBytes, readImageBytes, type ImageBytes } from "@/lib/storage/image-byte-cache";
+import { formatDownloadFailure, getDownloadFailure, type DownloadFailure } from "./download-error";
+import { createLogger } from "@/lib/observability/logger";
+
+const logger = createLogger("canvas.download");
 
 export type DownloadPreparationInput = {
   userId: string;
@@ -9,17 +13,18 @@ export type DownloadPreparationInput = {
   cookie: string;
 };
 type Result =
-  | { status: "preparing" }
+  | { status: "preparing"; requestId: string }
   | { status: "ready"; asset: ImageBytes }
-  | { status: "failed"; error: string };
+  | { status: "failed"; error: string; failure: DownloadFailure; requestId: string };
 type Job = {
+  requestId: string;
   userId: string;
   input: DownloadPreparationInput;
   status: "queued" | "running" | "ready" | "failed";
   updatedAt: number;
   asset?: ImageBytes;
+  failure?: DownloadFailure;
 };
-const FAILURE_MESSAGE = "原图暂时无法读取，图片仍保留在画布中，请稍后重试";
 const MAX_MEMORY_BYTES = 128 * 1024 * 1024;
 
 // A download is independent of node autosave and of the archive worker's batch.
@@ -69,7 +74,7 @@ export function createDownloadPreparationQueue(deps: {
               timer = setTimeout(() => {
                 controller.abort();
                 reject(new Error("Download preparation deadline"));
-              }, deps.timeoutMs || 90_000);
+              }, deps.timeoutMs || 150_000);
             }),
           ]);
           if (asset.contentType !== "image/png" || !asset.buffer.length || asset.buffer.length > MAX_MEMORY_BYTES) {
@@ -81,8 +86,10 @@ export function createDownloadPreparationQueue(deps: {
           const stored = await deps.read(key).catch(() => null);
           if (stored?.contentType === "image/png" && stored.buffer.length) job.asset = undefined;
           job.status = "ready";
-        } catch {
+        } catch (error) {
           job.status = "failed";
+          job.failure = getDownloadFailure(error);
+          logger.warn("preparation_failed", error, { requestId: job.requestId, code: job.failure.code });
         } finally {
           if (timer) clearTimeout(timer);
           // Do not retain authentication data after a preparation finishes.
@@ -105,8 +112,11 @@ export function createDownloadPreparationQueue(deps: {
       prune();
       const current = jobs.get(key);
       if (current?.status === "ready" && current.asset) return { status: "ready", asset: current.asset };
-      if (current?.status === "failed") return { status: "failed", error: FAILURE_MESSAGE };
+      if (current?.status === "failed") {
-      if (current && current.status !== "ready") return { status: "preparing" };
+        const failure = current.failure || getDownloadFailure(null);
+        return { status: "failed", error: formatDownloadFailure(failure, current.requestId), failure, requestId: current.requestId };
+      }
+      if (current && current.status !== "ready") return { status: "preparing", requestId: current.requestId };
       if (jobs.size >= 64) {
         for (const [oldKey, job] of jobs) {
           if (job.status === "ready" || job.status === "failed") jobs.delete(oldKey);
@@ -115,11 +125,14 @@ export function createDownloadPreparationQueue(deps: {
       }
       if (jobs.size >= 64 || [...jobs.values()].filter(job => job.userId === input.userId &&
           (job.status === "queued" || job.status === "running")).length >= 4) {
-        return { status: "failed", error: "正在准备的原图较多，请等待当前下载完成后再试" };
+        const requestId = randomUUID();
+        const failure = getDownloadFailure("DOWNLOAD_BUSY");
+        return { status: "failed", error: formatDownloadFailure(failure, requestId), failure, requestId };
       }
-      jobs.set(key, { userId: input.userId, input, status: "queued", updatedAt: now() });
+      const requestId = randomUUID();
+      jobs.set(key, { requestId, userId: input.userId, input, status: "queued", updatedAt: now() });
       deps.schedule(drain);
-      return { status: "preparing" };
+      return { status: "preparing", requestId };
     },
   };
 }

lib/canvas/photoshop-safe-download.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { isRetiredStorageUrl, RETIRED_STORAGE_MESSAGE } from "@/lib/storage/retired-storage";
 import { fetchImageBytes, onceImageBytes } from "@/lib/storage/image-byte-cache";
 import { extractImageProxySourceUrl, inferOriginalImageUrl } from "@/lib/image-url";
+import { getDownloadFailure } from "./download-error";
 
 type DownloadFileItem = {
   url: string;
@@ -31,6 +32,7 @@ function sleep(ms: number) {
 
 function normalizeDownloadError(error: unknown): string {
   if (error instanceof Error) return error.message || "download failed";
+  if (error && typeof error === "object" && "message" in error && typeof error.message === "string") return error.message;
   if (typeof error === "string") return error;
   return "download failed";
 }
@@ -330,6 +332,7 @@ export async function fetchCanvasDownloadAsset(params: {
       try {
         const data = await fetchImageBytes(candidateUrl, {
           timeoutMs,
+          signal: params.signal,
           headers: buildRemoteFetchHeaders(candidateUrl, params.requestOrigin, params.cookie),
           // Authenticated local assets must never share a cache across users.
           scope: new URL(candidateUrl).origin === params.requestOrigin && params.cookie
@@ -344,11 +347,13 @@ export async function fetchCanvasDownloadAsset(params: {
         });
       } catch (error) {
         params.signal?.throwIfAborted();
-        lastError = normalizeDownloadError(error);
+        const message = normalizeDownloadError(error);
+        if (!lastError || getDownloadFailure(message).retryable || !getDownloadFailure(lastError).retryable) lastError = message;
       }
     }
     // Archiving may have completed during the failed fetch. Resolve aliases
     // again before retrying, rather than spending every attempt on the old URL.
+    if (!getDownloadFailure(lastError).retryable) break;
     if (attempt < retryCount) await sleep(350 * attempt);
   }
 

lib/client/canvas-image-download.ts

@@ -1,5 +1,6 @@
 import { buildImageProxyUrl } from "@/lib/image-delivery";
 import { inferOriginalImageUrl } from "@/lib/image-url";
+import { formatDownloadFailure, getDownloadFailure, type DownloadFailure } from "@/lib/canvas/download-error";
 
 export type CanvasImageDownloadPhase = "preparing" | "downloading" | "saving";
 
@@ -26,6 +27,8 @@ export class CanvasImageDownloadError extends Error {
   code: CanvasImageDownloadErrorCode;
   retryAfterSeconds?: number;
   status?: number;
+  failure?: DownloadFailure;
+  requestId?: string;
 
   constructor(
     message: string,
@@ -33,6 +36,8 @@ export class CanvasImageDownloadError extends Error {
       code: CanvasImageDownloadErrorCode;
       retryAfterSeconds?: number;
       status?: number;
+      failure?: DownloadFailure;
+      requestId?: string;
     }
   ) {
     super(message);
@@ -40,11 +45,14 @@ export class CanvasImageDownloadError extends Error {
     this.code = options.code;
     this.retryAfterSeconds = options.retryAfterSeconds;
     this.status = options.status;
+    this.failure = options.failure;
+    this.requestId = options.requestId;
   }
 }
 
 export function getCanvasImageDownloadErrorMessage(error: unknown) {
   if (error instanceof CanvasImageDownloadError) {
+    if (error.failure) return formatDownloadFailure(error.failure, error.requestId);
     if (error.code === "rate_limited") {
       return error.retryAfterSeconds
         ? `图片下载请求过于频繁，请 ${error.retryAfterSeconds} 秒后重试`
@@ -54,10 +62,10 @@ export function getCanvasImageDownloadErrorMessage(error: unknown) {
       return "原图暂时无法读取，图片仍保留在画布中，请稍后重试";
     }
     if (error.code === "preparation_timeout") {
-      return "原图仍在后台准备中，请稍后再次点击下载";
+      return `原图仍在后台准备中，请稍后再次点击下载${error.requestId ? `\n下载编号：${error.requestId}` : ""}`;
     }
   }
-  return error instanceof Error ? error.message : "图片下载失败，请稍后重试";
+  return formatDownloadFailure(getDownloadFailure(error));
 }
 
 type DownloadCanvasImageParams = {
@@ -71,6 +79,8 @@ type DownloadCanvasImageParams = {
 type DownloadErrorPayload = {
   error?: string;
   retryAfter?: number;
+  failure?: DownloadFailure;
+  requestId?: string;
 };
 
 const MAX_RATE_LIMIT_RETRIES = 1;
@@ -257,7 +267,8 @@ export async function downloadCanvasImageAsPng({
   let preparationPolls = 0;
   for (;;) {
     signal?.throwIfAborted();
-    response = await fetch("/api/canvas/download-image", {
+    try {
+      response = await fetch("/api/canvas/download-image", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -268,7 +279,12 @@ export async function downloadCanvasImageAsPng({
         preparation: "async",
       }),
       signal,
-    });
+      });
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      const failure = getDownloadFailure(error);
+      throw new CanvasImageDownloadError(failure.message, { code: "request_failed", failure });
+    }
 
     if (response.status === 202) {
       rateLimitRetries = 0;
@@ -278,7 +294,7 @@ export async function downloadCanvasImageAsPng({
         throw new CanvasImageDownloadError("下载准备状态无效", { code: "request_failed", status: 202 });
       }
       if (Date.now() >= preparationDeadline || preparationPolls >= 60) {
-        throw new CanvasImageDownloadError("原图仍在准备中", { code: "preparation_timeout", status: 202 });
+        throw new CanvasImageDownloadError("原图仍在准备中", { code: "preparation_timeout", status: 202, requestId: preparing.requestId });
       }
       onProgress?.({ phase: "preparing", message: preparing.message || "正在准备原图，完成后将自动下载" });
       const delaySeconds = Math.max(preparationPolls > 5 ? 5 : 1, Math.min(5, Number(preparing.retryAfter) || 3));
@@ -299,6 +315,8 @@ export async function downloadCanvasImageAsPng({
           code: "rate_limited",
           retryAfterSeconds,
           status: response.status,
+          failure: errorPayload?.failure,
+          requestId: errorPayload?.requestId,
         }
       );
     }
@@ -321,6 +339,8 @@ export async function downloadCanvasImageAsPng({
       {
         code: status === 502 ? "source_unavailable" : "request_failed",
         status,
+        failure: errorPayload?.failure,
+        requestId: errorPayload?.requestId,
       }
     );
   }

lib/jobs/image-archive-job.ts

@@ -1,4 +1,4 @@
-import { preparePendingImageDownloads } from "@/lib/storage/image-download-preparation";
+import { scheduleImageDownloadPreparation } from "@/lib/storage/image-download-preparation";
 import "server-only";
 import { trackRuntimeWork } from "@/lib/observability/active-work";
 
@@ -32,6 +32,7 @@ export async function runImageArchiveJob() {
   console.log(`[ImageArchiveJob] Start image archive job (batchSize=${batchSize})`);
 
   await recoverStaleImageArchiveTasks();
+  scheduleImageDownloadPreparation();
   const storeTasks = await getImageArchiveTasksToStore({ limit: batchSize });
   let storeSucceeded = 0;
   let storeFailed = 0;
@@ -45,6 +46,7 @@ export async function runImageArchiveJob() {
         id: task.id,
         targetUrl: archived.url,
       });
+      scheduleImageDownloadPreparation(task.id);
       storeSucceeded += 1;
       console.log("[ImageArchiveJob] stored", {
         taskId: task.id,
@@ -108,7 +110,6 @@ export async function runImageArchiveJob() {
     }
   }
 
-  const downloadTasks = await preparePendingImageDownloads();
   const stats = await getImageArchiveTaskStats();
   return {
     success: true,
@@ -124,8 +125,8 @@ export async function runImageArchiveJob() {
       failed: replaceFailed,
     },
     stats,
-    downloadTasks,
+    downloadTasks: 0,
     pendingDownloads: await hasPendingImageDownloads(),
   };
-  });
+  }, { durable: true });
 }

lib/observability/active-work.ts

@@ -3,13 +3,14 @@ import { unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-const state = globalThis as typeof globalThis & { __aiChatbotActiveWork?: number };
+const state = globalThis as typeof globalThis & { __aiChatbotActiveWork?: number; __aiChatbotDurableWork?: number };
 const path = join(process.platform === "win32" ? tmpdir() : "/tmp", `ai-chatbot-active-work-${process.pid}.json`);
 
-function update(delta: number) {
+function update(delta: number, durable: boolean) {
   state.__aiChatbotActiveWork = (state.__aiChatbotActiveWork || 0) + delta;
+  if (durable) state.__aiChatbotDurableWork = (state.__aiChatbotDurableWork || 0) + delta;
   try {
-    writeFileSync(path, JSON.stringify({ pid: process.pid, active: state.__aiChatbotActiveWork }), { mode: 0o600 });
+    writeFileSync(path, JSON.stringify({ pid: process.pid, active: state.__aiChatbotActiveWork, durable: state.__aiChatbotDurableWork || 0 }), { mode: 0o600 });
   } catch (error) {
     try { unlinkSync(path); } catch {}
     console.warn("[Active Work] Failed to record running work:", error);
@@ -17,7 +18,7 @@ function update(delta: number) {
 }
 
 /** Includes generation that continues after the client connection closes. */
-export async function trackRuntimeWork<T>(execute: () => T | Promise<T>): Promise<T> {
+export async function trackRuntimeWork<T>(execute: () => T | Promise<T>, options: { durable?: boolean } = {}): Promise<T> {
-  update(1);
+  update(1, options.durable === true);
-  try { return await execute(); } finally { update(-1); }
+  try { return await execute(); } finally { update(-1, options.durable === true); }
 }

lib/storage/canvas-cdn-download.ts

@@ -10,17 +10,21 @@ export async function resolveCanvasCdnDownload(urls: string[], filename: string)
   })));
   const task = await findImageArchiveDownloadTask(sources, true);
   const asset = (task?.metadata as { downloadAsset?: { status?: string; url?: string; contentType?: string; bytes?: number } } | null)?.downloadAsset;
-  if (asset?.status !== "ready" || !asset.url || asset.contentType !== "image/png") return { task, direct: null };
+  if (!task) return { task, direct: null, canPrepareDirect: false };
   const config = await getDefaultStorageConfig();
-  if (config?.type !== "qiniu-kodo" || !config.publicUrl || !config.isEnabled) return { task, direct: null };
+  if (config?.type !== "qiniu-kodo" || !config.publicUrl || !config.isEnabled) return { task, direct: null, canPrepareDirect: false };
-  const url = new URL(asset.url);
+  const ready = asset?.status === "ready" && asset.url && asset.contentType === "image/png";
+  const source = ready ? asset.url : task.targetUrl;
+  if (!source) return { task, direct: null, canPrepareDirect: false };
+  const url = new URL(source);
   const base = new URL(config.publicUrl);
   const origin = process.env.CANVAS_QINIU_ORIGIN_URL;
   if (origin && url.origin === new URL(origin).origin) url.host = base.host;
   if (base.protocol !== "https:" || url.origin !== base.origin
-      || !(url.pathname.startsWith(base.pathname.replace(/\/$/, "") + "/"))) return { task, direct: null };
+      || !(url.pathname.startsWith(base.pathname.replace(/\/$/, "") + "/"))) return { task, direct: null, canPrepareDirect: false };
+  if (!ready) return { task, direct: null, canPrepareDirect: true };
   // attname is interpreted by Kodo/CDN as Content-Disposition, including Chinese
   // filenames. Keep all processing/auth parameters intact for correct cache keys.
   url.searchParams.set("attname", filename);
-  return { task, direct: { delivery: "cdn", downloadUrl: url.toString(), filename, bytes: asset.bytes || 0 } };
+  return { task, direct: { delivery: "cdn", downloadUrl: url.toString(), filename, bytes: asset?.bytes || 0 }, canPrepareDirect: true };
 }

lib/storage/image-byte-cache.ts

@@ -81,7 +81,7 @@ function isMediaResponse(data: ImageBytes) {
   if (/^<\?xml/i.test(prefix) && !/<svg[\s>]/i.test(prefix)) return false;
   return data.buffer.length > 0;
 }
-export async function fetchImageBytes(url: string, options: { headers?: HeadersInit; timeoutMs?: number; scope?: string } = {}) {
+export async function fetchImageBytes(url: string, options: { headers?: HeadersInit; timeoutMs?: number; scope?: string; signal?: AbortSignal } = {}) {
   if (isRetiredStorageUrl(url)) throw new Error(`HTTP 410: ${RETIRED_STORAGE_MESSAGE}`);
   return onceImageBytes(`source:${options.scope || ""}:${url}`, async () => {
     if (url.startsWith("data:")) {
@@ -92,7 +92,9 @@ export async function fetchImageBytes(url: string, options: { headers?: HeadersI
     const response = await fetch(url, {
       headers: options.headers, cache: "no-store", redirect: "follow",
       // The deadline covers the body as well as the response headers.
-      signal: AbortSignal.timeout(options.timeoutMs || 60_000),
+      signal: options.signal
+        ? AbortSignal.any([options.signal, AbortSignal.timeout(options.timeoutMs || 60_000)])
+        : AbortSignal.timeout(options.timeoutMs || 60_000),
     });
     if (!response.ok) { await response.body?.cancel(); throw new Error(`HTTP ${response.status}`); }
     const buffer = Buffer.from(await response.arrayBuffer());

lib/storage/image-download-preparation.ts

@@ -2,14 +2,21 @@ import "server-only";
 import { randomUUID } from "node:crypto";
 import { fetchImageBytes, cacheImageBytes } from "./image-byte-cache";
 import { normalizeCanvasDownloadAsset } from "@/lib/canvas/photoshop-safe-download";
-import { claimImageDownloadTask, saveImageDownloadAsset, getImageDownloadTasks } from "./image-archive-db";
+import { claimImageDownloadTask, saveImageDownloadAsset, getImageDownloadTasks, hasPendingImageDownloads } from "./image-archive-db";
 import { uploadFile } from "./service";
+import { getDownloadFailure } from "@/lib/canvas/download-error";
+import { createLogger } from "@/lib/observability/logger";
+import { trackRuntimeWork } from "@/lib/observability/active-work";
+
+const logger = createLogger("canvas.download");
 
 export async function prepareImageArchiveDownload(id: string) {
   const task = await claimImageDownloadTask(id);
   if (!task?.targetUrl) return;
+  let phase: "read" | "convert" | "store" = "read";
   try {
     const source = await fetchImageBytes(task.targetUrl);
+    phase = "convert";
     const asset = await normalizeCanvasDownloadAsset({
       item: { url: task.targetUrl }, index: 0, bytes: source.buffer,
       contentType: source.contentType, includeSequencePrefix: false,
@@ -17,15 +24,22 @@ export async function prepareImageArchiveDownload(id: string) {
     if (!asset.ok) throw new Error(asset.error);
     // An already compatible PNG shares the original object; other formats get
     // one prepared PNG, without changing the original dimensions or transparency.
+    phase = "store";
     const url = source.buffer.equals(asset.bytes) && asset.contentType === "image/png"
       ? task.targetUrl
       : (await uploadFile(`canvas-download-${randomUUID()}.${asset.filename.split(".").pop() || "png"}`, Uint8Array.from(asset.bytes).buffer)).url;
     await saveImageDownloadAsset(id, { status: "ready", url, bytes: asset.bytes.length,
       contentType: asset.contentType, preparedAt: new Date().toISOString() });
     await cacheImageBytes(`source::${url}`, { buffer: asset.bytes, contentType: asset.contentType });
-  } catch {
+  } catch (error) {
     const attempts = Number((task.metadata as { downloadAsset?: { attempts?: number } } | null)?.downloadAsset?.attempts || 1);
-    await saveImageDownloadAsset(id, { status: attempts >= 12 ? "abandoned" : "failed", attempts, retryAt: new Date(Date.now() + 10 * 60_000).toISOString() });
+    const failure = phase === "store"
+      ? getDownloadFailure("STORAGE_WRITE_FAILED")
+      : phase === "convert" && getDownloadFailure(error).code === "DOWNLOAD_FAILED"
+        ? getDownloadFailure("图片转换失败") : getDownloadFailure(error);
+    logger.warn("archive_download_preparation_failed", error, { requestId: id, code: failure.code });
+    await saveImageDownloadAsset(id, { status: !failure.retryable || attempts >= 12 ? "abandoned" : "failed", attempts,
+      failure, retryAt: new Date(Date.now() + 60_000).toISOString() });
   }
 }
 export async function preparePendingImageDownloads() {
@@ -36,3 +50,45 @@ export async function preparePendingImageDownloads() {
   }));
   return tasks.length;
 }
+
+const state = globalThis as typeof globalThis & {
+  __imageDownloadWorker?: { running: boolean; scanPending: boolean; priority: Set<string>; retry?: ReturnType<typeof setTimeout> };
+};
+
+/** Download preparation runs independently of the archive URL replacement batch. */
+export function scheduleImageDownloadPreparation(id?: string) {
+  const worker = state.__imageDownloadWorker ??= { running: false, scanPending: false, priority: new Set() };
+  if (id) worker.priority.add(id);
+  else worker.scanPending = true;
+  if (worker.running) return;
+  if (worker.retry) { clearTimeout(worker.retry); worker.retry = undefined; }
+  worker.running = true;
+  setImmediate(() => {
+    void trackRuntimeWork(async () => {
+      try {
+        for (;;) {
+          const priority = [...worker.priority].slice(0, 2);
+          for (const taskId of priority) worker.priority.delete(taskId);
+          if (priority.length) {
+            await Promise.all(priority.map(prepareImageArchiveDownload));
+          } else if (!worker.scanPending || await preparePendingImageDownloads() === 0) {
+            break;
+          }
+        }
+      } catch (error) {
+        logger.error("download_worker_failed", error);
+      } finally {
+        worker.running = false;
+        // Eligible retry times live in the database, including interrupted leases.
+        if (worker.priority.size) {
+          scheduleImageDownloadPreparation([...worker.priority][0]);
+        } else if (worker.scanPending && await hasPendingImageDownloads().catch(() => true)) {
+          worker.retry = setTimeout(() => scheduleImageDownloadPreparation(), 60_000);
+          worker.retry.unref?.();
+        } else {
+          worker.scanPending = false;
+        }
+      }
+    }, { durable: true });
+  });
+}

playwright.helpers.config.ts

@@ -3,6 +3,11 @@ import { defineConfig } from "@playwright/test";
 export default defineConfig({
   testDir: "./tests",
   testMatch: [
+    /routes\/canvas-download-speed\.test\.ts/,
+    /routes\/canvas-download-recovery\.test\.ts/,
+    /routes\/canvas-download-rate-limit\.test\.ts/,
+    /routes\/canvas-zip-download\.test\.ts/,
+    /routes\/image-archive-flow\.test\.ts/,
     /routes\/runtime-active-work\.test\.ts/,
     /routes\/canvas-capability-task-recovery\.test\.ts/,
     /routes\/canvas-toolbar-capability\.test\.ts/,

tests/routes/canvas-download-recovery.test.ts

@@ -0,0 +1,157 @@
+import { expect, test } from "@playwright/test";
+import { randomUUID } from "node:crypto";
+import { serverLoader } from "../helpers/canvas-download-server-loader";
+
+const auth = { auth: async () => ({ user: { id: "owner" } }) };
+const request = () => ({
+  url: "https://app.example/api/canvas/download-image", headers: new Headers(),
+  json: async () => ({ url: "https://provider.example/original.jpg", preferDirect: true, preparation: "async" }),
+});
+
+test("download failures distinguish permanent sources, transport, conversion and storage with actionable advice", () => {
+  const { getDownloadFailure, formatDownloadFailure } = serverLoader({})("lib/canvas/download-error.ts");
+  for (const [error, code, status] of [
+    ["HTTP 404", "SOURCE_NOT_FOUND", 404], ["HTTP 403", "SOURCE_FORBIDDEN", 403],
+    ["TimeoutError: slow body", "SOURCE_TIMEOUT", 504], ["fetch failed", "SOURCE_UNAVAILABLE", 503],
+    ["source returned an error document", "INVALID_IMAGE", 422], ["unsupported image format", "IMAGE_CONVERSION_FAILED", 422],
+    ["STORAGE_WRITE_FAILED", "DOWNLOAD_STORAGE_FAILED", 503], ["DOWNLOAD_BUSY", "DOWNLOAD_BUSY", 429],
+  ]) {
+    const failure = getDownloadFailure(new Error(error as string));
+    expect(failure).toMatchObject({ code, status });
+    expect(failure.recommendation).toBeTruthy();
+    expect(formatDownloadFailure(failure, "feedback-id")).toContain("下载编号：feedback-id");
+    if (status === 404) expect(failure.recommendation).not.toContain("稍后重试");
+  }
+});
+
+test("failed preparation polls retain the same cause and feedback ID without rerunning the load", async () => {
+  const { createDownloadPreparationQueue } = serverLoader({})("lib/canvas/download-preparation.ts");
+  const runs: Array<() => Promise<void>> = [];
+  let loads = 0;
+  const queue = createDownloadPreparationQueue({
+    load: async () => { loads++; throw new Error("HTTP 404 https://source.example/private?token=private"); },
+    read: async () => null, write: async () => {}, schedule: (run: () => Promise<void>) => runs.push(run),
+  });
+  const input = { userId: "owner", urls: ["https://source.example/original"], requestOrigin: "https://app.example", cookie: "session=private" };
+  const accepted = await queue.request(input);
+  await runs[0]();
+  for (let i = 0; i < 3; i++) {
+    const failed = await queue.request(input);
+    expect(failed).toMatchObject({ status: "failed", requestId: accepted.requestId, failure: { code: "SOURCE_NOT_FOUND", status: 404 } });
+    expect(failed.error).not.toContain("token=private");
+  }
+  expect(loads).toBe(1);
+});
+
+test("download queue saturation returns a retryable 429 instead of a source 502", async () => {
+  const { createDownloadPreparationQueue } = serverLoader({})("lib/canvas/download-preparation.ts");
+  const queue = createDownloadPreparationQueue({ load: async () => { throw new Error("not started"); }, read: async () => null, write: async () => {}, schedule() {} });
+  for (let i = 0; i < 4; i++) await queue.request({ userId: "owner", urls: [`https://source.example/${i}`], requestOrigin: "https://app.example", cookie: "" });
+  expect(await queue.request({ userId: "owner", urls: ["https://source.example/fifth"], requestOrigin: "https://app.example", cookie: "" }))
+    .toMatchObject({ status: "failed", failure: { code: "DOWNLOAD_BUSY", status: 429, retryable: true } });
+});
+
+test("cold archived downloads wait for CDN preparation and never buffer the file through the app", async () => {
+  const queued: string[] = [];
+  let ready = false;
+  const route = serverLoader({
+    "@/app/(auth)/auth": auth,
+    "next/server": { NextResponse: Response, after() {} },
+    "@/lib/storage/canvas-cdn-download": { resolveCanvasCdnDownload: async () => ({
+      task: { id: "archive-task", targetUrl: "https://cdn.example/original.jpg", metadata: { downloadAsset: { status: "pending" } } },
+      canPrepareDirect: true,
+      direct: ready ? { delivery: "cdn", downloadUrl: "https://cdn.example/prepared.png", filename: "original.png", bytes: 4000000 } : null,
+    }) },
+    "@/lib/storage/image-download-preparation": { scheduleImageDownloadPreparation: (id: string) => queued.push(id) },
+    "@/lib/canvas/photoshop-safe-download": { sanitizeCanvasDownloadFileName: () => "original", fetchCanvasDownloadAsset: () => { throw new Error("Must use CDN delivery"); } },
+  })("app/api/canvas/download-image/route.ts");
+  const first = await route.POST(request());
+  expect(first.status).toBe(202);
+  expect(await first.json()).toMatchObject({ delivery: "preparing", requestId: "archive-task" });
+  ready = true;
+  const second = await route.POST(request());
+  expect(second.status).toBe(200);
+  expect(await second.json()).toMatchObject({ delivery: "cdn", bytes: 4000000 });
+  expect(queued).toEqual(["archive-task"]);
+});
+
+test("an expired archived source returns its permanent cause and download task ID", async () => {
+  const errors = serverLoader({})("lib/canvas/download-error.ts");
+  const route = serverLoader({
+    "@/app/(auth)/auth": auth, "next/server": { NextResponse: Response, after() {} },
+    "@/lib/storage/canvas-cdn-download": { resolveCanvasCdnDownload: async () => ({ task: {
+      id: "failed-archive", targetUrl: "https://cdn.example/missing.png",
+      metadata: { downloadAsset: { status: "abandoned", failure: errors.getDownloadFailure("HTTP 404") } },
+    }, canPrepareDirect: true, direct: null }) },
+    "@/lib/storage/image-download-preparation": { scheduleImageDownloadPreparation() { throw new Error("Do not retry a permanent failure"); } },
+  })("app/api/canvas/download-image/route.ts");
+  const response = await route.POST(request());
+  expect(response.status).toBe(404);
+  expect(await response.json()).toMatchObject({ requestId: "failed-archive", failure: { code: "SOURCE_NOT_FOUND" } });
+});
+
+test("the download browser keeps the structured cause, advice and feedback ID", async () => {
+  const failure = { code: "SOURCE_FORBIDDEN", message: "图片源站拒绝访问原图。", recommendation: "请联系管理员检查访问权限。", status: 403, retryable: false };
+  const client = serverLoader({ fetch: async () => Response.json({ failure, requestId: "real-feedback" }, { status: 403 }) })("lib/client/canvas-image-download.ts");
+  let caught: unknown;
+  try { await client.downloadCanvasImageAsPng({ url: "https://source.example/original" }); } catch (error) { caught = error; }
+  expect(client.getCanvasImageDownloadErrorMessage(caught)).toBe("图片源站拒绝访问原图。请联系管理员检查访问权限。\n下载编号：real-feedback");
+});
+
+test("the preparation deadline cancels the source body as well as its headers", async () => {
+  const cache = serverLoader({ fetch: async (_url: string, options: { signal: AbortSignal }) => ({
+    ok: true, headers: new Headers({ "content-type": "image/png" }),
+    arrayBuffer: () => new Promise((_resolve, reject) => options.signal.addEventListener("abort", () => reject(options.signal.reason), { once: true })),
+  }) })("lib/storage/image-byte-cache.ts");
+  const controller = new AbortController();
+  const fetching = cache.fetchImageBytes(`https://source.example/${randomUUID()}`, { timeoutMs: 10000, signal: controller.signal });
+  setTimeout(() => controller.abort(new Error("Preparation canceled")), 20);
+  await expect(fetching).rejects.toThrow("Preparation canceled");
+});
+
+test("requested downloads are prioritized with two workers before scanning background assets", async () => {
+  let active = 0; let maximum = 0; let scans = 0;
+  const releases: Array<() => void> = [];
+  const claimed: string[] = []; const saved: string[] = [];
+  const bytes = Buffer.from("compatible PNG fixture");
+  const worker = serverLoader({
+    "@/lib/observability/active-work": { trackRuntimeWork: (execute: () => Promise<void>) => execute() },
+    "./image-archive-db": {
+      claimImageDownloadTask: async (id: string) => { claimed.push(id); return { id, targetUrl: `https://cdn.example/${id}.png`, metadata: {} }; },
+      saveImageDownloadAsset: async (id: string) => saved.push(id),
+      getImageDownloadTasks: async () => { scans++; return []; }, hasPendingImageDownloads: async () => false,
+    },
+    "./image-byte-cache": { fetchImageBytes: async () => { active++; maximum = Math.max(maximum, active); await new Promise<void>(resolve => releases.push(resolve)); active--; return { buffer: bytes, contentType: "image/png" }; }, cacheImageBytes: async () => {} },
+    "@/lib/canvas/photoshop-safe-download": { normalizeCanvasDownloadAsset: async () => ({ ok: true, bytes, contentType: "image/png" }) },
+    "./service": { uploadFile() { throw new Error("Compatible PNG must retain its object"); } },
+  })("lib/storage/image-download-preparation.ts");
+  worker.scheduleImageDownloadPreparation("one"); worker.scheduleImageDownloadPreparation("two"); worker.scheduleImageDownloadPreparation("three");
+  await expect.poll(() => active).toBe(2);
+  expect(scans).toBe(0);
+  releases.splice(0).forEach(release => release());
+  await expect.poll(() => claimed.length).toBe(3);
+  releases.splice(0).forEach(release => release());
+  await expect.poll(() => saved.length).toBe(3);
+  expect(maximum).toBe(2); expect(scans).toBe(0);
+});
+
+test("archive URL replacement cannot block the download worker wakeup", async () => {
+  let scheduled = false; let finish!: () => void; let replacing = false;
+  const gate = new Promise<void>(resolve => { finish = resolve; });
+  const job = serverLoader({
+    "@/lib/observability/active-work": { trackRuntimeWork: (execute: () => Promise<unknown>) => execute() },
+    "@/lib/storage/image-download-preparation": { scheduleImageDownloadPreparation() { scheduled = true; } },
+    "@/lib/storage/image-archive-db": { recoverStaleImageArchiveTasks: async () => {}, getImageArchiveTasksToStore: async () => [],
+      getImageArchiveTasksToReplace: async () => [{ id: "archive", sourceUrl: "https://source.example/a", targetUrl: "https://cdn.example/a" }],
+      markImageArchiveTaskReplacing: async () => true, markImageArchiveTaskCompleted: async () => {}, hasPendingImageDownloads: async () => false,
+      getImageArchiveTaskStats: async () => ({ pendingStore: 0, pendingReplace: 0 }),
+    },
+    "@/lib/storage/image-url-replacement": { replaceImageUrlInDatabase: async () => { replacing = true; await gate; return { changed: 1 }; } },
+    "@/lib/storage/image-archive": {},
+  })("lib/jobs/image-archive-job.ts");
+  const running = job.runImageArchiveJob();
+  await expect.poll(() => replacing).toBe(true);
+  expect(scheduled).toBe(true);
+  finish();
+  expect((await running).replace.succeeded).toBe(1);
+});

tests/routes/image-archive-flow.test.ts

@@ -224,7 +224,7 @@ test("bucket failure retains the provider URL and retry task", async () => {
   let stored = 0;
   let replaced = 0;
   const module = serverLoader({
-    "@/lib/storage/image-download-preparation": { preparePendingImageDownloads: async () => 0 },
+    "@/lib/storage/image-download-preparation": { scheduleImageDownloadPreparation() {} },
     "@/lib/storage/image-archive": {
       archiveTemporaryImage: async () => {
         throw new Error("Bucket unavailable");
@@ -414,7 +414,7 @@ test("successful background archive replaces saved references immediately", asyn
   let completed = false;
   const calls: string[][] = [];
   const module = serverLoader({
-    "@/lib/storage/image-download-preparation": { preparePendingImageDownloads: async () => 0 },
+    "@/lib/storage/image-download-preparation": { scheduleImageDownloadPreparation() {} },
     "@/lib/storage/image-archive": {
       archiveTemporaryImage: async () => ({ url: permanent, bytes: png.length }),
     },

tests/routes/runtime-active-work.test.ts

@@ -17,3 +17,14 @@ test("release draining includes background work until its original promise settl
   await expect(work.trackRuntimeWork(async () => { throw new Error("expected failure"); })).rejects.toThrow("expected failure");
   expect(counts.at(-1)).toBe(0);
 });
+
+test("durable archive handoff is separate from unfinished original generation", async () => {
+  const records: Array<{ active: number; durable: number }> = [];
+  const work = serverLoader({ "node:fs": { writeFileSync: (_path: string, value: string) => records.push(JSON.parse(value)), unlinkSync() {} } })("lib/observability/active-work.ts");
+  let complete!: () => void;
+  const original = work.trackRuntimeWork(() => new Promise<void>(resolve => { complete = resolve; }));
+  await work.trackRuntimeWork(async () => "archive", { durable: true });
+  expect(records.map(x => [x.active, x.durable])).toEqual([[1, 0], [2, 1], [1, 0]]);
+  complete(); await original;
+  expect(records.at(-1)).toMatchObject({ active: 0, durable: 0 });
+});