HTTPS 证书在 Nginx/Apache/IIS/Tomcat 的安装配置与微信小程序对接实战
一、问题背景与根因:小程序为什么强制 HTTPS
微信小程序的 wx.request、wx.uploadFile、wx.downloadFile 只允许 https:// 请求,域名必须在「小程序后台 → 开发管理 → 开发设置 → 服务器域名」中配置为 request 合法域名,不能是 IP 地址、不能带端口(只能走 443),国内主体还需完成 ICP 备案。基础库要求 TLS 1.2 及以上,iOS 的 ATS 还要求证书使用 SHA-256 签名、RSA ≥ 2048 位或 ECC ≥ 256 位、支持前向保密套件。自签名证书一律不被信任。
线上绝大多数「证书装完浏览器正常、小程序却报错」的问题,都可以归到下面几类根因:
- 证书链不完整:服务器只下发了站点证书,没带中间 CA。PC 浏览器会缓存在线获取的中间证书,所以看起来正常;Android 与小程序端直接握手失败。
- 域名不匹配:证书 CN/SAN 里没有实际请求的域名,例如漏配 www 或 api 子域。
- 协议或套件过旧:只开了 TLSv1.0/1.1,或仍在使用 CBC/3DES 套件。
- 证书与私钥不匹配、证书已过期、服务器时间不同步,握手阶段直接中断。
这里要纠正一个流传很广的过时说法:「免费 SSL 证书申请后可用一年」已经不成立。按 CA/Browser Forum 基线要求,2020-09-01 之后签发的公开信任 TLS 证书有效期上限为 398 天;Let’s Encrypt 的免费证书统一为 90 天,必须靠 certbot 自动续期,而不是手工一年一换。所谓「技术服务」只负责把证书装到服务器上,证书本身的生命周期管理仍然要靠自动化。
二、证书申请与 CSR 生成:先把文件准备对
无论后面用哪台服务器,前置产物只有四样:私钥、站点证书、中间链、合并后的 fullchain。先用 OpenSSL 生成私钥与 CSR(CN 与 SAN 必须覆盖所有要用的域名):
# RSA 2048,兼容性最好
openssl genrsa -out example.com.key 2048
# 或 ECDSA P-256,握手更快,小程序 / iOS 均支持
openssl ecparam -genkey -name prime256v1 -out example.com.key
# 生成 CSR,-addext 需要 OpenSSL 1.1.1+
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,DNS:api.example.com"
openssl req -in example.com.csr -noout -text | grep -A1 "Subject Alternative Name"
chmod 600 example.com.key
用 Let’s Encrypt 时不必手工做 CSR:
certbot certonly --webroot -w /var/www/html
-d example.com -d www.example.com --agree-tos -m ops@example.com
# 产物:/etc/letsencrypt/live/example.com/{fullchain.pem,privkey.pem,chain.pem}
拿到证书后先本地自检,再往服务器上放:
openssl x509 -in cert.pem -noout -subject -issuer -dates
openssl verify -CAfile chain.pem cert.pem # 期望输出 cert.pem: OK
openssl rsa -noout -modulus -in example.com.key | openssl md5
openssl x509 -noout -modulus -in cert.pem | openssl md5 # 两个 md5 必须一致
IIS / Tomcat 需要单文件容器,用下面命令打包成带完整链的 PFX:
openssl pkcs12 -export -out example.com.pfx
-inkey example.com.key -in cert.pem -certfile chain.pem -passout pass:ChangeMe123
注意 -certfile chain.pem 不能省,否则 Windows 上导入的 pfx 缺少中间证书,Android 与小程序端握手会失败。
三、Nginx 安装与配置实操
先确认模块:nginx -V 2>&1 | grep -o with-http_ssl_module,无输出说明要重编译或换官方源包。私钥权限必须是 root 可读:chown root:root example.com.key && chmod 600 example.com.key。
server {
listen 80;
server_name example.com www.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl; # Nginx 1.25.1+ 写法:listen 443 ssl; http2 on;
server_name example.com www.example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 必须是 fullchain
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;
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.pem;
add_header Strict-Transport-Security "max-age=31536000" 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;
}
}
保存后执行:nginx -t && systemctl reload nginx。
三个易错点:① ssl_certificate 必须指向 fullchain(站点证书在前、中间证书在后拼接),写成 cert.pem 会让小程序报握手失败;② OCSP stapling 依赖 ssl_trusted_certificate 指向 chain.pem,缺了会告警且不生效;③ 反向代理后端时 X-Forwarded-Proto https 不能丢,否则后端生成的回调地址仍是 http,小程序端会 302 到 http 被拦截。
四、Apache 与 IIS 配置示例
Apache 2.4:先确认 httpd -M | grep ssl_module,再写虚拟主机:
<VirtualHost *:443>
ServerName example.com
SSLEngine on
SSLCertificateFile /etc/httpd/ssl/fullchain.pem
SSLCertificateKeyFile /etc/httpd/ssl/example.com.key
# Apache 2.4.8 之前必须单独指定链文件;2.4.8+ 可把链拼进 SSLCertificateFile
# SSLCertificateChainFile /etc/httpd/ssl/chain.pem
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite ECDHE+AESGCM:ECDHE+CHACHA20:!aNULL:!MD5:!3DES
Header always set Strict-Transport-Security "max-age=31536000"
</VirtualHost>
校验并平滑重载:apachectl configtest 通过后 systemctl reload httpd(Debian 系为 apache2)。
IIS 8 及以上:
- 导入 PFX:
certutil -importPFX -p ChangeMe123 C:sslexample.com.pfx,或在 MMC「证书(本地计算机)→ 个人」中导入,务必勾选「包含所有扩展属性」与「允许导出」。 - 中间证书要单独导入到「中间证书颁发机构 → 证书」,否则 IIS 只发站点证书,链依旧不完整。
- 站点 → 绑定 → 添加 https,端口 443,勾选「需要服务器名称指示(SNI)」;多域名共用 443 必须开 SNI。
- 验证绑定:
netsh http show sslcert hostnameport=example.com:443。
IIS 没有 reload 概念,改完绑定即时生效;若客户端仍拿到旧证书,重启 W3SVC 服务或执行 iisreset。
- 服务器维护 · 网站代维护 · 服务器托管代维
- SSL证书安装服务 · 腾讯云 HTTPS 部署 · 证书过期更新
- NGINX / APACHE / TOMCAT / IIS 证书配置 · SSL证书安装
五、Tomcat 配置示例(JKS / PKCS12)
Tomcat 不认 PEM,先把 PFX 转成 keystore。Tomcat 8.5+ 也支持直接使用 PKCS12:
keytool -importkeystore -srckeystore example.com.pfx -srcstoretype PKCS12
-srcstorepass ChangeMe123 -destkeystore example.com.jks -deststoretype JKS
-deststorepass ChangeMe123 -destkeypass ChangeMe123
keytool -list -v -keystore example.com.jks | grep -E "Alias|Valid"
Tomcat 9 的 server.xml 使用 SSLHostConfig 写法:
<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="200" SSLEnabled="true" scheme="https" secure="true">
<SSLHostConfig protocols="TLSv1.2,TLSv1.3"
ciphers="TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
honorCipherOrder="true">
<Certificate certificateKeystoreFile="conf/example.com.jks"
certificateKeystorePassword="ChangeMe123"
certificateKeystoreType="JKS" />
</SSLHostConfig>
</Connector>
重启:systemctl restart tomcat,并检查 logs/catalina.out 是否出现 Keystore was tampered with, or password was incorrect。生产环境更常见的做法是 Tomcat 只监听 127.0.0.1:8080,由前置 Nginx 终结 TLS,这样续期只改一处,再用 proxy_set_header X-Forwarded-Proto https 保证 Spring Boot 生成的 redirect_uri 正确。
六、四种服务器横向对比与证书类型选择
| 对比项 | Nginx | Apache | IIS | Tomcat |
|---|---|---|---|---|
| 证书格式 | PEM | PEM | PFX / P12 | JKS 或 PKCS12 |
| 链证书配置 | fullchain 合并 | 2.4.8+ 合并;旧版 SSLCertificateChainFile | 中间 CA 需单独导入 | keystore 内须含链 |
| 语法校验 | nginx -t | apachectl configtest | 无,看事件查看器 | 无,看 catalina.out |
| 生效方式 | reload | graceful / reload | 绑定即生效,必要时 iisreset | restart |
| SNI 支持 | 默认支持 | 2.2.12+ | IIS 8+ | 8.5+ 默认 |
| 典型坑 | 误配 cert.pem | 漏 ChainFile | pfx 无中间证书 | keystore 密码 / 类型错 |
| 证书类型 | 覆盖范围 | 有效期上限 | 适用场景 |
|---|---|---|---|
| DV 单域名 | 1 个 FQDN | 398 天 | 单接口域名,小程序最常见 |
| DV 多域名(SAN) | 最多约 100 个 FQDN | 398 天 | 主域 + www + api |
| 通配符 *.example.com | 仅一级子域 | 398 天 | 子域多且结构固定 |
| Let’s Encrypt | 同 SAN 规则 | 90 天 | 可自动续期的任何场景 |
小程序只要求证书被系统信任,DV 证书即可满足;OV/EV 不改变小程序行为,只影响浏览器展示与企业合规。注意通配符不覆盖 a.b.example.com 这类二级子域,需改用 SAN 多域名证书。选型时优先看「能否自动续期」,而不是「有效期是不是一年」。
七、常见错误排查(附真实报错)
| 报错信息 | 根因 | 处理 |
|---|---|---|
curl: (60) SSL certificate problem: unable to get local issuer certificate |
缺中间证书 | 改用 fullchain.pem;IIS 导入中间 CA;Tomcat 重新打包 keystore |
nginx: [emerg] SSL_CTX_use_PrivateKey_file(...) failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch) |
证书与私钥不配对 | 用 modulus md5 比对,确认后重新签发 |
curl: (60) SSL: no alternative certificate subject name matches target host name 'api.example.com' |
SAN 未覆盖该域名 | CSR 补 SAN 后重签 |
curl: (35) error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure |
协议版本或加密套件不匹配 | 开放 TLSv1.2/1.3,补齐 ECDHE-GCM 套件 |
小程序 request:fail ssl hand shake error |
链不完整 / 协议过低 / 非受信 CA | openssl s_client 复现,按上面三条逐一排除 |
nginx: [warn] "ssl_stapling" ignored, issuer certificate not found |
未配 ssl_trusted_certificate | 指向 chain.pem |
Apache AH02217: ssl_stapling_init_cert: can't retrieve issuer certificate! |
缺链文件 | 补 SSLCertificateChainFile 或合并到 SSLCertificateFile |
Tomcat java.io.IOException: Keystore was tampered with, or password was incorrect |
密码错或格式声明不符 | 核对 certificateKeystorePassword / certificateKeystoreType |
x509: certificate has expired or is not yet valid |
过期或系统时间偏差 | 续期,并用 chronyc/ntpdate 校时 |
排查顺序建议固定为:先 openssl s_client -showcerts 看服务器到底发了几张证书,再用 curl -v 看客户端信任结果,最后才去翻服务器日志。绝大多数问题在第一步就能定位。
八、效果验证与自动续期
配置完成后按下面几条命令逐项验收:
# 1. 看服务器下发的证书链(应返回 2 张及以上)
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -c "BEGIN CERTIFICATE"
# 2. 看主体、签发者、有效期
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
# 3. 信任校验,必须是 0 (ok)
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | grep "Verify return code"
# 4. HTTP 状态与证书校验结果
curl -sS -o /dev/null -w "%{http_code} %{ssl_verify_result}n" https://example.com
# 5. 确认 TLSv1.0 已被拒绝(应出现 alert / handshake failure)
echo | openssl s_client -connect example.com:443 -tls1 2>&1 | grep -i "alert|error"
再做两件事:一是把域名丢进 SSL Labs 跑一次,目标 A 及以上,重点看「Certificate Chain」「Protocols」两项;二是在小程序开发者工具里用真机预览发起一次真实请求,注意「不校验合法域名」选项只对工具生效,真机必须走已配置的合法域名。
续期与到期监控:
# 提前 30 天告警
openssl x509 -in /etc/nginx/ssl/fullchain.pem -noout -checkend 2592000 || echo "证书 30 天内到期"
# Let's Encrypt 演练 + 实际续期
certbot renew --dry-run
# crontab:0 3 * * * /usr/bin/certbot renew --quiet --deploy-hook "systemctl reload nginx"
用 deploy-hook 而不是 renew-hook,才能保证只有在真正续期成功后才 reload,避免无意义的重载。
常见问题
免费 SSL 证书真的只能用一年吗?
不是。自 2020-09-01 起,CA/Browser Forum 规定公开信任 TLS 证书有效期上限为 398 天,且业界仍在持续缩短;Let’s Encrypt 的免费证书统一为 90 天。市面上所谓「一年免费证书」,多是商家代申请的一次性证书打包销售,到期同样要续。正确做法是用 certbot 配置自动续期,而不是每年手工更换。
浏览器显示锁标志正常,但小程序报 ssl hand shake error?
典型原因是证书链不完整。PC 浏览器会主动下载并缓存中间证书,Android 与小程序不会。用 openssl s_client -showcerts 检查服务器是否只返回了一张证书:Nginx 改用 fullchain.pem,Apache 补 SSLCertificateChainFile,IIS 把中间证书导入「中间证书颁发机构」,Tomcat 重新用带链的 PFX 生成 keystore。
一张证书能给多个域名或子域使用吗?
可以。用 SAN 多域名证书(单张通常覆盖 100 个 FQDN)或通配符 *.example.com。注意通配符只覆盖一级子域,a.b.example.com 不在其内。小程序后台配置的每一个 request 合法域名都必须被证书覆盖,否则对应接口调用会失败。
证书装好后还需要域名备案吗?
需要。域名必须完成 ICP 备案才能配置为小程序的 request 合法域名,且只能是 443 端口的标准 HTTPS 地址,不能使用 IP 或非标端口。备案与证书是两件独立的事,缺一不可。
私钥泄露或证书即将到期怎么办?
立即重新签发并替换证书:Let’s Encrypt 可先 certbot revoke --cert-path fullchain.pem 吊销,再重新签发;商业证书走 CA 的补发流程。同时轮换服务器上所有副本,检查私钥是否被误提交到 Git 或被打进镜像。私钥文件始终保持 600 权限、属主 root。
必须启用 TLS 1.3 吗?
不是必须,TLS 1.2 已满足微信小程序的要求。但建议同时开启 TLSv1.2 与 TLSv1.3,并显式关闭 TLSv1.0/1.1(SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1)。若仍有老版本 Android 客户端,先看访问日志与埋点再决定是否保留 TLSv1.0 过渡。