53 lines
3.3 KiB
Markdown
53 lines
3.3 KiB
Markdown
---
|
|
id: T-553
|
|
title: cmhub 生图超时口径调优（连接 66 秒，读取 900 秒）
|
|
phase: 7
|
|
deps: [T-535, T-545, T-547, T-548]
|
|
status: TODO
|
|
created: 2026-07-08
|
|
---
|
|
|
|
## 问题 / 背景
|
|
|
|
cmhub 生图偶发超时或连接失败。当前桌面端口径是：
|
|
|
|
- `ai.cmhub.connect_timeout` 默认 `10` 秒，慢网络、服务端连接队列或代理环境下容易过早报「连接 cmhub 超时」。
|
|
- cmhub 生图请求和随后 `image_url` 下载的读取等待固定 `650` 秒。如果 cmhub 线上 Nginx/Gunicorn 允许请求等待到 `900` 秒，桌面端会先于服务端超时，产生“服务端仍在生成或已扣点，本地先失败”的歧义。
|
|
- 生图是非幂等接口，读超时后不能自动重发，否则可能重复扣点。
|
|
|
|
cmhub 项目侧建议：桌面端连接超时提高到 60/120 秒量级；生图 read timeout 与线上 Nginx/Gunicorn 对齐到 900 秒。本项目第一版取中间偏保守值：连接超时默认 `66` 秒，生图读取等待 `900` 秒。
|
|
|
|
## 方案
|
|
|
|
1. **cmhub 连接超时默认改为 66 秒**
|
|
- `DEFAULT_CONFIG.ai.cmhub.connect_timeout` 从 `10` 改为 `66`。
|
|
- `cmhub_config()` 对缺失值使用 `66`。
|
|
- ⑤设置页 cmhub「连接超时(秒)」默认值改为 `66`，范围仍保持 `1..3600`。
|
|
- 兼容旧配置：如果旧 `data/config.json` 中该值缺失或仍是旧默认 `10`，迁到 `66`，确保已安装用户升级后也生效；若用户明确配置了其它正整数，保留用户配置。用户确实需要更短连接超时时，仍可在⑤设置页手工改小并保存。
|
|
|
|
2. **cmhub 生图读取等待改为 900 秒**
|
|
- `CMHUB_IMAGE_READ_TIMEOUT_SECONDS` 从 `650` 改为 `900`。
|
|
- 生图请求 `POST /api/v1/generate/image` 的 `read_timeout` 使用 `900`。
|
|
- 随后的 `image_url` 下载读取等待、curl `--max-time` 同步使用 `900`，保持现有统一口径。
|
|
- ⑤设置页「返回超时」只读展示改为「标题 600 秒 / 图片 900 秒」。
|
|
|
|
3. **保持非幂等安全边界**
|
|
- 生图读超时仍不可自动重发；只允许连接超时、`rate_limited`、`upstream_error` 按现有规则处理。
|
|
- 下载失败仍只复用已返回的同一个 `image_url` 做下载层重试，不重新调用 cmhub 生图接口。
|
|
- 不把图片并发默认值调高；用户排障时仍建议先把图片并发降到 1 或 2，稳定后再试 3。
|
|
|
|
## 验收要点
|
|
|
|
- 新默认配置中 `ai.cmhub.connect_timeout == 66`。
|
|
- ⑤设置页 cmhub 连接超时默认显示 `66`。
|
|
- cmhub 生图请求 timeout 为 `(connect_timeout, 900)`。
|
|
- cmhub 图片下载 requests timeout 为 `(connect_timeout, 900)`。
|
|
- curl 下载参数 `--max-time` 为 `900`。
|
|
- ⑤设置页「返回超时」显示「标题 600 秒 / 图片 900 秒」。
|
|
- 生图读超时仍不自动重发；相关单测继续覆盖“不重复扣点”的行为。
|
|
- 更新 `docs/04-architecture.md`、`docs/cmhub-integration-design.md`、`docs/02-requirements.md` 的超时口径。
|
|
|
|
## 边界（不改什么）
|
|
|
|
只改 cmhub 连接超时默认值、生图读取等待常量、⑤设置页显示文案、相关单测和文档；不改 cmhub API 协议、Base URL/Key/别名配置结构、标题读取等待 600 秒、图片并发上限 5、下载线程池语义、DB、Excel、Shopee/CDP 更新流程，也不增加生图读超时重试。
|