排查 AngeVoice 常见问题
先收集最小证据，再改配置。一次只改一个变量，避免把原始问题掩盖掉。
先做这五项检查
curl -s http://127.0.0.1:8100/health | python3 -m json.tool
curl -s http://127.0.0.1:8100/v1/models | python3 -m json.tool
docker ps --format "table {{{{.Names}}}}\t{{{{.Status}}}}\t{{{{.Ports}}}}"
docker logs --tail 200 <container-name>
df -h
按症状定位
| 现象 | 常见原因 | 先做什么 |
|---|---|---|
| 启动后一直下载模型 | 模型不存在、缓存不完整或 Git LFS 指针 | 检查模型文件头和大小；删除指针文件后让服务重新下载 |
/health 长时间 loading | 首次下载、CUDA 初始化或模型目录未持久化 | 观察日志和模型目录增长；确认 volume 挂载 |
| GPU OOM | 多模型同时加载、多个 worker、参考音频过长 | 保持单 worker，只加载当前模型，缩短参考音频 |
| MOSS 不可选 | 运行时缺失、路径错误或镜像不包含对应依赖 | 查看 /v1/models 的 unavailable reason |
| 克隆返回不支持 | 请求发给 Kokoro 或未选择克隆模型 | 明确设置 model=moss 或 zipvoice |
| WebSocket 连接但无音频 | 首包字段、Token、代理 Upgrade 或 PCM 播放错误 | 直连服务测试，再检查代理和采样率 |
| 401 | API Key 错误或未携带 Bearer Token | 从管理后台重新复制 Key，不要从日志猜测 |
| MP3 返回错误 | FFmpeg 或 MP3 功能未启用 | 先用 WAV 验证，再检查 ffmpeg -version |
识别 Git LFS 指针
head -5 models/models--hexgrad--Kokoro-82M-v1.1-zh/kokoro-v1_1-zh.pth
如果文件开头是 version https://git-lfs.github.com/spec/v1，它不是真实权重。可以执行：
git lfs install
git lfs pull
不要为了绕过权重加载错误直接设置 torch.load(weights_only=False)。不可信 PyTorch 权重可能执行代码。
检查 GPU 回退
nvidia-smi
curl http://127.0.0.1:8101/v1/models/current
docker logs --tail 200 angevoice-gpu | grep -Ei "cuda|cudnn|oom|fallback"
如果 CUDA 初始化失败但 CPU 可用，先确认功能链路，再处理驱动或 cuDNN。不要同时更换模型、镜像和运行参数。
克隆音频异常
- MOSS 参考音频不要放到 Kokoro 的
voices/*.pt目录。 - HTTP 使用 multipart 上传；WebSocket 在首个 JSON 的
prompt_audio.data传 base64 或 data URL。 - 参考音频过长会增加显存、延迟和失真风险。
- 爆音时先检查输入削波和输出增益，再比较关闭实时逐帧解码的结果。
反向代理
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 300s;
本地直连正常、代理后失败时，优先检查 WebSocket Upgrade、请求体大小和超时。
输出没有保存
ANGEVOICE_SAVE_OUTPUTS=true
ANGEVOICE_OUTPUT_DIR=/app/outputs
ANGEVOICE_OUTPUT_MAX_FILES=1000
同时确认 /app/outputs 已挂载到持久化目录。HTTP 和批量接口可以保存结果；WebSocket 实时流默认不落盘。
音色列表为空
ls -lh models/models--hexgrad--Kokoro-82M-v1.1-zh/voices/
docker exec -it <container-name> ls -lh /app/models/models--hexgrad--Kokoro-82M-v1.1-zh/voices/
如果目录为空或只有 Git LFS 指针，重新下载音色文件并确认模型目录挂载正确。
返回 429
按响应中的 Retry-After 退避重试。先降低客户端并发，不要直接关闭服务端限流。只有确认上游代理已提供等价保护时才调整 QPS 和 burst。
管理后台无法登录
grep -E 'KOKORO_ADMIN_ENABLED|ANGEVOICE_ADMIN_USERNAME|ANGEVOICE_ADMIN_PASSWORD' docker/angevoice.env
确认管理后台已启用、凭据目录可写且重启后仍挂载。修改密码后应使用新凭据；应用不会保存可恢复的明文密码。
提交问题前
提供版本、部署方式、硬件、/health 脱敏输出和相关日志片段。删除 API Key、Authorization、管理员密码、本地路径和 Provider 密钥。