跳到主要内容
cPanel

Let’s Encrypt SSL 证书 cPanel 安装部署实操教程

问题背景与根因:cPanel 部署 Let’s Encrypt 为什么容易失败

Let’s Encrypt 是免费 DV 证书,有效期固定 90 天,通过 ACME v2 协议自动签发和续期;公共 TLS 证书最长有效期受 CA/B 论坛限制为 398 天,但 Let’s Encrypt 不提供 398 天证书。cPanel 部署失败通常不是“证书没签发”,而是证书链、私钥、域名匹配或 DCV 验证环节出问题。cPanel 使用 PEM 三件套:叶子证书、私钥、CA Bundle。只上传 cert.pem 而漏掉中间证书,浏览器可能正常,但 curl、Java、微信小程序会报 unable to get local issuer certificate。另一个根因是 AutoSSL 的 HTTP-01 验证要求 example.com 的 A/AAAA 记录指向本机、80 端口可达,且 /.well-known/acme-challenge/ 不被重定向或防火墙拦截。先做三项检查:dig +short example.com A、curl -I http://example.com/.well-known/acme-challenge/test、openssl version。若使用 Cloudflare 代理,HTTP-01 常失败,应改为 DNS only 或使用 acme.sh 的 DNS-01。cPanel 的 AutoSSL 与手动上传是两条路径,不要混用旧文件。

部署前准备:核对证书、私钥与证书链

无论 AutoSSL 还是手动上传,先确认文件完整。Let’s Encrypt 典型文件:cert.pem(叶子)、privkey.pem(私钥)、chain.pem(中间证书)、fullchain.pem(叶子+中间)。cPanel 的 Manage SSL Sites 通常要求 Certificate 填叶子、CA Bundle 填中间链;若面板只提供一个证书输入框,才用 fullchain。执行以下命令核对域名、有效期和 SAN:

openssl x509 -in cert.pem -noout -subject -issuer -dates -ext subjectAltName
openssl rsa -in privkey.pem -noout -modulus | openssl sha256
openssl x509 -in cert.pem -noout -modulus | openssl sha256
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted chain.pem cert.pem

两条 modulus 的 SHA256 必须一致,否则报“证书与私钥不匹配”。SAN 必须同时包含 example.com 和 www.example.com,否则访问 www 会报名称不匹配。证书链验证最后一行应返回 cert.pem: OK;若返回 unable to get local issuer certificate,说明 CA Bundle 缺失或顺序错误。私钥权限建议 chmod 600 privkey.pem,属主为 cPanel 账户。不要用记事本另存 PEM,避免 CRLF 和多余空格;文件开头应为 -----BEGIN CERTIFICATE-----。准备完成后,记录证书到期时间,Let’s Encrypt 剩余 30 天左右就应续期。

方案一:cPanel AutoSSL 自动签发与续期

这是 cPanel 最省事的方案。登录 WHM,进入 SSL/TLS → Manage AutoSSL,在 Providers 中启用 Let’s Encrypt,勾选服务条款;再进入 SSL/TLS → SSL/TLS Status,选择域名后点击 Run AutoSSL。cPanel 会为已解析到本机且文档根存在的域名自动签发 90 天证书,并在到期前自动续期。命令行排查日志:

tail -f /usr/local/cpanel/logs/autossl_log
dig +short example.com A
dig +short example.com AAAA
curl -I http://example.com/.well-known/acme-challenge/test

常见失败原因:域名未解析到本机、AAAA 记录指向旧 IPv6、80 端口被防火墙拦截、文档根不存在、.htaccess 把 ACME 路径 301 到 HTTPS、Cloudflare 代理开启。若日志出现 The system could not find a valid document root,在 cPanel 中确认 public_html 存在且域名绑定正确;若出现 HTTP DCV failed,先关闭 CDN 代理或放行 /.well-known/acme-challenge/。AutoSSL 不需要你手动上传文件,续期也由面板调度;但如果你曾手动安装过期证书,建议在 SSL/TLS Status 中先移除旧证书再 Run AutoSSL,避免面板继续使用旧配置。

方案二:手动上传与 acme.sh 自动部署

