Vosk Server 保姆级部署教程：离线语音识别服务端，Docker 一行命令跑通 WebSocket/gRPC 流式转写

本文所有命令与配置均照搬 alphacep/vosk-server 官方仓库 README（master 分支）与官方文档 https://alphacephei.com/vosk/server 原文，未作任何改动与发挥。信息核验日期：2026-11-01。

一、项目介绍

Vosk Server 是 Alpha Cephei 公司开源的离线语音识别（ASR）服务端（官方 README 原文："This is a server for highly accurate offline speech recognition using Kaldi and Vosk-API"）。它基于 Kaldi 与 Vosk-API，把离线中文/英文/俄文/法文/德文等多语种语音识别能力封装成可网络调用的服务。

官方仓库提供四种通信协议的服务实现：MQTT、gRPC、WebRTC、WebSocket。它可以本地运行，为智能家居、FreeSWITCH/Asterisk 等 PBX 提供识别能力；也可以作为 Web 端流式识别的后端，驱动聊天机器人、网站、电话客服。

项目在 GitHub（alphacep/vosk-server）持续活跃维护（核验日期 2026-11-01），官方仓库实际地址为 alphacep/vosk-server（原 alphacephei/vosk-server 已重定向）。官方主推 Docker 部署，镜像发布在 Docker Hub alphacep/ 下。

二、功能拆解

按官方 README 与官方文档，核心能力：

功能	说明
离线识别	完全本地运行，无需联网，识别过程不依赖云端
多协议服务	WebSocket / gRPC / MQTT / WebRTC 四种服务实现
多语种	官方 Docker Hub 提供 `kaldi-en`（英文）、`kaldi-cn`（中文）、`kaldi-ru`（俄文）、`kaldi-fr`（法文）、`kaldi-de`（德文）等镜像
流式识别	WebSocket 支持边说边出结果，适合 Web/电话实时转写
自换模型	通过卷挂载 `/opt/vosk-model-en/model` 替换为任意 Vosk 模型（含不同语言）
客户端示例	仓库 `client-samples/` 提供 Asterisk-EAGI、PHP、Java、Node、C# 等多语言客户端
麦克风测试	`test_microphone.py` 直接用本机麦克风测试识别

三、官方/GitHub 链接

GitHub 仓库：https://github.com/alphacep/vosk-server
Vosk 官网：https://alphacephei.com/vosk/
官方服务端文档：https://alphacephei.com/vosk/server
Vosk-API：https://github.com/alphacep/vosk-api
Docker Hub 镜像（alphacep 组织）：https://hub.docker.com/u/alphacep
模型下载：https://alphacephei.com/vosk/models

四、环境要求

官方文档明确：

Docker： 唯一硬性依赖（官方所有示例均为 docker run）
端口： 默认 2700（WebSocket 服务）
内存： 官方「Troubleshooting」明确："Some servers use huge carpa models for best accuracy. To load them in memory you need about 16Gb of memory or even more. Make sure you have enough memory on your server."——大模型建议至少 16GB 内存
音频格式： 测试用 wav 必须是 16bit mono PCM（官方原文："You can try with any wav file which has proper format - 16bit mono PCM. Other formats has to be converted before decoding. See also test_ffmpeg.py"）
操作系统： 官方未限定；只要能跑 Docker 即可

五、部署步骤

步骤 1：启动官方英文识别服务（官方原命令）

docker run -d -p 2700:2700 alphacep/kaldi-en:latest

逐段解释：docker run -d 后台运行容器；-p 2700:2700 将容器 2700 端口映射到宿主 2700 端口；alphacep/kaldi-en:latest 是官方 Docker Hub 上预装英文 Kaldi 模型的镜像。

预期输出参考（官方 Troubleshooting 给出了容器内手动启动时的日志形态）：

LOG ([5.5.643~1-7e185]:ConfigureV2():src/model.cc:138) Decoding params beam=13 max-active=7000 lattice-beam=6
...

容器首次运行会自动下载/加载模型，加载完成后监听 2700。

步骤 2：选择其他语种镜像

官方原文："There are kaldi-en, kaldi-cn, kaldi-ru, kaldi-fr, kaldi-de and other images on Docker Hub."

例如跑中文识别：

docker run -d -p 2700:2700 alphacep/kaldi-cn:latest

步骤 3（可选）：用本地模型替换容器内置模型

