Appearance
CertiMan CLI 自动化实践:Nginx 证书部署与自动续期
本文适用于运行在 Linux 上、由 systemd 管理的 Nginx 服务,网站应已正常提供 HTTPS。CertiMan CLI 在本机生成新私钥,并使用已有 CertCloud 订单申请重颁发,取得与新私钥匹配的证书,再沿用原有文件路径和网站配置完成更新。
CLI 将新证书和私钥写入指定路径,再执行部署 Hook(证书安装后执行的命令或脚本),检查 Nginx 配置并重载服务。
操作流程: 找到部署位置 → 接管已有订单 → 配置自动部署 → 更新并检查 → 开启计划任务。
方案是怎样的?
完成本教程中的首次更新测试,并确认网站正常后,再开启计划任务。任务只检查已开启自动续期的证书,满足续期条件后才更新。
本教程仅用于操作引导与示例演示。读者应自行评估生产环境的网络架构、HTTPS 入口、软件版本、部署方式及业务要求,对文中的命令、配置和脚本进行适配,并在测试环境验证后再应用于生产环境。
网络放行
服务器需能通过 HTTPS(TCP 443)访问 certiman.trustasia.com、certcloud.cn 和 api.certcloud.cn。使用 DNS 验证脚本时,还需访问 DNS 服务商 API。安装失败时,先查看安装命令的错误提示;CLI 已安装但登录或连接异常时,可运行 certiman doctor,按诊断说明检查。自定义服务地址以实际配置为准。
第一步:找到网站正在使用的证书路径
打开目标网站的 Nginx 配置,找到 server_name 对应网站域名的 server 配置块,记录以下路径。示例域名 example.com 请替换为实际值。
| 配置项 | 记录什么 | 第三步填入 |
|---|---|---|
ssl_certificate | 完整证书链文件路径 | output.fullchain_file |
ssl_certificate_key | 私钥文件路径 | output.key_file |
备份当前证书、私钥及网站配置,确认配置检查通过。本文命令适用于 Nginx 主进程以 root 身份运行、证书路径为普通文件的环境;其他部署方式见其他运行环境。若有其他工具更新这两个文件,请先确认接管方式,避免同时写入。
第二步:将已有订单接入 CertiMan CLI
本步骤由 CLI 在本机生成新私钥,并使用已有订单申请重颁发。开始前,请确认重颁发后旧证书是否会被吊销、何时失效,备份当前证书、私钥和网站配置,并安排所有使用该订单证书的服务器或平台及时换证。
本文以尚未由 CertiMan CLI 管理的已签发订单为例,首次将该订单接入自动更新。
确认订单并安装 CLI
在 CertCloud 打开网站当前证书对应的订单,在订单详情左下角确认支持“自动交付”。进入接入引导,选择“命令行工具 CLI → Linux”;没有对应入口时联系支持确认。

通过 SSH 连接服务器,在同一个 root 会话中安装并完成后续操作:
bash
sudo -i
whoami
curl -fsSL https://certiman.trustasia.com/install.sh | sh
certiman version确认 whoami 输出为 root,按安装提示确认协议;已安装时无需重复安装。完整说明见官方安装文档。登录、接入、部署及计划任务使用同一个账号。
登录并重颁发证书
在运行 CLI 的环境中,以前述固定运行账号执行:
bash
certiman login status如果登录状态仍有效,且登录的是办理该订单的账户,无需重新授权。未登录或凭据失效时,执行 certiman login。在浏览器中确认登录账户正确,且申请授权的应用为 CertiMan,然后完成授权。服务器没有浏览器时,可在自己的电脑上打开 CLI 输出的授权地址。

使用以下命令接管网站当前证书对应的订单。执行前,将 YOUR_ORDER_ID 替换为实际订单号:
bash
certiman issue --reuse-order YOUR_ORDER_ID --on-existing-cert reissueCLI 会在本机生成新私钥,并使用该订单提交重颁发申请,取得与新私钥匹配的证书。后续步骤将这张新证书部署到原网站,并配置自动更新。
按 CLI 提示完成域名验证;需要人工审核时,请按订单提示提交所需资料,并等待审核结果。如果 CLI 等待超时,可在处理待办后执行 certiman issue -d example.com 继续当前申请,避免重复提交重颁发。新证书签发后,及时将证书链和新私钥部署到目标服务。
确认签发状态和本地证书文件
重颁发完成后,查看状态和本地文件。确认本轮新证书已签发并保存;仍在验证或审核时先完成待办,再继续部署。
bash
certiman status -d example.com
ls -l /root/.certiman/cc/certs/example.com/将示例域名替换为订单实际主域名。确认已签发,且目录中已有 fullchain.pem、privkey.pem 和 cert.yaml。目录名由订单主域名决定,请以 CLI 输出为准。

