文档中心

Appearance

CertiMan CLI 自动化实践：HAProxy 证书部署与自动续期 ​

CertiMan CLI 从 CertCloud 获取证书；部署 Hook 将证书链和私钥合并到 HAProxy 当前使用的 PEM 文件，再检查配置并重新加载服务。

本文适用于 Linux 上由 systemd 管理、root 主进程运行、已有正常 HTTPS 网站的 HAProxy。接管网站当前证书对应的订单，沿用原证书路径、监听和后端路由。

尚未启用 HTTPS 时，请先完成首次部署指南，再接入本文的自动更新流程。

操作流程： 接入已有订单 → 核对证书路径 → 配置 Hook → 更新并验收 → 开启计划任务。

方案是怎样的？ ​

CertCloud 负责订单管理、域名验证和证书签发；CertiMan CLI 获取新证书后调用部署 Hook，更新 HAProxy 并重新加载服务。需要自动写入域名验证记录时，由 DNS Hook 调用 DNS 服务商 API；网站访客仍通过 HAProxy 访问原有后端应用。

首次手动部署验收后再开启计划任务。定期扫描只处理已开启自动续期的证书，满足续期条件才更新，不是每次扫描都重新签发。

网络放行 ​

服务器需能通过 HTTPS（443）访问 certiman.trustasia.com、certcloud.cn 和 api.certcloud.cn。使用 DNS 验证脚本时，还需访问 DNS 服务商 API。安装或登录连接失败时，运行 certiman doctor，按诊断说明检查；自定义服务地址以实际配置为准。

开始前准备什么？ ​

  • 一个已经能正常访问 HTTPS 的 HAProxy 网站。
  • 该网站对应的 CertCloud 订单和原私钥。
  • 服务器 root 权限；安装、接入和部署命令在这台服务器的同一个 root 终端执行，网站访问检查按第四步在自己的电脑上进行。

示例域名 trustasia.com 换成你的域名。本文使用默认配置文件 /etc/haproxy/haproxy.cfg 和 haproxy 服务，实际不同时在第三步替换。

第一步：将已有订单接入 CertiMan CLI ​

本步骤将已有订单和匹配私钥交给 CLI 管理，取得后续更新所需的本地材料。已由当前账号的 CLI 管理且材料齐全时，核对状态后可直接进入第二步。

1.1 确认订单并安装 CLI ​

在 CertCloud 打开网站当前证书对应的订单，在订单详情左下角确认支持“自动交付”。进入接入引导，选择“命令行工具 CLI → Linux”；没有对应入口时联系支持确认。

CertCloud 订单中的 CertiMan CLI 接入引导，选择 Linux

通过 SSH 连接 HAProxy 服务器，在同一个 root 会话中安装并完成后续操作：

bash
sudo -i
whoami
curl -fsSL https://certiman.trustasia.com/install.sh | sh
certiman version

确认 whoami 输出为 root。安装过程中按提示阅读并确认协议；已安装时无需重复安装。完整说明见 CertiMan 安装指引。登录、接入、部署和计划任务使用同一个账号。

1.2 登录并导入原始私钥 ​

bash
certiman login status

缓存有效且账户正确时不重复授权；未登录或凭据失效时运行 certiman login。在浏览器中核对账户及应用名称为 CertiMan 后完成授权。终端没有浏览器时，在自己的电脑上打开 CLI 输出的授权地址。

CertiMan 浏览器登录授权确认

登录完成后，接入订单。将 YOUR_ORDER_ID 替换为接入引导中的实际订单号，将私钥路径替换为该订单已有证书的匹配私钥路径：

bash
certiman issue --reuse-order YOUR_ORDER_ID --private-key /root/cert-files/privkey.pem

私钥仅保存在合并 PEM 中时，先按文末提取私钥后再接入；无法找回原私钥时，参见重新签发。

1.3 确认订单状态和本地材料 ​

接入已签发订单后，查看 CLI 状态及本地文件。

bash
certiman status -d trustasia.com
ls -l /root/.certiman/cc/certs/trustasia.com/

将示例域名替换为订单实际主域名。确认已签发，且目录中已有 fullchain.pem、privkey.pem 和 cert.yaml。目录名由订单主域名决定，请以 CLI 输出为准。

证书状态与本地材料

1.4 确认后续域名验证可自动完成 ​

自动续期时，CertCloud 仍需要验证域名归属。根据订单使用的验证方式，按下面对应的一种处理：

持久验证： 使用 dns-persist 时，按订单提示添加 TXT 记录；使用 dns-proxy 时，添加指向平台的 CNAME 记录。授权有效期间通常可以继续使用这些记录，无需每次续期修改。已经配置好的记录继续保留，不要在首次签发成功后删除，也不要配置会删除它们的清理操作。

