文档中心

Appearance

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

本文适用于已经使用 JKS 提供 HTTPS 的 Linux / Tomcat 10.1 网站。本文按 Linux 软件包安装的常见方式使用 tomcat10 服务、tomcat 用户和 tomcat 组；CertiMan CLI 生成 JKS，部署脚本（Hook）将它安装到网站原路径并重启 Tomcat。其他安装方式只需替换脚本中的实际服务名、用户、组和路径。

尚未启用 HTTPS 时，请先完成Tomcat 首次部署指南。本文脚本使用 tomcat10 服务、tomcat 账号和 /etc/tomcat10/ 目录，请按实际安装调整并验证。

操作流程： 接入已有订单 → 找到 JKS 配置 → 配置输出和部署脚本 → 部署并检查网站 → 按需开启计划任务。

方案是怎样的？ ​

CertCloud 签发证书，CertiMan CLI 将它转换为 JKS，Hook 安装文件并重启 Tomcat。网站只允许在指定时间重启时，按第五步安排执行时间。

图中展示允许自动重启时的定时执行来源，维护窗口场景见第五步。定期扫描只处理已开启自动续期的证书，满足续期条件才更新，不是每次扫描都重新签发。

网络放行 ​

服务器需能通过 HTTPS（443）访问 certiman.trustasia.com、certcloud.cn 和 api.certcloud.cn。使用 DNS 验证脚本时，还需访问 DNS 服务商 API。CLI 安装成功后若连接异常，运行 certiman doctor，按诊断说明检查；自定义服务地址以实际配置为准。网站继续使用原 HTTPS 端口，本文以 8443 为例。

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

1.1 确认订单并安装 CLI ​

在 CertCloud 打开现有订单，确认支持“自动交付”。进入接入引导，选择“命令行工具 CLI → Linux”，无需重新申请订单。通过 SSH 连接服务器，在同一 root 账号下完成安装、登录和后续部署：

CertCloud 订单中的 CertiMan CLI 接入引导，选择 Linux
bash
sudo -i
whoami
curl -fsSL https://certiman.trustasia.com/install.sh | sh
certiman version

确认 whoami 输出为 root，按提示确认协议；已安装时无需重复安装。详细说明见官方安装指引。

1.2 登录并导入原始私钥 ​

bash
certiman login status

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

CertiMan 浏览器登录授权确认

准备网站当前证书对应的 PEM 私钥，可使用原申请时保存的文件，或从 KeyManager 另行导出。只有 JKS 文件时，先按文末从 JKS 提取私钥操作，再回到这里。

将 YOUR_ORDER_ID 换成 CertCloud 接入引导中的订单号，将 /root/cert-files/privkey.pem 换成准备好的 PEM 私钥路径，执行：

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

已由本机 CLI 管理且材料齐全时不重复导入。确实无法取得匹配私钥时，再看文末找不到原始私钥时重新签发。

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 或配置 Tomcat 部署脚本，不会自动完成 DNS 验证配置。

第二步：确认当前 JKS 配置 ​

先在浏览器确认网站 HTTPS 正常，再打开 Tomcat 的 server.xml，找到该网站使用的 HTTPS <Connector> 配置。记下下面三项，第三步按表格填写：

网站当前配置用途第三步填入
certificateKeystoreFileTomcat 正在读取的 JKS 文件路径脚本的 TARGET
certificateKeystorePasswordJKS 密码output.password
certificateKeyAliasJKS 中证书条目的名称（alias）output.jks_alias

同时记下 <Connector port="..."> 中的 HTTPS 端口，第四步继续访问原网址。本文按常见安装值继续使用 tomcat10 服务、tomcat 用户和 tomcat 组；配置中的证书路径和网站设置不用改。非默认安装的确认方法见 3.2 的提示。

第三步：配置 JKS 输出与部署 Hook ​

3.1 配置 JKS 文件、密码和 alias ​

在同一 root 终端编辑 /root/.certiman/cc/certs/trustasia.com/cert.yaml，其中 trustasia.com 换成第一步的订单主域名。先保存副本，再合并以下字段，保留订单和验证配置：

yaml
output:
  formats: [jks]
  jks_file: trustasia.com.jks
  jks_alias: tomcat
  password: '替换为密钥库密码'
deploy: null
renew:
  auto_cert: false
  auto_order: false
  • jks_file：只填文件名，例如 trustasia.com.jks，下一节脚本的 JKS_NAME 使用相同名称。Tomcat 正在使用的完整路径填在下一步脚本的 TARGET，不要填到这里。
  • jks_alias、password：填写第二步记录的 alias 和密码。密码包含单引号时，在 YAML 的单引号内写成两个单引号。
  • deploy: null 和 auto_cert: false：准备期间先不执行部署和自动更新，验收通过后再开启。

