密码学与证书 / 系统课时

-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/ 本身。

nginx
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 追加到根目录,因此实际读取:

text
/var/www/example/.well-known/acme-challenge/<ID>

所以 Certbot 的 -w 应填写 /var/www/example,而不是 /var/www/example/.well-known/acme-challenge。Certbot 会自己创建并使用后面的 Challenge 子目录。

Webroot 参数与 Nginx root 的路径映射

用探针文件验证映射

正式申请前,先手工创建一个与 Challenge 同路径的文件。把 <HOST> 替换为实际申请证书的域名;域名必须已经解析到这台 Nginx,并且 80 端口能从公网访问。

bash
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"

预期输出:

text
webroot-ok

如果这里拿不到 webroot-ok,先不要运行 Certbot。此时问题仍在 Nginx 路由、站点根目录、DNS、80 端口或上游代理链路中,Certbot 不会替你修复这些映射。

用同一个目录运行 Certbot

探针通过后,再把同一个 WEBROOT 交给 Certbot。-w 与 --webroot-path 等价,后面的 -d 指定需要验证的域名。

bash
DOMAIN="<HOST>"
WEBROOT="/var/www/example"

sudo certbot certonly --webroot -w "${WEBROOT}" -d "${DOMAIN}"

预期结果:

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

判断 -w 的核心只有一句:填 Nginx root 指向的站点根目录,让 Certbot 写出的 .well-known/acme-challenge/<ID> 与 Nginx 对同一 URL 读取的文件完全重合。 如果配置使用的是 alias、反向代理或容器挂载,路径计算方式会变化,应先按实际映射关系验证,再填写 -w。

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

目录与阅读设置

阅读设置

17

记录一个想法

-w 参数到底对应哪个目录

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

登录哪都通