企业官网建设流程全解析

• 网络
• CLI

DDNS 项目的edgeoneProvider 用于将腾讯云 EdgeOne 加速域名的源站 IP 动态更新为本机实时公网 IP，适用于源站为家庭宽带、VPS 等动态 IP 的边缘加速场景。本文覆盖认证凭证获取、完整配置示例、extra.teoDomainType双模式切换、endpoint 选择等全部配置细节，并结合 edgeone.py 源码深入解析 TC3 签名、查询-创建/更新的调用链与备源保留机制，读完后你即可独立完成一套可运行的 EdgeOne DDNS 配置。

功能定位：edgeone 与 edgeone_dns 两个 Provider

EdgeOne 是腾讯云提供的边缘计算与加速服务。DDNS 项目通过 EdgeOne API 动态更新加速域名的源站 IP 地址，从而让加速域名始终指向最新的源站出口 IP。

这里需要特别注意两个 Provider 的分工：

• edgeone（EdgeOneProvider）：管理 EdgeOne加速域名的源站（Origin）IP，这是默认行为；
• edgeone_dns（EdgeOneDnsProvider）：管理 EdgeOne 上非加速域名的普通 DNS 记录。

从源码看，edgeone_dns.py 中的EdgeOneDnsProvider直接继承自EdgeOneProvider，仅在构造函数中固定注入options["teoDomainType"] = "dns"（见 edgeone_dns.py#L18-L27），即两者共用同一套请求与签名逻辑，只靠一个开关区分走的 API 分支。

在 provider/init.py#L45-L52 中，Provider 名称支持以下别名映射（get_provider_class会对输入做小写化后查表）：

这些别名同样受 CLI 参数--dns支持，见 cli.py#L175-L194 中的 choices 列表。在 field-model.json 中，edgeone的认证方式为id-token，其中id对应 Secret ID，token对应 Secret Key。

说明：如果你要管理的是非加速域名的普通 DNS 记录，直接使用dns: "edgeone_dns"比在edgeone中配置extra.teoDomainType: "dns"更干净、语义更清晰。

认证：SecretId / SecretKey

EdgeOne 与腾讯云 DNS（tencentcloud Provider）一致，使用腾讯云 SecretId 和 SecretKey 进行签名认证，但权限要求不同：需要确保账号拥有 EdgeOne 操作权限。

获取凭证的步骤：

1. 登录腾讯云控制台；
2. 进入「访问管理 → API 密钥管理」（CAM）页面；
3. 点击「新建密钥」创建密钥对；
4. 复制生成的SecretId与SecretKey并妥善保管；
5. 确认账号已具备 EdgeOne 操作权限。

最小认证配置如下：

