文档中心

Appearance

完整示例 ​

本节提供可按需修改的脚本模板：适用于 nginx、Apache、systemd 与 IIS 的 deploy hook，以及适用于腾讯云、Cloudflare、阿里云的 DCV present / cleanup hook。

示例脚本仅供参考，使用后果由使用者自行承担

这些脚本是参考模板，不是 CertiMan 产品的一部分：

  • CertiMan 不会自动安装或调用这些脚本。使用前需将脚本复制到目标机器，并按实际环境修改
  • 每份脚本顶部都有 ── 改这里 ── 段，通常只需修改该段中的路径与凭证
  • 请务必根据自身的业务、系统、安全策略充分调整并测试（投入使用前须运行 certiman hook test 试运行）
  • 因使用这些示例脚本导致的任何损失（服务中断、证书泄露、误删记录等）由使用者自行承担，TrustAsia 不承担相关责任

分类 ​

分类场景脚本
部署示例证书下载后部署到服务nginx / apache / systemd（通用） / Windows IIS
DNS 验证示例在 DNS 中添加和删除验证记录（present 与 cleanup 共用一个脚本）腾讯云 DNSPod / Cloudflare / 阿里云 DNS / 接新服务商的模板

使用方法 ​

bash
# 1. 复制到数据目录下的 hooks/(这个目录 certiman 不会自动建),给执行权限
mkdir -p ~/.certiman/hooks && chmod 700 ~/.certiman/hooks
install -m 700 nginx.sh ~/.certiman/hooks/nginx.sh

# 2. 在证书配置里指向它——写绝对路径
#    ~/.certiman/cc/certs/example.com/cert.yaml
#    deploy: /home/<用户名>/.certiman/hooks/nginx.sh

# 3. 用模拟数据试运行一遍,避免在自动续期时才发现路径错误
certiman hook test -d example.com --step deploy

脚本建议放在数据目录 ~/.certiman/hooks/，与证书一同备份和迁移。~ 解析到哪个 home，取决于执行 hook 的用户：以 root 注册定时任务时，脚本应放在 /root/.certiman/hooks/。DCV 脚本顶部包含 API 凭证，脚本目录与脚本文件的权限均应设为 700。多张证书共用一份脚本的目录规划见 Hook 命令 · 推荐目录规划。

hook test 使用当前证书的真实路径执行脚本，退出码非 0 即判定为失败。以 --step present 试运行时，注入的值带 certiman-hook-test- 前缀，且 present 成功后自动执行一次 cleanup，删除试运行写入 DNS 的记录。

凭证配置 ​

脚本顶部的 ── 改这里 ── 段用于填写凭证，与路径、等待秒数集中在同一处，便于定位需要修改的行。密钥以明文存于文件，须执行 chmod 600。

也可以改为从环境变量读取凭证：

sh
SECRET_ID="${TENCENTCLOUD_SECRET_ID}"    # 原本是 SECRET_ID="AKIDxxxx..."

注意：cron 触发时不继承登录 shell 的环境变量，这是手动执行正常、自动执行失败的最常见原因。此时应在 crontab 中以行内赋值设置变量，或使用 systemd 的 Environment=；仅在 .bashrc 中 export 不会生效。

编写 hook 的注意事项 ​

  • CERTIMAN_CERT_PATH 是全链，不是叶子证书：该变量名易被误解。若参照部分 nginx 教程改为只含叶子证书的 cert.pem，桌面浏览器通常不报错，移动端或旧客户端访问时才会出现握手失败。certiman doctor 会将缺链判为 FAIL。
  • 脚本通过 sh -c 执行，而非 bash：Debian / Ubuntu 上的 /bin/sh 是 dash，不支持 [[ ]] 与数组。需要 bash 时，在脚本第一行写 #!/bin/bash，并确保 deploy 指向脚本文件本身（而非在 cert.yaml 中内联命令）。
  • set -e 与 [ -f x ] && cmd 的组合是常见陷阱：文件不存在时整条语句返回 1，set -e 会立即终止脚本，后续还原逻辑不会执行。示例中一律使用 if。
  • 默认 60 秒超时：超时后连同子进程一并终止。耗时操作（等待健康检查、滚动重启）应调整 deploy.timeout，或在脚本中转为后台任务。
  • 执行时没有可交互的终端：需要输入口令的操作将一直阻塞至超时。口令应通过环境变量或文件提供。
  • 注意执行 hook 的身份：cron 触发时使用注册定时任务时的用户身份。写入 /etc/nginx/ssl 或执行 systemctl reload 通常需要 root 权限，应以 root 注册定时任务，或为该用户配置免密 sudo 并在脚本中显式调用 sudo。手动执行正常、自动续期时静默失败通常由执行身份不符导致。
  • 先校验后重载：未经校验直接 reload 时，配置或证书中的问题会使服务处于不可用状态。重载前不可省略 nginx -t / apachectl configtest 校验。

相关文档 ​