FunASR Docker部署及WebSocket连接问题解决方案

背景介绍

FunASR作为一款开源的语音识别工具，提供了便捷的Docker部署方式。但在实际部署过程中，用户可能会遇到WebSocket连接失败的问题。本文将详细分析问题原因并提供解决方案。

典型问题现象

1. Docker容器正常启动，端口映射正确（如10098:10095）
2. 基础网络测试（telnet）通过
3. Web UI客户端无法建立连接（无论使用wss/ws/http协议）

根本原因分析

经过技术验证，该问题主要由以下两个因素导致：

1. SSL/TLS配置问题：服务端和客户端需要同时启用SSL加密通信
2. 模型加载失败：部分模型文件可能因网络问题下载不完整

解决方案

方案一：SSL配置调整

1. 服务端启动时确保SSL证书配置正确
2. 客户端连接时选择正确的协议（wss）
3. 在浏览器中手动授权SSL证书（首次连接时）

方案二：模型完整性检查

1. 检查Docker日志中的模型下载情况
2. 确保模型下载目录有足够权限
3. 建议的模型目录结构：

   /workspace/models/
   ├── damo/
   │   ├── speech_fsmn_vad_zh-cn-16k-common-onnx
   │   ├── speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-pytorch
   │   └── punc_ct-transformer_cn-en-common-vocab471067-large-onnx
   └── hotwords.txt
   

最佳实践建议

1. 使用完整的启动命令示例：

   docker run -it --rm \
   -p 10098:10095 \
   -v /path/to/models:/workspace/models \
   registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-gpu-0.1.1 \
   bash run_server.sh \
   --download-model-dir /workspace/models \
   --vad-dir damo/speech_fsmn_vad_zh-cn-16k-common-onnx \
   --model-dir damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-pytorch \
   --punc-dir damo/punc_ct-transformer_cn-en-common-vocab471067-large-onnx \
   --certfile /path/to/cert.pem
   

2. 客户端连接时注意：

   • 使用完整URL格式：wss://[IP]:10098/
   • 首次连接需处理SSL证书授权
   • 确保网络访问策略允许相关端口通信

总结

FunASR的Docker部署虽然简单，但需要注意SSL配置和模型完整性两个关键点。通过本文的解决方案，用户可以快速建立稳定的语音识别服务连接。建议在部署前仔细检查模型下载情况，并在生产环境使用有效的SSL证书。