密码学与证书 / 系统课时
-w 参数到底对应哪个目录
-w 参数到底对应哪个目录
certbot --webroot -w 最容易出错的地方不是参数语法,而是把 URL 路径误当成文件系统路径。本篇用 Nginx 的 root 规则确定 -w 应填写的目录,并用探针文件验证外网请求是否真的能读到 Certbot 写入的位置。
学习目标
- 根据 Nginx 的
root配置推导正确的 Webroot 文件系统目录 - 理解 Certbot 写入 Challenge 文件后,URL 与本地路径如何对应
- 在申请证书前用
curl验证目录映射是否正确
先从 Nginx 的 root 找目录
假设站点配置的关键部分如下。这里的 root /var/www/example; 才是判断 -w 的起点,而不是域名、Nginx 配置文件所在目录,也不是 /.well-known/acme-challenge/ 本身。
server {
listen 80;
server_name example.com;
root /var/www/example;
location ^~ /.well-known/acme-challenge/ {
try_files $uri =404;
}
}这是配置片段示例,需要放在有效的 server 块中并通过 nginx -t 后再加载。对请求 http://example.com/.well-known/acme-challenge/<ID>,使用 root 时 Nginx 会把请求 URI 追加到根目录,因此实际读取:
/var/www/example/.well-known/acme-challenge/<ID>所以 Certbot 的 -w 应填写 /var/www/example,而不是 /var/www/example/.well-known/acme-challenge。Certbot 会自己创建并使用后面的 Challenge 子目录。

用探针文件验证映射
正式申请前,先手工创建一个与 Challenge 同路径的文件。把 <HOST> 替换为实际申请证书的域名;域名必须已经解析到这台 Nginx,并且 80 端口能从公网访问。
DOMAIN="<HOST>"
WEBROOT="/var/www/example"
sudo mkdir -p "${WEBROOT}/.well-known/acme-challenge"
printf 'webroot-ok\n' | sudo tee "${WEBROOT}/.well-known/acme-challenge/probe" >/dev/null
curl -fsS "http://${DOMAIN}/.well-known/acme-challenge/probe"预期输出:
webroot-ok如果这里拿不到 webroot-ok,先不要运行 Certbot。此时问题仍在 Nginx 路由、站点根目录、DNS、80 端口或上游代理链路中,Certbot 不会替你修复这些映射。
用同一个目录运行 Certbot
探针通过后,再把同一个 WEBROOT 交给 Certbot。-w 与 --webroot-path 等价,后面的 -d 指定需要验证的域名。
DOMAIN="<HOST>"
WEBROOT="/var/www/example"
sudo certbot certonly --webroot -w "${WEBROOT}" -d "${DOMAIN}"预期结果:
HTTP-01 验证通过后,Certbot 为该域名保存证书;证书编号、路径和到期时间会因环境而不同。判断 -w 的核心只有一句:填 Nginx root 指向的站点根目录,让 Certbot 写出的 .well-known/acme-challenge/<ID> 与 Nginx 对同一 URL 读取的文件完全重合。 如果配置使用的是 alias、反向代理或容器挂载,路径计算方式会变化,应先按实际映射关系验证,再填写 -w。