DigitalPlat FreeDomain API 安全使用指南：只读起步、密钥最小权限与变更请求的六步安全模式

本文基于教程书 Category A 的第 1.6 章 Use the API Safely，系统讲解 DigitalPlat FreeDomain 控制台（Dashboard）API 的安全使用边界与实操方法：为什么绝不能假设 API 可以管理外部 DNS 记录、如何用"只读起步 + 六步变更安全模式"完成库存盘点与状态核对、如何为密钥落实最小权限与生命周期管理，以及一个可直接复制的 curl 请求骨架及其每个参数的作用。读完本篇，你将能够在不引入外部副作用的前提下，用 API 完成域名注册状态类的自动化查询，并建立一套可复用的变更审批与验证流程。

API 能力边界：先弄清它能做什么、不能做什么

DigitalPlat FreeDomain 是免费的域名注册服务（当前支持 .dpdns.org、.us.kg、.qzz.io、.xx.kg、.qd.je 等后缀），其核心产品模型是"注册 + 委托"：DigitalPlat 负责注册域名，并将域名委托（delegate）到用户自己提供的外部权威 DNS 服务的 nameserver 上。这一边界在 Category A 产品边界说明 和 1.0 章 中反复强调，它直接决定了 API 的能力范围。

1.6 章开篇即给出两条关键事实：

1. Dashboard 当前暴露了 API key 区域和 API 文档区域。端点（endpoint）、权限（permissions）、请求格式（request formats）与限制（limits）等细节，以当前官方 API 文档为准——不同版本的接口可能不同，本教程刻意不写死任何真实端点。
2. 不要假设 API 可以管理外部 DNS 记录。 DigitalPlat 的 nameserver 委托，与外部 DNS 服务商（如 Cloudflare 等权威 DNS 服务）的记录 API，是两套完全独立的系统。在外部 DNS 服务商创建 A、CNAME、MX、TXT 等记录时，必须使用那家服务商自己的 API 或控制台，而不是 DigitalPlat 的 API key。

用 1.0 章 的完整关系图来理解，责任链是三层：

DigitalPlat registration
  |
  | delegates the domain to external NS hostnames
  v
External authoritative DNS
  |
  | publishes A, CNAME, MX, TXT, and other records
  v
Website, email, and other services

DigitalPlat 这一层存储的是"域名委托给了哪几台外部 nameserver"这一注册层面的信息；具体记录（A 记录指向哪个 IP、MX 指向哪个邮件服务器）由外部权威 DNS 发布。因此，Dashboard Tour 中 API 一节的结论是：DigitalPlat 的 key 必须假定它不能编辑外部 zone 记录；搜索到某个功能入口也不代表它具备对应能力，实际支持范围以功能页面和当前文档定义为准。

只读起步：哪些任务适合 API 自动化

教程建议从只读任务开始，且任务类型应满足"可重复、可观察、可逆"三个条件。1.6 章 给出的第一批安全任务：

• 库存盘点（inventory）：列出账号下所有域名；
• 状态检查（status checks）：核对注册状态、到期日、当前生效的 nameserver 值。

高级篇 6.1 章《API 自动化安全》 将这一原则扩展到任意带 API 的注册/DNS/托管/监控服务，并补充了更适合自动化的只读场景：

只读任务	说明
读取域名库存	获取账号下全部域名列表，作为基线快照
检查到期日	配合提醒机制（90/60/30/7 天四档，见 1.4 章 的续期计划）提前预警
比对 nameserver	将 API 返回的委托 nameserver 与预期值比对，发现漂移
状态变更告警	域名状态、nameserver 发生变化时触发通知

而注册、续期、删除、nameserver 变更、购买、批量变更这类操作，因为一次错误或重试就可能在外部世界产生不可轻易撤销的后果，必须启用更强的防护（下一节的六步模式 + 审批）。

只读自动化本身也要按 6.1 章 的顺序搭建，而不是直接"能用就行"：

1. 先抓取单个已知资源（fetch a single known resource）；
2. 校验响应状态码与响应结构（schema）；
3. 加上超时控制；
4. 显式处理分页，不要默认第一页就是全部；
5. 日志中脱敏：去掉 Authorization 头和个人数据；
6. 专门测试限流（rate limit）与服务端错误的处理路径。

变更请求的六步安全模式

1.6 章的核心是一条六步流水线：在发起任何会改变外部状态的请求（mutation）之前，按以下顺序执行：

1. 读取当前状态（Read the current state）——以权威数据源为基准；
2. 与目标状态比对（Compare it with the intended state）——算出确切差异；
3. 显示将要执行的确切变更（Display the exact proposed change）——让差异可见、可审；
4. 外部影响显著时要求审批（Require approval when external effects are significant）；
5. 发送一个请求（Send one request）——一次只发一个，而不是循环补发；
6. 再次读取权威状态（Read the authoritative state again）——以服务端实际状态为准，而非请求的"成功感"。

6.1 章 将其整理为等价的文字流程图，并增加了"记录已验证结果"一步：

Read current state
-> Compare with desired state
-> Display exact change
-> Require approval when appropriate
-> Send one idempotent request
-> Read state again
-> Record the verified result

其中最重要的一条红线是：不要自动重试结果含糊的注册、续期、删除、购买、nameserver 操作。含糊（ambiguous）指的是：请求超时、连接中断、或返回了无法确认是否落库的状态码。此时正确的动作是回到第 6 步——先读权威状态，判断上一次请求是否已经生效，再决定是否可以安全地发起新请求。这一条与 1.4 章 的续期清单完全一致："收到含糊响应后不要反复提交，先回到 Domain List 确认之前的操作是否成功"。对 API 自动化来说同理：重复提交注册或续期请求，最坏的情况是产生重复的外部副作用。

