Nginx SSL配置常见问题

Nginx SSL 配置常见问题与排查清单

一 模块与依赖问题

• 未编译 http_ssl_module 会在 reload 时报错：the “ssl” parameter requires ngx_http_ssl_module 或 unknown directive “ssl”。处理：执行 nginx -V | grep http_ssl_module 检查；若缺失，安装 OpenSSL 开发库（如 openssl-devel），进入 Nginx 源码目录重新配置编译：./configure --with-http_ssl_module，执行 make（不要 make install 覆盖原二进制），再 reload。缺少 OpenSSL 依赖会触发 configure 报错：SSL modules require the OpenSSL library。以上步骤可恢复 SSL 指令支持。

二 证书与路径问题

• 证书/私钥路径错误或文件不可读：Nginx 启动或 reload 失败，提示 cannot load certificate key。处理：核对 ssl_certificate / ssl_certificate_key 路径、文件是否存在且非空；注意不同厂商打包文件名不同（如 fullchain.pem + privkey.pem，或 bundle.crt + .key），不要混用；私钥权限建议 600，属主 root:root。证书链不完整（仅放服务器证书、缺中间证书）会导致浏览器提示不受信任或 NET::ERR_CERT_AUTHORITY_INVALID，应使用包含完整链的 fullchain 文件或在 Nginx 中正确拼接中间证书。证书与私钥不匹配也会握手失败，可用模数校验：openssl rsa -noout -modulus -in privkey.pem | md5 与 openssl x509 -noout -modulus -in cert.pem | md5 比对；证书格式需为标准 PEM，避免多余空格或 BOM。多站点 SNI 场景下若未正确设置 server_name 或存在多个未区分的 listen 443 ssl，可能出现证书错配或默认站点证书被错误使用，建议仅为一个站点设置 default_server 并为每个站点明确 server_name。

三 协议与套件配置问题

• 启用过时协议（如 SSLv3/TLS1.0/TLS1.1）或不安全套件，既影响安全也会触发兼容性问题。建议仅启用 TLSv1.2/TLSv1.3，并优先选择支持前向保密的套件：ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ‘TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384’; ssl_prefer_server_ciphers on;。若客户端握手失败或评分偏低，使用 SSL Labs 等工具核查协议与套件配置，并关闭不安全协议/套件。

四 性能与安全增强项

• 启用 HTTP/2 可显著降低连接延迟（listen 443 ssl http2; 需 Nginx 编译时包含 http_v2_module）。开启 SSL 会话缓存 复用握手：ssl_session_cache shared:SSL:10m; ssl_session_timeout 1d;。启用 OCSP Stapling 减少客户端在线校验证书状态的开销：ssl_stapling on; ssl_stapling_verify on; resolver 8.8.8.8 8.8.4.4 valid=300s; resolver_timeout 5s;。启用 HSTS 强制浏览器使用 HTTPS：add_header Strict-Transport-Security “max-age=31536000; includeSubDomains; preload” always;。这些设置能同时提升安全与性能。

五 快速排查与验证命令

• 配置语法与包含路径：执行 nginx -t 检查语法与文件包含是否正确。证书与密钥匹配：对比模数 md5（见上）。查看证书链与有效期：openssl x509 -noout -text -in server.crt；如需验证中间链或 OCSP，准备 chain 或 trusted_certificate。在线检测与回归：使用 SSL Labs 测试；抓包分析可用 openssl s_client -connect example.com:443 -servername example.com 查看握手与证书链；浏览器开发者工具 Security/Console 面板定位 Mixed Content 等前端问题。以上步骤覆盖从配置、证书到握手的全链路排查。