feat: initial OpenCode configuration with custom commands and skills
This commit is contained in:
275
skill/mqtts-developer/USAGE_EXAMPLES.md
Normal file
275
skill/mqtts-developer/USAGE_EXAMPLES.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user