跳到主要内容
HTTPS小程序证书

TLS/SSL 证书部署、检测与 HTTPS 优化实战(小程序服务端 A 级配置指南)

TLS/SSL 证书部署、检测与 HTTPS 优化实战(小程序服务端 A 级配置指南) — TLS/SSL 证书部署、检测与 HTTPS 优化实战(小程序服务端 A 级配置指南)

一、问题背景与根因:小程序服务端为什么必须走 HTTPS + TLS 1.2

微信小程序的所有网络请求(wx.request、wx.uploadFile、wx.downloadFile、wx.connectSocket)在真机环境下只允许 https:// 与 wss://。原文提到的三条硬性要求今天依然成立,但细节必须更新:域名需已完成 ICP 备案,不能是 IP、localhost、127.0.0.1;请求地址不能携带非 443 端口,https://www.example.com:8443 会被直接拒绝;服务端必须支持 TLS 1.2 及以上,且禁用 SSLv2/SSLv3,TLS 1.0/1.1 已于 2021 年被 RFC 8996 正式弃用,主流浏览器与 CA 早已不再支持。

根因在于:小程序请求由微信客户端的原生网络栈发起,证书链校验走系统信任库并叠加微信自有策略,没有“用户点击继续访问”的降级通道。证书链缺中间证书、自签名、域名不匹配、SNI 未配置、TLS 版本过低,都会直接抛错。

真机上报错通常是这两条:

errMsg: "request:fail ssl hand shake error"
errMsg: "request:fail url not in domain list"

先用一条命令看清服务端真实握手结果:

openssl s_client -connect www.example.com:443 -servername www.example.com -brief

输出中应看到 Protocol version: TLSv1.3(或 TLSv1.2)、Verification: OK。再验证 TLS 1.1 是否确实关闭(预期报错,返回 SSL alert number 70 或 no protocols available):

openssl s_client -connect www.example.com:443 -servername www.example.com -tls1_1

另外两个必须纠正的过时事实:其一,自 2020-09-01 起公有信任 TLS 证书最长有效期已缩短为 398 天,Let’s Encrypt 免费证书为 90 天;CA/B Forum 的 SC-081 已确定 2026-03 降至 200 天、2027-03 降至 100 天、2029-03 降至 47 天,所以“买一年证书”的说法已不成立,续期必须自动化。其二,原文所说的 Symantec DV 免费证书早已失效——Symantec 的 CA 业务 2017 年已出售给 DigiCert,Symantec 品牌证书停止签发,当前主流免费 DV 是 Let’s Encrypt、ZeroSSL、Google Trust Services、Buypass。

二、证书选型与申请:CSR 生成、域名验证与 ACME 自动签发

选型原则:小程序服务端只需要 DV 证书即可满足微信校验,OV/EV 只在需要组织信息展示、合规审计或商业 SLA 时才有必要。通配符证书适合泛域名 API,多域名(SAN)证书适合一台服务器承载多个业务域名。

若走商业 CA 流程,先本地生成私钥与 CSR(OpenSSL 1.1.1+ 支持 -addext):

openssl genrsa -out example.com.key 2048
openssl req -new -key example.com.key -out example.com.csr 
  -subj '/CN=example.com' 
  -addext 'subjectAltName=DNS:example.com,DNS:www.example.com,DNS:api.example.com'

提交前务必核对 SAN 是否完整,漏掉 www 会导致小程序在部分入口报证书域名不匹配:

openssl req -in example.com.csr -noout -text | grep -A1 'Subject Alternative Name'

预期输出:DNS:example.com, DNS:www.example.com, DNS:api.example.com。私钥权限立刻收紧:chmod 600 example.com.key && chown root:root example.com.key。

更推荐 Let’s Encrypt 全自动签发,Nginx 环境一条命令搞定(HTTP-01 验证):

apt update && apt install -y certbot python3-certbot-nginx
certbot certonly --nginx -d example.com -d www.example.com 
  --agree-tos -m ops@example.com --no-eff-email --keep-until-expiring

