跳到主要内容
Tomcat

JoySSL 证书 Tomcat 安装部署实战:PFX/JKS 配置、证书链修复与 HTTPS 验证

问题背景与根因:Tomcat 部署 SSL 证书为什么总在“链”和“密码”上翻车

JoySSL 是国产 CA,提供免费 DV 和价格较友好的付费证书,中文审核与本地化支持对国内用户较友好。把 JoySSL 签发的证书部署到 Tomcat,常见问题并不是证书没签发,而是文件类型、证书链、别名/密码、Connector 配置四类信息不一致。Tomcat 8.5+ 推荐直接使用 PFX/PKCS12,老版本 Tomcat 7/8 常用 JKS;PFX 中必须同时包含私钥、叶子证书和中间 CA,只放叶子证书会出现“浏览器正常、Java/curl/小程序报 PKIX”的典型故障。

另一个高频根因是有效期认知过时:目前公有 SSL/TLS 证书最长有效期不超过 398 天,JoySSL 免费 DV 常见为 90 天,Let’s Encrypt 也是 90 天,付费证书以签发页为准。续期后必须重新签发、替换 keystore 并重启或重载 Tomcat,不能只改系统时间。部署前先做两条检查:

openssl x509 -in /opt/ssl/example.com.crt -noout -subject -issuer -dates
openssl pkcs12 -in /opt/ssl/example.com.pfx -nokeys -passin pass:'PFX密码' | grep -c 'BEGIN CERTIFICATE'

第二条命令输出应大于等于 2,表示至少包含叶子证书和中间 CA;若为 1,说明链不完整,需要向 JoySSL 获取 fullchain 或中间 CA 后重新导出 PFX。

准备工作:证书、私钥、CSR 与文件权限

建议在 /opt/ssl 下集中存放文件,至少准备 fullchain.pem、example.com.key、example.com.pfx。若证书尚未签发,先生成 CSR 和私钥,提交 CSR 给 JoySSL,私钥必须留在本机:

mkdir -p /opt/ssl
openssl req -new -newkey rsa:2048 -nodes -keyout /opt/ssl/example.com.key -out /opt/ssl/example.com.csr -subj '/CN=example.com' -addext 'subjectAltName=DNS:example.com,DNS:www.example.com'

签发后先核对证书与私钥是否匹配。RSA 证书用 modulus 比对:

openssl x509 -noout -modulus -in /opt/ssl/example.com.crt | openssl md5
openssl rsa -noout -modulus -in /opt/ssl/example.com.key | openssl md5

两条命令的 MD5 必须一致。ECC 证书不要用 modulus,改用公钥哈希:

openssl x509 -in /opt/ssl/example.com.crt -noout -pubkey | openssl md5
openssl pkey -in /opt/ssl/example.com.key -pubout | openssl md5

然后导出 PFX,-in 必须指向 fullchain.pem,-name 设置别名 tomcat,后面 Tomcat 配置要对应:

openssl pkcs12 -export -out /opt/ssl/example.com.pfx -inkey /opt/ssl/example.com.key -in /opt/ssl/fullchain.pem -name tomcat -passout pass:'StrongPass!2025'
chown tomcat:tomcat /opt/ssl/example.com.pfx
chmod 600 /opt/ssl/example.com.pfx

权限过宽会导致 Tomcat 启动时读取失败或被安全扫描告警;生产环境不要把 PFX 放在 Web 应用目录。

完整实操:Tomcat 8.5+ 使用 PFX/PKCS12 配置 HTTPS

编辑 $CATALINA_HOME/conf/server.xml,在 Service 内新增或替换 Connector。Tomcat 8.5+ 推荐 SSLHostConfig 写法,证书参数放在 Certificate 子标签中;端口可用 8443,若前面有 Nginx 卸载 SSL,则 Tomcat 可继续监听 8080。

<Connector port='8443' protocol='org.apache.coyote.http11.Http11NioProtocol' maxThreads='150' SSLEnabled='true' scheme='https' secure='true'>
  <SSLHostConfig protocols='TLSv1.2,TLSv1.3'>
    <Certificate certificateKeystoreFile='/opt/ssl/example.com.pfx'
                 certificateKeystorePassword='StrongPass!2025'
                 certificateKeystoreType='PKCS12'
                 certificateKeyAlias='tomcat' />
  </SSLHostConfig>
</Connector>

三个参数必须与 PFX 实际值一致:certificateKeystoreFile 是绝对路径,certificateKeystorePassword 是导出密码,certificateKeyAlias 是 -name 指定的别名。修改后执行:

$CATALINA_HOME/bin/shutdown.sh
$CATALINA_HOME/bin/startup.sh
ss -lntp | grep 8443
tail -n 100 $CATALINA_HOME/logs/catalina.out