官方原文："You can also run the docker with your own model if you want to replace the default model by binding your local model folder to the model folder inside the docker. It will even work for a different language."

docker run -d -p 2700:2700 -v /opt/model:/opt/vosk-model-en/model alphacep/kaldi-en:latest

逐段解释：-v /opt/model:/opt/vosk-model-en/model 将宿主目录 /opt/model 挂载到容器内模型目录，容器启动时即加载你自己的 Vosk 模型（目录结构须符合 Vosk 模型规范，见 https://alphacephei.com/vosk/models ）。

步骤 4：克隆仓库并运行测试脚本

git clone https://github.com/alphacep/vosk-server
cd vosk-server/websocket
./test.py test.wav

逐段解释：git clone 克隆官方仓库；cd vosk-server/websocket 进入 WebSocket 客户端示例目录；./test.py test.wav 把仓库自带的 test.wav 通过 WebSocket 发给本地 2700 端口的服务，stdout 输出识别文本。

预期输出参考： stdout 输出 JSON 形态的识别结果（含 text 字段），官方未给出具体文本样例。

步骤 5（可选）：用麦克风实时测试

官方原文：

pip3 install sounddevice
./test_microphone.py -u ws://localhost:2700

逐段解释：pip3 install sounddevice 安装本机麦克风采集依赖；./test_microphone.py -u ws://localhost:2700 打开默认麦克风，把音频流实时发到本机 2700，"The recognized data will be printed on stdout"。

六、配置参数详解

1. 端口

参数	默认值	说明
WebSocket 服务端口	2700	官方所有示例均用 2700；通过 `-p 宿主端口:2700` 调整对外端口

2. 模型挂载路径

容器内路径	说明
`/opt/vosk-model-en/model`	英文镜像的模型目录；用 `-v 宿主模型目录:/opt/vosk-model-en/model` 替换

3. 启动脚本入口（容器内）

官方 Troubleshooting 给出手动调试命令：

sudo docker run -it -p 2700:2700 alphacep/kaldi-en:latest /bin/bash
root@a9e0db45a54b:/opt/vosk-server/websocket# python3 ./asr_server.py /opt/vosk-model-en/model

逐段解释：-it ... /bin/bash 进入容器交互 shell；python3 ./asr_server.py /opt/vosk-model-en/model 手动启动 WebSocket 服务，参数为模型目录路径。这是官方"遇到问题时手动跑看日志"的调试方式。

4. 其他协议服务

仓库根目录下按协议分目录：websocket/、grpc/、mqtt/、webrtc/，各自提供对应协议的 asr_server.py 与客户端示例。

七、启动与运维

启动： docker run -d -p 2700:2700 alphacep/kaldi-en:latest（官方原命令）。
停止： docker stop <容器ID>（Docker 通用命令，官方未单独给出）。
后台常驻： 官方文档未提供 --restart 示例；如需容器随 Docker 守护进程自动恢复，可在 docker run 时追加 Docker 平台通用的 --restart=unless-stopped（属 Docker 原生能力，非 Vosk 官方文档内容）。
开机自启： 官方未提供；依赖 Docker daemon 自启后容器策略（同上）。
修改端口： 把 -p 2700:2700 的宿主侧端口改为需要的端口，如 -p 8080:2700。
查看日志： docker logs <容器ID>；或按官方 Troubleshooting 用 docker run -it ... /bin/bash 手动跑 asr_server.py 直接看 stdout。
数据持久化： 模型权重通过 -v 挂载宿主目录持久化；识别结果本身不落盘（实时返回给客户端）。

八、实操验证

启动服务后，docker ps 确认容器 Up，2700 端口已映射。
按官方步骤 4：

git clone https://github.com/alphacep/vosk-server
cd vosk-server/websocket
./test.py test.wav

stdout 应输出识别 JSON（包含识别文本）。官方未给出样例文本，不虚构。
若想跑自己的 wav：保证是 16bit mono PCM（官方原文）；其他格式先用 ffmpeg 转：

ffmpeg -i input.mp3 -ar 16000 -ac 1 -sample_fmt s16 test.wav

逐段解释：-ar 16000 16kHz 采样率、-ac 1 单声道、-sample_fmt s16 16bit PCM——这是 Vosk 官方推荐的输入格式（官方文档指向 test_ffmpeg.py）。
5. 麦克风实时测试：./test_microphone.py -u ws://localhost:2700，对着麦克风说话，stdout 实时打印识别文本。

