Gandi域名注册商技能

为Moltbot提供的全面Gandi域名注册商集成功能

状态：✅ 第二阶段完成 - DNS修改和快照功能已就绪

⚠️ 安全警告

此技能可对您的Gandi账户执行破坏性操作：

• DNS修改：添加、更新或删除DNS记录（可能导致网站/电子邮件服务中断）
• 邮件管理：创建、修改或删除邮件转发（可能拦截邮件）
• 域名注册：注册域名（将产生财务交易）
• 批量操作：一次性替换所有DNS记录（除非通过快照，否则无法撤销）

运行任何脚本前：

1. 请仔细审查脚本代码以了解其功能
2. 批量更改前请创建DNS快照（create-snapshot.js）
3. 尽可能使用只读个人访问令牌
4. 首先在非生产域进行测试
5. 请注意某些操作不可撤销

破坏性脚本(⚠️ 修改或删除数据):

• add-dns-record.js,delete-dns-record.js,update-dns-bulk.js
• add-email-forward.js,update-email-forward.js,delete-email-forward.js
• restore-snapshot.js(将替换当前DNS)

只读脚本(✅ 安全，不会修改数据):

• list-domains.js,list-dns.js,list-snapshots.js
• list-email-forwards.js,check-domain.js,check-ssl.js

📖完整脚本文档：请参阅SCRIPTS.md获取详细信息，包括：

• 每个脚本的功能
• 网络操作和API调用
• 安全影响
• 撤销/恢复流程
• 审计工作流建议

当前功能

阶段 1 (已完成)

