# 4K 生图总是 5 分钟超时：我把同步请求拆成了异步任务

先说结论：这次故障表面上像“模型太慢”，实际是请求链路被两套时间限制夹住了。

我们给图片生成业务留了 15 分钟超时，但 Node 内置 `fetch` 底层的 undici `headersTimeout` 默认只有 5 分钟。4K 图片还没生成完，请求先在客户端被判定失败。

把超时调大能续命，但解决不了更根本的问题：一个可能跑十几分钟的生成请求，不应该一直占着 API 到上游的连接。最后一次改造做了两件事：

1. 把超长请求从 `fetch` 切到 Node HTTP 长连接，让业务超时真正生效；
2. 把同步长请求拆成网关任务，由 Worker 执行，主 API 轮询结果。

这篇把故障、改法和边界完整记一遍。

## 一、故障长什么样

原来的链路很直接：

```text
画布 -> 主 API -> 自建网关 -> 上游图片接口
```

主 API 调网关时用的 `fetch`，业务代码传入 15 分钟超时。看起来没问题，但运行一段时间后，4K 请求会在 5 分钟左右失败。

上游并没有返回错误，图片还在生成。真正先报错的是 Node 内置 `fetch` 的 undici 连接池：

```text
headersTimeout 默认 300000ms
```

因为图片接口通常要等生成完成才返回响应头，所以请求在第 300 秒先被传输层掐断。业务层的 15 分钟根本没机会生效。

这里有两个时间概念，很容易混：

- **业务超时**：我以为可以等 15 分钟；
- **传输层超时**：底层实际只允许等 5 分钟拿到响应头。

后者先触发，前者就只是写在代码里的一个数字。

## 二、第一次修：让 15 分钟真的生效

第一步没有急着上队列，而是先换掉传输层。

对超过普通请求时限的图片请求，改走 `node:http` / `node:https`，普通请求继续用 `fetch`：

```ts
if (timeoutMs > 120_000) {
  return await this.postLongLivedJson(
    url,
    apiKey,
    body,
    idempotencyKey,
    signal,
    extraHeaders,
  );
}
```

长连接实现里保留了几个关键东西：

- `Authorization`；
- `Content-Type`；
- `Idempotency-Key`；
- 外部传入的 `AbortSignal`；
- 原始业务超时。

`Idempotency-Key` 尤其不能丢。生图是按次计费，网络重试如果没有幂等键，很容易变成同一个任务扣两次钱。

改完后，5 分钟误杀确实没了，15 分钟能跑满。

但这只是把问题往后推。

## 三、为什么继续改异步

同步长连接能工作，不代表它适合长期跑。

它还有四个问题：

1. **请求链路一直占着**：主 API、网关、反向代理和上游要同时维持一个长连接；
2. **进程重启就丢上下文**：网关重启后，进行中的请求没有可恢复状态；
3. **不能按任务治理**：看不到排队、执行中、超时、失败和结果留存；
4. **超时边界不统一**：业务代码、Node、Nginx、负载均衡、上游，每一层都可能各有一套时间。

真正的解法不是“把 5 分钟改成 30 分钟”，而是把一次长请求拆成两个阶段：

- 提交阶段：只负责创建任务，立刻返回任务 ID；
- 执行阶段：Worker 慢慢跑，客户端按任务 ID 查结果。

## 四、异步任务链路

改造后的流程是：

```text
画布
  -> 主 API /images/generations
  -> 自建网关 /images/generations   (X-Async-Image: 1)
  -> 写入任务表，立即返回 202 + task_id
  -> 网关 Worker 执行上游请求
  -> 主 API 每 3 秒查询任务
  -> 完成后返回标准图片响应
```

主 API 提交时只多一个请求头：

```http
X-Async-Image: 1
```

网关收到后不直接访问上游，而是先做三件事：

1. 保存最终的上游请求快照；
2. 写入任务表，状态设为 `queued`；
3. 返回 `202 Accepted` 和任务 ID。

任务查询走：

```http
GET /v1/images/generations/:task_id
```

返回状态只有三种主要形态：

```json
{
  "id": "img_task_xxx",
  "status": "queued",
  "progress": "0%"
}
```

```json
{
  "id": "img_task_xxx",
  "status": "in_progress",
  "progress": "40%"
}
```

完成时则直接返回标准的 OpenAI Images 响应，主 API 不需要再理解一套新的结果格式。

## 五、真正麻烦的是状态一致性

把同步接口改成“返回任务 ID”只用了半天，剩下时间基本都在处理一致性。

### 1. 上游请求要完整落库

Worker 和提交请求不在同一个调用栈里，因此必须保存：

- 上游 URL；
- HTTP 方法；
- 必要请求头；
- 请求体；
- 代理配置；
- 单任务超时。

请求体用 Base64 存进任务私有数据，并限制在 4MB 内。`Content-Length`、`Connection`、`Transfer-Encoding` 这类逐跳头不会保存。

任务查询接口只返回状态和结果，不会把上游地址、请求头或请求体暴露出去。

### 2. 幂等键直接映射任务 ID

提交时优先使用 `Idempotency-Key` 作为任务 ID。长度不合法时才生成新 ID。

同一个用户重复提交同一个幂等键，如果任务已经存在，就直接返回原任务，不重复创建、不重复扣费。

这一步比“客户端不要重复点”可靠得多。网络抖动、超时重试和用户刷新，都不会因为前端没拦住就多创建一个任务。

