跳到主要内容
cPanel

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 中安装付费证书

图形化流程共五步:

  1. 登录 cPanel(https://服务器IP:2083),进入 安全 → SSL/TLS。
  2. 点击 管理 SSL 站点(Manage SSL Sites),在域名下拉框选中目标域名,再点 Autofill by Domain,cPanel 会尝试自动填充已有的证书与私钥。
  3. 三个输入框逐项粘贴:Certificate 贴叶子证书全文(含 BEGIN/END 行);Private Key 贴 example.com.key;CA Bundle 贴 ca_bundle.crt。
  4. 多站点共用 IP 时确认已启用 SNI,点 Install Certificate。
  5. 回到 域(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 即可,功能不受影响。

第七步:效果验证清单

部署完成后按顺序跑一遍,全部通过再收工。

  1. 链验证:openssl s_client -connect example.com:443 -servername example.com </dev/null 2>&1 | grep 'Verify return code',必须是 0 (ok)。
  2. 证书信息:接 | openssl x509 -noout -subject -issuer -dates -ext subjectAltName,确认 SAN 覆盖全部域名、日期正确。
  3. 跳转:curl -sSI http://example.com | head -n 3,应出现 301 与 Location: https://...。
  4. HTTPS 可访问:curl -sSI https://example.com | head -n 1,应为 HTTP/2 200。
  5. HSTS 头:curl -sSI https://example.com | grep -i strict-transport-security。
  6. TLS 版本下限:openssl s_client -connect example.com:443 -tls1_1 </dev/null,应握手失败。
  7. 混合内容:F12 Console 无 Mixed Content 警告;或 grep -rIn 'http://' --include='*.html' /home/example/public_html | grep -v 'http://www.w3.org'。
  8. 到期监控: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 即说明顺序正确。

内容审核

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