276 lines
6.1 KiB
Markdown
276 lines
6.1 KiB
Markdown
# 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 执行：**
|
||
```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)
|