DigitalPlat FreeDomain API 自动化安全指南：专用密钥、只读优先与变更操作安全模式

本篇指南基于教程第 6.1 章「API Automation Safety」展开，面向需要对接域名注册、DNS、托管或监控服务 API 的自动化实践者。读完本文，你将能够：为自动化任务创建最小权限的专用密钥、用安全方式加载令牌、按「只读优先」路线搭建可观测的自动化脚本，并用一套可复现的「变更安全模式」约束注册、续费、删除等会产生外部影响的写操作，最后为整个自动化系统配置告警与手工恢复预案。

一、适用范围：以官方当前文档为准的第一原则

本章内容适用于任何暴露 API 的注册、DNS、托管或监控服务。核心原则只有一条：把该服务当前的官方文档视为端点路径、请求格式、权限、限流和错误码的最终权威。

这一点在 DigitalPlat FreeDomain 的语境下尤其重要。从仓库中 Dashboard 导览 可以看到，Dashboard 在可用时会提供「API Keys」和「API Documentation」两个区域；而 API 使用安全章节 明确指出：当前文档定义了实际的端点、权限、请求格式与限制，且不要假设 API 能管理外部 DNS 记录——DigitalPlat 的命名空间委派与外部 DNS 服务商的记录 API 是两套独立的系统。产品边界章节 也进一步说明，DigitalPlat 只保存外部权威 nameserver 的主机名，并不替代外部 DNS 服务的记录编辑器。

因此，在开始任何自动化之前：

• 先确认你要操作的状态到底属于哪一层：注册状态（DigitalPlat 侧）、DNS 委派（外部 nameserver）、还是 DNS 记录（外部 DNS 服务商）；
• 从认证后的官方 API 文档中抄录当前基址（base URL）与资源路径，而不是套用旧教程或猜测的路径；
• 注意 API 能力边界：例如 DigitalPlat 的密钥不应被默认可编辑外部 zone 记录。

二、选择适合自动化的任务

好的自动化任务应具备三个特征：可重复、可观测、可回滚。文档中给出的典型示例包括：

• 读取域名清单（inventory）；
• 检查到期日期；
• 将已配置的 nameserver 与期望值进行比对；
• 对状态变化进行告警。

而注册、续费、删除、nameserver 更新、购买以及批量变更这类操作需要更强的防护，因为一次重试或一个变量写错就可能产生外部影响——这些影响往往无法像本地测试那样随意撤销。

这与仓库 监控与事故响应章节 中「监控用户路径」的思路一致：自动化应该持续比对当前状态与期望状态（例如父级委派与批准的 nameserver 集合是否一致），而不是盲目地重复下发变更。

三、创建专用密钥

为自动化创建的每一把密钥都应遵循以下要求：

• 使用服务提供的最窄作用域（最小权限）；
• 每个应用、每个环境各建一把密钥，不复用；
• 给密钥起一个能标识「所有者 + 用途」的名称，方便日后审计与清理；
• 记录密钥的轮换日期和删除日期；
• 密钥本身必须放在源码控制之外。

仓库 账户与 API 安全章节 给出了配套的操作要求：只为主题明确的自动化任务创建密钥；密钥存于 secret manager 或受保护的环境变量；绝不把密钥写进 URL、截图、issue 报告、前端 JavaScript 或 Git 提交；在人员变动、疑似泄露或出现异常活动后轮换密钥；删除未使用的密钥。其中一条经验值得特别强调：如果密钥不慎被提交到仓库，删掉可见的那一行是不够的——必须立即吊销或轮换凭据，再按项目事故流程处理仓库历史。

发布代码前可以用仓库建议的命令自查：

git status --short
git diff --cached
git grep -n -i 'api[_-]*key\|token\|secret\|password'

这些手工检查可能漏掉编码过或形式特殊的密钥，毕业项目章节 中还给出了更宽的正则扫描示例（rg -n -i 'password|token|secret|api[_-]?key|192\.168\.' .），建议在开发工作流中再叠加专用 secret scanner 做兜底。

四、安全地加载密钥

教程给出的交互式加载模式是：

read -r -s DIGITALPLAT_API_TOKEN
export SERVICE_API_TOKEN

read -r -s 避免输入时明文回显令牌，随后 export 使其对子进程可见。需要清醒认识的是：这只解决了「输入时可见」的问题，环境变量与运行中进程依然处于暴露面内，任何能读取该进程 /proc/<pid>/environ 的本地主体都能看到它。生产级自动化应优先使用托管密钥系统（managed secret store）。

终端基础章节 从另一角度印证了这一要求：shell 历史会保留命令，因此不要在命令行中直接敲令牌和密码；更不要把密钥拼进 URL——URL 会出现在历史记录、日志、referrer 数据与截图中。该章的复习问题「为什么 API token 不应直接出现在 shell 命令里？」正是本节要内化的答案。

五、只读优先：启用写操作之前的六步清单

在开放任何 mutation（写/变更）能力之前，先让自动化只读运行，并按顺序完成：

