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

小程序服务器端 HTTPS 配置实战:SSL 证书、TLS 1.2 与微信/支付宝联调

小程序服务器端 HTTPS 配置实战:SSL 证书、TLS 1.2 与微信/支付宝联调 — 小程序服务器端 HTTPS 配置实战:SSL 证书、TLS 1.2 与微信/支付宝联调

问题背景与根因:小程序为什么强制 HTTPS 与 TLS 1.2

微信小程序和支付宝小程序在调用第三方服务器时,都要求使用 HTTPS。微信公众平台的 request 合法域名只能填写 https://api.example.com 这种形式,不能使用 localhost、127.0.0.1、公网 IP,也不能带端口,例如 https://api.example.com:8123 会被拒绝;国内服务器域名还必须完成工信部备案。服务端不仅要安装 SSL 证书,还必须支持 TLS 1.2 及以上,同时禁用 SSLv2、SSLv3、TLS 1.0、TLS 1.1。很多故障不是证书没装,而是证书链不完整、域名 SAN 不匹配、SNI 未返回正确证书、服务器时间偏差,或 Nginx 仍允许旧协议。

原文中“提供有效期为一年的免费 SSL 证书”已经过时:Let’s Encrypt 证书有效期是 90 天,依赖 certbot 自动续期;商业 DV 证书单次最长有效期也不超过 398 天,不存在随意签发一年且长期不续期的做法。CSR 是证书签发请求,Let’s Encrypt 由 ACME 客户端自动生成,商业证书才常需要手动生成 CSR。先用命令确认现状:

openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 < /dev/null
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_1 < /dev/null
curl -I https://api.example.com/health

第一条应成功并显示证书链,第二条应握手失败,第三条应返回 HTTP 200 或业务状态码。若第二条仍成功,说明 TLS 1.0/1.1 未禁用,小程序真机可能报 request:fail ssl hand shake error。

准备与证书申请:域名备案、CSR、Let’s Encrypt 90 天证书

第一步,把 api.example.com 的 A 记录解析到服务器公网 IP,完成备案,安全组放行 80 和 443。小程序后台的 request 合法域名只填 https://api.example.com,不要带路径和端口。第二步,安装 ACME 客户端。Ubuntu/Debian 执行 apt update && apt install -y certbot python3-certbot-nginx;CentOS/RHEL 执行 dnf install -y certbot python3-certbot-nginx。第三步,用 Nginx 插件申请并自动改配置:

certbot --nginx -d api.example.com --agree-tos -m ops@example.com --redirect --keep-until-expiring
certbot renew --dry-run
systemctl list-timers | grep certbot

证书会落在 /etc/letsencrypt/live/api.example.com/ 下,Nginx 必须使用 fullchain.pem 和 privkey.pem,fullchain.pem 已包含站点证书和中间证书。Let’s Encrypt 有效期 90 天,certbot 的 systemd timer 会自动续期,dry-run 成功才说明续期链路可用。若购买商业 DV 证书,才需要生成 CSR:

openssl req -new -newkey rsa:2048 -nodes -keyout api.key -out api.csr -subj '/CN=api.example.com'

把 api.csr 交给 CA,签发后得到 crt 或 pem,再与中间证书合并为 fullchain。商业证书最长有效期不超过 398 天,到期必须续签;通配符证书可覆盖 *.example.com,但仍需注意 SAN 和部署路径。不要使用自签名证书,小程序运行环境不会信任。

Nginx 实操:启用 TLS 1.2/1.3 并禁用 SSL 与旧 TLS

在 Nginx 中把 80 端口 301 到 443,443 只启用 TLSv1.2 和 TLSv1.3,不写 SSLv3、TLSv1、TLSv1.1。下面配置可直接替换域名后使用,fullchain.pem 不能写成 cert.pem,否则部分 Android 机和小程序会报证书链错误:

server {
    listen 80;
    server_name api.example.com;
    return 301 https://$host$request_uri;
}
server {
    listen 443 ssl http2;
    server_name api.example.com;
    ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
    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;
    add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/letsencrypt/live/api.example.com/chain.pem;
    resolver 223.5.5.5 119.29.29.29 valid=300s;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
}

执行 nginx -t && systemctl reload nginx。若后端是 HTTP 服务,proxy_pass 写 http://127.0.0.1:8080 没问题,但对外必须是 443 的 HTTPS。HSTS 首次上线可先用较短 max-age,确认全站 HTTPS 后再加 includeSubDomains。OCSP Stapling 需要 resolver 可用,否则可先关闭 ssl_stapling。TLS 1.3 可保留,但不要删除 TLS 1.2,因为部分旧基础库仍以 TLS 1.2 为主。

Apache 与 IIS 配置要点:保持同一套 TLS 策略

Apache 先启用 ssl、headers、rewrite 模块,再配置 80 跳转和 443 虚拟主机。关键是指令 SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1,只保留 TLSv1.2 和 TLSv1.3;证书文件用 fullchain,不要只给站点证书。示例:

<VirtualHost *:80>
    ServerName api.example.com
    Redirect permanent / https://api.example.com/
</VirtualHost>
<VirtualHost *:443>
    SSLEngine on
    ServerName api.example.com
    SSLCertificateFile /etc/letsencrypt/live/api.example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/api.example.com/privkey.pem
    SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
    SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
    SSLHonorCipherOrder off
    Header always set Strict-Transport-Security 'max-age=31536000'
</VirtualHost>

