在 Tomcat 中首次部署 SSL 证书并启用 HTTPS

本文按 Linux 软件包安装的 Tomcat 10.1 示例开启 HTTPS：从 KeyManager 导出 JKS 证书文件，安装后修改 server.xml 并重启。本文默认使用服务名 tomcat10、运行用户和组 tomcat、配置目录 /etc/tomcat10/；如果你的安装方式不同，只替换实际的服务名、用户、组和路径。若网站由前方代理提供 HTTPS，应在代理处部署证书。

操作流程： 准备环境 → KeyManager 导出 JKS → 安装证书 → 配置 HTTPS → 重启并检查网站。

第一步：准备部署环境

• 在 Tomcat 服务器终端操作，具备 sudo 权限，原 HTTP 应用正常。
• 找到实际 server.xml 并保存副本。
• 已签发证书，并能从 KeyManager 导出带私钥的 JKS。
• 安排允许重启的时间。本文 HTTPS 端口为 8443，访问地址需带端口；已有其他端口时沿用原值。

1.1 使用常见安装值

本文按常见 Linux 软件包安装方式使用以下值：

TOMCAT_SERVICE="tomcat10"
TOMCAT_USER="tomcat"
TOMCAT_GROUP="tomcat"
sudo systemctl status "$TOMCAT_SERVICE"

确认状态为 active (running) 且对应当前网站后，保留这些值继续操作。服务名是 systemd 管理 Tomcat 的名称，例如 tomcat10.service 可以在命令中写成 tomcat10；它不是网站名称。

如果安装方式不是上述默认值

先查找实际服务，再替换后文变量：

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

第二步：导出并安装 JKS

2.1 从 KeyManager 导出

1. 在 CertCloud 的已签发订单中点击“下载证书 → 打开 KeyManager”，同步到保存了匹配私钥的 KeyManager 环境。
2. 在“证书管理 → 更多 → 导出证书”选择 Tomcat（JKS）。
3. 按页面提示设置并保存导出密码，后面查看和配置 JKS 都要使用这个密码。
4. 将导出的 JKS 上传到服务器的受限目录。本文使用 /root/cert-files/trustasia.com.jks，请替换为实际文件路径。

操作图示见KeyManager 下载与导出指南。首次部署不需要安装自动化工具。

2.2 记下 JKS 的 alias

alias 是 JKS 中证书条目的名称，第三步需要填写。在服务器终端将 SOURCE_JKS 换成刚上传的 JKS 路径，再执行：

SOURCE_JKS="/root/cert-files/trustasia.com.jks"
sudo keytool -list -storetype JKS -keystore "$SOURCE_JKS"

按提示输入导出密码，找到类型为 PrivateKeyEntry 的条目，记下它的名称。例如条目名称是 tomcat，第三步的 alias 就填 tomcat；以你实际查到的名称为准。

2.3 安装到 Tomcat 可读的目录

按 1.1 的默认值或实际查到的值修改开头四个变量，在服务器终端整段执行，将 JKS 复制到 Tomcat 使用的证书目录。目标已有同名文件时先保存副本，命令会覆盖它。

sudo bash -c 'set -eu
SOURCE_JKS="/root/cert-files/trustasia.com.jks"
TARGET_JKS="/etc/tomcat10/tls/trustasia.com.jks"
TOMCAT_USER="tomcat"
TOMCAT_GROUP="tomcat"

TARGET_DIR=$(dirname -- "$TARGET_JKS")
install -d -m 750 -o root -g "$TOMCAT_GROUP" "$TARGET_DIR"
install -m 640 -o root -g "$TOMCAT_GROUP" "$SOURCE_JKS" "$TARGET_JKS"
if runuser -u "$TOMCAT_USER" -- test -r "$TARGET_JKS"; then
    echo "Tomcat 可以读取 JKS 文件"
else
    echo "Tomcat 无法读取 JKS 文件，请检查文件路径、服务账号及目录和文件权限" >&2
    exit 1
fi'

