228 lines
6.0 KiB
Markdown
228 lines
6.0 KiB
Markdown
# OpenCode Skills - MQTTS Certificate Management
|
||
|
||
这个目录包含了完整的 MQTTS (MQTT over TLS) 证书配置和管理技能库。
|
||
|
||
## 📚 Skills 列表
|
||
|
||
### 1. setup-mqtts-acme.md
|
||
**完整的 MQTTS 自动证书配置流程**
|
||
|
||
适用场景：
|
||
- 首次为 EMQX 配置 MQTTS
|
||
- 使用 acme.sh + DNS API 自动申请证书
|
||
- 需要证书自动续期
|
||
- 支持阿里云 DNS（可扩展到其他 DNS 提供商）
|
||
|
||
包含内容：
|
||
- 10 个阶段的详细执行步骤
|
||
- 环境检查和验证
|
||
- 证书申请和安装
|
||
- EMQX 容器重配置
|
||
- 文档和备份生成
|
||
- 故障排查指南
|
||
|
||
使用方式：
|
||
```
|
||
请帮我按照 setup-mqtts-acme skill 为域名 mq.example.com 配置 MQTTS
|
||
```
|
||
|
||
### 2. mqtts-quick-reference.md
|
||
**快速参考手册**
|
||
|
||
适用场景：
|
||
- 快速查找常用命令
|
||
- 紧急故障排查
|
||
- 日常维护操作
|
||
- 快速测试连接
|
||
|
||
包含内容：
|
||
- 快速启动命令
|
||
- 常用管理命令
|
||
- 测试命令
|
||
- 故障诊断一键脚本
|
||
- 关键概念速查
|
||
|
||
使用方式：
|
||
```
|
||
查看 mqtts-quick-reference，帮我测试 MQTTS 连接
|
||
```
|
||
|
||
### 3. mqtts-client-config.md
|
||
**客户端配置完整指南**
|
||
|
||
适用场景：
|
||
- 配置各种语言的 MQTT 客户端
|
||
- 解决客户端连接问题
|
||
- 选择合适的认证方式
|
||
- 多平台开发参考
|
||
|
||
包含内容：
|
||
- Python、Node.js、Java、C#、Go、ESP32 示例代码
|
||
- 系统 CA vs fullchain.pem 对比
|
||
- 单向 TLS 认证详解
|
||
- 客户端故障排查
|
||
- 安全最佳实践
|
||
|
||
使用方式：
|
||
```
|
||
根据 mqtts-client-config，帮我写一个 Python 客户端连接代码
|
||
```
|
||
```
|
||
我的 ESP32 连接 MQTTS 失败，参考 mqtts-client-config 帮我排查
|
||
```
|
||
|
||
## 🎯 使用场景示例
|
||
|
||
### 场景 1: 首次配置 MQTTS
|
||
```
|
||
我有一台运行 EMQX 5.8.8 的服务器，域名是 mqtt.mycompany.com，
|
||
已经配置了阿里云 DNS API。请按照 setup-mqtts-acme skill 帮我配置 MQTTS。
|
||
```
|
||
|
||
### 场景 2: 验证现有配置
|
||
```
|
||
根据 mqtts-quick-reference 中的诊断命令，
|
||
帮我检查 mq.example.com 的 MQTTS 配置是否正常。
|
||
```
|
||
|
||
### 场景 3: 客户端开发
|
||
```
|
||
我需要开发一个 Python MQTT 客户端连接到 mqtts://mq.example.com:8883。
|
||
参考 mqtts-client-config 帮我写代码，使用系统 CA 验证。
|
||
```
|
||
|
||
### 场景 4: 故障排查
|
||
```
|
||
我的 ESP32 连接 MQTTS 时出现 SSL handshake failed 错误。
|
||
根据 mqtts-client-config 的故障排查部分，帮我分析可能的原因。
|
||
```
|
||
|
||
### 场景 5: 证书更新
|
||
```
|
||
我的证书即将到期，根据 mqtts-quick-reference 帮我手动强制续期。
|
||
```
|
||
|
||
## 📖 Skill 使用最佳实践
|
||
|
||
### 1. 明确指定 Skill
|
||
在提问时明确提到 skill 名称，让 AI 知道参考哪个文档：
|
||
```
|
||
✅ 好：根据 setup-mqtts-acme skill 帮我...
|
||
✅ 好：参考 mqtts-client-config 中的 Python 示例...
|
||
❌ 差：帮我配置 MQTTS（不明确，AI 可能不使用 skill）
|
||
```
|
||
|
||
### 2. 提供必要参数
|
||
根据 skill 要求提供必要信息：
|
||
```
|
||
✅ 好：域名是 mq.example.com，使用阿里云 DNS，容器名是 emqx
|
||
❌ 差：帮我配置（缺少关键信息）
|
||
```
|
||
|
||
### 3. 分阶段执行
|
||
对于复杂流程，可以分阶段执行：
|
||
```
|
||
1. 先执行环境检查阶段
|
||
2. 确认无误后执行证书申请
|
||
3. 最后执行容器配置
|
||
```
|
||
|
||
### 4. 参考故障排查
|
||
遇到问题时先参考 skill 中的故障排查部分：
|
||
```
|
||
我遇到了 DNS 解析失败的错误，
|
||
根据 setup-mqtts-acme 的故障排查部分，应该如何处理？
|
||
```
|
||
|
||
## 🔄 Skill 更新和维护
|
||
|
||
### 当前版本
|
||
- setup-mqtts-acme: v1.0 (2026-01-07)
|
||
- mqtts-quick-reference: v1.0 (2026-01-07)
|
||
- mqtts-client-config: v1.0 (2026-01-07)
|
||
|
||
### 支持的配置
|
||
- EMQX: 5.8.8 (Docker)
|
||
- acme.sh: 最新版本
|
||
- DNS Provider: 阿里云 DNS (dns_ali)
|
||
- CA: ZeroSSL, Let's Encrypt
|
||
- TLS: TLSv1.2, TLSv1.3
|
||
- 认证: 单向 TLS + 用户名密码
|
||
|
||
### 扩展建议
|
||
可以基于这些 skills 创建新的变体：
|
||
|
||
1. **setup-mqtts-nginx.md**: Nginx 反向代理场景
|
||
2. **setup-mqtts-mtls.md**: 双向 TLS 认证配置
|
||
3. **mqtts-monitoring.md**: 证书监控和告警
|
||
4. **mqtts-ha-cluster.md**: 高可用集群配置
|
||
|
||
### 反馈和改进
|
||
如果发现 skill 有任何问题或改进建议：
|
||
1. 记录具体场景和问题
|
||
2. 建议改进方案
|
||
3. 更新对应的 skill 文件
|
||
|
||
## 📝 命名规范
|
||
|
||
Skill 文件命名遵循以下规范：
|
||
- 使用小写字母和连字符
|
||
- 清晰描述功能
|
||
- 使用 .md 扩展名
|
||
- 例如：`setup-mqtts-acme.md`, `mqtts-client-config.md`
|
||
|
||
## 🎓 学习路径
|
||
|
||
### 初学者
|
||
1. 先阅读 `mqtts-quick-reference.md` 了解基本概念
|
||
2. 使用 `setup-mqtts-acme.md` 完成首次配置
|
||
3. 参考 `mqtts-client-config.md` 开发客户端
|
||
|
||
### 进阶用户
|
||
1. 深入理解 `setup-mqtts-acme.md` 的每个阶段
|
||
2. 自定义配置参数（CA、DNS 提供商等）
|
||
3. 根据实际需求修改和扩展 skill
|
||
|
||
### 专家用户
|
||
1. 创建自定义 skill 变体
|
||
2. 集成到 CI/CD 流程
|
||
3. 开发自动化脚本
|
||
|
||
## 🔗 相关资源
|
||
|
||
- EMQX 官方文档: https://www.emqx.io/docs/
|
||
- acme.sh 项目: https://github.com/acmesh-official/acme.sh
|
||
- MQTT 协议规范: https://mqtt.org/
|
||
- TLS 最佳实践: https://wiki.mozilla.org/Security/Server_Side_TLS
|
||
|
||
## 💡 提示
|
||
|
||
1. **Token 节省**: 使用 skill 可以大幅减少 token 消耗，因为 AI 直接参考结构化的知识库
|
||
2. **一致性**: Skill 确保每次执行都遵循相同的最佳实践
|
||
3. **可维护**: 集中管理知识，便于更新和改进
|
||
4. **可重用**: 一次编写，多次使用，提高效率
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. 这些 skills 基于特定版本和配置，使用前请确认环境兼容性
|
||
2. 生产环境操作前建议先在测试环境验证
|
||
3. 涉及证书和密钥的操作需要特别注意安全性
|
||
4. 自动化脚本执行前请仔细审查命令
|
||
|
||
## 🚀 快速开始
|
||
|
||
最简单的使用方式：
|
||
```
|
||
我需要为 EMQX 配置 MQTTS 自动证书，域名是 mq.example.com。
|
||
请使用 setup-mqtts-acme skill 帮我完成配置。
|
||
```
|
||
|
||
AI 将会：
|
||
1. 读取 setup-mqtts-acme.md skill
|
||
2. 检查必要参数和前置条件
|
||
3. 逐步执行配置流程
|
||
4. 验证配置结果
|
||
5. 生成文档和备份
|
||
|
||
享受自动化的便利！🎉
|