PHP文生图接口异常？熔断机制法-php教程-PHP中文网

php文生图接口返回503是因熔断器主动拦截保护后端，需检查error_code、retry-after头、限制超时至8秒、缓存失败时间、降级fallback，并确认provider已退出半开态。

php文生图接口异常？熔断机制法

PHP 文生图接口不是“挂了”，而是被熔断器主动掐断了——它在保护后端模型服务不被拖垮。

为什么 PHP 调用文生图接口总返回 503 或自定义错误码

这不是网络超时或 token 错误，而是上游服务（比如 Z-Image-Turbo 或 SDXL 推理网关）触发了熔断。常见现象包括：

连续几次请求都卡在 curl_exec() 超时（如 30s），之后突然全部返回 503 Service Unavailable 或 {"error_code": "provider_down"}
错误响应里带 retry-after header，但重试无效
日志里查不到模型侧报错，只看到“服务不可用”类降级日志

根本原因是：PHP 客户端没感知熔断状态，还在拼命发请求；而服务端已将该 provider 标记为“故障”，所有流量被拦截并走本地降级逻辑。

PHP 侧如何配合熔断器做优雅重试

不能靠 while (true) 硬重试，得按熔断器的节奏来。关键点：

PHP

编写健壮的PHP代码，规避类型转换陷阱、数组怪癖及常见安全漏洞。

下载

检查响应状态码和 body 中是否含 "error_code" 字段，如 "model_unavailable"、"auth_unavailable"，这类是明确熔断信号
读取响应 header 中的 retry-after 值（单位秒），若存在则必须 sleep 对应时间再发起下一次请求
避免并发请求打穿熔断窗口：用 apcu_store() 缓存最近一次失败时间戳，10 秒内相同 provider 的请求直接跳过
降级 fallback：当检测到熔断时，可返回缓存图（/static/fallback.jpg）或调用备用模型 API（如从 Z-Image 切到 ComfyUI 兼容接口）

PHP cURL 请求必须加的三个熔断友好配置

默认 curl_setopt() 设置会让熔断器误判健康状态：

务必设 CURLOPT_TIMEOUT_MS ≤ 8000（8 秒），否则单次请求拖太久，熔断器统计的“超时率”虚高
禁用 CURLOPT_CONNECTTIMEOUT_MS 单独设置，改用统一 CURLOPT_TIMEOUT_MS 控制全程，避免连接快但处理慢却被放行
加上 CURLOPT_HTTPHEADER 包含 "X-Request-ID: " . uniqid("req_")，方便熔断器按 trace_id 统计失败链路，而不是粗暴封整个 IP

示例片段：

curl_setopt($ch, CURLOPT_TIMEOUT_MS, 8000);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Request-ID: ' . uniqid('req_')
]);