HAProxy SSL 配置实战:从 PEM 合并到 OCSP Stapling 的 6 个排查步骤
HAProxy SSL 配置的关键动作只有三步:在 bind 行写 ssl,把站点证书与中间证书合并成 PEM,用 crt 或 crt-list 指向 PEM,然后执行 haproxy -c 与 systemctl reload haproxy。 HAProxy 2.8/2.9 建议显式设置 ssl-default-bind-options no-sslv3 no-tlsv10 no-tlsv11 与 ssl-min-ver TLSv1.2,并保留 TLS 1.3;用 openssl s_client -alpn h2 验证 ALPN。 多域名或泛域名场景优先用 crt-list,每行一个 PEM 并绑定 SNI;证书链顺序应为站点证书→中间证书,根证书通常不必放入。 Let's Encrypt 证书可用 certbot --deploy-hook 'systemctl reload haproxy' 或 acme.sh --reloadcmd 'systemctl reload haproxy' 自动续期;商业 DV 常见约 0-300 元/年,OV 约 800-3000 元/年,以 CA 报价为准。
HAProxy SSL 配置为什么容易失败?先看 TLS 握手与证书链根因
HAProxy 不像 Nginx 那样把 ssl_certificate 和 ssl_certificate_key 分成两行配置,TLS 终止完全由 frontend 的 bind 行决定。据 HAProxy 官方文档,ssl 在 bind 上启用 TLS,crt 指向的 PEM 必须同时包含证书与私钥。下面是最小可用片段(HAProxy 2.8/2.9):
# /etc/haproxy/haproxy.cfg
global
# 显式声明最低版本,避免依赖 OpenSSL 默认值;默认值随底层 SSL 库而变
ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets
ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384
frontend fe_https
# ssl 启用终止;crt 指向「证书 + 私钥」合并后的 PEM
bind *:443 ssl crt /etc/haproxy/certs/example.com.pem alpn h2,http/1.1
default_backend bk_web
根因一:证书链不完整。这是“haproxy ssl 配置不生效”最常见的来源——只部署了站点证书。客户端会报 curl: (60) SSL certificate problem: unable to get local issuer certificate,openssl s_client 则返回 Verify return code: 20 (unable to get local issuer certificate)。据 Let’s Encrypt 文档,fullchain.pem 已按「站点证书 → 中间证书」排好序,直接拼接私钥即可,切忌把根证书放在最前面:
# 正确顺序:站点证书在前,中间证书在后,私钥位置随意但不要夹在链中间
cat fullchain.pem privkey.pem > /etc/haproxy/certs/example.com.pem
# 校验顺序:输出的第一段 CN 必须是你自己的域名,且不应出现 ISRG Root X1/X2
openssl crl2pkcs7 -nocrl -certfile /etc/haproxy/certs/example.com.pem
| openssl pkcs7 -print_certs -noout
根因二:私钥与证书不匹配。HAProxy 启动会直接失败,日志典型为 unable to load SSL private key from PEM file。用公钥指纹比对(RSA/ECDSA 通用):
openssl x509 -in fullchain.pem -noout -pubkey | openssl md5
openssl pkey -in privkey.pem -pubout | openssl md5
# 两个 MD5 必须完全一致,否则说明拿错了私钥
根因三:多域名只给了一个 crt。客户端不带 SNI 或域名未命中时,会拿到默认(第一个)证书。2.8/2.9 推荐 crt-list,每行一个 PEM 并显式绑定 SNI:
| 写法 | 示例 | 适用场景 | 坑点 |
|---|---|---|---|
| 单个 crt | crt site.pem |
单域名或一张多 SAN 证书 | 无 SNI 时回落到该证书 |
| crt 目录 | crt /etc/haproxy/certs/ |
证书多、按文件名自动建索引 | 目录内所有 PEM 都会被加载 |
| crt-list | crt-list /etc/haproxy/crt-list.txt |
需显式 SNI 过滤、别名、OCSP | 文件每行格式写错即启动失败 |
# /etc/haproxy/crt-list.txt
/etc/haproxy/certs/example.com.pem [ssl-min-ver TLSv1.2] ocsp-update on
/etc/haproxy/certs/api.example.com.pem
根因四:TLS 版本/套件不匹配。日志里出现 SSL handshake failure,多半是仍在用 TLS 1.0/1.1 的老设备。HAProxy 2.8 通常跑在 OpenSSL 3.x 上,显式设置 ssl-min-ver TLSv1.2 后用 openssl s_client -tls1_1 验证旧协议确实被拒(应看到 alert protocol version)。
根因五:reload 静默失败。HAProxy 是无缝 reload,新配置校验不通过时旧进程继续服务,浏览器自然还显示旧证书。别只看 systemctl reload 的返回码:
haproxy -c -f /etc/haproxy/haproxy.cfg # 期望:Configuration file is valid
journalctl -u haproxy -n 50 --no-pager # 看是否有 SSL 加载/解析错误
HAProxy SSL 配置完整实操步骤:从合并 PEM 到平滑 reload
把证书塞进 bind 行只是开始。下面 6 步是可直接照抄的最小闭环,每一步都给出验证手段——因为 HAProxy 的 TLS 故障里,真正难查的往往不是语法错,而是”进程起来了但读不到私钥”和”reload 成功但旧进程还在服务”。
第 1 步:合并 PEM 并收紧权限。HAProxy 的 crt 要求证书链与私钥在同一个文件里,顺序是”叶子证书 → 中间 CA → 私钥”:
# 1) 合并:fullchain.pem 在前,privkey.pem 在后
cat fullchain.pem privkey.pem > /etc/haproxy/certs/example.com.pem
# 2) 属主 root、属组 haproxy;640 = 属主读写,属组只读
chown root:haproxy /etc/haproxy/certs/example.com.pem
chmod 640 /etc/haproxy/certs/example.com.pem
# 注意:绝不 chmod 644。私钥一旦全局可读,任何本地用户都能离线冒用你的域名。
HAProxy 只需读权限即可。若配置了 global 段的 user haproxy(2.x 默认即以该用户运行 worker),640 root:haproxy 正好够用;若你还开了 OCSP 自动更新或 crt-list 热加载,worker 进程会在运行期重新读文件,权限过紧会报 [ALERT] ... cannot open ... Permission denied。
第 2 步:先验证书,再验私钥。合并后的文件是”证书+私钥”混合体,openssl x509 只会读第一段证书,正好用于校验:
# 看域名、签发者、有效期(notBefore/notAfter)
openssl x509 -in /etc/haproxy/certs/example.com.pem -noout -subject -issuer -dates
# RSA 私钥一致性检查
openssl rsa -in /etc/haproxy/certs/example.com.pem -check -noout
# ECDSA 私钥改用 pkey(RSA 也通用)
openssl pkey -in /etc/haproxy/certs/example.com.pem -check -noout
ECDSA 证书还要确认 HAProxy 链接的 OpenSSL 支持该曲线,用 haproxy -vv | grep -i openssl 看 Built with OpenSSL version 与 Running on OpenSSL version 是否一致(不一致常见于容器里挂载了宿主机库)。据 OpenSSL 官方文档,P-256/P-384 在 1.1.1 及以上均默认启用。
第 3 步:写 frontend。终止 TLS 的标准写法:
frontend fe_https
mode http
bind *:443 ssl crt /etc/haproxy/certs/example.com.pem alpn h2,http/1.1
default_backend be_app
如果 HAProxy 只做四层透传、TLS 由后端终止,则写 mode tcp 且 bind 行不能带 ssl——带了就等于在 HAProxy 上解密再明文转发,这是最常见的”配置能跑但架构错了”。
第 4 步:加全局 TLS 基线。写在 global 段,对全部 bind 生效:
global
# 协议下限(HAProxy 2.3 起默认值已含这三项,显式写出防止跨版本漂移)
ssl-default-bind-options no-sslv3 no-tlsv10 no-tlsv11
# TLS 1.2 及以下套件
ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
# TLS 1.3 套件必须用 ciphersuites,改 ciphers 对 1.3 无效
ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384
很多人只改 ciphers 就以为锁死了套件,结果 openssl s_client 仍协商出 TLS 1.3 的其它套件——因为 1.3 的套件由 ssl-default-bind-ciphersuites 独立控制(该关键字需 HAProxy 2.2+ 与 OpenSSL 1.1.1+)。
第 5 步:多域名改用 crt-list。一个 PEM 一个域名,靠 SNI 自动匹配:
# /etc/haproxy/certs/crt-list.txt
/etc/haproxy/certs/example.com.pem
/etc/haproxy/certs/api.example.com.pem [ocsp-update on]
# frontend 里改为
bind *:443 ssl crt-list /etc/haproxy/certs/crt-list.txt alpn h2,http/1.1
[ocsp-update on] 是 HAProxy 2.8 引入的按证书 OCSP 自动更新能力,低版本请改用外部定时任务刷新 stapling 文件。
| 对比项 | bind … crt 单文件 | bind … crt-list |
|---|---|---|
| 适用场景 | 单域名或一张多 SAN 证书 | 多域名、多张证书、需按证书设参数 |
| SNI 匹配 | 全部流量用同一证书 | 按 SNI 逐行匹配,未命中走首行 |
| OCSP 配置粒度 | 只能整 bind 统一 | 每行可加 [ocsp-update on](2.8+) |
| 增删证书 | 需改配置 + reload | 改 txt 后 reload,配置段不动 |
第 6 步:先 -c 校验,再 reload,最后验身份。
# 语法与证书加载校验,任何 ALERT 都不要继续
haproxy -c -f /etc/haproxy/haproxy.cfg
# 平滑 reload(master-worker 模式下不中断连接)
systemctl reload haproxy
# 确认监听 443 的确实是新 PID
ss -ltnp 'sport = :443'
# 对比 reload 前后证书 serial,防止"看似成功、旧进程仍在服务"
openssl s_client -connect 127.0.0.1:443 -servername example.com </dev/null 2>/dev/null
| openssl x509 -noout -serial -dates
典型失败输出是 [ALERT] (12345) : config : parsing [/etc/haproxy/haproxy.cfg:42] : 'bind :443' unable to load SSL private key from PEM file '/etc/haproxy/certs/example.com.pem'.——九成是合并顺序反了(私钥在前)或权限不足。生产环境建议低峰期 reload,并保留上一版 PEM 以便秒级回滚。
HAProxy SSL 配置示例:bind ssl crt、crt-list 与 OCSP Stapling 参数
问:一份能直接改域名就用的 HAProxy SSL 配置长什么样?
下面这份片段适配 HAProxy 2.8 / 2.9(2.6 也能跑,只有 ocsp-update 部分需要降级处理,见后文表格)。关键行都加了注释,改 example.com 为你的域名即可。
global
log /dev/log local0
maxconn 20000
# 统一收紧协议版本:显式写出比依赖默认值安全
# ssl-min-ver 默认值随版本变化(2.6+ 默认 TLSv1.2,2.4 及更早默认 TLSv1.0)
ssl-default-bind-options no-sslv3 no-tlsv10 no-tlsv11
# TLS1.2 及以下用 ciphers(OpenSSL 密码串)
ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
# TLS1.3 专用 ciphersuites,只能用 TLS_* 名称,写错会启动报错
ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384
defaults
mode http
option httplog # 记录 TLS/HTTP 细节,排查握手问题必备
timeout connect 5s # 未设置时 HAProxy 启动会告警并可能无限等待
timeout client 30s
timeout server 30s
frontend fe_https
# crt-list 支持多域名 + 每行独立参数;单个 crt 只能挂一个 PEM
bind *:443 ssl crt-list /etc/haproxy/certs/crt-list.txt ssl-min-ver TLSv1.2 alpn h2,http/1.1
capture request header Host len 64 # 对比 SNI 与 Host,定位 421/证书错配
http-request set-header X-Forwarded-Proto https # HAProxy 不会自动加,必须手写
default_backend be_app
backend be_app
server app1 127.0.0.1:8080 check
对应的 /etc/haproxy/certs/crt-list.txt(# 开头为注释,每行一个 PEM,证书链顺序必须是「服务器证书 → 中间 CA」):
# 每行:PEM 路径 [选项...]
/etc/haproxy/certs/example.com.pem
/etc/haproxy/certs/api.example.com.pem
# 2.8+ 由 HAProxy 自己定时刷新 OCSP,无需 cron
/etc/haproxy/certs/wildcard.example.com.pem [ocsp-update on]
问:OCSP Stapling 在 2.6 和 2.8 上做法差在哪?
| 维度 | HAProxy 2.6 及更早(外部任务) | HAProxy 2.8+(内置 ocsp-update) |
|---|---|---|
| 配置方式 | crontab 调 openssl ocsp 生成 cert.ocsp,PEM 同目录同名 |
crt-list 条目追加 [ocsp-update on] |
| 刷新间隔 | 自己写,通常 1 小时 | ocsp-update.mindelay(默认 300s)/ ocsp-update.maxdelay(默认 3600s) |
| 失败表现 | 文件过期后静默停止 stapling,客户端自行回源查询 | 日志出现 OCSP update 错误,仍返回旧响应直至过期 |
| 依赖 | 需要 chain.pem、外部脚本、文件权限 |
PEM 内必须含中间 CA,否则无法定位 responder |
据 Let’s Encrypt 文档,其 OCSP responder(http://ocsp.int-x3.letsencrypt.org)对单次查询有频率限制,手工调试时务必带 -no_nonce 复用缓存:
# 手工生成 .ocsp(2.6 及更早的常规做法)
openssl ocsp -issuer chain.pem -cert cert.pem
-url http://ocsp.int-x3.letsencrypt.org
-respout cert.ocsp -no_nonce
# 验证服务端是否真的在 stapling
openssl s_client -connect example.com:443 -servername example.com -status
# 期望看到:OCSP Response Status: successful (0x0)
# 若为 "no response sent",说明 PEM 缺中间 CA 或 ocsp-update 尚未完成首次拉取
问:怎么确认密码套件和协议版本真的生效了?
先确认 HAProxy 的编译参数——套件能否协商取决于链接的 OpenSSL,而不是配置文本。haproxy -vv 会输出 Built with OpenSSL 3.x 与 OPTIONS = ... OPENSSL ...,若看到的是 OpenSSL 1.1.1 且没有 TLSv1.3 字样,说明 ssl-default-bind-ciphersuites 会被忽略。
haproxy -vv | grep -E 'OpenSSL|TLSv1.3'
haproxy -c -f /etc/haproxy/haproxy.cfg # 改完先做配置校验
# 应成功(TLS1.2 + 指定套件)
openssl s_client -connect example.com:443 -servername example.com
-tls1_2 -cipher 'ECDHE-RSA-AES128-GCM-SHA256'
# 应失败,返回 protocol version alert
openssl s_client -connect example.com:443 -servername example.com -tls1_1
最后一条如果没被拒绝,检查 bind 行是否被更宽松的 ssl-default-bind-options 覆盖,或是否漏了 ssl-min-ver。真正失败时 HAProxy 日志往往只有一行 SSL handshake failure(见 Mozilla Server Side TLS 指南对 alert 的分类),必须回到 openssl s_client 看 alert protocol version / alert handshake failure 才能区分「版本被拒」和「无匹配套件/SNI 无证书」。
HAProxy SSL 配置方案对比:单 PEM、crt-list、TCP 透传与自动续期怎么选
单域名、多域名、泛域名,后端还要自己终止 TLS……到底该选哪种?先把四类方案的边界和代价摆出来,再谈 haproxy ssl 配置怎么落地。
| 方案 | 关键配置 | 适用场景 | 注意点 |
|---|---|---|---|
| 单 PEM + bind crt | bind *:443 ssl crt /etc/haproxy/certs/example.com.pem |
单域名或默认证书 | 多域名需改用 crt-list;续期后必须 reload 才生效 |
| crt-list 多证书 | bind *:443 ssl crt-list /etc/haproxy/certs/crt-list.txt |
多域名、泛域名、按 SNI 分流 | 每行一个 PEM;第一行是 SNI 未命中时的默认证书 |
| TCP 透传 | mode tcp + bind *:443(不写 ssl) |
后端必须自行终止 TLS | HAProxy 看不到 HTTP 层,无法做 L7 路由、加头、限流 |
| 前置 Nginx 终止 | Nginx ssl_certificate + HAProxy 后端走 HTTP |
已有 Nginx 生态与 WAF | 多一跳,排障要同时看两侧日志 |
| ACME 自动续期 | certbot --deploy-hook 'systemctl reload haproxy' |
Let’s Encrypt 免费证书 | hook 必须 reload,否则旧证书继续在内存里服役 |
多域名最常用的是 crt-list,注意 PEM 文件本身要把证书链和私钥拼在一起(顺序:服务端证书 → 中间 CA → 私钥),据 HAProxy 官方文档 Certificates 一节,单文件内的顺序即证书链顺序:
# /etc/haproxy/certs/crt-list.txt
# 每行一个 PEM;第一行是 SNI 未匹配时的默认证书
/etc/haproxy/certs/example.com.pem [ocsp-update on] example.com
# 泛域名证书,[ocsp-update on] 需 HAProxy 2.8+ 才支持自动 stapling
/etc/haproxy/certs/wildcard.example.com.pem [ocsp-update on] *.example.com
# 合并 PEM 的可复制命令(证书链在前,私钥在后)
cat fullchain.pem privkey.pem > /etc/haproxy/certs/example.com.pem
chmod 600 /etc/haproxy/certs/example.com.pem
haproxy -c -f /etc/haproxy/haproxy.cfg # 改完先做语法校验再 reload
续期侧,Let’s Encrypt 官方 certbot 文档推荐用 deploy-hook;acme.sh 的等价参数是 --reloadcmd:
# certbot:证书更新成功后自动让 HAProxy 重新加载
certbot renew --deploy-hook 'systemctl reload haproxy'
# acme.sh 写法
acme.sh --install-cert -d example.com
--fullchain-file /etc/haproxy/certs/fullchain.pem
--key-file /etc/haproxy/certs/privkey.pem
--reloadcmd 'systemctl reload haproxy'
选型结论:单域名先用 bind ssl crt;多域名或泛域名用 crt-list;只有后端确实要自己终止 TLS 时才用 mode tcp 透传。已有 Nginx 承担证书与 WAF 时,可以让 Nginx 终止 TLS、HAProxy 只做 HTTP 负载均衡,但链路多一跳,排障要同时翻 Nginx 与 HAProxy 日志。
成本上,Let’s Encrypt 免费;商业证书常见区间为 DV 约 0–300 元/年、OV 约 800–3000 元/年、EV 约 2000–8000 元/年,实际以 CA 与代理商报价为准。性能侧,maxconn 建议显式写(生产常从 20000 起步,未显式设置时 HAProxy 会按内存与 ulimit 估算),nbthread 默认等于可用 CPU 核数,4 核机器显式写 nbthread 4 更可控。TLS 握手吃 CPU,握手速率用运行时接口观察:
# 确认编译进去的 OpenSSL 版本与是否支持 TLS 1.3
haproxy -vv | grep -Ei 'HAProxy version|OpenSSL|OPTIONS'
# 需要 stats socket:global 段 stats socket /var/run/haproxy.sock mode 660 level admin
echo "show info" | socat stdio /var/run/haproxy.sock | grep -E 'SslRate|Maxconn|Nbthread'
合规与兼容性:据 Mozilla SSL Configuration Generator,面向现代浏览器的推荐配置只保留 TLS 1.2/1.3;HAProxy 2.3 起 ssl-default-bind-options 默认已禁用 SSLv3/TLS 1.0/TLS 1.1。若必须兼容旧 POS 机或 Android 5,请单独建一个 frontend 与独立证书,不要为了少数客户端把主站整体降级到 TLS 1.0。
- Wildcard 通配符 SSL 证书安装部署续费申请
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
- SSL/HTTPS 证书配置 · 证书安装 · 证书申请
HAProxy SSL 配置常见错误与排查:真实报错逐条拆解
在 haproxy ssl 配置里,90% 的启动失败和握手失败都能归到三类:PEM 内容不对、证书链不完整、权限/协议版本不匹配。下面按真实报错逐条拆解,每条都给出可直接复制的定位命令。
问:启动时报 [ALERT] ... unable to load SSL private key from PEM file '/etc/haproxy/certs/example.com.pem',怎么查?
这条 ALERT 只说明一件事:HAProxy 在 PEM 里找不到”能用的”私钥。两种常见原因——私钥根本不在 PEM 里,或私钥被口令加密了(HAProxy 没有交互终端,无法输入 passphrase)。按顺序执行:
# 1) 私钥本身是否健康:输出 "RSA key ok" 才算合格;若提示 Enter pass phrase 说明带口令
openssl rsa -in privkey.pem -check -noout
# 2) PEM 里是否真的有私钥块(期望输出 1)
grep -c "BEGIN.*PRIVATE KEY" /etc/haproxy/certs/example.com.pem
# 3) 若是加密私钥,先解密(OpenSSL 3.x 推荐 pkey)
openssl pkey -in encrypted.key -out privkey.pem
# 4) 权限与属主:HAProxy 主进程 root、工作进程 haproxy,640 + root:haproxy 即可
chown root:haproxy /etc/haproxy/certs/example.com.pem
chmod 640 /etc/haproxy/certs/example.com.pem
chmod 750 /etc/haproxy/certs
问:curl: (60) SSL certificate problem: unable to get local issuer certificate、Verify return code: 20 是什么问题?
返回码 20 是 OpenSSL 的 unable to get local issuer certificate,即服务端只发了叶证书、没发中间证书。据 Let’s Encrypt 文档的 Chain of Trust 说明,cert.pem 只有叶证书,fullchain.pem 才含中间证书。先看服务端实际返回几条:
# 统计服务端下发的证书数量,正常应为 2 条(叶证书 + 中间证书)
openssl s_client -connect example.com:443 -servername example.com -showcerts
</dev/null 2>/dev/null | grep -c "BEGIN CERTIFICATE"
# 正确做法:fullchain + 私钥,顺序不能反
cat fullchain.pem privkey.pem > /etc/haproxy/certs/example.com.pem
写成 cat cert.pem privkey.pem 就是本故障的典型成因,浏览器因缓存/AIA 抓取可能”看起来正常”,而 Java、Go、curl 客户端会直接失败。
问:[ALERT] ... cannot bind socket (Permission denied) for [0.0.0.0:443] 怎么解决?
Linux 上绑定 <1024 端口需要 CAP_NET_BIND_SERVICE。若你用 user haproxy 让 HAProxy 直接降权,或用非 root 的 systemd 单元启动,就会撞上这条。两种方案对比:
| 方案 | 配置要点 | 优点 | 代价 |
|---|---|---|---|
| 授予绑定能力(推荐) | AmbientCapabilities=CAP_NET_BIND_SERVICE |
仍监听 443,客户端无感 | 需 root 改 systemd 单元并 daemon-reload |
| 改监听 8443 + 端口转发 | HAProxy bind :8443 ssl,nftables/iptables 做 443→8443 DNAT |
完全不需要特权 | 日志里源 IP 需 proxy 协议或保留原地址规则 |
# /etc/systemd/system/haproxy.service.d/caps.conf
[Service]
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
# 生效
systemctl daemon-reload && systemctl restart haproxy
注意:不要用 chmod 777 处理证书目录,那等于把私钥暴露给本机所有用户。
问:日志里大量 SSL handshake failure,是配置错了吗?
先确认是不是”预期的拒绝”。HAProxy 自 2.4 起 ssl-min-ver 默认值为 TLSv1.2(更早版本默认 TLSv1.0),RHEL 9 / Ubuntu 22.04 等发行版还把 OpenSSL 3.x 的默认安全级别调到 2,会额外拒绝 SHA-1 签名与 <2048 位 RSA 证书。定位命令:
# 强制用 TLS1.1 握手,若返回 protocol version alert,说明是被 ssl-min-ver 主动拒绝
openssl s_client -connect example.com:443 -servername example.com -tls1_1 </dev/null
# 显式声明最低版本与套件(HAProxy 2.8 语法)
bind :443 ssl crt /etc/haproxy/certs/example.com.pem ssl-min-ver TLSv1.2
ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384
TLS 1.3 的套件由 ssl-default-bind-ciphersuites 控制,写进 ssl-default-bind-ciphers 不生效——这是漏配套件最常见的原因。
问:systemctl reload haproxy 之后证书怎么还是旧的?
HAProxy 的 reload 是”新进程起来、旧进程优雅退出”,如果新配置加载失败,旧进程会继续持有旧证书。两步验证:
# 1) 看 reload 是否真的成功、有无 SSL 相关告警
journalctl -u haproxy -n 50 --no-pager | grep -iE "ssl|crt|reload|ALERT"
# 2) 对比实际下发的证书序列号(换证书后 serial 必然变化)
openssl s_client -connect 127.0.0.1:443 -servername example.com </dev/null 2>/dev/null
| openssl x509 -noout -serial -dates
serial 未变,要么新 PEM 路径与 bind ... crt 不一致,要么旧进程尚未退出(可配合 hard-stop-after 限制旧进程存活时间)。
问:openssl s_client -status 显示 OCSP response: no response sent?
HAProxy 2.8 起支持内置 OCSP 自动更新,开关写在 crt-list 而非 bind 行;2.8 之前则依赖同目录的 .ocsp 文件或外部脚本。配置示例:
# /etc/haproxy/certs/crt-list.txt
/etc/haproxy/certs/example.com.pem [ocsp-update on]
# haproxy.cfg
bind :443 ssl crt-list /etc/haproxy/certs/crt-list.txt
# 更新器需要 DNS 解析 OCSP 响应器域名,故必须配置 resolvers 段
验证:openssl s_client -connect example.com:443 -servername example.com -status </dev/null 2>/dev/null | grep -A2 "OCSP Response Status",期望看到 successful。注意 OCSP 走的是明文 HTTP(80 端口),出站防火墙只放行 443 会导致更新一直失败。
如何验证 HAProxy SSL 配置生效?openssl s_client 与 curl 检查清单
静态检查永远是第一步,因为 HAProxy 的 reload 是”新进程起来、旧进程才退”,配置写错时你往往感知不到——旧连接继续由老进程服务,看起来”一切正常”。所以先跑这两条:
# 1. 语法与关键字校验(HAProxy 2.0+ 通用)
haproxy -c -f /etc/haproxy/haproxy.cfg
# 期望输出:Configuration file is valid
# 2. 版本与 TLS 库能力(决定哪些关键字可用)
haproxy -vv | grep -E 'HAProxy version|OpenSSL|TLSv1.3'
# 期望:HAProxy version 2.8.x / 2.9.x,OpenSSL 1.1.1w 或 3.x,且列出 TLSv1.3
为什么要看第二行?据 HAProxy 官方文档,ssl-default-bind-ciphersuites(TLS 1.3 密码套件)依赖 OpenSSL 1.1.1+;如果你的 HAProxy 编译时链接的是 OpenSSL 1.0.2,这条指令会直接报 [ALERT] (1234) : config : parsing [haproxy.cfg:45] : unknown keyword 'ssl-default-bind-ciphersuites',此时应改用 ssl-default-bind-ciphers。这正是很多 haproxy ssl 配置”抄了文档却起不来”的根因。
语法通过后,reload 并立刻验证进程真的换了:
systemctl reload haproxy
journalctl -u haproxy -n 50 --no-pager | grep -Ei 'alert|unable to load|error'
ss -ltnp 'sport = :443' # 必须能看到 haproxy 进程在监听
若日志出现 [ALERT] ... unable to load SSL private key from PEM file,说明 PEM 里私钥与证书不匹配或合并顺序错误(HAProxy 要求 cert+key+chain 顺序,见其 configuration.txt 的 crt 说明)。
接下来是证书链与主机名,这是 Let’s Encrypt 用户最常踩的坑:
openssl s_client -connect example.com:443 -servername example.com
-CAfile /etc/ssl/certs/ca-certificates.crt </dev/null
# 关注最后一行:Verify return code: 0 (ok)
| Verify return code | 含义 | 处理动作 |
|---|---|---|
| 0 (ok) | 链完整、主机名匹配 | 通过 |
| 20 (unable to get local issuer certificate) | 缺中间证书 | 把 fullchain.pem 合并进 PEM,而非只放 leaf |
| 21 (unable to verify the first certificate) | 服务端只发了 leaf | 同上,检查 crt 文件内容顺序 |
| 62 (hostname mismatch) | SNI 命中错误证书 | 核对 crt-list 中的域名与 -servername |
ALPN 与 TLS 版本边界一并验证,据 RFC 7301,h2 必须通过 ALPN 协商:
openssl s_client -connect example.com:443 -servername example.com -alpn h2 /dev/null | grep 'ALPN protocol'
# 期望:ALPN protocol: h2
curl -I --http2 https://example.com # 期望 HTTP/2 200
openssl s_client -connect example.com:443 -tls1_1 &1 | grep -E 'alert protocol version|no protocols available'
curl 若回退到 HTTP/1.1,说明 bind 行缺 alpn h2,http/1.1;-tls1_1 报 alert protocol version 才证明 ssl-min-ver TLSv1.2 生效(Mozilla SSL Configuration Generator 对 2.8 的推荐即 ssl-min-ver TLSv1.2)。最后确认 OCSP 与证书确实更新:
openssl s_client -connect example.com:443 -servername example.com -status /dev/null | grep 'OCSP Response Status'
# 期望:OCSP Response Status: successful (0x0)
openssl s_client -connect example.com:443 -servername example.com /dev/null
| openssl x509 -noout -serial -dates # 对比续期前后的 serial 与 notAfter
单域名或只需要一个默认证书时,用 `bind *:443 ssl crt /path/example.com.pem` 最简单。多域名、泛域名或需要按 SNI 选择不同证书时,用 `crt-list`,每行一个 PEM,bind 改为 `crt-list /path/crt-list.txt`;改完先 `haproxy -c` 再 `systemctl reload haproxy`。
把站点证书与中间证书按“站点证书→中间证书”的顺序合并成 PEM,例如 `cat fullchain.pem privkey.pem > example.com.pem`,根证书通常不必放入。用 `openssl s_client -showcerts` 检查返回链,若 `Verify return code: 20` 仍出现,说明中间证书顺序或文件内容不对。
Nginx 用 `ssl_certificate` 与 `ssl_certificate_key` 分开指定证书和私钥;HAProxy 通常把证书、中间证书和私钥合并成一个 PEM,由 `bind … ssl crt` 加载。HAProxy 更适合四层/七层负载均衡入口,若已有 Nginx 处理 WAF 或证书,也可以让 Nginx 终止 TLS、HAProxy 只做后端 HTTP 负载均衡。
常见原因是 `haproxy -c` 未通过、reload 失败但旧进程仍在,或 PEM 路径写错。执行 `journalctl -u haproxy -n 50 –no-pager` 看报错,再用 `openssl s_client … | openssl x509 -noout -serial` 对比 serial;serial 未变就检查证书文件是否真的被替换。
先确认 PEM 中私钥存在且未加密,RSA 用 `openssl rsa -in privkey.pem -check -noout`,ECDSA 用 `openssl pkey -in privkey.pem -check -noout`。再检查权限是否为 `640`、属主是否为 `root:haproxy`,以及私钥与证书是否匹配;带口令的私钥需要先解密再合并。
TLS 1.3 需要 HAProxy 链接 OpenSSL 1.1.1 或 3.x,并用 `ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384` 设置套件;HTTP/2 在 bind 行写 `alpn h2,http/1.1`。验证用 `openssl s_client -alpn h2` 看 `ALPN protocol: h2`,以及 `curl -I –http2` 看是否返回 HTTP/2。
certbot 用 `certbot renew –deploy-hook 'systemctl reload haproxy'`,acme.sh 用 `–reloadcmd 'systemctl reload haproxy'`;续期后要确保 fullchain 与 privkey 重新合并成 HAProxy 读取的 PEM。上线前执行 `certbot renew –dry-run` 或 `acme.sh –renew –force` 验证 reload 钩子是否成功。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。