Ana Sayfa Keşfet Yardım
Giriş Yap
renzixin
/
ai_fwt_pro
1
0
Çatalla 0
Dosyalar Sorunlar 0 Değişiklik İstekleri 0 Wiki
Ağaç: c4197b0ad0
Dallar Biçim İmleri
ai_fwt_pro
/
docs
/
mqtt-gateway-integration.md

mqtt-gateway-integration.md 8.5 KB
Geçmiş Ham

MQTT 网关部署教程

xiaozhi-esp32-server项目，可结合虾哥开源的xiaozhi-mqtt-gateway 项目进行简单改造，即可实现小智硬件MQTT+UDP连接。 本教程分为三部分，你可以根据你是全模块部署还是单模块部署，选择对应的部分接入MQTT网关：

  • 第一部分：部署MQTT网关
  • 第二部分：全模块运行实现小智硬件MQTT+UDP连接
  • 第三部分：单模块运行xiaozhi-server实现小智硬件MQTT+UDP连接

准备阶段

准备好你的xiaozhi-server的mqtt-websocket连接地址。在你原来的websocket地址基础上，添加?from=mqtt_gateway字符，就可以得到mqtt-websocket连接地址

1、如果你是源码部署，你的mqtt-websocket地址是：

ws://127.0.0.1:8000/xiaozhi/v1/?from=mqtt_gateway

2、如果你是docker部署，你的mqtt-websocket地址是

ws://你宿主机局域网IP:8000/xiaozhi/v1/?from=mqtt_gateway

重要提示

如果你是服务器部署，需要确保服务器1883、8884、8007端口都对外开放。8884选择的协议类型是UDP，其他是TCP。

如果你是服务器部署，需要确保服务器1883、8884、8007端口都对外开放。8884选择的协议类型是UDP，其他是TCP。

如果你是服务器部署，需要确保服务器1883、8884、8007端口都对外开放。8884选择的协议类型是UDP，其他是TCP。

第一部分：部署MQTT网关

  1. 克隆改造后的xiaozhi-mqtt-gateway项目：

    git clone https://ghfast.top/https://github.com/xinnan-tech/xiaozhi-mqtt-gateway.git
cd xiaozhi-mqtt-gateway

  2. 安装依赖：

    npm install
npm install -g pm2

  3. 配置 config.json：

    cp config/mqtt.json.example config/mqtt.json

  4. 编辑配置文件 config/mqtt.json，把你在本文准备阶段的mqtt-websocket地址替换到chat_servers里。例如源码部署的xiaozhi-server就是如下配置：

{
    "production": {
        "chat_servers": [
            "ws://127.0.0.1:8000/xiaozhi/v1/?from=mqtt_gateway"
        ]
    },
    "debug": false,
    "max_mqtt_payload_size": 8192,
    "mcp_client": {
        "capabilities": {
        },
        "client_info": {
            "name": "xiaozhi-mqtt-client",
            "version": "1.0.0"
        },
        "max_tools_count": 128
    }
}
  1. 在项目根目录创建下.env文件，并设置以下环境变量: PUBLIC_IP=your-ip # 服务器公网IP MQTT_PORT=1883 # MQTT服务器端口 UDP_PORT=8884 # UDP服务器端口 API_PORT=8007 # 管理API端口 MQTT_SIGNATURE_KEY=test # MQTT签名密钥 SERVER_SECRET=Te1st12134 # 服务器密钥，请保持和智控台（server.secret）一致或者和xiaozhi-server里（server.auth_key）保持一致 请注意PUBLIC_IP配置，确保其与实际公网IP一致，如果有域名就填域名。

MQTT_SIGNATURE_KEY 是用于MQTT连接认证的密钥，最好设置成复杂一点的，最好是设置成8个字符以上且同时包含大小写字母，这个密钥稍后还会用到。

  • 注意不要用简单的密码，比如123456、test等。
  • 注意不要用简单的密码，比如123456、test等。
  • 注意不要用简单的密码，比如123456、test等。

SERVER_SECRET 是用生成websocket连接的认证信息。

1、如果你是全模块部署，且你的智控台的参数管理里server.auth.enabled设置成了true，那么，SERVER_SECRET需要和智控台（server.secret）保持一致。

2、如果你是单模块部署，且你在配置文件里把server.auth.enabled设置成了true，那么，SERVER_SECRET需要和配置文件里（server.auth_key）保持一致。

  1. 启动MQTT网关 ```

    启动服务

    pm2 start ecosystem.config.js

查看日志

pm2 logs xz-mqtt


当你看到如下日志，说明MQTT网关启动成功：

0|xz-mqtt | 2025-09-11T12:14:48: MQTT 服务器正在监听端口 1883 0|xz-mqtt | 2025-09-11T12:14:48: UDP 服务器正在监听 x.x.x.x:8884


如果需要重启MQTT网关，执行如下命令：

pm2 restart xz-mqtt


## 第二部分：全模块运行实现小智硬件MQTT+UDP连接

查看你智控台首页底部的版本号，确认你的智控台版本是否是`0.7.7`及以上版本。如果不是，需要升级智控台。

1. 在智控台顶部，点击`参数管理`，搜索`server.mqtt_gateway`，点击编辑，填入你在`.env`文件中设置的`PUBLIC_IP`+`:`+`MQTT_PORT`。类似这样

192.168.0.7:1883

2. 在智控台顶部，点击`参数管理`，搜索`server.mqtt_signature_key`，点击编辑，填入你在`.env`文件中设置的`MQTT_SIGNATURE_KEY`。

3. 在智控台顶部，点击`参数管理`，搜索`server.udp_gateway`，点击编辑，填入你在`.env`文件中设置的`PUBLIC_IP`+`:`+`UDP_PORT`。类似这样

192.168.0.7:8884

4. 在智控台顶部，点击`参数管理`，搜索`server.mqtt_manager_api`，点击编辑，填入你在`.env`文件中设置的`PUBLIC_IP`+`:`+`API_PORT`。类似这样

192.168.0.7:8007


上面的配置完成后，你可以使用curl命令，验证你的ota地址是否会下发mqtt配置，把下面的`http://localhost:8002/xiaozhi/ota/`改成你的ota地址

