Initial commit: Tencent DNSPod DNS deployment skill
- Support for single record deployment - Batch deployment from JSON config - Service quick deployment (Web/API/CDN) - .env file support for secure credentials - Complete documentation
This commit is contained in:
OpenClaw
180
references/api-auth.md
Normal file
180
references/api-auth.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# 腾讯云API认证说明
|
||||
|
||||
## 概述
|
||||
|
||||
DNSPod API使用腾讯云统一的API v3签名算法,基于HMAC-SHA256进行请求签名认证。
|
||||
|
||||
## 获取密钥
|
||||
|
||||
### 1. 访问API密钥管理页面
|
||||
https://console.cloud.tencent.com/cam/capi
|
||||
|
||||
### 2. 创建密钥
|
||||
- 点击「新建密钥」或「访问密钥」
|
||||
- 系统生成 `SecretId` 和 `SecretKey`
|
||||
|
||||
### 3. 保存密钥
|
||||
⚠️ **重要:** SecretKey只在创建时显示一次,请妥善保存!
|
||||
|
||||
### 4. 设置环境变量
|
||||
|
||||
**Linux/Mac (Bash/Zsh):**
|
||||
```bash
|
||||
# 添加到 ~/.bashrc 或 ~/.zshrc
|
||||
export TENCENT_SECRET_ID="你的SecretId"
|
||||
export TENCENT_SECRET_KEY="你的SecretKey"
|
||||
|
||||
# 重新加载配置
|
||||
source ~/.bashrc # 或 source ~/.zshrc
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
# 添加到环境变量
|
||||
[System.Environment]::SetEnvironmentVariable('TENCENT_SECRET_ID', '你的SecretId', 'User')
|
||||
[System.Environment]::SetEnvironmentVariable('TENCENT_SECRET_KEY', '你的SecretKey', 'User')
|
||||
|
||||
# 临时设置(当前会话有效)
|
||||
$env:TENCENT_SECRET_ID="你的SecretId"
|
||||
$env:TENCENT_SECRET_KEY="你的SecretKey"
|
||||
```
|
||||
|
||||
**验证环境变量:**
|
||||
```bash
|
||||
# Linux/Mac
|
||||
echo $TENCENT_SECRET_ID
|
||||
|
||||
# Windows PowerShell
|
||||
echo $env:TENCENT_SECRET_ID
|
||||
```
|
||||
|
||||
## 签名算法详解
|
||||
|
||||
### 1. 构造规范请求串
|
||||
|
||||
**格式:**
|
||||
```
|
||||
HTTPRequestMethod + '\n' +
|
||||
CanonicalURI + '\n' +
|
||||
CanonicalQueryString + '\n' +
|
||||
CanonicalHeaders + '\n' +
|
||||
SignedHeaders + '\n' +
|
||||
HexEncode(Hash(RequestPayload))
|
||||
```
|
||||
|
||||
**示例:**
|
||||
```
|
||||
POST
|
||||
/
|
||||
content-type:application/json
|
||||
host:dnspod.tencentcloudapi.com
|
||||
|
||||
content-type;host
|
||||
356f92b5d0373084a2bc07df8267b0ab
|
||||
```
|
||||
|
||||
### 2. 构造待签名字符串
|
||||
|
||||
**格式:**
|
||||
```
|
||||
Algorithm + '\n' +
|
||||
RequestTimestamp + '\n' +
|
||||
CredentialScope + '\n' +
|
||||
HexEncode(Hash(CanonicalRequest))
|
||||
```
|
||||
|
||||
**示例:**
|
||||
```
|
||||
TC3-HMAC-SHA256
|
||||
1666666666
|
||||
2021-03-23/dnspod/tc3_request
|
||||
5c9d88e6d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d
|
||||
```
|
||||
|
||||
### 3. 计算签名
|
||||
|
||||
使用 HMAC-SHA256 算法分三次计算:
|
||||
|
||||
```python
|
||||
secret_date = HMAC_SHA256("TC3" + SecretKey, Date)
|
||||
secret_service = HMAC_SHA256(secret_date, Service)
|
||||
secret_signing = HMAC_SHA256(secret_service, "tc3_request")
|
||||
signature = HMAC_SHA256(secret_signing, StringToSign)
|
||||
```
|
||||
|
||||
### 4. 构造Authorization头
|
||||
|
||||
**格式:**
|
||||
```
|
||||
Algorithm Credential={SecretId}/{CredentialScope}, SignedHeaders={SignedHeaders}, Signature={Signature}
|
||||
```
|
||||
|
||||
**示例:**
|
||||
```
|
||||
TC3-HMAC-SHA256 Credential=AKIDxxxxxxxx/2021-03-23/dnspod/tc3_request, SignedHeaders=content-type;host, Signature=5c9d88e6d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d
|
||||
```
|
||||
|
||||
## 完整请求示例
|
||||
|
||||
### 请求头
|
||||
```http
|
||||
POST / HTTP/1.1
|
||||
Host: dnspod.tencentcloudapi.com
|
||||
Content-Type: application/json
|
||||
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxxxxxxx/2021-03-23/dnspod/tc3_request, SignedHeaders=content-type;host, Signature=xxxxxxxx
|
||||
X-TC-Action: DescribeRecordList
|
||||
X-TC-Timestamp: 1666666666
|
||||
X-TC-Version: 2021-03-23
|
||||
X-TC-Region: ap-guangzhou
|
||||
```
|
||||
|
||||
### 请求体
|
||||
```json
|
||||
{
|
||||
"Domain": "example.com"
|
||||
}
|
||||
```
|
||||
|
||||
## 请求参数说明
|
||||
|
||||
| 参数 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| X-TC-Action | 操作名称 | CreateRecord |
|
||||
| X-TC-Version | API版本 | 2021-03-23 |
|
||||
| X-TC-Timestamp | 时间戳(秒) | 1666666666 |
|
||||
| X-TC-Region | 地域 | ap-guangzhou |
|
||||
| Authorization | 签名信息 | 见上文 |
|
||||
|
||||
## 地域说明
|
||||
|
||||
DNSPod API支持的地域:
|
||||
|
||||
- **ap-guangzhou** (广州,推荐)
|
||||
- **ap-shanghai** (上海)
|
||||
- **ap-beijing** (北京)
|
||||
- **ap-chengdu** (成都)
|
||||
|
||||
建议选择就近地域以降低延迟。
|
||||
|
||||
## 安全建议
|
||||
|
||||
### 1. 密钥安全
|
||||
- ⚠️ 不要将密钥硬编码在代码中
|
||||
- ⚠️ 不要在Git仓库中提交密钥
|
||||
- ✓ 使用环境变量或配置文件
|
||||
- ✓ 定期轮换密钥
|
||||
|
||||
### 2. 权限管理
|
||||
- 为不同应用创建独立的子账号
|
||||
- 只授予必要的权限(最小权限原则)
|
||||
- 定期审计密钥使用情况
|
||||
|
||||
### 3. IP白名单
|
||||
- 在腾讯云访问管理(CAM)中设置IP白名单
|
||||
- 限制只有特定IP才能调用API
|
||||
|
||||
## 参考文档
|
||||
|
||||
- **API签名文档:** https://cloud.tencent.com/document/product/1427/56152
|
||||
- **访问管理(CAM):** https://cloud.tencent.com/document/product/598
|
||||
- **SDK示例:** https://cloud.tencent.com/document/sdk
|
||||
192
references/common-errors.md
Normal file
192
references/common-errors.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# DNSPod API常见错误处理
|
||||
|
||||
## 错误码说明
|
||||
|
||||
### 认证相关
|
||||
|
||||
#### AuthFailure
|
||||
**错误:** 签名验证失败
|
||||
|
||||
**原因:**
|
||||
- SecretId或SecretKey错误
|
||||
- 签名算法错误
|
||||
- 请求时间戳偏差过大
|
||||
|
||||
**解决方案:**
|
||||
1. 检查环境变量 `TENCENT_SECRET_ID` 和 `TENCENT_SECRET_KEY`
|
||||
2. 确认密钥未过期且状态正常
|
||||
3. 检查系统时间是否准确(误差不超过5分钟)
|
||||
|
||||
#### AuthFailure.SecretIdNotFound
|
||||
**错误:** SecretId不存在
|
||||
|
||||
**原因:**
|
||||
- SecretId输入错误
|
||||
- 密钥已被删除
|
||||
|
||||
**解决方案:**
|
||||
- 访问 https://console.cloud.tencent.com/cam/capi 重新获取
|
||||
|
||||
### 域名相关
|
||||
|
||||
#### ResourceNotFound.Domain
|
||||
**错误:** 域名不存在
|
||||
|
||||
**原因:**
|
||||
- 域名未添加到DNSPod
|
||||
- 域名名称输入错误
|
||||
|
||||
**解决方案:**
|
||||
- 检查域名拼写
|
||||
- 使用 `--create-domain` 自动创建域名
|
||||
- 手动在DNSPod控制台添加域名
|
||||
|
||||
#### ResourceNotFound.DomainOffline
|
||||
**错误:** 域名已停用
|
||||
|
||||
**原因:**
|
||||
- 域名已被禁用
|
||||
|
||||
**解决方案:**
|
||||
- 登录DNSPod控制台重新启用域名
|
||||
|
||||
### 记录相关
|
||||
|
||||
#### InvalidParameter.RecordAlreadyExists
|
||||
**错误:** 记录已存在
|
||||
|
||||
**原因:**
|
||||
- 相同的主机记录、类型、线路的记录已存在
|
||||
|
||||
**解决方案:**
|
||||
- 使用 `--force` 参数强制更新
|
||||
- 先删除现有记录再创建
|
||||
|
||||
#### InvalidParameter.RecordNotFound
|
||||
**错误:** 记录不存在
|
||||
|
||||
**原因:**
|
||||
- RecordId错误
|
||||
- 记录已被删除
|
||||
|
||||
**解决方案:**
|
||||
- 使用 `list_records.py` 查询正确的记录ID
|
||||
|
||||
#### InvalidParameter.RecordValueInvalid
|
||||
**错误:** 记录值格式错误
|
||||
|
||||
**原因:**
|
||||
- IP地址格式错误
|
||||
- CNAME目标域名格式错误
|
||||
- 记录值与类型不匹配
|
||||
|
||||
**解决方案:**
|
||||
- A记录值必须是IPv4地址(如: 1.2.3.4)
|
||||
- CNAME记录值必须是域名(如: cdn.example.com)
|
||||
- MX记录值格式: `mx.example.com` (优先级单独设置)
|
||||
|
||||
### 限频相关
|
||||
|
||||
#### RequestLimitExceeded
|
||||
**错误:** 请求频率超限
|
||||
|
||||
**原因:**
|
||||
- API调用超过频率限制(默认: 20次/秒)
|
||||
|
||||
**解决方案:**
|
||||
- 降低请求频率
|
||||
- 批量操作时增加 `--delay` 参数
|
||||
- 使用批量API代替循环调用
|
||||
|
||||
#### LimitExceeded.DomainRecord
|
||||
**错误:** 域名记录数超限
|
||||
|
||||
**原因:**
|
||||
- 该域名下的记录数超过套餐限制
|
||||
|
||||
**解决方案:**
|
||||
- 删除不需要的记录
|
||||
- 升级DNSPod套餐
|
||||
|
||||
### 参数相关
|
||||
|
||||
#### InvalidParameter
|
||||
**错误:** 参数错误
|
||||
|
||||
**原因:**
|
||||
- 必填参数缺失
|
||||
- 参数格式错误
|
||||
- 参数值超出范围
|
||||
|
||||
**解决方案:**
|
||||
- 检查命令行参数拼写
|
||||
- 确认参数值格式正确
|
||||
- 查看API文档确认参数要求
|
||||
|
||||
#### MissingParameter
|
||||
**错误:** 缺少必填参数
|
||||
|
||||
**原因:**
|
||||
- 未提供必要的参数
|
||||
|
||||
**解决方案:**
|
||||
- 使用 `--help` 查看必填参数
|
||||
- 补充完整的参数
|
||||
|
||||
### 其他常见错误
|
||||
|
||||
#### UnknownParameter
|
||||
**错误:** 未知参数
|
||||
|
||||
**原因:**
|
||||
- 传递了不支持的参数
|
||||
|
||||
**解决方案:**
|
||||
- 检查参数名称拼写
|
||||
- 确认API版本支持该参数
|
||||
|
||||
#### UnsupportedOperation
|
||||
**错误:** 不支持的操作
|
||||
|
||||
**原因:**
|
||||
- 当前套餐不支持该功能
|
||||
- 域名状态不允许该操作
|
||||
|
||||
**解决方案:**
|
||||
- 升级DNSPod套餐
|
||||
- 检查域名状态
|
||||
|
||||
## 调试技巧
|
||||
|
||||
### 1. 开启详细日志
|
||||
在脚本中添加调试输出:
|
||||
```python
|
||||
import logging
|
||||
logging.basicConfig(level=logging.DEBUG)
|
||||
```
|
||||
|
||||
### 2. 打印API响应
|
||||
查看完整的API错误信息:
|
||||
```python
|
||||
print(json.dumps(result, indent=2, ensure_ascii=False))
|
||||
```
|
||||
|
||||
### 3. 验证参数
|
||||
在调用API前打印参数:
|
||||
```python
|
||||
print(f"参数: {params}")
|
||||
```
|
||||
|
||||
### 4. 测试连通性
|
||||
检查网络连接:
|
||||
```bash
|
||||
ping dnspod.tencentcloudapi.com
|
||||
curl -I https://dnspod.tencentcloudapi.com
|
||||
```
|
||||
|
||||
## 获取帮助
|
||||
|
||||
- **API文档:** https://cloud.tencent.com/document/product/1427/56152
|
||||
- **错误码参考:** https://cloud.tencent.com/document/product/1427/56190
|
||||
- **工单系统:** https://console.cloud.tencent.com/workorder
|
||||
- **技术支持:** 95716 (DNSPod技术热线)
|
||||
Reference in New Issue
Block a user