保存后执行以下命令，将域名换成第一步的订单主域名。它下载已有证书并生成 JKS，不重新申请：

bash
certiman download -d trustasia.com -f

执行后，先确认输出中没有 JKS 转换失败提示，再查看生成的文件。下面的域名目录和 JKS 文件名按实际配置替换：

bash
ls -lh /root/.certiman/cc/certs/trustasia.com/converted/trustasia.com.jks

确认能看到该文件、大小不为 0，修改时间对应本次生成，再继续下一节。若有转换失败提示，按文末JKS 生成失败处理。

3.2 创建部署脚本 ​

在前述 root 会话中准备脚本目录：

bash
install -d -m 700 /root/.certiman/hooks

按常见安装方式保留下面的默认变量；如果服务名、用户、组或路径不同，替换为实际值。先保存当前 JKS、server.xml 及密码。将以下内容保存为 /root/.certiman/hooks/tomcat-jks.sh，目标目录沿用已有目录：

bash
#!/usr/bin/env bash
# 按实际环境填写以下变量
JKS_NAME='trustasia.com.jks'
TARGET='/etc/tomcat10/tls/trustasia.com.jks'
TOMCAT_USER='tomcat'
TOMCAT_GROUP='tomcat'
TOMCAT_SERVICE='tomcat10'

set -euo pipefail
umask 077
export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
: "${CERTIMAN_CONVERTED_DIR:?缺少转换产物目录}"
SOURCE="$CERTIMAN_CONVERTED_DIR/$JKS_NAME"
test -s "$SOURCE"
test ! -L "$TARGET"
test -d "$(dirname -- "$TARGET")"
install -m 640 -o root -g "$TOMCAT_GROUP" "$SOURCE" "$TARGET"
runuser -u "$TOMCAT_USER" -- test -r "$TARGET"
systemctl restart "$TOMCAT_SERVICE"
sleep 2
systemctl is-active --quiet "$TOMCAT_SERVICE" || { echo 'Tomcat 未保持运行，请使用备份恢复并检查日志' >&2; exit 1; }
echo 'JKS 文件已更新并提交服务重启，请继续验收 HTTPS 和应用。'

配置区变量说明：

  • JKS_NAME：CLI 转换产物的文件名，与 output.jks_file 一致。
  • TARGET：Tomcat 当前使用的 JKS 绝对路径，与 certificateKeystoreFile 一致。
  • TOMCAT_USER：Tomcat 服务实际运行用户，默认值为 tomcat；其他安装方式替换为实际值。
  • TOMCAT_GROUP：Tomcat 进程所属且用于读取 JKS 的组，默认值为 tomcat；它可以与用户名不同，其他安装方式替换为实际值。
  • TOMCAT_SERVICE：systemd 服务名称，默认值为 tomcat10；填写时可以省略 .service 后缀。

脚本先检查源 JKS 存在且非空，再复制到 TARGET，将属主和属组设为 root:Tomcat 服务组、权限设为 0640，让 Tomcat 服务账号可以读取，最后重启服务。output.jks_file 只控制生成文件名，安装和权限设置由这段脚本完成。异常处理见文末。

非默认安装：确认服务名、用户和组

服务名是 systemd 管理 Tomcat 的名称，不是网站名称。查找并确认实际值：

bash
systemctl list-units --type=service --all | grep -Ei 'tomcat|catalina'
systemctl list-unit-files --type=service | grep -Ei 'tomcat|catalina'
systemctl show tomcat10 -p User -p Group -p SupplementaryGroups -p MainPID

将 tomcat10 换成查到的服务名；用 id <User> 查看用户所属组，SupplementaryGroups= 中的组也可以用于读取 JKS。多个服务中选择状态为 active (running) 且对应当前网站的一个。Tomcat 不是由 systemd 管理时，本文的 systemctl restart 命令不适用。

设置权限并检查语法：

脚本通过路径直接执行，使用 0700。语法检查不执行安装或重启，也不代表部署通过。

bash
chmod 700 /root/.certiman/hooks/tomcat-jks.sh
bash -n /root/.certiman/hooks/tomcat-jks.sh

3.3 绑定部署 Hook ​

回到 3.1 编辑的 cert.yaml，将 deploy: null 改为下面的脚本路径：

yaml
deploy: /root/.certiman/hooks/tomcat-jks.sh

