文档中心

Appearance

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

CertiMan CLI 从 CertCloud 获取证书并安装到 Nginx 当前使用的路径；部署 Hook 只检查配置并重新加载服务。

本文适用于 Linux 上由 systemd 管理、已有正常 HTTPS 网站的 Nginx。接管网站当前证书对应的订单，保留原证书路径和业务配置，不重新创建站点或绑定。

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

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

需要向多台服务器集中分发时，阅读 Ansible 集中管理教程。

方案是怎样的？ ​

CertiMan 安装新证书，再执行 deploy 中的配置检查和重载命令，无需另建复制脚本。

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

网络放行 ​

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

开始前准备什么？ ​

  • 一个已经能正常访问 HTTPS 的 Nginx 网站，nginx -t 检查通过。
  • 该网站对应的 CertCloud 订单和原私钥。
  • 服务器 root 权限；安装、接入和部署命令在这台服务器的同一个 root 终端执行，网站访问检查按第四步在客户端执行。

示例域名 trustasia.com 换成你的域名。本文使用普通文件路径；容器、非 root 服务或链接路径先看文末其他运行环境。

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

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

1.1 确认订单并安装 CLI ​

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

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

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

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

确认 whoami 输出为 root，按安装提示确认协议；已安装时无需重复安装。完整说明见官方安装文档。登录、接入、部署及计划任务使用同一个账号。

1.2 登录并导入原始私钥 ​

在运行 CLI 的环境中，以前述固定运行账号执行：

bash
certiman login status

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

CertiMan 浏览器登录授权确认

将订单号和与网站当前证书匹配的原始私钥路径替换为实际值，首次接入时执行：

bash
certiman issue --reuse-order YOUR_ORDER_ID --private-key /root/cert-files/privkey.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 验证： 如果每次签发都需要新的验证记录，就需要让 CertiMan 自动更新 DNS。先按 DNS 服务商配置 DNS 验证 Hook（自动写入验证记录的脚本）和 API 凭据；CertiMan 会将本次记录名、类型和值交给脚本，由脚本调用服务商 API 写入 DNS。具体配置见官方 DNS Hook 示例。确认自动写入可用后，再开启自动续期；仅安装 CertiMan 或配置 Nginx 重载命令，不会自动完成 DNS 验证配置。

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

先在浏览器确认网站的 HTTPS 能正常访问，再打开该网站的 Nginx 配置文件，找到对应的 server 配置块。确认其中的 server_name 是你要更新的网站域名，记下以下两项：

配置项记录什么下一步填入
ssl_certificate证书文件的完整路径output.fullchain_file
ssl_certificate_key私钥文件的完整路径output.key_file

第三步沿用这两个路径，网站配置中的路径不用改。若还有其他工具自动更新这两个文件，接入 CertiMan 前先暂停其更新任务，避免同时写入。

网站使用 CDN 等代理时，本文更新的是 Nginx 服务器上的证书，代理服务的证书需在对应平台单独管理。

第三步：配置证书输出与重载命令 ​

在服务器 root 终端编辑 /root/.certiman/cc/certs/trustasia.com/cert.yaml，域名目录按实际输出替换。先保存当前网站证书、私钥和配置的副本，再合并以下字段，保留订单、验证及其他配置：

yaml
output:
  formats: [pem]
  fullchain_file: /etc/nginx/tls/trustasia.com/fullchain.pem
  key_file: /etc/nginx/tls/trustasia.com/privkey.pem
deploy: 'nginx -t && systemctl reload nginx'
renew:
  auto_cert: false
  auto_order: false
  • fullchain_file：填写网站 ssl_certificate 后面的完整路径。
  • key_file：填写同一网站 ssl_certificate_key 后面的完整路径。
  • deploy：检查通过才 reload。服务名不是 nginx 时替换为实际名称。

执行部署时，CLI 会将证书复制到上述路径，再检查配置并重载 Nginx。保存配置后，继续第四步测试部署；网站正常后，再按第五步开启自动续期。

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

bash
certiman deploy -d trustasia.com

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

bash
certiman deploy -d trustasia.com -f

这会部署本机已有的证书，不重新申请。如果部署的仍是网站正在使用的同一张证书，有效期不会变化。

4.1 检查网站访问 ​

确认部署命令没有报错，再在自己的电脑上打开浏览器，访问 https://trustasia.com/。把 trustasia.com 换成你的网站域名，与第二步确认的 server_name 一致。

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

网站使用 CDN 等代理时，浏览器可能显示代理服务的证书，还需按证书检查说明核对 Nginx 上的证书。 检查通过后，继续第五步开启自动续期。如果出现证书错误或网站无法访问，先按本文异常恢复处理。

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

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

yaml
renew:
  auto_cert: true
  auto_order: false

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

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

bash
certiman cron install
certiman cron status

certiman cron install 为当前账号注册系统计划任务，Linux 默认通过用户级 crontab 每 12 小时执行一次 certiman cron。进入续期窗口后，CLI 下载材料并调用已保存的部署 Hook。确认系统 cron 服务正常；已有任务时用 status 查看，无需重复注册。

CLI 注册的计划任务由系统定期执行，不需要长期打开终端。已有企业任务负责运行 CLI 时，只保留一个执行来源，避免重复更新。

后续如何维护？ ​

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

检查 ~/.certiman/logs/ 中的错误，将续期失败、部署失败和待人工处理项接入已有告警流程。

证书已下载但部署失败时，修复原因后运行 certiman deploy -d trustasia.com；上次已成功但需要重新同步时添加 -f。无需为部署失败重新下单。

异常恢复 ​

关闭本证书的 renew.auto_cert，确认任务结束。CLI 安装失败时不执行 Hook，但不要假定所有文件都保持旧内容；检查实际证书和私钥。检查配置或 reload 失败后，已写文件不会自动回滚。

必要时把更新前保存、仍有效且配对的材料恢复到原路径，保持 root 所有、私钥 0600，执行 nginx -t && systemctl reload nginx 后按第四步验收。不要用 certiman deploy 恢复旧文件，它会再次安装 CLI 中的新材料。自动更新期间的备份沿用服务器备份安排；旧证书失效时应部署有效新材料。

卸载 CertiMan（不再使用时） ​

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

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

脚本移除 CertiMan 注册的计划任务、程序和命令补全，默认保留 /root/.certiman 中的证书、私钥及授权数据。Nginx 已部署的证书、路径和网站配置不删除，后续更新需自行安排。企业另建任务、部署脚本和备份需单独管理，完整说明见官方卸载指引。

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

仅在无法找回匹配私钥时执行；有私钥时按第一步导入即可。重颁发可能使旧证书失效，应安排换证时间并准备及时部署。

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

已由本机 CLI 管理时，改用 certiman issue -d trustasia.com --on-existing-cert reissue，域名替换为订单主域名。两种方式按接入状态选择一种。签发后确认材料，按第四步部署并验收；入口异常时按本文异常恢复处理。

相关文档 ​

其他运行环境 ​

本文适用于 Linux/systemd、root Nginx master 和普通证书文件路径。非 root 服务、容器或链接路径沿用自身安装及权限方案。CDN 等代理入口需分别更新和验收。

参考链接 ​