DNSPod-Skill/INSTALL.md

# DNSPod Skill 安装指南

## 概述

本Skill已针对**域名快速部署**场景优化,提供以下核心功能:

✅ **单条记录快速部署** - 秒级添加/更新DNS记录
✅ **批量部署** - 从JSON配置文件一键部署多条记录
✅ **服务快速部署** - 一键配置Web/API/CDN服务
✅ **自动化友好** - 支持DevOps CI/CD集成

## 核心脚本

### 1. `deploy_record.py` - 单条记录部署
```bash
# 添加A记录
python scripts/deploy_record.py \
  --domain example.com \
  --subdomain www \
  --type A \
  --value 1.2.3.4

# 强制更新
python scripts/deploy_record.py \
  --domain example.com \
  --subdomain www \
  --type A \
  --value 1.2.3.5 \
  --force
```

### 2. `batch_deploy.py` - 批量部署
```bash
# 从配置文件批量部署
python scripts/batch_deploy.py \
  --domain example.com \
  --config examples/dns-config.json
```

### 3. `deploy_service.py` - 服务快速部署
```bash
# 部署Web服务(@ + www)
python scripts/deploy_service.py \
  --domain example.com \
  --service web \
  --ip 1.2.3.4

# 部署API服务
python scripts/deploy_service.py \
  --domain example.com \
  --service api \
  --ip 1.2.3.5
```

### 4. `list_records.py` - 查询记录
```bash
python scripts/list_records.py --domain example.com
```

### 5. `delete_record.py` - 删除记录
```bash
python scripts/delete_record.py \
  --domain example.com \
  --subdomain www \
  --type A
```

## 安装步骤

### 步骤1: 获取腾讯云API密钥

1. 访问: https://console.cloud.tencent.com/cam/capi
2. 创建或查看密钥(包含 `SecretId` 和 `SecretKey`)
3. ⚠️ **重要:** SecretKey只在创建时显示,请立即保存!

### 步骤2: 配置API密钥

有两种方式配置API密钥:

#### 方式1: 使用 .env 文件(推荐,更安全)

```bash
# 1. 复制示例配置
cp .env.example .env

# 2. 编辑 .env 文件,填入你的密钥
# TENCENT_SECRET_ID=你的SecretId
# TENCENT_SECRET_KEY=你的SecretKey

# 3. 确保 .env 文件不会被提交到Git(已添加到 .gitignore)
```

#### 方式2: 设置环境变量

**Linux/Mac (添加到 ~/.bashrc 或 ~/.zshrc):**
```bash
export TENCENT_SECRET_ID="你的SecretId"
export TENCENT_SECRET_KEY="你的SecretKey"
source ~/.bashrc  # 重新加载
```

**Windows PowerShell:**
```powershell
[System.Environment]::SetEnvironmentVariable('TENCENT_SECRET_ID', '你的SecretId', 'User')
[System.Environment]::SetEnvironmentVariable('TENCENT_SECRET_KEY', '你的SecretKey', 'User')
```

**验证配置:**
```bash
# 方式1: 查看 .env 文件
cat .env

# 方式2: 查看环境变量
# Linux/Mac
echo $TENCENT_SECRET_ID

# Windows PowerShell
echo $env:TENCENT_SECRET_ID
```

### 步骤3: 安装Python依赖

```bash
cd tencent-dnspod
pip install -r requirements.txt
```

依赖项:
- `requests>=2.28.0` (HTTP请求库)

### 步骤4: 测试连接

```bash
python scripts/list_records.py --domain example.com
```

如果成功,将显示域名下的DNS记录列表(可能为空)。

## 典型使用场景

### 场景1: 新服务快速上线

**需求:** 将新Web服务部署到 1.2.3.4

```bash
# 一键部署主域名 + www
python scripts/deploy_service.py \
  --domain example.com \
  --service web \
  --ip 1.2.3.4
```

**结果:**
- ✅ example.com → 1.2.3.4
- ✅ www.example.com → 1.2.3.4

### 场景2: 多环境部署

