# 准备 MQTT Broker

设备智能体通过 MQTT Broker 连接真实设备、SDK 和浏览器模拟器。启动前先准备 MQTT 连接信息：

```bash
MQTT_BROKER_URL=
VITE_MQTT_WS_URL=
MQTT_USERNAME=
MQTT_PASSWORD=
```

使用 TLS 时，MQTT 地址使用 `mqtts://`，WebSocket 地址使用 `wss://`。如果浏览器控制台和设备智能体不在同一台机器上，不要把 Broker 地址写成 `localhost`，请使用浏览器也能访问的域名或 IP。

## Zero EMQX

如果只是想先跑通设备连接，可以使用 Zero EMQX。它会创建一个临时 MQTT Broker，自动生成 MQTTS/WSS 地址和账号密码。Zero EMQX 由 [EMQX Cloud](https://www.emqx.com/zh/cloud) 提供，会自动过期，不适合长期运行。

有三种方式可以创建 Zero EMQX：

1. 让 Agent 创建。

在设备智能体中对 Agent 说：

```text
帮我创建一个 Zero EMQX MQTT Broker 测试实例，并把 MQTT 设置写入当前配置。
```

2. 在设置页创建。

打开 **Settings > MQTT**，点击 **Create test broker**。

通过 Agent 或设置页创建后，在 MQTT 设置页保存本页，让正在运行的网关使用新配置。

3. `.env` 自动创建。

首次部署或首次启动设备智能体时，可以在工作区 `.env` 中开启 Zero EMQX：

```bash
ZERO_EMQX_ENABLED=true
```

启动时会自动创建 Zero EMQX，并把 MQTT 设置写入配置。已经创建过的工作区不会重复创建。

可选：需要指定创建服务地址或标签时再设置：

```bash
ZERO_EMQX_MANAGER_URL=https://zero.emqx.io
ZERO_EMQX_TAG=device-agent
```

## EMQX

如果需要在自己的基础设施中运行 MQTT Broker，可以私有部署 EMQX。EMQX 适合生产环境、内网部署、数据留在本地或需要自主管理集群的场景。

Docker 启动：

```bash
docker run -d --name emqx \
  -p 1883:1883 -p 8083:8083 -p 8084:8084 -p 8883:8883 -p 18083:18083 \
  emqx/emqx-enterprise:latest
```

快捷脚本安装：

```bash
curl -fsSL emqx.sh | bash
emqx start
```

EMQX Dashboard 默认地址是 `http://localhost:18083/`。

如果没有开启客户端认证，可以先使用：

```bash
MQTT_BROKER_URL=mqtt://127.0.0.1:1883
VITE_MQTT_WS_URL=ws://127.0.0.1:8083/mqtt
MQTT_USERNAME=
MQTT_PASSWORD=
```

如果开启了认证或 TLS，请在 EMQX Dashboard 中复制对应的用户名、密码和监听器地址。

## EMQX Cloud

如果希望使用全托管 MQTT Broker，减少部署、升级和运维工作，可以使用 EMQX Cloud。它适合长期运行、团队共享和更多设备连接。

1. 登录或注册 [EMQX Cloud](https://www.emqx.com/zh/cloud)。
2. 创建 Serverless、专有版或 BYOC 部署。
3. 在部署 Overview 页面复制 MQTT 和 WebSocket 地址。
4. 在 **Access Control > Client Authentication** 中创建客户端账号。

Serverless 默认使用 TLS：

```bash
MQTT_BROKER_URL=mqtts://<deployment-host>:8883
VITE_MQTT_WS_URL=wss://<deployment-host>:8084/mqtt
MQTT_USERNAME=<client-username>
MQTT_PASSWORD=<client-password>
MQTT_TLS_ENABLED=true
MQTT_TLS_REJECT_UNAUTHORIZED=true
```

## EMQX Edge

如果设备智能体部署在现场网关、工控机或小型边缘设备上，并且需要靠近设备网络运行，可以使用 EMQX Edge。

Linux 安装：

```bash
curl -fsSL emqx.sh/edge | bash
source /etc/profile.d/emqx-edge.sh && emqx-edge start
```

EMQX Edge Dashboard 默认地址是 `http://localhost:8081/`。Docker 部署请参考官方文档。

局域网配置示例：

```bash
MQTT_BROKER_URL=mqtt://edge-gateway.local:1883
VITE_MQTT_WS_URL=ws://edge-gateway.local:8083/mqtt
MQTT_USERNAME=
MQTT_PASSWORD=
```

## 怎么选

| 需求 | 建议 |
| --- | --- |
| 先跑通 Demo | Zero EMQX |
| 私有部署、自主管理、数据留在本地 | EMQX |
| 全托管、少运维、团队共享 | EMQX Cloud |
| 现场网关、小型边缘设备、设备侧网络 | EMQX Edge |

## 官方参考

- [EMQX Docker 安装](https://docs.emqx.com/zh/emqx/latest/deploy/install-docker.html)
- [EMQX 安装](https://docs.emqx.com/zh/emqx/latest/deploy/install.html)
- [EMQX Cloud：连接到部署](https://docs.emqx.com/zh/cloud/latest/connect_to_deployments/deploy_mqtt_broker.html)
- [EMQX Edge Linux 安装](https://docs.emqx.com/zh/emqx-edge/latest/installation/packages.html)
- [EMQX Edge Docker 部署](https://docs.emqx.com/en/emqx-edge/v1.4/installation/docker.html)