产物目录 /etc/letsencrypt/live/example.com/,其中 fullchain.pem 是“站点证书 + 中间证书”,必须使用它,只用 cert.pem 会造成链不完整、安卓端与小程序握手失败。通配符证书需走 DNS-01:

certbot certonly --manual --preferred-challenges dns -d '*.example.com' -d example.com

签发后立即演练续期,确认 80 端口可达、防火墙未拦截:certbot renew --dry-run。certbot 安装时会注册 systemd timer,一天执行两次,用 systemctl list-timers | grep certbot 可确认。

三、Nginx / Apache / IIS 配置示例(可直接执行)

Nginx 完整可用配置(http2 on 需 1.25.1+,旧版本改写为 listen 443 ssl http2;):

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

server {
    listen 443 ssl;
    http2 on;
    server_name example.com www.example.com;

    ssl_certificate         /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key     /etc/letsencrypt/live/example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.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;

    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 223.5.5.5 1.1.1.1 valid=300s;
    resolver_timeout 5s;

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

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

改完先语法检查再平滑重载,切勿直接 restart:nginx -t && nginx -s reload。

Apache 关键指令(写入 ssl.conf 或站点配置):

SSLEngine on
SSLCertificateFile    /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
SSLProtocol -all +TLSv1.2 +TLSv1.3
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
SSLHonorCipherOrder off
SSLSessionTickets off

IIS 需先在“服务器证书”中导入含完整链的 PFX,再绑定 443。若服务器较老,需在注册表显式启用 TLS 1.2 并关闭 SSL 3.0,改完执行 iisreset:

reg add "HKLMSYSTEMCurrentControlSetControlSecurityProvidersSCHANNELProtocolsTLS 1.2Server" /v Enabled /t REG_DWORD /d 1 /f
reg add "HKLMSYSTEMCurrentControlSetControlSecurityProvidersSCHANNELProtocolsSSL 3.0Server" /v Enabled /t REG_DWORD /d 0 /f

四、全站 HTTPS 迁移:混合内容排查与资源替换

证书装上只是第一步,页面里残留的 http:// 资源会让浏览器判定“混合内容”,小程序端表现为接口能通但图片、附件加载失败。先在服务器上全量扫描:

grep -rIn 'http://' /var/www/html 
  --include='*.html' --include='*.js' --include='*.css' 
  | grep -v 'http://www.w3.org' | head -50

排除 W3C 命名空间等合法用途后,逐条替换。数据库驱动的站点(如 WordPress)直接执行 SQL 批量替换,注意同时处理序列化字段:

UPDATE wp_posts SET post_content = REPLACE(post_content, 'http://example.com', 'https://example.com');
UPDATE wp_options SET option_value = REPLACE(option_value, 'http://example.com', 'https://example.com');

再加一道兜底策略,让浏览器自动把 http 子资源升级为 https:

add_header Content-Security-Policy "upgrade-insecure-requests" always;

第三方组件要单独确认。原文提到的“百度分享不支持 HTTPS”已是过时结论——该产品早已停止维护,正确做法是改用支持 HTTPS 的原生分享或 share.js 类方案;同理,老版本统计代码、字体 CDN、地图 JS 都要换成 https 版本。

HSTS 建议最后再上,且采用渐进式:先 max-age=300 观察一天,确认全站无 http 依赖后再提升到 31536000。一旦设置 includeSubDomains 与 preload,回退成本极高——浏览器会强制 HTTPS 且无法点击绕过。反向代理场景还要确认 X-Forwarded-Proto $scheme 已透传,否则后端生成绝对 URL 时仍会输出 http,触发 301 重定向死循环。

五、证书方案与协议版本对比表

下表按当前(公有信任证书 398 天上限)规则整理,用于选型决策:

方案 代表 CA 有效期 价格 续期方式 适用场景
免费 DV Let’s Encrypt 90 天 免费 ACME 全自动 小程序后端、API、个人站
免费 DV ZeroSSL / Google Trust Services 90 天 免费 ACME 全自动 同上,作为备用 CA
商业 DV DigiCert / GlobalSign / Sectigo 最长 398 天 数百至数千元/年 手动或 API 需发票、SLA、保险赔付
OV / EV DigiCert / GlobalSign 最长 398 天 数千元/年 手动 金融、政企、需展示组织信息

协议版本与评分关系(Qualys SSL Labs 实测口径):

协议 规范状态 建议 开启后的评分影响
SSLv2 / SSLv3 RFC 6176 / RFC 7568 弃用 必须禁用 直接 C 或 F
TLS 1.0 / TLS 1.1 RFC 8996 弃用 禁用 最高只能到 B
TLS 1.2 可用 必须开启 无负面影响
TLS 1.3 推荐 开启 A+ 加分项

结论很直接:小程序场景用 Let’s Encrypt + ACME 自动续期即可,把省下的成本投入到监控与自动化上,比买一年期商业 DV 更划算——毕竟 2029 年后证书有效期只剩 47 天,手动续期在工程上已不可行。

六、冲上 Qualys SSL Labs A / A+ 的调优清单

评分工具为 https://www.ssllabs.com/ssltest/,输入域名后等待 2-3 分钟。常见扣分项与修复动作如下:

1)证书链不完整(降为 B):用 openssl s_client -connect example.com:443 -servername example.com -showcerts 数一下返回几张证书,正常应有 2 张(站点证书 + 中间证书)。修复方式是改用 fullchain.pem,或在 Nginx 中把 cert.pem 与 chain.pem 按“站点在前、中间在后”的顺序合并。