变更后用 DNS 查询做独立验证

对于 nameserver 变更类操作，六步模式中的"再次读取权威状态"可以用与 API 无关的独立信道来做——直接查 DNS，见 命令参考 6.3 章 与 1.3 章 的验证命令：

# 查看域名当前委托的权威 nameserver
dig NS example.dpdns.org

# 必要时沿父级域逐级追踪委托链
dig +trace NS example.dpdns.org

# 直接询问某台外部权威服务器，确认 zone 已生效
dig @ns1.dns-service.example SOA example.dpdns.org

验证的判据是：dig NS 返回的 nameserver 集合，必须与你在 DigitalPlat 填入/提交的外部 nameserver 完全一致。如果 NS 正确但 A 记录缺失，问题出在外部 DNS zone（见 1.0 章 的分层诊断表），反复修改 DigitalPlat 侧的 nameserver 字段不会创建出任何记录。

密钥安全：一个目的、最小权限、受保护存储

1.6 章的 Key Safety 一节给出了六条密钥管理规则：

• 一个 key 只服务一个目的（Create a key for one purpose）；
• 使用可用的最小权限（the narrowest available permission）；
• 存放在受保护的密钥系统中（a protected secret system），而不是散落在脚本、配置文件或笔记里；
• 绝不放进前端 JavaScript、截图、URL 或 Git 提交——这四类是泄漏的高发位置；
• 暴露后或人员变动后轮换（Rotate it after exposure or staff changes）；
• 删除不再使用的 key，定期清理。

6.1 章 在此基础上补充了工程化细节：

• 每个应用、每个环境单独建 key，不跨环境共用；
• 给 key 起一个能标识属主和用途的名字，便于审计；
• 记录 key 的轮换日期和删除日期，让它有明确的生命周期。

本地开发时读取密钥，推荐 6.1 章 的交互式方式，避免 token 出现在命令历史或终端回显中：

read -r -s DIGITALPLAT_API_TOKEN
export SERVICE_API_TOKEN

该方式只是避免"打字时明文可见"，教程同时提醒：环境变量和运行中的进程仍然需要保护；生产自动化应优先使用托管密钥存储（managed secret store）。另外两条配套纪律：日志中脱敏 Authorization 头与个人数据；生产环境不要开冗长的 HTTP 调试日志，因为它可能把 Authorization 头原样打印出来。

标准请求骨架：逐参数解读

1.6 章刻意用占位地址（address-from-current-api-documentation.example）给出请求骨架，要求读者只从登录态下的官方 API 文档复制真实的 base URL 和资源路径。骨架本身是一个可以直接上手的模板：

curl --fail-with-body \
  --connect-timeout 10 \
  --max-time 30 \
  --header "Authorization: Bearer $DIGITALPLAT_API_TOKEN" \
  --header "Accept: application/json" \
  "https://address-from-current-api-documentation.example/resource"

各部分的作用：

参数	作用	工程含义
--fail-with-body	HTTP 状态码 ≥ 400 时以失败退出，同时保留输出响应体	区别于 --fail（只给错误码、丢弃正文）：能拿到服务端返回的错误详情用于排障，又让脚本可据此判断成败
--connect-timeout 10	建立连接最长等 10 秒	防止 TCP/TLS 握手阶段无限挂起；要求 curl 7.76.0 及以上版本才支持 --fail-with-body，使用时需确认本地 curl 版本
--max-time 30	整个请求（含传输）最长 30 秒	兜底超时：即使连接成功但响应体传输卡住，也会在 30 秒后中止
Authorization: Bearer $DIGITALPLAT_API_TOKEN	以 Bearer 令牌方式携带 API key	从环境变量取值而非硬编码，配合前文的 read -r -s 或密钥存储注入
Accept: application/json	声明期望 JSON 响应	与"校验响应 schema"的只读检查流程配套
占位 URL	端点路径不写死	真实端点、权限与限制一律以当前官方 API 文档为准，避免教程过期后误导

这个骨架对应的就是六步模式中"发送一个请求"那一步：带认证、带超时、失败可见、成功可读。把真实端点填上后，先跑通它再谈自动化脚本，是教程隐含的最短路径。

自动化监控与人工兜底

6.1 章 建议对 API 自动化本身设置告警，覆盖以下信号：认证失败、权限变化、限流、资源数量异常（例如库存突然变少）、域名状态或 nameserver 变化、重复重试、批量任务只完成了一部分。这些信号大多可以基于只读轮询结果计算得出，与 1.6 章"先读状态、再谈变更"的思路闭环。

最后一条原则值得单独强调：保留一套不依赖自动化系统健康状态的人工恢复流程。API 挂了、密钥轮换了、脚本有 bug 时，你仍然能通过 Dashboard 手动完成关键操作（对照 Dashboard 安全操作例程 的八步流程：确认账号 → 读公告 → 打开目标域名 → 记录现状 → 复核意图 → 核对策略/额度/费用 → 提交一次 → 回到权威页面验证结果）。

小结与下一步

本篇继承 1.6 章 的全部核心结论：Dashboard 提供 API key 与 API 文档区域，端点细节以当前官方文档为唯一权威来源；DigitalPlat API 与外部 DNS 记录 API 是两套系统，不可互相假设；只读任务（库存、状态核对）是安全的起点；变更必须走"读现状 → 比对 → 展示 → 审批 → 发一个请求 → 读权威状态"的六步模式，且含糊响应绝不自动重试；密钥按单目的、最小权限、受保护存储、定期轮换、及时删除来管理。

配套的深入材料：6.1 章《API 自动化安全》 提供完整自动化工程实践，6.3 章《命令参考》 提供 dig/curl 诊断命令集。完成 Category A 的 DigitalPlat 专属章节后，按教程路径继续 Category B：通用域名与网站教程。