第四步：在维护窗口更新并验收 ​

在允许重启网站的时间，于同一 root 终端执行。trustasia.com 换成第一步的订单主域名：

bash
certiman deploy -d trustasia.com

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

bash
certiman deploy -d trustasia.com -f

出现“JKS 文件已更新并提交服务重启”且命令没有报错后，等待网站启动，在自己的电脑上用浏览器打开原 HTTPS 地址。例如 https://trustasia.com:8443/：域名换成自己的网站域名，端口使用第二步记下的值；原有页面路径继续保留。

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

使用 CDN 等代理时，浏览器可能显示代理服务的证书，按证书检查说明核对 Tomcat 上的证书。检查通过后再进入第五步；启动报错或网站异常时，先按本文异常恢复处理。

第五步：按需开启自动续期 ​

第四步验收通过后，只有业务允许无人值守重启时，才开启下面的自动续期。当前 Hook 每次部署都会重启 Tomcat，auto_cert: true 和 cron install 不提供维护窗口控制。 如果业务只允许在维护窗口变更，保持 renew.auto_cert: false，在维护窗口内手动执行第四步。

开启自动续期 ​

业务确认可在自动更新发生时重启，才使用本小节。修改原 renew 节点，保留其他字段：

yaml
renew:
  auto_cert: true
  auto_order: false

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

尚未注册任务时，在同一运行账号下执行：

bash
certiman cron install
certiman cron status

系统会定期执行这个任务，不需要一直开着终端。同一账号已注册任务时，只运行 certiman cron status 查看，不必重复安装。

续期完成后，CLI 下载材料并调用该证书配置的部署 Hook。若已有企业计划任务负责运行 CLI，先确认是否继续沿用，避免两套任务同时运行。

后续维护与异常恢复 ​

定期查看证书、计划任务和诊断结果：

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

检查 /root/.certiman/logs/ 中的错误，并关注实际 HTTPS 访问。JKS 已正确生成、只是安装或重启失败时，修复原因后执行第四步的部署命令。若 JKS 转换失败，先按下一节重新生成，无需重新申请证书。备份按自己的保留策略管理，恢复验证前不要删除。

JKS 生成失败 ​

CLI 1.0.2 在 JKS 转换失败时可能只输出警告，仍显示证书下载成功；显式指定的部署 Hook 也可能继续执行。看到 Could not produce jks 等提示时，先处理转换错误。本文脚本的 test -s 能阻止安装缺失或空的 JKS，但不能判断已有文件是否为本次证书。

先将这张证书的 renew.auto_cert 改为 false、deploy 暂设为 null，确认任务已结束。核对 output.jks_file 只填写文件名，并按错误提示修正配置，再执行 3.1 的下载命令，检查本次 JKS 已生成。随后按 3.3 重新绑定 Hook，在允许重启的时间完成第四步验收，再按第五步恢复自动更新。certiman deploy 不重新生成 JKS，直接重跑它不能修复转换失败。

异常恢复 ​

先将这张证书的 renew.auto_cert 改为 false，确认部署任务已结束。在服务器终端查看启动错误，TOMCAT_SERVICE 换成脚本里填写的服务名：

bash
TOMCAT_SERVICE="tomcat10"
journalctl -u "$TOMCAT_SERVICE" --since '10 minutes ago'

Tomcat 报告 JKS 密码或 alias 错误时，核对 cert.yaml 的 output.password、output.jks_alias 与 server.xml 中的配置。Hook 会先安装 JKS 再重启，加载失败时目标文件可能已更新；本文 Hook 不自动备份或回滚。

需要恢复时，把更新前自行保存、仍有效的 JKS 复制回原路径，保持 root:tomcat（实际服务组）和 0640，必要时恢复原 server.xml。直接重启服务并按第四步验收。自动更新期间的备份使用服务器备份安排。过期或已失效证书不能用于恢复。

停用自动化与卸载计划任务 ​

不再由 CertiMan 自动更新此 Tomcat 证书时，在对应 cert.yaml 中将 renew.auto_cert 改为 false，删除 deploy 字段，保留其他配置。确认没有更新任务正在运行后，可删除本文创建的 /root/.certiman/hooks/tomcat-jks.sh；若该脚本还被其他证书使用，不要删除。

如果当前 root 账号下的其他证书也不再需要 CertiMan 计划任务，执行：

bash
certiman cron uninstall
certiman cron status

该命令卸载当前 CLI 账号的计划任务，不是只停用 Tomcat 这一张证书。其他证书仍需要自动更新时，不执行卸载，只关闭对应证书的 renew.auto_cert。自行配置的企业任务需在原平台另行停用。

