企业官网建设流程全解析

• 网络安全
• 密码学

Derak Cloud 提供了一套基于 REST 的 DNS 管理 API，覆盖 DNS 记录的增删改查、CDN 缓存清理与域名 SSL 开关等能力；这套 API 同时是 Go 版 ACME 客户端 lego 中 Derak Cloud DNS provider（--dns derak）的底层支撑，用于自动完成 DNS-01 挑战所需的 TXT 记录写入与清理。本文以仓库内 Derak 接口笔记 providers/dns/derak/internal/readme.md 为主体，逐条讲解各接口的请求方法、参数、错误码与 curl 示例，并结合 providers/dns/derak/derak.go、providers/dns/derak/internal/client.go 等源码，说明 lego 是如何调用这套 API 完成证书自动签发的。读完本文，你将能独立用 curl 手工管理 Derak Cloud 的 DNS 记录，也能配置 lego 实现全自动的 Let's Encrypt DNS-01 验证。

接口总览与认证方式

所有接口统一挂载在https://api.derak.cloud/v1.0下（源码常量定义见 internal/client.go），核心资源路径为：

认证采用 HTTP Basic Auth：用户名固定为api，密码为你的 API Key。在 curl 中写作--user "api:YOUR_API_KEY"；在 lego 的 Go 客户端中，由 client.go 的req.SetBasicAuth("api", c.apiKey)完成同样的认证。API Key 可在 Derak Cloud 控制台获取（对应文档开头的 FAQ 指引）。

zoneId 即"网站/区域"ID（形如47c0ecf6c91243308c649ad1d2d618dd），表示你要操作的域名所属站点。

DNS 记录管理 API

GET：获取 DNS 记录列表

GET https://api.derak.cloud/v1.0/zones/{zoneId}/dnsrecords

查询参数

错误码

示例：不带参数获取全部记录：

curl -X GET --user "api:YOUR_API_KEY" \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/dnsrecords

按类型过滤 TXT 记录：

curl -X GET --user "api:api-MbmnxdpIBvk14nk5LFFdG1CV9PdMDfqi3tZAixBZLXYzM3qc187d7ede2de" \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/dnsrecords \ -F dnsType="TXT"

源码与测试佐证：lego 的 internal/client.go 用go-querystring将GetRecordsParameters{DNSType, Content}编码为查询串；对应 mock 测试 internal/client_test.go 用固定夹具 internal/fixtures/records-GET.json 验证了解析结果。需要特别留意源码中的一处注释（client.go）：

Note: the response is not influenced by the query parameters, so the documentation seems wrong.

即从实测看，查询参数可能并不会真正影响返回内容，因此过滤逻辑在 Go 客户端中并未被依赖（lego 主流程会直接用后续的创建/删除接口完成任务）。

PUT：创建新的 DNS 记录

PUT https://api.derak.cloud/v1.0/zones/{zoneId}/dnsrecords

参数（标*为必填）

错误码

示例：创建一条app.example.com的 A 记录指向1.2.3.4：

curl -X PUT --user "api:YOUR_API_KEY" \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/dnsrecords \ -F type="A" \ -F host="app" \ -F content="1.2.3.4"

源码佐证：Go 客户端CreateRecord（client.go）将Record结构体以 JSON 形式 PUT 到同一路径，并在 internal/client.go 中要求201 Created才算成功。lego 的 DNS-01 挑战正是调用该方法写入TXT记录（详见下文"与 lego 结合"一节）。

GET：查询单条 DNS 记录

GET https://api.derak.cloud/v1.0/zones/{zoneId}/dnsrecords/{recordId}

错误码

示例：

curl -X GET --user "api:YOUR_API_KEY" \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/dnsrecords/:recordId

PATCH：编辑 DNS 记录参数

PATCH https://api.derak.cloud/v1.0/zones/{zoneId}/dnsrecords/{recordId}

参数与 PUT 相同（type、host、content、ttl、cloud、priority、service、protocol、weight、port、advanced、upstreamPort、upstreamProtocol、customSSLType，均为可选，按需提交要修改的字段）。

错误码

示例：仅把记录开启 CDN 云加速：

curl -X PATCH --user "api:YOUR_API_KEY" \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/dnsrecords/:recordId \ -F cloud="true"

DELETE：删除 DNS 记录

DELETE https://api.derak.cloud/v1.0/zones/{zoneId}/dnsrecords/{recordId}

