一、前期准备

1.1 账号与权限准备

• 注册并登录天翼云账号，完成实名认证（个人/企业均可，具体要求参考天翼云实名认证规范），未完成实名认证将无法开通云资源服务。
• 确保账号拥有「分布式消息服务MQTT」的操作权限，若为子账号，需主账号在天翼云访问控制（IAM）中分配相关权限（如MQTT实例创建、管理、认证授权等），避免因权限不足导致操作失败。

1.2 基础环境准备

• 网络环境：确认本地设备（或服务器）可正常访问天翼云服务，建议提前测试天翼云MQTT服务所在地域的网络连通性，避免网络防火墙拦截。
• 客户端工具：提前准备MQTT客户端，推荐使用开源跨平台的MQTTX（支持图形化界面，操作便捷，适配MQTT 5.0协议），也可选择Mosquitto（命令行工具，适合服务器环境）、MQTT Explorer等工具，根据自身开发场景选择即可。
• 基础资源：提前规划虚拟私有云（VPC）、子网、安全组，若暂无相关资源，可在开通MQTT实例时同步创建，确保实例网络可正常接入。

二、MQTT实例开通（核心步骤）

2.1 进入实例开通页面

1. 登录天翼云控制台，在顶部导航栏搜索「分布式消息服务MQTT」，进入产品详情页；
2. 点击页面「立即开通」按钮，或进入消息管理控制台，点击「创建实例」，进入MQTT实例订购页面。

2.2 实例规格配置（最佳配置建议）

1. 实例名称：实例名称不可重复；实例名称长度4~40个字符，大小写字母开头，只能包含大小写字母、数字及分隔符(-)，大小写字母或数字结尾。
2. 计费模式：根据业务需求选择，测试场景或短期使用推荐「按需计费」（按实际使用量收费，成本可控）；长期稳定使用推荐「包年包月」，可享受优惠，且支持自动续期功能，避免实例到期中断服务。
3. 部署方式：目前仅支持单可用区和3可用区部署，测试场景选择「单可用区」即可（成本较低）；生产环境建议选择「多可用区」（3个AZ），系统自动将Broker节点平均分配至各可用区，提升服务可用性和容灾能力。
4. 代理数：可选择3/5/7/9个，代理数越多，集群稳定性和并发处理能力越强，测试场景选择3个代理即可满足需求，生产环境根据并发量调整（如高并发场景选择5个及以上），节点数需与实例规格匹配。
5. 网络配置：选择已有的VPC、子网和安全组，若无则点击「创建」同步创建，确保VPC和子网的网段不冲突，安全组后续需配置端口放行规则，此处可先选择默认安全组，后续再优化配置。

2.3 实例开通与状态查看

1. 配置完成后，点击「下一步」，进入费用确认页面，核对实例信息和费用无误后，提交开通请求；
2. 返回实例列表页面，查看实例状态，实例创建需3~15分钟，期间状态为「创建中」，请勿操作实例；
3. 当实例状态变为「运行中」，说明实例开通成功，可进入实例管理页面进行后续配置。

三、实例核心配置（必做步骤）

3.1 创建认证用户（客户端连接必备）

1. 进入MQTT实例列表，找到已开通的实例，点击「管理」按钮，进入实例管理菜单；
2. 在左侧导航栏找到「认证授权」，点击「新增」按钮，在弹出的对话框中，输入认证用户名、用户密码、确认密码（密码建议复杂，包含大小写字母、数字和特殊符号，提升安全性）；
3. 点击「确认」，完成用户创建，创建后可在认证授权列表中查看用户状态（默认启用），若需禁用，可点击「禁用」按钮。

3.2 主题授权（收发消息必备）

1. 在认证授权列表中，找到已创建的用户，点击操作列的「授权」按钮；
2. 在弹出的授权对话框中，填写主题名称（建议命名规范，如test/mqtt/ctyun，支持通配符#，#代表所有主题，测试场景可直接填写#，方便快速测试）；
3. 选择权限类型：根据需求选择pub（仅发布）、sub（仅订阅）、pubsub（既可以发布也可以订阅），测试场景选择「pubsub」，便于后续测试消息收发；
4. 点击「确认」，完成主题授权，授权后用户即可操作对应主题的消息收发。

3.3 绑定公网IP（如需公网访问）

1. 进入实例管理页面，在实例详情中查看「公网IP」，点击「绑定」按钮；
2. 选择已购买的弹性公网IP，若暂无，点击「购买弹性IP」，按照提示完成购买（带宽建议按业务需求的120%购买，应对突发流量，如报文大小1KB、TPS 2W/s，建议带宽200Mb/s）；
3. 绑定完成后，实例详情中会显示绑定的公网IP，后续客户端连接时使用该IP作为服务器地址；若仅内网访问（如同一VPC内的ECS），可无需绑定公网IP，使用内网地址连接即可。

3.4 安全组配置（放行MQTT端口）

1. 进入实例管理页面，找到实例绑定的安全组，点击安全组名称，进入安全组管理页面；
2. 点击「添加入方向规则」，配置以下规则（测试场景可放宽限制，生产环境需严格控制访问来源）：
   1. 协议类型：选择「TCP」（MQTT协议默认基于TCP传输）；
   2. 端口范围：填写MQTT默认端口（1883，非加密端口；若使用SSL加密，需放行8085端口）；
   3. 源地址：测试场景选择「0.0.0.0/0」（允许所有IP访问），生产环境填写具体的客户端IP地址段，提升安全性；
   4. 描述：填写备注（如MQTT端口放行），便于后续管理。
3. 点击「确认」，完成安全组规则配置，确保规则已生效（生效时间约1~2分钟），同时确认实例的开放端口在安全组中已允许访问。

