opencode/skill/mqtts-developer/USAGE_EXAMPLES.md

MQTTS Skills 使用示例

实际对话示例

示例 1: 完整配置新域名的 MQTTS

用户提问：

我需要为域名 mqtt.mycompany.com 配置 MQTTS，服务器 IP 是 10.20.30.40，
EMQX 容器名是 emqx，使用阿里云 DNS。请按照 setup-mqtts-acme skill 执行。

AI 响应流程：

1. 读取 ~/.opencode/skills/setup-mqtts-acme.md
2. 验证 DNS 解析
3. 申请证书
4. 安装证书并配置自动更新
5. 重建 EMQX 容器
6. 验证配置
7. 生成文档和备份

预期输出：

• 证书文件: /root/certs/mqtt.mycompany.com/
• 备份包: /root/certs/mqtt.mycompany.com-complete-*.tar.gz
• MQTTS 端口 8883 工作正常
• 自动续期已配置

---

示例 2: 快速诊断 MQTTS 问题

用户提问：

根据 mqtts-quick-reference 的诊断脚本，
帮我检查 mq.example.com 的 MQTTS 配置状态。

AI 执行：

DOMAIN="mq.example.com"

echo "=== DNS ==="
dig $DOMAIN +short

echo "=== Certificate ==="
openssl x509 -in /root/certs/$DOMAIN/cert.pem -noout -dates -subject

echo "=== EMQX Container ==="
docker ps | grep emqx

echo "=== Listeners ==="
docker exec emqx emqx ctl listeners | grep -A 5 ssl

echo "=== SSL Test ==="
timeout 5 openssl s_client -connect $DOMAIN:8883 -servername $DOMAIN

echo "=== Auto-Renewal ==="
~/.acme.sh/acme.sh --list | grep $DOMAIN

预期输出：

• DNS 解析状态
• 证书有效期
• 容器运行状态
• SSL 监听器状态
• 自动续期配置

---

示例 3: 生成 Python 客户端代码

用户提问：

根据 mqtts-client-config，帮我生成一个 Python MQTT 客户端，
连接到 mqtts://mq.example.com:8883，
使用系统 CA 验证，订阅 sensor/# 主题。

AI 响应（参考 skill 生成代码）：

import paho.mqtt.client as mqtt
import ssl

def on_connect(client, userdata, flags, rc):
    if rc == 0:
        print("Connected successfully")
        client.subscribe("sensor/#")
    else:
        print(f"Connection failed with code {rc}")

def on_message(client, userdata, msg):
    print(f"{msg.topic}: {msg.payload.decode()}")

client = mqtt.Client()
client.username_pw_set("username", "password")

# Use system CA - no files needed
client.tls_set(
    cert_reqs=ssl.CERT_REQUIRED,
    tls_version=ssl.PROTOCOL_TLSv1_2
)

client.on_connect = on_connect
client.on_message = on_message

client.connect("mq.example.com", 8883, 60)
client.loop_forever()

---

示例 4: ESP32 连接故障排查

用户提问：

我的 ESP32 连接 mqtts://mq.example.com:8883 时报错：
"SSL handshake failed"

参考 mqtts-client-config 的故障排查部分，帮我分析原因并提供解决方案。

AI 响应（基于 skill 的故障排查部分）：

可能原因：

1. 未设置 CA 证书
2. ESP32 时间不正确
3. fullchain.pem 内容不完整
4. 证书过期
5. 内存不足

解决方案：

1. 检查是否设置了 CA 证书：

espClient.setCACert(root_ca);  // 确保调用了这个

2. 同步时间（ESP32 必须）：

#include <time.h>

void setup() {
  configTime(0, 0, "pool.ntp.org");
  
  // Wait for time sync
  time_t now = time(nullptr);
  while (now < 8 * 3600 * 2) {
    delay(500);
    now = time(nullptr);
  }
  Serial.println("Time synchronized");
}

3. 验证 fullchain.pem 内容完整： 确保包含完整的证书链（服务器证书 + 中间证书 + 根证书）

4. 如果内存不足，尝试：

// 减小 MQTT 缓冲区
client.setBufferSize(256);

// 或仅使用服务器证书（不推荐）
espClient.setCACert(server_cert_only);

5. 临时测试（仅用于诊断）：

espClient.setInsecure();  // 跳过验证
// 如果成功，说明是证书问题；如果仍失败，是其他问题

---

示例 5: 证书手动续期

用户提问：

我的证书还有 10 天到期，想手动提前续期。
根据 mqtts-quick-reference 帮我执行强制续期。

AI 执行（参考 skill）：

# 1. 查看当前证书信息
~/.acme.sh/acme.sh --info -d mq.example.com

# 2. 强制续期
~/.acme.sh/acme.sh --renew -d mq.example.com --force

# 3. 验证新证书
openssl x509 -in /root/certs/mq.example.com/cert.pem -noout -dates

# 4. 检查容器是否重启
docker ps | grep emqx

# 5. 测试 MQTTS 连接
openssl s_client -connect mq.example.com:8883 -servername mq.example.com

输出解释：

• 新证书已生成
• EMQX 容器已自动重启（通过 reloadcmd）
• MQTTS 连接正常
• 下次自动续期时间已更新

---

示例 6: 多语言客户端对比

用户提问：

根据 mqtts-client-config，对比 Python、Node.js 和 Java 
连接 MQTTS 的代码差异，我需要选择一个用于生产环境。

AI 响应（基于 skill 的多语言示例）：

特性	Python	Node.js	Java
易用性	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
性能	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
系统 CA	简单	简单	中等
异步支持	中等	原生	复杂
部署	需要 Python	需要 Node.js	打包成 JAR

推荐：

• 快速原型: Python（最简单）
• 高并发: Node.js（原生异步）
• 企业级: Java（稳定可靠）

代码示例见 skill 文档...

---

示例 7: 创建客户端分发包

用户提问：

我需要给客户端开发者提供连接包，包含：
1. fullchain.pem
2. 连接文档
3. 各语言示例代码

参考 mqtts-client-config 帮我生成。

AI 执行：

# 1. 创建分发目录
mkdir -p /root/mqtts-client-package
cd /root/mqtts-client-package

# 2. 复制证书
cp /root/certs/mq.example.com/fullchain.pem ./

# 3. 生成连接信息
cat > CONNECTION_INFO.txt << EOF
MQTTS Connection Information

Server: mq.example.com
Port: 8883
Protocol: MQTTS (MQTT over TLS)
TLS Version: TLSv1.2+

Authentication:
- Username: [Your Username]
- Password: [Your Password]

Certificate Verification:
- Option 1: Use system CA (recommended for PC/Mobile)
- Option 2: Use provided fullchain.pem (recommended for embedded)

Certificate Fingerprint (SHA256):
$(openssl x509 -in fullchain.pem -noout -fingerprint -sha256)