共计 4592 个字符,预计需要花费 12 分钟才能阅读完成。
要让 Nginx 以 HTTPS 提供单个站点的页面,最小配置要解决四件事:安装或编译出带 ngx_http_ssl_module 的 nginx,在 listen 上启用 ssl,ssl_certificate 指向包含服务器证书与中间证书的 PEM 文件,ssl_certificate_key 指向私钥。四项具备后,还需用配置测试和客户端链检查确认实际可用。
下面按“确认模块、写完整配置、检查证书文件、语法检查与重载、验证实际发送的链”的顺序展开。适用于单域名、单 IP、已从 CA 取得 PEM 格式证书和中间证书的场景;多域名共用同一 IP 时的 SNI 选择、HTTP 自动跳转、OCSP 装订不在最小配置范围内。
先确认模块与 SNI 支持
ngx_http_ssl_module 不是默认构建的模块,需要在编译时用 --with-http_ssl_module 启用,并且依赖 OpenSSL 库(模块文档)。先做只读检查;下面命令为未执行示例:
nginx -V 2>&1 | grep -E -- '--with-http_ssl_module|TLS SNI support enabled'
nginx -V 把版本和编译参数输出到标准错误,所以先用 2>&1 合并再过滤。输出中应出现 --with-http_ssl_module;如果还出现 TLS SNI support enabled,说明该二进制在编译时带 SNI 支持(HTTPS 配置文档)。若这里没有 --with-http_ssl_module,后面的配置即使写对也无法加载,需要换用带该模块的软件包或重新编译。
另一个版本差异是 ssl 指令:它在 1.15.0 被废弃,在 1.25.1 被移除,现代配置应使用 listen ... ssl,而不是在 server 里写 ssl on;(模块文档)。
最小完整 nginx.conf
下面是一份未执行的示例配置,只监听 443,位置以 Debian/Ubuntu 常见的 /etc/nginx/nginx.conf 为例。请替换域名、证书路径和站点根目录;写入 /etc/nginx 通常需要 root 或相应权限,并要保证 nginx master 进程能读取证书和私钥。include 的 mime.types 路径若发行版不同也要调整。
worker_processes auto;
events {
worker_connections 1024;
}
http {
include /etc/nginx/mime.types;
default_type application/octet-stream;
server {
listen 443 ssl;
server_name www.example.com;
ssl_certificate /etc/nginx/certs/www.example.com.chained.crt;
ssl_certificate_key /etc/nginx/certs/www.example.com.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
location / {
root /usr/share/nginx/html;
index index.html;
}
}
}
这份配置没有省略号,包含 nginx 启动所需的 events 与 http 块。listen 443 ssl 在监听套接字上启用 SSL;server_name 是虚拟主机名,客户端校验证书名称时还要看证书里的名称字段(例如 SubjectAltName),因此需另行确认证书覆盖 www.example.com。ssl_certificate 指向的 PEM 文件应把服务器证书放在最前,中间证书放在后面;ssl_certificate_key 指向私钥。证书是公开的,私钥需要限制访问,但必须可被 nginx master 进程读取(HTTPS 配置文档)。
文档说明当前默认使用 ssl_protocols TLSv1.2 TLSv1.3 和 ssl_ciphers HIGH:!aNULL:!MD5,所以通常不必显式写;这里写出来是为了让配置审阅时一眼看到协议和套件。默认值在历史上改过多次,旧版本上不要假设与当前文档一致(HTTPS 配置文档)。
如果 /etc/nginx/mime.types 不存在,nginx -t 会失败,应按发行版路径调整或删除该行;删除后静态文件的 Content-Type 可能不符合预期。这个示例只处理 HTTPS;如果还要在同一站点处理 80 端口,可按文档在同一 server 中增加 listen 80;,或另加 server 块并自行决定跳转策略(HTTPS 配置文档)。
检查证书文件本身
证书与私钥都应是 PEM 格式;私钥不要设为全局可读,但必须可被 nginx master 进程读取(HTTPS 配置文档)。可以用 ls -l 查看属主和权限,再按 master 的实际运行用户调整。下面命令为未执行示例:
ls -l /etc/nginx/certs/www.example.com.chained.crt /etc/nginx/certs/www.example.com.key
证书链的顺序最容易出错。文档明确要求:服务器证书在前,中间证书在后。若 CA 提供的是单独的服务器证书和中间证书包,可以按下面方式拼接;若 CA 直接提供合并好的 fullchain 文件,也可以直接指向它,是否包含中间证书仍要用后文的 s_client 核实。拼接命令为未执行示例:
cat /etc/nginx/certs/www.example.com.crt /etc/nginx/certs/intermediate.crt > /etc/nginx/certs/www.example.com.chained.crt
顺序拼反时,nginx 会尝试把私钥和证书包中的第一张证书配对,启动失败并显示包含 key values mismatch 的错误(HTTPS 配置文档)。因此出现这个错误时,先查链顺序,再查证书与私钥是否配对,不要只盯着私钥权限。
以下 OpenSSL 命令用于只读检查,均为未执行示例;不同 OpenSSL 版本的输出格式可能不同。第一条针对链文件中的第一张证书输出主题、签发者和有效期;第二条把文件中的证书打印出来,用来核对顺序。
openssl x509 -in /etc/nginx/certs/www.example.com.chained.crt -noout -subject -issuer -dates
openssl crl2pkcs7 -nocrl -certfile /etc/nginx/certs/www.example.com.chained.crt | openssl pkcs7 -print_certs -noout
如果证书是 RSA,可以用 modulus 的哈希值确认证书与私钥是否配对;下面两条命令也是未执行示例:
openssl x509 -noout -modulus -in /etc/nginx/certs/www.example.com.chained.crt | openssl md5
openssl rsa -noout -modulus -in /etc/nginx/certs/www.example.com.key | openssl md5
两条命令的输出应一致。这个方法只适用于 RSA;ECDSA 私钥没有 modulus,需要改用公钥比对,不能照搬这两条命令。若私钥有口令保护,命令可能要求输入口令。
语法检查、重载与回滚
修改前先备份原配置。下面命令只做复制,不改变 nginx 运行状态,为未执行操作示例:
sudo cp -a /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
编辑配置后先用 nginx -t 做配置测试,不要直接用重载代替测试。下面命令为未执行示例;成功或失败以命令输出和退出状态为准,失败时按报错文件与行号回到配置或证书文件。
sudo nginx -t
确认通过后再让 nginx 重新读取配置。重载属于运维操作,不在上述 nginx 文档节选范围内;下面命令是常见操作示例,未在当前环境执行,实际以本机 systemd 或服务脚本的管理方式为准:
sudo nginx -s reload
若使用 systemd 管理,也可以用 sudo systemctl reload nginx,二选一即可。重载后如果服务异常,恢复备份并再次测试、重载;以下回滚命令为未执行示例:
sudo cp -a /etc/nginx/nginx.conf.bak /etc/nginx/nginx.conf
sudo nginx -t
sudo nginx -s reload
这里的原则是先测试再重载,失败就回滚;不要把“改配置、测试、重载”合并成一条无法回退的命令。
验证服务端实际发送的证书链
nginx -t 通过只代表本机配置测试通过,不能证明客户端收到完整链。用 openssl s_client 直接看服务端返回的内容;下面命令为未执行示例,不会在本文环境产生实际输出:
openssl s_client -connect www.example.com:443 -servername www.example.com -showcerts </dev/null
输出中的 Certificate chain 会按 0、1、2 编号列出证书:0 是服务器证书,后续是中间证书。如果只出现 0,通常说明 ssl_certificate 指向的文件没有包含中间证书。文档也给出用 openssl s_client 确认完整链的做法(HTTPS 配置文档)。
还可以用 curl 做一次带证书校验的请求;下面命令为未执行示例:
curl -vI https://www.example.com/
观察证书校验是否通过、HTTP 状态是否符合预期。若 curl 报证书错误,而浏览器能打开,不要急着用 -k 跳过校验;-k 只能用来区分“是不是证书校验失败”,不能作为生产验收。应回到链、域名匹配和有效期三项逐一核对。
常见失败判断
| 现象 | 优先检查 | 说明 |
|---|---|---|
nginx 启动失败并报 key values mismatch |
证书链顺序、证书与私钥是否配对 | 服务器证书不在链文件首位时,nginx 会用错证书与私钥配对 |
| 浏览器提示证书链不完整 | openssl s_client 的 Certificate chain 是否只有 0 |
缺少中间证书时,应把中间证书追加到服务器证书之后 |
| 同一 IP 的多个 HTTPS 站点总返回默认站点证书 | 是否依赖 SNI,或是否为每个站点分配独立 IP | SSL 连接在 HTTP 请求之前建立,nginx 此时还不知道请求的域名,只能先给默认服务器证书 |
配置里写 ssl on; 报未知指令 |
nginx 版本 | 该指令在 1.25.1 已移除,应改用 listen ... ssl |
如果同一 IP 上要放多个 HTTPS 站点,需要让客户端通过 SNI 提供名称,或为每个站点分配独立 IP;文档还说明可以用 ssl_reject_handshake 在默认服务器上拒绝不合适的握手(该指令从 1.19.4 起提供,见模块文档)。这不属于单站点最小配置,但遇到“证书串站”时应先想到这里。
本文所依据的是 nginx 官方“Configuring HTTPS servers”和“Module ngx_http_ssl_module”两页的节选与提取代码块,未执行配置,也未抓取完整全文;不同发行版的默认路径、nginx 版本和 OpenSSL 行为可能不同,落地时以本机 nginx -V 和 nginx -t 的结果为准。
常见问题
证书和私钥可以放在同一个文件吗?
可以。nginx 文档说明私钥可以放在证书同一文件中,此时文件访问权限也要限制;本文示例为便于排错,将证书和私钥分开存放。
为什么 nginx -t 成功,浏览器还提示证书链不完整?
nginx -t 通过不等于客户端实际收到完整链;用 openssl s_client -showcerts 查看 Certificate chain 是否包含中间证书。
必须显式写 ssl_protocols 和 ssl_ciphers 吗?
文档说明默认已是 TLSv1.2、TLSv1.3 和 HIGH:!aNULL:!MD5,通常不必显式写;但默认值随版本变过,本文写出便于审阅。
引用资料
资料链接仅表示正文使用了该素材,不代表所有结论已独立核验。