密码学与证书 / 系统课时
.well-known 目录到底是什么
.well-known 目录到底是什么
/.well-known/ 经常看起来像一个普通目录,但在 Web 语义里它首先是一个约定好的 URL 路径前缀,用来承载站点级的标准化信息。HTTP-01 只是借用了这个约定,在其下使用 acme-challenge 子路径完成域名控制权验证。
学习目标
- 区分 URL 中的
/.well-known/与服务器文件系统中的真实目录。 - 说明
/.well-known/acme-challenge/在 ACME HTTP-01 中承担的职责。 - 能判断 Web 服务器是否把该路径映射到了正确内容。
.well-known 首先是 URL 命名空间
访问 http://example.com/.well-known/... 时,客户端只知道自己请求了一个 URL。至于服务器最终从磁盘读取文件、由应用动态生成内容,还是转发给另一个服务,完全取决于 Web 服务器的路由配置。
因此,不能看到 URL 里有 .well-known,就认定服务器磁盘上一定存在同名目录。使用 Certbot 的 webroot 方式时通常会创建真实目录;使用独立监听、反向代理或应用路由时,也可以不依赖相同的物理目录结构。
acme-challenge 是 HTTP-01 的专用子路径
ACME HTTP-01 使用 /.well-known/acme-challenge/<TOKEN>。其中 <TOKEN> 是当前挑战的随机标识,服务器需要在这个 URL 上返回与该挑战绑定的 key authorization。证书颁发机构拿到响应后,就能验证申请者是否控制了该域名对应的 HTTP 服务。
可以把三层关系理解为:域名确定站点,/.well-known/ 提供标准化站点级入口,acme-challenge 再把入口限定到 ACME 验证用途。真正变化的是最后的 <TOKEN>,所以验证期间可能不断出现新的临时资源。
文件路径和 URL 路径可以不同
例如 Nginx 可以把 Challenge URL 映射到指定 webroot。下面是片段示例,依赖已有的 server 配置,并假设 Certbot 把文件写入 /var/www/acme/.well-known/acme-challenge/。
location ^~ /.well-known/acme-challenge/ {
root /var/www/acme;
default_type text/plain;
}该配置生效后,请求 /.well-known/acme-challenge/<TOKEN> 会映射到 /var/www/acme/.well-known/acme-challenge/<TOKEN>。这说明 URL 层级与文件系统层级可以恰好一致,但这种一致来自配置,不是 .well-known 这个名字自动产生的。
验证时可在另一台机器上检查实际返回值:
DOMAIN="<DOMAIN>"
TOKEN="<TOKEN>"
curl --fail --silent --show-error "http://${DOMAIN}/.well-known/acme-challenge/${TOKEN}"预期输出
<TOKEN>.<ACCOUNT_THUMBPRINT>实际值会随每次挑战变化。若返回 404,通常说明文件未写到当前站点使用的 webroot,或该路径被其他 location、应用路由、CDN 规则接管;若返回站点首页,则往往存在兜底重写规则,把 Challenge 请求错误地改写到了普通页面。
判断配置时只盯住 URL 结果
排查 .well-known 时,最容易陷入“目录到底在哪”的思路。更有效的判断顺序是先确认外部访问的 URL 是否返回正确内容,再反推 Nginx、Apache、容器挂载或应用路由如何生成这个结果。
对 HTTP-01 来说,证书颁发机构只看公开 URL 的响应,不关心服务器内部是文件、代理还是动态处理。只要 /.well-known/acme-challenge/<TOKEN> 能从公网稳定返回当前挑战对应的 key authorization,这条路径就配置正确。