音乐生成 504 修复记录 | MiniMax Music Gen Fix

🤖 Hermes Agent · 分析

1. 根因分析

问题	根因
🎵 音乐 504 超时	XinCache nginx `proxy_read_timeout` ~60s，而 MiniMax 音乐生成 API 需要 60–90s。nginx 在 PHP 返回前断开连接 → 浏览器收到 HTML 504 而非 JSON → 前端解析报错
🗣️ TTS 童声问题	Agent 传入无效 `voice_id`（如"童声"），不在 enum 列表内。现有 handler 已兜底：出错返回 10 种可用音色列表，不需改代码

修复前的请求链路：

浏览器 → proxy.php (XinCache nginx) → PHP-FPM → curl → MiniMax API
                          ↓
                  nginx proxy_read_timeout ~60s
                  返回 504 Gateway Time-out ✗

2. 环境约束（关键发现）

通过向 XinCache 上传 PHP 探测脚本，发现服务器极端受限：

约束项	值	影响
`disable_functions`	`exec, proc_open, shell_exec, system, popen, passthru, pcntl_exec`等全部禁用	无法启动后台独立进程
`open_basedir`	`/webHome/.../www:/vhost/tmp`	`/tmp/` 不可写，只能用 `/vhost/tmp/`
`max_execution_time`	30s	常规 PHP 处理超时，但 curl IO 等待不计入
`fastcgi_finish_request`	可用 ✅	可先发响应、再后台处理

3. 修复方案

3.1 技术选型

所有进程执行函数均已禁用，因此无法使用 exec("nohup php worker.php &") 启动独立后台进程。最终采用 fastcgi_finish_request 去前台后处理 方案——利用 curl IO 等待不消耗 CPU 时间（不触发 30s max_execution_time），在同一 PHP-FPM 进程内异步处理：

请求 → proxy.php
         │
         ├─ ① 保存参数到 /vhost/tmp/music_tasks/{taskId}.params
         ├─ ② echo json_encode({task_id, status: "processing"})
         ├─ ③ fastcgi_finish_request()  ← 立即发送响应到 nginx/浏览器
         │
         └─ ④ PHP 继续后台执行
               ├─ curl_setopt_timeout(180s) → MiniMax API
               ├─ curl_exec() ← IO 等待，不消耗 CPU 时间
               ├─ 写入 /vhost/tmp/music_tasks/{taskId}.result
               └─ exit

3.2 前端改动

前端 music_generation handler 改为两步：

创建任务：proxyRequest('minimax','/music_generation', body) → 返回 {task_id}（0.18s）
轮询结果：proxyRequest('minimax','/music_poll', {task_id})，指数退避 3s→10s，最多 180s

3.3 修复的 Bug

#	Bug	修复
🔴	proxy.php Auth header: `'Authorization: Bearer *** . $key'`（本地备份文件中的占位符）	修复为 `'Authorization: Bearer ' . $key`（正确的 PHP 字符串拼接）
🔴	音乐生成 504→前端解析 HTML 报错	异步模式 + 轮询兜底，不再依赖同步等待
🟡	缺少 `output_format:'url'`（官方 SDK 需求）	之前已修复：显式传参
🟡	genre/mood 等结构化参数作为扁平字段发送	之前已修复：折叠进 prompt 文本

4. 验证结果

测试项	结果	耗时
Chat Completions	✅ 正常	~2s
TTS	✅ 音频 URL 返回	~5s
Music 创建	✅ task_id 立即返回	0.18s（不再 504）
Music 后台结果	✅ audio_url 有效	~86s 轮询完成
`fastcgi_finish_request` 存活	✅ 30s 后台 sleep 成功	request_terminate_timeout > 30s

5. 已修改文件

文件	改动
`proxy.php`	新增异步 `/music_generation` + `/music_poll` 端点；修复 Auth header 占位符；使用 `/vhost/tmp/`
`ui2.html`	`music_generation` handler 改为两步轮询（3s→10s 指数退避，180s 上限）

6. 注意事项

并发限制：每个音乐任务占用一个 PHP-FPM worker 60-90s。如果并发生成多首音乐，可能耗尽 XinCache 的 FPM 连接池。这是托管环境的固有约束。
request_terminate_timeout：已验证 >30s，但若音乐生成超过此值时可能导致失败。目前 180s curl timeout 配合合理。
文件清理：/vhost/tmp/music_tasks/ 中的 .params 和 .result 文件在 poll 成功后自动删除。
全局站：不支持 PHP。音乐生成功能仅限香港站 cmdcode.cn。
TTS 无效音色：handler 已有兜底逻辑，出错时返回可用音色列表。

7. 参考链接

MiniMax CLI Official SDK — 参考了 music_generation 端点的参数结构
PHP: fastcgi_finish_request — 核心异步机制
proxy.php (deployed) — 修复后的代理文件

🔧 MiniMax 音乐生成 504 错误修复