需要按实际环境替换的变量：

• SOURCE_JKS：替换为上传到服务器的 JKS 源文件的绝对路径，例如 /root/cert-files/trustasia.com.jks。
• TARGET_JKS：替换为安装后供 Tomcat 使用的 JKS 文件的绝对路径，例如 /etc/tomcat10/tls/trustasia.com.jks。第三步的 certificateKeystoreFile 必须填写相同路径。
• TOMCAT_USER：Tomcat 服务实际运行用户，默认值为 tomcat；使用其他安装方式时替换为实际值。
• TOMCAT_GROUP：Tomcat 进程所属且用于读取 JKS 的组，默认值为 tomcat；它可以与用户名不同，使用其他安装方式时替换为实际值。

只修改开头四个变量的值，TARGET_DIR 会自动取得目标目录。看到“Tomcat 可以读取 JKS 文件”后继续；如果提示无法读取，先核对上面的路径和服务账号。

这一步会把上传的 JKS 复制到 Tomcat 使用的证书目录，并设置读取权限：root 可读写，Tomcat 服务组可读。第三步配置使用安装后的 TARGET_JKS 路径。

第三步：为网站添加 HTTPS 入口

打开第一步找到的 server.xml，在网站所属的 <Service> 内、已有 <Connector> 旁加入下面这段 HTTPS 配置。原 HTTP 配置和网站设置保留：

<Connector port="8443"
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true">
    <SSLHostConfig>
        <Certificate certificateKeystoreFile="/etc/tomcat10/tls/trustasia.com.jks"
                     certificateKeystoreType="JKS"
                     certificateKeystorePassword="替换为密钥库密码"
                     certificateKeyAlias="替换为实际alias" />
    </SSLHostConfig>
</Connector>

填写以下四项，其他内容按示例保留：

字段	填写什么
port	HTTPS 访问端口，示例为 8443，需确认该端口未被占用且允许访问
certificateKeystoreFile	第二步 TARGET_JKS 的完整路径
certificateKeystorePassword	KeyManager 导出 JKS 时设置的密码
certificateKeyAlias	2.2 查到的 alias

若密码包含 &、< 或双引号，在 XML 中分别写成 &、<、"。例如，密码 Abc&123 应填写为 certificateKeystorePassword="Abc&123"，实际密码不变。

配置包含密码，应限制 server.xml 的读取权限，不将实际密码截图或公开。

保存文件后，在允许重启的时间执行下面的命令。TOMCAT_SERVICE 填第一步确认的服务名，本文为 tomcat10：

TOMCAT_SERVICE="tomcat10"
sudo systemctl restart "$TOMCAT_SERVICE" && sudo systemctl is-active "$TOMCAT_SERVICE"

重启会短暂中断连接。输出 active 后继续第四步；如果启动报错，先按文末的异常恢复处理。

第四步：检查网站访问

在自己的电脑上打开浏览器，访问 https://trustasia.com:8443/。把 trustasia.com 换成证书对应的网站域名，8443 换成第三步 port 中填写的端口；网站原来需要的页面路径继续保留。

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

以上均正常，就完成了 HTTPS 部署。使用 CDN 等代理或怀疑显示旧证书时，按证书检查说明核对 Tomcat 上的证书。

异常恢复

如果本次修改后 Tomcat 无法启动或网站无法访问，先用第一步保存的副本恢复 server.xml，再按第三步重启，确认原 HTTP 网站恢复。需要排查启动原因时，在服务器终端执行 sudo journalctl -u tomcat10 --since '10 minutes ago'，其中 tomcat10 换成实际服务名。重点核对 JKS 路径、密码、alias 和端口是否填对。

后续自动更新

需要自动更新时，继续Tomcat 自动更新指南，沿用本次配置的 JKS 路径、密码和 alias。自动化脚本会把新 JKS 安装到同一路径，设置读取权限后重启 Tomcat。

参考文档

参考链接

• Tomcat 10.1 SSL 配置
• Tomcat HTTP Connector 配置