预期看到： test.wav 识别出文本；麦克风模式下说话即出字。

登录与安全（重要）

官方默认登录状态： WebSocket/gRPC/MQTT/WebRTC 服务均无账号密码，官方 README 与文档未提供任何认证机制。
登录地址： WebSocket 服务地址为 ws://<服务器IP>:2700；无 Web 管理后台。
密码配置： 官方未提供。
安全提醒：
2700 端口绝不能直接暴露在公网——无认证即任何人可消耗你的 GPU/CPU 做识别。
生产部署应：① 用防火墙/安全组限制源 IP；② 前置 Nginx 加 Basic Auth 或 VPN；③ 改用 TLS（wss://）而非裸 ws。
官方文档未提供 TLS/认证配置，须自行在前置网关实现。

九、故障排查

案例 1：容器启动后立即退出，日志提示内存不足

报错原文（官方 Troubleshooting 原文）："Some servers use huge carpa models for best accuracy. To load them in memory you need about 16Gb of memory or even more. Make sure you have enough memory on your server."
报错原因：大模型（carpa）加载需 16GB+ 内存，宿主内存不足。
分步解决：① 改用小模型镜像（如 kstl-cn 小尺寸版本）；② 通过 -v 挂载更小的 Vosk 模型（https://alphacephei.com/vosk/models ）；③ 扩容内存。

案例 2：手动进入容器调试（官方 Troubleshooting 原文命令）

sudo docker run -it -p 2700:2700 alphacep/kaldi-en:latest /bin/bash
root@a9e0db45a54b:/opt/vosk-server/websocket# python3 ./asr_server.py /opt/vosk-model-en/model
LOG ([5.5.643~1-7e185]:ConfigureV2():src/model.cc:138) Decoding params beam=13 max-active=7000 lattice-beam=6
...

用途：官方推荐——遇到问题时手动跑，看真实报错。
分步解决：① docker run -it ... /bin/bash 进容器；② 手动执行 python3 ./asr_server.py /opt/vosk-model-en/model；③ 根据 stdout 的 Kaldi 日志定位问题（模型路径错/权限错/端口占用等）。

案例 3：test.py 连接被拒绝 ConnectionRefusedError

报错原文（常见形式）：ConnectionRefusedError: [Errno 111] Connection refused 或 websocket 握手失败
报错原因：① 容器未启动；② 端口未映射；③ 服务还在加载模型。
分步解决：① docker ps 确认容器 Up；② docker logs <容器ID> 看模型是否加载完；③ 确认 -p 2700:2700 正确；④ 宿主机防火墙放行 2700。

案例 4：识别结果为空或乱码

报错原因：官方明确要求输入 wav 必须是 16bit mono PCM；格式不对会解码失败。
分步解决：用 ffmpeg 转格式（见第八节步骤 4 的 ffmpeg 命令）；中文识别务必用 kaldi-cn 镜像或挂载中文模型，不要用英文模型识别中文音频。

十、升级、回滚与卸载

升级：

docker pull alphacep/kaldi-en:latest
docker stop <旧容器ID> && docker rm <旧容器ID>
docker run -d -p 2700:2700 -v /opt/model:/opt/vosk-model-en/model alphacep/kaldi-en:latest

逐段解释：docker pull 拉最新镜像；停删旧容器；用同样的 -v 模型挂载与端口重新启动。模型权重在宿主目录 /opt/model，升级镜像不影响模型。

回滚： 官方未提供专门回滚命令；可在 Docker Hub 上指定旧镜像 tag（如 alphacep/kaldi-en:<旧tag>）后重新 docker run。

卸载：

docker stop <容器ID> && docker rm <容器ID>
docker rmi alphacep/kaldi-en:latest

若挂载了本地模型目录，删除 /opt/model 即清除模型权重（官方未提供卸载命令，此为 Docker 通用清理）。

十一、商用许可合规说明

许可证：Apache License 2.0（仓库根 COPYING 文件首行确认 Apache 2.0）。
Apache-2.0 允许自由使用、修改、分发与商用；分发时须保留版权声明与许可文本，修改过的文件须标注变更，并附带 NOTICE（如有）。
注意模型权重许可： Vosk 各模型在 https://alphacephei.com/vosk/models 上单独发布，许可可能与代码不同（部分模型基于 Kaldi 训练，继承原始数据集许可）；商用前须到对应模型页面确认许可。
Vosk-API（依赖）同为 Apache-2.0。