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 创建新的变体：
- setup-mqtts-nginx.md: Nginx 反向代理场景
- setup-mqtts-mtls.md: 双向 TLS 认证配置
- mqtts-monitoring.md: 证书监控和告警
- mqtts-ha-cluster.md: 高可用集群配置
反馈和改进
如果发现 skill 有任何问题或改进建议：
- 记录具体场景和问题
- 建议改进方案
- 更新对应的 skill 文件
📝 命名规范
Skill 文件命名遵循以下规范：
- 使用小写字母和连字符
- 清晰描述功能
- 使用 .md 扩展名
- 例如：
setup-mqtts-acme.md,mqtts-client-config.md
🎓 学习路径
初学者
- 先阅读
mqtts-quick-reference.md了解基本概念 - 使用
setup-mqtts-acme.md完成首次配置 - 参考
mqtts-client-config.md开发客户端
进阶用户
- 深入理解
setup-mqtts-acme.md的每个阶段 - 自定义配置参数（CA、DNS 提供商等）
- 根据实际需求修改和扩展 skill
专家用户
- 创建自定义 skill 变体
- 集成到 CI/CD 流程
- 开发自动化脚本
🔗 相关资源
- 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
💡 提示
- Token 节省: 使用 skill 可以大幅减少 token 消耗，因为 AI 直接参考结构化的知识库
- 一致性: Skill 确保每次执行都遵循相同的最佳实践
- 可维护: 集中管理知识，便于更新和改进
- 可重用: 一次编写，多次使用，提高效率
⚠️ 注意事项
- 这些 skills 基于特定版本和配置，使用前请确认环境兼容性
- 生产环境操作前建议先在测试环境验证
- 涉及证书和密钥的操作需要特别注意安全性
- 自动化脚本执行前请仔细审查命令
🚀 快速开始
最简单的使用方式：
我需要为 EMQX 配置 MQTTS 自动证书，域名是 mq.example.com。
请使用 setup-mqtts-acme skill 帮我完成配置。
AI 将会：
- 读取 setup-mqtts-acme.md skill
- 检查必要参数和前置条件
- 逐步执行配置流程
- 验证配置结果
- 生成文档和备份
享受自动化的便利！🎉