跳到主要内容
SSL 证书付费服务

小程序与网站 HTTPS 证书配置实战:Nginx SSL 部署、证书链修复与报错排查指南

小程序与网站 HTTPS 证书配置实战:Nginx SSL 部署、证书链修复与报错排查指南 — 小程序与网站 HTTPS 证书配置实战:Nginx SSL 部署、证书链修复与报错排查指南

一、问题背景与根因:小程序和网站为什么绕不开 HTTPS 证书配置

微信小程序从基础库 1.6.0 起,wx.request 与 wx.connectSocket 只允许 https:// 和 wss:// 请求,且服务端必须支持 TLS 1.2 及以上。开发阶段在微信开发者工具里勾选了「不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书」时一切正常,一上真机就抛 request:fail ssl hand shake error——这是线上最高频的一类故障。

根因通常只有四类,九成集中在第一类:

1)证书链不完整。Nginx 的 ssl_certificate 只配了域名证书(叶子证书),没有把中间 CA 证书拼进去。桌面浏览器会自行补链,部分 Android 版本也会,但 iOS 与小程序真机严格校验,直接握手失败。2)TLS 协议版本过低。仍配置 ssl_protocols TLSv1 TLSv1.1;,协商不到 TLS 1.2。3)域名不匹配。证书 SAN 里没有 api.example.com,或误以为通配符 *.example.com 能覆盖 a.b.example.com(通配符只匹配一级)。4)证书过期。自 2020 年 9 月 1 日起,公有信任 CA 签发的 SSL/TLS 证书最长有效期被限制为 398 天;Let’s Encrypt 免费证书有效期为 90 天。忘记续期,就会在某天凌晨集体失效。

动手前先跑一条命令定位故障层级,看服务器到底发了什么:

openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates

如果输出中 issuer 是中间 CA 名称、subject 是你的域名,且整段只出现一个 -----BEGIN CERTIFICATE-----,说明服务器只发了叶子证书,证书链缺失。再用 -tls1_2 单独测试一次,可确认协议支持情况:能连通说明协议没问题,连不上就是 ssl_protocols 或加密套件配置有误。

二、证书选型与 CSR 申请:单域名、通配符与 398 天有效期规则

小程序后端场景对证书等级要求不高,DV(域名验证型)证书足够,微信不校验 OV/EV。真正需要判断的是覆盖范围:

  • 单域名证书:只保护 api.example.com,一个证书对应一个 FQDN。
  • 通配符证书:*.example.com 覆盖 api.example.com、www.example.com 等一级子域,不覆盖裸域 example.com,也不覆盖 a.b.example.com。裸域必须在 SAN 里额外添加。
  • 多域名(SAN/UCC)证书:一张证书挂多个不同主域,适合微服务共用入口。

生成 CSR 与私钥(RSA 2048 兼容性最好,ECDSA P-256 握手更快、证书体积更小):

# RSA 2048,同时写入 SAN,避免浏览器报域名不匹配
openssl req -new -newkey rsa:2048 -nodes 
  -keyout example.com.key -out example.com.csr 
  -subj "/C=CN/O=Example/CN=api.example.com" 
  -addext "subjectAltName=DNS:api.example.com,DNS:example.com,DNS:www.example.com"

# ECDSA P-256
openssl ecparam -genkey -name prime256v1 -out example.com.ec.key
openssl req -new -key example.com.ec.key -out example.com.ec.csr -subj "/CN=api.example.com"

申请时 CA 会要求验证域名归属:DNS 验证需添加 TXT 记录,文件验证需在网站根目录放置指定文件。若走免费路线,用 acme.sh 或 certbot 申请 Let’s Encrypt 证书,90 天有效期配合自动续期即可长期使用。注意:市面上所谓「2 年证书」在 398 天规则下已不可能由单张证书实现,实质是多年期订阅 + 多张证书自动轮换,采购时要确认服务商是否提供自动重签与自动部署,否则第二年仍需人工介入。

三、Nginx SSL 配置完整实操:从模块确认到 reload

第一步确认 Nginx 是否编译了 SSL 模块,没有输出就必须先解决依赖:

nginx -V 2>&1 | tr ' ' 'n' | grep -E 'http_ssl_module|http_v2_module'

