OpenResty SSL 证书安装实操:从证书链、OCSP Stapling 到 TLS 1.3 验证
OpenResty 安装 SSL 证书不是执行某个安装命令,而是把 fullchain.pem 与 privkey.pem 放到 /usr/local/openresty/nginx/conf/ssl/,在 server 块用 ssl_certificate 与 ssl_certificate_key 引用,然后 openresty -t && openresty -s reload,通常 1-3 秒生效。 证书链必须用 fullchain.pem(叶子证书加中间 CA),只配单证书时 curl、Java 旧 truststore 常报 unable to get local issuer certificate;openssl verify -untrusted chain.pem example.com.crt 应返回 OK。 OpenResty 1.25.3.1 建议 ssl_protocols TLSv1.2 TLSv1.3,ssl_session_cache shared:SSL:10m,ssl_stapling on 且配 ssl_trusted_certificate chain.pem 与 resolver 223.5.5.5 119.29.29.29 valid=300s。 Let's Encrypt DV 证书有效期 90 天、费用 0 元,用 acme.sh --issue --webroot 后 --install-cert 并 openresty -s reload;商业 OV 常见 800-5000 元/年、审核 1-5 个工作日。 验证用 openssl s_client -connect example.com:443 -servername example.com -showcerts,看到 Verify return code: 0 (ok) 与 Protocol: TLSv1.3 才算链路和协议都正常。
问题背景与根本原因:OpenResty 装了证书为什么还报 SSL 错误?
Q:OpenResty 有专门的「安装证书」命令吗?为什么我把证书传上去还是报 SSL 错误?
没有。OpenResty 不自带 certbot install 这类证书安装器,所谓 openresty ssl证书安装,本质只有三步:证书文件落盘 → nginx.conf 里被实际加载的 server 块引用 → 平滑 reload。任何一步没闭环,都会表现为「证书明明传上去了却报错」。以 OpenResty 1.25.3.1 为例,默认 prefix 为 /usr/local/openresty/nginx,二进制在 /usr/local/openresty/bin/openresty。
# 1) 落盘:目录 700、私钥 600,证书链用 fullchain(叶子证书 + 中间 CA)
install -d -m 700 /usr/local/openresty/nginx/conf/ssl
install -m 644 fullchain.pem /usr/local/openresty/nginx/conf/ssl/example.com.crt
install -m 600 privkey.pem /usr/local/openresty/nginx/conf/ssl/example.com.key
# 2) 在【被 include 的那个】server 块里引用(nginx 1.25 已弃用 listen ... ssl 之外的旧写法)
# listen 443 ssl;
# ssl_certificate /usr/local/openresty/nginx/conf/ssl/example.com.crt;
# ssl_certificate_key /usr/local/openresty/nginx/conf/ssl/example.com.key;
# 3) 检查 + 热加载:master 不退出,worker 在 1-3 秒内被替换
/usr/local/openresty/bin/openresty -t # 语法检查,默认读 conf/nginx.conf
/usr/local/openresty/bin/openresty -s reload
ps -eo pid,ppid,cmd | grep nginx # master PID 不变,worker PID 全变即为成功
Q:浏览器显示锁正常,但 curl / Java 客户端报错,怎么回事?
九成是证书链不完整——只部署了 example.com.crt 而没拼中间 CA。桌面浏览器会通过 AIA(Authority Information Access)自动补链,所以看起来「正常」;而 curl、Java 8 旧 truststore、部分 Android WebView 不会补,直接报 curl: (60) SSL certificate problem: unable to get local issuer certificate。据 Let’s Encrypt 文档,其签发证书必须与中间证书 R3/E1 等一起组成完整链才能被严格客户端验证;nginx 官方文档也明确 ssl_certificate 应指向「服务器证书 + 中间证书」的拼接文件。验证方法:
# 期望输出 >=2,只有 1 说明链断了
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null
| grep -c 'BEGIN CERTIFICATE'
Q:reload 时提示私钥和证书不匹配怎么办?
典型报错:nginx: [emerg] SSL_CTX_use_PrivateKey() failed (SSL: ...X509_check_private_key:key values mismatch)。用 OpenSSL 比对模数即可定位:
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in privkey.pem | openssl md5 # 两行 md5 必须一致
Q:openresty -t 通过了,线上却仍是旧证书 / 别的域名证书?
两种常见原因,用合并后配置与证书 SAN 一起排查:
/usr/local/openresty/bin/openresty -T 2>/dev/null | grep -n 'listen 443' # 看真正生效的 server
openssl x509 -noout -text -in fullchain.pem | grep -A1 'Subject Alternative Name'
| 现象 | 根因 | 一条验证命令 |
|---|---|---|
unable to get local issuer certificate |
缺中间 CA,链不完整 | openssl s_client -showcerts 数证书张数 |
SSL_CTX_use_PrivateKey() failed |
私钥与证书不配对 | 比对两者 -modulus | md5 |
| 改了配置无效果 | 改错 conf.d 文件 / server 块缺 listen 443 ssl |
openresty -T | grep 'listen 443' |
| 老客户端拿到别的域名证书 | 不支持 SNI,落到 default_server |
将主域名标 default_server,确认 SAN 覆盖 server_name |
13: Permission denied |
私钥权限过宽或 SELinux 上下文错误 | ls -Z + restorecon -Rv |
Q:权限与 SELinux 具体怎么配?
worker 以 nobody 运行时需能读到私钥:文件 chmod 600、目录 chmod 700、属主与 master 一致。若开启 SELinux,/usr/local/openresty/nginx/conf/ssl 若不在 httpd_config_t 可读上下文内,reload 会报 BIO_new_file() failed ... Permission denied:
ls -Z /usr/local/openresty/nginx/conf/ssl
restorecon -Rv /usr/local/openresty/nginx/conf/ssl # 按策略重打标签
getenforce # Enforcing 下必须处理,Permissive 只是掩盖问题
下一步才是 OCSP Stapling、TLS 1.3 与 ssl_protocols 的取舍——据 RFC 8446 与 Mozilla SSL Configuration Generator 的 intermediate 配置,ssl_protocols TLSv1.2 TLSv1.3 已是 2024 年后的合理默认值。
完整实操步骤:OpenResty SSL 证书安装按这 8 步走
把 openresty ssl证书安装拆成 8 步,每一步都有可复制的命令和可验证的输出。以下命令默认 OpenResty 安装在 /usr/local/openresty,非默认路径请自行替换。
第 1 步:先确认版本,否则 TLS 1.3 可能根本开不起来。执行:
# 查看 OpenResty 版本及其编译时链接的 OpenSSL 版本
openresty -V 2>&1 | grep -E 'openresty|openssl'
# 典型输出:
# nginx version: openresty/1.25.3.1
# built with OpenSSL 3.0.13 30 Jan 2024
# 若显示 "built with OpenSSL 1.0.2k" 则无 TLS 1.3 支持
TLS 1.3 需要 OpenSSL 1.1.1 及以上(RFC 8446),OpenResty 1.25.3.1 默认捆绑 OpenSSL 3.0.x,1.21.4.1 默认捆绑 1.1.1 系列。据 OpenSSL 官方文档,1.1.1 是首个完整实现 TLS 1.3 的长期支持版本。
第 2 步:生成私钥与 CSR。RSA 2048(兼容性最好):
# -nodes 表示私钥不加密,便于 Nginx 自动加载;-addext 写入 SAN,现代浏览器只看 SAN 不看 CN
openssl req -new -newkey rsa:2048 -nodes
-keyout example.com.key -out example.com.csr
-subj '/C=CN/ST=Zhejiang/L=Hangzhou/O=Example/CN=example.com'
-addext 'subjectAltName=DNS:example.com,DNS:www.example.com'
ECDSA P-256(握手更快、证书更小,但需客户端支持):
openssl ecparam -genkey -name prime256v1 -out example.com.key
openssl req -new -key example.com.key -out example.com.csr
-subj '/C=CN/ST=Zhejiang/L=Hangzhou/O=Example/CN=example.com'
-addext 'subjectAltName=DNS:example.com,DNS:www.example.com'
第 3 步:签发。Let’s Encrypt 用 acme.sh 最省事:
# --webroot 走 HTTP-01 校验,需 80 端口可达;-d 可重复指定多个域名
acme.sh --issue -d example.com -d www.example.com --webroot /data/www
DV 证书通常 1–10 分钟签发;OV/EV 需人工核验企业资料,一般 1–5 个工作日。商业证书则把上一步的 CSR 提交给 CA。
第 4 步:合并证书链——这是最容易出错的一步。
# fullchain = 叶子证书 + 中间证书,顺序不能反
cat example.com.crt intermediate.crt > fullchain.pem
# chain.pem 只放中间证书,供 OCSP Stapling 与 ssl_trusted_certificate 使用
cp intermediate.crt chain.pem
根证书一般不放(客户端本就信任它,放了反而增大握手包)。据 Let’s Encrypt 文档,其 chain.pem 提供的是 ISRG Root X1 交叉签名的中间证书,务必使用 CA 提供的最新版本。
| 文件 | 内容 | 权限 | 用途 |
|---|---|---|---|
| fullchain.pem | 叶子 + 中间 | 644 | ssl_certificate |
| chain.pem | 仅中间证书 | 644 | ssl_trusted_certificate |
| privkey.pem | 私钥 | 600 | ssl_certificate_key |
第 5 步:放置文件并收紧权限。
install -d -m 700 /usr/local/openresty/nginx/conf/ssl
install -m 644 fullchain.pem /usr/local/openresty/nginx/conf/ssl/
install -m 644 chain.pem /usr/local/openresty/nginx/conf/ssl/
install -m 600 privkey.pem /usr/local/openresty/nginx/conf/ssl/
第 6 步:改配置。在 server 块内:
listen 443 ssl;
http2 on; # 1.25.1+ 推荐写法;旧版用 listen 443 ssl http2;
ssl_certificate ssl/fullchain.pem; # 相对 conf 目录
ssl_certificate_key ssl/privkey.pem;
ssl_trusted_certificate ssl/chain.pem; # OCSP Stapling 校验链用
ssl_protocols TLSv1.2 TLSv1.3; # 默认值仅 TLSv1.2 TLSv1.3(1.25.x)
ssl_stapling on;
ssl_stapling_verify on;
ssl_session_cache shared:SSL:10m;
第 7 步:检查,失败绝不 reload。
openresty -t
# 期望:nginx: configuration file /usr/local/openresty/nginx/conf/nginx.conf test is successful
# 常见报错:nginx: [emerg] cannot load certificate ... PEM_read_bio_X509_AUX() failed
# 说明 fullchain.pem 里混入了私钥或顺序错误
第 8 步:热加载并观察日志。
openresty -s reload
tail -f /usr/local/openresty/nginx/logs/error.log
# 关注 1–3 分钟,不应出现 emerg,也不应出现
# "ssl_stapling" ignored, issuer certificate not found
最后用 openssl s_client -connect example.com:443 -servername example.com -tls1_3 </dev/null 验证协商到 TLSv1.3 且返回完整链,至此 openresty ssl证书安装完成。
配置与命令示例:nginx.conf、OCSP Stapling 和权限怎么设置?
问:HTTPS server 块到底怎么写?为什么我的 listen 443 ssl http2 会报 deprecated 警告?
这是 OpenResty 版本分水岭导致的。Nginx 1.25.1 起把 HTTP/2 从 listen 参数拆成独立指令 http2,旧的写法会触发 nginx: [warn] the "listen ... http2" directive is deprecated, use the "http2" directive instead。按你的 OpenResty 版本二选一:
| OpenResty 版本 | 上游 Nginx | 推荐写法 |
|---|---|---|
| 1.21.4.1 及更早 | 1.21.4 | listen 443 ssl http2; |
| 1.25.3.1 及之后 | 1.25.3 | listen 443 ssl; + http2 on; |
server {
listen 443 ssl; # 1.25.3.1 写法;旧版改成 listen 443 ssl http2;
http2 on; # 仅 1.25.x 支持,旧版删掉此行
server_name example.com www.example.com;
# fullchain.pem = 站点证书 + 中间证书;私钥必须与叶证书公钥匹配
ssl_certificate /usr/local/openresty/nginx/conf/ssl/fullchain.pem;
ssl_certificate_key /usr/local/openresty/nginx/conf/ssl/privkey.pem;
# 只放中间链,供 OCSP Stapling 构建验证链;缺它 stapling 直接失效
ssl_trusted_certificate /usr/local/openresty/nginx/conf/ssl/chain.pem;
ssl_protocols TLSv1.2 TLSv1.3; # TLSv1.3 需 OpenSSL 1.1.1+,官方预编译包已满足
# 注意:ssl_ciphers 只作用于 TLS 1.2 及以下,TLS 1.3 套件由 ssl_conf_command Ciphersuites 控制
ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305';
ssl_prefer_server_ciphers off; # 遵循 Mozilla SSL Configuration Generator 的 intermediate 配置
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets off; # ticket key 不轮换会削弱前向保密(RFC 5077)
}
问:OCSP Stapling 开了却提示 ignored,怎么排查?
ssl_stapling on;
ssl_stapling_verify on;
resolver 223.5.5.5 119.29.29.29 valid=300s; # 必须显式配 DNS,否则无法拉取 OCSP 响应
resolver_timeout 5s;
最常见的报错是 nginx: [warn] "ssl_stapling" ignored, issuer certificate not found for certificate ".../fullchain.pem"——说明 ssl_trusted_certificate 没指向中间链 chain.pem。据 OpenSSL 文档,可用 openssl s_client -connect example.com:443 -status 查看响应,输出中出现 OCSP Response Status: successful 即生效;空白则说明 stapling 未工作。
问:80 跳转和 HSTS 怎么配才安全?
server {
listen 80;
server_name example.com www.example.com;
return 301 https://$host$request_uri;
}
# 在 HTTPS server 块内追加;首次上线建议 max-age=300 观察 1-2 天再放大
add_header Strict-Transport-Security 'max-age=31536000' always;
HSTS 一旦下发浏览器就会强制走 HTTPS,回滚成本高(RFC 6797),所以先用短 max-age 试水;确认全站资源无混合内容后再提到一年。
问:能同时装 RSA 和 ECDSA 证书吗?
# Nginx 1.11.0 起支持多份 ssl_certificate,OpenResty 1.25.3.1 可直接用
ssl_certificate .../rsa.fullchain.pem;
ssl_certificate_key .../rsa.key;
ssl_certificate .../ecdsa.fullchain.pem;
ssl_certificate_key .../ecdsa.key;
顺序即默认优先级:ECDSA 握手更快、报文更短,但少数老旧客户端只支持 RSA,建议按真实客户端覆盖率测试后决定谁在前。
问:私钥权限怎么设?644 行不行?
chown root:root /usr/local/openresty/nginx/conf/ssl/privkey.pem
chmod 600 /usr/local/openresty/nginx/conf/ssl/privkey.pem
ps -o user= -C nginx # 查看实际运行用户
master 进程以 root 启动时 600 足够(worker 由 master 打开文件后降权)。若在容器或 systemd User= 下以非 root 启动,则 chown 给该用户,但仍不要给 644,否则同机任意用户可读私钥。
问:改完配置,openresty -t 之前该跑哪些检查?
openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
openssl verify -untrusted chain.pem example.com.crt # 用中间链验证叶证书
openssl rsa -in privkey.pem -check # ECDSA 私钥改用 openssl ec -in privkey.pem -check
openresty -t && openresty -s reload
三条都通过再 reload。若私钥与证书不匹配,reload 会直接失败并报 nginx: [emerg] SSL_CTX_use_PrivateKey(...) failed (SSL: error:...key values mismatch),此时回到 openssl x509 -noout -modulus 与 openssl rsa -noout -modulus 对比摘要值即可定位。以上配置完成后,才算真正把 openresty ssl证书安装 走完整个闭环;后续 TLS 1.3 验证与证书续期可在此基础上叠加。
方案选型对比:DV、通配符、OV、ACME 自动续期在 OpenResty 上怎么选?
预算有限、又要跑多子域,到底该买哪种证书?先看结论:单域名站点和测试环境直接上 Let’s Encrypt DV;多级子域用通配符 + DNS-01;企业门户或支付场景才需要 OV/EV 的组织身份背书。下表按 2025 年常见公开报价整理(实际以 CA 渠道价为准),第四列直接对应 openresty ssl证书安装 时的落地点。
| 场景 | 推荐证书 | OpenResty 关键配置 | 续期与成本 |
|---|---|---|---|
| 单域名博客或测试 | Let’s Encrypt DV | fullchain.pem + privkey.pem;acme.sh --webroot |
90 天;0 元;每日 03:17 定时检查 |
| 多子域网关 | 通配符 DV(*.example.com) |
必须走 DNS-01;server_name 与 SAN 严格匹配 |
90 天或 1 年;0–1500 元/年 |
| 企业门户或支付 | OV 或 EV | 同上,另加 HSTS、OCSP Stapling、TLS1.2/1.3 | 1 年;800–5000 元/年;审核 1–5 个工作日 |
| 高兼容双栈 | RSA 2048 + ECDSA P-256 双证书 | 两组 ssl_certificate 与 ssl_certificate_key |
续期两份;成本同上 |
为什么通配符必须用 DNS-01?因为 ACME 的 HTTP-01 校验要求逐个域名回源到 /.well-known/acme-challenge/,而通配符的授权校验只能通过 DNS TXT 记录完成(见 RFC 8555 第 7.1.3 节对 dns-01 的定义)。下面这条命令一次签发主域与泛域名,OpenResty 重载由 --reloadcmd 托管:
# 安装并显式切回 Let's Encrypt(acme.sh 自 3.0 起默认 CA 为 ZeroSSL)
curl https://get.acme.sh | sh -s email=ops@example.com
~/.acme.sh/acme.sh --set-default-ca --server letsencrypt
# 通配符走 DNS-01(以阿里云 DNS 为例,密钥来自 RAM 子账号)
export Ali_Key="LTAI******"; export Ali_Secret="******"
~/.acme.sh/acme.sh --issue --dns dns_ali
-d example.com -d '*.example.com'
--keylength ec-256
--reloadcmd "openresty -t && openresty -s reload"
双证书怎么落盘?OpenResty 基于 nginx 1.11.0 以上即支持在同一 server 块重复声明证书,按客户端 ClientHello 的签名算法自动选择;ssl_certificate 默认值为 none,不配置则握手直接失败。
server {
listen 443 ssl;
# OpenResty 1.25.3.1+ 推荐 http2 on;;更早版本写成 listen 443 ssl http2;
server_name example.com;
# 顺序无关,nginx 按算法匹配;ECDSA 优先给现代客户端
ssl_certificate /etc/openresty/ssl/example.com.ecdsa.fullchain.pem;
ssl_certificate_key /etc/openresty/ssl/example.com.ecdsa.key;
ssl_certificate /etc/openresty/ssl/example.com.rsa.fullchain.pem; # 兼容 Android 4.x 等老客户端
ssl_certificate_key /etc/openresty/ssl/example.com.rsa.key;
ssl_protocols TLSv1.2 TLSv1.3; # 默认值随版本变化,务必显式声明
ssl_session_cache shared:SSL:10m;
ssl_stapling on;
ssl_stapling_verify on;
}
续期窗口设多少?据 Let’s Encrypt 官方文档,证书有效期固定 90 天,官方建议在到期前 30 天续期、且不要依赖”最后一天”;实践上把 acme.sh 的 cron 保持默认 17 3 * * *(每日 03:17)即可,它只在剩余天数低于 60 天才真正发起签发。商业证书虽然仍是 1 年,但受 CA/Browser Forum SC-081 影响,2026-03-15 起公开信任证书最长有效期将降至 200 天,续期自动化不再是”可选优化”。
老设备非要 TLS 1.1 怎么办?先算账:PCI DSS v4.0 要求 2024-03-31 后新环境不得使用 TLS 1.0/1.1,Mozilla SSL Configuration Generator 的 Intermediate 配置同样只保留 TLS 1.2/1.3。若确实存在存量客户端,建议按 server_name 拆出独立虚拟主机临时降级,而不是把全站 ssl_protocols 拉低——这是 openresty ssl证书安装 中最容易留下长期技术债的一步。做双栈时可先用 openssl s_client -connect example.com:443 -tls1_3 -servername example.com 确认握手协议版本与返回的证书链,再决定是否需要保留 RSA 分支。
EV 证书值不值得加钱?Chrome 77 起已移除 EV 的绿色地址栏与公司名展示,仅剩证书详情页可查,因此除非合规条款明确要求,把钱花在 OV 的审核与 OCSP Stapling 优化上回报更高。
常见错误与排查:这些真实报错分别对应什么原因?
把 openresty -t 的原始输出和浏览器报错逐条对照,绝大多数 openresty ssl证书安装 失败都能归到这六条。下面每条都给出可直接复制的排查命令。
问:nginx: [emerg] cannot load certificate … PEM_read_bio_X509_AUX() failed (SSL: error:0480006C:PEM routines::no start line) 是什么原因?
答:OpenSSL 3.x 在文件里找不到 -----BEGIN CERTIFICATE----- 起始行。常见成因只有三个:文件为 0 字节(复制或 scp 中断)、Windows 编辑后带了 CRLF、把私钥段拼进了证书文件。三步确认:
# 1. 文件类型与大小:应为 "PEM certificate",大小不为 0
file fullchain.pem && ls -l fullchain.pem
# 2. 首行必须是证书起始标记;若出现 "PRIVATE KEY" 说明私钥被拼进来了
head -1 fullchain.pem
# 3. 能解析出 subject 才说明证书本体完整
openssl x509 -in fullchain.pem -noout -subject
# 若怀疑 CRLF(OpenSSL 3.x 对行尾比 1.1.1 严格)
sed -i 's/r$//' fullchain.pem
问:SSL_CTX_use_PrivateKey_file(…) failed (SSL: error:1C800064:Provider routines::bad decrypt) 怎么修?
答:私钥被密码保护,或与证书不配对。OpenSSL 3.x 走 provider 层因此报 Provider routines::bad decrypt,1.1.1 则直接报 bad decrypt,含义相同。先用 openssl rsa -in privkey.pem -check 确认可用,再比对 modulus 的 MD5:
# 两个 MD5 必须完全一致,否则证书与私钥不是一对
openssl x509 -in fullchain.pem -noout -modulus | openssl md5
openssl rsa -in privkey.pem -noout -modulus | openssl md5
# 导出无密码私钥(会提示输入原密码),重命名为 privkey.pem 后 reload
openssl rsa -in enc.key -out privkey.pem
问:curl: (60) SSL certificate problem: unable to get local issuer certificate?
答:缺中间证书。据 Let’s Encrypt 文档,服务端必须下发“叶子证书 + 中间证书”,顺序不能颠倒:
cat example.com.crt intermediate.crt > fullchain.pem
# -untrusted 只喂中间证书,不要喂根证书;返回 OK 即链完整
openssl verify -untrusted chain.pem example.com.crt
问:nginx: [warn] ‘ssl_stapling’ ignored, issuer certificate not found for certificate?
答:ssl_stapling 默认 off,开启后必须同时给 ssl_trusted_certificate(指向含中间+根的 chain.pem),否则 Nginx 无法验证 OCSP 响应签名(RFC 6960)。另外 resolver 没有默认值,不配则无法解析 OCSP 域名:
resolver 223.5.5.5 119.29.29.29 valid=300s ipv6=off;
ssl_stapling on;
ssl_stapling_verify on; # 默认 off,建议开启
ssl_trusted_certificate /usr/local/openresty/nginx/conf/cert/chain.pem;
# 验证是否真的 Stapling 成功
openssl s_client -connect example.com:443 -servername example.com -status </dev/null 2>/dev/null | grep -A1 "OCSP Response Status"
问:nginx: [emerg] no ‘ssl_certificate’ is defined for the ‘listen … ssl’ directive?
答:该 server 块内没有证书指令,多是 include 顺序或 server 块拆分导致证书落在了别的 server 里。用合并视图定位:
openresty -T | grep -n "ssl_certificate" # 看证书出现在哪个 server 上下文
openresty -T | grep -n "listen .*ssl"
确认 listen 443 ssl; 与 ssl_certificate 处于同一个 server 块内。
问:浏览器报 NET::ERR_CERT_COMMON_NAME_INVALID 或 SSL_ERROR_BAD_CERT_DOMAIN?
答:自 Chrome 58 起只看 SAN(subjectAltName),CN 已失效(RFC 6125 亦如此建议)。检查并重新签发:
openssl x509 -in fullchain.pem -noout -ext subjectAltName
# 用 certbot 重签时显式带上所有域名
certbot certonly --webroot -w /var/www/html -d example.com -d www.example.com
| 报错关键词 | 首查命令 | 最常见根因 |
|---|---|---|
| no start line | head -1 fullchain.pem |
空文件 / CRLF / 私钥混入 |
| bad decrypt | openssl rsa -check |
私钥有密码或与证书不配对 |
| unable to get local issuer | openssl verify -untrusted |
缺中间证书 |
| ssl_stapling ignored | s_client -status |
缺 ssl_trusted_certificate 或 resolver |
| no ‘ssl_certificate’ is defined | openresty -T | grep -n |
证书不在该 server 块 |
| COMMON_NAME_INVALID | -ext subjectAltName |
SAN 未覆盖访问域名 |
排查顺序建议固定为:openresty -t 看语法 → openssl verify 看链 → s_client -status 看 Stapling → curl -vI 看实际握手。据 Mozilla SSL Configuration Generator,任何一条链不完整都会让 TLS 1.3 的握手在 Certificate 消息阶段就被客户端拒绝,与协议版本无关。
效果验证方法:如何确认 OpenResty 已加载新证书并启用 TLS 1.3?
问:改完配置后,第一条命令该看什么?
先做配置自检,确认 OpenResty 解析的是你以为的那份配置。openresty -t 只做语法校验、不加载生效,openresty -T(OpenResty 1.15.8+ 起可用)会把 include 展开后的完整配置输出到 stdout,这是排查“证书写在了没被引用的 server 块里”最快的手段:
# 语法校验:期望末行 test is successful,否则先修语法再谈验证
openresty -t
# nginx: configuration file /usr/local/openresty/nginx/conf/nginx.conf test is successful
# 打印生效配置并过滤关键指令
openresty -T | grep -E 'ssl_certificate|ssl_protocols|ssl_stapling'
# 期望看到:ssl_certificate .../ssl/fullchain.pem; (必须是 fullchain,不是 cert.pem)
# ssl_protocols TLSv1.2 TLSv1.3;
# ssl_stapling on;
据 Let’s Encrypt 文档,ssl_certificate 指向的应是包含站点证书与中间证书的 fullchain,缺失中间证书会让部分客户端报 unable to get local issuer certificate。若 grep 无输出,通常是 ssl_certificate 落在了 default server 之外,或 include 的 vhost 文件未被 include conf.d/*.conf; 命中。
问:怎么用 curl 一次性看到协议版本、HTTP 版本和证书校验结果?
# -v 输出握手细节,-I 只取响应头,避免拉全量 body
curl -vI https://example.com 2>&1 | grep -E 'SSL certificate verify|ALPN|HTTP/2|TLSv1'
# 期望:* SSL certificate verify ok.
# * ALPN: server accepted h2
# * using HTTP/2
# < HTTP/2 200
如果 ALPN 协商出的是 http/1.1,说明 HTTP/2 没启用:OpenResty 1.25.3.1 及以上用独立指令 http2 on;(推荐),1.25.3.1 以下只能用 listen 443 ssl http2;;两者混用会报 "http2" directive is duplicate。同时 ssl_protocols 默认值是 TLSv1 TLSv1.1 TLSv1.2(老版本),必须显式加上 TLSv1.3 才会协商到 TLS 1.3。
问:证书链到底装全了没有?
# -servername 必须带,否则拿到的是默认站点的证书(SNI 未命中)
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>&1
| grep -E 'Verify return code|Protocol|Cipher'
# 期望:Protocol : TLSv1.3
# Cipher : TLS_AES_256_GCM_SHA384 (或 TLS_CHACHA20_POLY1305_SHA256)
# Verify return code: 0 (ok)
若返回 Verify return code: 21 (unable to verify the first certificate),几乎可以断定 ssl_certificate 指向了只含叶子证书的 cert.pem。
问:OCSP Stapling 真的生效了吗?
# -status 请求服务端返回 stapled 的 OCSP 响应
echo | openssl s_client -connect example.com:443 -servername example.com -status 2>/dev/null
| grep -A1 'OCSP Response Status'
# 期望:OCSP Response Status: successful (0x0)
返回 unauthorized (0x6) 或整段缺失,先检查 ssl_trusted_certificate 是否指向含中间证书的 chain.pem,再确认 resolver 可用——OpenResty 需要它去回源 OCSP 响应,且首次请求时 stapling 常为 tryLater,需等一个 ssl_stapling_verify on 后的缓存周期(默认 60 分钟量级,由响应中的 nextUpdate 决定)。
问:怎么排除“以为 reload 了其实没生效”?
# 本地文件的有效期与 SAN,先确认不是旧证书
openssl x509 -in /usr/local/openresty/nginx/conf/ssl/fullchain.pem -noout -dates -ext subjectAltName
date -u # 与 notBefore / notAfter 对比,注意 UTC
# 端口与进程:worker 启动时间应晚于你执行 reload 的时间
ss -lntp | grep ':443'
ps -eo pid,lstart,cmd | grep nginx | grep -v grep
OpenResty 的 reload 是平滑重启:master 保持 PID 不变、worker 全部换新,所以“master 启动时间很旧”是正常的,要看 worker 的 lstart。最后在浏览器开发者工具 Security 面板复核,应显示“连接已加密”、有效证书与 TLS 1.3。
| 检查项 | 通过标准 | 典型失败输出 | 常见根因 |
|---|---|---|---|
openresty -t |
test is successful | PEM_read_bio_X509_AUX() failed |
证书路径错或文件权限不足 |
curl -vI |
HTTP/2 200 + TLSv1.3 | using HTTP/1.1 |
未写 http2 on; 或 listen ... http2 |
s_client -showcerts |
Verify return code: 0 | num=21 unable to verify the first certificate |
用了 cert.pem 而非 fullchain.pem |
-status |
successful (0x0) | unauthorized (0x6) |
chain.pem 缺失或 resolver 不可用 |
上线后的维护与回滚:续期、监控和变更窗口怎么安排?
问:证书 90 天就过期,续期怎么做到“零人工”?
据 Let’s Encrypt 文档,其证书有效期固定为 90 天,官方建议在剩余 30 天时完成续期;acme.sh 默认的 --cron 逻辑正是“剩余不足 30 天才真正申请”。所以你要做的不是每天续,而是把“续期成功之后如何安全地写入 OpenResty 并 reload”固化成 --install-cert 的钩子:
# acme.sh v3.x(默认 CA 为 Let's Encrypt,可用 --server 切换)
acme.sh --install-cert -d example.com
--key-file /usr/local/openresty/nginx/conf/ssl/privkey.pem
--fullchain-file /usr/local/openresty/nginx/conf/ssl/fullchain.pem
--reloadcmd "chmod 600 /usr/local/openresty/nginx/conf/ssl/privkey.pem
&& /usr/local/openresty/bin/openresty -t
&& /usr/local/openresty/bin/openresty -s reload"
# 说明:--reloadcmd 只在证书“确实发生续期”后执行;
# 把 chmod 600 和 openresty -t 串进钩子,可避免写入后权限变松、语法错就 reload
定时任务用 crontab -e 写非整点时间,错开全网集中续期的高峰(Let’s Encrypt 也建议随机化):
# 每天 03:17 触发一次 cron 检查(acme.sh 自身会判断是否到期)
17 3 * * * /root/.acme.sh/acme.sh --cron --home /root/.acme.sh > /dev/null
# 提示:acme.sh 安装时已用 --install-cronjob 写过一条,重复添加前先 crontab -l 确认
问:怎么第一时间发现“证书没换成功”?
最轻量的方式是从外部按真实 SNI 握手取到期日,脚本化后可直接接告警:
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null
| openssl x509 -noout -enddate
# 输出示例:notAfter=Jun 8 12:00:00 2026 GMT
规模化部署用 Prometheus blackbox_exporter:它的 SSL 探针默认暴露 probe_ssl_earliest_cert_expiry(证书链中最早到期者,含中间证书,Unix 时间戳),比只看叶证书更能提前暴露链问题:
# blackbox.yml 中 ssl 探针默认开启 tls_config 与证书过期采集
- alert: OpenRestyCertExpiringSoon
expr: probe_ssl_earliest_cert_expiry - time() < 30 * 86400
for: 1h
labels: { severity: warning }
| 监控手段 | 命令 / 指标 | 建议阈值 | 能发现什么 |
|---|---|---|---|
| 外部握手取到期日 | openssl s_client … -enddate |
剩余 < 30 天 | 续期钩子静默失败、文件没替换 |
| blackbox_exporter | probe_ssl_earliest_cert_expiry |
距 now < 30 天 | 中间证书缺失或更早过期 |
| 探活指标 | probe_success / probe_ssl_last_chain_expiry |
== 0 即告警 | 443 不通、SNI 不匹配、协议被关 |
| 配置复核 | SSL Labs 扫描(约 1–2 分钟) | 评级 ≥ A | 弱套件、TLS 1.0 残留、HSTS 缺失 |
问:换证书出问题,多久能回滚?
原则是“先备份、再 -t、后 reload”,据 OpenResty/nginx 文档,-s reload 是平滑加载,旧 worker 处理完存量连接才退出,实测 1–3 秒完成,不会掐断在途请求;但 openresty -t 返回非零时绝不能 reload,否则新配置不生效却掩盖了错误:
# 1) 变更前备份(目录 700,文件保持 600)
D=$(date +%F); mkdir -p /data/ssl/backup/$D && chmod 700 /data/ssl/backup/$D
cp -a /usr/local/openresty/nginx/conf/ssl/{fullchain.pem,privkey.pem,chain.pem} /data/ssl/backup/$D/
# 2) 只有语法检查通过才 reload
/usr/local/openresty/bin/openresty -t && /usr/local/openresty/bin/openresty -s reload
# 3) 5 分钟内核对:监听、HTTP 响应、证书序列号
ss -lntp | grep ':443'
curl -sI https://example.com | head -1
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null
| openssl x509 -noout -serial -dates
# 4) 异常回滚:恢复旧文件 → 再 -t → 再 reload
cp -a /data/ssl/backup/$D/*.pem /usr/local/openresty/nginx/conf/ssl/
&& /usr/local/openresty/bin/openresty -t && /usr/local/openresty/bin/openresty -s reload
回滚前先 tail -f /usr/local/openresty/nginx/logs/error.log,典型失败是 SSL_CTX_use_PrivateKey_file() failed (SSL: error:...key values mismatch)——私钥与 fullchain 不是同一对,说明复制时漏了文件。变更窗口建议固定在 02:00–05:00,此时回滚的影响面最小。
问:日常安全基线要盯哪几项?
私钥 600、所在目录 700,且绝不放进 Web 根目录或 Git 仓库。协议侧显式写死 ssl_protocols TLSv1.2 TLSv1.3;——nginx 的默认值仍是 TLSv1 TLSv1.1 TLSv1.2,不写就是留着 TLS 1.0/1.1。HSTS 按 RFC 6797 的忠告分两步上线,因为 max-age 会被浏览器缓存、无法即时撤销:
# 阶段一:先 300 秒,观察混合内容与子域覆盖
add_header Strict-Transport-Security "max-age=300" always;
# 阶段二:稳定运行后再升到一年(含子域需确认全部支持 HTTPS)
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
套件与协议参数可对照 Mozilla SSL Configuration Generator 的 intermediate 档;每次 openresty ssl证书安装 或升级 OpenSSL 后,用 SSL Labs 复扫一次,确认评级未从 A 掉到 B。若你还要复核 OCSP Stapling 是否仍生效,可用 openssl s_client -status 看是否返回 OCSP Response Status: successful。
通常不需要重启,执行 openresty -t 检查通过后 openresty -s reload 即可,master 进程 PID 不变,worker 在 1-3 秒内平滑替换。若用 systemd 管理,可执行 systemctl reload openresty;只有监听端口或 master 参数变更才考虑 restart。
可以。Let's Encrypt DV 证书有效期 90 天,用 acme.sh 或 certbot 的 webroot、DNS-01 方式签发,把 fullchain 与私钥指到 OpenResty 的 ssl_certificate 与 ssl_certificate_key 即可。续期后通过 –reloadcmd 'openresty -s reload' 自动加载,建议每 60 天续期一次。
填 fullchain.pem,也就是叶子证书加中间 CA;ssl_trusted_certificate 填 chain.pem,只放中间证书。只填单张域名证书时,curl、Java 旧 truststore 可能报 unable to get local issuer certificate,OCSP Stapling 也容易出警告。
常见原因是服务端只发了叶子证书,浏览器通过 AIA 自动补中间链,而 curl 和 Java 不会。把中间证书拼进 fullchain.pem 后用 openssl verify -untrusted chain.pem example.com.crt 验证;Java 8 旧 truststore 还可能不信任新根证书,需要升级 JDK 或导入根证书。
TLS 配置基本一致,区别在命令和默认路径:OpenResty 用 openresty -t、openresty -s reload,默认 prefix 是 /usr/local/openresty/nginx;Nginx 用 nginx -t、nginx -s reload。Lua 代码不参与 TLS 握手,证书链、私钥、协议参数仍按 Nginx 规则生效。
先检查 fullchain.pem 是否为空、是否含 CRLF、是否把私钥拼进证书。执行 file fullchain.pem、head -1 fullchain.pem、openssl x509 -in fullchain.pem -noout -subject;若不能解析,重新从 CA 下载完整 PEM 并确认首行是 BEGIN CERTIFICATE。
Caddy 内置 ACME 自动签发与续期,开箱即用,适合简单站点;OpenResty 适合已有 Lua 网关、WAF、灰度路由或复杂 upstream 的场景,但需要自己用 acme.sh 或 certbot 管证书,并配 openresty -s reload。两者都能开 TLS 1.3,选择取决于现有技术栈与运维自动化程度。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。