密码学与证书 / 知识点
Certbot 常用命令与参数速查
基础查询
certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...Certbot 命令由子命令、全局选项和域名参数组成;不确定具体操作时,可先从这个结构判断需要使用申请、续期还是管理类子命令。
Certbot 通用命令结构
用这条结构先判断“要做什么”,再补对应选项和域名。SUBCOMMAND 决定操作类型,options 控制验证方式、插件或运行行为,-d 用于声明证书应覆盖的域名;同一张证书包含多个域名时可重复使用 -d。
基本语法
certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...这是一条 synopsis,不应把方括号或 DOMAIN 原样输入。方括号表示该部分按场景选择,末尾省略号表示 -d DOMAIN 可以重复出现。
子命令与参数怎么组合
常见操作可按目的区分:申请但不自动安装证书时使用 certonly,检查并续期已管理证书时使用 renew,查看现有证书时使用 certificates,撤销或删除证书则分别进入对应的管理子命令。不同子命令接受的选项并不完全相同,应以当前安装版本的帮助信息为准。
-d DOMAIN 是可重复参数。例如一张证书同时覆盖主域名与 www 域名时,需要分别提供两个 -d。域名必须是实际希望写入证书的名称,不能把 URL、协议前缀或路径放进去。
安全主示例
先用只读的证书列表命令确认当前 Certbot 管理了哪些证书,再决定是否执行申请、续期或删除操作。
certbot certificates预期输出:如果本机存在由 Certbot 管理的证书,会显示证书名称、所含域名和有效期等信息;具体文本随版本和证书状态变化,结构类似:
Found the following certs:
Certificate Name: <CERT_NAME>
Domains: <DOMAIN_LIST>
Expiry Date: <TIME>如果当前没有可列出的证书,命令会给出相应提示,而不会新建或修改证书。
风险与边界
通用结构本身不代表命令一定安全:申请、安装、撤销和删除类操作可能触发 ACME 请求、修改 Web 服务器配置或改变本地证书状态。执行前先确认子命令、域名和插件选择,尤其不要把生产域名直接套入来源不明的示例。只想确认语法时优先查看帮助;要测试续期链路时使用该子命令提供的测试机制,而不是反复发起真实签发请求。
certbot --help查看当前安装版本支持的子命令和常用参数;服务器上的 Certbot 版本与网上示例不一致时,应优先以本机帮助信息为准。
查看 Certbot 命令帮助
当服务器上的 Certbot 版本、安装方式或可用插件与网上示例不一致时,先读取本机帮助。certbot --help 是只读操作,用来确认当前可用的命令结构、子命令和常用选项,不会申请、续期或删除证书。
基本语法
certbot --help预期输出:帮助文本会列出通用命令格式,并继续展示当前版本支持的子命令和选项。不同版本的具体段落可能不同,开头结构通常可据此识别:
certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...
<当前安装版本支持的子命令与选项说明>怎么读帮助信息
先看 synopsis,确认域名参数和选项的写法;再根据目标寻找申请、续期或证书管理相关子命令。准备复制网上命令前,重点核对其中使用的选项是否出现在本机帮助中,避免把旧版本、其他安装渠道或未安装插件的参数直接套用。
帮助输出只说明 CLI 接受什么参数,并不能替代实际环境检查。例如某个验证插件的选项存在,不代表插件已正确配置,也不代表 DNS、端口、权限或 Web 服务器条件已经满足。
常见失败与处理
如果 shell 直接提示找不到 certbot,问题发生在命令解析阶段,而不是证书或 ACME 流程;应先确认 Certbot 是否已安装,以及当前用户的 PATH 是否能找到对应可执行文件。如果帮助可以打开但网上示例中的某个选项不存在,应以本机版本为准,不要强行照抄。
certbot --version输出当前 Certbot 版本,适合排查参数不存在、插件兼容性和不同服务器行为差异,也便于升级前后确认实际生效版本。
查看 Certbot 版本
当参数在某台服务器上不可用、插件行为与预期不同,或刚完成 Certbot 升级时,先确认当前 Shell 实际调用的版本。该命令只输出版本并退出,不会申请、续期或修改证书。
基本语法
certbot --version--version 显示当前执行的 Certbot 程序版本,然后立即退出,不需要域名或其他子命令。
常用示例
certbot --version预期输出:版本号取决于当前环境,实际值可能不同。
certbot <VERSION>可把升级前后的结果直接对照;排查插件兼容问题时,也应记录这一版本,因为不同 Certbot 版本支持的参数和插件版本范围可能不同。
风险与边界
该命令本身是只读操作。若机器上同时存在系统包、Snap、虚拟环境等多套 Certbot,输出只代表当前 Shell 解析到的那个可执行程序;排查定时续期或自动化任务时,应确认它们使用的是同一安装来源和执行入口。
certbot plugins [options]列出当前环境可用的认证器和安装器插件;执行 --nginx、--apache 或 DNS 自动验证前,可先确认对应插件是否已经安装。
查看已安装插件
在使用 Nginx、Apache 或 DNS 自动验证前,可先列出当前 Certbot 能发现的插件。这样能区分“插件未安装或未被加载”和“插件已经存在但后续配置错误”两类问题。
基本语法
certbot plugins [options]不带选项时会列出当前环境发现的插件及其能力。认证器负责完成域名所有权验证,安装器负责把已取得的证书部署到受支持的服务器配置中;一个插件也可能同时具备两种能力。
关键选项
| 选项 | 作用 |
|---|---|
--authenticators |
只显示可作为认证器使用的插件 |
--installers |
只显示可作为安装器使用的插件 |
--init |
初始化插件后显示状态,适合进一步诊断插件加载问题 |
--prepare |
初始化并准备插件,可用于检查插件能否在当前环境完成准备阶段 |
仅确认插件是否安装时,优先使用不带选项的 certbot plugins,通常不需要 --init 或 --prepare。
常用示例
certbot plugins预期输出:终端列出当前 Certbot 发现的插件;名称、数量和描述随安装方式及环境不同。
<PLUGIN_LIST>如果准备执行 certbot --nginx、certbot --apache 或某个 DNS 插件参数,应先确认对应插件出现在列表中,并检查它是否包含所需的 Authenticator 或 Installer 能力。
风险与排查
普通 certbot plugins 主要用于查看插件,不会申请或续期证书。若已安装的插件没有出现,常见原因是插件与 Certbot 安装在不同 Python、系统包或 Snap 环境中;应先确认 Certbot 与插件来自同一安装体系,再继续排查证书命令。
证书申请与安装
certbot run --nginx [options] [-d DOMAIN] [-d DOMAIN] ...使用 Nginx 插件完成域名验证、证书签发和站点 HTTPS 配置;适合 Certbot 能正确识别现有 server 配置的常规部署。
Nginx 申请并安装证书
certbot run --nginx 使用 Nginx 插件完成域名验证、证书签发和 HTTPS 配置安装。省略 run 时,certbot --nginx 也会进入默认的申请并安装流程,适合 Certbot 能正确识别现有 server_name 的常规站点。
使用前提
执行前应确认域名已经解析到当前服务器,Nginx 正常运行且配置能够通过语法检查。HTTP-01 验证通常还要求公网能够通过 80 端口访问目标域名。
Nginx 插件必须已经安装并能被 Certbot 发现。复杂的反向代理、动态生成配置或无法准确匹配 server_name 的环境,应先备份配置再操作。
基本语法
sudo certbot run --nginx -d example.com -d www.example.com--nginx:使用 Nginx 插件完成验证,并把签发后的证书安装到匹配的站点配置。-d DOMAIN:指定证书包含的域名;需要多个域名时重复使用。--redirect:安装证书时配置 HTTP 到 HTTPS 的重定向。--no-redirect:安装证书但不添加 HTTP 到 HTTPS 的重定向。
常用示例
下面显式指定两个域名,并在签发后检查 Nginx 配置和 Certbot 管理的证书。实际域名应替换为自己的域名。
sudo certbot run --nginx -d example.com -d www.example.com
sudo nginx -t
sudo certbot certificates预期结果:证书申请成功后,Certbot 将证书部署到匹配的 Nginx 站点;随后 Nginx 配置检查成功,证书列表能够看到这两个域名。证书名称和文件路径可能因现有证书记录而不同。
Nginx configuration test: successful
Certificate Name: example.com
Domains: example.com www.example.com
Certificate Path: <PATH>/fullchain.pem
Private Key Path: <PATH>/privkey.pem风险与恢复
该模式会修改 Nginx 配置并使新配置生效,因此不要在无法确认站点匹配关系时直接用于复杂生产配置。执行前可先备份 Nginx 配置;如果 Certbot 的最近一次 Nginx 修改需要撤销,可使用 certbot --nginx rollback 回退其配置检查点。
通配符域名不能依靠 HTTP-01 的 Nginx 验证流程签发,应改用支持 DNS-01 的验证方式。签发完成后还应确认外部 HTTPS 请求能够访问正确站点,而不只是检查证书文件是否存在。
certbot certonly --nginx [options] [-d DOMAIN] [-d DOMAIN] ...使用 Nginx 完成域名验证但不自动修改 HTTPS 配置;适合希望自行配置 ssl_certificate、反向代理或复杂多站点环境。
Nginx 只申请证书
certbot certonly --nginx 使用 Nginx 插件完成域名控制权验证并取得证书,但不把证书自动安装到 Nginx 的 HTTPS 配置中。它适合需要自行控制 ssl_certificate、反向代理结构或多站点配置的环境。
使用前提
域名应已经解析到当前服务器,Nginx 配置需要能够被 Certbot 正确解析并通过语法检查。使用 HTTP-01 验证时,还要保证验证请求能够从公网到达目标域名的 80 端口。
此命令只负责取得或更新证书,不等于站点已经启用 HTTPS。签发完成后仍需由管理员把证书路径配置到正确的 Nginx server 中,并重新加载 Nginx。
基本语法
sudo certbot certonly --nginx -d example.com -d www.example.comcertonly:只取得或更新证书,不调用安装器修改 HTTPS 站点配置。--nginx:使用 Nginx 插件完成域名验证。-d DOMAIN:指定证书包含的域名;多个域名可重复指定。--cert-name NAME:需要明确控制 Certbot 证书 lineage 名称时指定,避免在自动化脚本里依赖推断名称。
常用示例
下面为两个域名申请同一张证书,并用 Certbot 自身的证书列表确认保存位置。实际证书路径由 Certbot 管理,不应在申请前凭空假定。
sudo certbot certonly --nginx -d example.com -d www.example.com
sudo certbot certificates预期结果:第一条命令完成域名验证并保存证书,但不会自动为 Nginx 增加 HTTPS 监听配置;第二条命令能够列出证书覆盖的域名以及证书链和私钥路径。
Certificate Name: example.com
Domains: example.com www.example.com
Certificate Path: <PATH>/fullchain.pem
Private Key Path: <PATH>/privkey.pem安装与验证
取得证书后,应把 certbot certificates 显示的证书链路径配置给 Nginx 的 ssl_certificate,把私钥路径配置给 ssl_certificate_key。修改完成后先执行 nginx -t,确认无误再重新加载服务。
证书文件由 Certbot 管理,Nginx 应引用 Certbot 提供的当前证书路径,而不是把证书复制到另一个不会随续期更新的位置。
风险与边界
certonly 成功只说明证书已经取得,不代表 HTTPS 已经可用。若忘记修改或重新加载 Nginx,客户端仍可能访问旧证书或根本没有 HTTPS 监听。
通配符域名不能使用基于 HTTP-01 的 Nginx 验证方式,应选择支持 DNS-01 的插件或验证流程。配置完成后应同时检查 Nginx 语法、外部 HTTPS 访问以及后续自动续期是否仍引用同一证书记录。
certbot run --apache [options] [-d DOMAIN] [-d DOMAIN] ...通过 Apache 插件完成域名验证、证书申请和虚拟主机 HTTPS 配置;执行前应确认 Apache 插件已经安装且站点配置能够正常加载。
Apache 申请并安装证书
Apache 插件可以一次完成 HTTP-01 验证、证书申请和虚拟主机 HTTPS 配置。执行前应确保域名已经解析到当前服务器、Apache 配置可正常加载,并且公网能够通过 80 端口访问目标站点。
基本语法
certbot run --apache [options] [-d DOMAIN] [-d DOMAIN] ...run 是申请并安装证书的完整流程;--apache 指定使用 Apache 插件完成验证和安装。每个 -d 增加一个需要写入同一张证书的域名。不指定 -d 时,交互模式下 Certbot 可以根据检测到的虚拟主机询问要保护哪些名称。
申请并安装
先确认 Apache 当前配置没有语法错误,再明确指定证书覆盖的域名:
sudo apachectl configtest
sudo certbot run --apache -d example.com -d www.example.com
sudo apachectl configtest预期结果:两次 Apache 配置检查均通过;Certbot 完成域名验证和证书签发后,把证书安装到匹配的虚拟主机,并保存续期所需的证书配置。首次运行时可能还会交互询问联系邮箱、服务条款等信息。
关键选项
-d DOMAIN:指定证书中的域名,可重复使用以申请多域名证书。--redirect:在安装证书时配置 HTTP 到 HTTPS 的重定向;只有确认站点适合强制 HTTPS 时再启用。--cert-name NAME:明确证书 lineage 名称,适合已有多张相关证书时避免选错目标。--non-interactive:关闭交互提示,适合自动化;同时必须提供运行所需的其他选项,否则命令会直接失败。
验证与常见失败
签发后可用 sudo certbot certificates 查看 Certbot 管理的证书、域名和到期时间,再实际访问 HTTPS 站点验证虚拟主机是否正确。证书文件通常由 Certbot 维护在 /etc/letsencrypt/live/<CERT_NAME>/ 下,不应手工覆盖其中的链接或私钥。
如果验证失败,优先检查 DNS 是否指向当前服务器、80 端口是否能从公网访问,以及 ServerName、ServerAlias 与请求域名是否匹配。如果证书签发成功但安装失败,则应检查 Apache 虚拟主机结构和配置测试结果,而不是反复重新申请证书。
风险与恢复
Apache 安装插件会修改站点配置,因此生产环境应先保存配置版本或备份。若自动修改后的配置不符合预期,可使用 Certbot 的回滚能力或恢复自己的配置备份,再执行 Apache 配置检查和重载。不要删除 /etc/letsencrypt 中不认识的文件来“重置”证书状态,以免同时破坏续期配置。
certbot certonly --webroot -w WEBROOT_PATH [-d DOMAIN] [-d DOMAIN] ...把 ACME 验证文件写入现有站点 Web 根目录,不接管 Web 服务器;适合 Nginx 自定义程度较高且能正常访问 /.well-known/acme-challenge/ 的环境。
通过 Webroot 申请证书
Webroot 模式只负责申请证书,不接管或改写现有 Web 服务器配置。Certbot 会把 HTTP-01 挑战文件写入站点根目录下的 .well-known/acme-challenge/,因此关键条件是公网请求能够原样访问这一路径。
基本语法
certbot certonly --webroot -w WEBROOT_PATH [-d DOMAIN] [-d DOMAIN] ...certonly 表示只获取或续期证书,不执行安装;--webroot 选择 Webroot 验证器;-w 指定 Web 服务器实际对外提供文件的根目录。多个 -d 可以共用最近一次指定的 -w,不同站点根目录则应分别指定对应的 -w。
申请前验证访问路径
不要只根据 Nginx 或其他服务器配置文件猜测 Webroot。可以先放置一个临时文件,确认外部 HTTP 请求确实能读取同一路径,再执行 Certbot:
sudo mkdir -p /var/www/example.com/.well-known/acme-challenge
printf 'webroot-ok\n' | sudo tee /var/www/example.com/.well-known/acme-challenge/check.txt >/dev/null
curl -fsS http://example.com/.well-known/acme-challenge/check.txt
sudo certbot certonly --webroot -w /var/www/example.com -d example.com -d www.example.com
sudo rm -f /var/www/example.com/.well-known/acme-challenge/check.txt预期结果:curl 输出 webroot-ok;随后 Certbot 能通过 HTTP-01 验证并保存新证书。certonly 不会替你修改 Nginx、Apache 或其他服务器的 TLS 配置,也不会自动把新证书接入正在运行的站点。
路径如何对应
当使用 -w /var/www/example.com 时,Certbot 的验证文件位于 /var/www/example.com/.well-known/acme-challenge/。外部 ACME 验证服务器则访问 http://DOMAIN/.well-known/acme-challenge/<TOKEN>;Web 服务器必须把这个 URL 映射到同一个文件,而不能被认证、SPA 回退、错误的 rewrite 或访问控制规则截走。
若同一张证书包含多个域名,而这些域名使用不同根目录,可以按域名切换 Webroot;每个 -d 使用它前面最近指定的 -w。配置复杂时应先逐个域名验证挑战路径,而不是等 Certbot 报错后再猜测是哪一个站点映射有问题。
证书安装与续期
申请成功后,用 sudo certbot certificates 确认证书名称和文件位置,再让 Web 服务器引用对应的 fullchain.pem 与 privkey.pem 并重新加载配置。Certbot 会保存本次 Webroot 续期参数,因此后续自动续期仍依赖相同的站点路径能够提供 /.well-known/acme-challenge/。
常见失败与边界
Webroot 模式要求现有 HTTP 服务已经可用,因此不适合尚未启动站点、80 端口无法从公网访问或挑战路径无法映射到本地文件的场景。遇到验证失败时,先用普通 HTTP 请求检查挑战 URL,再排查 DNS、代理/CDN、重写规则和目录映射;不要通过反复申请来代替路径验证,以免触发 CA 的请求频率限制。
certbot certonly --standalone [options] [-d DOMAIN] [-d DOMAIN] ...由 Certbot 临时启动 HTTP 服务完成域名验证;适合机器上没有正在运行的 Web 服务,或可以暂时释放验证所需端口的场景。
使用独立服务器验证
当目标域名已经解析到当前主机,且验证期间可以让 Certbot 占用 HTTP-01 所需的 TCP 80 端口时使用。Certbot 会临时启动内置 HTTP 服务完成验证,只申请证书,不修改 Nginx、Apache 等现有 Web 服务配置。
使用前提
域名的 A 记录应指向当前服务器;如果同时发布 AAAA 记录,对应 IPv6 地址也应能够正确到达该主机。公网 TCP 80 端口必须允许 ACME 服务访问,并且执行验证时不能被其他进程占用。
基本语法
certbot certonly --standalone [options] [-d DOMAIN] [-d DOMAIN] ...certonly:只获取或更新证书,不自动安装到 Web 服务器。--standalone:由 Certbot 临时监听 HTTP 端口并响应验证请求。-d DOMAIN:指定证书包含的域名;需要多个名称时可以重复使用。
常用示例
下面一次申请包含两个主机名的证书。执行前应确认两个名称都解析到当前服务器,并释放 TCP 80 端口。
sudo certbot certonly --standalone -d example.com -d www.example.com预期输出:验证成功后会显示证书和私钥保存位置;实际路径和有效期可能不同。
Successfully received certificate.
Certificate is saved at: <PATH>/fullchain.pem
Key is saved at: <PATH>/privkey.pem风险与恢复
如果 80 端口已被 Nginx、Apache 或其他程序监听,Standalone 验证会因无法绑定端口而失败。可以在验证前临时停止占用端口的服务,验证完成后立即恢复;不能中断现有 Web 服务时,应改用 Webroot 或适合当前环境的 DNS 验证插件。
--http-01-port 只改变 Certbot 本机监听端口,不会让 ACME 服务改为访问其他公网端口;除非前端已经把公网 80 端口转发到该端口,否则不要把它当作绕过 80 端口要求的方法。使用 Standalone 续期时也必须保证验证时刻所需端口可用。
certbot certonly --manual [options] [-d DOMAIN] [-d DOMAIN] ...按终端提示手动添加 HTTP 或 DNS 验证记录;适合临时签发和没有自动化插件的环境,长期自动续期应优先使用可自动完成验证的插件。
手动完成域名验证
当 Certbot 无法直接控制 Web 服务器或 DNS 服务商,又需要临时证明域名控制权时,可以使用 Manual 验证。Certbot 会在终端给出需要部署的 HTTP 文件或 DNS 记录,由操作者完成后再继续验证。
基本语法
certbot certonly --manual [options] [-d DOMAIN] [-d DOMAIN] ...--manual:使用交互式人工验证器。-d DOMAIN:指定需要写入证书的域名,可重复使用。--preferred-challenges dns:优先使用 DNS-01,并按提示添加 TXT 记录;申请通配符证书时需要 DNS 验证。--manual-auth-hook、--manual-cleanup-hook:通过脚本创建和清理验证记录,适合确实需要把 Manual 流程自动化的环境。
DNS 验证示例
下面为 *.example.com 申请通配符证书。单引号用于防止 Shell 把星号当成本地文件通配符展开。
sudo certbot certonly --manual --preferred-challenges dns -d '*.example.com'预期输出:Certbot 会给出需要创建的 TXT 记录和值;<TOKEN> 和证书路径属于动态值,实际内容每次可能不同。添加记录并确认 DNS 已传播后,再按终端提示继续。
Please deploy a DNS TXT record under the name:
_acme-challenge.example.com
with the following value:
<TOKEN>
Press Enter to Continue
...
Successfully received certificate.
Certificate is saved at: <PATH>/fullchain.pem风险与续期
不要在 TXT 记录尚未从权威 DNS 查询到时立即继续,否则验证可能失败。验证成功后,可删除仅为本次挑战创建的 TXT 记录;如果同一名称还有其他业务记录,只删除本次挑战对应的值。
纯交互式 Manual 验证不适合无人值守续期:后续验证仍需要再次人工操作。长期使用的证书应优先配置对应 DNS 插件、Webroot 等可自动完成挑战的方式;必须继续使用 Manual 时,应通过认证与清理 Hook 实现可靠自动化。
certbot certonly --nginx -d DOMAIN [-d DOMAIN] ...通过多个 -d 把多个域名写入同一张证书的 SAN 列表;适合主域名和 www 等站点共同使用一张证书,而不是分别维护多张证书。
一次申请多个域名
当多个主机名由同一站点或同一组服务使用时,可以在一次申请中重复传入 -d,让它们进入同一张证书的 SAN 列表。使用 certonly 只负责取得或更新证书,不会把证书直接安装到 Nginx 的站点配置中。
基本语法
certbot certonly --nginx -d DOMAIN [-d DOMAIN] ...certonly:只获取或续订证书,不执行证书安装。--nginx:使用 Nginx 插件完成域名控制权验证。-d:指定要写入证书的域名,可重复多次;这些名称会进入同一张证书的 SAN 列表。
未显式指定 --cert-name 时,新证书通常以第一个域名作为证书名称;若本机已有同名 lineage,实际名称可能不同,应以 certbot certificates 的结果为准。
申请并验证
执行前确认每个域名都解析到当前服务器,并且外部验证请求能够到达 Nginx。下面的命令在运行时读取两个真实域名,避免把示例域名误当成可验证目标。
read -r -p 'Primary domain: ' PRIMARY_DOMAIN
read -r -p 'Second domain: ' SECOND_DOMAIN
sudo certbot certonly --nginx -d "$PRIMARY_DOMAIN" -d "$SECOND_DOMAIN"
sudo certbot certificates预期结果:
Certificate Name: <CERTNAME>
Domains: <PRIMARY_DOMAIN> <SECOND_DOMAIN>
Expiry Date: <TIME>
Certificate Path: <PATH>
Private Key Path: <PATH><CERTNAME>、<TIME> 和 <PATH> 以实际输出为准;重点确认 Domains 同时包含本次传入的两个域名。
风险与边界
同一张证书中的每个域名都需要通过 CA 验证;其中任一域名的 DNS、Nginx server_name 或 HTTP 验证链路有问题,都可能导致整次申请失败。执行前可先用 certbot certificates 检查现有证书,避免无意中与已有 lineage 冲突。
把多个业务域名合并到一张证书会把它们的续订和故障影响绑定在一起。只有这些域名确实适合共同维护时才合并;需要独立变更或隔离风险的站点应分别管理证书。
certbot certonly --nginx --cert-name CERTNAME -d DOMAIN [-d DOMAIN] ...显式指定 Certbot 用于管理和生成目录名称的证书名;它主要影响证书 lineage 和文件路径,不会改变证书中的实际域名内容。
指定证书名称
--cert-name 用来指定 Certbot 管理证书时使用的 lineage 名称,便于让目录和后续管理命令使用稳定标识。它不会把这个名称写成证书域名;证书实际覆盖哪些主机名仍由 -d 决定。
基本语法
certbot certonly --nginx --cert-name CERTNAME -d DOMAIN [-d DOMAIN] ...--cert-name CERTNAME:指定 Certbot 的证书管理名称;名称不能包含路径分隔符。-d DOMAIN:指定证书实际包含的域名,可重复多次。--nginx:使用 Nginx 插件完成验证;certonly仍然只获取或更新证书,不负责安装到站点配置。
在默认配置目录下,名为 CERTNAME 的 lineage 通常对应 /etc/letsencrypt/live/CERTNAME/;如果修改过 Certbot 的配置目录,应以 certbot certificates 显示的路径为准。
指定名称并验证
下面的命令同时读取证书名称和两个真实域名。证书名称可以使用便于运维识别的稳定标识,但不要把它误当成域名列表。
read -r -p 'Certificate name: ' CERTNAME
read -r -p 'Primary domain: ' PRIMARY_DOMAIN
read -r -p 'Second domain: ' SECOND_DOMAIN
sudo certbot certonly --nginx --cert-name "$CERTNAME" -d "$PRIMARY_DOMAIN" -d "$SECOND_DOMAIN"
sudo certbot certificates预期结果:
Certificate Name: <CERTNAME>
Domains: <PRIMARY_DOMAIN> <SECOND_DOMAIN>
Expiry Date: <TIME>
Certificate Path: <PATH>
Private Key Path: <PATH>Certificate Name 应与输入的管理名称一致,而 Domains 应反映 -d 指定的实际域名;<TIME> 和 <PATH> 以当前环境输出为准。
修改已有 lineage 时要谨慎
如果 --cert-name 指向已经存在的证书,Certbot 会以该 lineage 为目标处理本次申请。此时 -d 描述新证书要包含的域名集合;漏掉原有域名可能使后续签发的证书不再包含它。
变更前先用 certbot certificates 核对该名称当前覆盖的全部域名。若域名列表写错,修正后应再次使用同一个 --cert-name 并完整列出期望保留的所有 -d,再验证 Domains 与文件路径是否符合预期。
certbot certonly --nginx --key-type {rsa,ecdsa} -d DOMAIN [-d DOMAIN] ...申请时选择 RSA 或 ECDSA 私钥类型;新部署通常可使用默认设置,只有兼容性、安全策略或既有基础设施有明确要求时再显式指定。
选择证书私钥类型
当客户端兼容性、安全规范或现有 TLS 基础设施明确要求某种算法时,可在申请证书时用 --key-type 指定 RSA 或 ECDSA。没有明确约束时,通常无需为了“更安全”而反复切换已有证书的私钥类型。
基本语法
certbot certonly --nginx --key-type {rsa,ecdsa} -d DOMAIN [-d DOMAIN] ...这里是命令 synopsis:{rsa,ecdsa} 表示二选一,方括号表示可重复的可选域名参数,不应把这些括号原样输入 Shell。
certonly:只获取或续发证书,不负责把证书安装到站点配置中。--nginx:使用 Nginx 插件完成域名验证,要求本机存在可用的 Nginx 配置和对应插件。--key-type rsa:生成 RSA 私钥,适合需要兼容较旧客户端、设备或既有密码基础设施的场景。--key-type ecdsa:生成 ECDSA 私钥,适合已经确认终端、代理、负载均衡器和 TLS 检查设备均支持 ECDSA 的场景。-d:指定证书包含的域名;多个域名重复使用-d。
常用示例
下面为同时覆盖主域名和 www 域名申请 ECDSA 证书的示例。执行前应把示例域名替换为已经解析到当前服务器、且能通过 ACME 验证的真实域名。
sudo certbot certonly --nginx --key-type ecdsa -d example.com -d www.example.com预期输出:首次申请且验证成功时,控制台会包含证书获取成功以及证书、私钥保存位置;实际路径会随证书名称和环境变化。
Successfully received certificate.
Certificate is saved at: <PATH>
Key is saved at: <PATH>选择与变更边界
RSA 与 ECDSA 的选择首先取决于终端兼容性和组织策略,而不是单纯比较密钥长度。证书前方若还有 CDN、硬件负载均衡器、旧版 Java 客户端或 TLS 检查设备,应先确认整条链路支持目标算法。
已有证书不会因为修改想法就自动原地转换私钥类型。确需迁移时,应在计划好的签发或续期过程中明确选择目标类型,并在证书生效后验证 Web 服务器加载的是新证书。不要连续重复申请来试错,以免触发证书颁发机构的频率限制。
续期与自动化
certbot renew [options]检查 Certbot 管理的证书并续期达到续期条件的证书;正常自动化任务应使用该命令,而不是每天强制重新申请所有证书。
续期即将过期的证书
certbot renew 用于周期性检查 Certbot 管理的证书,并只对达到续期条件的证书发起续期。它适合作为定时任务的固定入口,不需要每天重新申请全部证书。
基本语法
certbot renew [options]这里的 [options] 是 synopsis 记号,不应把方括号原样输入命令。普通自动续期通常直接执行 certbot renew 即可;Certbot 会读取每张证书已保存的续期配置,而不是要求定时任务重新填写全部域名和验证参数。
常用示例
sudo certbot renew预期结果取决于当前证书状态。若没有证书达到续期条件,Certbot 会跳过它们,控制台摘要通常包含:
No renewals were attempted.如果存在达到续期条件的证书,Certbot 会按各自保存的续期配置尝试重新验证和签发,并在命令末尾汇总成功或失败的证书。证书路径、域名和时间属于动态值,实际输出会因环境不同而变化。
自动化时的边界
定时任务应让 renew 自己判断是否需要续期,而不是固定强制重新签发。尤其不要把强制续期行为作为每天运行的常规策略:频繁签发既没有必要,也可能触发证书颁发机构的频率限制。
续期失败时应先处理实际原因,例如域名解析变化、HTTP 验证端口不可达、Nginx 配置错误或原有验证插件失效,再重新执行续期。不要用反复强制申请来掩盖验证失败,否则既不能修复根因,也会增加后续签发受限的风险。
certbot renew --dry-run [options]使用测试环境模拟续期流程而不保存正式证书,适合证书首次部署、修改验证方式或调整定时任务后检查未来自动续期能否成功。
测试自动续期
certbot renew --dry-run 会按现有 renewal 配置模拟证书续期,并使用 Let's Encrypt 测试环境完成验证和签发流程。测试证书不会保存为正式证书,适合在首次部署、修改验证方式或调整续期配置后检查续期链路。
基本语法
certbot renew --dry-run [options]--dry-run 仅适用于支持测试运行的续期场景。它会读取 Certbot 已保存的证书 lineage、验证插件和相关续期参数,即使正式证书当前尚未到期,也可以模拟未来的续期过程。
常用示例
sudo certbot renew --dry-run预期结果:Certbot 逐个模拟可管理证书的续期;全部验证成功时,会报告所有模拟续期成功。证书名和路径取决于当前服务器配置。
Simulating renewal of an existing certificate for <DOMAIN>
...
Congratulations, all simulated renewals succeeded:
/etc/letsencrypt/live/<CERTNAME>/fullchain.pem (success)其中 <DOMAIN> 和 <CERTNAME> 为实际域名和证书名,输出细节可能随 Certbot 版本、验证插件和证书数量变化。
Hook 与实际影响
测试不会把测试环境签发的无效证书保存为正式证书,但并非完全没有运行期影响。根据现有续期配置,Certbot 可能临时修改并回滚 Web 服务器配置,也可能触发服务器重载。
pre-hook 和 post-hook 默认可以在 dry run 中执行;deploy-hook 默认不执行。确实需要验证部署 Hook 时,可额外使用 --run-deploy-hooks,但应先确认 Hook 本身不会产生不希望出现的生产操作。
风险与边界
测试成功说明当前机器在测试时能够完成 ACME 验证和续期流程,但不能单独证明 systemd timer 或 cron 将来一定按计划触发。修改 DNS、Web 根目录、防火墙、插件凭据或反向代理配置后,应重新运行测试。
certbot renew --cert-name CERTNAME [options]将续期操作限制到指定证书 lineage;适合服务器管理多张证书时单独验证、调整或维护其中一张,证书名可先通过列表命令查询。
只续期指定证书
certbot renew --cert-name CERTNAME 将 renew 的处理范围限制到一个指定的证书 lineage,适合一台服务器管理多张证书时单独维护其中一张。CERTNAME 是 Certbot 管理用的证书名,不一定等于当前访问时使用的单个域名。
基本语法
certbot renew --cert-name CERTNAME [options]--cert-name 只负责选择目标证书,不会强制提前续期。目标尚未进入续期窗口时,普通 renew 会跳过它;需要先验证目标名称时,可通过 certbot certificates 查看 Certbot 当前管理的证书名。
常用示例
假设 certbot certificates 中显示证书名为 example.com,只处理这一张证书:
sudo certbot renew --cert-name example.com预期结果:只有 example.com 对应的 lineage 会被检查。若证书已满足续期条件,Certbot 尝试续期;若尚未到期,则跳过而不会签发新证书。
目标 lineage: example.com
结果可能为:续期成功,或因尚未进入续期窗口而跳过。实际控制台文案和证书路径会随 Certbot 版本、证书状态及验证插件变化。
单独测试指定证书
需要验证这一张证书未来能否续期,而不是立即申请正式证书时,可把范围限制和测试模式组合使用。
sudo certbot renew --cert-name example.com --dry-run预期结果:Certbot 仅对 example.com 对应的 lineage 执行测试环境续期;成功时不会用测试证书替换当前正式证书。
Simulating renewal of an existing certificate for <DOMAIN>
...
Congratulations, all simulated renewals succeeded:
/etc/letsencrypt/live/example.com/fullchain.pem (success)风险与恢复
证书名写错时不要通过猜测目录名处理,应先确认 certbot certificates 显示的 Certificate Name。不要为了测试而随意追加 --force-renewal:该选项会绕过正常续期时机并尝试签发正式证书,频繁使用还可能触及 CA 的签发限制。
certbot certonly --nginx --force-renewal -d DOMAIN [-d DOMAIN] ...忽略当前证书是否接近到期并立即重新签发;会增加 CA 请求次数,应只在确有更换证书需求时使用,日常续期不要依赖此参数。
强制重新签发证书
当某张现有证书必须立即重新签发,而不能等待正常续期窗口时使用 --force-renewal。它会忽略当前证书是否接近到期并向 CA 发起新的签发请求,因此不适合作为日常续期方式。
基本语法
certbot certonly --nginx --force-renewal -d DOMAIN [-d DOMAIN] ...certonly:获取或更新证书,不把命令当作站点安装流程使用。--nginx:使用 Nginx 插件完成域名验证,要求插件可用且当前 Nginx 配置能够正常加载。--force-renewal:即使现有证书尚未进入正常续期窗口,也立即申请新证书。-d DOMAIN:声明证书包含的域名。重新签发已有证书时应明确列出需要保留的全部域名,不要漏掉原有 SAN。
主示例
先用 certbot certificates 核对证书名称和现有域名,再执行实际签发:
sudo certbot certificates
sudo certbot certonly --nginx --force-renewal -d example.com -d www.example.com
sudo certbot certificates预期结果:域名验证成功后,Certbot 获得一张新证书,并更新该证书 lineage 的当前文件引用。实际路径、证书编号和有效期会不同。
Successfully received certificate.
Certificate is saved at: <PATH>/fullchain.pem
Key is saved at: <PATH>/privkey.pem风险与恢复
强制重新签发会消耗 CA 的签发额度,短时间反复执行可能触发速率限制。日常维护应使用 certbot renew,让 Certbot 只处理已进入续期窗口的证书。
certonly 的重点是获取或更新证书,不应假定它已经完成应用层部署。签发后应按实际部署方式确认 Web 服务正在使用预期证书;如果域名集合或签发选项有误,应修正参数后重新签发正确证书。
certbot renew --cert-name CERTNAME --reuse-key [options]续期指定证书时继续使用已有私钥,而不是采用默认的密钥更新行为;只有密钥固定、证书固定或下游系统存在明确要求时才建议启用。
续期时复用私钥
当下游系统要求证书续期后仍保持同一私钥时,可以对指定证书使用 --reuse-key。Certbot 默认不会在续期时复用已有私钥,因此这个选项应只用于明确需要保持密钥连续性的场景。
基本语法
certbot renew --cert-name CERTNAME --reuse-key [options]--cert-name CERTNAME:只选择指定的 Certbot 证书 lineage,可先通过certbot certificates查看名称。--reuse-key:续期成功时继续使用现有证书的私钥。[options]:可附加该证书续期所需的其他选项,但不要无意中把与当前证书无关的全局参数带入续期。
主示例
下面在证书进入正常续期窗口后执行续期,并比较续期前后的公钥摘要。私钥通常位于受限目录,因此读取时需要相应权限。
CERT_NAME=example.com
sudo openssl pkey -in "/etc/letsencrypt/live/$CERT_NAME/privkey.pem" -pubout -outform DER | sha256sum
sudo certbot renew --cert-name "$CERT_NAME" --reuse-key
sudo openssl pkey -in "/etc/letsencrypt/live/$CERT_NAME/privkey.pem" -pubout -outform DER | sha256sum预期结果:如果本次确实执行了续期且成功,两次公钥摘要应相同。摘要值以及 Certbot 输出中的时间、路径等内容会因环境而异。
<ID> -
<Certbot renewal messages>
<ID> -如果证书尚未进入续期窗口,renew 可能跳过实际签发,此时摘要相同只能说明本次没有更换密钥,不能作为一次真实续期后的验证结果。
风险与恢复
复用私钥会减少密钥轮换,因此不应在私钥疑似泄露、权限失控或需要主动换钥时使用。需要恢复默认的不复用策略时可使用 --no-reuse-key;如果希望立即生成新私钥,并让之后的续期继续复用这把新密钥,可结合 --new-key 与 --reuse-key 使用。
certbot renew --deploy-hook DEPLOY_HOOK [options]在证书成功签发或续期后执行部署命令,常用于重新加载 Nginx、同步证书或触发部署流程;Hook 命令应确保可重复执行且失败可观察。
续期成功后执行部署命令
--deploy-hook 适合把证书续期与服务重载、证书同步等部署动作串联起来。Hook 只在证书成功签发或续期后执行,不会因为一次普通的“尚未到续期时间”检查而反复重载服务。
基本语法
certbot renew --deploy-hook DEPLOY_HOOK [options]--deploy-hook DEPLOY_HOOK:指定续期成功后由 shell 执行的命令。- Hook 执行时可读取
RENEWED_LINEAGE,获得当前证书 lineage 的 live 目录;RENEWED_DOMAINS包含此次证书对应的域名列表。 - 一次
renew处理多个证书时,部署 Hook 可能针对每个成功续期的证书分别执行,因此命令应设计为可重复执行。
常用示例
下面先检查 Nginx 配置,只有检查成功才重新加载服务:
sudo certbot renew --deploy-hook "nginx -t && systemctl reload nginx"预期结果:需要续期且续期成功时,Certbot 执行 Nginx 配置检查并重新加载服务;没有证书达到续期条件时不会执行该部署 Hook。实际证书名称和续期时间可能不同。
测试与风险
使用 --dry-run 测试续期流程时,部署 Hook 默认不会按正常续期方式执行;需要专门验证部署 Hook 时,应结合 Certbot 支持的 --run-deploy-hooks 选项进行测试。
Hook 若负责重新加载服务,建议先执行配置校验再 reload,避免新证书已经生成却因服务配置错误导致重载失败。
certbot renew -q [options]执行续期时仅输出错误信息,并自动采用非交互模式;适合 cron 或其他定时任务,避免正常检查产生大量无意义日志。
静默执行自动续期
certbot renew -q 用于定时续期任务:正常检查和成功执行时尽量减少终端输出,只保留错误信息。它适合 cron 等无人值守环境,但静默输出不能代替退出状态、日志和告警检查。
基本语法
certbot renew -q [options]renew:检查 Certbot 管理的证书,只对达到续期条件的证书尝试续期。-q、--quiet:静默正常输出,仅保留错误信息,并按非交互方式运行。- 没有证书需要续期属于正常情况,不应把“没有输出”理解为任务没有执行。
常用示例
sudo certbot renew -q
printf 'exit=%s\n' "$?"预期输出:正常完成且没有续期错误时,Certbot 本身通常不打印正常信息,随后可看到退出状态:
exit=0发生续期错误时会有错误信息,并应结合非零退出状态和 Certbot 日志继续排查;具体错误文本取决于失败原因。
自动化注意事项
很多 Certbot 安装方式已经配置 systemd timer 或其他周期任务。另加 cron 前应先检查现有调度,避免重复维护同一套自动续期机制。