Let’s Encrypt SSL 证书 Apache 部署实战:fullchain、HSTS 与自动续期全流程
问题背景与根因:为什么证书“装上了”却不生效
Let’s Encrypt 是免费的 DV(域名验证)证书,有效期固定 90 天,通过 ACME 协议自动签发与续期,无人工审核、无保障金,是个人站点和自动化环境的首选。它本身很少出问题,故障几乎都发生在 Apache 这一侧的部署细节上。
把线上案例归纳一下,根因集中在六类:
- 文件用错。
cert.pem是叶子证书,fullchain.pem才是叶子 + 中间证书。只配叶子证书时,浏览器靠 AIA(Authority Information Access)自动补链还能正常打开,但 curl、Java、Android WebView、微信小程序等严格校验的客户端会直接判定“证书链不完整”。 - 版本差异没搞清。Apache 2.4.8 起
SSLCertificateFile可以直接指向 fullchain 单文件,SSLCertificateChainFile被标记为废弃(2.4.8+ 仍配置会输出告警);而 2.2 与 2.4.8 以下版本必须单独指定SSLCertificateChainFile,两者不能混用。 - 续期后没有 reload。certbot 只替换了磁盘文件,Apache 进程仍持有旧证书句柄,表现为“续期日志成功,浏览器依旧报过期”。
- 私钥权限与符号链接。
/etc/letsencrypt/live/example.com/是符号链接,真实私钥权限 0600 root,Apache 工作进程读不到时会直接启动失败。 - 有效期认知错误。受 CA/B Forum 基线约束,公网信任证书最长有效期 398 天(Apple、Chrome 强制),Let’s Encrypt 的 90 天完全合规,不存在“申请更长有效期”的操作空间。
- 环境问题。443 端口未放行、SELinux/防火墙拦截、
SSLProtocol仍允许 TLSv1.0,都会造成握手失败。
下文按“准备文件 → 配置 Apache → 对比方案 → 排查报错 → 验证效果”的顺序给出可直接执行的命令。
前置准备:选对 ACME 客户端,拿到正确的证书文件
推荐用 webroot 模式签发,它不改动现有 Apache 配置,风险最低。先装客户端:
# Debian / Ubuntu
sudo apt update && sudo apt install -y certbot
# RHEL / Rocky / AlmaLinux
sudo dnf install -y certbot
# 需要 certbot 自动改写 Apache 配置时再装(可选)
sudo apt install -y python3-certbot-apache
用 webroot 签发,注意 -w 指向站点真实的 DocumentRoot:
sudo mkdir -p /var/www/html/.well-known/acme-challenge
sudo certbot certonly --webroot -w /var/www/html
-d example.com -d www.example.com
--email admin@example.com --agree-tos --no-eff-email
服务器上没有包管理器权限时改用 acme.sh:
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 --webroot /var/www/html
签发成功后,/etc/letsencrypt/live/example.com/ 下会出现四个文件,用途完全不同:
| 文件 | 内容 | Apache 中的用法 |
|---|---|---|
| cert.pem | 叶子证书(仅域名证书) | 不要单独使用,会断链 |
| chain.pem | 中间证书 | 仅 2.2 / <2.4.8 用 SSLCertificateChainFile |
| fullchain.pem | 叶子 + 中间证书 | 2.4.8+ 的 SSLCertificateFile 指向它 |
| privkey.pem | 私钥 | SSLCertificateKeyFile |
部署前先确认 Apache 能读到私钥,这一步能省掉后面 80% 的启动失败:
sudo ls -l /etc/letsencrypt/live/example.com/
sudo -u www-data cat /etc/letsencrypt/live/example.com/privkey.pem > /dev/null && echo OK
证书有效期 90 天,certbot 在剩余 30 天时自动续期,acme.sh 默认每 60 天续一次。若需要通配符证书,把 --webroot 换成 --dns 插件即可,证书文件结构不变。
实操步骤:Apache 2.4.8+ 的部署流程
第一步加载模块。改证书配置只需 reload,但加载 mod_ssl、mod_headers 这类模块必须 restart:
sudo a2enmod ssl headers
# 可选:启用 HTTP/2(依赖 mod_http2)
sudo a2enmod http2
sudo systemctl restart apache2
第二步新建站点配置。Debian/Ubuntu 放到 /etc/apache2/sites-available/example-ssl.conf;RHEL 系没有 a2ensite,直接写到 /etc/httpd/conf.d/example-ssl.conf 即可,内容见下一节完整示例。
第三步启用站点并做语法检查:
sudo a2ensite example-ssl.conf
sudo apachectl configtest
只有输出 Syntax OK 才继续。很多非语法错误也会在这一步暴露,例如证书路径不存在、私钥不可读,都会以 AH00526 开头打印出来。
第四步平滑重载:
sudo systemctl reload apache2
# RHEL 系执行 sudo systemctl reload httpd
第五步核对监听端口。若 443 未监听,先回头确认 VirtualHost 是否被启用、Listen 443 是否被注释:
sudo ss -lntp | grep -E ':(80|443)s'
第六步放行防火墙:
sudo ufw allow 'Apache Full'
# 或
sudo firewall-cmd --permanent --add-service=https && sudo firewall-cmd --reload
几个容易忽略的细节:ServerName 必须出现在证书的 SAN 列表里;同一 IP 上第一个匹配的 443 VirtualHost 是默认站点,配置顺序会影响未携带 SNI 的请求落到哪张证书;SSLCertificateFile 直接写 /etc/letsencrypt/live/example.com/fullchain.pem 绝对路径,不要先复制到 /etc/ssl/ 再软链,否则续期后软链会指向失效文件。
完整配置示例:HTTP 跳转 + 强加密套件 + HSTS + OCSP Stapling
下面这份配置可直接落地,包含 80 端口跳转、443 站点、TLS 1.2/1.3、HSTS 与 OCSP Stapling:
<VirtualHost *:80>
ServerName example.com
ServerAlias www.example.com
Redirect permanent / https://example.com/
</VirtualHost>
<IfModule mod_ssl.c>
<VirtualHost *:443>
ServerName example.com
ServerAlias www.example.com
DocumentRoot /var/www/html
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
# Apache 2.4.8+ 无需 SSLCertificateChainFile
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
SSLHonorCipherOrder off
SSLSessionTickets off
SSLUseStapling on
SSLStaplingResponderTimeout 5
SSLStaplingReturnResponderErrors off
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
Header always set X-Content-Type-Options "nosniff"
ErrorLog ${APACHE_LOG_DIR}/example-ssl-error.log
CustomLog ${APACHE_LOG_DIR}/example-ssl-access.log combined
</VirtualHost>
</IfModule>
# 放在 VirtualHost 之外(httpd.conf / ssl.conf 全局段)
SSLStaplingCache "shmcb:logs/ssl_stapling(32768)"
关键参数说明:
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1保留 TLSv1.2 与 TLSv1.3,微信小程序与较老的 Android 客户端才能握手成功;TLS 1.3 不需要单独写进指令。SSLCipherSuite只列 ECDHE + AES-GCM,去掉 CBC 与 RSA 密钥交换,兼容性与性能更均衡。- HSTS 首次上线建议先用
max-age=300,确认全站 HTTPS 无混合内容后再改成 31536000;加preload前务必想清楚,浏览器硬编码名单移除周期以月计。 - OCSP Stapling 依赖
fullchain.pem中的中间证书,链不完整时 Stapling 会静默失效。 - 若同时持有 RSA 与 ECDSA 证书,可在同一 VirtualHost 内写两行
SSLCertificateFile与两行SSLCertificateKeyFile,Apache 会按客户端能力自动选择。
改完执行 sudo apachectl configtest,输出 Syntax OK 后再 systemctl reload apache2。
方案对比:证书链配置方式与 ACME 客户端选型
先看证书链的三种配置方式,选错是“浏览器正常但接口报错”的头号原因:
| 场景 | Apache 版本 | 配置方式 | 说明 |
|---|---|---|---|
| 推荐 | 2.4.8 及以上 | SSLCertificateFile → fullchain.pem | 单文件,最少出错,续期无需改配置 |
| 兼容 | 2.4.8 及以上 | SSLCertificateFile=cert.pem SSLCertificateChainFile=chain.pem |
ChainFile 已废弃,日志会出现告警 |
| 老版本 | 2.2 / 低于 2.4.8 | SSLCertificateFile=cert.pem SSLCertificateChainFile=chain.pem |
必须分开配置,不能只配叶子证书 |
再看 ACME 客户端选型:
| 客户端 | 安装方式 | 续期机制 | 适用场景 |
|---|---|---|---|
| certbot | apt / dnf 包 | systemd timer + renewal-hooks | 单机 Apache/Nginx,标准运维链路 |
| acme.sh | curl 脚本,纯 shell | 自带 cron + –reloadcmd | 无包管理权限、多 CA 切换、DNS API 丰富 |
| Win-ACME | Windows 可执行文件 | Windows 计划任务 | IIS 与 Windows 版 Apache |
证书类型与有效期对比:
| 证书类型 | 最长有效期 | 校验方式 | 典型用途 |
|---|---|---|---|
| Let’s Encrypt DV | 90 天 | 域名控制权(HTTP-01 / DNS-01) | 个人站、API、内部系统 |
| 商业 DV | 398 天(CA/B 上限) | 域名控制权 | 需要发票、SLA、多域名打包 |
| OV / EV | 398 天 | 域名 + 组织身份核验 | 金融、政企对外门户 |
选型建议:能自动续期的一律用 Let’s Encrypt;需要组织信息展示或合规审计时再上商业证书,但 398 天是硬上限,任何“多年期”承诺本质都是后台自动重签。客户端优先 certbot,没有包管理权限或需要 DNS-01 通配符时选 acme.sh。
常见错误排查:真实报错与修复命令
1. 配置路径写错
AH00526: Syntax error on line 12 of /etc/apache2/sites-enabled/example-ssl.conf:
SSLCertificateFile: file '/etc/ssl/example.com.crt' does not exist or is empty
文件没生成或路径拼错。执行 sudo ls -l /etc/letsencrypt/live/example.com/ 核对,把路径改为 fullchain.pem 的绝对路径。
2. 证书与私钥不匹配
AH02565: Certificate and PrivateKey example.com:443:0 from
/etc/letsencrypt/live/example.com/fullchain.pem and
/etc/letsencrypt/live/example.com/privkey.pem do not match
用公钥比对,RSA 与 ECDSA 证书通用:
diff <(openssl x509 -noout -pubkey -in fullchain.pem) <(openssl pkey -pubout -in privkey.pem) && echo MATCH
输出 MATCH 才算一致。RSA 证书也可用 openssl x509 -noout -modulus 与 openssl rsa -noout -modulus 各取一次 MD5 对比。
3. curl 报证书链不完整
curl: (60) SSL certificate problem: unable to verify the first certificate
典型原因是 SSLCertificateFile 指向了 cert.pem。改为 fullchain.pem 后 reload 即可。
4. Java 客户端 PKIX 报错
sun.security.provider.certpath.SunCertPathBuilderException:
unable to find valid certification path to requested target
与第 3 条同源,缺中间证书。Java 8 之前不主动做 AIA 补链,这类问题在浏览器上完全看不出来。
5. 微信小程序 / Android 握手失败
request:fail ssl hand shake error
排查顺序:证书链是否完整 → SSLProtocol 是否禁用了 TLSv1.0/1.1(小程序要求 TLS 1.2 以上)→ 是否只配了 ECDSA 证书而客户端不支持。用 openssl s_client -connect example.com:443 -servername example.com -tls1_2 单独验证。
6. 域名不匹配
AH01909: www.example.com:443:0 server certificate does NOT include an ID which matches the server name
ServerAlias 里配了证书未包含的域名。重新签发时把该域名加入 -d 列表,或从 ServerAlias 中删除。
7. 续期成功但证书没变
先比对进程实际持有的证书与磁盘文件:openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -enddate 与 openssl x509 -noout -enddate -in fullchain.pem。不一致说明没有 reload,补一个 deploy hook 即可。
自动续期:certbot timer 与 deploy hook 配置
先空跑一次,确认续期链路可用:
sudo certbot renew --dry-run
输出 Congratulations, all simulated renewals succeeded 才算通过。certbot 包默认已安装 systemd timer,无需自己写 cron:
systemctl list-timers | grep certbot
# 输出形如:certbot.timer ... 下次触发时间
关键是续期成功后必须 reload Apache。在 renewal-hooks/deploy/ 下放一个可执行脚本,certbot 每次续期成功都会调用:
sudo mkdir -p /etc/letsencrypt/renewal-hooks/deploy
sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-apache.sh > /dev/null <<'EOF'
#!/bin/sh
systemctl reload apache2 || systemctl restart apache2
EOF
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-apache.sh
RHEL 系把脚本里的 apache2 换成 httpd。acme.sh 用户在安装证书时就把 reload 命令带上,它会写进续期任务:
~/.acme.sh/acme.sh --install-cert -d example.com
--key-file /etc/ssl/example.com.key
--fullchain-file /etc/ssl/example.com.crt
--reloadcmd 'systemctl reload apache2'
几个续期相关的坑:/etc/letsencrypt/live/ 下是符号链接,续期后指向新的 archive/ 文件,因此配置里必须写 live/ 路径,写死 archive/example.com/cert1.pem 这类带序号的路径下次续期就失效;如果服务器 80 端口对外关闭,HTTP-01 验证会失败,改用 --dns 插件走 DNS-01;多个域名塞进同一张证书时,任一域名验证失败会导致整张证书续期失败,建议按业务拆成多张证书。
效果验证:从 configtest 到 SSL Labs 评分
按顺序执行,每一步都有明确判据:
# 1. 语法检查,必须输出 Syntax OK
sudo apachectl configtest
# 2. 服务端实际下发的证书与有效期
openssl s_client -connect example.com:443 -servername example.com -showcerts
</dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
# 3. 严格校验整条链,必须出现 Verify return code: 0 (ok)
openssl s_client -connect example.com:443 -servername example.com
-verify_return_error -CAfile /etc/ssl/certs/ca-certificates.crt
</dev/null 2>&1 | grep -E 'Verify return code|Verification'
# 4. 响应头与跳转
curl -sI https://example.com | grep -Ei 'HTTP/|strict-transport-security'
curl -sI http://example.com | grep -i location
# 5. OCSP Stapling 是否生效
openssl s_client -connect example.com:443 -servername example.com -status
</dev/null 2>/dev/null | grep -A1 'OCSP Response Status'
判据:第 2 步的 notAfter 应在 90 天内;第 3 步必须输出 Verify return code: 0 (ok),出现 21 (unable to verify the first certificate) 就是链断了;第 4 步 80 端口应返回 301 且 Location 指向 https;第 5 步应输出 successful。
再做整体评分:浏览器访问确认小锁无告警后,用 SSL Labs(ssllabs.com/ssltest)跑一次完整检测,目标 A 或 A+。若提示 Chain issues: Incomplete,说明中间证书缺失;若提示 supports weak Diffie-Hellman,则是 DH 参数过小,可在 SSLCipherSuite 中去掉 DHE 套件,或生成 2048 位 dhparam。
最后做一次全链路回归:curl -s -o /dev/null -w '%{http_code} %{ssl_verify_result}n' https://example.com,输出 200 0 表示 HTTP 状态与证书校验双双正常,ssl_verify_result 非 0 就是证书链或域名匹配有问题。
常见问题
固定签发 90 天,目的是通过高频自动续期降低私钥泄露风险,不能申请更长有效期。公网信任证书受 CA/B Forum 约束,最长不超过 398 天,Apple、Chrome 会拒绝超期证书,因此 90 天完全合规,靠 ACME 自动续期即可,无需人工干预。
Apache 2.4.8 及以上必须指向 fullchain.pem,它包含叶子证书与中间证书,一次配好整条链。指向 cert.pem 会缺中间证书,浏览器靠 AIA 补链可能正常,但 curl、Java、小程序会直接报错。2.4.8 以下版本用 cert.pem 加 SSLCertificateChainFile 指向 chain.pem。
说明 Apache 进程没有重新加载证书。用 openssl s_client 查看服务端实际下发的 notAfter,与磁盘 fullchain.pem 对比即可确认。修复方式是在 /etc/letsencrypt/renewal-hooks/deploy/ 放一个执行 systemctl reload apache2 的脚本,certbot 每次续期成功后自动调用。
这是证书链不完整的典型报错。先确认 SSLCertificateFile 指向 fullchain.pem 而不是 cert.pem,再用 openssl s_client -showcerts 查看服务端下发的证书数量,正常应为两张以上。改完配置执行 apachectl configtest 后 reload 服务。
不建议首次上线就加。preload 会把域名写进浏览器硬编码名单,移除周期以月计。建议先用 max-age=300 验证全站 HTTPS 无混合内容,再逐步升到 31536000 并加 includeSubDomains,确认所有子域都支持 HTTPS 后再考虑 preload。
可以,改用 DNS-01 验证即可,无需开放 80 端口。certbot 安装对应 DNS 插件后用 –dns-插件名 参数,acme.sh 用 –dns dns_xxx 并配置 API 凭据。DNS-01 还支持签发通配符证书,例如 -d example.com -d ‘*.example.com’。