跳到主要内容

Nginx 报错 no ssl_certificate is defined for the ssl listener:原因、修复与排查全指南

改完配置执行 sudo nginx -t,却收到一条 [emerg] 级别的错误,reload 被直接拒绝——这是 Nginx 里最常见、也最容易误判的一类启动失败。本文从报错原文出发,讲清它为什么指向 listen 行、如何用五分钟修好、以及证书明明存在却读不到时,怎么区分权限问题和 SELinux 问题。

一、报错原文到底在说什么

Nginx 1.15 及以后的输出(注意 ssl_certificate 两侧带引号):

nginx: [emerg] no "ssl_certificate" is defined for the "listen ... ssl" directive in /etc/nginx/conf.d/example.conf:5

老版本输出不带引号,含义完全相同:

nginx: [emerg] no ssl_certificate is defined for the "listen ... ssl" directive in /etc/nginx/nginx.conf:42

三个容易误解的点:

  • [emerg] 是最高级别。配置被整体拒绝,master 进程不会加载新配置,也不会重启 worker,此时线上仍在跑旧配置。
  • "listen ... ssl" 里的 ... 是字面占位符,不是省略了你的 IP 或端口,它就是在说“某个带 ssl 参数的 listen 指令”。
  • 行号指向 listen 443 ssl; 那一行,而不是你漏写证书的位置。因为 Nginx 在解析 listen 时就把文件名和行号记进了 SSL 的 srv_conf,真正的检查发生在 server 级配置合并之后。

换句话说:这条错误的意思是“这个 server 块监听了 ssl 端口,但合并完之后它名下没有任何证书”,而不是“你的证书路径写错了”。路径问题会以另一条错误出现,见第八节。

二、三种触发场景(第 2 种最容易忽略)

ssl_certificate 的合法上下文是 http 和 server:它可以从 http 块继承到子 server 块,但不会在兄弟 server 块之间传递。于是有三种典型情况:

  1. 该 server 块根本没写。最常见。
  2. 写在了兄弟 server 块里。两个域名共用一个 443 端口,A 域名正常、B 域名报错:
server {
    listen 443 ssl;
    server_name a.example.com;
    ssl_certificate     /etc/nginx/ssl/a.example.com.fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/a.example.com.key;
}

server {
    listen 443 ssl;          # ← 报错行号指向这里
    server_name b.example.com;
    # 证书忘写了,也不会从上面那个块继承
}
  1. 用了已废弃的 ssl on; 写法。ssl 指令自 1.15.0 起废弃、在 1.25.1 中被移除,正确做法是把 ssl 作为参数放进 listen。

另外两点常被忽略:stream 和 mail 模块里的 listen ... ssl 同样要求 ssl_certificate,且它们的上下文只有 stream/mail 和各自的 server 块,写在 http 块里无效;include 进来的文件如果路径写错、或被条件注释掉,也会表现为“明明写了却报没写”。

三、五分钟修复:最小可用配置

server {
    listen      443 ssl;
    listen      [::]:443 ssl;
    server_name example.com www.example.com;

    ssl_certificate     /etc/nginx/ssl/example.com.fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;

    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 10m;

    root  /var/www/example.com;
    index index.html;
}

放置文件并校验(master 进程以 root 启动,600/root:root 的私钥是安全的):

sudo mkdir -p /etc/nginx/ssl
sudo install -m 644 -o root -g root example.com.fullchain.pem /etc/nginx/ssl/
sudo install -m 600 -o root -g root example.com.key         /etc/nginx/ssl/
sudo nginx -t
sudo systemctl reload nginx

nginx -t 必须同时输出 syntax is ok 与 test is successful 才算通过。非 systemd 环境下对应命令是 nginx -s reload 或 openresty -s reload。

四、定位真正的缺失点

配置无效时 nginx -T 也会失败(它同样要做校验),所以先用 grep 找:

grep -rn --include='*.conf' -E 'listen[^;]*443[^;]*ssl' /etc/nginx/
grep -rn --include='*.conf' 'ssl_certificate' /etc/nginx/

