跳到主要内容
cPanel

cPanel 部署 Let’s Encrypt SSL 证书完整教程:从证书链校验到 AutoSSL 自动续期

问题背景与根因:cPanel 部署 Let’s Encrypt 为何常报证书链错误

cPanel 站点通常由 Apache、Exim、Dovecot 共同使用同一套域名证书,部署 Let’s Encrypt 时不是“上传一个 .crt 就结束”,而是要让证书、私钥、中间证书链三者同时正确。Let’s Encrypt 是免费 DV 证书,当前公开有效期仍为 90 天,官方建议在剩余 30 天左右续期;付费 DV/OV 证书受 CA/Browser Forum 约束,单张证书最长有效期 398 天。把 90 天证书当成长周期证书手动维护,是续期后旧证书不生效的主要根因。

常见根因有四类:一是只上传 cert.pem 叶子证书,未提供 chain.pem 中间证书,浏览器可能靠缓存补链而正常,但 curl、Java、小程序会报 unable to get local issuer certificate;二是 Certificate 与 Private Key 不匹配,cPanel 会提示证书与私钥不匹配;三是 SAN 未覆盖 www 或 mail 域名,访问别名时触发域名不匹配;四是 AutoSSL 或 acme.sh 续期后未 reload Apache/Exim/Dovecot,配置仍指向旧文件。

先做两条诊断,确认是链问题还是私钥问题:

openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
curl -vI https://example.com

若 curl 输出 curl: (60) SSL certificate problem: unable to get local issuer certificate,优先检查 CA Bundle 是否遗漏中间证书;若浏览器报 NET::ERR_CERT_AUTHORITY_INVALID,则检查服务端是否只发送了叶子证书。cPanel 的 SSL/TLS Status 页面显示绿色 ✓ 只代表面板登记成功,不代表外部客户端能完整验证链,因此必须用 OpenSSL 和 curl 从外部复核。

准备证书文件:PEM 三件套与模数/链校验

cPanel 的 Manage SSL Sites 使用 PEM 格式三件套:Certificate 填域名证书,Private Key 填私钥,CA Bundle 填中间证书。Let’s Encrypt 通过 certbot 或 acme.sh 签发后,目录中通常有 cert.pem(叶子证书)、chain.pem(中间证书)、fullchain.pem(cert.pem + chain.pem)、privkey.pem(私钥)。手动部署时推荐 Certificate 用 cert.pem,CA Bundle 用 chain.pem;若面板只接受单文件,可把 fullchain.pem 放入 Certificate 并将 CA Bundle 留空或填入 chain.pem,安装后必须用 s_client 验证服务端发送的链。

上传前逐项校验。先看证书主题、签发者、有效期和 SAN:

openssl x509 -in cert.pem -noout -subject -issuer -dates -ext subjectAltName
openssl verify -CAfile chain.pem cert.pem

再核对证书与私钥模数,两个 MD5 必须一致:

openssl x509 -in cert.pem -noout -modulus | openssl md5
openssl rsa -in privkey.pem -noout -modulus | openssl md5

若不一致,说明私钥与证书不是同一次生成,不能靠改文件名解决,应重新签发或找回对应私钥。若 SAN 只包含 example.com 而站点同时使用 www.example.com,需要重新签发包含两个域名的证书。还要检查 fullchain 顺序:叶子证书在前、中间证书在后,可用 cat cert.pem chain.pem > fullchain.pem 生成。最后确认私钥权限为 600,避免 cPanel 安装时报权限错误:chmod 600 privkey.pem。完成这些校验后再进入面板,可排除大部分“安装成功但客户端报错”的问题。

cPanel 手动安装完整实操:Manage SSL Sites 上传与强制 HTTPS

登录 cPanel,进入 Security → SSL/TLS → Manage SSL Sites。在 Domain 下拉框选择要部署的域名,点击 Browse Certificate 上传 cert.pem,或直接把证书 PEM 内容粘贴到 Certificate 文本框;在 Private Key 文本框粘贴 privkey.pem 内容;在 CA Bundle 文本框粘贴 chain.pem 内容。三个字段齐全后点击 Install Certificate。安装完成后回到 SSL/TLS Status,确认域名条目显示绿色 ✓,并检查证书到期时间是否为新的 90 天周期。

如果使用 SSH 和 cPanel UAPI,可把证书文件先上传到 /home/用户名/ssl/,再执行:

uapi SSL install_ssl domain=example.com cert=/home/user/ssl/cert.pem key=/home/user/ssl/privkey.pem cabundle=/home/user/ssl/chain.pem