停用自动化不会删除证书或关闭 Tomcat HTTPS。保留 Tomcat 当前使用的 JKS、server.xml 和恢复备份，后续需在证书到期前手动更新或交由其他工具接管。上述操作不卸载 CertiMan CLI 程序，也不撤销平台订单。

卸载 CertiMan（不再使用时） ​

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

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

卸载脚本移除 CertiMan 注册的计划任务、程序和命令补全，默认保留 /root/.certiman 中的证书、私钥及授权数据。Tomcat 已部署的 JKS 和 server.xml 不会因此删除，当前 HTTPS 不受影响，后续证书更新需自行安排。企业另建任务、部署脚本和备份需单独管理。完整说明见官方卸载指引。

从 JKS 提取私钥 ​

只有 JKS、没有单独 PEM 私钥时使用本节；已经有私钥的读者跳过。在 Tomcat 服务器的 root 终端操作，需要 Java 的 keytool 和 OpenSSL。

先准备私钥输出目录。使用本文示例路径时执行：

bash
install -d -m 700 /root/cert-files

修改开头三个变量，整段执行：

bash
bash -c 'set -eu
umask 077
SOURCE_JKS="/etc/tomcat10/tls/trustasia.com.jks"
KEY_ALIAS="tomcat"
OUTPUT_KEY="/root/cert-files/privkey.pem"

if [ -e "$OUTPUT_KEY" ] || [ -L "$OUTPUT_KEY" ]; then
    echo "输出文件已存在，请另选路径，避免覆盖原私钥" >&2
    exit 1
fi
test -d "$(dirname -- "$OUTPUT_KEY")"
WORK_DIR=$(mktemp -d /root/jks-extract.XXXXXXXX)
trap "rm -f -- \"$WORK_DIR/entry.p12\" \"$WORK_DIR/privkey.pem\"; rmdir -- \"$WORK_DIR\"" EXIT
keytool -importkeystore \
    -srckeystore "$SOURCE_JKS" -srcstoretype JKS -srcalias "$KEY_ALIAS" \
    -destkeystore "$WORK_DIR/entry.p12" -deststoretype PKCS12
openssl pkcs12 -in "$WORK_DIR/entry.p12" -nocerts -nodes -out "$WORK_DIR/privkey.pem"
openssl pkey -in "$WORK_DIR/privkey.pem" -check -noout
install -m 600 "$WORK_DIR/privkey.pem" "$OUTPUT_KEY"
echo "私钥已保存到：$OUTPUT_KEY"
'
  • SOURCE_JKS：现有 JKS 文件的完整路径。
  • KEY_ALIAS：server.xml 中 certificateKeyAlias 的值。没有记录时，按首次部署篇的查询步骤取得。
  • OUTPUT_KEY：未加密 PEM 私钥的保存路径，使用已存在的目录，不能覆盖已有文件。

keytool 会提示设置临时 PKCS#12 密码并输入 JKS 密码；私钥密码不同时按提示输入。随后 OpenSSL 提示输入密码时，填写刚设置的临时 PKCS#12 密码。看到“私钥已保存到……”后，回到 1.2，将输出路径填入 --private-key 导入。原 JKS 不会被修改；确实无法取得私钥时再看下一节。

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

有匹配私钥时按第一步导入，不执行本节。找不到时先安排换证时间，重颁发可能使旧证书失效。

首次接管订单时执行：

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

已由本机 CLI 管理时使用原配置：

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

根据接入状态选择一种，域名替换为订单主域名。签发后回到第三步生成 JKS，再按第四步部署并验收。部署异常按本文异常恢复处理；重颁发后旧证书可能失效，不能保证恢复旧备份即可恢复访问，应及时部署新证书。

参考文档 ​

JKS 输出路径与独立转换命令 ​

CLI 1.0.2 的 output.jks_file 与 PEM 的 output.fullchain_file、output.key_file 用途不同，不能作为 JKS 的额外安装位置。实测 output.output_file 和 output.jks_output_file 都会因字段不存在而报错。

独立的 certiman convert --to jks --out-file <完整路径> 可以把 JKS 生成到指定位置，实测转回 PEM 后证书和私钥与输入一致。但 --out-file 是转换命令参数，不是 cert.yaml 的自动安装字段；以 root 运行时，生成的文件为 root 所有、权限 0600，还需设置 Tomcat 的读取权限。本文通过部署脚本完成安装、权限设置和重启。

参考链接 ​