把两份结果对照,缺证书的块立刻现形。修复之后再用 nginx -T 看合并后的完整配置:

sudo nginx -T | grep -nE '^s*(listen|server_name|ssl_certificate|ssl_certificate_key)'
nginx -v

别忽略发行版自带的默认站点:Debian/Ubuntu 的 sites-enabled/default、RHEL 系的 conf.d/default.conf 里通常已经有一个 listen 443 ssl; 块,你新加的配置没问题、报错却来自它,这类情况非常常见。

五、证书存在却读不到:权限与 SELinux

ls -l /etc/nginx/ssl/
namei -l /etc/nginx/ssl/example.com.fullchain.pem
sudo -u nginx test -r /etc/nginx/ssl/example.com.key && echo READABLE || echo DENIED

namei -l 会逐级列出路径上每一层目录的权限,父目录缺 x 位是典型的“文件 644 却读不到”。Debian/Ubuntu 上 worker 用户是 www-data,上面的 -u nginx 要相应替换。

RHEL/CentOS/Rocky/Alma 上先看 SELinux:

getenforce
ls -Z /etc/nginx/ssl/
sudo restorecon -Rv /etc/nginx/ssl
sudo ausearch -m avc -ts recent 2>/dev/null | grep -i nginx

从 /root 或 /home 拷过来的证书带的是 admin_home_t,即使 chmod 777 也会被拒绝;restorecon 会按策略把它恢复成 /etc/nginx 下应有的类型。需要确认策略规则时用 sudo semanage fcontext -l | grep /etc/nginx。Ubuntu 上则检查 AppArmor:sudo aa-status 与 sudo dmesg | grep -i -E 'apparmor|DENIED' | tail。

六、变量路径与版本门槛

ssl_certificate     /etc/nginx/ssl/$ssl_server_name.fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/$ssl_server_name.key;
  • 变量支持从 1.15.9 开始(不少老教程写 1.15.7,并不准确),用 nginx -v 确认。版本不够时 Nginx 会把 $ssl_server_name 当字面量,报出来的正是 cannot load certificate "/etc/nginx/ssl/$ssl_server_name.fullchain.pem" 这类路径错误。
  • 该写法依赖 SNI,不支持 SNI 的老客户端拿不到证书,握手直接失败。
  • 变量模式下证书在握手时才由 worker 进程读取,所以 nginx -t 永远通过、坏路径要等真实请求才暴露,并且文件必须对 worker 用户可读——这与固定路径“master 以 root 读一次”的模型完全不同。

七、原因对照表

现象 最可能的原因 处理
[emerg] no "ssl_certificate" ...,行号指向 listen 该 server 块没有 ssl_certificate 补上证书与私钥两行
只有部分域名报错,另一个域名正常 证书写在了兄弟 server 块 每个块各写一份,或提到 http 块统一继承
cannot load certificate ... No such file or directory 路径拼错、文件在容器外、include 未生效 改用绝对路径并 ls -l 验证
cannot load certificate ... Permission denied 目录缺 x 位、属主不对、SELinux/AppArmor namei -l + restorecon
PEM_read_bio_X509_AUX ... no start line 文件是 DER 格式、空文件、下载成了 HTML 错误页 openssl x509 -in ... -text 验证
SSL_CTX_use_PrivateKey ... failed 私钥与证书不匹配 比对公钥指纹
nginx -t 通过,浏览器仍报不受信任 缺中间证书或链顺序错 换成 fullchain 文件
启动无报错,握手时才失败 变量路径 + worker 无读权限 检查文件与 worker 用户
the "ssl" directive is deprecated 用了 ssl on; 改为 listen 443 ssl;

八、其他真实报错与处理

1. 文件不存在

nginx: [emerg] cannot load certificate "/etc/nginx/ssl/example.com.crt": BIO_new_file() failed (SSL: error:80000002:system library::No such file or directory:calling fopen(/etc/nginx/ssl/example.com.crt, r) error:10000080:BIO routines::no such file)

