概述

Certbot 是一个 ACME 客户端。它可比如以申请，还有部署，再有续约和撤销 HTTPS 证书。

Certbot 通常用于申请 Let's Encrypt 证书。它支持以下验证方式:

• standalone
• webroot
• Nginx 插件
• Apache 插件
• DNS 插件
• 手动 DNS 验证

这篇文章以 Debian 程序为例，介绍 Certbot 的安装、申请、续约和自动化管理方法。

前置条件

开始申请证书前，需要确认以下条件:

• 域名的 A 记录已指向服务器的公网 IPv4 地址。
• 域名存在 AAAA 记录时该记录必须指向正确的 IPv6 地址。说起来，
• HTTP 验证需要外部网络访问服务器的 TCP 80 和 TCP 443 端口。
• 防火墙和云服务安全组必须允许 TCP 80 与 TCP 443。
• 当前使用者必须拥有 sudo 权限。

可以使用以下命令检查 DNS 解析:

dig +short A example.com
dig +short AAAA example.com

安装 Certbot

安装基础组件

痛点一：软件源不更新导致安装失败或版本过旧。

更新 Debian 软件包索引:

sudo apt update

sudo apt install certbot

再看检查安装结果，

certbot --version

输出会包含当前安装的 Certbot 版本。

安装 Web 服务插件

痛点二：忘记同时安装对应的 web 插件，导致后续自动配置失败。

• Nginx 时：

sudo apt install python3-certbot-nginx

• Apache 时：

sudo apt install python3-certbot-apache
**查看已装插件**
 sudo certbot plugins


申请 HTTPS 证书

使用 standalone 模式
`standalone` 模式会启动一个临时 HTTP 服务。该服务默认监听 **TCP port 80**。不过，**单域名**
 sudo certbot certonly \
--standalone \
-d example.com
**多域名**
 sudo certbot certonly \
--standalone \
-d example.com \
-d www.example.com
该模式不会修改 Nginx 或 Apache 配置。申请成功后需要手动配置 Web 服务。在使用此模式前，请先确认 **TCP port 80/443 已空闲**：
 sudo ss -ltnp | grep ':'
如果 Nginx、Apache 或 Docker 容器占用该端口。将导致 `Could not bind` 错误。

使用 webroot 模式
`webroot` 模式文件，不需要停止 Nginx 或 Apache。外部网络必须能访问 `/.well-known/acme-challenge/` 方法。指定网站根目录并申请证书：
 sudo certbot certonly \
--webroot \
-w /var/www/html \
-d example.com
如果您正在使用 Docker Compose。请确保容器映射了对应方法，否则验证文件将无法访问。

使用 Nginx 插件
Nginx 插件可一键申请并自动修改 Nginx 配置。先确保已装插件，接下来执行：
 sudo certbot --nginx \
-d example.com \
-d www.example.com
请务必在运行前检查 Nginx 配置无误；若出现语法错误，Certbot 会提示 `nginx: …` 并中止操作，

申请通配符证书
通配符证书只能获得。不过，手动 DNS 验证虽可行，但不适合无人值守续约；其实，建议结合 Cloudflare 等支持 API 的 DNS 提供商。
 sudo certbot certonly \
--manual \
--preferred-challenges dns \
-d example.com \
-d '*.example.com'
在执行前请先准备好能创建 TXT 记录的权限。并记得在完成后手动删除临时 TXT，以免影响后续请求。

配置与验证证书

配置 Nginx
Certbot 默认将证书保存在 `/etc/letsencrypt/live/example.com/`。按理说，示例完整 HTTPS 配置：
 server {
listen ssl;listen :ssl，server_name example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;root /var/www/html;

}


检查语法并重载：

html
 sudo nginx -t && sudo systemctl reload nginx


避免把 privkey.pem 加入 Git 仓库或给非管理员读取权限——这属于最常被忽略的安全风险。

验证证书