Debian/Ubuntu 可直接 apt install nginx-full;自编译需加 --with-http_ssl_module --with-http_v2_module --with-http_stub_status_module 重新编译。

第二步建立专用目录并收紧权限,私钥绝不能全局可读:

mkdir -p /etc/nginx/ssl && chmod 700 /etc/nginx/ssl
# 上传 example.com.key / example.com.crt / intermediate.crt 后
cat example.com.crt intermediate.crt > /etc/nginx/ssl/fullchain.crt
cp intermediate.crt /etc/nginx/ssl/chain.crt
chmod 600 /etc/nginx/ssl/example.com.key
chown root:root /etc/nginx/ssl/*
openssl x509 -in /etc/nginx/ssl/fullchain.crt -noout -dates -subject

第三步校验私钥与证书是否配对,不匹配时 reload 会直接失败:

openssl x509 -noout -modulus -in /etc/nginx/ssl/fullchain.crt | openssl md5
openssl rsa  -noout -modulus -in /etc/nginx/ssl/example.com.key | openssl md5

两行 MD5 必须一致。第四步放行端口,云服务器要同时改安全组和本机防火墙:

firewall-cmd --permanent --add-service=https && firewall-cmd --reload
# 或 ufw allow 443/tcp

第五步灰度生效,避免直接 restart 打断长连接:

nginx -t && systemctl reload nginx && systemctl status nginx --no-pager

小程序的 request 合法域名不支持端口号、不支持 IP、必须 HTTPS,配置完成后记得回到微信公众平台「开发管理 → 服务器域名」同步填写。

四、Nginx 配置示例:HTTP 强制跳转 + TLS 1.2/1.3 + HSTS

下面是一份可直接落地的 /etc/nginx/conf.d/api.conf,包含 80 跳 443、TLS 1.2/1.3、会话复用、OCSP Stapling 与 HSTS:

server {
    listen 80;
    server_name api.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    http2 on;                      # nginx < 1.25.1 请改为 listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate     /etc/nginx/ssl/fullchain.crt;   # 叶子+中间证书
    ssl_certificate_key /etc/nginx/ssl/example.com.key;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
    ssl_prefer_server_ciphers off;

    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    ssl_session_tickets off;

    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/nginx/ssl/chain.crt;
    resolver 223.5.5.5 119.29.29.29 valid=300s;

    add_header Strict-Transport-Security "max-age=31536000" always;
    add_header X-Content-Type-Options nosniff always;

    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

几个容易踩坑的参数:ssl_prefer_server_ciphers 在 TLS 1.3 下已无效,保持 off 让客户端选择更快套件;ssl_stapling 必须配合 ssl_trusted_certificate 指向中间证书(不是 fullchain)才能生效,且需要 resolver 能解析 CA 的 OCSP 地址;HSTS 的 max-age 一旦下发,浏览器在有效期内拒绝走 HTTP,首次上线建议先用 max-age=300 观察一天再拉长到一年。小程序端只要求 TLS 1.2+,不要为了兼容老旧 Android 4.x 而放开 TLS 1.0,微信本身已不支持。

五、证书链合并与校验:fullchain 到底怎么拼

SSL 证书是三级结构:根证书(Root CA)→ 中间证书(Intermediate CA)→ 服务器证书(叶子)。根证书内置在操作系统与浏览器信任库中,服务器只需发送叶子证书 + 中间证书,顺序不能颠倒,也不要把根证书打包进去(会增大握手包,个别客户端还会告警)。

# 正确顺序:叶子在前,中间在后
cat example.com.crt intermediate.crt > fullchain.crt

# 本地验证链是否完整
openssl verify -untrusted intermediate.crt example.com.crt
# 期望输出:example.com.crt: OK

# 拆分 fullchain 检查每一段的身份
awk 'BEGIN{n=0} /BEGIN CERT/{n++} {print > "cert"n".pem"}' fullchain.crt
openssl x509 -in cert1.pem -noout -subject   # 应为你的域名
openssl x509 -in cert2.pem -noout -subject   # 应为中间 CA

部署后必须从外部验证服务器实际发送的链,而不是本地文件:

openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null 
  | grep -E '^ *[is]:|Verify return code'

健康输出应包含两段 i:(颁发者)与 s:(主体)记录,且末尾为 Verify return code: 0 (ok)。若出现 verify error:num=21:unable to verify the first certificate 或 Verify return code: 21,就是典型的中间证书缺失。另一个常见坑:从 CA 后台下载的是 .crt 与 .ca-bundle 两个文件,很多人只上传了前者;也有服务商把中间证书藏在压缩包的 chain/ 目录里,务必核对。若使用 ECDSA 证书,中间证书也要用对应的 ECDSA 链,RSA 与 ECDSA 双证书可通过 ssl_certificate 配置两次实现双栈。

六、对比表格:证书类型、部署方式与配置项取舍

先看证书与配置服务的选型对照(价格为常见服务参考价,证书本身价格随 CA 与渠道浮动):

方案 覆盖范围 有效期 参考价格 适用场景
已有证书,仅配置服务 按原证书 按原证书 100 元 证书已购,缺 Nginx 部署与调优
单域名证书 + 配置 1 个 FQDN ≤398 天 200 元 单一 API 域名
泛域名通配符证书 + 配置 *.example.com 一级子域 ≤398 天 600 元 多子域、多环境共用
单域名 2 年订阅 + 配置 1 个 FQDN 2 张证书轮换 500 元 希望减少续期操作
泛域名 2 年订阅 + 配置 *.example.com 2 张证书轮换 1000 元 长期多子域业务

部署方式对比:

方式 续期 运维成本 风险点
手动上传证书 人工,398 天/90 天一次 低但易遗忘 过期事故、文件拼错
certbot(webroot/dns 插件) 自动,90 天续期 中 需配 hook 自动 reload
acme.sh + DNS API 全自动,含通配符 低 DNS API 密钥需妥善保管

关键配置项取舍:TLSv1.2 + TLSv1.3 是当前唯一推荐组合;RSA 2048 兼容性最好,ECDSA P-256 在移动弱网下握手更快,二者可共存;HSTS 建议先短 max-age 灰度;ssl_session_tickets off 更安全但会略微增加握手开销,会话缓存已能覆盖大部分场景。

七、常见错误排查:6 个真实报错与修复命令

报错 1:nginx: [emerg] PEM_read_bio_X509_AUX("/etc/nginx/ssl/fullchain.crt") failed (SSL: error:0480006C:PEM routines::no start line:Expecting: TRUSTED CERTIFICATE)。原因是文件为空、被上传工具截断,或下载的是 DER 格式。执行 file fullchain.crt,若显示 data 而非 ASCII text,用 openssl x509 -inform DER -in fullchain.crt -out fullchain.pem 转换。

报错 2:nginx: [emerg] SSL_CTX_use_PrivateKey_file("...key") failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)。证书与私钥不配对。用第三节的 modulus | md5 对比两行输出;ECDSA 证书改用 openssl ec -in key -pubout | md5 与 openssl x509 -in crt -pubkey -noout | md5 对比。不一致只能重新签发,无法修复。

报错 3:curl: (60) SSL certificate problem: unable to get local issuer certificate。客户端拿不到中间证书,即证书链不完整,按第五节重新合并 fullchain 并 reload。

报错 4:小程序真机 request:fail ssl hand shake error。先 openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2,握手失败说明 ssl_protocols 缺 TLSv1.2 或 ssl_ciphers 只保留了 TLS 1.3 套件;握手成功但仍报错,多为证书链或域名不匹配。

报错 5:curl: (60) SSL certificate problem: certificate has expired。证书已过期但 Nginx 仍加载旧文件——续期脚本只换了文件没 reload。执行 systemctl reload nginx,并把 --deploy-hook "systemctl reload nginx" 写进续期任务。

报错 6:浏览器 NET::ERR_CERT_COMMON_NAME_INVALID 或小程序 request:fail url not in domain list。前者是 SAN 不含当前域名(检查 openssl x509 -in fullchain.crt -noout -text | grep -A1 "Subject Alternative Name"),后者是微信公众平台未登记该域名,或域名带了端口/是 IP。

八、效果验证:命令行检测、在线评分与自动续期巡检

先用 curl 做一次端到端验证,ssl_verify_result 为 0 才代表证书校验通过:

curl -sS -o /dev/null -w "http_code=%{http_code} verify=%{ssl_verify_result} handshake=%{time_appconnect}sn" https://api.example.com/
# 期望:http_code=200 verify=0 handshake=0.0xxxs

再确认协议与套件:

echo | openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 2>/dev/null 
  | grep -E 'Protocol|Cipher|Verify return code'
# 期望:Protocol: TLSv1.2 / Cipher: ECDHE-RSA-AES128-GCM-SHA256 / Verify return code: 0 (ok)

在线评分可调用 SSL Labs API,目标 A 级及以上:

curl -s "https://api.ssllabs.com/api/v3/analyze?host=api.example.com&publish=off&all=done" 
  | jq -r '.endpoints[0].grade, .endpoints[0].details.protocols[].name'

最后加一条过期巡检脚本,挂到 cron 每日执行,把「证书到期」从事故变成提醒:

#!/usr/bin/env bash
DOMAIN=api.example.com
END=$(echo | openssl s_client -connect $DOMAIN:443 -servername $DOMAIN 2>/dev/null 
      | openssl x509 -noout -enddate | cut -d= -f2)
LEFT=$(( ( $(date -d "$END" +%s) - $(date +%s) ) / 86400 ))
[ "$LEFT" -lt 15 ] && echo "$DOMAIN 证书剩余 ${LEFT} 天" | mail -s "SSL 到期告警" ops@example.com

小程序侧验证:关闭开发者工具「不校验合法域名」开关,用真机预览调用一次接口;确认公众平台「服务器域名」中的 request 域名与证书 SAN 完全一致,且不带端口。iOS 与 Android 各测一台,两端都通过才算真正完成 HTTPS 配置。

常见问题

证书只配了域名证书,为什么电脑浏览器正常、小程序真机却握手失败?

桌面浏览器内置了中间 CA 证书,能自行补全证书链;iOS 与小程序真机不做这种补全,只认服务器发来的完整链。把叶子证书与中间证书按「叶子在前、中间在后」合并成 fullchain 后写入 ssl_certificate,再用 openssl s_client -showcerts 确认返回 Verify return code: 0 (ok) 即可解决。

现在还能买到 2 年有效期的 SSL 证书吗?

不能。自 2020 年 9 月 1 日起,公有信任 CA 签发的 SSL/TLS 证书最长有效期被限制为 398 天,Let’s Encrypt 为 90 天。市面上的「2 年证书」实质是多年期订阅,服务商会在首张证书到期前自动重签并重新部署。采购时务必确认是否包含自动重签与自动 reload,否则第二年仍需人工操作。

通配符证书 *.example.com 能覆盖 api.example.com 和 example.com 吗?

能覆盖 api.example.com,但不能覆盖裸域 example.com,也不能覆盖二级子域 a.b.example.com。解决办法是签发时在 SAN 中同时写入 *.example.com 与 example.com,二级子域则单独加 SAN 或使用多域名证书。

配置完成后 Nginx 启动报 key values mismatch 是什么原因?

证书与私钥不配对,常见于重新签发证书后忘记替换私钥、或从多个压缩包里混拿了文件。用 openssl x509 -noout -modulus -in fullchain.crt | openssl md5 与 openssl rsa -noout -modulus -in example.com.key | openssl md5 对比,两行 MD5 必须完全一致;ECDSA 证书改用 openssl ec -pubout 与 openssl x509 -pubkey 对比。不一致只能重新签发,无法通过配置修复。

HSTS 开了之后想回退到 HTTP,为什么浏览器还是强制跳 HTTPS?

HSTS 由浏览器本地缓存生效,服务端改配置无法立即撤销。上线初期应先用 add_header Strict-Transport-Security "max-age=300" always; 短周期灰度,确认无误后再拉长到 31536000 秒;已下发长周期的域名只能等缓存过期,或引导用户清理浏览器 HSTS 列表。

Let’s Encrypt 证书续期成功,为什么线上仍然是旧证书?

续期只更新了磁盘文件,Nginx 进程仍持有旧证书。certbot 需加 --deploy-hook "systemctl reload nginx",acme.sh 需加 --reloadcmd "systemctl reload nginx"。另外若使用 ssl_stapling,reload 后建议再执行一次 openssl s_client -status 确认 OCSP 响应正常。

内容审核

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