错误码

示例：

curl -X DELETE --user "api:YOUR_API_KEY" \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/dnsrecords/:recordId

源码佐证：DeleteRecord（client.go）在删除后还会检查响应中的success字段，若为 false 则根据error字段映射为可读错误文本（codeText，见 internal/types.go）。

缓存清理 API

POST：清理（Purge）缓存

POST https://api.derak.cloud/v1.0/zones/{zoneId}/cache/purge

不传任何参数时会清空整个缓存；传参时按指定目标精确清理。

参数

错误码

示例：清理两个 URL：

curl -X POST --user "api:YOUR_API_KEY" \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/cache/purge \ -F urls[]="https://www.derak.cloud/post/1" \ -F urls[]="https://www.derak.cloud/post/2"

清理两个主机名：

curl -X POST --user "api:YOUR_API_KEY" \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/cache/purge \ -F hostnames[]="www.derak.cloud" \ -F hostnames[]="app.derak.cloud"

清空全部缓存（谨慎使用）：

curl -X POST --user "api:YOUR_API_KEY" \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/cache/purge

SSL 证书管理 API

PUT：为域名启用 SSL

PUT https://api.derak.cloud/v1.0/zones/{zoneId}/ssl/

错误码

示例：

curl -X PUT --user "api:YOUR_API_KEY" \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/ssl/

DELETE：为域名禁用 SSL

DELETE https://api.derak.cloud/v1.0/zones/{zoneId}/ssl/

错误码

示例：

curl -X DELETE --user "api:YOUR_API_KEY" \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/ssl/

错误码速查表

综合上文各接口的错误码，Derak Cloud API 的典型错误如下（Go 客户端在 internal/types.go 中亦有相同映射，错误样例见 internal/fixtures/error.json）：

与 lego 结合：用 Derak Cloud 自动完成 DNS-01 挑战

上述 API 正是 lego 中derakDNS provider 的实现基础。从 v4.12.0 起（见 derak.toml 的Since字段），lego 支持通过环境变量配置该 provider：

命令行签发示例（derak.toml）：

DERAK_API_KEY="xxxxxxxxxxxxxxxxxxxxx" \ lego run --dns derak -d '*.example.com' -d example.com

对应官方文档见 docs/content/dns/zz_gen_derak.md。所有环境变量同样支持_FILE后缀以从文件读取（更安全地注入密钥）。

zoneId 的自动探测：若不设置DERAK_WEBSITE_ID，lego 会调用GetZones（client.go）请求一个非官方文档化的接口https://api.derak.cloud/api/v2/service/cdn/zones（源码注释说明该端点来自对 Derak 控制台 UI 网络请求的分析），然后遍历返回的 zone 列表，通过EffectiveFQDN与zone.HumanReadable的域名后缀匹配确定目标 zone（derak.go）。建议在多站点场景下显式设置DERAK_WEBSITE_ID以避免歧义。

DNS-01 全流程（Present/CleanUp）：Present（derak.go）先生成挑战信息，通过FindZoneByFqdn定位权威 zone、ExtractSubDomain提取记录名，再构造TXT记录（type=TXT、host=记录名、content=挑战值、ttl=配置值）调用CreateRecord（PUT 接口）写入；同时把token → recordId存进内存 map。CleanUp（derak.go）则通过该 map 找到 recordId 调用DeleteRecord（DELETE 接口）清理，并在完成后从 map 中移除，保证重复签发不会残留。Timeout返回传播超时与轮询间隔，配合挑战前的等待逻辑适应 DNS 传播延迟。

测试与可信度：单元测试覆盖了全部 5 个 API 方法与 zone 列表解析（internal/client_test.go），响应夹具存放在 internal/fixtures 下；provider 层面还有需要真实凭据的 live 测试TestLivePresent/TestLiveCleanUp（derak_test.go），日常默认跳过。

小结

Derak Cloud 的这套 REST API 覆盖了 DNS 记录全生命周期、缓存清理与 SSL 开关三大能力，配合 Basic Auth 认证与明确的错误码，非常适合脚本化运维；而在 lego 中，--dns derak通过同样的接口自动完成 TXT 记录写入与清理，实现 Let's Encrypt 证书的零人工 DNS-01 签发。手工管理时可直接复用上文 curl 示例，自动化场景则推荐优先使用 lego 的环境变量配置方式。

• 网络安全
• 密码学