宝塔面板部署 Let’s Encrypt SSL 证书完整教程:自动申请、手动配置与报错排查
问题背景与根因:为什么宝塔“显示已部署”却仍有客户端报错
宝塔面板把 SSL 入口做得很简单,但“面板显示证书有效期正常、浏览器小锁正常,Java 客户端 / 微信小程序 / curl 却握手失败”依旧是最常见的故障。问题几乎从不来自 Let’s Encrypt 本身,而是集中在三个层面。
第一层:证书链不完整。ACME 签发下来的是叶子证书(leaf),必须与中间证书拼接成 fullchain 才能被客户端信任。宝塔“其他证书”输入框若只粘贴了 cert.pem 的内容,Chrome 会自行补链所以看起来正常,而 Java 8 默认信任库、Android 7 以下、部分 Python requests 环境会直接抛出 PKIX path building failed。
第二层:有效期与续期。Let’s Encrypt 证书有效期固定 90 天,官方建议剩余 30 天时续期。宝塔的自动续签依赖面板计划任务与 crontab,如果系统时间漂移、80/443 端口被其他进程占用、DNS 验证 TXT 记录未生效,续期就会静默失败,90 天后站点直接变成 NET::ERR_CERT_DATE_INVALID。需要强调的是:自 2020 年 9 月起,所有公共 CA 签发的证书最长有效期被限制为 398 天,不要再按“一年期”规划证书生命周期;Let’s Encrypt 的 90 天更短,必须依赖自动化续期。
第三层:协议与代理层。站点开启“强制 HTTPS”后,若前面套了 CDN 或 Nginx 反向代理且回源协议仍是 HTTP,就会形成 301 死循环,浏览器报 ERR_TOO_MANY_REDIRECTS。
把这三层拆开看,后面的每一步操作才有明确目的,而不是照着截图点一遍就完事。
前置检查与证书文件准备:fullchain、privkey 与 CSR 的区别
动手前先跑四条检查,能省掉后面 80% 的报错。
1. 校时。ACME 协议对时间敏感,偏差超过 5 分钟会直接返回 JWS verification error:
timedatectl set-ntp true
timedatectl status | grep -E 'System clock|synchronized'
2. 端口放通。文件验证(HTTP-01)要求外网能访问 80 端口下的 /.well-known/acme-challenge/;DNS 验证(DNS-01)不占端口,是泛域名 *.example.com 的唯一选择。
ss -lntp | grep -E ':80|:443'
curl -I http://example.com/.well-known/acme-challenge/test
3. 用 acme.sh 签发并落盘到宝塔目录。宝塔站点证书默认目录为 /www/server/panel/vhost/cert/站点名/:
curl https://get.acme.sh | sh -s email=admin@example.com
~/.acme.sh/acme.sh --issue -d example.com -d www.example.com --webroot /www/wwwroot/example.com
~/.acme.sh/acme.sh --install-cert -d example.com
--key-file /www/server/panel/vhost/cert/example.com/privkey.pem
--fullchain-file /www/server/panel/vhost/cert/example.com/fullchain.pem
--reloadcmd "nginx -s reload"
4. 分清三个文件。CSR(证书签名请求)只是申请时提交的公钥与主体信息,签发完成后即可丢弃;私钥 privkey.pem 必须自行保管,权限设为 600;fullchain.pem 是叶子证书加中间证书,服务器上永远配置这个文件。用下面两条命令确认链的层数:
openssl x509 -in fullchain.pem -noout -subject -issuer -dates
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
输出中应看到至少两张证书(你的域名 + R10/R11 中间证书)。只有一张,就是链不完整,客户端必然报错。
实操步骤一:面板内一键申请 Let’s Encrypt 并开启自动续签
这是最省事的方式,适合单站点、单域名或少量 SAN 域名。路径:网站 → 站点 → 设置 → SSL → Let’s Encrypt。
具体操作:① 勾选需要签发的域名(example.com 与 www.example.com 建议一起勾,避免后续跳转时域名不匹配);② 选择验证方式,文件验证要求 80 端口可访问,DNS 验证需在域名商处添加 TXT 记录,泛域名必须选 DNS;③ 点击“申请”,等待 10~60 秒;④ 成功后立刻勾选强制 HTTPS;⑤ 确认“自动续签”开关为开启状态。
面板背后其实是通过计划任务调用的,登录 SSH 验证一下是否真的写入了 crontab:
crontab -l | grep -iE 'acme|letsencrypt|panel'
正常应看到类似 /www/server/panel/script/rememory.py 或 acme.sh --cron 的条目。如果为空,说明自动续签根本没生效,需要手动在面板 → 计划任务中添加一条 Shell 脚本任务,执行周期设为每天一次:
"/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /var/log/acme-cron.log 2>&1
需要提醒的是,宝塔不同版本(7.x / 8.x / 9.x)的 SSL 页面布局有差异,8.x 之后“其他证书”被折叠在“当前证书”标签下方;找不到入口时先用 bt 命令查看面板版本号,再对照官方文档,不要凭旧截图乱点。另外,如果站点已接入 CDN,申请阶段建议先暂停 CDN 或把回源端口放通,否则文件验证会返回 404。
实操步骤二:手动部署 ACME 证书到“其他证书”通道
当面板一键申请失败(常见于域名解析在 Cloudflare、服务器无公网 80 端口、或需要泛域名),就走手动通道。流程是:本地或服务器上用 acme.sh / certbot 签发 → 把两个文件的文本内容粘贴进面板。
第一步,取到两个文件。签发命令见上一节,落盘后确认:
ls -l /www/server/panel/vhost/cert/example.com/
chmod 600 /www/server/panel/vhost/cert/example.com/privkey.pem
第二步,粘贴。进入 站点 → 设置 → SSL → 其他证书,左侧“密钥(KEY)”框粘贴 privkey.pem 全文(含 -----BEGIN PRIVATE KEY----- 与结束行),右侧“证书(PEM 格式)”框粘贴 fullchain.pem 全文。注意:右侧绝对不能只贴叶子证书,这是后续所有客户端报错的源头。
第三步,避免面板覆盖。手动粘贴后,如果同时还开着面板的 Let’s Encrypt 自动续签,续签成功时会重写 vhost 配置指向面板自己的路径,导致“手动贴的证书被顶掉”。两者只能选其一。更稳妥的做法是让 acme.sh 直接写入面板目录并用 --reloadcmd 触发重载,即上一节的 --install-cert 写法。
第四步,检查配置文件。宝塔会把证书路径写入站点 vhost:
grep -nE 'ssl_certificate|ssl_certificate_key' /www/wwwroot/example.com/nginx.conf
/www/server/nginx/sbin/nginx -t
确认两行分别指向 fullchain.pem 与 privkey.pem,且 nginx -t 输出 syntax is ok 与 test is successful。任何一步不通过都不要 reload,否则整站 443 会直接不可用。
关键配置示例:强制 HTTPS、CDN 回源与 TLS 参数
证书装好只是及格线,配置才决定兼容性与评分。以下是宝塔站点可直接使用的 Nginx 片段(写入站点配置文件,或在面板“配置文件”中修改):
server {
listen 80;
server_name example.com www.example.com;
location /.well-known/acme-challenge/ { root /www/wwwroot/example.com; }
location / { return 301 https://$host$request_uri; }
}
server {
listen 443 ssl http2;
server_name example.com www.example.com;
ssl_certificate /www/server/panel/vhost/cert/example.com/fullchain.pem;
ssl_certificate_key /www/server/panel/vhost/cert/example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
ssl_stapling on;
ssl_stapling_verify on;
add_header Strict-Transport-Security "max-age=31536000" always;
}
要点说明:保留 /.well-known/acme-challenge/ 的 location 且放在 301 之前,否则续期时 HTTP-01 验证会被自己重定向掉,报 Invalid response ... 301。ssl_stapling 依赖 OCSP 响应,若服务器无法访问外网可关闭以免首包变慢。HSTS 头一旦下发就无法回退,先在测试域名验证再上生产。
CDN 场景:Cloudflare / 阿里云 CDN 开启后,必须把“回源协议”从 HTTP 改为 HTTPS(或 443 端口),否则源站的强制 HTTPS 与 CDN 的 HTTP 回源互相踢皮球。若暂时无法改回源,就关闭源站“强制 HTTPS”,由 CDN 边缘节点完成跳转。泛域名证书部署在 CDN 时,注意证书要上传到 CDN 控制台,而不是只装在源站。
续期钩子:无论哪种方式,续期后必须让 Nginx 重新加载证书,否则内存里还是旧证书。acme.sh 的 --reloadcmd "nginx -s reload" 就是干这个的,certbot 则用 --deploy-hook。
三种部署方式与证书类型对比
先看部署方式怎么选,这直接决定了后续维护成本:
| 对比项 | 面板一键申请 | acme.sh 手动签发 | 付费证书手动粘贴 |
|---|---|---|---|
| 适用场景 | 单站点、单/多域名 | 泛域名、多站点、CDN 场景 | OV/EV、合规审计要求 |
| 泛域名支持 | 需 DNS API,配置繁琐 | 支持,DNS-01 即可 | 视 CA 而定 |
| 续期方式 | 面板计划任务自动 | crontab 自动 + reloadcmd | 手动替换文件 |
| 有效期 | 90 天 | 90 天 | 最长 398 天 |
| 失败排查难度 | 低(日志在面板) | 中(需看 acme.sh 日志) | 低 |
再看证书类型本身:
| 维度 | Let’s Encrypt(DV) | 付费 DV | 付费 OV/EV |
|---|---|---|---|
| 有效期 | 90 天 | 最长 398 天 | 最长 398 天 |
| 验证内容 | 域名控制权 | 域名控制权 | 域名 + 组织实名 |
| 浏览器小锁 | 有 | 有 | 有(EV 不再显示绿色地址栏) |
| 价格 | 免费 | 几十至几百元/年 | 千元以上/年 |
| 赔付保障 | 无 | 有 | 有 |
| 推荐人群 | 个人站、API、内部系统 | 中小企业官网 | 金融、电商、政企 |
结论很直接:只要具备自动化续期能力,Let’s Encrypt 在技术上与付费 DV 完全等价,差别只在保障与人工服务。真正需要付费的是 OV/EV 的组织身份背书,而不是“加密强度”——两者用的都是同一套 TLS 1.2/1.3 与 AES-GCM/ChaCha20 算法。
常见错误排查:真实报错与对应处置
报错一:curl: (60) SSL certificate problem: unable to get local issuer certificate
或 Java 侧 javax.net.ssl.SSLHandshakeException: PKIX path building failed。
根因是链不完整。处置:把服务器上的证书换成 fullchain.pem,用 openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout 确认至少两段;Java 客户端还需把中间证书导入 cacerts 或改用完整链。
报错二:nginx: [emerg] SSL_CTX_use_PrivateKey_file(...) failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)
根因是证书与私钥不配对(常见于多次签发后贴错文件)。用模数比对:
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in privkey.pem | openssl md5
两个 MD5 必须完全一致。注意 ECDSA 证书不适用 modulus 比对,改用 openssl x509 -in fullchain.pem -noout -pubkey 与 openssl pkey -in privkey.pem -pubout 比对公钥。
报错三:Problem binding to port 80: Could not bind to IPv4 or IPv6
80 端口被 Nginx/Apache 占用,acme.sh 的 standalone 模式抢不到端口。改用 --webroot 模式,或先 systemctl stop nginx 再申请。
报错四:Invalid response from http://example.com/.well-known/acme-challenge/xxx: 404
验证文件没落到 webroot,或被伪静态规则拦截。检查 root 是否指向站点真实根目录,并临时在 Nginx 中放行该路径。
报错五:too many certificates already issued for exact set of domains
触发 Let’s Encrypt 速率限制:同一组域名每周最多 50 张,重复证书每周 5 张。处置:改用 --staging 参数调试,确认无误后再申请正式证书,否则会被锁 7 天。
报错六:续期日志显示成功,但浏览器仍是旧证书。
原因是 Nginx 未 reload,或配置指向的仍是旧路径。执行 nginx -s reload 后,用 openssl s_client 复核实际下发的证书指纹。
效果验证:四步确认部署真正生效
第一步,服务端握手。这是最权威的验证,直接看服务端实际下发的证书链:
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
输出中 notAfter 应是 90 天内,issuer 应为 C=US, O=Let's Encrypt, CN=R10/R11。若仍是上一周期的日期,说明 reload 未生效。
第二步,链完整性验证。
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | grep -E 'Verify return code|verify error'
必须看到 Verify return code: 0 (ok)。出现 unable to verify the first certificate 即链断裂。
第三步,跳转与协议验证。
curl -I http://example.com
curl -vI https://example.com 2>&1 | grep -E 'SSL connection|TLSv'
curl -s -o /dev/null -w '%{http_code} %{redirect_url}n' http://example.com
期望结果:HTTP 返回 301 且 Location 指向 https,HTTPS 返回 200,协商协议为 TLSv1.3 或 TLSv1.2。
第四步,面板侧确认。宝塔“站点 → SSL”页应显示证书到期时间;监控页可观察 HTTPS 请求占比是否接近 100%;计划任务 → 日志里确认最近一次续签任务返回码为 0。建议再跑一次外部评级(SSL Labs)确认无弱套件告警。
最后把续期演练做一遍:手动执行一次 acme.sh --renew -d example.com --force,观察证书日期是否更新、Nginx 是否自动 reload。能在测试环境跑通,才算真正完成部署,而不是“这次装上了”。
常见问题
先确认 80 端口外网可访问且未被占用,用 curl 访问 /.well-known/acme-challenge/ 下的测试文件;其次检查站点是否套了 CDN,回源会拦截验证;最后看系统时间是否准确。泛域名必须改用 DNS 验证,文件验证无法签发。
有效期固定 90 天,官方建议剩余 30 天续期。宝塔面板开启自动续签后会写入计划任务,但需确认 crontab 中存在对应条目且执行日志返回码为 0。若手动部署,务必配置 reloadcmd 重载 Nginx,否则续期成功也不会生效。
这是典型的跳转循环:CDN 或反代以 HTTP 回源,源站又强制跳 HTTPS。处理方式是把 CDN 的回源协议改为 HTTPS(443 端口),或暂时关闭源站的强制 HTTPS,由 CDN 边缘节点完成跳转,二者只保留一层。
单张证书最多包含 100 个 SAN 名称,同一组域名每周签发上限为 50 张,重复证书每周 5 张。调试阶段务必使用 –staging 参数,避免触发速率限制导致正式环境被锁 7 天。