acme-companion 证书签发钩子完全指南：用 ACME_PRE_HOOK / ACME_POST_HOOK 在证书签发前后执行自定义动作

云原生运维【免费下载链接】acme-companionAutomated ACME SSL certificate generation for nginx-proxy项目地址https://gitcode.com/gh_mirrors/ac/acme-companion点击查看免费下载本文基于 acme-companion 官方文档 Hooks.md深入讲解如何通过ACME_PRE_HOOK与ACME_POST_HOOK环境变量在 ACME 证书签发前、后自动执行自定义命令。文章结合 letsencrypt_service.sh 源码与 acme_hooks 集成测试说明其底层实现原理、默认/每容器两种配置方式、优先级规则、验证方法与实际限制。读完本文你将能够在 nginx-proxy acme-companion 的自动 HTTPS 体系中灵活接入防火墙临时放行、证书格式转换、监控告警等自动化动作。什么是 Pre-Hook 与 Post-Hookacme-companion 本质上是 nginx-proxy 的 ACME 证书自动签发伴生容器它把 Docker 容器的环境变量翻译成 acme.sh 的调用参数。acme.sh 本身提供了 Pre-Hook、Post-Hook以及 Renew-Hook、ReloadCmd机制允许在证书签发流程的特定时间点执行用户命令。acme-companion 通过两个环境变量将其暴露给用户ACME_PRE_HOOK在证书签发之前执行的命令ACME_POST_HOOK在证书签发之后执行的命令。典型应用包括仅在 ACME 授权期间临时调整防火墙规则、签发完成后对证书做后处理如格式转换、以及接入监控系统。关于 acme.sh 原生的 hook 能力可参考 acme.sh 官方 Wiki 的 Using pre-hook post-hook renew-hook reloadcmd 文档在 acme-companion 项目中相关入口文档见 Lets-Encrypt-and-ACME.md 与 Container-configuration.md。底层实现环境变量如何变成 acme.sh 参数理解 hook 的配置方式之前先看它在源码中的完整传递链路。这条链路分为三步docker-gen 模板采集容器环境变量。letsencrypt_service_data.tmpl 中通过coalesce $container.Env.ACME_PRE_HOOK 和coalesce $container.Env.ACME_POST_HOOK 从每个被代理容器的环境变量中读取 hook 命令并 trim 掉首尾空白随后将结果写进生成的/app/letsencrypt_service_data对应变量名为ACME_${cid}_PRE_HOOK与ACME_${cid}_POST_HOOK见该模板第 87-88、122-123 行。这里的cid是容器 ID 的前 12 位。服务脚本 source 生成的数据文件。letsencrypt_service.sh 在启动时source /app/letsencrypt_service_data把这些按容器隔离的变量载入当前 shell 环境。组装 acme.sh --issue 参数。签发函数中letsencrypt_service.sh通过local -n acme_pre_hookACME_${cid}_PRE_HOOK间接引用每容器变量再拼接到params_issue_arr# acme.sh pre and post hooks local -n acme_pre_hookACME_${cid}_PRE_HOOK if [[ -n ${acme_pre_hook} ]]; then # Use per-container pre hook params_issue_arr(--pre-hook ${acme_pre_hook}) elif [[ -n ${ACME_PRE_HOOK// } ]]; then # Use default pre hook params_issue_arr(--pre-hook ${ACME_PRE_HOOK}) fiPost-Hook 的处理逻辑完全相同最终以--pre-hook/--post-hook参数随acme.sh --issue第 532 行一起执行。值得注意--pre-hook参数值会原样传递给 acme.sh因此 hook 中涉及引号、空格等特殊字符时需要按照 shell 命令的书写习惯在环境变量值中正确转义。默认 Hook设置在 acme-companion 容器上如果把ACME_PRE_HOOK/ACME_POST_HOOK设置在acme-companion容器上那么所有证书的签发都会执行相同的动作。例如在 acme-companion 容器上设置默认 Pre-Hook签发前执行echo start$ docker run --detach \ --name nginx-proxy-acme \ --volumes-from nginx-proxy \ --volume /var/run/docker.sock:/var/run/docker.sock:ro \ --volume acme:/etc/acme.sh \ --env DEFAULT_EMAILmailyourdomain.tld \ --env ACME_PRE_HOOKecho start \ nginxproxy/acme-companion设置默认 Post-Hook签发后执行echo end$ docker run --detach \ --name nginx-proxy-acme \ --volumes-from nginx-proxy \ --volume /var/run/docker.sock:/var/run/docker.sock:ro \ --volume acme:/etc/acme.sh \ --env DEFAULT_EMAILmailyourdomain.tld \ --env ACME_POST_HOOKecho end \ nginxproxy/acme-companion上面的示例沿用了 Hooks.md 的标准启动参数--volumes-from nginx-proxy复用 nginx-proxy 的卷/var/run/docker.sock以只读方式挂载供 docker-gen 监听容器事件acme:/etc/acme.sh持久化证书与 acme.sh 数据。如果你使用 Docker Compose也可以把ACME_PRE_HOOK/ACME_POST_HOOK直接写进 acme-companion 服务的environment小节效果等同。每容器 Hook只对特定证书生效如果希望不同证书执行不同的动作就把ACME_PRE_HOOK/ACME_POST_HOOK设置在被代理的容器上。例如对某个代理应用容器设置每容器 Pre-Hook$ docker run --detach \ --name your-proxyed-app \ --env VIRTUAL_HOSTyourdomain.tld \ --env ACME_HOSTyourdomain.tld \ --env ACME_PRE_HOOKecho start \ nginx对另一个应用容器设置每容器 Post-Hook$ docker run --detach \ --name your-proxyed-app \ --env VIRTUAL_HOSTyourdomain.tld \ --env ACME_HOSTyourdomain.tld \ --env ACME_POST_HOOKecho start \ nginx注意这些命令是在acme-companion 容器内部执行的而非在被代理容器内执行。ACME_HOST用于指定该容器需要证书的域名兼容旧变量名LETSENCRYPT_HOSTVIRTUAL_HOST则是 nginx-proxy 路由所需的域名二者通常一致。优先级与组合规则重要不合并默认设置在 acme-companion 容器上与每容器的ACME_PRE_HOOK/ACME_POST_HOOK不会叠加执行。当某个被代理容器同时存在默认值和每容器值时每容器值优先生效默认值被完全忽略。这一优先级逻辑同样体现在 letsencrypt_service.sh 中先判断ACME_${cid}_PRE_HOOK是否非空非空即采用否则才回落到全局ACME_PRE_HOOK。例外容器禁用默认 Hook如果大多数容器想用同一套默认 Hook但个别容器不想执行可以在这几个容器上把变量值设为 Bash 的 noop 操作符:即ACME_PRE_HOOK:。由于每容器值非空时优先于默认值:这个什么都不做的合法命令就覆盖掉了全局默认达到只对特定容器禁用 Hook 的效果。同理可设置ACME_POST_HOOK:。如何验证 Hook 是否真正生效文档给出了直接的验证手段检查 acme.sh 在容器内持久化的域名配置文件/etc/acme.sh/[EMAILADDRESS]/[DOMAIN]/[DOMAIN].conf。其中变量Le_PreHook存放 Pre-Hook 命令base64 编码变量Le_PostHook存放 Post-Hook 命令base64 编码。acme-companion 仓库中的集成测试 test/tests/acme_hooks/run.sh 对该行为做了精确断言并揭示了编码细节测试期望配置文件中出现形如Le_PreHook__ACME_BASE64__START_base64内容__ACME_BASE64__END_的内容第 53-56 行再通过echo -n ${command} | base64计算出期望值做比对第 67-78 行。也就是说实际写入 conf 的 base64 串还带有一对__ACME_BASE64__START_/__ACME_BASE64__END_包裹标记这是 acme.sh 的编码约定。测试同时验证了两个层面的行为默认 Hook 生效在 acme-companion 容器上设置ACME_PRE_HOOKtouch /tmp/default_prehook与ACME_POST_HOOKtouch /tmp/default_posthook第 20-22 行签发完成后检查 conf 中 base64 编码是否正确、且容器内确实生成了对应文件第 82-87 行每容器 Hook 生效为第二个被代理容器单独设置 hook 命令第 44-48 行同样检查 conf 编码与文件落盘第 99-119 行证明每容器配置独立生效。这套测试恰好对应文档中默认/每容器两种配置模式的正确性验证如果你想在自己的环境里手动核对可以在容器内执行$ docker exec nginx-proxy-acme \ grep Le_PreHook /etc/acme.sh/contactyourdomain.tld/yourdomain.tld/yourdomain.tld.conf然后将取回的 base64 值解码确认与你设置的命令一致注意剥掉__ACME_BASE64__START_/__ACME_BASE64__END_标记。限制命令只能使用容器内可用的工具Hook 命令在acme-companion 容器内部执行因此命令的选择受限于容器镜像内已安装的工具不能假定所有系统命令都可用。文档明确指出curl和wget是可用的因此可以通过 HTTP 与容器外部的工具或其它容器通信把复杂动作放到外部实现。例如调用外部 HTTP 接口触发防火墙规则变更或撤销变更向监控系统自建 Webhook 等推送证书签发/续期事件。设计 Hook 时建议先docker exec nginx-proxy-acme which command确认命令存在或直接选用文档确认可用的curl/wget避免因缺少二进制导致 Hook 静默失败。典型使用场景结合 Hooks.md 与项目上下文Pre/Post-Hook 的典型落地场景包括临时调整防火墙规则ACME 的 HTTP-01 挑战通常要求 80 或 443 端口对 CA 的验证服务器公开可达。可以在 Pre-Hook 中临时放行对应端口例如通过 curl 调用防火墙管理 API在 Post-Hook 中再关闭从而不必让 80/443 长时间对外开放。证书后处理与格式转换签发完成后在 Post-Hook 中把 PEM 证书转换成应用需要的格式如 PKCS#12、DER或拷贝到指定位置供非 HTTPS 场景如 FTPS、邮件服务器使用。配合ACME_RESTART_CONTAINER见 Lets-Encrypt-and-ACME.md还可以在续期后重启相关容器加载新证书。监控在 Post-Hook 中上报签发结果、证书有效期等指标便于巡检证书是否按时续期成功。相关配置速查ACME_PRE_HOOK证书签发前执行的命令可设置在 acme-companion全局默认或被代理容器每容器优先。ACME_POST_HOOK证书签发后执行的命令设置方式与优先级同上。ACME_${cid}_PRE_HOOK/ACME_${cid}_POST_HOOKdocker-gen 生成的每容器内部变量见 letsencrypt_service_data.tmpl一般无需手动设置仅用于理解实现。两个变量的完整环境变量参考见 Environment-variables-reference.md与其它 ACME 相关变量的关系见 Lets-Encrypt-and-ACME.md。小结ACME_PRE_HOOK/ACME_POST_HOOK是 acme-companion 把 acme.sh 的 Hook 能力透传给用户的两个关键开关设置在 acme-companion 容器上即全局生效设置在某个被代理容器上则只影响该容器的证书且每容器值永远优先、不会与默认值合并想豁免个别容器时可用 Bash noop 操作符:覆盖。Hook 命令在 acme-companion 容器内执行受容器可用工具限制curl、wget可用可通过 letsencrypt_service.sh 源码与 acme_hooks 集成测试 印证其实现与验证方式。掌握这套机制后你可以在完全自动化的证书生命周期中插入任意自定义动作让 HTTPS 证书管理真正贴合你的运维流程。赞分享云原生运维【免费下载链接】acme-companionAutomated ACME SSL certificate generation for nginx-proxy项目地址https://gitcode.com/gh_mirrors/ac/acme-companion点击查看免费下载相关推荐acme-companion 实战指南为 nginx-proxy 自动化签发与续期 ACME SSL 证书acme companion 实战指南为 nginx proxy 自动化签发与续期 ACME SSL 证书 本文围绕 nginx proxy 生态中的轻量级伴云原生运维letsencrypt.sh 钩子脚本如何自定义证书签发和部署流程letsencrypt.sh 钩子脚本如何自定义证书签发和部署流程 letsencrypt.sh也称为 dehydrated是一个轻量级的ACME客户端网络安全运维acme-companion 独立证书Standalone Certificates配置指南通过 /app/letsencrypt_user_data 为无容器依赖场景签发 ACME 证书acme companion 独立证书Standalone Certificates配置指南通过 /app/letsencrypt_user_data 为云原生运维上一篇Prettier 韩文HangulMarkdown 格式化解析splitCjkText/korean.md 测试用例深度解读下一篇SMAPI安卓安装器终极指南5分钟快速配置星露谷物语模组环境创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考