Appearance
Hook 环境变量
CertiMan 通过环境变量向 hook 传递上下文。变量名统一使用 CERTIMAN_ 前缀，变量名与取值格式保持稳定，可在脚本中直接使用。
所有 hook 共有的变量
| 变量 | 说明 |
|---|---|
CERTIMAN_CERT_NAME | 证书目录名（主域名派生） |
CERTIMAN_DOMAINS | 配置里申请的域名，逗号分隔；不含平台赠送的伴随域名（如需完整 SAN，请从证书文件中读取） |
CERTIMAN_STEP | 触发本次 hook 的生命周期：issue / renew / reissue；手动运行 certiman deploy 或 certiman download --deploy-hook 时不注入该变量。脚本应使用 ${CERTIMAN_STEP+x} 判断变量是否存在，不应依赖 case $CERTIMAN_STEP in 的 *) 分支；hook 类型见 CERTIMAN_HOOK_TYPE |
CERTIMAN_HOOK_TYPE | 本次 hook 的类型：present / cleanup / deploy；与 CERTIMAN_STEP 相互独立：CERTIMAN_HOOK_TYPE 表示 hook 执行的动作，CERTIMAN_STEP 表示触发该动作的生命周期 |
CERTIMAN_CONFIG_PATH | 该证书 cert.yaml 的绝对路径 |
Present / Cleanup Hook 变量
DCV 域名验证阶段的 hook 会额外收到以下变量：
| 变量 | 说明 |
|---|---|
CERTIMAN_DOMAIN | 当前处理的域名（每个域名调用一次 hook） |
CERTIMAN_DCV_METHOD | 验证方式：dns-persist / dns-proxy / dns / cname / file / file-proxy / email |
CERTIMAN_DCV_HOST | DNS 类：记录名（相对主域名） |
CERTIMAN_DCV_MAIN_DOMAIN | DNS 类：注册主域名，即 DNS 服务商的 zone |
CERTIMAN_DCV_FQDN | DNS 类：完整 FQDN 记录名 |
CERTIMAN_DCV_TYPE | DNS 类：记录类型 TXT / CNAME |
CERTIMAN_DCV_VALUE | DNS 类：记录值 |
CERTIMAN_DCV_FILE_PATH | file 类：验证文件相对路径 |
CERTIMAN_DCV_FILE_CONTENT | file 类：验证文件内容 |
CERTIMAN_REMAINING | 剩余待处理域名数；0 表示当前为最后一个域名，可在此时批量提交 |
CERTIMAN_DCV_RESULT | 仅 cleanup：success / failure，用于按验证成功或失败分别处理 |
批量提交 DNS 记录
DNS 服务商 API 通常有速率限制，逐域名添加记录容易触发限流。推荐做法是在 present hook 内先缓存要添加的记录，当 CERTIMAN_REMAINING=0 时一次性批量提交。
Deploy Hook 变量
部署阶段的 hook 会额外收到以下变量：
| 变量 | 说明 |
|---|---|
CERTIMAN_CERT_PATH | 全链证书路径（推荐用于 Nginx 等接受 fullchain 的服务）；设置了 output.fullchain_file（额外安装位置）时指向安装位置，而非证书目录中的文件 |
CERTIMAN_KEY_PATH | 私钥路径；设置了 output.key_file 时指向安装位置，而非证书目录中的文件 |
CERTIMAN_CHAIN_PATH | 中间证书链路径；仅在 chain.pem 存在时注入；缺少中间链时，deploy 输出警告并提示运行 certiman download -d <主域名> 下载完整证书链 |
CERTIMAN_CONVERTED_DIR | 转换产物目录（PFX / JKS 等） |
CERTIMAN_CERT_ID | 平台证书 ID |
CERTIMAN_NOT_AFTER | 证书到期时间，RFC 3339 格式 |
CERTIMAN_RENEWED | true 表示由续期或重新颁发触发；false 表示首次签发或手动运行 |
判断是否需要 reload
通常只在 CERTIMAN_RENEWED=true 时 reload 或 restart 服务。首次签发时，服务配置通常尚未引用该证书，执行 reload 可能失败。deploy hook 骨架已包含该判断，只需修改业务逻辑部分。
国密双证书变量
签发国密双证书（SM2）时，deploy hook 还会收到以下加密证书相关变量：
| 变量 | 说明 |
|---|---|
CERTIMAN_ENC_CERT_PATH | 加密证书全链路径 |
CERTIMAN_ENC_KEY_PATH | 加密证书私钥路径 |
CERTIMAN_ENC_LEAF_PATH | 加密证书文件（不含证书链） |
退出码 126 与 127
hook 脚本未能执行时，shell 返回以下两个特殊退出码，CertiMan 检测到后会额外输出一条处置提示：
| 退出码 | 含义 | CertiMan 的提示 |
|---|---|---|
126 | 文件存在但不可执行（无执行权限，或不是可执行格式） | chmod +x <脚本>；或改用 sh <脚本> 显式指定解释器 |
127 | 命令或脚本不存在 | 检查路径是否正确；相对路径以证书目录为基准（既非当前工作目录，也非 cert.yaml 所在目录）。路径含空格时同样返回该码：hook 的取值是一条 shell 命令串，解释器在空格处分词，需自行为路径加引号 |
执行 issue 的 --dcv.present、deploy 的 --deploy-hook 与 hook test 时均会输出这两条提示。提示不改变退出码，脚本中针对 126 / 127 的判断逻辑无需调整。
相对路径基准
为避免出现 126 / 127，建议使用绝对路径引用 hook 脚本（--deploy-hook /home/<用户名>/.certiman/hooks/nginx.sh），或将脚本放在证书目录 ~/.certiman/cc/certs/<CN>/ 下并使用相对路径引用。