密码学与证书 / 系统课时
Deploy Hook 适合做什么
Deploy Hook 适合做什么
证书续期成功后,证书文件已经更新,但正在运行的 Nginx 未必会立刻重新读取它。Deploy Hook 的作用,就是把“续期成功”与“部署新证书”连接起来,例如先校验 Nginx 配置,再安全 reload,让新证书真正进入在线服务。
学习目标
- 说明 Deploy Hook 与 pre/post hook 的触发差异
- 用 Deploy Hook 在续期成功后安全重新加载 Nginx
- 判断哪些部署动作适合放进 Hook,以及如何验证它
Deploy Hook 只在成功后执行
certbot renew 可能检查多个证书,也可能发现某个证书无需续期。Deploy Hook 的关键语义是:只有某张证书成功签发或续期后,才执行对应的部署命令。因此,它很适合执行“必须建立在新证书已经可用”这一前提上的动作。
常见用途包括重新加载 Nginx、把证书同步到另一个服务、转换证书格式,或通知依赖证书的进程重新读取文件。相对地,--post-hook 表示一次续期尝试结束后的动作,不等价于“续期成功”。
Deploy Hook 执行时还可使用 RENEWED_LINEAGE 和 RENEWED_DOMAINS。前者指向本次已更新证书的 live 目录,后者包含该证书覆盖的域名,适合一个 Hook 服务多个证书时做条件处理。

用脚本安全重载 Nginx
Nginx 通常直接引用 /etc/letsencrypt/live/<ID>/ 下的证书链接,其中 <ID> 是 Certbot 管理的证书名称。因此续期完成后通常不必复制证书;让 Nginx 重新加载配置即可读取新的目标文件。部署动作应先运行 nginx -t,只有配置有效时才 reload,避免把配置错误放大成服务中断。
下面把脚本放入 Certbot 的 deploy hook 目录,并立即用 dry run 验证续期链路与 Hook。该示例适用于使用 systemd 管理 Nginx 的 Linux 主机。
sudo install -d -m 0755 /etc/letsencrypt/renewal-hooks/deploy
sudo tee /etc/letsencrypt/renewal-hooks/deploy/10-reload-nginx >/dev/null <<'EOF'
#!/usr/bin/env bash
set -eu
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
# 只有配置检查通过,才重新加载正在运行的 Nginx。
nginx -t
systemctl reload nginx
EOF
sudo chmod 0755 /etc/letsencrypt/renewal-hooks/deploy/10-reload-nginx
sudo certbot renew --dry-run --run-deploy-hooks预期结果
模拟续期成功时,Certbot 执行 deploy hook;nginx -t 检查通过后,Nginx 被 reload。
实际输出中的证书名称、时间和日志行会因环境而不同。--run-deploy-hooks 很重要:普通 --dry-run 默认不会运行 Deploy Hook。启用该选项后,只有模拟续期成功才会执行适用的 Hook;Hook 使用的是当前活动证书,而不是 dry run 临时取得的测试证书。
Hook 里应该做什么
Deploy Hook 最适合短、可重复、失败后容易诊断的部署动作。重新加载 Nginx、更新证书格式、向本机服务发送 reload 信号都比较合适。脚本最好具备幂等性,因为同一逻辑会在未来的每次成功续期中再次执行。
不要把长时间备份、复杂发布、无人值守时可能阻塞的交互命令塞进 Hook。Hook 出错需要单独监控和排查,不能只确认新证书是否已经签发。
如果 Nginx 通过固定的 live 路径读取证书,那么“成功续期 → 配置校验 → reload”通常就是最小而可靠的 Deploy Hook。