CertiMan CLI 自动化实践：通过 Ansible 集中管理证书

CertiMan CLI 从 CertCloud 获取证书，Ansible 将证书和私钥复制到各台 Nginx 当前使用的路径，检查配置并重新加载服务。

本文适用于已有 Ansible 管理环境、需要为同一网站的多台 Nginx 更新同一张证书的团队。沿用已有订单、主机清单、SSH 账号和网站配置；目标服务器应已正常提供 HTTPS。尚未启用 HTTPS 时，先完成Nginx 首次部署指南。只管理一台服务器时，可阅读Nginx 本机自动化指南。

操作流程： 接入已有订单 → 确认节点和原路径 → 配置 Playbook 与 Hook → 部署并验收 → 开启自动续期。

方案是怎样的？

CLI 和 Ansible 在同一台管理节点运行，目标 Nginx 服务器无需安装 CertiMan。计划任务检查证书是否需要续期，获取新证书后再调用 Ansible 分发；不是每次执行任务都重新签发。

网络放行

管理节点需能通过 HTTPS（443）访问 certiman.trustasia.com、certcloud.cn 和 api.certcloud.cn。使用 DNS 验证脚本时，还需访问 DNS 服务商 API。管理节点通过 SSH 连接各目标服务器，默认端口为 22；目标服务器无需为此连接 CertCloud。自己的电脑需能访问网站 HTTPS。

开始前准备什么？

一个可用的 Ansible 管理环境，以及已有的主机清单和 SSH 凭据。
同一网站的各台 Nginx 已能正常提供 HTTPS，使用同一张证书；本文按 Linux/systemd、root 启动的 Nginx 示例操作。
网站当前证书对应的 CertCloud 订单和匹配私钥，私钥文件需在管理节点上可读。
Ansible 的 SSH 账号能在目标节点提权执行文件复制、nginx -t 和 reload，计划任务执行时无需交互输入密码。

下文的 管理节点指运行 CLI 和 Ansible 的机器，目标节点指提供网站服务的 Nginx 服务器。安装、登录、编辑文件和执行部署都在管理节点进行。

本文示例管理账号为 certops，工作目录为 /home/certops/cert-deploy。使用你现有的账号和目录替换即可，无需新建同名账号；后续登录、部署和计划任务都使用同一账号。

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

已由当前账号的 CLI 管理且材料齐全时，核对状态后可直接进入第二步。

1.1 确认订单并安装 CLI

在 CertCloud 打开网站当前证书对应的订单，确认支持“自动交付”。进入接入引导，选择“命令行工具 CLI → Linux”。

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

在管理节点以选定的运行账号打开终端，按提示安装并确认协议；已安装时无需重复安装：

bash

curl -fsSL https://certiman.trustasia.com/install.sh | sh
certiman version

显示版本号后继续。详细安装说明见官方安装文档。

1.2 登录并导入原始私钥

bash

certiman login status

缓存有效且账户正确时不重复授权；未登录时执行 certiman login。在浏览器中核对账户及应用名称为 CertiMan 后授权。管理节点没有浏览器时，在自己的电脑上打开 CLI 输出的授权地址。

将 YOUR_ORDER_ID 换成接入引导中的订单号，私钥路径换成管理节点上与网站当前证书匹配的私钥文件，再执行：

bash

certiman issue --reuse-order YOUR_ORDER_ID --private-key /home/certops/cert-files/privkey.pem

找不到匹配私钥时，参见文末重新签发说明。

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

接入已签发订单后，将域名换成订单主域名，查看状态和文件：

bash

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

确认已签发，且目录中已有 fullchain.pem、privkey.pem 和 cert.yaml。目录名以 CLI 输出为准。只有 CLI 提示尚有验证或审核待处理时，才按订单提示完成。

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

自动续期时，CertCloud 仍需验证域名归属，根据订单使用的方式处理：

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

普通 DNS 验证： 每次签发需要新验证记录时，在管理节点配置 DNS Hook 和服务商 API 凭据。CLI 将本次记录名、类型和值交给 Hook，由 Hook 调用服务商 API 写入记录。具体方法见官方 DNS Hook 示例。确认自动写入可用后再开启续期；配置 Ansible 部署任务不会自动完成 DNS 验证配置。

