Fish Speech 1.5镜像启动排错手册：7860/7861端口异常定位与修复

1. 问题概述与排查思路

Fish Speech 1.5镜像采用双服务架构设计，前端WebUI服务运行在7860端口，后端API服务运行在7861端口。当出现端口异常时，通常表现为以下几种情况：

• 7860端口无法访问：浏览器打开显示连接失败或长时间加载
• 7861端口无响应：API调用返回连接拒绝错误
• 双端口均异常：服务完全无法启动或运行

排查思路遵循从简到繁的原则：先检查服务状态，再查看日志信息，最后进行深度诊断。整个过程不需要复杂的命令，只需几个简单的终端操作就能定位问题。

2. 基础状态检查方法

2.1 端口状态快速检查

首先检查两个关键端口的监听状态：

# 检查7860端口（前端WebUI）
lsof -i :7860

# 检查7861端口（后端API）  
lsof -i :7861

正常情况应该看到类似这样的输出：

COMMAND   PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
python  12345 root    3u  IPv4  12345      0t0  TCP *:7860 (LISTEN)

如果没有任何输出，说明对应端口的服务没有正常启动。

2.2 服务进程检查

查看Fish Speech相关进程是否在运行：

ps aux | grep fish_speech

应该能看到两个主要进程：一个是后端API服务，一个是前端WebUI服务。如果只有一个或者完全没有，说明服务启动有问题。

2.3 服务启动状态验证

通过查看启动日志来确认服务状态：

# 实时查看日志尾部
tail -f /root/fish_speech.log

# 或者查看最后50行日志
tail -50 /root/fish_speech.log

正常启动的日志应该包含这样的关键信息：

后端API服务已启动在7861端口
前端WebUI服务已启动在7860端口
Running on http://0.0.0.0:7860

3. 常见问题与解决方案

3.1 首次启动延迟问题

问题现象：部署实例后，7860端口长时间无法访问，日志显示"正在编译CUDA Kernel"

原因分析：首次启动时需要编译CUDA内核，这个过程需要60-90秒时间

解决方案：

1. 耐心等待90秒左右
2. 通过日志监控编译进度：tail -f /root/fish_speech.log
3. 看到"后端API已就绪"和"启动前端WebUI"提示后再访问

验证方法：

# 等待2分钟后检查端口
sleep 120 && lsof -i :7860

3.2 端口冲突问题

问题现象：日志显示端口已被占用，服务启动失败

解决方案：

# 查找占用7860端口的进程
lsof -i :7860

# 如果确实有冲突，可以终止占用进程（谨慎操作）
kill -9 <进程ID>

# 重新启动服务
bash /root/start_fish_speech.sh

3.3 模型权重加载失败

问题现象：服务能启动但生成语音失败，日志显示模型加载错误

检查方法：

# 检查模型文件是否存在
ls -la /root/fish-speech/checkpoints/fish-speech-1___5/

# 检查文件大小（应该有两个主要文件）
# model.pth 约1.2GB
# firefly-gan-vq-fsq-8x1024-21hz-generator.pth 约180MB

解决方案：如果文件缺失或损坏，需要重新部署镜像

3.4 显存不足问题

问题现象：服务启动后很快崩溃，日志显示CUDA out of memory

检查方法：

# 查看GPU显存使用情况
nvidia-smi

# 查看已用显存
nvidia-smi --query-gpu=memory.used --format=csv

解决方案：

• 确保GPU显存不小于6GB
• 关闭其他占用显存的程序
• 如果显存刚好6GB，尝试减少并发请求

4. 深度诊断方法

4.1 服务启动流程检查

手动执行启动脚本，观察详细输出：

# 进入root目录
cd /root

# 手动启动并查看详细输出
bash -x start_fish_speech.sh

这个过程会显示脚本执行的每一步，有助于定位具体哪一步出错。

4.2 单独测试后端服务

如果双服务启动失败，可以尝试单独启动后端API：

# 单独启动后端API服务
cd /root/fish-speech
python tools/api_server.py --host 0.0.0.0 --port 7861

如果后端能正常启动，说明问题可能出在前端WebUI服务。

4.3 网络连通性测试

测试端口内部连通性：

# 测试7861端口内部访问
curl -v http://127.0.0.1:7861/v1/health

# 测试7860端口内部访问
curl -v http://127.0.0.1:7860

如果内部访问正常但外部无法访问，可能是网络配置或防火墙问题。

5. 系统资源检查

5.1 硬件资源验证

检查系统是否满足最低要求：

# 检查GPU是否可用
nvidia-smi

# 检查显存大小（需要≥6GB）
nvidia-smi --query-gpu=memory.total --format=csv

# 检查系统内存
free -h

# 检查磁盘空间
df -h /root

5.2 依赖包检查

检查关键Python包是否正确安装：

# 检查PyTorch和CUDA
python -c "import torch; print(f'PyTorch版本: {torch.__version__}'); print(f'CUDA可用: {torch.cuda.is_available()}')"

# 检查Fish Speech依赖
python -c "import gradio; import fastapi; print('基础依赖正常')"

6. 高级排查技巧

6.1 日志级别调整

如果需要更详细的日志信息，可以调整日志级别：

# 查看当前日志配置
cat /root/fish-speech/config/logging.conf

# 临时提高日志级别（在启动前设置）
export LOG_LEVEL=DEBUG
bash /root/start_fish_speech.sh

6.2 服务健康检查

创建自动化健康检查脚本：

# 创建健康检查脚本
cat > /root/health_check.sh << 'EOF'
#!/bin/bash
echo "检查时间: $(date)"
echo "7860端口状态:"
lsof -i :7860 || echo "未监听"
echo "7861端口状态:"
lsof -i :7861 || echo "未监听"
echo "进程状态:"
ps aux | grep fish_speech | grep -v grep
EOF

chmod +x /root/health_check.sh

7. 预防措施与最佳实践

7.1 启动顺序优化

确保服务按正确顺序启动：

1. 先启动后端API服务（7861端口）
2. 等待后端就绪后再启动前端WebUI（7860端口）
3. 前端通过HTTP调用后端服务

7.2 资源监控设置

设置资源监控告警：

# 监控显存使用情况
watch -n 10 nvidia-smi

# 监控服务进程
while true; do
    ps aux | grep fish_speech | grep -v grep || echo "服务异常停止"
    sleep 30
done

7.3 定期维护建议

• 定期清理临时文件：rm -f /tmp/fish_speech_*.wav
• 监控日志文件大小，避免磁盘写满
• 定期检查模型文件完整性

8. 总结

通过本手册介绍的方法，可以系统性地排查和解决Fish Speech 1.5镜像的端口异常问题。关键排查步骤包括：

1. 基础检查：端口状态、服务进程、启动日志
2. 常见问题：首次启动延迟、端口冲突、显存不足
3. 深度诊断：服务启动流程、网络连通性、资源验证
4. 预防措施：启动顺序优化、资源监控、定期维护

大多数端口异常问题都可以通过查看日志和检查端口状态来解决。如果问题持续存在，建议重新部署镜像或联系技术支持。

记住排查黄金法则：先看日志，再查端口，最后深度诊断。按照这个顺序，绝大多数问题都能快速定位和解决。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。