跳到主要内容
安装配置教程

OpenResty SSL 证书安装实操:从证书链、OCSP Stapling 到 TLS 1.3 验证

openresty ssl证书安装 — 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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。