密码学与证书 / 系统课时
Webroot 配错为什么一定验证失败
Webroot 配错为什么一定验证失败
Webroot 模式的 HTTP-01 验证要求三件事严格对齐:Certbot 写入文件的位置、Nginx 对 Challenge URL 的本地映射,以及 ACME 服务实际访问到的文件。只要 -w 指向错误目录,即使 Certbot 成功创建了令牌文件,Nginx 仍会返回 404 或其他内容,验证必然失败。
学习目标
- 解释错误 Webroot 为什么会导致 HTTP-01 验证失败
- 用错误目录与正确目录对照定位 404
- 在重新申请前验证 Certbot 写入路径和 Nginx 返回路径已经一致
失败发生在写入路径与读取路径分离
假设 Nginx 的站点根目录是 /srv/www/site:
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 并不会自动去错误目录寻找文件。

用同一个探针复现错误
下面的命令故意把文件写进错误目录 /var/www/site。把 <HOST> 替换为实际域名;Nginx 仍然使用 /srv/www/site 作为 root。
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"预期输出:
404如果站点存在统一重定向、反向代理或自定义错误处理,状态码可能不同,但关键现象不变:响应内容不是刚写入的 Challenge 文件。因此只检查“文件存在”没有意义,必须从域名 URL 反向验证。
改成 Nginx 实际读取的目录
把探针写入 /srv/www/site,让文件位置与 Nginx 的 root 对齐:
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"预期输出:
200还应确认响应正文就是探针内容,而不是缓存页或代理返回的固定页面:
curl -fsS "http://<HOST>/.well-known/acme-challenge/probe"预期输出:
correct-root修复后再重新申请
只有探针通过后,才使用正确目录运行 Certbot:
DOMAIN="<HOST>"
sudo certbot certonly --webroot -w /srv/www/site -d "${DOMAIN}"预期结果:
HTTP-01 验证通过后,Certbot 保存该域名的证书;实际证书路径和到期时间会因环境而不同。排查 Webroot 失败时,最有效的顺序是:先看 Nginx 的实际 root,再确认 Certbot 写入哪个目录,最后从公网 URL 请求同一个探针文件。只要“写入文件”和“HTTP 请求读到的文件”不是同一个文件,重试 Certbot 不会改变结果。