Derak Cloud DNS 管理 API 实战指南：从 curl 接口到 lego DNS-01 自动签发

网络安全密码学【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址https://gitcode.com/gh_mirrors/le/lego点击查看免费下载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 实现全自动的 Lets Encrypt DNS-01 验证。接口总览与认证方式所有接口统一挂载在https://api.derak.cloud/v1.0下源码常量定义见 internal/client.go核心资源路径为资源方法路径DNS 记录列表GET / PUT/zones/{zoneId}/dnsrecords单条 DNS 记录GET / PATCH / DELETE/zones/{zoneId}/dnsrecords/{recordId}缓存清理POST/zones/{zoneId}/cache/purge域名 SSL 开关PUT / DELETE/zones/{zoneId}/ssl/认证采用 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 记录管理 APIGET获取 DNS 记录列表GET https://api.derak.cloud/v1.0/zones/{zoneId}/dnsrecords查询参数参数名说明dnsTypeDNS 记录类型筛选如TXTcontent记录内容Host 值筛选错误码错误类型错误码ForbiddenError1003RateLimitExceeded1013示例不带参数获取全部记录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 dnsTypeTXT源码与测试佐证lego 的 internal/client.go 用go-querystring将GetRecordsParameters{DNSType, Content}编码为查询串对应 mock 测试 internal/client_test.go 用固定夹具 internal/fixtures/records-GET.json 验证了解析结果。需要特别留意源码中的一处注释client.goNote: 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参数标*为必填参数名说明*type记录类型可选A、AAAA、CNAME、MX、NS、CAA、TXT、SPF、PTR、SRV*host记录的主机名Host 值*content记录内容原文档亦写为 Host 值实际即解析目标值ttl记录 TTL默认 0cloud流量是否经过 CDN 云默认 falsepriorityMX / SRV 记录优先级默认 0serviceSRV 记录的服务名protocolSRV 记录协议默认_tcpweightSRV 记录权重默认 0portMX / SRV 记录端口默认 0advanced是否启用高级设置默认 falseupstreamPort上游端口默认 80upstreamProtocol上游协议默认http。注意修改同一子域其他记录会覆盖该设置customSSLType自定义 SSL 类型。注意修改同一子域其他记录会覆盖该设置错误码错误类型错误码ForbiddenError1003RateLimitExceeded1013DNSValidationError1008示例创建一条app.example.com的 A 记录指向1.2.3.4curl -X PUT --user api:YOUR_API_KEY \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/dnsrecords \ -F typeA \ -F hostapp \ -F content1.2.3.4源码佐证Go 客户端CreateRecordclient.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}错误码错误类型错误码ForbiddenError1003RateLimitExceeded1013RecordNotFoundError1021示例curl -X GET --user api:YOUR_API_KEY \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/dnsrecords/:recordIdPATCH编辑 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均为可选按需提交要修改的字段。错误码错误类型错误码ForbiddenError1003RateLimitExceeded1013RecordNotFoundError1021DNSValidationError1008示例仅把记录开启 CDN 云加速curl -X PATCH --user api:YOUR_API_KEY \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/dnsrecords/:recordId \ -F cloudtrueDELETE删除 DNS 记录DELETE https://api.derak.cloud/v1.0/zones/{zoneId}/dnsrecords/{recordId}错误码错误类型错误码ForbiddenError1003RateLimitExceeded1013RecordNotFoundError1021示例curl -X DELETE --user api:YOUR_API_KEY \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/dnsrecords/:recordId源码佐证DeleteRecordclient.go在删除后还会检查响应中的success字段若为 false 则根据error字段映射为可读错误文本codeText见 internal/types.go。缓存清理 APIPOST清理Purge缓存POST https://api.derak.cloud/v1.0/zones/{zoneId}/cache/purge不传任何参数时会清空整个缓存传参时按指定目标精确清理。参数参数名说明hostname要清理的主机名hostnames要清理的主机名数组url要清理的 URLurls要清理的 URL 数组错误码错误类型错误码ForbiddenError1003RateLimitExceeded1013示例清理两个 URLcurl -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/purgeSSL 证书管理 APIPUT为域名启用 SSLPUT https://api.derak.cloud/v1.0/zones/{zoneId}/ssl/错误码错误类型错误码ForbiddenError1003示例curl -X PUT --user api:YOUR_API_KEY \ https://api.derak.cloud/v1.0/zones/47c0ecf6c91243308c649ad1d2d618dd/ssl/DELETE为域名禁用 SSLDELETE https://api.derak.cloud/v1.0/zones/{zoneId}/ssl/错误码错误类型错误码ForbiddenError1003示例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错误类型错误码出现场景ForbiddenError1003API Key 无效或无权限DNSValidationError1008记录内容校验失败创建/编辑时RateLimitExceeded1013请求触发限流RecordNotFoundError1021目标记录不存在与 lego 结合用 Derak Cloud 自动完成 DNS-01 挑战上述 API 正是 lego 中derakDNS provider 的实现基础。从 v4.12.0 起见 derak.toml 的Since字段lego 支持通过环境变量配置该 provider环境变量必填说明默认值DERAK_API_KEY是API Key对应接口 Basic Auth 密码无DERAK_WEBSITE_ID否强制指定 zone/website ID跳过自动探测自动探测DERAK_TTL否TXT 记录 TTL秒120dns01.DefaultTTLDERAK_PROPAGATION_TIMEOUT否DNS 传播最大等待时间秒120DERAK_POLLING_INTERVAL否传播检查间隔秒5DERAK_HTTP_TIMEOUT否API 请求超时秒30命令行签发示例derak.tomlDERAK_API_KEYxxxxxxxxxxxxxxxxxxxxx \ lego run --dns derak -d *.example.com -d example.com对应官方文档见 docs/content/dns/zz_gen_derak.md。所有环境变量同样支持_FILE后缀以从文件读取更安全地注入密钥。zoneId 的自动探测若不设置DERAK_WEBSITE_IDlego 会调用GetZonesclient.go请求一个非官方文档化的接口https://api.derak.cloud/api/v2/service/cdn/zones源码注释说明该端点来自对 Derak 控制台 UI 网络请求的分析然后遍历返回的 zone 列表通过EffectiveFQDN与zone.HumanReadable的域名后缀匹配确定目标 zonederak.go。建议在多站点场景下显式设置DERAK_WEBSITE_ID以避免歧义。DNS-01 全流程Present/CleanUpPresentderak.go先生成挑战信息通过FindZoneByFqdn定位权威 zone、ExtractSubDomain提取记录名再构造TXT记录typeTXT、host记录名、content挑战值、ttl配置值调用CreateRecordPUT 接口写入同时把token → recordId存进内存 map。CleanUpderak.go则通过该 map 找到 recordId 调用DeleteRecordDELETE 接口清理并在完成后从 map 中移除保证重复签发不会残留。Timeout返回传播超时与轮询间隔配合挑战前的等待逻辑适应 DNS 传播延迟。测试与可信度单元测试覆盖了全部 5 个 API 方法与 zone 列表解析internal/client_test.go响应夹具存放在 internal/fixtures 下provider 层面还有需要真实凭据的 live 测试TestLivePresent/TestLiveCleanUpderak_test.go日常默认跳过。小结Derak Cloud 的这套 REST API 覆盖了 DNS 记录全生命周期、缓存清理与 SSL 开关三大能力配合 Basic Auth 认证与明确的错误码非常适合脚本化运维而在 lego 中--dns derak通过同样的接口自动完成 TXT 记录写入与清理实现 Lets Encrypt 证书的零人工 DNS-01 签发。手工管理时可直接复用上文 curl 示例自动化场景则推荐优先使用 lego 的环境变量配置方式。赞分享网络安全密码学【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址https://gitcode.com/gh_mirrors/le/lego点击查看免费下载相关推荐lego 集成 Derak Cloud DNS 提供者DNS-01 挑战配置指南与源码实现解析lego 集成 Derak Cloud DNS 提供者DNS 01 挑战配置指南与源码实现解析 本篇文章以 lego 项目内置的 Derak Cloud DN网络安全密码学Vulhub 复现 Mojarra JSF ViewState 反序列化漏洞从 Payload 构造到远程命令执行Vulhub 复现 Mojarra JSF ViewState 反序列化漏洞从 Payload 构造到远程命令执行 本文基于 Vulhub 仓库中 mojar网络安全密码学Backstage 应用 UI 定制指南MUI 与 Backstage UI 双主题体系深度实践Backstage 应用 UI 定制指南MUI 与 Backstage UI 双主题体系深度实践 Backstage 原生内置了 Light / Dark 两网络安全密码学上一篇ComponentKit动画系统终极指南打造流畅的iOS用户体验下一篇linux-tutorial 项目之 FastDFS 分布式文件系统架构解析与部署配置实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考