先确认路径是否被 Docker volume 覆盖成空目录:docker exec nginx ls -l /etc/nginx/ssl/。

2. 权限被拒

nginx: [emerg] cannot load certificate "/etc/nginx/ssl/example.com.crt": BIO_new_file() failed (SSL: error:8000000D:system library::Permission denied:calling fopen(/etc/nginx/ssl/example.com.crt, r))

先 namei -l 看目录权限,再 restorecon -Rv 看 SELinux;chmod 777 对 SELinux 无效。

3. 不是 PEM 格式

nginx: [emerg] PEM_read_bio_X509_AUX("/etc/nginx/ssl/example.com.crt") failed (SSL: error:0480006C:PEM routines::no start line)

文件里必须有 -----BEGIN CERTIFICATE-----。DER 格式先转换:openssl x509 -inform DER -in cert.der -out cert.pem。

4. 私钥与证书不匹配

nginx: [emerg] SSL_CTX_use_PrivateKey("/etc/nginx/ssl/example.com.key") failed (SSL: error:0A080006:SSL routines::EVP lib)

比对指纹,两条命令的输出必须完全一致:

openssl x509 -in /etc/nginx/ssl/example.com.fullchain.pem -noout -pubkey | openssl sha256
openssl pkey -in /etc/nginx/ssl/example.com.key -pubout | openssl sha256

5. 私钥带密码

nginx: [emerg] cannot load certificate key "/etc/nginx/ssl/example.com.key": PEM_read_bio_PrivateKey() failed (SSL: error:1E08010C:DECODER routines::unsupported)

要么去掉密码:openssl pkey -in example.com.key -out example.com.nopass.key,要么配置 ssl_password_file。

6. 指令重复

nginx: [emerg] "ssl_certificate" directive is duplicate in /etc/nginx/conf.d/default.conf:12

同一个 server 块里写了两次,或 include 的文件与主文件重复定义。

7. stream 块里报同样的错

stream { server { listen 443 ssl; } } 同样需要证书,且 ssl_certificate 不能从 http 块继承——两个模块的配置树彼此独立。

九、FAQ

Q:我只写了一个 server 块,为什么还是报这个错?
A:发行版自带的默认站点里通常已经有 listen 443 ssl;。用 grep -rn '443.*ssl' /etc/nginx/ 找出来,删掉或补证书即可。

Q:reload 失败了,线上站点会不会立刻挂?
A:不会立刻挂。master 进程保留旧配置、旧 worker 继续服务;但这是一颗定时炸弹——下次重启或崩溃恢复时 Nginx 将起不来,务必尽快修掉。

Q:为什么 nginx -T 也报同样的错?
A:-T 是先校验再 dump,配置无效时它和 -t 一样直接失败。所以排查阶段请先用 grep,修复后再用 -T 看合并结果。

Q:证书能放在 /root 或 /home 下吗?
A:技术上能读,但不推荐。SELinux 下这些目录是 admin_home_t,nginx 会被拒绝访问;统一放 /etc/nginx/ssl/ 最省事。

Q:一张证书能给多个域名用吗?
A:可以,前提是证书带对应 SAN,并且 server_name 里列全所有域名。多域名共用时,把 ssl_certificate 提到 http 块可以一次性继承给所有子块。

Q:HTTP/2 现在该怎么写?
A:1.25.1 起用 listen 443 ssl; 加 http2 on;;旧写法 listen 443 ssl http2; 已废弃但仍可用。

Q:私钥一定要 600 吗?
A:建议 600 root:root。master 以 root 启动时读取一次即可;但如果你用了变量路径,worker 也要读,此时需要按 worker 用户放宽属组或权限。

Q:改完怎么确认真的生效了?
A:按下面四步验证:

sudo nginx -t && sudo systemctl reload nginx
sudo ss -lntp | grep ':443'
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
curl -sSI https://example.com | head -n 1

第二条确认端口真的在监听,第三条确认服务端出示的正是预期证书与有效期,第四条确认 HTTP 层返回 HTTP/2 200 或 HTTP/1.1 200。