手动上传适合外部签发或 AutoSSL 不可用。cPanel 路径:Security → SSL/TLS → Manage SSL Sites,选择域名;Certificate 粘贴 cert.pem,Private Key 粘贴 privkey.pem,CA Bundle 粘贴 chain.pem。若面板提示 The certificate is not trusted in all web browsers,就是 CA Bundle 缺失。安装后到 Domains 开启 Force HTTPS Redirect。手动证书不会自动续期,必须用脚本重新上传。需要批量自动化时,用 acme.sh 签发并调用 WHM API:

curl https://get.acme.sh | sh -s email=admin@example.com
~/.acme.sh/acme.sh --set-default-ca --server letsencrypt
~/.acme.sh/acme.sh --issue -d example.com -d www.example.com -w /home/user/public_html
~/.acme.sh/acme.sh --install-cert -d example.com 
  --key-file /home/user/ssl/example.com.key 
  --cert-file /home/user/ssl/example.com.crt 
  --ca-file /home/user/ssl/example.com.ca.pem 
  --fullchain-file /home/user/ssl/example.com.fullchain.pem 
  --reloadcmd 'whmapi1 installssl domain=example.com crt=/home/user/ssl/example.com.crt key=/home/user/ssl/example.com.key cabundle=/home/user/ssl/example.com.ca.pem'

Cloudflare 开代理时 HTTP-01 会失败,改用 acme.sh --issue --dns dns_cf -d example.com -d www.example.com 并配置 CF_Token。安装后 whmapi1 installssl 应返回 result: 1;续期测试用 acme.sh --renew -d example.com --force。手动上传与 acme.sh 都需确认 cPanel 中 Certificate 与 CA Bundle 不重复、不遗漏。

配置示例:Apache、HTTPS 跳转与 HSTS

cPanel 环境不要直接改主 httpd.conf,优先用面板的 Force HTTPS Redirect;自管 Apache 可参考以下虚拟主机配置。注意 SSLCertificateFile 放叶子证书,SSLCertificateChainFile 放中间链;Apache 2.4.8+ 也可用 SSLCACertificateFile。配置后执行 apachectl configtest,返回 Syntax OK 再重载。

<VirtualHost *:443>
    ServerName example.com
    ServerAlias www.example.com
    DocumentRoot /home/user/public_html
    SSLEngine on
    SSLCertificateFile /home/user/ssl/example.com.crt
    SSLCertificateKeyFile /home/user/ssl/example.com.key
    SSLCertificateChainFile /home/user/ssl/example.com.ca.pem
    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
</VirtualHost>

强制 HTTPS 的 .htaccess 示例:

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

HSTS 只在全站及子域都已 HTTPS 后开启,否则会把用户锁在无法访问的 http 页面。若使用 Nginx 反向代理,核心配置为 ssl_certificate /home/user/ssl/example.com.fullchain.pem;、ssl_certificate_key /home/user/ssl/example.com.key;、ssl_protocols TLSv1.2 TLSv1.3;。cPanel 的 AutoSSL 会管理自己的配置,手动加 vhost 时避免与面板生成配置重复,导致 AH01909 或证书被覆盖。

方案对比与选型表格

三种方式都能部署 Let’s Encrypt,但权限、续期和排错成本不同。个人站点优先 AutoSSL;多服务器、CDN、泛域名或需要 DNS-01 的场景用 acme.sh;临时迁移或证书由外部 CA 签发时用手动上传。选型时重点看“谁负责续期”和“证书链是否完整”。

方案 适用场景 续期方式 权限要求 主要风险
cPanel AutoSSL 单机 cPanel、域名已解析 面板自动,约 90 天周期 cPanel/WHM 管理员 HTTP DCV 被 CDN/防火墙拦截
手动上传 外部签发、临时部署 人工或脚本重新上传 cPanel 用户 漏 CA Bundle、续期遗忘
acme.sh + WHM API 批量域名、DNS-01、自动化 acme.sh 定时任务 + reloadcmd SSH/WHM root API 参数错误、文件权限