查看主题、签发机构与有效期：

html
 sudo openssl x509 \
-in /etc/letsencrypt/live/example.com/cert.pem \
-noout -subject -issuer -dates


测试 HTTPS 是否工作：

html
 curl -I https://example.com


若返回 HTTP/1.1 200 OK 并含 Strict-Transport-Security,则表示 SSL 已生效。

查看证书状态

列出所有 Certbot 管理的证书

html
 sudo certbot certificates


至于示例输出。

text
Certificate Name: example.com
Domains: example.com www.example.com
Expiry Date: -- ::+
Certificate Path: /etc/letsencrypt/live/example.com/fullchain.pem
Private Key Path: /etc/letsencrypt/live/example.com/privkey.pem


其中 Certificate Name' 是内部标识，用于续约或撤销时指定。

查看目录结构



方法
用途




/etc/letsencrypt/live/
当前有效软链接


/etc/letsencrypt/archive/
历史版本


/etc/letsencrypt/renewal/
每个 certificate 的 renew config


`/etc/letsencrypt/renewal-hooks/pre/deploy/post/'
自动脚本 Hook


`/var/log/letsencrypt/'
日志文件




Web 服务应引用 /etc/letsencrypt/live//fullchain.pem & privkey.pem'；请勿直接
live 或 archive 内容。不过，


续约流程

测试续约

先用测试环境模拟一次 renew。确认无错误：

成功时会看到 Congratulations,all simulated renewals succeeded. 

如果出现 Could not bind ...,检查是否有进程占用 port 80 或 port 443。


正式执行

只要有任意一张证书剩余有效期少于三分之一。即触发 renew：

你可以随时执行，多次调用也不会产生负担。

强制续约

仅针对特定名称强制 renew。例如私钥泄露后立即更换：

html
sudo certbot renew --cert-name example.com --force-renewal


注意频繁强制可能触发 Let's Encrypt 的速率限制，请谨慎使用。

重配参数

如果你想改用不同 webroot 方法或开启某些插件。可重新配置:

html
sudo certbot reconfigure --cert-name example.com \
--webroot-path /srv/www/example.net

CertBot 会先在测试环境下验证新配置，再应用到正式周期。


Hook 使用技巧

Hooks 能在不同阶段执行自定义脚本，解决诸如 Docker Compose 占用端口等痛点。不过，

***注***：不同目录内文件排序只影响同一类 Hook 执行顺序；如 `/deploy-hooks/' 中按字节排序决定先后顺序，而不影响 `/pre-hooks/' 与 `/post-hooks/' 的关系。老实说，

Standalone + Docker Compose 示例
再看创建停止脚本，

\`\`\`
sudo nano /etc/letsencrypt/.../-stop-nginx.sh
set -eu
/usr/bin/docker compose \
-f /srv/web/docker-compose.yaml stop nginx
chmod +x ...
\`\`\`
至于创建恢复脚本。\`\`\`
sudo nano .../-start-nginx.sh
set -eu
/usr/bin/docker compose \
-f /srv/web/docker-compose.yaml start nginx
chmod +x ...
\`\`\`
授予权限并检查：
\`\`\`
sudo chmod +x /etc/...{-stop,-start}-nginx.sh
ls -l /etc/.../{pre,deploy,post}/-*nginx*.sh
\`\`\`
随后每次 renewal 前就会自动停机，再恢复；避免因端口冲突导致 renewal fail。

Deploy-Hook 示例
当成功签发或续订后可自动 reload Nginx:
\`\`\`
sudo cat>> ~/.config/autoscript/deploy-hook < 'EOF'
systemctl reload nginx>/dev/null || true # 防止因其他原因失败而中断全流程。EOF
chmod +x ~/.config/autoscript/deploy-hook
\`\`\`
或者直接在命令行添加：
\`\`\`
sudo certbot renew --deploy-hook "systemctl reload nginx"
\`\`\`.


*管理自动续约 *
程序默认创建 `certbot.timer`.
检查状态：
\
获取下次触发时间：
\
启用并立即启动：
\
正常运行时显示:
\.
程序 timer 本身是一次性任务。在完成后变为 inactive，这属于正常行为。

日志查看
获取最近一次 run 的日志:
\\\]
获取全量日志的观点是，\\\]
实时跟踪 log:
\\\]


撤销与删除
当私钥泄露或不再需要某域名时请及时撤销并删除以免被滥用。

撤销
按名称撤销:
\
按文件方法撤销：
`${\。{\displaystyle {\texttt{certboot revoke }}~-}{-\mathrm{path}~/.../\dots}}
.\)
若泄露原因需明确，可加 reason 参数，例如 keycompromise。撤销后即使保留 renewal config，CertBot 有可能
尝试。如果不再需要，请同步删除 config 文件。