返回 JSON 中若 result.status 为 1 表示安装成功;若出现 The certificate is not valid for the domain,检查 SAN 是否包含该域名;若出现私钥不匹配,回到上一节核对模数。随后在 cPanel 的 Domains 页面开启 Force HTTPS Redirect,或为站点写入 .htaccess 重定向规则:

RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

开启强制 HTTPS 后,用 curl -I http://example.com 应返回 301 且 Location 指向 https。注意 cPanel 的 AutoSSL 与手动安装可能同时存在,若同一域名已有 AutoSSL 证书,手动安装后应在 SSL/TLS Status 中确认当前生效证书的签发者和到期时间,避免面板显示绿色但 Apache 仍加载旧文件。最后重启相关服务使配置生效:/usr/local/cpanel/scripts/restartsrv_httpd。

配置示例:AutoSSL、acme.sh 与 Apache 证书路径

如果希望全自动续期,优先用 cPanel 自带 AutoSSL。WHM 中进入 SSL/TLS → Manage AutoSSL,在 Providers 中勾选 Let’s Encrypt,保存后运行 AutoSSL。命令行可执行:

/usr/local/cpanel/bin/autossl_check --user=username
/usr/local/cpanel/bin/autossl_check --all
whmapi1 start_autossl_check_for_user user=username

AutoSSL 日志在 /var/cpanel/logs/autossl/,失败时重点看 DNS 解析、域名所有权验证和 rate limit。若使用 acme.sh 手动签发并部署,可用 webroot 模式:

acme.sh --issue -d example.com -d www.example.com --webroot /home/user/public_html
acme.sh --install-cert -d example.com --cert-file /home/user/ssl/example.com.cert.pem --key-file /home/user/ssl/example.com.key --ca-file /home/user/ssl/example.com.chain.pem --fullchain-file /home/user/ssl/example.com.fullchain.pem --reloadcmd 'uapi SSL install_ssl domain=example.com cert=/home/user/ssl/example.com.cert.pem key=/home/user/ssl/example.com.key cabundle=/home/user/ssl/example.com.chain.pem'

cPanel 为 Apache 生成的证书通常位于 /var/cpanel/ssl/apache_tls/example.com/,其中 combined 文件包含证书与私钥。排查时可查看虚拟主机实际引用的路径:

grep -R SSLCertificateFile /var/cpanel/ssl/apache_tls/example.com/
grep -R SSLCertificateKeyFile /var/cpanel/ssl/apache_tls/example.com/

不建议直接手改 cPanel 生成的 Apache 配置,否则面板更新或 AutoSSL 续期可能覆盖。若必须展示 Apache 片段,应保证 SSLCertificateFile 指向叶子证书、SSLCertificateKeyFile 指向私钥、SSLCertificateChainFile 指向中间证书,并在修改后执行 /usr/local/cpanel/scripts/restartsrv_httpd。对邮件服务,cPanel 会在安装 SSL 后同步 Dovecot/Exim 证书,可用 openssl s_client -connect mail.example.com:993 -servername mail.example.com 验证。

对比表格:AutoSSL、手动 Let’s Encrypt、付费证书与自签名

不同方案的核心差异在有效期、信任链和续期责任,而不是“能不能变绿”。下表用于选择 cPanel 部署方式:

方案 有效期 信任链 续期方式 cPanel 操作 适用场景
cPanel AutoSSL + Let’s Encrypt 90 天 公开信任,自动补中间证书 面板自动续期,建议保留 30 天余量 SSL/TLS Status → Run AutoSSL 个人站、批量域名、免维护
手动安装 Let’s Encrypt 90 天 需自行提供 chain.pem acme.sh/certbot 定时任务 + reload Manage SSL Sites 上传三件套 需要自定义 SAN、特殊验证
付费 DV/OV 证书 最长 398 天 公开信任,CA 提供 CA Bundle 到期前手动续费并重装 上传 CRT、KEY、CA Bundle 企业展示、合规要求
自签名证书 自定义 不受公开信任 手动重新生成 可安装但客户端需导入信任 内网测试、临时排障

选择时注意:Let’s Encrypt 的 90 天不是缺点,配合 AutoSSL 或 acme.sh 的自动续期比手动维护 398 天付费证书更不容易遗漏;付费证书最长 398 天,也不是“永久证书”,到期同样要更新。若站点面向 Java、小程序、API 客户端,必须确保服务端发送完整链,不能只看浏览器是否显示锁标志。自签名证书只适合内网测试,公网使用会触发 NET::ERR_CERT_AUTHORITY_INVALID。对 cPanel 多域名账户,AutoSSL 能覆盖主域、附加域和子域,但要求 DNS 已指向本机且 HTTP 验证可访问;若开启 DNS 泛解析或 CDN 代理,需确认验证路径没有被拦截。

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

