密码学与证书 / 系统课时

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 服务多个证书时做条件处理。

Deploy Hook 在续期成功后触发部署动作

用脚本安全重载 Nginx

Nginx 通常直接引用 /etc/letsencrypt/live/<ID>/ 下的证书链接,其中 <ID> 是 Certbot 管理的证书名称。因此续期完成后通常不必复制证书;让 Nginx 重新加载配置即可读取新的目标文件。部署动作应先运行 nginx -t,只有配置有效时才 reload,避免把配置错误放大成服务中断。

下面把脚本放入 Certbot 的 deploy hook 目录,并立即用 dry run 验证续期链路与 Hook。该示例适用于使用 systemd 管理 Nginx 的 Linux 主机。

bash
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

预期结果

text
模拟续期成功时,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。

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

目录与阅读设置

阅读设置

17

记录一个想法

Deploy Hook 适合做什么

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

登录哪都通