# MQTTS Skills 使用示例

## 实际对话示例

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

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

**AI 响应流程：**
1. 读取 `~/.config/opencode/skill/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 执行：**
```bash
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 生成代码）：**
```python
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 证书：**
```cpp
espClient.setCACert(root_ca);  // 确保调用了这个
```

2. **同步时间（ESP32 必须）：**
```cpp
#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. **如果内存不足，尝试：**
```cpp
// 减小 MQTT 缓冲区
client.setBufferSize(256);

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

5. **临时测试（仅用于诊断）：**
```cpp
espClient.setInsecure();  // 跳过验证
// 如果成功，说明是证书问题；如果仍失败，是其他问题
```

---

### 示例 5: 证书手动续期

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

**AI 执行（参考 skill）：**
```bash
# 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 执行：**
```bash
# 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)