开发者 → DNS 即代码

DNS 即代码

将您的区域保存在代码旁的一个 YAML 或 JSON 文件中。在拉取请求中审查 DNS 更改，在更改生效前准确了解将发生的变化，并一步完成应用。

从您的区域开始

nameocean

$ nameocean dns export example.com > dns.yaml
$ $EDITOR dns.yaml
$ nameocean dns plan -f dns.yaml
+  CNAME  blog  example.netlify.app
~  A      @     203.0.113.10  ttl 1h → 5m
-  A      old   203.0.113.9
example.com: 1 to add, 1 to change, 1 to delete, 6 unchanged.
$ nameocean dns apply -f dns.yaml
Apply these changes? [y/N] y
Applied: 1 added, 1 changed, 1 deleted. example.com is at serial 214.

文件

dns.yaml

# yaml-language-server: $schema=https://nameocean.net/schemas/dns-zone.json
zone: example.com
records:
  - name: "@"
    type: A
    value: 203.0.113.10
    ttl: 5m
  - name: www
    type: CNAME
    value: "@"
  - name: "@"
    type: MX
    value: mail.example.com
    priority: 10
  - name: "@"
    type: TXT
    value: "v=spf1 mx -all"
  - name: _sip._tcp
    type: SRV
    value: sip.example.com
    priority: 10
    weight: 5
    port: 5060
  - name: old
    type: REDIRECT
    value: https://example.com/new

name 为 @ 表示区域本身，或为相对于区域的名称（www、_dmarc）；也可以使用带末尾点号的完全限定名称。
type 可为 A、AAAA、CNAME、MX、TXT、SRV、PTR 或 REDIRECT（HTTP 重定向到 value 中的 URL）。
ttl 可为 5m、15m、30m、1h 或 1d；未指定时，记录使用文件的 ttl，否则为 1h。MX 使用 priority（默认 10），SRV 使用 priority、weight 和 port，REDIRECT 使用 save_path（默认 true）。
同一文档也可以使用 JSON 格式。借助 JSON Schema，您可以在 VS Code 及其他编辑器中获得自动补全和校验。

plan 的生成方式

文件即代表整个区域：存在于区域中但不在文件中的记录将被删除。传入 --keep-unlisted（API 中为 prune=false）可仅执行添加和修改。

A、AAAA、MX 和 TXT 记录按名称和值进行匹配（MX 记录还会匹配优先级），因为同一名称可以对应多条此类记录。CNAME、SRV、PTR 和 REDIRECT 记录按名称进行匹配。如果 ttl 不同，或 SRV 的优先级、权重或端口不同，则视为修改；其他情况均视为新增或删除。

apply 在一个事务中运行：先删除，再修改，最后添加新记录，因此可以在同一文件中用 CNAME 替换 A 记录。如果有任何一条记录被拒绝，则不会进行任何更改。如果在 plan 与 apply 之间有人修改了区域，apply 将被拒绝，您需要重新执行 plan。

NameOcean 自用的记录，即 HTTP 重定向背后的地址以及用于 SSL 的 ACME 验证记录，永远不会被导出、纳入 plan 或删除。

GitHub Actions

创建一个具有 dns:write 权限的 API 密钥（仅执行 plan 的任务只需 dns:read），并将其保存为 NAMEOCEAN_API_KEY 机密。

.github/workflows/dns.yml

name: dns
on:
  pull_request: {paths: [dns.yaml]}
  push: {branches: [main], paths: [dns.yaml]}
jobs:
  dns:
    runs-on: ubuntu-latest
    env:
      NAMEOCEAN_API_KEY: ${{ secrets.NAMEOCEAN_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://nameocean.net/install.sh | sh
      - run: nameocean dns plan -f dns.yaml
      - if: github.event_name == 'push'
        run: nameocean dns apply -f dns.yaml --yes

对于只需报告偏差的任务，dns plan --detailed-exitcode 在存在更改时以退出码 2 退出。

使用 REST API

GET /dns/{zone}/export?output=yaml	以文件形式表示的区域（不带 output=yaml 时为 JSON）；X-Zone-Serial 标头为其序列号
POST /dns/{zone}/plan	apply 将执行的操作；不做任何更改，仅需 dns:read
POST /dns/{zone}/apply?serial=N	使区域与文件保持一致；如果区域已不再处于计划中的序列号，则返回 409 zone_changed

curl

$ curl -X POST https://nameocean.net/api/v1/dns/example.com/plan \
    -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
    -H "Content-Type: application/yaml" --data-binary @dns.yaml

请以 Content-Type: application/yaml 发送 YAML，或以 JSON 发送相同内容的文档。如果服务器无法接受该文件，将返回 400 invalid_zone_file，并附带 errors 列表，逐一指出有问题的记录和字段。详细信息请参阅 API 参考文档。

通过您的 AI

通过 MCP，助手可以导出区域，使用 plan_dns_zone 一次性规划对多条记录的更改，并在向您展示该计划后，使用 apply_dns_zone 应用更改。