普通 DNS 验证： 每次签发需要新的验证记录时，CLI 会将本次记录名、类型和值传给 DNS Hook，由 Hook 调用 DNS 服务商 API 更新记录。按官方 DNS Hook 示例配置对应服务商的脚本和 API 凭据，确认能够自动写入后再开启自动续期；安装 HAProxy 部署 Hook 不等于已配置 DNS 验证。

第二步：找到网站正在使用的证书路径 ​

先在浏览器确认网站的 HTTPS 能正常访问，记下网站域名和端口，第四步继续使用这个地址检查。再打开 HAProxy 配置文件（默认 /etc/haproxy/haproxy.cfg），找到该网站的 frontend 配置段。下面是现有配置的示例：

haproxy
frontend web_front
    bind :80
    bind :443 ssl crt /etc/haproxy/certs/trustasia.com.pem
    mode http
    default_backend web_backend

找到 HTTPS bind 行，crt 后面的完整路径就是 HAProxy 正在读取的合并 PEM 文件。按下面的对应关系记录，第三步填写到脚本中：

记录什么示例下一步填入
crt 后面的 PEM 文件完整路径/etc/haproxy/certs/trustasia.com.pemTARGET
当前 HAProxy 配置文件路径/etc/haproxy/haproxy.cfgCONFIG
HAProxy 服务名称haproxySERVICE

第三步沿用这些值，网站配置中的路径和后端路由继续保留。更新前保存当前 PEM 和配置副本；若其他工具也在自动更新这个 PEM，先暂停其更新任务，避免同时写入。

第三步：安装并配置 Hook ​

3.1 安装更新脚本 ​

在 HAProxy 服务器的 root 终端创建脚本文件：

bash
mkdir -p /root/.certiman/hooks
chmod 700 /root/.certiman/hooks
nano /root/.certiman/hooks/certiman-haproxy.sh

复制以下脚本，按代码后的说明填写开头三个值，再保存：

bash
#!/usr/bin/env bash
set -eu

# 按实际环境修改这三个值
TARGET="/etc/haproxy/certs/trustasia.com.pem"
CONFIG="/etc/haproxy/haproxy.cfg"
SERVICE="haproxy"

TMP="$(mktemp "${TARGET}.tmp.XXXXXX")"
trap 'rm -f -- "$TMP"' EXIT

cat "$CERTIMAN_CERT_PATH" > "$TMP"
printf '\n' >> "$TMP"
cat "$CERTIMAN_KEY_PATH" >> "$TMP"
chown root:root "$TMP"
chmod 600 "$TMP"
mv -- "$TMP" "$TARGET"

haproxy -c -f "$CONFIG" && systemctl reload "$SERVICE"
  • TARGET：填写第二步找到的 crt 后面的 PEM 完整路径。
  • CONFIG：填写第二步打开的 HAProxy 配置文件路径，默认值为 /etc/haproxy/haproxy.cfg。
  • SERVICE：填写 HAProxy 服务名，通常为 haproxy。

CERTIMAN_CERT_PATH 和 CERTIMAN_KEY_PATH 由 CLI 自动传入，保留原样。脚本将两者合并到 TARGET，设置文件为 root:root、0600，配置检查通过后才 reload。

保存后设置执行权限并检查 Bash 语法：

bash
chmod 700 /root/.certiman/hooks/certiman-haproxy.sh
bash -n /root/.certiman/hooks/certiman-haproxy.sh

bash -n 没有输出且没有报错，即表示语法检查通过，继续配置部署 Hook。

3.2 绑定部署 Hook ​

在同一 root 终端编辑 /root/.certiman/cc/certs/trustasia.com/cert.yaml，其中 trustasia.com 换成第一步 CLI 显示的订单主域名。配置下面的 deploy 和 renew 字段，保留订单、验证和其他配置：

yaml
deploy: /root/.certiman/hooks/certiman-haproxy.sh
renew:
  auto_cert: false
  auto_order: false

deploy 填刚保存的脚本路径，示例路径相同时可直接保留。保存配置后，进入第四步测试部署；网站正常后，再按第五步开启自动续期。

第四步：更新并验证网站访问 ​

在同一 root 终端执行，将 trustasia.com 换成第一步的订单主域名：

bash
certiman deploy -d trustasia.com

如果提示之前已部署成功而跳过，本次需要重新执行时使用：

bash
certiman deploy -d trustasia.com -f

这一步部署本机已有材料，不申请新证书。接入时若部署的是同一张证书，有效期不会变化。

4.1 检查网站访问 ​

