跳到主要内容
Tomcat

DigiCert SSL 证书 Tomcat 安装部署教程:PFX/JKS 配置、证书链修复与验证

问题背景与根因:为什么 Tomcat 部署后仍报证书错误

Tomcat 默认 server.xml 中 8443 Connector 通常被注释,直接放入证书文件不会自动启用 HTTPS;必须配置 Connector 与 SSLHostConfig/Certificate,并确保 Tomcat 进程对证书文件有读权限。部署后仍报错的根因往往不是证书没装,而是证书链、格式、密码、SNI 或 Java 信任库问题。DigiCert 是商业 CA,CertCentral 支持批量签发与 API,EV 证书适合银行、证券、大型电商,但价格高于 DV;公开信任 TLS 证书最长有效期已缩短为 398 天,Let’s Encrypt 为 90 天,续期后必须替换文件并 reload/restart。常见根因包括:只部署叶子证书未带中间证书,浏览器可能补链而 curl、Java、小程序失败;PFX 密码、别名或 keystoreType 写错;证书 SAN 不含实际域名;多域名未配 SNI;旧 Java 不支持 TLS 1.2/1.3 或证书链算法;续期后配置仍指向旧文件。先用命令检查:openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName,输出应包含完整 SAN 和有效期。若 Not After 超过 398 天,说明证书不合规或文件不是当前公开信任证书。Tomcat 日志 catalina.out 中的 SSLHandshakeException 是定位入口,应先确认证书链长度和私钥匹配,再改配置,避免盲目重装。

准备证书文件:PFX、JKS、PEM 与证书链

从 DigiCert CertCentral 下载时优先选 PKCS12/PFX,Tomcat 8.5+ 原生支持;同时保留 fullchain.pem 与 privkey.pem 便于 openssl 校验。CSR 提交后签发的文件通常包括叶子证书、中间证书、根证书和 PFX。若 CA 只给 PEM,可用以下命令合成 PFX:

openssl pkcs12 -export -out /opt/ssl/example.com.pfx -inkey /opt/ssl/privkey.pem -in /opt/ssl/fullchain.pem -certfile /opt/ssl/chain.pem -name tomcat -passout pass:'StrongPass'

如果 fullchain.pem 已包含中间证书,可省略 -certfile;-name 指定别名,Tomcat 默认不强制别名,但 JKS 迁移时建议统一。查看 PFX 内容:openssl pkcs12 -info -in /opt/ssl/example.com.pfx -noout。验证证书与私钥匹配:

openssl x509 -noout -modulus -in /opt/ssl/fullchain.pem | openssl md5
openssl rsa -noout -modulus -in /opt/ssl/privkey.pem | openssl md5

两个 MD5 必须一致,否则 Tomcat 会报私钥不匹配。检查 SAN:openssl x509 -in /opt/ssl/fullchain.pem -noout -text | grep -A1 'Subject Alternative Name'。最后设置权限:chown tomcat:tomcat /opt/ssl/example.com.pfx && chmod 640 /opt/ssl/example.com.pfx,避免密码和私钥被其他用户读取。注意 PFX 密码不要写入公开仓库,建议用环境变量注入。

Tomcat 8.5+ 配置 PFX/PKCS12 完整步骤

第一步备份 cp $CATALINA_BASE/conf/server.xml $CATALINA_BASE/conf/server.xml.bak;第二步编辑 server.xml,找到 8443 Connector 或新增以下配置;第三步设置环境变量并重启;第四步放行防火墙端口。示例:

<Connector port='8443' protocol='org.apache.coyote.http11.Http11NioProtocol' maxThreads='150' SSLEnabled='true' scheme='https' secure='true'>
  <SSLHostConfig>
    <Certificate certificateKeystoreFile='/opt/ssl/example.com.pfx' certificateKeystorePassword='${env.TOMCAT_SSL_PASS}' certificateKeystoreType='PKCS12' />
  </SSLHostConfig>
</Connector>

在 systemd 的 tomcat.service 中加入 Environment='TOMCAT_SSL_PASS=StrongPass',或在 setenv.sh 中 export。不要直接把密码写进 server.xml 并提交到版本库。重启与检查:sudo systemctl restart tomcat、sudo ss -lntp | grep 8443。防火墙放行:sudo firewall-cmd --add-port=8443/tcp --permanent && sudo firewall-cmd --reload。启动后立即验证:openssl s_client -connect 127.0.0.1:8443 -servername example.com </dev/null,返回 Verify return code: 0 (ok) 说明链验证通过。若 Tomcat 启动失败,查看 tail -n 100 $CATALINA_BASE/logs/catalina.out,重点看 Keystore was tampered with 或 Alias name does not exist。Tomcat 10 的配置与 9 基本一致,包名仍为 org.apache.coyote.http11.Http11NioProtocol。

