Hook 命令

CertiMan CLI 的 hook 机制在证书生命周期的关键环节调用用户脚本，典型场景有两个：

• DCV 域名验证：issue / renew / reissue 提交订单后，需要在 DNS 服务商或 Web 服务器上布置验证信息，由 present / cleanup hook 自动布置与清理
• 证书部署：运行 deploy 或自动续期完成后，需要将新证书部署到 Nginx、IIS、云 CDN 等目标，由 deploy hook 调用对应服务的 reload 或 restart

hook 命令用于生成 hook 骨架与本地试运行；hook 在实际流程中的调用点见 issue 的 --dcv.present / --dcv.cleanup 与 deploy 的 --deploy-hook。

所有命令都可以叠加 全局 flag。

命令一览

命令	作用
hook init	生成 hook 骨架（支持 present / cleanup / deploy 三种类型）
hook test	用模拟数据本地试运行 hook（不改动真实证书、不联网）
Hook 环境变量	CERTIMAN_* 变量清单 + 126/127 特殊退出码提示
完整示例	可修改后直接使用的示例脚本：nginx / apache / systemd / IIS 部署，腾讯云 / Cloudflare / 阿里云 DNS 验证

hook 命令本身不接受参数，直接运行时输出帮助信息。

推荐目录规划

建议将 hook 脚本集中存放在 ~/.certiman/hooks/（目录权限 0700），凭证与配置写在脚本顶部；各 profile 与 cert.yaml 使用绝对路径引用同一份脚本。修改该脚本后对所有引用处生效，避免在各证书目录中产生多份副本。

~/.certiman/
├── hooks/                          # 0700，凭证写在脚本顶部「改这里」
│   ├── dcv-dnspod.sh
│   └── deploy-nginx.sh
└── cc/
    ├── profiles/
    │   └── dnspod.yaml             # dcv.present / dcv.cleanup 填写上述绝对路径
    └── certs/
        ├── shop.com/cert.yaml
        └── api.shop.com/cert.yaml

Windows 上，将 %USERPROFILE%\.certiman\hooks 的权限设置为不继承，并只保留当前用户与 SYSTEM（右键 → 属性 → 安全），可达到相同效果。

DCV Hook 生命周期

issue / renew / reissue 提交订单后按下图调用 hook：每个域名按顺序调用一次 present（CERTIMAN_REMAINING 从 N-1 递减到 0）；随后 CertiMan 轮询平台的域名验证结果，并通过 CERTIMAN_DCV_RESULT 传给 cleanup，cleanup 可按成功或失败分别处理。

批量优化：多数 DNS 服务商 API 有速率限制。present hook 可先缓存待添加的记录，在 CERTIMAN_REMAINING=0 时一次性批量提交，以减少 API 调用次数。

cleanup 幂等性建议：CA 侧验证超时或失败时，cleanup 以 CERTIMAN_DCV_RESULT=failure 被调用。脚本应将「记录不存在」视为删除成功，不应将删除失败作为致命错误处理。

dns-persist / dns-proxy 一般不建议配置 cleanup

dns-persist 与 dns-proxy 属于持久授权模式：验证记录布置一次，后续多次续期复用。若在 cert.yaml.dcv.cleanup 或 --dcv.cleanup 中配置了删除脚本，DCV 完成后记录将被删除，下次续期需要重新执行 present 并等待 DNS 传播。

配置建议：

• dns / cname / file / email：每次验证使用新的验证值，通常需要配置 cleanup
• dns-persist / dns-proxy / file-proxy：布置一次，持久复用，建议不配置 cleanup

同一份 hook 脚本需要同时支持两类验证方式时，可在脚本中读取 $CERTIMAN_DCV_METHOD 区分处理：遇到 dns-persist / dns-proxy / file-proxy 时直接 exit 0。

相关文档

• 证书命令 —— issue / renew / reissue 的 --dcv.present / --dcv.cleanup 参数
• 部署命令 —— deploy 命令与 --deploy-hook
• 定时任务命令 —— 定时续期后自动触发 deploy hook
• 配置 —— 数据目录与全局配置