如果服务器启用了 firewalld,放行端口:

firewall-cmd --add-port=8443/tcp --permanent && firewall-cmd --reload

云服务器还需在安全组放行 8443/tcp。CentOS/RHEL 开启 SELinux 时,非标准端口需放行:

semanage port -a -t http_port_t -p tcp 8443

启动日志出现“Server startup in”且无 keystore 异常,才说明 Connector 加载成功。

老版本兼容:keytool 转换 JKS 与 Connector 配置示例

Tomcat 7/8 老版本或既有运维规范要求 JKS 时,先用 keytool 查看 PFX 中的别名,再导入 JKS。别名不要想当然写 tomcat,必须以列表为准:

keytool -list -v -keystore /opt/ssl/example.com.pfx -storetype PKCS12 -storepass 'StrongPass!2025'

确认别名后执行导入,deststorepass 与 destkeypass 建议分开设置,但老 Tomcat 可能要求两者一致:

keytool -importkeystore -srckeystore /opt/ssl/example.com.pfx -srcstoretype PKCS12 -srcstorepass 'StrongPass!2025' -destkeystore /opt/ssl/example.com.jks -deststoretype JKS -deststorepass 'JksStorePass!2025' -destkeypass 'JksKeyPass!2025' -alias tomcat

验证 JKS 中证书链和私钥条目:

keytool -list -v -keystore /opt/ssl/example.com.jks -storepass 'JksStorePass!2025'

老版本 Connector 配置如下,keystorePass 填 JKS storepass,keyAlias 填导入别名:

<Connector port='8443' protocol='org.apache.coyote.http11.Http11NioProtocol' SSLEnabled='true' maxThreads='150' scheme='https' secure='true' keystoreFile='/opt/ssl/example.com.jks' keystorePass='JksStorePass!2025' keystoreType='JKS' keyAlias='tomcat' clientAuth='false' sslProtocol='TLS'/>

注意:JKS 是旧格式,新项目优先 PKCS12;转换后不要删除原 PFX,续期时还要用私钥和 fullchain 重新生成。若 keytool 报“别名不存在”,回到上一步复制列表中的 Alias name,不要手动猜。

配置对比:PFX 与 JKS、Tomcat 版本与关键参数

选择 keystore 类型时,核心看 Tomcat 版本和现有运维规范。下表可直接对照排错:

对比项 PFX/PKCS12 JKS
推荐版本 Tomcat 8.5+ Tomcat 7/8 老版本
配置位置 SSLHostConfig/Certificate Connector 属性
文件参数 certificateKeystoreFile keystoreFile
密码参数 certificateKeystorePassword keystorePass
类型参数 certificateKeystoreType=’PKCS12′ keystoreType=’JKS’
别名参数 certificateKeyAlias keyAlias
生成方式 openssl pkcs12 -export keytool -importkeystore

协议与端口建议:

项目 建议值 说明
HTTPS 端口 8443 或 443 443 需 root 或端口映射
TLS 协议 TLSv1.2,TLSv1.3 禁用 TLSv1.0/1.1
证书链 叶子+中间 CA 根证书通常不必下发
证书有效期 ≤398 天 JoySSL 免费 DV 常见 90 天

如果使用 Nginx 反向代理,Tomcat Connector 可只监听 127.0.0.1:8080,由 Nginx 配置 ssl_certificate 和 ssl_certificate_key;此时不要重复在 Tomcat 配 8443,否则排错面变大。

常见错误排查:真实报错与修复命令

先看日志再改配置,Tomcat 的 SSL 错误通常落在 catalina.out 或 localhost.log:

grep -iE 'SSL|Certificate|keystore|alias|handshake' $CATALINA_HOME/logs/catalina.out

报错 1:java.io.IOException: keystore password was incorrect。说明 certificateKeystorePassword 或 keystorePass 与文件实际密码不一致。用以下命令验证 PFX 密码,能输出信息即密码正确:

openssl pkcs12 -info -in /opt/ssl/example.com.pfx -noout

报错 2:java.io.IOException: Alias name tomcat does not exist。别名不存在,先 keytool -list 查看实际别名,再改 certificateKeyAlias/keyAlias。

报错 3:curl: (60) SSL certificate problem: unable to get local issuer certificate 或 openssl 输出 Verify return code: 21 (unable to verify the first certificate)。这是证书链不完整,不是 Tomcat 端口问题。检查:

openssl s_client -connect 127.0.0.1:8443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -c 'BEGIN CERTIFICATE'

结果小于 2 时,用 fullchain.pem 重新导出 PFX,而不是只放 example.com.crt。