老版本 Tomcat 与 JKS:keytool 导入与别名管理

Tomcat 7 及更早版本常用 JKS。将 PFX 导入 JKS:

keytool -importkeystore -srckeystore /opt/ssl/example.com.pfx -srcstoretype PKCS12 -srcstorepass 'StrongPass' -srcalias tomcat -destkeystore /opt/ssl/example.com.jks -deststoretype JKS -deststorepass 'JksPass' -destkeypass 'JksPass' -destalias tomcat

查看链长度:keytool -list -v -keystore /opt/ssl/example.com.jks -storepass 'JksPass'。Certificate chain length 应为 3 或至少包含中间证书;若只有 1,说明只导入了叶子证书。补导中间证书:keytool -importcert -alias intermediate -file /opt/ssl/intermediate.pem -keystore /opt/ssl/example.com.jks -storepass 'JksPass'。Tomcat 配置中写 certificateKeystoreFile='/opt/ssl/example.com.jks' certificateKeystorePassword='JksPass' certificateKeystoreType='JKS'。JKS 已弃用,Tomcat 8.5+ 推荐 PKCS12;Java 9+ 默认 keystore 类型为 PKCS12,但 keytool 仍可生成 JKS。常见报错 keytool error: java.io.IOException: keystore password was incorrect 表示源 PFX 或目标 JKS 密码错误;Alias name tomcat does not exist 表示 -srcalias 与 PFX 实际别名不一致,先用 keytool -list -v -keystore example.com.pfx -storetype PKCS12 查看别名。

配置示例与参数说明:多域名、SNI 与 HTTP 强制跳转

多域名部署需要 defaultSSLHostConfigName 与多个 SSLHostConfig,Tomcat 依据 SNI 选择证书。示例:

<Connector port='8443' protocol='org.apache.coyote.http11.Http11NioProtocol' SSLEnabled='true' defaultSSLHostConfigName='example.com'>
  <SSLHostConfig hostName='example.com'>
    <Certificate certificateKeystoreFile='/opt/ssl/example.com.pfx' certificateKeystorePassword='${env.TOMCAT_SSL_PASS}' certificateKeystoreType='PKCS12'/>
  </SSLHostConfig>
  <SSLHostConfig hostName='api.example.com'>
    <Certificate certificateKeystoreFile='/opt/ssl/api.example.com.pfx' certificateKeystorePassword='${env.TOMCAT_SSL_PASS}' certificateKeystoreType='PKCS12'/>
  </SSLHostConfig>
</Connector>

参数说明:certificateKeystoreFile 必须写绝对路径;certificateKeystorePassword 支持 ${env.变量名};certificateKeystoreType 取 PKCS12 或 JKS;defaultSSLHostConfigName 是默认主机,hostName 必须与 SNI 域名一致。HTTP 跳转需让 8080 Connector 带 redirectPort='8443',并在 web.xml 增加 security-constraint,或用 RewriteValve 将 http 永久跳转到 https。多域名证书若为 SAN 证书,可一个 PFX 覆盖多个域名;若分域名签发,则每个 SSLHostConfig 指向独立 PFX。Tomcat 10 配置兼容,注意不要混用旧版 protocol=’HTTP/1.1′ 写法。

PFX、JKS、PEM 三种部署方式对比表格

Tomcat 8.5+ 首选 PKCS12/PFX;老系统用 JKS;PEM 直连适合容器和自动化。对比如下:

方式 适用版本 优点 缺点 关键配置 推荐场景
PFX/PKCS12 Tomcat 8.5+ 单文件含私钥和链,跨平台 密码需保护 certificateKeystoreType=’PKCS12′ 生产默认
JKS Tomcat 7 及更早 旧 Java 兼容好 已弃用,链管理繁琐 certificateKeystoreType=’JKS’ 遗留系统
PEM Tomcat 8.5+ 便于自动化和容器挂载 需分别管理证书和私钥 certificateFile/certificateKeyFile K8s、CI/CD