curl 'http://localhost:8002/xiaozhi/ota/' \ -H 'Content-Type: application/json' \ -H 'Client-Id: 7b94d69a-9808-4c59-9c9b-704333b38a' \ -H 'Device-Id: 11:22:33:44:55:66' \ --data-raw $'{\n "application": {\n "version": "1.0.1",\n "elf_sha256": "1"\n },\n "board": {\n "mac": "11:22:33:44:55:66"\n }\n}'


如果返回的内容包含`mqtt`相关的配置，说明配置成功。类似这样

{"server_time":{"timestamp":1757567894012,"timeZone":"Asia/Shanghai","timezone_offset":480},"activation":{"code":"460609","message":"http://xiaozhi.server.comn460609","challenge":"11:22:33:44:55:66"},"firmware":{"version":"1.0.1","url":"http://xiaozhi.server.com:8002/xiaozhi/otaMag/download/NOT_ACTIVATED_FIRMWARE_THIS_IS_A_INVALID_URL"},"websocket":{"url":"ws://192.168.4.23:8000/xiaozhi/v1/"},"mqtt":{"endpoint":"192.168.0.7:1883","client_id":"GID_default@@@11_22_33_44_55_66@@@7b94d69a-9808-4c59-9c9b-704333b38aff","username":"eyJpcCI6IjA6MDowOjA6MDowOjA6MSJ9","password":"Y8XP9xcUhVIN9OmbCHT9ETBiYNE3l3Z07Wk46wV9PE8=","publish_topic":"device-server","subscribe_topic":"devices/p2p/11_22_33_44_55_66"}}


由于MQTT信息是需要靠OTA地址下发的，因此只有你保证能正常连接服务器的OTA地址，重启唤醒即可。

唤醒后留意mqtt-gateway的日志，确认是否有连接成功的日志。

pm2 logs xz-mqtt


## 第三部分：单模块运行xiaozhi-server实现小智硬件MQTT+UDP连接

打开你的`data/.config.yaml`文件，在`server`下找到`mqtt_gateway`填入你在`.env`文件中设置的`PUBLIC_IP`+`:`+`MQTT_PORT`。类似这样

192.168.0.7:1883

在`server`下找到`mqtt_signature_key`填入你在`.env`文件中设置的`MQTT_SIGNATURE_KEY`。

在`server`下找到`udp_gateway`填入你在`.env`文件中设置的`PUBLIC_IP`+`:`+`UDP_PORT`。类似这样

192.168.0.7:8884


上面的配置完成后，你可以使用curl命令，验证你的ota地址是否会下发mqtt配置，把下面的`http://localhost:8002/xiaozhi/ota/`改成你的ota地址

curl 'http://localhost:8002/xiaozhi/ota/' \ -H 'Device-Id: 11:22:33:44:55:66' \ --data-raw $'{\n "application": {\n "version": "1.0.1",\n "elf_sha256": "1"\n },\n "board": {\n "mac": "11:22:33:44:55:66"\n }\n}'


如果返回的内容包含`mqtt`相关的配置，说明配置成功。类似这样

{"server_time":{"timestamp":1758781561083,"timeZone":"GMT+08:00","timezone_offset":480},"activation":{"code":"527111","message":"http://xiaozhi.server.comn527111","challenge":"11:22:33:44:55:66"},"firmware":{"version":"1.0.1","url":"http://xiaozhi.server.com:8002/xiaozhi/otaMag/download/NOT_ACTIVATED_FIRMWARE_THIS_IS_A_INVALID_URL"},"websocket":{"url":"ws://192.168.1.15:8000/xiaozhi/v1/"},"mqtt":{"endpoint":"192.168.1.15:1883","client_id":"GID_default@@@11_22_33_44_55_66@@@11_22_33_44_55_66","username":"eyJpcCI6IjE5Mi4xNjguMS4xNSJ9","password":"fjAYs49zTJecWqJ3jBt+kqxVn/x7vkXRAc85ak/va7Y=","publish_topic":"device-server","subscribe_topic":"devices/p2p/11_22_33_44_55_66"}}


由于MQTT信息是需要靠OTA地址下发的，因此只有你保证能正常连接服务器的OTA地址，重启唤醒即可。

唤醒后留意mqtt-gateway的日志，确认是否有连接成功的日志。

pm2 logs xz-mqtt ```