确认后续域名验证可自动完成
自动续期时,CertCloud 仍需要验证域名归属。根据订单使用的验证方式,按下面对应的一种处理:
持久验证: 使用 dns-persist 时,按订单提示添加 TXT 记录;使用 dns-proxy 时,添加指向平台的 CNAME 记录。授权有效期间通常可以继续使用这些记录,无需每次续期修改。已经配置好的记录继续保留,不要在首次签发成功后删除,也不要配置会删除它们的清理操作。
普通 DNS 验证: 如果每次签发都需要新的验证记录,就需要让 CertiMan 自动更新 DNS。先按 DNS 服务商配置 DNS 验证 Hook(自动写入验证记录的脚本)和 API 凭据;CertiMan 会将本次记录名、类型和值交给脚本,由脚本调用服务商 API 写入 DNS。具体配置见官方 DNS Hook 示例。确认自动写入可用后,再开启自动续期;仅安装 CertiMan 或配置 Nginx 重载命令,不会自动完成 DNS 验证配置。
第三步:配置证书输出与重载命令
在服务器 root 终端编辑 /root/.certiman/cc/certs/example.com/cert.yaml,域名目录按实际输出替换。先保存当前网站证书、私钥和配置的副本,再合并以下字段,保留订单、验证及其他配置:
yaml
output:
formats: [pem]
fullchain_file: /etc/nginx/tls/example.com/fullchain.pem
key_file: /etc/nginx/tls/example.com/privkey.pem
deploy: 'nginx -t && systemctl reload nginx'
renew:
auto_cert: false
auto_order: falsefullchain_file:填写网站ssl_certificate后面的完整路径。key_file:填写同一网站ssl_certificate_key后面的完整路径。deploy:检查配置通过后重载 Nginx。服务名不是nginx时,请替换为实际名称。
执行部署时,CLI 会将证书复制到上述路径,再检查配置并重载 Nginx。保存配置后,继续第四步测试部署;网站正常后,再按第五步开启自动续期。
第四步:更新并验证网站访问
bash
certiman deploy -d example.com如果提示之前已部署成功而跳过,本次要重新执行部署时使用:
bash
certiman deploy -d example.com -f这会部署第二步取得的新证书与新私钥,不再次申请。使用证书指纹核对换证结果;新证书的到期时间由签发规则和订单剩余服务期决定,可能与旧证书相同。
确认部署命令没有报错,再在自己的电脑上打开浏览器,访问 https://example.com/。把 example.com 换成你的网站域名,与第一步确认的 server_name 一致。
- 确认打开的是自己的网站,浏览器没有“连接不安全”或证书错误提示。
- 点击地址栏左侧的网站信息按钮,打开连接信息和证书查看器,确认证书覆盖当前访问的域名,且仍在有效期内。比较网站返回证书与本次新证书的 SHA-256 指纹,确认一致。
- 浏览常用页面,确认图片和页面样式显示正常,登录等业务功能可用。
网站使用 CDN 等代理时,浏览器可能显示代理服务的证书,还需按证书检查说明核对 Nginx 上的证书。 检查通过后,继续第五步开启自动续期。如果出现证书错误或网站无法访问,先按本文异常恢复处理。
第五步:开启并确认自动续期
第四步验收通过后,在同一 root 账号下修改 cert.yaml 中已有的续期字段,保留其他配置:
yaml
renew:
auto_cert: true
auto_order: falseauto_cert 开启订单服务期内的自动续期;auto_order: false 表示不自动创建付费续订订单,请提前安排订单续费。
尚未注册系统计划任务时执行 install;已经注册时用 status 查看,无需重复安装。
bash
certiman cron install
certiman cron statuscertiman cron install 为当前账号注册系统计划任务,Linux 默认通过用户级 crontab 每 12 小时执行一次 certiman cron。满足续期条件后,CLI 申请并下载新证书,安装到指定路径,再执行部署 Hook。请确认系统 cron 服务正常运行。
CLI 注册的计划任务由系统定期执行,不需要长期打开终端。已有企业任务负责运行 CLI 时,只保留一个执行来源,避免重复更新。
后续如何维护?
bash
certiman status -d example.com
certiman cron status
certiman doctor检查 ~/.certiman/logs/ 中的错误,将续期失败、部署失败和待人工处理项接入已有告警流程。
证书已下载但部署失败时,解决部署错误后运行 certiman deploy -d example.com;上次已成功但需要重新部署时添加 -f。无需为部署失败重新下单。
异常恢复
将本证书的 renew.auto_cert 设为 false,确认更新任务已结束。CLI 写入证书文件失败时,不会执行部署 Hook。此时部分文件可能已经更新,请检查目标路径中的证书和私钥是否匹配。配置检查或服务重载失败时,已写入的文件不会自动恢复。
需要恢复时,将备份中仍有效、未被吊销且相互匹配的证书和私钥复制回原路径,文件属主设为 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 已部署的证书、路径和网站配置不删除,后续更新需自行安排。企业另建任务、部署脚本和备份需单独管理,完整说明见官方卸载指引。
相关文档
其他运行环境
本文示例使用 systemd 管理 Nginx,主进程以 root 身份运行,证书和私钥保存在普通文件中。以非 root 身份运行、使用容器或通过符号链接引用证书时,请按实际部署方式调整路径、权限及加载命令。CDN 等代理入口需分别更新和验收。
