密码学与证书 / 系统课时

Webroot 配错为什么一定验证失败

Webroot 配错为什么一定验证失败

Webroot 模式的 HTTP-01 验证要求三件事严格对齐:Certbot 写入文件的位置、Nginx 对 Challenge URL 的本地映射,以及 ACME 服务实际访问到的文件。只要 -w 指向错误目录,即使 Certbot 成功创建了令牌文件,Nginx 仍会返回 404 或其他内容,验证必然失败。

学习目标

  • 解释错误 Webroot 为什么会导致 HTTP-01 验证失败
  • 用错误目录与正确目录对照定位 404
  • 在重新申请前验证 Certbot 写入路径和 Nginx 返回路径已经一致

失败发生在写入路径与读取路径分离

假设 Nginx 的站点根目录是 /srv/www/site:

nginx
server {
    listen 80;
    server_name example.com;

    root /srv/www/site;

    location ^~ /.well-known/acme-challenge/ {
        try_files $uri =404;
    }
}

这是配置片段示例。此时访问 /.well-known/acme-challenge/<ID>,Nginx 会读取 /srv/www/site/.well-known/acme-challenge/<ID>。

如果却执行 certbot --webroot -w /var/www/site,Certbot 会把令牌写到另一棵目录 /var/www/site/.well-known/acme-challenge/<ID>。写文件本身可以成功,但 ACME 服务请求域名时只经过 Nginx;Nginx 并不会自动去错误目录寻找文件。

Webroot 配错导致 HTTP-01 失败的请求链路

用同一个探针复现错误

下面的命令故意把文件写进错误目录 /var/www/site。把 <HOST> 替换为实际域名;Nginx 仍然使用 /srv/www/site 作为 root。

bash
DOMAIN="<HOST>"
WRONG_WEBROOT="/var/www/site"

sudo mkdir -p "${WRONG_WEBROOT}/.well-known/acme-challenge"
printf 'wrong-root\n' | sudo tee "${WRONG_WEBROOT}/.well-known/acme-challenge/probe" >/dev/null
curl -sS -o /dev/null -w '%{http_code}\n' "http://${DOMAIN}/.well-known/acme-challenge/probe"

预期输出:

text
404

如果站点存在统一重定向、反向代理或自定义错误处理,状态码可能不同,但关键现象不变:响应内容不是刚写入的 Challenge 文件。因此只检查“文件存在”没有意义,必须从域名 URL 反向验证。

改成 Nginx 实际读取的目录

把探针写入 /srv/www/site,让文件位置与 Nginx 的 root 对齐:

bash
DOMAIN="<HOST>"
WEBROOT="/srv/www/site"

sudo mkdir -p "${WEBROOT}/.well-known/acme-challenge"
printf 'correct-root\n' | sudo tee "${WEBROOT}/.well-known/acme-challenge/probe" >/dev/null
curl -sS -o /dev/null -w '%{http_code}\n' "http://${DOMAIN}/.well-known/acme-challenge/probe"

预期输出:

text
200

还应确认响应正文就是探针内容,而不是缓存页或代理返回的固定页面:

bash
curl -fsS "http://<HOST>/.well-known/acme-challenge/probe"

预期输出:

text
correct-root

修复后再重新申请

只有探针通过后,才使用正确目录运行 Certbot:

bash
DOMAIN="<HOST>"
sudo certbot certonly --webroot -w /srv/www/site -d "${DOMAIN}"

预期结果:

text
HTTP-01 验证通过后,Certbot 保存该域名的证书;实际证书路径和到期时间会因环境而不同。

排查 Webroot 失败时,最有效的顺序是:先看 Nginx 的实际 root,再确认 Certbot 写入哪个目录,最后从公网 URL 请求同一个探针文件。只要“写入文件”和“HTTP 请求读到的文件”不是同一个文件,重试 Certbot 不会改变结果。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Webroot 配错为什么一定验证失败

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通