企业官网建设流程全解析

• 网络安全
• 密码学

本篇技术指南以 lego 官方 DNS 提供商文档中的 Vscale 章节为核心，完整讲解如何使用 lego 配合 Vscale Domains API 通过 DNS-01 挑战自动签发（含通配符）证书。读完本文，你将掌握 Vscale 提供商的环境变量配置、_FILE后缀与 dotenv 用法、全部可选参数及默认值，并能结合源码理解其底层实现原理。

概述：lego 中的 Vscale DNS 提供商

Vscale 是 lego 内置的 DNS 提供商之一，提供商代码为vscale，自v2.0.0版本起可用。其配置说明文档位于 docs/content/dns/zz_gen_vscale.md，该文件由 providers/dns/vscale/vscale.toml 自动生成，字段与 TOML 元数据一一对应。

它的适用场景非常明确：当你的域名托管在 Vscale，且希望以纯 DNS 方式（DNS-01 挑战）为域名或*.example.com这类通配符域名签发 Let's Encrypt 证书时，无需在服务器上开放 80/443 端口，只需在 Vscale 控制台生成 API Token 并注入环境变量即可。

快速开始：一条命令签发通配符证书

官方文档给出的最小可用示例如下（docs/content/dns/zz_gen_vscale.md）：

VSCALE_API_TOKEN=xxxxx \ lego run --dns vscale -d '*.example.com' -d example.com

命令解析：

• VSCALE_API_TOKEN：必填的 API Token，在 Vscale 控制台的「Settings → Tokens」页面生成（源码注释见 providers/dns/vscale/vscale.go）；
• --dns vscale：指定使用 Vscale 提供商走 DNS-01 挑战；
• -d '*.example.com' -d example.com：同时为通配符域名和根域名申请证书（ACME 要求通配符域名必须与根域名一并提交）。

凭证配置：VSCALE_API_TOKEN

Vscale 提供商仅需一个凭证环境变量：

从源码看，凭证的加载逻辑位于 providers/dns/vscale/vscale.go：NewDNSProvider()调用env.Get(EnvAPIToken)读取环境变量，若为空则返回错误vscale: some credentials information are missing: VSCALE_API_TOKEN。相关测试用例（providers/dns/vscale/vscale_test.go）也验证了「缺失 API Token 时报错」这一行为。

_FILE后缀：凭证改为引用文件

官方文档特别说明：所有环境变量名都可以加上_FILE后缀，改为引用一个文件路径而不是直接的值（详细说明见 docs/content/dns/_index.md）。例如：

VSCALE_API_TOKEN_FILE=/etc/secrets/vscale-token \ lego run --dns vscale -d '*.example.com' -d example.com

文件内容必须只包含凭证值本身（不能带换行之外的字符）。该机制由platform/env包统一实现：env.Get内部调用GetOrFile（platform/env/env.go），会先读取普通变量，若为空则自动尝试对应的_FILE变量。

dotenv 文件：批量管理配置

此外还可使用 dotenv 文件集中管理环境变量。使用lego run时通过--env-file指定：

lego run --dns vscale -d '*.example.com' -d example.com --env-file .env.vscale

.env.vscale内容示例：

VSCALE_API_TOKEN=your-token-here

附加配置参数与默认值

除凭证外，Vscale 提供商还支持 4 个可选环境变量（官方文档表格，docs/content/dns/zz_gen_vscale.md）：

这些默认值可以在源码的NewDefaultConfig()中得到印证（providers/dns/vscale/vscale.go）：

func NewDefaultConfig() *Config { return &Config{ TTL: env.GetOrDefaultInt(EnvTTL, selectel.MinTTL), PropagationTimeout: env.GetOrDefaultSecond(EnvPropagationTimeout, 120*time.Second), PollingInterval: env.GetOrDefaultSecond(EnvPollingInterval, dns01.DefaultPollingInterval), HTTPClient: &http.Client{ Timeout: env.GetOrDefaultSecond(EnvHTTPTimeout, 30*time.Second), }, } }

几个值得注意的细节：

