@aigne/afs-dns

AFS DNS Provider - 统一的 DNS 管理接口，支持多种 DNS 服务商。

支持的 Provider

| Provider | 配置值 | 说明 |
|----------|--------|------|
| AWS Route53 | route53 | 默认 Provider，完整支持 |
| Google Cloud DNS | clouddns | Google Cloud 托管 DNS |

安装

``bash
pnpm add @aigne/afs-dns

Route53 需要 AWS SDK（已包含）

Cloud DNS 需要额外安装：

pnpm add @google-cloud/dns
`

配置示例

$3

`toml
[[mounts]]
path = "/dns/aws"
uri = "dns://example.com"
access_mode = "readwrite"

[mounts.options]
provider = "route53"
region = "us-east-1"

[mounts.options.credentials]
accessKeyId = "${AWS_ACCESS_KEY_ID}"
secretAccessKey = "${AWS_SECRET_ACCESS_KEY}"

[mounts.options.permissions]
preset = "standard" # safe | standard | full
`

$3

`toml
[[mounts]]
path = "/dns/gcp"
uri = "dns://example.com"
access_mode = "readwrite"

[mounts.options]
provider = "clouddns"
projectId = "my-gcp-project"
keyFilename = "/path/to/service-account.json"

[mounts.options.permissions]
preset = "standard"
`

$3

`toml
[[mounts]]
path = "/dns/local"
uri = "dns://test.local"
access_mode = "readwrite"

[mounts.options]
provider = "route53"
endpoint = "http://localhost:4566"
region = "us-east-1"

[mounts.options.credentials]
accessKeyId = "test"
secretAccessKey = "test"
`

使用方式

$3

`bash


列出所有记录

afs ls /dns/aws

读取记录

afs read /dns/aws/www

读取 Zone 元数据

afs read /dns/aws/_zone

创建/更新记录

afs write /dns/aws/api --content '{"type":"A","ttl":300,"values":["1.2.3.4"]}'

删除记录

afs rm /dns/aws/old-record

删除特定类型

afs rm /dns/aws/www?type=AAAA
`

$3

`typescript
import { DNSProvider, Route53Adapter, CloudDNSAdapter } from "@aigne/afs-dns";

// Route53
const route53 = new Route53Adapter({
region: "us-east-1",
credentials: {
accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
},
});

// Cloud DNS
const cloudDNS = new CloudDNSAdapter({
projectId: "my-project",
keyFilename: "/path/to/service-account.json",
});

// 创建 Provider
const provider = new DNSProvider({
zone: "example.com",
adapter: route53, // 或 cloudDNS
accessMode: "readwrite",
permissions: { preset: "standard" },
});

// 列出记录
const records = await provider.list("/");

// 读取记录
const www = await provider.read("/www");

// 写入记录
await provider.write("/api", {
content: { type: "A", ttl: 300, values: ["1.2.3.4"] },
});
`

目录结构

`
/dns/example.com/
├── @ # 根域名记录 (apex)
├── www # www.example.com
├── api # api.example.com
├── *.staging # 通配符记录
├── _dmarc # DMARC 记录
└── _zone # Zone 元数据（只读）
`

支持的记录类型

| 类型 | 值格式 | 示例 |
|------|--------|------|
| A | string[] | ["1.2.3.4", "5.6.7.8"] |
| AAAA | string[] | ["2001:db8::1"] |
| CNAME | string | "alias.example.com" |
| MX | {priority, value}[] | [{"priority": 10, "value": "mail.example.com"}] |
| TXT | string[] | ["v=spf1 include:..."] |
| NS | string[] | ["ns1.example.com"] |
| SRV | {priority, weight, port, target}[] | [{"priority": 10, "weight": 5, "port": 443, "target": "..."}] |
| CAA | {flags, tag, value}[] | [{"flags": 0, "tag": "issue", "value": "letsencrypt.org"}] |
| PTR | string | "host.example.com" |
| SOA | (只读) | 区域授权记录 |

权限模型

危险操作默认禁止，需要显式配置开启：

| 操作 | 默认 | 说明 |
|------|------|------|
| read | 允许 | 读取任何记录 |
| write | 按 access_mode | 普通记录写入 |
| delete | 按 access_mode | 普通记录删除 |
| modify_root | 禁止 | 修改根域名 (@) |
| modify_ns | 禁止 | 修改 NS 记录 |
| modify_wildcard | 禁止 | 修改通配符 (*) |
| delete_zone | 禁止 | 删除整个 Zone |

$3

`toml
[mounts.options.permissions]
preset = "standard" # 选择预设
`

| 预设 | write | delete | modify_root | modify_ns |
|------|-------|--------|-------------|-----------|
| safe | ✓ | ✗ | ✗ | ✗ |
| standard | ✓ | ✓ | ✗ | ✗ |
| full | ✓ | ✓ | ✓ | ✓ |

$3

`toml
[mounts.options.permissions]
preset = "standard"

[mounts.options.permissions.dangerous]
modify_root = true # 允许修改根域名
modify_wildcard = true # 允许修改通配符
`

E2E 测试

使用 LocalStack 进行本地测试：

`bash


启动 LocalStack

docker run -d --name localstack-dns \
-p 4566:4566 \
-e SERVICES=route53 \
localstack/localstack

运行测试

cd providers/dns
pnpm test:e2e:full
`

依赖

- @aws-sdk/client-route-53 - AWS Route53 SDK（内置）
- @google-cloud/dns` - Google Cloud DNS SDK（可选，peer dependency）

注意事项

- Route53 API 有请求限制（5 requests/second），内置 rate limiting
- DNS 变更是最终一致的，写入后可能需要等待传播
- Zone 创建/删除不在 AFS 范围内（通过云控制台或 IaC 工具管理）