价格上 Let’s Encrypt 为免费 DV;付费 OV/EV 证书提供组织验证和保障,但公共 TLS 证书最长有效期同样受 398 天上限约束。若只需要浏览器信任和小程序 HTTPS,Let’s Encrypt 足够。对比时不要只看“证书年限”,而要看自动续期是否可靠、CA Bundle 是否随证书更新、以及 cPanel 是否会在续期后重载服务。建议保留监控:openssl x509 -in cert.pem -noout -enddate,到期前 30 天告警。

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

1. curl: (60) SSL certificate problem: unable to get local issuer certificate:缺中间证书。把 chain.pem 填入 CA Bundle,或改用 fullchain;用 openssl s_client -connect example.com:443 -servername example.com -showcerts 确认返回至少两张证书。2. 证书与私钥不匹配:执行 openssl x509 -in cert.pem -noout -modulus | openssl sha256 与 openssl rsa -in privkey.pem -noout -modulus | openssl sha256,值不同就重新签发或找回匹配私钥。3. AH01909: RSA certificate configured for example.com:443 does NOT include an ID which matches the server name:ServerName/ServerAlias 与证书 SAN 不一致,补 www 或修正 vhost。4. NET::ERR_CERT_AUTHORITY_INVALID:证书链不完整或安装了自签证书,检查 CA Bundle。5. AutoSSL 日志出现 HTTP DCV failed / DNS DCV failed:检查 A/AAAA、80 端口、CDN 代理和 /.well-known/acme-challenge/ 是否 200。6. too many certificates already issued:触发 Let’s Encrypt 速率限制,改用 staging 环境测试,等待窗口恢复。每次改配置后先 apachectl configtest,再 systemctl reload httpd,不要直接 restart 生产服务。

效果验证:浏览器、命令行与续期测试

先看浏览器:地址栏锁标志正常,开发者工具 Console 无 Mixed Content 警告,Network 中所有资源均为 https。命令行验证:

curl -I https://example.com
curl -vI https://example.com 2>&1 | grep -E 'SSL certificate|subject|issuer|verify'
openssl s_client -connect example.com:443 -servername example.com -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -c 'BEGIN CERTIFICATE'

curl -v 应出现 SSL certificate verify ok;openssl s_client 的 Verify return code 应为 0 (ok);证书数量应大于等于 2,表示含中间证书。再检查 SAN:openssl x509 -in cert.pem -noout -ext subjectAltName 必须覆盖根域和 www。续期测试不要等 90 天:AutoSSL 可在 SSL/TLS Status 手动 Run AutoSSL;acme.sh 执行 acme.sh --renew -d example.com --force,然后重新执行上面的 openssl s_client,确认 notAfter 已更新。最后用 SSL Labs 或 curl 从外网验证,避免只在服务器本机测试。

常见问题

Let’s Encrypt 固定为 90 天,建议剩余约 30 天续期;398 天是公共 TLS 证书的最长有效期上限,不是 Let’s Encrypt 的签发时长。cPanel AutoSSL 会自动续期,手动上传则需自行配置续期任务。


若面板有 Certificate 和 CA Bundle 两个字段,Certificate 用 cert.pem,CA Bundle 用 chain.pem;若只有一个证书输入框,才用 fullchain.pem。只传叶子证书会导致 curl、Java、小程序报证书链不完整。


这是中间证书缺失。检查 cPanel 的 CA Bundle 是否填入 chain.pem,或用 openssl s_client -showcerts 确认服务端返回至少两张证书;修正后重载 httpd 并重新验证。


确认域名 A/AAAA 指向本机、80 端口可达、/.well-known/acme-challenge/ 返回 200;Cloudflare 代理会拦截验证,应改为 DNS only。还要检查 .htaccess 是否把 ACME 路径重定向到 HTTPS。


先确认配置指向新文件,再执行 systemctl reload httpd 或 cPanel 重新安装证书;用 openssl s_client 查看 notAfter 是否更新。若前面有 CDN,还要在 CDN 侧更新或回源验证。


可以,但必须使用 DNS-01 验证,不能只用 HTTP-01。acme.sh 可用 –dns dns_cf 等 DNS API 模式签发 *.example.com;cPanel AutoSSL 对泛域名的支持取决于面板版本和 DNS 配置。

内容审核

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