报错 1:curl: (60) SSL certificate problem: unable to get local issuer certificate。说明服务端未发送中间证书或客户端缺少根证书。先执行 openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null,输出中应至少有两张证书;若只有一张,把 chain.pem 填入 CA Bundle,或改用 fullchain.pem。再用 openssl verify -CAfile chain.pem cert.pem 验证,返回 OK 才说明链完整。

报错 2:PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target。这是 Java 客户端典型报错,通常是服务端链不完整或 Java truststore 未导入中间证书。优先修复服务端链;若必须导入,执行 keytool -importcert -alias intermediate -file chain.pem -keystore cacerts,然后重启 Java 应用。

报错 3:cPanel 提示 The certificate is not valid for the domain 或浏览器报 NET::ERR_CERT_COMMON_NAME_INVALID。用 openssl x509 -in cert.pem -noout -ext subjectAltName 检查 SAN 是否包含当前访问域名和 www 别名,缺失则重新签发。

报错 4:证书与私钥不匹配。执行 openssl x509 -in cert.pem -noout -modulus | openssl md5 与 openssl rsa -in privkey.pem -noout -modulus | openssl md5,两个 MD5 不一致即确认。不要尝试修改证书,重新签发或找回正确私钥。

报错 5:续期后浏览器仍显示旧证书。检查 Apache 实际加载路径和进程是否 reload:/usr/local/cpanel/scripts/restartsrv_httpd;查看 AutoSSL 日志 /var/cpanel/logs/autossl/;用 openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -dates 对比到期时间。若时间未变,说明配置仍指向旧文件或 CDN 缓存未刷新。

效果验证:浏览器、curl、OpenSSL 与邮件服务检查

安装完成后不要只看 cPanel 的绿色 ✓。第一层验证是 cPanel:SSL/TLS Status 中域名显示 Active,证书到期时间正确,Force HTTPS Redirect 已开启。第二层用 curl 从本机检查 HTTP 跳转和 TLS 握手:

curl -I http://example.com
curl -vI https://example.com
curl --resolve example.com:443:服务器IP https://example.com

第三层用 OpenSSL 检查服务端发送的证书链、主题、签发者和有效期:

openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null | openssl x509 -noout -subject -issuer -dates
openssl s_client -connect example.com:443 -servername example.com -verify_return_error </dev/null

若 verify_return_error 返回 Verify return code: 0 (ok),说明链验证通过。第四层检查混合内容:浏览器 DevTools Console 若出现 Mixed Content: The page at https://... was loaded over HTTPS, but requested an insecure resource,需把图片、脚本、CSS 的 http:// 改为 https:// 或使用相对协议;也可在 .htaccess 加 Header always set Content-Security-Policy "upgrade-insecure-requests"。第五层检查邮件服务:openssl s_client -connect mail.example.com:993 -servername mail.example.com,确认 Dovecot 使用同一证书;Exim 可查 /var/cpanel/ssl/ 下对应文件。最后用 Java、小程序或 API 客户端各跑一次请求,避免浏览器正常但非浏览器客户端因链不完整失败。

常见问题

当前 Let’s Encrypt DV 证书有效期为 90 天,官方建议在剩余约 30 天时续期。cPanel AutoSSL 或 acme.sh 会自动处理续期,但续期后必须 reload Apache/Exim/Dovecot,并用 openssl s_client 确认服务端已加载新证书。付费证书单张最长 398 天,也不是永久有效。


Certificate 填域名叶子证书 cert.pem,CA Bundle 填中间证书 chain.pem,Private Key 填 privkey.pem。若面板只允许一个证书文件,可把 fullchain.pem 放入 Certificate,并确保 CA Bundle 不缺失。安装后用 openssl s_client -showcerts 检查服务端是否发送至少两张证书。


这是典型的链不完整:浏览器可能缓存或自动补链,curl/Java 不会。检查 CA Bundle 是否填入中间证书,优先使用 fullchain.pem;执行 openssl verify -CAfile chain.pem cert.pem 应返回 OK。Java 还需确认 truststore 含对应根证书,但应先修服务端链。


大多数 cPanel 站点优先 AutoSSL,自动续期、少维护;需要自定义 SAN、特殊验证或指定 acme.sh 时再手动安装。手动方案必须配置定时续期和 reload 命令,否则 90 天到期后会出现证书过期。两者都要用外部 curl/OpenSSL 验证链。


先执行 openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -dates 看到期时间;若未更新,检查 Apache 配置指向的证书路径、执行 /usr/local/cpanel/scripts/restartsrv_httpd,并查看 /var/cpanel/logs/autossl/。使用 CDN 时还要刷新边缘证书缓存。

内容审核

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