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 配置。