密码学与证书 / 系统课时
Webroot 模式适合什么场景
Webroot 模式适合什么场景
Webroot 模式适合已经由 Nginx 稳定提供 HTTP 服务、又不希望 Certbot 自动改动站点配置的场景。它把“证明域名归你控制”和“如何配置 HTTPS”拆开:Certbot 只写验证文件,Nginx 继续负责对外响应请求。
学习目标
- 说清 Webroot 模式中 Certbot、Nginx 与 ACME 验证服务器各自的职责
- 判断现有站点是否满足 Webroot 的使用条件
- 在申请证书前验证
/.well-known/acme-challenge/是否能从公网访问
Webroot 把验证交给现有 Web 服务器
使用 HTTP-01 验证时,Certbot 会在指定 Webroot 下创建 /.well-known/acme-challenge/ 目录中的临时验证文件。证书机构随后访问目标域名对应的 HTTP URL;请求仍由正在运行的 Nginx 接收,并从同一个 Webroot 返回文件内容。

这与 Standalone 模式的关键差异是:Webroot 不需要 Certbot 临时监听 80 端口,因此通常无需停止现有 Nginx。它也不同于 Nginx 插件模式:certonly --webroot 只负责获取或续订证书,不负责把证书路径写进站点配置。
什么时候适合使用
如果站点必须持续在线、你能控制 Nginx 配置,并且已经知道域名实际对应的 Webroot,Webroot 往往很合适。它尤其适用于配置由版本库或运维系统统一管理、不希望自动工具直接改写 Nginx 文件的环境。
使用前应同时满足几个条件:域名已经解析到当前服务器或能够把验证请求转发到它;公网能够通过 HTTP 访问该域名;Nginx 会把 /.well-known/acme-challenge/ 映射到 Certbot 写入的目录,而且这条路径不会被登录鉴权、错误的反向代理、SPA 回退或重写规则替换成其他内容。
如果需要申请通配符证书,HTTP-01 的 Webroot 模式并不适用,应改用支持 DNS-01 的方式。如果服务器没有现成 Web 服务且可以让 Certbot 占用 80 端口,Standalone 通常更直接。
申请前先验证目录映射
不要只根据 Nginx 配置中的目录名猜测 Webroot。最稳妥的方法是先放一个临时文件,再从站点 URL 读取它。执行前把 <PATH> 替换为 Nginx 实际服务目录,把 <HOST> 替换为待验证域名。
WEBROOT="<PATH>"
DOMAIN="<HOST>"
TOKEN="anystack-webroot-check"
sudo mkdir -p "$WEBROOT/.well-known/acme-challenge"
printf 'webroot-ok\n' | sudo tee "$WEBROOT/.well-known/acme-challenge/$TOKEN" >/dev/null
curl --fail --silent --show-error "http://$DOMAIN/.well-known/acme-challenge/$TOKEN"
sudo rm -f "$WEBROOT/.well-known/acme-challenge/$TOKEN"预期输出
webroot-ok如果 curl 返回 404、403、登录页或业务页面,不要继续申请证书。应先检查该域名对应的 server 块、root 或 alias 映射、反向代理与重写规则,以及公网到 80 端口的访问链路。只有测试文件能通过目标 URL 被正确取回,Certbot 写入的挑战文件才有机会被证书机构读到。
Webroot 最重要的职责边界
Webroot 的价值不在于“自动配置 HTTPS”,而在于让证书验证复用现有 Web 服务。你仍然负责 Nginx 的 TLS 配置、证书路径、配置测试和重载;Certbot 负责申请、保存证书,并在后续续期时再次把挑战文件写入已记录的 Webroot。只要这条 HTTP 验证路径长期保持可达,自动续期就不需要为了抢占端口而停站。