第二步：确认目标节点和原证书路径

在已有 Inventory 中选出需要更新的服务器。以下用 nginx_tls 组表示这些节点；组名按实际清单替换。示例内容如下，不要覆盖已有主机清单：

ini

[nginx_tls]
web01 ansible_host=192.0.2.11
web02 ansible_host=192.0.2.12

[nginx_tls:vars]
ansible_user=deploy

ansible_host 填目标服务器地址，ansible_user 使用已有 SSH 账号；这里的 deploy 是目标登录账号，与管理节点上的 certops 可以不同。示例地址需替换成真实地址。

查看各目标节点上该网站的 Nginx 配置，找到对应的 server 段。例如：

nginx

server {
    listen 443 ssl;
    server_name trustasia.com;
    ssl_certificate     /etc/nginx/tls/trustasia.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/tls/trustasia.com/privkey.pem;
    # 原网站业务配置
}

记下以下内容，第三步填写到 Playbook 中：

记录什么	下一步填入
`ssl_certificate` 后面的完整路径	`cert_target`
`ssl_certificate_key` 后面的完整路径	`key_target`
Nginx 服务名，通常为 `nginx`	`nginx_service`

沿用已有路径，不修改网站配置。更新前保存各节点当前证书、私钥及配置副本。记下网站域名和 HTTPS 端口，第四步用于验收。

在管理节点终端验证连接，将清单路径和组名换成实际值：

bash

ansible -i /home/certops/cert-deploy/inventory.ini nginx_tls -b -m ansible.builtin.ping

所有目标返回 SUCCESS、pong，且无需交互输入密码后继续；连接或提权报错时，先修正已有 SSH 和权限配置。

第三步：配置 Playbook 与部署 Hook

3.1 准备证书部署 Playbook

已有 Nginx Role 能完成证书复制、配置检查和 reload 时，沿用该任务，将 CLI 的两个源文件作为输入。下面的短 Playbook 展示同样的操作，可放入现有 Ansible 项目使用。

在管理节点的作业目录保存 deploy.yml，本文示例为 /home/certops/cert-deploy/deploy.yml。将 hosts 换成第二步的目标组，三个目标变量换成实际值：

yaml

---
- name: 更新各节点的 Nginx 证书
  hosts: nginx_tls
  become: true
  serial: 1
  any_errors_fatal: true
  gather_facts: false
  vars:
    cert_target: /etc/nginx/tls/trustasia.com/fullchain.pem
    key_target: /etc/nginx/tls/trustasia.com/privkey.pem
    nginx_service: nginx
  tasks:
    - name: 复制完整证书链到原路径
      ansible.builtin.copy:
        src: "{{ lookup('ansible.builtin.env', 'CERTIMAN_CERT_PATH') }}"
        dest: "{{ cert_target }}"
        owner: root
        group: root
        mode: '0644'

    - name: 复制私钥到原路径
      ansible.builtin.copy:
        src: "{{ lookup('ansible.builtin.env', 'CERTIMAN_KEY_PATH') }}"
        dest: "{{ key_target }}"
        owner: root
        group: root
        mode: '0600'
      no_log: true
      diff: false

    - name: 检查 Nginx 配置
      ansible.builtin.command: nginx -t
      changed_when: false

    - name: 重新加载 Nginx
      ansible.builtin.systemd_service:
        name: "{{ nginx_service }}"
        state: reloaded

src 读取的是管理节点上的证书文件，路径由 CLI 自动传入；dest 是目标 Nginx 服务器上的原路径。无需配置 CLI 的 output.fullchain_file 或 output.key_file。

各节点路径相同时直接使用示例变量；路径不同时，把 cert_target、key_target 放到现有 Inventory 的各主机变量中，并删除 Playbook vars 中对应的两项，让各节点使用自己的路径。

Playbook 逐台更新，当前节点配置检查失败时不会 reload，也不会继续后面的节点。已写入的文件不会自动恢复，已完成的节点也不会自动回退。

在管理节点终端检查语法，目录和清单路径按实际值替换：