### 3. 先结算，失败再退款

任务创建后先完成计费结算。Worker 执行失败、超过 30 分钟、被超时回收时，再触发退款。

退款不能靠“觉得失败了就退”。多个 Worker 可能同时看到同一个任务，所以状态更新使用 CAS：

```text
UPDATE task
SET status = 'failure'
WHERE id = ?
  AND status = 'in_progress'
```

只有真正把状态从 `in_progress` 改成 `failure` 的那一个 Worker 才执行退款。状态竞争失败的 Worker 直接退出。

### 4. 进程重启后还能继续

Worker 每次从任务表里取排队任务，默认并发 2，可通过环境变量调整，代码上限 16。

任务被认领时同样走 CAS，所以即使网关开多个副本，也不会两个进程同时执行同一个任务。

进程重启后，排队任务可以重新被认领；长时间停在 `in_progress` 的任务由超时回收循环处理。

## 六、客户端为什么轮询 35 分钟

网关 Worker 的单任务超时是 30 分钟。

主 API 侧给自己留 35 分钟：

```ts
const deadline = Date.now() + 35 * 60_000;
```

多出来的 5 分钟不是拍脑袋，而是给任务状态写入、网络抖动和最后一轮查询留余量。

轮询间隔是 3 秒。为了避免每个轮询都推一次进度，主 API 只在状态变化时更新前端：

```ts
if (status && status !== lastStatus) {
  lastStatus = status;
  await input.onProgress?.(taskId, progress);
}
```

这个细节不显眼，但能减少大量无意义的数据库更新和前端重渲染。

## 七、哪些请求没有走异步

这次只覆盖纯文生图。

带参考图的请求会被网关转到 `/images/edits`，当前 Worker 还没覆盖这条协议。如果强行发异步头，任务返回格式会对不上，所以主 API 会自动回退同步路径。

蒙版局部重绘也不走异步，直接提示使用同步图片线路。

另外每条模型线路都有一个 `asyncImageTasks` 开关。某条线路不支持或者上游行为不稳定时，可以单独回退同步模式，不需要回滚整个网关。

**异步不是“全面替换同步”，而是只接管适合异步的那一段。**

这个边界必须提前写清楚。否则上线后最容易被问的不是“为什么慢”，而是“为什么带参考图的请求行为不一样”。

## 八、怎么验证

验证分三层：

1. **主 API 编排**：提交后拿到任务 ID，第一次轮询返回 `in_progress`，第二次返回完成结果，最终图片正常落库；
2. **网关 Worker**：模拟上游延迟，检查任务状态、结果保存、失败退款和超时回收；
3. **路由与兼容**：默认走异步、线路开关能回退同步、带参考图请求自动走 `/images/edits`。

发布前没有拿真实 4K 任务去付费上游烧钱验收，先把模拟上游的提交、轮询、失败和恢复路径跑通。对这类改造来说，状态机是否正确，比多生成一张图更重要。

## 九、最后三条经验

### 1. 超时不是一个数字

业务超时、连接池超时、网关超时、代理超时、上游超时，是五层不同的问题。

看到“代码写了 15 分钟却 5 分钟失败”，先查传输层默认值，不要直接怀疑模型。

### 2. 异步任务的核心不是 202

返回任务 ID 很容易，难的是：

- 重复提交怎么办；
- 进程重启怎么办；
- 多副本抢同一个任务怎么办；
- 失败后谁退款；
- 任务卡死谁回收；
- 结果怎么保存和查询。

这些没处理完，异步只是把同步错误藏到了后台。

### 3. 先划边界，再谈覆盖率

这次只让纯文生图走异步，参考图和局部重绘继续同步。

看起来不够“彻底”，但每条路径都有明确回退方式，线上出问题时可以按线路关闭，而不是一次性回滚整个生成链路。

对我们来说，这次改造真正解决的不是一个 5 分钟报错，而是把“提交”和“执行”拆开了。

只要生成任务还会越来越慢，这个边界迟早都要画。

我们给图片生成业务留了 15 分钟超时，但 Node 内置 fetch 底层的 undici headersTimeout 默认只有 5 分钟。4K 图片还没生成完，请求先在客户端被判定失败。

4K 生图总是 5 分钟超时：我把同步请求拆成了异步任务

后端

架构设计

人工智能

4K生图5分钟超时，实为同步请求被undici默认300秒headersTimeout误杀。根治方案：将长请求改造为异步任务——提交后立即返回任务ID，Worker后台执行，主API轮询结果。重点解决幂等映射、CAS状态一致性、失败退款与超时回收，并明确异步仅覆盖纯文生图场景。此架构分离提交与执行，避免长连接占用，支持任务治理与稳定回退。

负载均衡

代码解释

数据库

路由

Nginx

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

4K生图5分钟超时，实为同步请求被undici默认300秒headersTimeout误杀。根治方案：将长请求改造为异步任务——提交后立即返回任务ID，Worker后台执行，主API轮询结果。重点解决幂等映射、CAS状态一致性、失败退款与超时回收，并明确异步仅覆盖纯文生图场景。此架构分离提交与执行，避免长连接占用，支持...

4K 生图总是 5 分钟超时：我把同步请求拆成了异步任务-腾讯云开发者社区-腾讯云

4K 生图总是 5 分钟超时：我把同步请求拆成了异步任务

4K 生图总是 5 分钟超时：我把同步请求拆成了异步任务

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