确认部署命令没有报错，再在自己的电脑上打开浏览器，访问 https://trustasia.com/。把域名换成第二步记下的网站域名；端口不是 443 时加上实际端口，例如 https://trustasia.com:8443/。

  1. 确认打开的是自己的网站，浏览器没有“连接不安全”或证书错误提示。
  2. 点击地址栏左侧的网站信息按钮，进入连接信息并查看证书，确认域名是自己的网站、有效期与 CertCloud 订单中本次部署的证书一致。
  3. 浏览常用页面，确认图片、样式和登录等功能正常。

网站使用 CDN 等代理时，浏览器可能显示代理服务的证书，按证书检查说明核对 HAProxy 上的证书。

检查通过后，继续第五步开启自动续期。如果出现证书错误或网站无法访问，先按本文异常恢复处理。

第五步：开启并确认自动续期 ​

第四步验收通过后，在同一 root 账号下修改 cert.yaml 中已有的 renew 字段，保留其他配置：

yaml
renew:
  auto_cert: true
  auto_order: false

auto_cert 开启订单服务期内的自动续期；auto_order: false 表示不自动续订订单。保留对应的持久验证记录，或维护 DNS Hook，使后续域名验证可持续完成。

尚未注册系统计划任务时，在同一 root 终端执行 install；已经注册时只用 status 查看，无需重复安装。

bash
certiman cron install
certiman cron status

确认 certiman cron status 显示任务已注册。系统会定期执行 certiman cron，进入续期窗口后，CLI 获取新证书并调用已保存的部署 Hook。

不需要一直开着终端。已有企业计划任务负责运行 CLI 时，只保留一个执行来源，避免重复更新。

后续如何维护？ ​

在服务器的同一 root 终端查看证书状态、计划任务和诊断结果，将域名换成订单主域名：

bash
certiman status -d trustasia.com
certiman cron status
certiman doctor

检查 /root/.certiman/logs/ 中的错误，并关注实际网站访问。证书已下载但部署失败时，修复原因后重新执行第四步的部署命令，无需重新申请证书。

异常恢复 ​

配置检查发生在 PEM 替换后；检查失败时不会 reload，已替换的文件也不会自动恢复。需要恢复时，先将该证书的 renew.auto_cert 设为 false，确认任务已结束，再用第二步保存且仍有效的 PEM 副本恢复原路径，保持 root:root、0600 权限。

在服务器 root 终端执行，配置文件路径和服务名使用第三步 CONFIG、SERVICE 中填写的值：

bash
haproxy -c -f /etc/haproxy/haproxy.cfg && systemctl reload haproxy

完成后按第四步检查网站。certiman deploy 会重新安装 CLI 当前材料，不能用来恢复旧文件。

卸载 CertiMan（不再使用时） ​

在安装并注册计划任务时使用的 root 账号下，执行官方卸载脚本，按提示确认：

bash
curl -fsSL https://certiman.trustasia.com/uninstall.sh | sh

卸载脚本移除 CertiMan 注册的计划任务、程序和命令补全，默认保留 /root/.certiman 中的证书、私钥和授权数据。本文配置的 HAProxy PEM 文件、监听和路由不会因此删除，当前 HTTPS 服务仍使用已部署证书；后续更新需要自行安排。

如果另有企业计划任务调用 CLI，请停用对应任务，官方脚本只清理 CertiMan 自身注册的任务。部署脚本和你自行保存的 PEM、配置副本不由卸载脚本删除，确认不再需要后再另行清理。完整说明见官方卸载指引。

从合并文件提取私钥 ​

仅当原私钥保存在 HAProxy 的合并 PEM 中时使用本节。在服务器的 root 终端执行，将输入路径替换为现有 PEM，输出路径替换为已有受限目录中的新文件路径：

bash
umask 077
openssl pkey -in /etc/haproxy/certs/trustasia.com.pem -out /root/cert-files/privkey.pem

导出成功后，回到第一步，将 --private-key 填为导出的私钥路径，再接入已有订单。

找不到原始私钥时重新签发 ​

有匹配私钥时按第一步导入，不执行本节。只有无法找回原始私钥时才重新签发；将 YOUR_ORDER_ID 替换为实际订单号。

如果无法找回原始私钥，首次接管时指定订单并重颁发：

bash
certiman issue --reuse-order YOUR_ORDER_ID --on-existing-cert reissue

如果订单已由本机 CLI 管理，则使用已有配置，将域名替换为订单主域名：

bash
certiman issue -d trustasia.com --on-existing-cert reissue

两种方式根据接入状态选择一种。按提示完成验证或审核，回到第一步确认状态和材料，然后执行第四步部署并验收。

参考文档 ​

参考链接 ​