bash

cd /home/certops/cert-deploy
ansible-playbook -i inventory.ini deploy.yml --syntax-check

命令未报错并显示 playbook: deploy.yml 后，继续绑定 Hook。

3.2 配置部署 Hook

在管理节点保存 /home/certops/cert-deploy/deploy-ansible.sh，填写作业目录、清单、Playbook 和程序路径：

bash

#!/usr/bin/env bash
set -eu
WORK_DIR='/home/certops/cert-deploy'
INVENTORY='inventory.ini'
PLAYBOOK='deploy.yml'
ANSIBLE_BIN='/usr/bin/ansible-playbook'

cd "$WORK_DIR"
exec "$ANSIBLE_BIN" -i "$INVENTORY" "$PLAYBOOK"

WORK_DIR：已有 Ansible 作业目录。
INVENTORY、PLAYBOOK：清单和部署文件；相对路径以 WORK_DIR 为基准。
ANSIBLE_BIN：在当前账号终端执行 command -v ansible-playbook 得到的完整路径。

保存后执行：

bash

chmod 700 /home/certops/cert-deploy/deploy-ansible.sh
bash -n /home/certops/cert-deploy/deploy-ansible.sh

没有报错后，编辑管理节点的 ~/.certiman/cc/certs/trustasia.com/cert.yaml，域名目录以第一步输出为准。合并下面字段，保留订单和验证配置：

yaml

deploy:
  command: /home/certops/cert-deploy/deploy-ansible.sh
  timeout: 10m
renew:
  auto_cert: false
  auto_order: false

command 填刚保存的脚本完整路径；timeout 是整批部署的等待时间，示例为 10 分钟，按节点数量和实际耗时调整。保存后进入第四步，确认全部节点部署成功再开启自动续期。

第四步：分发并检查网站访问

在管理节点以同一 CLI 账号执行，将域名换成订单主域名：

bash

certiman deploy -d trustasia.com

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

bash

certiman deploy -d trustasia.com -f

这是部署本机已有证书，不重新申请；部署同一张证书时，有效期不会变化。

4.1 查看每台节点的执行结果

查看 Ansible 最后的 PLAY RECAP，确认第二步选定的每台服务器都列在结果中，且 failed=0、unreachable=0。出现失败时，修正对应节点的问题，再重新执行部署。

4.2 检查网站和各节点 HTTPS

在自己的电脑上用浏览器打开第二步记录的网站地址，例如 https://trustasia.com/，域名和端口使用实际值：

网站打开正常，没有证书错误提示。
从地址栏的网站信息中查看证书，确认域名正确、有效期与 CertCloud 订单中本次部署的证书一致。
浏览常用页面，确认图片、样式和登录等功能正常。

公共域名可能只连接到其中一个节点。还需从能访问各节点的管理节点或客户端终端逐台检查，下面以 192.0.2.11 为例：

bash

curl --noproxy '*' --resolve trustasia.com:443:192.0.2.11 \
  --connect-timeout 10 --max-time 30 --show-error https://trustasia.com/

将两个 trustasia.com 换成网站域名，IP 依次换成每台服务器地址，端口和页面路径使用实际值。确认没有证书或连接错误，返回的是预期网站内容；不要加 -k 跳过证书校验。此检查确认节点 HTTPS 可用；若怀疑仍使用旧证书，按证书检查说明核对该节点证书。

使用 CDN 等代理时，浏览器可能显示代理服务的证书，代理入口需单独更新。全部节点和网站检查通过后，继续第五步。

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

在管理节点以同一 CLI 账号修改第三步的 cert.yaml：

yaml

renew:
  auto_cert: true
  auto_order: false

auto_cert 开启订单服务期内的自动续期；auto_order: false 表示不自动创建付费续订订单，请提前安排订单续费。

已有统一调度任务时，让它以同一账号定期执行 certiman cron。没有现成任务时，在管理节点执行：

bash

certiman cron install
certiman cron status

确认任务已注册；已注册时只查看状态即可。两种执行来源选一种，不重复注册。任务执行时需能使用与手动部署相同的 SSH 凭据和提权权限。