执行 apachectl configtest && systemctl reload apache2。Windows IIS 则导入包含私钥的 PFX,在站点绑定中新增 https、端口 443,勾选 SNI,主机名填 api.example.com。随后用 IISCrypto 勾选 TLS 1.2,取消 SSL 3.0、TLS 1.0、TLS 1.1,重启服务器生效。Let’s Encrypt 可用 win-acme 申请:wacs.exe –target iis –host api.example.com –installation iis –emailaddress ops@example.com。IIS 常见问题是证书绑定未勾选 SNI,导致同一 IP 多域名返回错误证书;Apache 常见问题是未加载 headers 模块导致 HSTS 不生效。

证书类型、有效期与协议对比表

选择证书时不要只看价格,要看有效期、自动续期能力、域名覆盖和证书链。下表把原文中过时的“一年免费证书”修正为当前常见实践:

项目 Let’s Encrypt DV 商业 DV 通配符证书 说明
有效期 90 天 不超过 398 天 不超过 398 天 原文“一年免费”已过时
续期 certbot 自动 手动或 ACME 手动或 ACME 必须监控到期时间
适用 API、测试、中小站点 需要商业 SLA 多子域 小程序只看是否受信任
证书链 fullchain.pem fullchain 或中间证书 fullchain 缺中间证书会握手失败
协议版本 建议状态 小程序影响
SSLv2 / SSLv3 禁用 不满足微信/支付宝要求
TLS 1.0 / TLS 1.1 禁用 易报 ssl hand shake error
TLS 1.2 必须启用 当前兼容性基线
TLS 1.3 可选启用 提升性能,保留 1.2 兜底

如果域名很多,通配符证书能减少部署次数,但不要把私钥散落在多台机器;证书有效期无论 90 天还是 398 天,都必须设置到期告警和续期演练。

常见错误排查:从真实报错到根因

微信开发者工具报 request:fail 无效的域名,请检查域名是否已配置,通常不是 TLS 问题,而是微信公众平台后台未把 https://api.example.com 加入 request 合法域名,或填了 IP、localhost、带端口地址。真机报 request:fail ssl hand shake error,先用 openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 < /dev/null 检查是否握手成功;若失败,看 ssl_protocols 是否包含 TLSv1.2、证书是否过期、系统时间是否准确、fullchain 是否完整。

浏览器或 curl 报 net::ERR_CERT_AUTHORITY_INVALID、unable to get local issuer certificate,根因是缺中间证书,Nginx 改用 fullchain.pem,Apache 使用 fullchain 或配置 SSLCertificateChainFile。报 ERR_CERT_COMMON_NAME_INVALID 是证书 SAN 不含当前域名,重新用 -d api.example.com 签发。报 ERR_SSL_PROTOCOL_ERROR 或 wrong version number,常见于 443 端口被纯 HTTP 服务占用、Nginx 未写 listen 443 ssl、或反向代理到了错误端口。报 504 Gateway Timeout 说明 TLS 已通,问题在后端 8080 不可达。SSL Labs 评分低时,检查是否启用 HSTS、OCSP Stapling、是否禁用 TLS 1.0/1.1、RSA 是否至少 2048 位。

效果验证:openssl、curl、SSL Labs 与小程序真机

先验证证书主题、签发者和有效期:

openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 < /dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_1 < /dev/null
curl -I https://api.example.com/health
curl -I http://api.example.com/health

第一条应输出 CN 和 SAN 包含 api.example.com,issuer 为受信任 CA,日期未过期;第二条应失败;第三条返回 200;第四条应返回 301 到 https。再用 nmap –script ssl-enum-ciphers -p 443 api.example.com 或 sslscan api.example.com:443 检查协议和套件,确认只出现 TLS 1.2/1.3。打开 Qualys SSL Server Test 输入域名,目标达到 A 或 A+,重点看 Certificate 链完整、Protocols 无 SSLv3/TLS1.0/1.1。最后在微信和支付宝小程序后台保存合法域名,开发者工具关闭“不校验合法域名”后重新编译,并用真机 4G 网络请求一次;若真机仍失败,抓包看 SNI、证书链和后端状态码,而不是只盯 SSL Labs 评分。

常见问题

小程序必须支持 TLS 1.2 吗?

是。微信小程序要求 HTTPS,并支持 TLS 1.2 及以上,同时应禁用 SSLv2、SSLv3、TLS 1.0、TLS 1.1;支付宝小程序同样要求 HTTPS 和受信任证书。配置时保留 TLSv1.2,可选启用 TLSv1.3。

Let’s Encrypt 证书 90 天会不会频繁过期?

不会,只要 certbot timer 正常。用 certbot renew –dry-run 验证续期,用 systemctl list-timers | grep certbot 检查定时器。商业 DV 证书最长有效期也不超过 398 天,不是原文说的一年无限续期。

小程序合法域名可以带端口吗?

不可以。合法域名只写 https://api.example.com,默认使用 443 端口;不能写 https://api.example.com:8123,也不能用 IP、localhost、127.0.0.1。国内服务器还需完成备案。

SSL Labs 评 A 但小程序仍请求失败怎么办?

先查微信/支付宝后台合法域名是否保存并重新编译;再查证书 SAN 是否包含当前域名、fullchain 是否完整、SNI 是否返回正确证书、后端是否 504、手机系统时间是否准确。SSL Labs 通过不代表小程序后台配置正确。

需要购买付费证书吗?

Let’s Encrypt DV 已能满足小程序 HTTPS 和 TLS 1.2 要求。商业 DV 的优势是 SLA、保障和审计支持;通配符证书适合多子域。无论哪种,都要部署 fullchain 并设置到期告警。

商业证书的 CSR 怎么生成?

可执行 openssl req -new -newkey rsa:2048 -nodes -keyout api.key -out api.csr -subj ‘/CN=api.example.com’,把 api.csr 交给 CA。Let’s Encrypt 不需要手动 CSR,certbot 会自动完成密钥和签发。

内容审核

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