跳到主要内容
HTTPS安装配置

HTTPS 证书在 Nginx/Apache/IIS/Tomcat 的安装配置与微信小程序对接实战

HTTPS 证书在 Nginx/Apache/IIS/Tomcat 的安装配置与微信小程序对接实战 — 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。

五、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 过渡。

内容审核

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