进入续期窗口后，CLI 获取新证书并调用 Hook，由 Ansible 逐台更新。首次自动更新后，再按第四步查看每台节点和网站的结果。

后续如何维护？

在管理节点以同一 CLI 账号执行，将域名换成订单主域名：

bash

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

检查 ~/.certiman/logs/ 和 Ansible 执行结果。使用外部调度时，还需在该平台查看任务状态。证书已下载但部署失败时，确认原作业已经结束，修正原因后重新执行 certiman deploy；上次已成功但需要重跑时加 -f。

异常恢复

先将这张证书的 renew.auto_cert 设为 false，确认更新任务已结束。逐台查看结果，已成功节点不会因其他节点失败而自动恢复。

需要恢复时，在受影响的目标 Nginx 节点上恢复第二步保存、仍有效且配对的证书和私钥，保持私钥为 root 所有、权限 0600。再以有 sudo 权限的账号执行：

bash

sudo nginx -t && sudo systemctl reload nginx

服务名按实际值替换。按第四步检查节点和网站，修正更新问题后再开启自动续期。不要用 certiman deploy 恢复旧文件，它会再次分发 CLI 当前材料。

停用自动化与卸载

只停用此证书时，将其 renew.auto_cert 设为 false 并删除 deploy 字段。其他证书仍使用共用计划任务时，保留该任务。

当前账号下所有证书都不再需要 CLI 注册的任务时，在管理节点执行 certiman cron uninstall，再用 certiman cron status 确认。外部调度任务在对应平台停用。

不再使用 CLI 时，以安装时的账号按官方卸载说明执行：

bash

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

卸载默认保留 CLI 的证书、私钥和授权数据，不删除 Ansible 文件或各台 Nginx 已部署的证书。后续证书更新需自行安排。

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

有匹配私钥时按第一步导入即可。重颁发可能使旧证书失效，应先安排所有目标节点的换证时间。首次接管时执行：

bash

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

已由本机 CLI 管理时，使用 certiman issue -d trustasia.com --on-existing-cert reissue。订单号和域名替换为实际值，两种方式选择一种。签发后回到第四步分发并逐台验收。

CertiMan CLI 自动化实践：通过 Ansible 集中管理证书

方案是怎样的？

网络放行

开始前准备什么？

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

1.1 确认订单并安装 CLI

1.2 登录并导入原始私钥

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

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

第二步：确认目标节点和原证书路径

第三步：配置 Playbook 与部署 Hook

3.1 准备证书部署 Playbook

3.2 配置部署 Hook

第四步：分发并检查网站访问

4.1 查看每台节点的执行结果

4.2 检查网站和各节点 HTTPS

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

后续如何维护？

异常恢复

停用自动化与卸载

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

相关文档

特殊执行环境

参考链接

CertiMan CLI 自动化实践：通过 Ansible 集中管理证书 ​

方案是怎样的？ ​

网络放行 ​

开始前准备什么？ ​

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

1.1 确认订单并安装 CLI ​

1.2 登录并导入原始私钥 ​

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

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

第二步：确认目标节点和原证书路径 ​

第三步：配置 Playbook 与部署 Hook ​

3.1 准备证书部署 Playbook ​

3.2 配置部署 Hook ​

第四步：分发并检查网站访问 ​

4.1 查看每台节点的执行结果 ​

4.2 检查网站和各节点 HTTPS ​

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

后续如何维护？ ​

异常恢复 ​

停用自动化与卸载 ​

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

相关文档 ​

特殊执行环境 ​

参考链接 ​

CertiMan CLI 自动化实践：通过 Ansible 集中管理证书

方案是怎样的？

网络放行

开始前准备什么？

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

1.1 确认订单并安装 CLI

1.2 登录并导入原始私钥

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

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

第二步：确认目标节点和原证书路径

第三步：配置 Playbook 与部署 Hook

3.1 准备证书部署 Playbook

3.2 配置部署 Hook

第四步：分发并检查网站访问

4.1 查看每台节点的执行结果

4.2 检查网站和各节点 HTTPS

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

后续如何维护？

异常恢复

停用自动化与卸载

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

相关文档

特殊执行环境

参考链接