• VSCALE_TTL的默认值并非写死的 60，而是引用了共享常量selectel.MinTTL = 60（providers/dns/internal/selectel/provider.go），且该值同时是 TTL 的下限——低于 60 会被直接拒绝；
• VSCALE_POLLING_INTERVAL默认值 2 秒来自dns01.DefaultPollingInterval（challenge/dns01/dns_challenge.go）；
• 这些变量同样支持_FILE后缀，加载逻辑与凭证一致，底层均为env.GetOrDefaultInt/env.GetOrDefaultSecond（platform/env/env.go）。

源码级实现：Vscale 提供商的工作原理

配置结构与 TTL 校验

vscale包的类型Config是共享包selectel.Config的类型别名（providers/dns/vscale/vscale.go），包含Token、PropagationTimeout、PollingInterval、TTL、HTTPClient五个字段（providers/dns/internal/selectel/provider.go）。

NewDNSProviderConfig(config)会执行两项硬校验（providers/dns/internal/selectel/provider.go）：

1. config.Token为空 → 报错credentials missing；
2. config.TTL < 60→ 报错invalid TTL, TTL (59) must be greater than 60。

测试用例TestNewDNSProviderConfig对「missing api key」和「bad TTL value（ttl=59）」两种失败场景都有断言（providers/dns/vscale/vscale_test.go）。

API 端点与认证方式

Vscale 的默认 API 基址为https://api.vscale.io/v1/domains（providers/dns/vscale/vscale.go），HTTP 客户端在每次请求的请求头中注入X-Token: <token>完成认证（providers/dns/internal/selectel/internal/client.go）。

核心调用链如下（对应 Vscale Domains API 的Domains Records资源）：

Present / CleanUp 生命周期

DNSProvider实现了challenge.ProviderTimeout接口（providers/dns/vscale/vscale.go），三个核心方法的语义如下：

• Present：通过dns01.GetChallengeInfo计算挑战 FQDN 与 TXT 值，先GetDomainByName拿到域名对象 ID，再以Type=TXT、TTL=config.TTL、Name=EffectiveFQDN、Content=Value调用AddRecord写入记录（providers/dns/internal/selectel/provider.go）；
• CleanUp：对EffectiveFQDN执行dns01.UnFqdn去掉尾部点得到记录名，列出该域下所有记录，逐一删除名称匹配的记录（providers/dns/internal/selectel/provider.go）；
• Timeout：直接返回配置中的PropagationTimeout与PollingInterval，供 lego 在验证前等待 DNS 传播（providers/dns/vscale/vscale.go）。

另外，GetDomainByName具备递归降级能力：当查询的域名层级大于 2 且返回 404 时，会去掉最左侧子域重新查找，直至找到账号下实际存在的父域（client.go）。从源码结构看，这一设计是为了兼容子域名记录挂在父域下的场景。

请求与错误处理

内部客户端统一走do()方法：注入X-Token头、发送请求、将非 2xx 响应解析为APIError（含code、error、field字段）后包装返回（client.go、types.go）。此外 HTTP 客户端还会被clientdebug.Wrap包装，便于开启调试日志排查问题（provider.go）。

验证与测试

仓库为 Vscale 提供商提供了完整的单元测试与实时测试（providers/dns/vscale/vscale_test.go）：

• TestNewDNSProvider：覆盖「成功初始化」与「缺少VSCALE_API_TOKEN时报错」两条路径；
• TestNewDNSProviderConfig：覆盖 token 为空、TTL 低于 60 两种非法配置；
• TestLivePresent/TestLiveCleanUp：真实的挑战记录创建与清理测试，仅在设置了 live 测试环境时运行（默认跳过）。

如果你在配置过程中遇到「credentials information are missing」错误，优先检查VSCALE_API_TOKEN是否设置或_FILE指向的文件内容是否为空；若收到 TTL 相关报错，请确认VSCALE_TTL不小于 60 秒。

小结

Vscale 是 lego 中接入成本较低的 DNS 提供商之一：只需一个 API Token，配合lego run --dns vscale即可完成通配符证书的签发与自动续期。其实现复用了 selectel 共享内核，通过X-Token认证与「查域名 → 增删 TXT 记录」的标准流程工作，全部参数（TTL、传播超时、轮询间隔、HTTP 超时）均可用环境变量覆盖且默认值明确。更多 provider 配置通用约定（如_FILE后缀与 dotenv）可参考 docs/content/dns/_index.md，完整参数元数据则维护在 providers/dns/vscale/vscale.toml。

• 网络安全
• 密码学