删除
先确认 name:
`${\。{\displaystyle {\texttt{certboot certificates}}}}
.\)
接下来移除引用方法，再删掉：
`${\,{\displaystyle {${ ‘${…‘}$ $] }}`
不要直接删掉 `/var/lib/etc/lts/...`;那样可能导致数据损坏，


常见问题 & 痛点汇总


Hook 类型与执行时间表格说明


Name Prefix Order 
Description 
Addiction Example 

-stop-nginx.sh 
"stop nginx before renewal"
     ... 

-start-nginx.sh 
"restart after renewal"
     ... 
















痛点
场景
快速排查 & 对策




TCP port 已被占用
standalone 模式时报错 "Could not bind..."
查看占用进程 并停止相关服务或切换到 webroot/Nginx plugin


Docker Compose 占位冲突
同步容器监听了端口，但未关闭导致 Renewal fail
在 Hook 中停止容器 后再继续 renewal；或者改为 webroot mode


域名解析错误
Let’s Encrypt 无法访问正确 IP 导致验证失败
检查 A 与 AAAA 并修正或删除错误记录


HTTP 重定向阻止 /.well-known/acme-challenge/*?path 无法访问 */?path/http请求 /?path/ .well-known/acme-challenge/test 返回空白 or redirect 循环
检查 NGINX root alias try_files 配置，还有是否开启了 HSTS 或 HTTP -> HTTPS 强制跳转


手工 DNS 验收不适用于无人值守环境
若需通配符但没有 API 支持。仅手工失效升级难度大
推荐集成 Cloudflare/DigitalOcean 等支持 API 的提供商，用 Auto‑DNS plugin 替代 manual 方法


hook 脚本权限不足或方法错误导致 Hook 未执行
script 权限不是755，docker compose 方法未绝对化等造成失效
确认 chmod +x 并使用绝对方法；话说回来，在 dry-run 时加入 --run-deploy-hooks 来测试 deploy-hook 是否生效





小结


Debian 可通过 APT 安装 CertBot 与相应 Web 插件；请同步更新软件源以防止版本过旧。

如果已有正在运行的 NGINX/Affice。只需选择插件或 webroot mode，无需停机。

standalone mode 对没有任何 Web 服务的新服务器最友好，但须保证端口空闲且无其它进程占用。

当 Docker Compose 占用关键端口时务必利用 Hook 停止容器。并记得使用绝对方法，否则程序定时任务很容易因冲突失效。老实说，

Hook 脚本一定要以 .sh 后缀、数字前缀控制顺序。并赋予可执行权限，否则它们永远不会被调用。

定期跑 sudo certboot renew --dry-run 来确保整个链条—从验证到部署—都能顺畅工作，这是保证持续 HTTPS 的关键步骤。

一旦发现私钥泄漏立即撤销。接下来删除对应配置文件，以消除潜在风险。其实，



版权声明：
这篇文章为原创内容。作者保留版权，如转载，请保留原文完整内容，并以超链接形式注明作者及出处。本篇文章来源于 blog.mazey.net/.