{ "dns": "edgeone", "id": "SecretId", // 腾讯云 SecretId "token": "SecretKey" // 腾讯云 SecretKey }

注意 SimpleProvider._validate 会在初始化时强制校验：id、token与endpoint任一缺失都会抛出ValueError，因此认证信息必须在运行时真正传入才会生效。

权限要求

确保腾讯云账号具备以下权限之一：

• QcloudTEOFullAccess：EdgeOne 完全访问权限（推荐）；
• QcloudTEOReadOnlyAccess + 自定义写权限：细粒度权限控制。

权限可在控制台的「访问管理 → 策略管理」中查看与配置。

完整配置示例

加速域名配置（默认模式）

{ "$schema": "https://ddns.newfuture.cc/schema/v4.1.json", // 格式校验 "dns": "edgeone", // 当前 Provider "id": "your_secret_id", // 腾讯云 SecretId "token": "your_secret_key", // 腾讯云 SecretKey "index4": ["url:http://api.ipify.org", "public"], // IPv4 地址来源 "index6": "public", // IPv6 地址来源 "ipv4": ["ddns.newfuture.cc"], // IPv4 域名列表 "ipv6": ["ipv6.ddns.newfuture.cc"], // IPv6 域名列表 "endpoint": "https://teo.intl.tencentcloudapi.com" // API 端点 }

仓库内对应的 schema 文件为 schema/v4.1.json，配置文件中带上$schema可在编辑器中获得字段校验与补全。

index4/index6支持多种取值形态（详见 docs/en/config/json.md）：

• false：禁止更新对应 IP 类型的记录；
• 数字（0、1…）：使用第 N 个网卡的 IP；
• "default"：系统默认出站 IP；
• "public"：通过第三方 API 查询公网 IP；
• "url:http..."：通过指定 URL 获取 IP，如"url:http://ip.sb"；
• "regex:xxx"：正则匹配本机网卡配置中的 IP，如"regex:192\\.168\\..*"；
• "cmd:xxx"/"shell:xxx"：执行命令并以输出作为 IP。

写成数组（如示例中的["url:http://api.ipify.org", "public"]）表示按顺序回退：前一条规则失败再尝试下一条。IPv4 与 IPv6 相互独立，某一侧禁用或探测失败不影响另一侧的更新。

通过 extra 参数切换域名类型

edgeoneProvider 支持用extra.teoDomainType参数在「加速域名」与「DNS 记录」两种管理模式间灵活切换：

{ "$schema": "https://ddns.newfuture.cc/schema/v4.1.json", "dns": "edgeone", "id": "your_secret_id", "token": "your_secret_key", "ipv4": ["ddns.newfuture.cc"], "extra": { "teoDomainType": "dns" // 切换为 DNS 记录模式（非加速域名） } }

teoDomainType 参数说明

注意：

• teoDomainType参数不区分大小写（dns、DNS、Dns均有效），源码中通过str(...).lower()归一化后再比较（见 edgeone.py#L56）；
• 取值优先级为：extra参数 > 顶层 options > 默认值acceleration，同样来自 edgeone.py#L56 的extra.get("teoDomainType", self.options.get("teoDomainType", "acceleration"))；
• 管理非加速域名时，更推荐使用专门的 EdgeOne DNS Provider。

关于extra的三种传入方式，可从 config.py 的_collect_extra确认其合并规则：

1. JSON 配置中的嵌套"extra": { ... }对象；
2. JSON 配置中的扁平化extra_xxx前缀键（会覆盖同来源嵌套对象中的同名键）；
3. CLI 的--extra.xxx value参数（CLI 不支持嵌套 extra 对象），解析逻辑见 cli.py#L563-L584。

例如以下两种写法等价：

{ "extra": { "teoDomainType": "dns" } }

{ "extra_teoDomainType": "dns" }

参数说明

参数类型说明：

• 通用配置：适用于所有受支持 DNS Provider 的标准参数；
• 通用网络：适用于所有 Provider 的网络参数；
• Provider：当前 Provider 专属参数。

EdgeOne 的 TTL 实际缓存策略由 EdgeOne 平台侧管理，DDNS 配置中的ttl对加速域名源站更新不产生实际作用。

endpoint 选择：国内版与国际版

EdgeOne 支持国内与国际两套 API 端点，需要根据账号类型选择：

• 国内版（默认，推荐）：https://teo.tencentcloudapi.com
• 国际版：https://teo.intl.tencentcloudapi.com

国内账号使用国内端点，国际账号使用国际端点；不确定时建议使用默认的国内端点。端点默认值定义在 edgeone.py#L19，若配置中提供了endpoint，SimpleProvider.init会用配置值覆盖类属性，因此无需改代码即可切换区域。

底层实现原理

复用腾讯云 TC3-HMAC-SHA256 签名

EdgeOneProvider继承自 TencentCloudProvider，只改写了与 EdgeOne API 对应的四个方法。其类属性如下（edgeone.py#L19-L22）：

endpoint = "https://teo.tencentcloudapi.com" service = "teo" # 签名凭证作用域使用 teo version_date = "2022-09-01" # EdgeOne API 版本

签名流程由父类_request完成（tencentcloud.py#L31-L101）：以TC3 + SecretKey为根密钥，依次按日期、服务名（EdgeOne 为teo）、tc3_request三级 HMAC-SHA256 派生签名密钥；再对规范化请求（方法、路径、查询串、签名头部、请求体哈希）计算签名值，写入authorization头，同时携带X-TC-Action（API 名称）、X-TC-Version（2022-09-01）、X-TC-Timestamp头，以application/json请求体 POST 到端点的根路径。这也解释了为何 EdgeOne 与腾讯云 DNS 的凭证格式相同、但服务标识不同——权限差异就体现在service = "teo"这个维度上。

一次 set_record 的完整调用链

所有 Provider 共享 BaseProvider.set_record 的统一流程：

1. 域名拆分为「子域 + 主域」：优先识别sub~main或sub+main自定义分隔符（见 _split_custom_domain），否则从右向左逐级尝试，用_query_zone_id探测哪一级是已存在的站点主域；
2. 调用子类实现的_query_record查询现有记录；
3. 记录存在则走_update_record，不存在则走_create_record；
4. 任何异常被捕获并记录日志，本次更新返回False而不中断整个同步流程。

针对 EdgeOne 的具体实现：

• 查 ZoneId（edgeone.py#L24-L40）：调用DescribeZones，以zone-name精确过滤主域名，取返回Zones[].ZoneId；查询结果会缓存在实例的_zone_map中，同一主域不会重复查询；
• 查记录（edgeone.py#L42-L84）：
  • dns模式：DescribeDnsRecords，以name过滤并匹配Name与Type；
  • 加速模式：DescribeAccelerationDomains，以domain-name过滤并匹配DomainName；
• 创建记录（edgeone.py#L86-L128）：
  • dns模式调用CreateDnsRecord（传入Name、Type、Content）；
  • 加速模式调用CreateAccelerationDomain，源站信息固定为{"OriginType": "IP_DOMAIN", "Origin": <新IP>}；
  • 两种模式下都会先把teoDomainType从 extra 中剔除（api_extra，见 edgeone.py#L103），防止这个内部开关被误传给云 API；
• 更新记录（edgeone.py#L130-L176）：
  • dns模式调用ModifyDnsRecords，以DnsRecords数组提交新Content；
  • 加速模式调用ModifyAccelerationDomain，其中有一个值得注意的细节：更新时会从旧记录中取出OriginDetail.BackupOrigin并原样带回（edgeone.py#L166-L170），避免刷新源站 IP 时把用户在控制台配置的备源（BackupOrigin）清掉。

对应的单元测试位于 tests/test_provider_edgeone.py，覆盖了关键路径：set_record的创建/更新全流程（断言依次发生DescribeZones→DescribeAccelerationDomains→Create/ModifyAccelerationDomain三次调用，见 test_set_record_create_new）、备源保留（test_update_record_preserve_backup_origin）、test~example.com自定义分隔符格式（test_custom_domain_format），以及认证失败时的错误日志行为。

错误处理

父类_request会在响应含Response.Error时记录TencentCloud API error: <Code> - <Message>并返回None，由上层按「查询失败/更新失败」路径降级处理；HTTP 层面对 400/401/403/5xx 状态码会抛出带中文语义的RuntimeError（如「认证失败 [401]」），调试模式下可见完整请求体与响应。

调试与常见问题

调试模式

开启 debug 日志可获得每一步 API 调用的详细信息（含请求 URL、打码后的请求体与响应）：

ddns -c config.json --debug

CLI 参数定义见 cli.py#L168。

常见问题排查

结合上文源码可知两条典型日志线索：Acceleration domain not found for: ...（debug 级，主域不在 EdgeOne 站点中或拼写不符）与No DNS record found for: ...（warning 级，记录查询为空，随后会走创建流程）。若创建也失败，通常是该站点下不允许 API 侧新建此类型记录，需回到控制台核对站点状态与套餐能力。

参考资源

• 腾讯云 EdgeOne 产品与 API 文档（控制台内可查，产品 ID 1552）；
• 仓库内相关文档：edgeone_dns.md（非加速域名 DNS 记录管理）、tencentcloud.md（腾讯云 DNS，共享同一套 SecretId/SecretKey 认证）、json.md（通用配置参数详解）；
• 相关源码与测试：edgeone.py、edgeone_dns.py、tencentcloud.py、tests/test_provider_edgeone.py。

• 网络
• CLI