1. 获取单个已知资源（fetch a single known resource）；
2. 校验响应状态码与响应结构（schema）；
3. 为所有请求添加超时；
4. 显式处理分页（pagination）——域名清单类接口几乎必然分页，漏掉最后一页会造成「资源数量突变」类误报；
5. 在日志中脱敏授权头（authorization headers）与个人数据；
6. 测试限流（rate limit）与服务端错误的处理路径。

这一步骤清单的价值在于把「连通性」扩展为「可靠性」：超时、分页、脱敏、限流处理都是脚本进入无人值守前必须覆盖的分支，而不是事后补丁。

六、变更操作安全模式

对于每一次会产生外部状态变化的请求，套用文档给出的固定模式：

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

即：读取当前状态 → 与期望状态比对 → 展示将要发生的精确变更 → 必要时要求人工批准 → 发送一个幂等请求 → 再次读取状态 → 记录经过验证的结果。

其中两条是硬性红线：

• 不要自动重试含义模糊的注册、支付、续费或删除响应。 网络超时之后，服务端可能已经完成了注册。此时的正确动作是回到权威状态（重新读取）再判断是否需要补发请求，而不是直接重放请求——重放可能造成重复注册、重复扣费或重复删除；
• 写请求本身应设计为幂等，配合「读-比对-写-读」的闭环，即使某一步失败也能从状态比对中恢复判断，而不是依赖请求是否发出过。

DigitalPlat 平台的 API 安全章节 对同一模式有更短的表述：读当前状态、与意图状态比对、展示精确的拟变更、外部影响重大时要求批准、只发一个请求、再次读取权威状态。两个版本互为印证，核心不变：用状态比对取代对请求历史的信任。

七、请求骨架：curl 示例与参数说明

文档给出了一个刻意省略真实端点的骨架，端点需要从当前 Dashboard API 文档中抄录：

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

各参数的工程含义：

• --fail-with-body：HTTP 状态码 ≥ 400 时以非零码退出，同时保留响应体用于诊断，方便脚本据此分支处理；
• --connect-timeout 10：建立连接的阶段限时 10 秒，避免自动化在 DNS 或路由故障上无限挂起；
• --max-time 30：整个请求（含数据传输）总限时 30 秒，保证批处理不会被单个慢请求拖死；
• Authorization: Bearer $SERVICE_API_TOKEN：令牌从环境变量注入，绝不写死在脚本里；
• Accept: application/json：显式声明期望的响应格式，便于做 schema 校验；
• URL 使用 .example 占位符是有意为之——真实基址与资源路径只能从认证后的官方 API 文档获取。

一条配套纪律：生产中不要开启会打印 Authorization 头的冗长 HTTP 日志（如 --trace 类详细日志），否则密钥会随日志进入监控系统或工单附件。这与第五章第 5 步「日志脱敏」是同一条要求。

八、监控自动化本身

自动化上线不等于自动化结束。文档要求对以下事件配置告警：

• 认证失败（authentication failure）；
• 权限变化（permission changes）；
• 触发限流（rate limits）；
• 资源数量异常（unexpected resource counts，例如域名清单突然变少）；
• 域名状态或 nameserver 变化；
• 反复重试（repeated retries，往往意味着上游故障而非瞬时抖动）;
• 批处理只完成了部分（partial batch completion）。

最后一句容易被忽略但至关重要：保留一套不依赖自动化自身健康的手工恢复流程。自动化宕机、密钥过期或脚本 bug 时，域名续费与状态核查仍然要能靠人手工完成。这与仓库 监控与事故响应章节 的原则完全一致：每条告警都要能回答「用户影响是什么、谁接收、多紧急、先跑哪条诊断、何时升级、如何验证恢复」；且该章的域名劫持处置流程明确包含「吊销会话与 API 密钥」，说明密钥管理不是上线前的一次性工作，而是事故响应的一部分。

九、落地检查清单

把本章浓缩为可执行的验收清单：

1. 任务清单：先列出只读任务并跑通，写操作任务单独列清单并标注外部影响等级；
2. 密钥：每应用每环境一把、最窄作用域、命名含所有者与用途、记录轮换/删除日期、不在源码库中；
3. 加载：read -r -s + export 起步，生产迁移到 secret store；
4. 只读脚本：单资源获取、状态与 schema 校验、超时、分页、日志脱敏、限流与 5xx 处理全部就绪；
5. 写脚本：完整执行「读-比对-展示-批准-幂等单请求-再读-记录」闭环，禁止对模糊的注册/支付/续费/删除响应自动重试；
6. 告警：认证失败、限流、数量异常、状态变化、反复重试、批次部分完成；
7. 预案：一份可离线执行的手工恢复步骤，覆盖自动化工具全部不可用的情况。

完成以上内容后，即可按教程顺序继续学习 自建权威 DNS（6.2 章），把 API 自动化与自托管 DNS 运维的边界一并纳入同一套安全纪律。