四、客户端连接测试（验证连通性）

4.1 MQTTX客户端测试（图形化界面）

步骤1：下载并安装MQTTX

步骤2：新建MQTT连接

1. 点击MQTTX客户端左上角「新建连接」，填写连接配置信息，核心配置如下（其他配置保持默认）：
   1. 连接名称：自定义（如ctyun-mqtt-test），便于区分多个连接；
   2. 客户端ID：保留默认值，或点击刷新按钮自动生成（客户端唯一标识，不可重复）；
   3. 服务器地址：选择协议（非加密选择mqtt://，加密选择mqtts://），主机填写实例的公网IP（或内网IP，内网访问时）；
   4. 端口：填写1883（非加密）或8085（加密），与安全组放行的端口一致；
   5. 用户名/密码：填写3.1中创建的认证用户名和密码；
   6. SSL/TLS：若未使用加密连接，关闭该开关；若使用，启用并配置对应证书（天翼云MQTT实例可在控制台下载证书）。
2. 配置完成后，点击右上角「连接」按钮，若连接成功，客户端左侧连接列表中会显示「已连接」（绿色状态），说明客户端与MQTT实例连通成功；若连接失败，查看下方错误提示，针对性排查（常见错误：IP错误、端口未放行、用户名密码错误）。

步骤3：消息收发测试（验证功能正常）

1. 创建消息发布客户端：在已连接的客户端中，输入主题（如test/mqtt/ctyun，与3.2中授权的主题一致），在消息输入框中填写测试消息（如“Hello, Ctyun MQTT!”），点击「发送」按钮，消息发送成功后，会在客户端聊天界面显示发送的消息；
2. 创建消息接收客户端：点击「+」->「新建连接」，创建另一个连接（名称如ctyun-mqtt-sub），连接配置与发布客户端一致（服务器地址、端口、用户名密码相同）；
3. 订阅主题：在接收客户端中，点击「+ 添加订阅」，输入与发布客户端相同的主题（test/mqtt/ctyun），QoS保持默认（0级，最多一次传递，适合测试场景），点击「确定」；
4. 再次使用发布客户端发送消息，此时接收客户端会立即收到该消息，显示在聊天界面中，说明消息收发功能正常，MQTT实例运行正常。

4.2 MQTTX CLI命令行测试（服务器/批量测试）

1. 安装MQTTX CLI：以macOS为例，使用Homebrew安装，命令如下（其他操作系统参考MQTTX CLI官方文档）： # Homebrew安装 brew install emqx/mqttx/mqttx-cli
2. 连接MQTT实例并订阅主题：打开命令行窗口，执行以下命令（替换占位符为实际信息）： mqttx sub -t 'test/mqtt/ctyun' -q 1 -h '公网IP' -p 1883 -u '用户名' -P '密码' -v参数说明：-t（订阅主题）、-q（QoS等级）、-h（服务器地址）、-p（端口）、-u（用户名）、-P（密码）、-v（显示消息主题），执行成功后，命令行将阻塞等待接收消息；
3. 发布消息：打开新的命令行窗口，执行以下命令，发布消息到指定主题： mqttx pub -t 'test/mqtt/ctyun' -q 1 -h '公网IP' -p 1883 -u '用户名' -P '密码' -m 'Hello, Ctyun MQTT from CLI'
4. 验证结果：发布消息后，订阅消息的命令行窗口会显示收到的消息（包含主题和 payload），说明连接和消息收发正常。

五、常见问题排查（避坑指南）

5.1 客户端连接失败（最常见）

• 问题现象：MQTTX客户端连接时提示“连接超时”“连接被拒绝”；
• 排查方向：
  • 网络问题：测试本地设备与MQTT实例公网IP的连通性（使用ping命令），若ping不通，检查网络防火墙是否拦截，或实例公网IP是否绑定成功；
  • 安全组问题：确认安全组已放行1883/8085端口，源地址是否包含客户端IP（测试场景建议0.0.0.0/0）；
  • 配置问题：检查服务器地址、端口是否正确，用户名密码是否与创建的认证用户一致，客户端ID是否重复；
  • 实例状态：确认MQTT实例状态为「运行中」，若处于创建中或异常状态，等待实例正常后再尝试连接。

5.2 消息收发失败

• 问题现象：客户端连接成功，但无法发布/接收消息；
• 排查方向：
  • 主题授权问题：确认用户已获得对应主题的pub/sub权限，主题名称是否与授权主题一致（区分大小写）；
  • QoS等级问题：若QoS等级设置为1或2，确认实例配置支持该等级，测试场景建议使用QoS 0，降低复杂度；
  • 客户端配置：检查发布/订阅的主题是否一致，避免主题拼写错误，或使用通配符时格式错误。

六、最佳实践总结与建议

6.1 配置建议（按场景优化）

• 测试场景：选择按需计费、单可用区、3个节点，绑定临时公网IP，安全组放宽限制，快速完成测试，降低成本；
• 生产场景：选择包年包月、多可用区部署、5个及以上节点、计算增强型规格，绑定固定公网IP，安全组严格限制访问来源，启用SSL加密连接，提升服务稳定性和安全性；
• 主题规划：生产环境建议按业务模块划分主题（如device/iot/device1、device/iot/device2），避免使用通配符#授权，降低安全风险，便于消息管理和排查。

6.2 运维建议

• 定期查看实例状态和监控数据（天翼云MQTT控制台提供连接数、消息吞吐量等监控指标），及时发现实例异常；
• 实例到期前，及时续费（包年包月）或调整按需计费配置，避免实例中断，影响业务运行；
• 若业务规模扩大，可随时调整实例规格、节点数、磁盘空间，天翼云支持弹性扩容，无需中断服务。

6.3 拓展建议