JoySSL 证书 Apache 部署实战:fullchain 配置、configtest 校验与证书链不完整排查
一、问题背景与根因:为什么“浏览器正常、程序报错”
Apache 部署 SSL 证书失败,多数情况原因不在证书本身,而在于证书链与版本配置差异。Chrome、Firefox、Safari 内置 AIA(Authority Information Access)补链能力,会按证书中的 URL 自动下载缺失的中间证书,所以即使你只部署了叶子证书,浏览器仍会显示小锁。但 curl、Java(Tomcat/Spring Boot)、Python requests、微信小程序、Android OkHttp 不做 AIA 补全,只认本地信任库,缺少中间证书时就直接握手失败。
第二个根因是 Apache 版本对证书链配置方式的要求不同:2.4.8 起 SSLCertificateChainFile 被标记为废弃,推荐把中间证书与站点证书合并成 fullchain 交给 SSLCertificateFile;2.2 与 2.4.8 以下必须用 SSLCertificateChainFile 单独指定。写错版本后,轻则链不完整,重则启动失败。
第三个根因是有效期与续期。按 CA/B Forum 基线要求,公开信任的 TLS 证书单张有效期上限为 398 天;Let’s Encrypt 为 90 天,JoySSL 免费 DV 证书同样按短期有效期签发(以控制台签发信息为准),付费证书最长 398 天。很多站点续期后只覆盖了文件却没有 reload,Apache 主进程仍持有旧证书的内存副本,于是出现“文件是新的、线上是旧的”。
第四个根因是协议过时:Chrome 98 起已移除 TLS 1.0/1.1 支持。若配置里沿用 SSLProtocol all -SSLv3,会把 TLS 1.0 一起打开,被扫描工具判定不合规。下面按“准备文件 → 写配置 → 校验 → 验证 → 排错 → 续期”的顺序完整走一遍。
二、证书文件准备:fullchain、私钥与 CSR 的对应关系
在 JoySSL 控制台下载 Apache 格式压缩包,通常含三个文件:example.com.crt(站点/叶子证书)、example.com.ca-bundle(中间证书)、example.com.key(私钥)。若只给了 crt 与 bundle 两个文件,就手动合并成 fullchain:
cat example.com.crt example.com.ca-bundle > example.com_fullchain.crt
顺序不能反:叶子证书在前,中间证书在后,末尾不要拼根证书(根证书由客户端信任库提供,拼上只会增大握手包)。合并后逐项核对:
# 1. 查看主体、签发者、有效期
openssl x509 -in example.com_fullchain.crt -noout -subject -issuer -dates
# 2. 列出链中所有证书,正常应为 2 张(叶子 + 中间)
openssl crl2pkcs7 -nocrl -certfile example.com_fullchain.crt | openssl pkcs7 -print_certs -noout
# 3. 校验证书与私钥是否匹配(RSA)
openssl x509 -noout -modulus -in example.com.crt | openssl md5
openssl rsa -noout -modulus -in example.com.key | openssl md5
# 4. ECC 证书用公钥比对,rsa -modulus 对 EC 私钥无效
openssl x509 -in example.com.crt -noout -pubkey | openssl md5
openssl pkey -in example.com.key -pubout | openssl md5
两个 md5 一致即匹配。再收紧权限,私钥必须 600 且属主 root,否则 Apache 可能读不到,安全扫描也会扣分:
sudo install -m 644 example.com_fullchain.crt /etc/ssl/example.com_fullchain.crt
sudo install -m 600 example.com.key /etc/ssl/example.com.key
sudo chown root:root /etc/ssl/example.com.key
注意 BEGIN RSA PRIVATE KEY(PKCS#1)与 BEGIN PRIVATE KEY(PKCS#8)Apache 2.4 都能读,无需转换;但带口令保护的私钥在重启时会阻塞输入,生产环境务必去掉口令。
三、Apache 配置实操:启用模块与 VirtualHost 完整示例
先安装模块。Debian/Ubuntu 用 a2enmod,RHEL 系装 mod_ssl:
# Debian / Ubuntu
sudo apt update && sudo apt install -y apache2
sudo a2enmod ssl headers rewrite
sudo systemctl restart apache2
# RHEL / CentOS / AlmaLinux / Rocky
sudo dnf install -y httpd mod_ssl
sudo systemctl enable --now httpd
配置文件位置:Debian 系放 /etc/apache2/sites-available/example.com-ssl.conf 后执行 a2ensite;RHEL 系直接放 /etc/httpd/conf.d/example.com-ssl.conf。完整示例:
<VirtualHost *:443>
ServerName example.com
ServerAlias www.example.com
DocumentRoot /var/www/example.com/public
SSLEngine on
SSLCertificateFile /etc/ssl/example.com_fullchain.crt
SSLCertificateKeyFile /etc/ssl/example.com.key
# Apache < 2.4.8 才需要,2.4.8+ 请保持注释
# SSLCertificateChainFile /etc/ssl/example.com.ca-bundle
SSLProtocol -all +TLSv1.2 +TLSv1.3
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305
SSLHonorCipherOrder off
SSLSessionTickets off
SSLUseStapling on
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
Header always set X-Content-Type-Options "nosniff"
ErrorLog ${APACHE_LOG_DIR}/example.com-ssl_error.log
CustomLog ${APACHE_LOG_DIR}/example.com-ssl_access.log combined
</VirtualHost>
SSLStaplingCache 必须写在全局配置(Debian 的 /etc/apache2/mods-enabled/ssl.conf 或 RHEL 的 /etc/httpd/conf.d/ssl.conf),写进 VirtualHost 会报 AH00526: Syntax error ... SSLStaplingCache not allowed in <VirtualHost> context:
SSLStaplingCache "shmcb:logs/ssl_stapling(32768)"
最后补上 80 端口跳转,避免用户走明文:
<VirtualHost *:80>
ServerName example.com
RewriteEngine on
RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>
四、三种证书链配置方式对比:按版本选对写法
先确认版本,再决定写法,这是最容易踩错的一步:
apache2 -v # Debian/Ubuntu
httpd -v # RHEL 系
| Apache 版本 | 链配置方式 | 关键指令组合 | 结果与注意 |
|---|---|---|---|
| 2.4.8 及以上(推荐) | 单文件 fullchain | SSLCertificateFile → fullchain.crtSSLCertificateKeyFile → .key |
链完整;SSLCertificateChainFile 已废弃,同时写可能告警 |
| 2.4.8 及以上(分离写法) | 叶子与中间证书分开 | SSLCertificateFile → 叶子.crtSSLCertificateChainFile → ca-bundle |
仍可用,但日志有 deprecated 提示,不建议新站采用 |
| 2.2.x / 2.4.8 以下 | 必须分离 | 同上 | 缺 SSLCertificateChainFile 必然链不完整,curl/Java 必报错 |
| 任意版本(错误做法) | 只配叶子证书 | 仅 SSLCertificateFile → 叶子.crt |
浏览器靠 AIA 补链显示正常,程序客户端全部失败 |
文件与指令的对应关系也要记牢:SSLCertificateFile 指向站点证书(2.4.8+ 可为 fullchain),SSLCertificateKeyFile 指向私钥,SSLCertificateChainFile 只放中间证书、绝不能放根证书。若你从 Nginx 迁移过来,Nginx 的 ssl_certificate 相当于 fullchain,ssl_certificate_key 相当于 key,可一一对应。
另外不要将 .key 的路径写到证书指令里,也不要把 ca-bundle 直接塞进 SSLCertificateFile 却漏掉叶子证书——这两种情况分别会触发密钥不匹配和 AH01909 域名不匹配告警。
五、配置校验与平滑重载:configtest 到 reload
改完配置先做语法检查,输出 Syntax OK 才允许重载,否则 reload 会失败并保留旧配置,容易误判“已经生效”:
sudo apachectl configtest # 等价 apache2ctl configtest / httpd -t
sudo apachectl -S # 列出 vhost 与 SNI 匹配,确认 443 命中正确站点
sudo ss -lntp | grep ':443' # 确认 443 已被 apache 监听
sudo systemctl reload apache2 # graceful 重载,不断开现有连接
什么时候必须 restart 而不是 reload:修改 SSLProtocol、SSLCipherSuite、SSLStaplingCache 等模块级参数,或更换监听端口、加载新模块时,建议 sudo systemctl restart apache2。仅替换证书文件用 reload 即可。
校验期常见报错与处理:
# 1) 文件不存在或为空
AH00526: Syntax error on line 12 of /etc/apache2/sites-enabled/example.com-ssl.conf:
SSLCertificateKeyFile: file '/etc/ssl/example.com.key' does not exist or is empty
# → ls -l 检查路径与权限,确认私钥属主 root、权限 600
# 2) 模块没装
AH00526: Syntax error ... Invalid command 'SSLEngine'
# → Debian: sudo a2enmod ssl;RHEL: sudo dnf install -y mod_ssl
# 3) headers 模块缺失
AH00526: Syntax error ... Invalid command 'Header'
# → sudo a2enmod headers
# 4) 证书与私钥不匹配(reload 后才暴露)
SSL Library Error: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch
# → 用第二节的 modulus/pubkey md5 比对,重新配对文件
还有一个隐蔽点:SELinux 开启的 RHEL 系,证书放在 /etc/ssl 以外(如 /home)会因安全上下文被拒,日志出现 AH02217 或直接 403。用 sudo restorecon -Rv /etc/ssl 或把文件放回标准目录即可。
六、部署验证:openssl s_client、curl 与在线扫描
不要只看浏览器小锁,用命令行验证链与有效期:
# 1. 看握手结果与 Verify return code,必须是 0 (ok)
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | grep -E "Verify return code|Protocol|Cipher"
# 2. 数一数服务端下发的证书条数,正常为 2(叶子 + 中间),1 说明链缺失
echo | openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null | grep -c "BEGIN CERTIFICATE"
# 3. 查看线上实际生效的证书主体、签发者、到期时间与 SAN
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -subject -issuer -dates -ext subjectAltName
# 4. 用 curl 模拟普通客户端
curl -vI https://example.com 2>>&1 | grep -E "SSL certificate verify|subject:|issuer:|expire"
# 5. 模拟 Java 客户端(Tomcat/Spring Boot 场景必测)
keytool -printcert -sslserver example.com:443 | head -20
关键判据:Verify return code: 0 (ok)、证书条数为 2、subjectAltName 覆盖所有访问域名(含 www 与泛域名匹配规则)、Protocol 为 TLSv1.2 或 TLSv1.3。
最后用 SSL Labs 或 JoySSL 自带的检测工具跑一次完整扫描,目标评级 A 以上:出现 Chain issues: Incomplete 就是链没配全;出现 TLS 1.0/1.1 enabled 说明 SSLProtocol 没写死;出现 HSTS not enabled 就检查 Header always set Strict-Transport-Security 是否在 443 的 VirtualHost 内。三条都通过,浏览器、curl、Java、小程序才会表现一致。
七、常见错误排查:真实报错与对应处理
| 报错/现象 | 根因 | 处理 |
|---|---|---|
curl: (60) SSL certificate problem: unable to get local issuer certificate |
只部署叶子证书,中间证书缺失 | 改用 fullchain;2.4.8 以下补 SSLCertificateChainFile |
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target |
JVM 不做 AIA 补链 | 补全链后重启 Tomcat/应用;必要时把中间证书导入 cacerts |
微信小程序 request:fail ssl hand shake error / errCode: -1 |
链不完整或仅支持 TLS 1.0/1.1 | 部署 fullchain,SSLProtocol -all +TLSv1.2 +TLSv1.3 |
AH01909: example.com:443 server certificate does NOT include an ID which matches the server name |
ServerName/SNI 与证书 SAN 不一致 | 补 SAN 重签,或修正 ServerName/ServerAlias |
AH02217: ssl_stapling_init_cert: can't retrieve issuer certificate! |
开了 OCSP Stapling 但缺中间证书 | 部署 fullchain;或先关闭 SSLUseStapling |
| 续期后浏览器仍显示旧证书 | 未 reload,主进程持有旧证书 | systemctl reload apache2 后重新验证 |
排查顺序建议固定为三步:先用 openssl s_client -showcerts 看服务端到底下发了什么(这一步能定位大部分问题),再用 apachectl configtest 排除配置语法,最后查 /var/log/apache2/error.log 或 /var/log/httpd/ssl_error_log 找 AH 开头的错误码。特别注意:浏览器显示正常不能作为验证通过的依据,必须用 curl 或 Java 客户端复测,因为只有它们会暴露链缺失问题。
八、续期与长期维护:别让证书悄悄过期
有效期规则先记清:公开信任的 TLS 证书单张上限 398 天,Let’s Encrypt 等免费 DV 为 90 天,JoySSL 免费 DV 同样短期签发,付费证书最长 398 天。建议在到期前 30 天完成续期,避免节假日翻车。
续期替换的标准动作只有四步,写成脚本可复用:
#!/usr/bin/env bash
set -euo pipefail
NEW_CRT=/root/joyssl/example.com_fullchain.crt
NEW_KEY=/root/joyssl/example.com.key
install -m 644 "$NEW_CRT" /etc/ssl/example.com_fullchain.crt
install -m 600 "$NEW_KEY" /etc/ssl/example.com.key
apachectl configtest
systemctl reload apache2
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null
| openssl x509 -noout -subject -enddate
再加一条到期监控,返回非 0 即告警:
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null
| openssl x509 -noout -checkend 2592000 || echo "证书将在 30 天内到期"
-checkend 2592000 表示检查 30 天(单位为秒)内是否过期,可挂到 cron 或 Zabbix/Prometheus 探针里。另外保留上一版证书与私钥副本(建议带日期后缀),一旦新证书链配错可在 1 分钟内回滚:cp -a /etc/ssl/example.com_fullchain.crt /etc/ssl/backup/$(date +%F).crt。
常见问题
不需要。2.4.8 起该指令已废弃,把中间证书拼在站点证书后面交给 SSLCertificateFile 即可,同时配置两者可能出现 deprecated 告警;2.4.8 以下版本则必须单独指定 ChainFile。
九成是证书链不完整。用 openssl s_client -showcerts 数证书条数,正常为 2 条(叶子+中间)。改用 fullchain 后 reload,再用 keytool -printcert -sslserver 复测即可。
RSA 证书用 openssl x509 -noout -modulus 与 openssl rsa -noout -modulus 分别取 md5,结果一致即匹配;ECC 证书改用 -pubkey 与 openssl pkey -pubout 比对公钥摘要。
Apache 主进程在内存中缓存证书,只覆盖文件不会重新加载。必须执行 systemctl reload apache2(graceful)或 restart;修改 SSLProtocol 等模块级参数时建议直接 restart。
按 CA/B Forum 要求,公开信任 TLS 证书单张有效期上限为 398 天;Let’s Encrypt 等免费 DV 为 90 天,JoySSL 免费 DV 同样短期签发,付费证书最长 398 天,建议提前 30 天续期。