证书文件类型也要区分:叶子证书只含站点证书,不能单独部署;fullchain 含叶子与中间证书,是服务器部署的最小完整链;PFX 是打包格式。DigiCert 商业证书最长有效期 398 天,Let’s Encrypt 为 90 天,二者都需自动化续期。若使用 PEM 直连,Tomcat 的 Certificate 可配置 certificateFile='/opt/ssl/fullchain.pem' certificateKeyFile='/opt/ssl/privkey.pem' certificateChainFile='/opt/ssl/chain.pem',但生产环境仍建议 PFX 以减少文件错配。

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

按报错定位比反复重装有效。以下为 Tomcat 部署 DigiCert 证书时的高频真实报错:

  • java.security.cert.CertificateException: No name matching example.com found:证书 SAN 不含访问域名。执行 openssl x509 -in fullchain.pem -noout -ext subjectAltName 检查,重新签发含 DNS:example.com 的证书。
  • sun.security.validator.ValidatorException: PKIX path building failed / unable to find valid certification path to requested target:客户端信任库缺根证书,或服务器未发送中间证书。服务器改用 fullchain;客户端导入根证书:keytool -importcert -alias digicert -file root.pem -keystore cacerts -storepass changeit。
  • javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure:TLS 版本或加密套件不匹配。Tomcat SSLHostConfig 配 sslProtocol='TLS',Java 8 升级到 8u321+ 并启用 TLS 1.2。
  • keytool error: java.io.IOException: keystore password was incorrect 或 Keystore was tampered with, or password was incorrect:PFX/JKS 密码错误。用 openssl pkcs12 -info -in example.com.pfx -noout 验证密码后修正 certificateKeystorePassword。
  • curl: (60) SSL certificate problem: unable to get local issuer certificate:链不完整。执行 openssl s_client -connect example.com:8443 -showcerts </dev/null,证书数量至少 2 张。
  • 续期后不生效:先 reload/restart,再确认配置指向新文件,比较序列号 openssl s_client -connect example.com:8443 </dev/null 2>/dev/null | openssl x509 -noout -serial。

另外,JKS 别名错误会报 java.io.IOException: Alias name tomcat does not exist,用 keytool -list 查看实际别名;Tomcat 权限不足会报 java.io.FileNotFoundException: /opt/ssl/example.com.pfx (Permission denied),用 chown/chmod 修复。

效果验证:openssl、curl、Java 与浏览器四层检查

第一层 openssl 链检查:

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

第二层强制验证:openssl s_client -connect example.com:8443 -servername example.com -verify_return_error </dev/null,返回 Verify return code: 0 (ok) 即通过。第三层 curl:curl -vI https://example.com:8443 --resolve example.com:8443:127.0.0.1,不应出现 SSL certificate problem。第四层 Java:keytool -printcert -sslserver example.com:8443,或用 java -Djavax.net.debug=ssl:handshake -jar app.jar 查看握手日志。浏览器访问 https://example.com:8443,检查锁标志、SAN 和有效期,公开信任证书有效期不超过 398 天。最后用 SSL Labs 或 nmap --script ssl-enum-ciphers -p 8443 example.com 确认只启用 TLS 1.2/1.3 和合规套件。若 s_client 显示证书链只有 1 张,回到证书文件准备步骤补全 fullchain。

常见问题

公开信任 TLS 证书最长 398 天,DigiCert 也需遵守;Let’s Encrypt 为 90 天。到期前 30 天续期,替换 Tomcat 指向的 PFX/JKS 后 reload 或 restart。

优先 PKCS12/PFX,Tomcat 8.5+ 原生支持,单文件含私钥和证书链;JKS 仅用于 Tomcat 7 及更早的遗留系统,且需检查 Certificate chain length。

通常是服务器未发送中间证书,浏览器会自动补链,Java 不会。服务器应部署 fullchain 或完整 PFX,并用 openssl s_client -showcerts 确认链中至少包含叶子与中间证书。

分别计算证书和私钥的 modulus MD5:openssl x509 -noout -modulus -in fullchain.pem | openssl md5 与 openssl rsa -noout -modulus -in privkey.pem | openssl md5,两个结果一致即匹配。

替换 PFX/JKS 后需要 reload 或 restart,并确认 server.xml 指向新文件。用 openssl s_client 查看 serial 是否变化,若未变化说明进程仍加载旧证书或路径配置错误。

内容审核

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