2)DH 参数过弱(Logjam,降为 B):若配置了 ssl_dhparam,必须使用 2048 位以上,1024 位会被直接降级:

openssl dhparam -out /etc/nginx/dhparam.pem 2048

3)缺少 HSTS(只能到 A,拿不到 A+):加上 Strict-Transport-Security 响应头即可,A+ 还需要证书链完整、支持 TLS 1.3、无任何已知漏洞。

4)开启 TLS 1.0/1.1 或 RC4/3DES 套件:检查 ssl_protocols 与 ssl_ciphers,删掉 RC4、3DES、DES-CBC3-SHA、EXPORT 相关条目。

5)OCSP Stapling 未生效:表现为 “OCSP stapling: No”。多半是 resolver 未配置或 DNS 解析超时,按第三节配置 resolver 后重载即可。

配置完成后用两条命令做本地复检,比在线工具更快:

nmap --script ssl-enum-ciphers -p 443 example.com
testssl.sh --severity HIGH example.com

七、常见错误排查(含真实报错信息)

1)request:fail ssl hand shake error:小程序端握手失败。按顺序排查——SNI 是否配置(多站点必须)、是否只支持 TLS 1.3 而客户端要求 1.2、证书链是否完整。用 openssl s_client -servername 域名 复现,缺 -servername 时拿到默认站点证书也会报同样错误。

2)curl: (60) SSL certificate problem: unable to get local issuer certificate:服务端只下发了站点证书,缺中间证书。改为 fullchain.pem 即可,这是最高频的一类故障。

3)nginx: [emerg] SSL_CTX_use_PrivateKey_file(...) failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch):证书与私钥不匹配。用 modulus 比对确认:

openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa  -noout -modulus -in privkey.pem   | openssl md5

两个 md5 值必须一致,否则说明证书申请时用的不是这把私钥。

4)SSL_ERROR_NO_CYPHER_OVERLAP:客户端与服务端没有共同密码套件,常见于只保留 ECDSA 套件却部署了 RSA 证书。确认 ssl_ciphers 中同时包含 ECDHE-RSA-*。

5)urn:ietf:params:acme:error:unauthorized:Let’s Encrypt 验证失败。多为 80 端口被防火墙拦截、Nginx 未放行 /.well-known/acme-challenge/、或 CDN 回源配置错误。可临时改用 --preferred-challenges dns 绕开。

6)request:fail url not in domain list:与证书无关,是微信公众平台后台未把域名加入“request 合法域名”。注意合法域名不支持端口、必须备案、每月修改次数有限。

7)net::ERR_CERT_DATE_INVALID:证书过期或服务器系统时间错误。用 date -u 检查时间,用 openssl x509 -noout -enddate -in fullchain.pem 查看到期日。