**配置文件:** `dns-config.json`
```json
{
  "records": [
    {"subdomain": "www", "type": "A", "value": "1.2.3.4", "line": "默认", "remark": "生产"},
    {"subdomain": "dev", "type": "A", "value": "1.2.3.5", "line": "默认", "remark": "开发"},
    {"subdomain": "test", "type": "A", "value": "1.2.3.6", "line": "默认", "remark": "测试"}
  ]
}
```

**批量部署:**
```bash
python scripts/batch_deploy.py \
  --domain example.com \
  --config dns-config.json
```

### 场景3: CDN加速配置

```bash
# 添加CNAME记录指向CDN
python scripts/deploy_record.py \
  --domain example.com \
  --subdomain cdn \
  --type CNAME \
  --value cdn.example.com.cdn.dnsv1.com
```

### 场景4: 智能DNS(电信/联通线路)

```bash
# 电信用户访问1.2.3.4
python scripts/deploy_record.py \
  --domain example.com \
  --subdomain www \
  --type A \
  --value 1.2.3.4 \
  --line "电信"

# 联通用户访问5.6.7.8
python scripts/deploy_record.py \
  --domain example.com \
  --subdomain www \
  --type A \
  --value 5.6.7.8 \
  --line "联通"
```

### 场景5: CI/CD集成

**示例: Jenkins/GitLab CI**
```bash
# 部署时自动更新DNS
pip install -r tencent-dnspod/requirements.txt

# 部署新版本
docker push registry.example.com/myapp:v1.2.3

# 更新DNS
python tencent-dnspod/scripts/deploy_record.py \
  --domain example.com \
  --subdomain app \
  --type A \
  --value $(kubectl get svc myapp -o jsonpath='{.status.loadBalancer.ingress[0].ip}') \
  --force
```

## 高级功能

### 泛域名解析

```bash
# 部署Web服务时添加泛域名
python scripts/deploy_service.py \
  --domain example.com \
  --service web \
  --ip 1.2.3.4 \
  --wildcard
```

**结果:**
- ✅ example.com → 1.2.3.4
- ✅ www.example.com → 1.2.3.4
- ✅ *.example.com → 1.2.3.4

### TTL设置

```bash
# 测试环境使用较短TTL(快速生效)
python scripts/deploy_record.py \
  --domain example.com \
  --subdomain test \
  --type A \
  --value 1.2.3.10 \
  --ttl 60
```

### 记录备注

```bash
# 添加备注方便管理
python scripts/deploy_record.py \
  --domain example.com \
  --subdomain api \
  --type A \
  --value 1.2.3.5 \
  --remark "后端API服务"
```

## 常见问题

### Q1: 认证失败怎么办?

**错误:** `AuthFailure`

**解决:**
1. 检查环境变量是否正确设置
2. 确认SecretId和SecretKey匹配
3. 检查系统时间是否准确

### Q2: 域名不存在?

**错误:** `ResourceNotFound.Domain`

**解决:** 使用 `--create-domain` 参数自动创建:
```bash
python scripts/deploy_record.py \
  --domain example.com \
  --subdomain www \
  --type A \
  --value 1.2.3.4 \
  --create-domain
```

### Q3: 记录已存在?

**错误:** `RecordAlreadyExists`

**解决:** 使用 `--force` 参数强制更新:
```bash
python scripts/deploy_record.py \
  --domain example.com \
  --subdomain www \
  --type A \
  --value 1.2.3.5 \
  --force
```

### Q4: API频率限制?

**错误:** `RequestLimitExceeded`

**解决:** 批量部署时增加延迟:
```bash
python scripts/batch_deploy.py \
  --domain example.com \
  --config dns-config.json \
  --delay 1.0  # 改为1秒延迟
```

## 文档索引

- **API认证:** [references/api-auth.md](references/api-auth.md)
- **错误处理:** [references/common-errors.md](references/common-errors.md)
- **完整文档:** [SKILL.md](SKILL.md)

## 技术支持

- **DNSPod文档:** https://cloud.tencent.com/document/product/1427/56152
- **API参考:** https://cloud.tencent.com/document/api/1427/56194
- **控制台:** https://console.dnspod.cn

## 更新日志

### v1.0.0 (2026-03-01)
- ✅ 单条记录部署
- ✅ 批量部署
- ✅ 服务快速部署
- ✅ 记录查询和删除
- ✅ 完整错误处理