cPanel 安装部署 SSL 证书完整教程:PEM 三件套、AutoSSL 与证书链排错
问题背景与根因:证书「装上了」为什么还不安全
在 cPanel 里点完 Install,SSL/TLS Status 页面变成绿色对勾,只说明 cPanel 认为该域名有一份可解析的证书与私钥,并不等于整条 TLS 链路正确。线上「装完证书仍然报错」的案例,九成集中在三个根因上。
根因一:证书链不完整。cPanel 的 Certificate 输入框只接受叶子证书,中间证书必须单独放进 CA Bundle。如果 CA Bundle 留空或只贴了一半,Chrome、Firefox 会通过 AIA 自动补链,看起来一切正常;但 curl、Java、微信小程序、Python requests、老版本 Android 不会补链,直接握手失败。
根因二:证书与私钥不匹配。同一台服务器跑多个站点、同一域名多次重新签发后旧 key 没换,很容易把 A 站点的私钥贴到 B 站点。Apache 启动时会直接拒绝加载,报 AH02572。
根因三:跳转与混合内容没处理。Force HTTPS Redirect 关闭时 http:// 仍可访问;页面里残留 http:// 的图片、JS、字体,浏览器地址栏虽是锁形图标,但控制台会报 Mixed Content,部分资源被静默拦截。
另外有两个时间点必须记牢:按 CA/B Forum 基线要求,公有 TLS 证书单张最长有效期为 398 天;Let’s Encrypt 与 cPanel AutoSSL 签发的免费 DV 证书为 90 天,靠到期前 30 天自动续期维持。行业已排定分阶段把上限压缩到 200 天、100 天、47 天,所以「手工装一次管一年」的旧习惯必须换成自动化续期加到期监控。同时 TLS 1.0/1.1 已被主流浏览器彻底弃用,cPanel 侧只应保留 TLS 1.2 与 TLS 1.3。
先用一条命令判断自己属于哪种情况:
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>&1 | grep -E 'Verify return code|depth='
输出 Verify return code: 0 (ok) 说明链完整;出现 unable to get local issuer certificate 或 unable to verify the first certificate,就是缺中间证书,直接看下一节。
第一步:准备 PEM 三件套并校验证书链
cPanel(Apache)需要的是 PEM 格式三件套,不要用 DER、PFX 或 JKS。从 CA 下载时选「cPanel / Apache」格式包,解压后通常得到 example.com.crt、example.com.key、ca_bundle.crt;部分 CA 只给一个 fullchain.crt(叶子加中间证书拼接),需要自己拆:
# 按 BEGIN CERTIFICATE 出现顺序拆分 fullchain
awk 'BEGIN{n=0} /BEGIN CERTIFICATE/{n++} {print > "part" n ".crt"}' fullchain.crt
# part1.crt 为叶子证书,part2.crt 起为中间证书
cat part2.crt part3.crt > ca_bundle.crt 2>/dev/null
随后做三项硬校验,任何一项失败都不要继续往下装。
1)查看证书主体、签发者、有效期与 SAN:
openssl x509 -in example.com.crt -noout -subject -issuer -dates -ext subjectAltName
确认 notAfter 与订单一致,且 SAN 里包含全部要访问的域名(example.com、www.example.com)。只在 CN 写域名、不写 SAN 的证书,现代浏览器已不再接受。
2)验证证书链能否闭合:
openssl verify -CAfile ca_bundle.crt -untrusted ca_bundle.crt example.com.crt
# 期望输出:example.com.crt: OK
3)确认证书与私钥是同一对:
openssl x509 -in example.com.crt -noout -pubkey | openssl md5
openssl pkey -in example.com.key -pubout | openssl md5
两行 md5 必须完全一致。老教程里的 openssl rsa -noout -modulus | openssl md5 只对 RSA 密钥有效,现在大量证书使用 ECDSA(P-256),执行会报 Not an RSA key,请改用上面的公钥对比法。
最后收权限:私钥 chmod 600,属主与 web 用户一致;文件放 /etc/ssl/example.com/ 或用户目录 /home/example/ssl/,绝对不要放在 public_html 下——那是公网可下载的目录,私钥泄漏等于证书作废。
第二步:在 cPanel 中安装付费证书
图形化流程共五步:
- 登录 cPanel(
https://服务器IP:2083),进入 安全 → SSL/TLS。 - 点击 管理 SSL 站点(Manage SSL Sites),在域名下拉框选中目标域名,再点 Autofill by Domain,cPanel 会尝试自动填充已有的证书与私钥。
- 三个输入框逐项粘贴:Certificate 贴叶子证书全文(含 BEGIN/END 行);Private Key 贴
example.com.key;CA Bundle 贴ca_bundle.crt。 - 多站点共用 IP 时确认已启用 SNI,点 Install Certificate。
- 回到 域(Domains)页面,打开 Force HTTPS Redirect,让 cPanel 自动写入 301 跳转。
WHM 侧(root)可用命令行做同样的事,适合脚本化批量部署:
whmapi1 installssl domain=example.com
crt="$(cat /etc/ssl/example.com/example.com.crt)"
key="$(cat /etc/ssl/example.com/example.com.key)"
cabundle="$(cat /etc/ssl/example.com/ca_bundle.crt)" --output=json
cabundle 参数千万不要省略,省略就等于主动制造链不完整。
装完必须让 Apache 重新加载配置,否则新证书不会生效:
/scripts/rebuildhttpdconf
/scripts/restartsrv_httpd
# EA4 环境下先做语法检查
/usr/local/apache/bin/apachectl configtest
configtest 输出 Syntax OK 才算过关。cPanel 会把证书副本写入 /var/cpanel/ssl/installed/,虚拟主机片段由 rebuildhttpdconf 生成,所以不要手改 httpd.conf 中 cPanel 托管的那一段,下次重建会被覆盖。若 Install 时报 The Certificate is not valid for the domain,说明证书 SAN 中没有当前域名,回去核对签发时的域名列表,而不是反复重装。
第三步:AutoSSL 与免费 DV 证书的自动化
不打算买付费证书,cPanel 自带的 AutoSSL 就能签发 90 天免费 DV 证书(默认 Let’s Encrypt,或 cPanel 自签 CA),并在到期前约 30 天自动续期。图形入口是 SSL/TLS Status → Run AutoSSL,但它一次只处理当前账户,排障时更推荐命令行:
# 单个用户
/usr/local/cpanel/bin/autossl_check --user=example
# 全服务器
/usr/local/cpanel/bin/autossl_check --all
# 强制重试之前失败的域名
/usr/local/cpanel/bin/autossl_check --user=example --force
日志在 /var/cpanel/logs/autossl/(按用户分文件)与 /usr/local/cpanel/logs/autossl.log,常见报错与对应处理:
DNS DCV failed:域名 A/AAAA 记录没指向本机,或开了 CDN 代理导致验证请求打到别处。先dig +short example.com确认解析。HTTP DCV failed:/.well-known/acme-challenge/被 .htaccess 重写规则、WAF 或强制 HTTPS 拦截,临时放行该路径。rate limit:Let’s Encrypt 有「同一注册域名每周 50 张」等限速,停手等窗口重置,不要反复点。CAA record prevents issuance:域名存在 CAA 记录但未授权该 CA,用dig CAA example.com查看并补上0 issue "letsencrypt.org"。
不需要 AutoSSL 的域名写进 /var/cpanel/autossl_excluded_domains,避免它去覆盖你手工安装的付费证书。AutoSSL 续期成功后 cPanel 一般会自动重载 Apache,但如果你改过配置模板,就要手动确认:
/scripts/restartsrv_httpd
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -enddate
看到的 notAfter 是新日期,续期才算真正落地。
第四步:配置示例——虚拟主机、强制跳转与 HSTS
cPanel/WHM 使用 EA4(EasyApache 4)时,自定义配置应放在 userdata 目录,靠 include 生效,这样 rebuildhttpdconf 不会清掉你的改动:
/etc/apache2/conf.d/userdata/ssl/2_4/example/example.com/ssl.conf
/etc/apache2/conf.d/userdata/std/2_4/example/example.com/https.conf
ssl.conf 示例(Apache 2.4.8 之后不再需要 SSLCertificateChainFile,把中间证书拼进 SSLCertificateFile 即可):
<VirtualHost 203.0.113.10:443>
ServerName example.com
ServerAlias www.example.com
DocumentRoot /home/example/public_html
SSLEngine on
# 顺序:叶子证书在前,中间证书在后
SSLCertificateFile /etc/ssl/example.com/fullchain.crt
SSLCertificateKeyFile /etc/ssl/example.com/example.com.key
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
SSLHonorCipherOrder off
SSLSessionTickets off
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
Header always set X-Content-Type-Options "nosniff"
</VirtualHost>
HSTS 首次上线建议先用 max-age=300 试跑一天,确认全站 HTTPS 无遗漏再改成一年——一旦下发长周期 HSTS,回退非常麻烦。
强制跳转有两种写法。cPanel 面板开关(Domains → Force HTTPS Redirect)本质就是写 .htaccess,也可以自己控制:
RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteRule ^(.*)$ https://%{HTTP_HOST}/$1 [R=301,L]
如果站点在反向代理或 CDN 后面,%{HTTPS} 可能永远是 off,改用:
RewriteCond %{HTTP:X-Forwarded-Proto} !https
RewriteRule ^(.*)$ https://%{HTTP_HOST}/$1 [R=301,L]
改完统一执行:
/usr/local/apache/bin/apachectl configtest && /scripts/restartsrv_httpd
第五步:证书方案与文件对照表
先看选型,再看每个文件该填到哪个框里。
| 方案 | 签发方 | 单张有效期 | 覆盖域名 | 验证方式 | 适合谁 |
|---|---|---|---|---|---|
| cPanel AutoSSL | Let’s Encrypt / cPanel CA | 90 天,自动续期 | 单域名 + www | DV(HTTP/DNS) | 个人站、博客、测试环境 |
| 付费 DV | 商业 CA | 最长 398 天 | 1–5 个 | DV | 中小企业官网 |
| 付费 OV | 商业 CA | 最长 398 天 | 多域名 | 组织验证 | 电商、政企、需展示主体 |
| 通配符 DV | 商业 CA | 最长 398 天 | *.example.com | DNS | 子域多、SaaS 多租户 |
398 天是当前 CA/B Forum 允许的上限,行业已排定逐步缩短到 200/100/47 天。无论买多长的证书,都要准备自动化续期与到期告警,别依赖手工记账。
| 文件 | 内容 | cPanel 字段 | Apache 指令 | 常见误用 |
|---|---|---|---|---|
| example.com.crt | 叶子证书 | Certificate | — | 把 fullchain 整段贴进去 |
| example.com.key | 私钥 | Private Key | SSLCertificateKeyFile | 复制时漏掉 BEGIN/END 行 |
| ca_bundle.crt | 中间证书(可多张) | CA Bundle | 拼进 SSLCertificateFile | 留空导致链不完整 |
| fullchain.crt | 叶子 + 中间证书 | 不建议直接填 | SSLCertificateFile | 顺序颠倒(中间在前) |
第六步:常见错误排查(含真实报错)
下面每条都是线上真实出现过的报错,按「报错原文 → 根因 → 处理」组织。
| 报错原文 | 根因 | 处理 |
|---|---|---|
curl: (60) SSL certificate problem: unable to get local issuer certificate |
缺中间证书 | 补齐 CA Bundle 后重启 httpd |
SunCertPathBuilderException: unable to find valid certification path to requested target |
Java 不补链 | 下发完整链,JDK 无需额外导入 |
request:fail ssl hand shake error(微信小程序) |
链不完整 / TLS 版本过低 / 证书过期 | 用 s_client 验链与协议版本 |
AH02572: Failed to configure at least one certificate and key for example.com:443 |
证书与私钥不匹配或路径错 | 比对公钥 md5,检查文件路径 |
AH02032: Hostname example.com provided via SNI and hostname www.example.com provided via HTTP are different |
SNI 与 Host 头不一致 | 两个域名都写进 ServerAlias 与 SAN |
NET::ERR_CERT_COMMON_NAME_INVALID |
访问域名不在 SAN 内 | 重新签发含该域名的证书 |
NET::ERR_CERT_AUTHORITY_INVALID |
自签证书或链错误 | 换受信 CA 证书 |
Mixed Content: The page at 'https://...' was loaded over HTTPS, but requested an insecure ... |
页面内残留 http:// 资源 | 改为 https:// 或加 CSP upgrade-insecure-requests |
浏览器正常但 curl/Java/小程序报错,就是典型的链不完整,浏览器靠 AIA 补链掩盖了问题。确认方法:
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -c 'BEGIN CERTIFICATE'
返回 1 表示只下发了叶子证书,正常至少应为 2(叶子 + 中间)。修复:把中间证书拼到 SSLCertificateFile 指向文件的末尾,或在 cPanel 的 CA Bundle 里补全,再 /scripts/restartsrv_httpd。
续期后浏览器仍显示旧证书,按三个检查点依次排除:openssl x509 -noout -enddate 看服务端实际下发的是不是新证书;确认 Apache 已重载(systemctl reload httpd 不够时用 /scripts/restartsrv_httpd);若前面挂了 CDN,去 CDN 控制台更新源站证书或重试「严格 SSL」模式。
Apache 起不来,日志出现 SSLCertificateChainFile is deprecated:Apache 2.4.8+ 已把该指令标记为过时,删掉这一行、把中间证书拼进 SSLCertificateFile 即可,功能不受影响。
第七步:效果验证清单
部署完成后按顺序跑一遍,全部通过再收工。
- 链验证:
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>&1 | grep 'Verify return code',必须是0 (ok)。 - 证书信息:接
| openssl x509 -noout -subject -issuer -dates -ext subjectAltName,确认 SAN 覆盖全部域名、日期正确。 - 跳转:
curl -sSI http://example.com | head -n 3,应出现301与Location: https://...。 - HTTPS 可访问:
curl -sSI https://example.com | head -n 1,应为HTTP/2 200。 - HSTS 头:
curl -sSI https://example.com | grep -i strict-transport-security。 - TLS 版本下限:
openssl s_client -connect example.com:443 -tls1_1 </dev/null,应握手失败。 - 混合内容:F12 Console 无 Mixed Content 警告;或
grep -rIn 'http://' --include='*.html' /home/example/public_html | grep -v 'http://www.w3.org'。 - 到期监控:
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -checkend 2592000,30 天内到期会输出Certificate will expire,可直接接进 Zabbix/Prometheus 告警。
最后用 SSL Labs(https://www.ssllabs.com/ssltest/analyze.html?d=example.com)做交叉验证,配置正确应拿到 A 或 A+;若因 TLS 1.0 enabled 掉到 B,回到第四节的 SSLProtocol 收紧即可。验证通过后把上述命令做成每日巡检脚本,比事后救火省心得多。
常见问题
必须填。它承载中间证书,浏览器会自动补链所以看不出问题,但 curl、Java、微信小程序、部分 Android 不会补链,留空就会握手失败。把 CA 提供的 ca_bundle.crt 全文粘进去,或把中间证书拼到 Apache 的 SSLCertificateFile 文件末尾。
个人站、博客、测试环境用 AutoSSL 即可,90 天全自动续期且零成本;需要展示企业主体、要 OV 标识、或子域很多需要通配符时选付费证书,单张最长 398 天。但两者都要配到期监控,因为行业已计划把上限逐步缩短到 200/100/47 天。
先确认服务端实际下发:openssl s_client -connect 域名:443 -servername 域名 /dev/null | openssl x509 -noout -enddate。日期是旧的说明 Apache 没重载,执行 /scripts/rebuildhttpdconf 加 /scripts/restartsrv_httpd;日期是新的仍报错,检查是否挂了 CDN 缓存。
用公钥对比确认:openssl x509 -in cert.crt -noout -pubkey | openssl md5 与 openssl pkey -in key.key -pubout | openssl md5,两个 md5 不一致就是配错了文件。重新从 CA 下载包中取对应私钥,或对现有私钥重新签发 CSR,不要试图「修」私钥本身。
一般不影响,AutoSSL 的 HTTP DCV 会走 /.well-known/acme-challenge/ 白名单。但如果自定义 .htaccess 把所有请求 301 到 https 且丢了路径,或 WAF 拦截该目录,就会报 HTTP DCV failed,临时放行该路径后重跑 autossl_check –user=xxx –force。
有。SSLCertificateFile 或 fullchain.crt 必须叶子证书在前、中间证书在后,顺序颠倒会导致部分客户端握手失败但浏览器仍正常,极难排查。用 openssl verify -CAfile ca_bundle.crt -untrusted ca_bundle.crt cert.crt 返回 OK 即说明顺序正确。