八、效果验证:命令行、在线检测与真机联调

部署完成后按四层验证,任何一层不通过都不要交付。

第一层,协议与证书:

openssl s_client -connect www.example.com:443 -servername www.example.com -brief
openssl x509 -noout -subject -issuer -dates -in /etc/letsencrypt/live/example.com/fullchain.pem

确认 Verification: OK、Protocol version 为 TLSv1.2/1.3、到期时间与预期一致。

第二层,HTTP 行为:

curl -sI https://www.example.com | grep -Ei 'HTTP/|strict-transport|content-security'
curl -sI http://www.example.com

预期 301 跳转到 https,且响应头包含 HSTS。再验证弱协议确实被拒:curl --tlsv1.0 --tls-max 1.0 -I https://www.example.com 应返回 error:1409442E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version。

第三层,在线评分:Qualys SSL Labs 目标 A 及以上;国内可用 myssl.com 交叉验证,重点看“证书链完整性”和“TLS 版本分布”。

第四层,小程序真机:在微信开发者工具中关闭“不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书”选项,用真机预览执行一次 wx.request,同时观察服务端 access.log 是否收到请求、error.log 是否有握手告警。

最后配置到期监控,30 天内告警,避免“续期定时任务悄悄失效”这类静默故障:

openssl x509 -checkend 2592000 -noout -in /etc/letsencrypt/live/example.com/fullchain.pem || echo '证书将在30天内过期'

常见问题

Let’s Encrypt 免费证书能通过微信小程序的校验吗?

能。微信校验的是证书是否由受信任根 CA 签发、域名是否匹配、证书链是否完整、TLS 版本是否达标,与证书价格无关。Let’s Encrypt 由 ISRG Root X1 签发,在主流安卓与 iOS 系统信任库中均有效。前提是必须部署 fullchain.pem(含中间证书),只部署 cert.pem 会在部分机型上握手失败。

证书有效期不是一年吗?为什么我的证书 90 天就到期了?

公有信任 TLS 证书的最长有效期自 2020-09-01 起已被限制为 398 天,2026 年 3 月起进一步缩短到 200 天,2027 年 3 月为 100 天,2029 年 3 月为 47 天。Let’s Encrypt 主动把自家证书设为 90 天,是为了推动 ACME 自动化。正确做法不是“找一年期证书”,而是把续期交给 certbot 的 systemd timer 并配置到期监控。

小程序报 request:fail url not in domain list,是证书问题吗?

不是。这是域名未加入微信公众平台的“request 合法域名”列表。该列表要求域名已备案、使用 443 端口、不支持 IP 与 localhost,且每月修改次数有限。排查顺序:先看后台配置,再看证书——两者报错文案完全不同。

一台服务器有多个域名,如何避免证书混用导致的握手失败?

为每个站点单独配置 server_name 与 ssl_certificate,依赖 SNI 分流;客户端不支持 SNI(极老设备)时会拿到默认站点证书并报域名不匹配。也可以用一张 SAN 多域名证书覆盖全部域名,减少配置复杂度。测试时务必带上 -servername 域名 参数,否则复现不出真实行为。

开启 HSTS 之后还能回退到 HTTP 吗?

基本不能。浏览器在 max-age 有效期内会强制使用 HTTPS,且不提供“继续访问”按钮。上线时建议先用 max-age=300 观察,确认全站资源(含第三方 JS、字体、图片)全部支持 HTTPS 后再提升到一年;includeSubDomains 与 preload 要在确认所有子域都有证书后再加。

证书自动续期成功了,但网站还在用旧证书,为什么?

因为续期只更新磁盘文件,Web 服务仍持有旧证书的内存副本。certbot 的 --nginx/--apache 插件会自动 reload,但用 certonly 模式签发的证书需要手动挂 hook:在续期配置中加入 --deploy-hook 'nginx -s reload'。验证方法:续期后执行 openssl x509 -noout -dates -in fullchain.pem 与线上实际下发的证书做对比,两者日期不一致即为未重载。

内容审核

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