ZeroSSL 证书 cPanel 安装部署实战:从 PEM 三件套到强制 HTTPS 全流程
问题背景与根因:cPanel 装 ZeroSSL 证书为什么反复失败
ZeroSSL 提供 90 天免费 DV 证书(支持 ACME 协议与网页流程签发)以及付费 DV/OV/EV 证书,是 cPanel 站长常用的 Let’s Encrypt 之外的替代方案。但大量案例显示:证书在浏览器里显示正常,curl、Java 客户端、微信小程序却握手失败;或者续期完成后站点仍在返回旧证书。问题九成不在签发环节,而在部署环节。
根因可归为四类:
- 证书链不完整:只上传了叶子证书(leaf certificate),漏掉中间证书 CA Bundle。桌面浏览器有 AIA 自动补链机制,看起来“正常”;但 curl(OpenSSL 默认不补链)、Java TrustStore、旧版 Android、小程序运行时不会补链,于是直接报错。
- 证书与私钥不匹配:多次申请后文件混用,或复制粘贴时串行,导致私钥和证书不是同一对密钥。
- 文件格式污染:用 Windows 记事本另存引入 CRLF 换行或 UTF-8 BOM 头,PEM 解析失败。
- 服务未重载:证书文件已替换,但 httpd 进程仍持有旧证书句柄。
有效期也必须重新认知:按 CA/Browser Forum 基线要求,当前公有 TLS 证书最长有效期为 398 天;Let’s Encrypt 与 ZeroSSL 免费 DV 均为 90 天。2026 年 3 月 15 日起单张证书上限缩短为 200 天,2027 年 3 月 15 日起为 100 天,2029 年起为 47 天。“装一次管几年”的做法已经彻底失效,自动化续期是必选项。
部署后最常见的真实报错如下,本文后续章节会逐条给出修复命令:
curl: (60) SSL certificate problem: unable to get local issuer certificate
[ssl:emerg] AH02565: Certificate and private key example.com:443:0 from /etc/ssl/example.com.crt and /etc/ssl/example.com.key do not match
小程序:request:fail ssl hand shake error
Java:sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
下面按“准备文件 → 自动签发 → 手动安装 → 配置示例 → 方案对比 → 排错 → 验证”的顺序完整走一遍。
准备 PEM 三件套:从 ZeroSSL 后台正确下载与校验
cPanel(Apache)只认 PEM 格式,标准三件套是:CRT(叶子证书)、KEY(私钥)、CA Bundle(中间证书包)。在 ZeroSSL 控制台进入对应证书详情页,点击 Download,选择 “Apache / cPanel” 或 “Other”,会得到一个 ZIP,解压后通常是:
certificate.crt:叶子证书,Subject 是你的域名;private.key:私钥,只在生成 CSR 时下载一次,丢失只能重签;ca_bundle.crt:中间证书,ZeroSSL 常见签发链为 USERTrust RSA CA 或 Sectigo RSA DV CA。
拿到文件后不要急着上传,先做三项校验。第一,确认域名与有效期:
openssl x509 -in certificate.crt -noout -subject -issuer -dates -ext subjectAltName
输出里必须能看到 notBefore、notAfter,并且 X509v3 Subject Alternative Name 中同时包含 example.com 与 www.example.com。如果只写了裸域,访问 www 就会触发 NET::ERR_CERT_COMMON_NAME_INVALID。
第二,确认证书与私钥配对。RSA 证书用模数比对:
openssl x509 -noout -modulus -in certificate.crt | openssl md5
openssl rsa -noout -modulus -in private.key | openssl md5
两行输出的 MD5 必须完全一致。如果是 ECDSA 证书(ZeroSSL 支持 ECC 签发),模数命令会报 Not an RSA key,改用公钥比对:
openssl x509 -noout -pubkey -in certificate.crt | openssl md5
openssl pkey -pubout -in private.key | openssl md5
第三,拼接 fullchain 并验证链路。cPanel 的 UAPI 安装接口要求 cert 与 cabundle 分开传,但 acme.sh 与 Nginx 习惯用 fullchain,所以两个文件都建议保留:
cat certificate.crt ca_bundle.crt > fullchain.crt
openssl verify -CAfile ca_bundle.crt certificate.crt
# 期望输出:certificate.crt: OK
chmod 600 private.key fullchain.crt
如果 openssl verify 报 unable to get issuer certificate,说明 ca_bundle 拿错了(例如误下成根证书或另一条链的中间证书),重新下载即可。私钥权限务必收紧到 600,避免被同服务器其他用户读取。
方案一:用 acme.sh + ZeroSSL ACME 自动签发并自动安装
cPanel 自带的 AutoSSL 默认签发厂商是 Sectigo,界面里并没有 ZeroSSL 选项,因此想用 ZeroSSL 的免费 90 天证书,最稳妥的做法是用 acme.sh 作为 ACME 客户端,再通过 UAPI 把证书灌进 cPanel。以下命令可直接执行(示例用户 example,域名 example.com)。
第一步,安装 acme.sh 并把默认 CA 切到 ZeroSSL。注意 acme.sh 新版本默认 CA 是 Let’s Encrypt,必须显式指定:
curl https://get.acme.sh | sh -s email=admin@example.com
source ~/.bashrc
acme.sh --set-default-ca --server zerossl
acme.sh --register-account -m admin@example.com --server zerossl
# 期望输出:Account registered.
ZeroSSL 需要 EAB(External Account Binding)凭据,acme.sh 会自动完成 EAB 注册,无需手工去后台取 KMAC。
第二步,签发证书。站点可公网访问时用 webroot 模式,注意 webroot 必须是域名实际根目录:
acme.sh --issue -d example.com -d www.example.com
-w /home/example/public_html --server zerossl
需要泛域名时改用 DNS API 模式,例如 Cloudflare:
export CF_Token=你的API令牌
acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --server zerossl
第三步,写一个部署脚本,让 acme.sh 每次续期后自动拆分 fullchain 并调用 cPanel UAPI 安装。创建 /home/example/ssl/deploy.sh:
#!/bin/bash
set -e
DOMAIN=example.com
DIR=/home/example/ssl
awk '/BEGIN CERTIFICATE/{n++} n==1{print}' $DIR/fullchain.crt > $DIR/leaf.crt
awk '/BEGIN CERTIFICATE/{n++} n>1{print}' $DIR/fullchain.crt > $DIR/ca_bundle.crt
uapi --user=example SSL install_ssl domain=$DOMAIN
cert="$(cat $DIR/leaf.crt)"
key="$(cat $DIR/example.com.key)"
cabundle="$(cat $DIR/ca_bundle.crt)"
/usr/local/cpanel/bin/rebuild_phpconf --no-restart 2>/dev/null || true
赋权并挂载到 acme.sh:
chmod 700 /home/example/ssl /home/example/ssl/deploy.sh
acme.sh --install-cert -d example.com
--key-file /home/example/ssl/example.com.key
--fullchain-file /home/example/ssl/fullchain.crt
--reloadcmd '/home/example/ssl/deploy.sh'
acme.sh 会写入 crontab,每天检查一次,剩余 30 天时自动续期并触发 reloadcmd。用 crontab -l | grep acme 确认任务存在,用 acme.sh --list 查看续期时间。
方案二:手动上传证书到 Manage SSL Sites(含 UAPI 命令)
付费 DV/OV 证书或从其他服务器迁移过来的证书,适合手动安装。图形界面路径在新版 cPanel 中为 SSL/TLS Status → 目标域名 → Install,老版本为 SSL/TLS → Manage SSL Sites。操作要点:
- Domain 选择要绑定的域名,必须与证书 SAN 完全一致;
- Certificate 粘贴
certificate.crt全文(含-----BEGIN CERTIFICATE-----与结束行); - Private Key 粘贴
private.key全文; - CA Bundle 粘贴
ca_bundle.crt全文; - 勾选 Enable SNI(多域名共用 IP 必须开启)。
粘贴时最容易出问题的是尾部多一个空行、或者中间混入空格。建议直接用命令行完成,避免手工粘贴污染。以 root 身份执行:
uapi --user=example SSL install_ssl
domain=example.com
cert="$(cat /home/example/ssl/leaf.crt)"
key="$(cat /home/example/ssl/example.com.key)"
cabundle="$(cat /home/example/ssl/ca_bundle.crt)"
成功时返回 JSON:
{"apiversion":3,"func":"install_ssl","module":"SSL","result":{"status":1,"messages":null,"data":{"servername":"example.com","certificate":{"domains":["example.com","www.example.com"],"not_after":1750000000}}}}
status 为 1 即安装成功。若返回 status: 0 并带 The certificate does not match the private key.,说明私钥与证书不配对,回到上一节用 MD5 比对排查。
安装完成后,确认 /var/cpanel/ssl/apache_tls/example.com/combined 文件已更新,然后重载 Apache:
/scripts/restartsrv_httpd --hard
# 或
systemctl reload httpd
注意:cPanel 中手动安装的证书不会被 AutoSSL 覆盖,但如果该域名的 AutoSSL 处于启用状态且签发失败,状态页仍可能显示黄色警告,这属于正常提示,不代表证书无效。付费 OV 证书还需确认已在 Domains 页面把该域名的 SSL 状态设为已安装。
配置示例:强制 HTTPS 跳转、HSTS 与混合内容修复
证书装好只是第一步,站点还必须强制走 HTTPS 并消除混合内容,否则浏览器地址栏不会出现完整的安全标识。
方式一:cPanel 面板开关。进入 Domains 页面,打开目标域名右侧的 Force HTTPS Redirect 开关。该开关会在 .htaccess 中写入规则,但仅对 Apache 生效,如果前面有 Nginx 或 CDN,需要在对应层单独配置。
方式二:.htaccess 显式规则(放在站点根目录,位于 WordPress 等应用的规则之前):
RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteCond %{HTTP:X-Forwarded-Proto} !https
RewriteRule ^(.*)$ https://%{HTTP_HOST}/$1 [R=301,L]
第二条条件用于兼容 CDN 回源场景,避免 CDN 已终止 TLS 但源站仍判定为 HTTP 而产生无限跳转。
方式三:HSTS 与混合内容升级。确认全站 HTTPS 稳定运行两周后,再开启 HSTS,否则回退成本很高:
<IfModule mod_headers.c>
Header always set Strict-Transport-Security 'max-age=31536000; includeSubDomains'
Header always set Content-Security-Policy 'upgrade-insecure-requests'
</IfModule>
upgrade-insecure-requests 会把页面中残留的 http:// 资源请求自动升级为 https://,是修复混合内容最快的临时手段,但根因仍应改为相对协议或直接写 https 绝对地址。
排查混合内容可以用两条命令。先抓取首页中的 http 资源:
curl -s https://example.com | grep -oE 'http://[^"''' ]+' | sort -u | head -20
再检查响应头是否已下发 HSTS:
curl -sI https://example.com | grep -i strict-transport-security
# 期望:strict-transport-security: max-age=31536000; includeSubDomains
WordPress 站点还要注意数据库里可能存有大量 http://example.com 的绝对地址,可用 WP-CLI 批量替换:wp search-replace 'http://example.com' 'https://example.com' --all-tables --precise。替换前务必备份数据库。
三种部署方式对比:AutoSSL、acme.sh + ZeroSSL、手动上传
选哪种方式取决于你的证书类型、运维能力和续期要求。下表是三种方案在 cPanel 环境下的关键差异:
| 对比项 | cPanel AutoSSL(Sectigo) | acme.sh + ZeroSSL | 手动上传(付费 DV/OV/EV) |
|---|---|---|---|
| 证书有效期 | 约 90 天,自动续期 | 90 天,自动续期 | 最长 398 天(2026-03-15 起 200 天) |
| 是否自动续期 | 是,cPanel 定时任务 | 是,acme.sh cron + reloadcmd | 否,需人工重签重装 |
| 是否支持泛域名 | 不支持 | 支持(需 DNS API) | 支持,需在订单中勾选 |
| 身份验证级别 | DV | DV | DV / OV / EV |
| 典型命令/入口 | SSL/TLS Status → Run AutoSSL | acme.sh --issue --server zerossl |
Manage SSL Sites 或 uapi SSL install_ssl |
| 失败影响面 | 全部域名可能同时掉证 | 单域名,可控 | 仅当前域名 |
| 适合场景 | 纯 DV、无泛域名、零运维 | 需要 ZeroSSL 或泛域名 | 企业站、需要 OV/EV 展示主体信息 |
几点补充判断依据。第一,如果站点需要 *.example.com 泛域名,AutoSSL 直接出局,只能选 acme.sh(ZeroSSL 泛域名需 DNS-01 验证)或付费证书。第二,如果业务涉及支付、小程序审核或需要展示组织信息,OV/EV 证书的审核材料(营业执照、电话回拨)无法用免费 DV 替代。第三,OV/EV 证书虽然最长 398 天,但 2026 年 3 月起上限降到 200 天,续期频率翻倍,务必把续期提醒写进运维日历。
成本方面,ZeroSSL 免费 DV 为 0 元但只有 90 天;付费 DV 与 OV 的价格差异主要体现在审核流程与保修金额上,选型时优先看“是否需要展示企业身份”,而不是单纯比价。
常见错误排查:真实报错与对应修复命令
下面列出 cPanel 部署 ZeroSSL 证书时出现频率最高的六类报错,每条都给出定位命令。
1)curl: (60) SSL certificate problem: unable to get local issuer certificate
典型缺链。用 openssl s_client 数一下服务器实际下发的证书数量:
echo | openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null | grep -c 'BEGIN CERTIFICATE'
输出为 1 说明只下发了叶子证书,必须补 CA Bundle;正常应为 2 或 3。修复方式是重新执行 UAPI 安装并正确传入 cabundle。
2)AH02565: Certificate and private key ... do not match
证书与私钥不配对。执行:
openssl x509 -noout -modulus -in leaf.crt | openssl md5
openssl rsa -noout -modulus -in example.com.key | openssl md5
两个 MD5 不同则必须重新签发或找回正确私钥,没有其他绕过办法。
3)NET::ERR_CERT_COMMON_NAME_INVALID
域名不在 SAN 列表中。检查:
openssl x509 -in leaf.crt -noout -ext subjectAltName
若缺少 www 子域,重新签发时加上 -d www.example.com,或为 www 单独做 301 跳转到裸域。
4)小程序报 request:fail ssl hand shake error
绝大多数是中间证书缺失,其次是 TLS 版本过低(小程序要求 TLS 1.2 及以上)。检查协议与链:
openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null | grep -E 'Protocol|Verify return code'
Verify return code: 0 (ok) 才算通过。若为 21 或 20,仍是证书链问题。
5)Java 报 unable to find valid certification path to requested target
JDK 的 TrustStore 不含 ZeroSSL 所用根证书,或服务器未下发中间证书。先用 openssl s_client -showcerts 导出完整链,再导入:
keytool -importcert -alias zerossl-ca -file ca_bundle.crt -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit
6)续期后站点仍返回旧证书
先看证书实际到期时间,再确认配置指向的文件路径是否为新文件:
echo | openssl s_client -connect example.com:443 2>/dev/null | openssl x509 -noout -dates -issuer
grep -r 'SSLCertificateFile' /var/cpanel/ssl/apache_tls/example.com/ 2>/dev/null
/scripts/restartsrv_httpd --hard
如果前面套了 CDN,还要在 CDN 控制台刷新或重新上传证书,否则边缘节点仍缓存旧证书。
效果验证:从 OpenSSL 到浏览器与 API 的全链路检查
安装完成后不要只看浏览器地址栏的小锁,要按“链 → 有效期 → 协议 → 应用层”四层验证。
第一层,证书链与主机名。
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
期望看到 Subject 为 CN = example.com,Issuer 为 ZeroSSL RSA Domain Secure Site CA 或对应中间 CA,且 notAfter 在 90 天内。
第二层,链完整性验证。
openssl s_client -connect example.com:443 -servername example.com -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null 2>/dev/null | grep 'Verify return code'
# 期望:Verify return code: 0 (ok)
非 0 即为链问题,回到排查章节处理。
第三层,HTTP 层跳转与响应头。
curl -sI http://example.com | head -3
# 期望:HTTP/1.1 301 Moved Permanently 且 Location: https://example.com/
curl -sI https://example.com | grep -Ei 'strict-transport-security|server'
curl -vI https://example.com 2>&1 | grep -E 'SSL certificate verify|TLSv'
第四层,应用层实测。用与真实客户端一致的运行时验证,例如 PHP 的 curl 扩展、Java 客户端、微信开发者工具。这一步能暴露浏览器自动补链掩盖的问题。
最后建议做一个到期监控,避免自动续期静默失败:
cat > /usr/local/bin/check_cert.sh <<'EOF'
#!/bin/bash
END=$(echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -enddate | cut -d= -f2)
DAYS=$(( ( $(date -d "$END" +%s) - $(date +%s) ) / 86400 ))
[ $DAYS -lt 14 ] && echo "WARN: example.com cert expires in $DAYS days" | mail -s 'SSL Expiry' admin@example.com
EOF
chmod +x /usr/local/bin/check_cert.sh
把该脚本加入 crontab 每天执行一次,配合 acme.sh 的续期日志 ~/.acme.sh/acme.sh.log 一起看,就能在证书真正过期前发现问题。验证通过后,记得把证书备份到独立目录,包含私钥、证书、CA Bundle 与部署脚本四件套。
常见问题
免费 DV 证书固定 90 天,无法延长,到期前 30 天需续期。付费 DV/OV/EV 当前最长 398 天,但 2026 年 3 月 15 日起上限降为 200 天,2027 年起 100 天。建议用 acme.sh 配置自动续期,不要依赖手工重签。
不能。cPanel AutoSSL 内置的签发厂商是 Sectigo,面板里没有 ZeroSSL 选项。要使用 ZeroSSL,需安装 acme.sh 并指定 –server zerossl 签发,再通过 uapi SSL install_ssl 把证书安装到 cPanel 对应域名。
几乎都是证书链不完整。浏览器会用 AIA 机制自动补齐中间证书,而 curl、Java TrustStore、小程序运行时不会。用 openssl s_client -showcerts 统计证书数量,若只有 1 张,说明只下发了叶子证书,需补传 CA Bundle。
先用 openssl x509 -noout -modulus 与 openssl rsa -noout -modulus 分别计算 MD5 对比,ECDSA 证书改用 -pubkey 对比。结果不一致说明文件混用,只能重新签发或找回原始私钥,无法通过修改配置绕过。
先执行 openssl s_client 查看服务器实际返回的 notAfter 是否已更新;再确认 Apache 配置与 cPanel 的 combined 文件指向新证书;最后重启 httpd。若前端有 CDN,还需在 CDN 控制台重新上传证书或刷新缓存。