• ✅ 个人访问令牌认证
• ✅ 列出您账户中的域名
• ✅ 获取域名详细信息（过期时间、状态、服务）
• ✅ 列出域名的DNS记录
• ✅ 查看域名和DNS信息
• ✅域名可用性检查(#4)
• ✅提供带变体的智能域名建议(#4)
• ✅ SSL证书状态检查器
• ✅ 错误处理和验证

第二阶段 (已完成)

• ✅添加/更新DNS记录(A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR)
• ✅删除DNS记录
• ✅批量DNS操作(一次性替换所有记录)
• ✅DNS区域快照(创建、列出、恢复)
• ✅邮件转发(创建、列出、更新、删除转发，包括全收邮件转发)
• ✅记录验证(每种记录类型的自动验证)
• ✅安全功能(批量更改前自动快照，确认提示)

即将推出 (第3阶段及以后)

• 域名注册
• 多组织支持 (#1)
• 网关控制台配置 (#3)
• 域名续期管理
• DNSSEC 配置
• 证书管理
• 电子邮箱管理 (不仅仅是转发)

设置

步骤 1：创建个人访问令牌

⚠️ 安全建议：请根据您的使用场景使用最低必要权限范围。

1. 前往Gandi 管理员 → 个人访问令牌

2. 点击"创建令牌"

3. 选择您的组织

4. 选择权限范围：

   只读权限（建议仅用于查看）：

   • ✅ 域名：读取（列出域名所需）
   • ✅ LiveDNS：读取（查看DNS记录所需）
   • ✅ 邮箱：读取（查看邮件转发所需）

   写入权限（修改操作所需 - 请谨慎使用）：

   • ⚠️ LiveDNS：写入（允许DNS修改、删除、批量操作）
   • ⚠️ 邮箱：写入（允许邮件转发的创建、更新、删除）

5. 复制令牌（您将无法再次查看！）

安全最佳实践：

• 为只读和写入操作分别创建独立的令牌
• 日常检查/监控使用只读令牌
• 仅在主动进行更改时使用写入令牌
• 定期轮换令牌（建议每90天一次）
• 立即删除未使用的令牌
• 切勿将令牌共享或提交到版本控制系统

步骤二：存储令牌

脚本按以下优先级顺序检查凭据：

1. GANDI_API_TOKEN环境变量（优先检查）
2. ~/.config/gandi/api_token文件（环境变量未设置时的备选方案）

请根据您的工作流程选择合适的方法：

方案A：环境变量（推荐用于CI/CD）

# Set environment variable (replace YOUR_PAT with actual token)
export GANDI_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"

# Add to shell profile for persistence (~/.bashrc, ~/.zshrc, etc.)
echo 'export GANDI_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"' >> ~/.bashrc

优势：

• ✅ 适用于CI/CD（自动化标准模式）
• ✅ 容器化就绪（无需挂载文件）
• ✅ 兼容密钥管理工具（如1Password、Vault等）
• ✅ 便于在多个令牌间切换

方案B：基于文件（推荐用于本地开发）

# Create config directory
mkdir -p ~/.config/gandi

# Store your token (replace YOUR_PAT with actual token)
echo "YOUR_PERSONAL_ACCESS_TOKEN" > ~/.config/gandi/api_token

# Secure the file (owner read-only)
chmod 600 ~/.config/gandi/api_token

优势：

• ✅ 令牌在多个Shell会话间持续有效
• ✅ 安全的文件权限设置（0600 = 仅所有者可读）
• ✅ 无进程列表暴露令牌风险
• ✅ 支持离线运行（无外部依赖）

步骤3：安装依赖项

必需条件：Node.js >= 18.0.0

cd gandi-skill/scripts

# Install npm dependencies
npm install

# Verify installation
npm list --depth=0

预期安装包：

• axios（用于Gandi API的HTTP客户端）
• package.json中列出的其他依赖项

故障排除：

• 若node或npm未找到：请从nodejs.org
• 安装Node.js若遇权限错误：请勿使用sudo
• - 修复npm权限或使用nvm若遇包错误：请删除node_modules/与package-lock.json后执行再来一次

步骤4：测试身份验证

cd gandi-skill/scripts
node test-auth.js

预期输出：

✅ Authentication successful!

Your organizations:
  1. Personal Account (uuid-here)
     Type: individual

🎉 You're ready to use the Gandi skill!

步骤5：设置联系信息（可选，用于域名注册）

如果您计划注册域名，可一次性保存联系信息以便重复使用：

cd gandi-skill/scripts
node setup-contact.js

脚本将提示输入：

• 姓名（名和姓）
• 电子邮件地址
• 电话号码（国际格式：+1.5551234567）
• 街道地址
• 城市
• 州/省（美国：2字母代码，如OH，自动格式化为US-OH）
• 邮政编码
• 国家（2字母代码：US、FR等）
• 类型（个人或公司）
• 隐私偏好：注册后保留或自动清除联系人信息

联系信息将保存至：

• ~/.config/gandi/contact.json
• 权限：600（仅所有者可读写）
• 技能目录之外（从未提交到git）

隐私选项：

1. 保留（默认）：保存联系人信息以供未来注册使用

   • 最适合频繁注册域名的用户
   • 设置一次，永久使用
   • 随时使用以下脚本手动删除delete-contact.js

2. 清除：每次注册后自动删除联系人信息

   • 最适合注重隐私的用户
   • 联系人信息仅存在于注册期间
   • 下次注册需重新输入

管理已保存的联系人：

# View current contact
node view-contact.js

# Update contact info or privacy preference
node setup-contact.js

# Delete saved contact manually
node delete-contact.js

# Delete without confirmation
node delete-contact.js --force

一次性清除覆盖：

# Register and delete contact (even if preference is "retain")
node register-domain.js example.com --purge-contact

使用示例

列出您的域名

node list-domains.js

输出显示：

• 域名
• 到期日期
• 自动续订状态
• 服务（LiveDNS、邮箱等）
• 组织所有权

列出DNS记录

node list-dns.js example.com

输出显示：

• 按类型分组的所有DNS记录
• TTL值
• 记录名称和值
• 名称服务器

从Moltbot使用

配置后，您可以使用自然语言：

“列出我的Gandi域名”

“显示example.com的DNS记录”

“example.com何时到期？”

“example.com是否启用了自动续费？”

域名可用性检查

检查单个域名

检查特定域名是否可注册：

node check-domain.js example.com

功能：

• 显示可用性状态（可用/不可用/待定/错误）
• 显示价格信息（注册、续费、转移）
• 列出支持的功能（DNSSEC、LiveDNS等）
• 显示TLD信息

智能域名建议

🔍 Checking availability for: example.com

Domain: example.com

✅ Status: AVAILABLE

💰 Pricing:
  1 year: 12.00 EUR (+ 2.40 tax)
  2 years: 24.00 EUR (+ 4.80 tax)

📋 Supported Features:
  • create
  • dnssec
  • livedns

🌐 TLD Information:
  Extension: com

通过顶级域名变体和名称修改查找可用替代方案：

名称变体模式：

# Check all configured TLDs + variations
node suggest-domains.js example

# Check specific TLDs only
node suggest-domains.js example --tlds com,net,io

# Skip name variations (only check TLDs)
node suggest-domains.js example --no-variations

# Output as JSON
node suggest-domains.js example --json

连字符化

1. ：在单词边界处添加连字符（example→ex-ample）缩写化
2. ：去除元音字母（example→exmpl）前缀添加
3. ：添加常见前缀（example→get-example、my-example）后缀添加
4. ：添加常见后缀（: Adds common suffixes (示例→示例应用,示例中心)
5. 数字: 附加数字 (示例→示例2,示例3)

示例输出:

🔍 Checking availability for: example

📊 Checking 13 TLDs and generating variations...

═══════════════════════════════════════════════════════
📋 EXACT MATCHES (Different TLDs)
═══════════════════════════════════════════════════════

✅ Available:

  example.net                    12.00 EUR
  example.io                     39.00 EUR
  example.dev                    15.00 EUR

❌ Unavailable:

  example.com                    (unavailable)
  example.org                    (unavailable)

═══════════════════════════════════════════════════════
🎨 NAME VARIATIONS
═══════════════════════════════════════════════════════

Hyphenated:

  ✅ ex-ample.com                12.00 EUR

Prefix:

  ✅ get-example.com             12.00 EUR
  ✅ my-example.com              12.00 EUR

Suffix:

  ✅ example-app.com             12.00 EUR
  ✅ example-io.com              12.00 EUR

═══════════════════════════════════════════════════════
📊 SUMMARY: 8 available domains found
═══════════════════════════════════════════════════════

配置

域名检查器的配置存储在gandi-skill/config/domain-checker-defaults.json文件中。

结构:

{
  "tlds": {
    "mode": "extend",
    "defaults": ["com", "net", "org", "info", "io", "dev", "app", "ai", "tech"],
    "custom": []
  },
  "variations": {
    "enabled": true,
    "patterns": ["hyphenated", "abbreviated", "prefix", "suffix", "numbers"],
    "prefixes": ["get", "my", "the", "try"],
    "suffixes": ["app", "hub", "io", "ly", "ai", "hq"],
    "maxNumbers": 3
  },
  "rateLimit": {
    "maxConcurrent": 3,
    "delayMs": 200,
    "maxRequestsPerMinute": 100
  },
  "limits": {
    "maxTlds": 5,
    "maxVariations": 10
  }
}

速率限制与限制:

• maxConcurrent: 最大并发API请求数 (默认: 3)
• delayMs: 请求之间的延迟，单位毫秒 (默认: 200ms)
• maxRequestsPerMinute: 每分钟请求数的硬性限制（默认值：100，Gandi 允许 1000）
• maxTlds: 在 suggest-domains.js 中要检查的最大 TLD 数量（默认值：5）
• maxVariations: 要生成的名称变体的最大数量（默认值：10）

这些限制确保了良好的 API 使用规范，并防止对 Gandi 的 API 造成过大压力。

TLD 模式：

• "extend": 使用默认值 + 自定义 TLD（合并列表）
• "replace": 仅使用自定义 TLD（忽略默认值）

网关控制台集成：

当添加网关控制台支持时（#3），配置将在以下位置可用：

skills:
  entries:
    gandi:
      config:
        domainChecker:
          tlds:
            mode: extend
            defaults: [...]
            custom: [...]
          variations:
            enabled: true
            patterns: [...]

请参阅docs/gateway-config-design.md以获取完整的配置架构信息。

DNS 管理（第二阶段）

添加或更新 DNS 记录

创建或更新单个DNS记录：

# Add an A record for root domain
node add-dns-record.js example.com @ A 192.168.1.1

# Add www subdomain pointing to root
node add-dns-record.js example.com www CNAME @

# Add MX record for email
node add-dns-record.js example.com @ MX "10 mail.example.com."

# Add TXT record for SPF
node add-dns-record.js example.com @ TXT "v=spf1 include:_spf.google.com ~all"

# Add with custom TTL (5 minutes)
node add-dns-record.js example.com api A 192.168.1.10 300

支持的记录类型：A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR

删除DNS记录

移除特定的DNS记录：

# Delete old A record
node delete-dns-record.js example.com old A

# Delete with confirmation prompt
node delete-dns-record.js example.com test CNAME

# Delete without confirmation
node delete-dns-record.js example.com old A --force

批量DNS操作

一次性替换所有DNS记录：

# From JSON file
node update-dns-bulk.js example.com new-records.json

# From stdin
cat records.json | node update-dns-bulk.js example.com

# Skip automatic snapshot
node update-dns-bulk.js example.com records.json --no-snapshot

# Skip confirmation
node update-dns-bulk.js example.com records.json --force

JSON格式：

[
  {
    "rrset_name": "@",
    "rrset_type": "A",
    "rrset_ttl": 10800,
    "rrset_values": ["192.168.1.1"]
  },
  {
    "rrset_name": "www",
    "rrset_type": "CNAME",
    "rrset_ttl": 10800,
    "rrset_values": ["@"]
  },
  {
    "rrset_name": "@",
    "rrset_type": "MX",
    "rrset_ttl": 10800,
    "rrset_values": ["10 mail.example.com.", "20 mail2.example.com."]
  }
]

DNS区域快照

在进行更改前创建安全备份：

# Create a snapshot
node create-snapshot.js example.com "Before migration"

# List all snapshots
node list-snapshots.js example.com

# Restore from a snapshot
node restore-snapshot.js example.com abc123-def456-ghi789

# Restore without confirmation
node restore-snapshot.js example.com abc123-def456-ghi789 --force

自动快照：

• 批量更新会自动创建快照（除非--no-snapshot）
• 快照以时间戳命名
• 使用快照以便轻松回滚

常见DNS配置示例

基本网站设置

# Root domain
node add-dns-record.js example.com @ A 192.168.1.1

# WWW subdomain
node add-dns-record.js example.com www CNAME @

电子邮件配置（Google Workspace）

# MX records
node add-dns-record.js example.com @ MX "1 ASPMX.L.GOOGLE.COM."
node add-dns-record.js example.com @ MX "5 ALT1.ASPMX.L.GOOGLE.COM."
node add-dns-record.js example.com @ MX "5 ALT2.ASPMX.L.GOOGLE.COM."

# SPF record
node add-dns-record.js example.com @ TXT "v=spf1 include:_spf.google.com ~all"

域名重定向设置

要将一个域名重定向到另一个：

# Point root domain to same server
node add-dns-record.js old-domain.com @ A 192.168.1.1

# Point www to same CNAME
node add-dns-record.js old-domain.com www CNAME @

然后在服务器层面配置HTTP 301重定向。

子域名设置

# API subdomain
node add-dns-record.js example.com api A 192.168.1.10

# Staging subdomain
node add-dns-record.js example.com staging A 192.168.1.20

# Wildcard subdomain
node add-dns-record.js example.com "*" A 192.168.1.100

邮件转发（第二阶段）

列出邮件转发

查看为域名配置的所有邮件转发：

node list-email-forwards.js example.com

创建邮件转发

将邮件转发到一个或多个目的地：

# Simple forward
node add-email-forward.js example.com hello you@personal.com

# Forward to multiple destinations
node add-email-forward.js example.com support team1@example.com team2@example.com

# Catch-all forward (forwards all unmatched emails)
node add-email-forward.js example.com @ catchall@example.com

更新邮件转发

更改现有转发的目的地：

# Update single destination
node update-email-forward.js example.com hello newemail@personal.com

# Update to multiple destinations
node update-email-forward.js example.com support new1@example.com new2@example.com

注意：这将用新的目的地替换所有现有目的地。

删除邮件转发

移除邮件转发：

# Delete with confirmation prompt
node delete-email-forward.js example.com old

# Delete without confirmation
node delete-email-forward.js example.com old --force

# Delete catch-all forward
node delete-email-forward.js example.com @ --force

常见邮件转发用例

基本邮件转发

# Forward contact@ to your personal email
node add-email-forward.js example.com contact you@gmail.com

# Forward sales@ to team
node add-email-forward.js example.com sales team@example.com

域名迁移邮件转发

# Forward all email from old domain to new domain
# Preserves the local part (username before @)

# First, list existing forwards on old domain
node list-email-forwards.js old-domain.com

# Then create matching forwards on new domain
node add-email-forward.js old-domain.com contact contact@new-domain.com
node add-email-forward.js old-domain.com support support@new-domain.com

# Or use catch-all to forward everything
node add-email-forward.js old-domain.com @ admin@new-domain.com

团队分发列表

# Forward to entire team
node add-email-forward.js example.com team alice@example.com bob@example.com charlie@example.com

# Update team members
node update-email-forward.js example.com team alice@example.com dave@example.com

全收件配置

# Forward all unmatched emails to one address
node add-email-forward.js example.com @ catchall@example.com

# Forward all unmatched emails to multiple addresses
node add-email-forward.js example.com @ admin1@example.com admin2@example.com

注意：全收件转发仅适用于未配置特定转发的电子邮件地址。

邮件转发管理技巧

1. 创建后进行测试：发送测试邮件以验证转发功能正常
2. 优先使用特定转发而非全能捕获：更易控制和管理
3. 多重目的地：邮件会发送至所有目的地（非轮询方式）
4. 顺序无关紧要：Gandi会优先处理最具体的匹配项
5. 检查垃圾邮件文件夹：转发的邮件可能被收件人的垃圾邮件过滤器拦截

示例：完整域名邮箱设置

# 1. Set up MX records (if not already done)
node add-dns-record.js example.com @ MX "10 spool.mail.gandi.net."
node add-dns-record.js example.com @ MX "50 fb.mail.gandi.net."

# 2. Create specific forwards
node add-email-forward.js example.com hello you@personal.com
node add-email-forward.js example.com support team@example.com
node add-email-forward.js example.com sales sales-team@example.com

# 3. Set up catch-all for everything else
node add-email-forward.js example.com @ admin@example.com

# 4. List all forwards to verify
node list-email-forwards.js example.com

辅助脚本

所有脚本位于gandi-skill/scripts/目录：

身份验证与设置

脚本	用途
test-auth.js	验证身份验证功能正常
setup-contact.js	保存域名注册的联系信息（仅需运行一次）
view-contact.js	查看已保存的联系人信息
delete-contact.js	删除已保存的联系人（可使用可选的 --force 参数）

域名与 DNS 查看

脚本	用途
list-domains.js	显示账户中的所有域名
list-dns.js <域名>	显示指定域名的 DNS 记录
check-domain.js <域名>	检查单个域名的可用性与价格
suggest-domains.js <名称>	提供包含变体的智能域名建议
check-ssl.js	检查所有域名的 SSL 证书状态

DNS 修改（第二阶段）

脚本	用途
add-dns-record.js <域名> <名称> <类型> <值> [ttl]	添加或更新一条 DNS 记录
delete-dns-record.js <域名> <记录名> <类型> [--force]	删除一条 DNS 记录
update-dns-bulk.js <域名> <records.json> [--no-snapshot] [--force]	批量更新所有 DNS 记录
list-snapshots.js <域名>	列出 DNS 区域快照
create-snapshot.js <域名> [快照名称]	创建 DNS 区域快照
restore-snapshot.js <域名> <快照ID> [--force]	从快照恢复 DNS 区域

邮件转发（第二阶段）

脚本	用途
list-email-forwards.js <域名>	列出域名的所有邮件转发
add-email-forward.js <域名> <邮箱> <目标地址> [目标地址2...]	创建邮件转发（使用 @ 表示全部捕获）
update-email-forward.js <域名> <邮箱> <目标地址> [目标地址2...]	更新邮件转发目标地址
delete-email-forward.js <域名> <邮箱> [--force]	删除邮件转发

核心库

脚本	用途
gandi-api.js	核心 API 客户端（可导入）

配置

默认配置

• 令牌文件： ~/.config/gandi/api_token（API 身份验证）
• 联系人文件： ~/.config/gandi/contact.json（域名注册信息，可选）
• API 地址： https://api.gandi.net（生产环境）

沙盒测试

要使用 Gandi 的沙盒环境：

# Create sandbox token at: https://admin.sandbox.gandi.net
echo "YOUR_SANDBOX_TOKEN" > ~/.config/gandi/api_token
echo "https://api.sandbox.gandi.net" > ~/.config/gandi/api_url

故障排除

令牌未找到

# Verify file exists
ls -la ~/.config/gandi/api_token

# Should show: -rw------- (600 permissions)

身份验证失败（401）

• 令牌不正确或已过期
• 在 Gandi 管理界面创建新令牌
• 更新存储的令牌文件

权限被拒绝 (403)

• 令牌不具备所需权限范围
• 创建具有 Domain:read 和 LiveDNS:read 权限的新令牌
• 验证组织成员身份

域名未使用 LiveDNS

如果遇到"未使用 Gandi LiveDNS"错误：

1. 登录 Gandi 管理后台
2. 进入域名管理
3. 为域名附加 LiveDNS 服务

速率限制 (429)

Gandi 允许每分钟 1000 次请求。如果超出限制：

• 等待 60 秒
• 降低 API 调用频率

API 参考

该技能提供可导入的函数：

import { 
  testAuth,
  listDomains,
  getDomain,
  listDnsRecords,
  getDnsRecord,
  checkAvailability
} from './gandi-api.js';

// Test authentication
const auth = await testAuth();

// List domains
const domains = await listDomains();

// Get domain info
const domain = await getDomain('example.com');

// List DNS records
const records = await listDnsRecords('example.com');

// Get specific DNS record
const record = await getDnsRecord('example.com', '@', 'A');

// Check availability
const available = await checkAvailability(['example.com', 'example.net']);

安全

令牌存储

✅请执行：

• 存储位置：~/.config/gandi/api_token
• 使用600权限（所有者只读）
• 定期轮换令牌
• 使用最小必要权限范围

❌禁止事项：

• 将令牌提交到代码库
• 在用户间共享令牌
• 授予令牌不必要的权限
• 在脚本中存储令牌

令牌权限范围

第一阶段（当前）：

• 域名：读取
• LiveDNS：读取

第二阶段及以后（未来）：

• 域名：读取、写入（用于注册、续期）
• LiveDNS：读取、写入（用于DNS修改）
• 证书：读取（可选，用于SSL证书）
• 邮件：读取、写入（可选，用于邮件配置）

架构

gandi-skill/
├── SKILL.md                 # This file
├── references/              # API documentation
│   ├── api-overview.md
│   ├── authentication.md
│   ├── domains.md
│   ├── livedns.md
│   └── setup.md
└── scripts/                 # Helper utilities
    ├── package.json
    ├── gandi-api.js         # Core API client
    ├── test-auth.js         # Test authentication
    ├── list-domains.js      # List domains
    └── list-dns.js          # List DNS records

开发路线图

第一阶段：读取操作（✅ 当前阶段）

• 使用个人访问令牌进行身份验证
• 列出域名
• 获取域名详情
• 列出DNS记录
• 基础错误处理

第二阶段：DNS修改

• 添加DNS记录
• 更新DNS记录
• 删除DNS记录
• 批量DNS操作

第三阶段：域名管理

• 域名注册
• 域名续期
• 自动续期配置
• 名称服务器管理

第四阶段：多组织管理(#1)

• 基于配置文件的令牌管理
• 组织选择
• 多令牌支持

第五阶段：高级功能

• DNSSEC管理
• 证书管理
• 电子邮件/邮箱配置
• 域名转移操作

参与贡献

参见贡献指南在主README文件中。

支持

• 问题反馈： GitHub Issues
• 文档： 参考指南
• Gandi 支持： help.gandi.net

许可证

MIT 许可证 - 参见LICENSE文件

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。