报错 4:PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target。Java 客户端不信任服务端链,先修服务端中间 CA;内部 CA 场景还需把根证书导入客户端 truststore。

报错 5:ERR_SSL_VERSION_OR_CIPHER_MISMATCH。检查 SSLHostConfig 是否误删 TLSv1.2,或 JVM 是否禁用旧协议;用 openssl s_client -tls1_2 分段测试。

效果验证:openssl、curl 与 Java 握手检查

本机验证先看证书链和协议版本,Verify return code 应为 0 (ok):

openssl s_client -connect 127.0.0.1:8443 -servername example.com -showcerts </dev/null
openssl s_client -connect example.com:8443 -servername example.com -verify_return_error </dev/null

查看实际下发的主题、签发者和到期时间:

echo | openssl s_client -connect example.com:8443 -servername example.com 2>/dev/null | openssl x509 -noout -subject -issuer -dates

用 curl 强制解析到本机,避免 DNS 未切换导致误判:

curl -Iv https://example.com:8443 --resolve example.com:8443:127.0.0.1
curl -I --tlsv1.2 https://example.com:8443

Java 应用侧用 keytool 打印服务端证书,确认客户端信任链:

keytool -printcert -sslserver example.com:8443
java -Djavax.net.debug=ssl:handshake -jar app.jar

预期结果:openssl 显示 TLSv1.2 或 TLSv1.3;证书链数量至少 2;curl 返回 HTTP/1.1 或 HTTP/2 状态码而非 SSL 错误;Java 日志出现“Found trusted certificate”或握手完成。浏览器访问 https://example.com:8443 只作为辅助,不能替代 curl/Java 验证,因为浏览器会自动补链,容易掩盖服务端缺中间 CA 的问题。

上线注意事项:续期、安全加固与自动化

上线后把证书到期监控纳入巡检。JoySSL 免费 DV 常见 90 天,Let’s Encrypt 为 90 天,公有 SSL/TLS 证书最长不超过 398 天,任何“多年期”说法都应拆分为多次签发。建议提前 30 天检查:

openssl x509 -checkend 2592000 -noout -in /opt/ssl/example.com.crt
echo $?

返回 0 表示 30 天内不过期,返回 1 表示即将过期。续期流程是重新签发证书,重新生成 PFX/JKS,然后重启 Tomcat:

openssl pkcs12 -export -out /opt/ssl/example.com.pfx -inkey /opt/ssl/example.com.key -in /opt/ssl/fullchain.pem -name tomcat -passout pass:'StrongPass!2025'
systemctl restart tomcat

若使用 $CATALINA_HOME/bin/startup.sh 管理,则执行 shutdown.sh 后再 startup.sh,并确认进程确实重启:

ps -ef | grep tomcat
ss -lntp | grep 8443

安全加固至少做到:SSLHostConfig 只启用 TLSv1.2/TLSv1.3;PFX/JKS 权限 600 且属主为 Tomcat 运行用户;备份旧证书但不要放在 Web 目录;Nginx 卸载 SSL 时,后端 Tomcat 只监听 127.0.0.1。最后用 openssl s_client 再验一次 enddate,确保新证书已生效。

常见问题

优先用 PFX/PKCS12,Tomcat 8.5+ 原生支持 SSLHostConfig 和 Certificate 配置,少一次 keytool 转换;只有老版本 Tomcat 或既有规范要求 JKS 时再转换,转换后别名和密码必须与 Connector 一致。

多半是服务端证书链不完整,只下发了叶子证书。用 fullchain.pem 重新导出 PFX,确保 s_client 的 BEGIN CERTIFICATE 数量至少为 2,再重启 Tomcat;内部 CA 还需把根证书导入客户端 truststore。

公有 SSL/TLS 证书最长有效期不超过 398 天;JoySSL 免费 DV 常见为 90 天,付费证书以签发页为准,Let’s Encrypt 也是 90 天。到期必须重新签发并替换 keystore,不能只改配置。

先确认 Connector 指向的是新 PFX/JKS 文件,再执行 shutdown.sh 和 startup.sh 或 systemctl restart tomcat;用 openssl s_client 查看 enddate,并清理浏览器缓存和 CDN 缓存。

执行 openssl s_client -connect 域名:8443 -servername 域名 -showcerts </dev/null 2>/dev/null | grep -c ‘BEGIN CERTIFICATE’,结果至少为 2;Verify return code 应为 0 (ok)。

检查 server.xml 中 Connector 是否 SSLEnabled=’true’ 且端口为 8443,ss -lntp 确认监听;再放行 firewalld 和云安全组 8443/tcp,SELinux 环境用 semanage 放行端口。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。