DevOps知识中心
DevOps知识中心

Nginx 常见错误排查：实用指南

遇到 Nginx 错误？本实用指南可帮助您诊断并解决常见问题。了解如何处理配置问题、权限拒绝错误、连接拒绝、502/504 网关错误等。我们提供清晰的解释、可操作的解决方案以及必要的 Nginx 命令，以确保您的网站保持可访问且平稳运行。

67 浏览量

Nginx 常见错误故障排除：实用指南

Nginx 是一个强大而多功能的 Web 服务器，但与任何复杂软件一样，它有时也会带来挑战。遇到错误可能会令人沮丧，尤其是在影响您的网站可用性时。本指南提供了一种实用的方法来诊断和解决一些最常见的 Nginx 错误，涵盖配置问题、权限问题、超时和客户端相关错误。通过理解这些常见陷阱并学习如何解决它们，您可以确保您的 Nginx 服务器运行顺畅，并且您的网站对用户保持可访问性。

本文旨在为您提供有效排除 Nginx 故障的知识和工具。我们将介绍典型的错误场景，解释其根本原因，并提供附有说明性示例的具体解决方案。无论您是初学者还是经验丰富的 Nginx 管理员，本指南都将是保持 Web 服务器处于最佳状态的宝贵资源。

Nginx 常见错误类别

Nginx 错误可以根据其根本原因进行广泛分类。理解这些类别有助于缩小问题范围。

  • 配置错误：nginx.conf 或包含的配置文件中的错误。这些通常是最常见的罪魁祸首。
  • 权限错误：Nginx 工作进程缺少访问文件或目录所需的权限。
  • 超时错误：与服务器未在预期时间内响应相关的问题，通常是由于后端应用程序问题或网络延迟引起的。
  • 客户端错误：源自客户端的问题，但有时被误解为服务器端问题。
  • 资源错误：服务器资源不足，如内存、CPU 或文件描述符。

诊断 Nginx 错误

故障排除的第一步是识别错误消息及其位置。Nginx 日志是您的主要信息来源。

检查 Nginx 日志

Nginx 通常将错误记录到两个主要文件中：

  • 错误日志 (error.log)：Nginx 在此处记录所有错误和警告。在 Linux 系统上，其默认位置通常是 /var/log/nginx/error.log。
  • 访问日志 (access.log)：虽然主要用于跟踪请求，但此日志有时可以为错误提供上下文，尤其是 HTTP 状态码。

要查看错误日志的最新条目，您可以使用 tail 命令：

tail -f /var/log/nginx/error.log

此命令将实时流式传输日志文件，允许您在错误发生时进行查看。

验证 Nginx 配置

在对 Nginx 进行配置更改后重新启动之前，至关重要的是测试配置是否存在语法错误：

sudo nginx -t

此命令会检查配置文件，并报告发现的任何语法错误以及错误发生的行号。如果测试成功，它将输出：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Nginx 常见错误及解决方案

让我们深入研究具体的错误场景及其补救措施。

1. (13: Permission denied) 错误

当 Nginx 工作进程没有读取文件或访问其应服务的目录的权限时，此错误通常会出现在 error.log 中。

原因：nginx.conf 中的 user 指令（通常是 www-data 或 nginx）对 Web 根目录或其中的文件没有读取权限。

解决方案：确保 Nginx 用户对您的 Web 内容目录具有适当的读取权限。您可以使用 chown 和 chmod 命令来实现这一点。

示例：

如果您的 Web 根目录是 /var/www/html 并且 Nginx 用户是 www-data：

# 将所有权授予 nginx 用户和组
sudo chown -R www-data:www-data /var/www/html

# 确保目录可执行且文件可读
sudo find /var/www/html -type d -exec chmod 755 {} \;
sudo find /var/www/html -type f -exec chmod 644 {} \;

提示：如果您正在提供静态文件并且需要阻止对某些目录的直接访问，请确保 Nginx 用户对目录具有执行权限以遍历它们，但不一定对目录内容具有读取权限（如果它们不应被列出）。

2. (111: Connection refused) 错误

此错误表示 Nginx 服务器尝试连接到另一个服务（例如，后端应用程序服务器，如 Node.js、Python/Gunicorn 或 PHP-FPM），但连接被目标主动拒绝。

原因：后端应用程序服务未运行，正在监听与 Nginx 期望的端口或 IP 地址不同的端口或 IP 地址，或者防火墙正在阻止连接。

解决方案：

  • 验证后端服务状态：确保您的应用程序服务器（例如 Gunicorn、Node.js、PHP-FPM）正在运行。
    • 对于 systemd 服务：sudo systemctl status <service_name>（例如 php8.1-fpm、gunicorn）。
    • 对于其他进程：ps aux | grep <process_name>。
  • 检查监听地址/端口：确认后端服务正在监听 Nginx proxy_pass 或 fastcgi_pass 指令中指定的 IP 地址和端口。
    bash # 示例：检查 Node.js 是否监听端口 3000 sudo ss -tulnp | grep 3000
  • 防火墙规则：确保没有防火墙阻止 Nginx 和后端服务之间的连接。

示例 Nginx 配置片段：

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

在这种情况下，请确保您的应用程序正在运行并监听 http://127.0.0.1:3000。

3. 502 Bad Gateway 错误

502 Bad Gateway 错误表示 Nginx 作为网关或代理，从上游服务器收到了无效的响应。

原因：与 Connection refused 类似，但上游服务器是可访问的，却返回了无效或不完整的响应。这可能是由于：
* 后端应用程序崩溃或遇到内部错误。
* 后端应用程序响应时间过长。
* Nginx 和上游之间的网络问题。
* proxy_pass 或 fastcgi_pass 配置不正确。

解决方案：

  • 检查后端应用程序日志：检查后端应用程序的日志以查找任何错误或异常。这通常是查找根本原因的最直接方法。
  • 增加超时时间：如果应用程序正在执行长时间操作，您可能需要增加 Nginx 的超时值。
    nginx proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; fastcgi_send_timeout 60s; fastcgi_read_timeout 60s;
    请谨慎调整这些值，因为过长的超时可能会占用工作进程。
  • 验证上游配置：仔细检查 proxy_pass 或 fastcgi_pass 指令是否正确。

4. 413 Request Entity Too Large 错误

当客户端发送的请求体超过 Nginx 中配置的大小限制时，会发生此错误。

原因：客户端尝试上传文件或发送的数据大于 Nginx 配置的接受大小。

解决方案：在 Nginx 配置中调整 client_max_body_size 指令。此指令通常设置在 http、server 或 location 块中。

示例：

允许高达 100MB 的请求：

http {
    # ... 其他 http 配置 ...
    client_max_body_size 100M;
}

记住在进行更改后运行 sudo nginx -t 并重新加载 Nginx (sudo systemctl reload nginx)。

5. 403 Forbidden 错误

403 Forbidden 错误表示服务器理解请求但拒绝授权。对于静态文件，这通常意味着 Nginx 没有权限访问所请求的文件或目录。

原因：与 Permission denied 错误类似，但具体导致 HTTP 403 状态码。如果禁用了目录列表且未找到 index 文件，也可能发生这种情况。

解决方案：

  • 检查文件权限：确保 Nginx 用户对所请求的文件具有读取权限，并且对通往它的所有父目录具有执行权限。请参阅 (13: Permission denied) 错误的解决方案。
  • 检查 index 指令：如果请求的是目录（例如 http://example.com/some/directory/），Nginx 会查找 index 文件（如 index.html 或 index.php）。如果不存在 index 文件且禁用了目录列表，则会发生 403 Forbidden 错误。
    nginx location / { root /var/www/html; index index.html index.htm; }
  • 检查 autoindex 指令：如果您打算允许目录列表，请确保设置了 autoindex on;。但出于安全原因，通常不建议这样做。

6. 504 Gateway Timeout 错误

这表示 Nginx 作为网关，未及时收到上游服务器的响应。

原因：上游应用程序处理请求的时间过长，超出了 Nginx 中配置的超时限制。这与 502 Bad Gateway 非常相似，但专门强调了超时。

解决方案：

  • 增加 Nginx 超时时间：与 502 errors 一样，增加 proxy_read_timeout、proxy_send_timeout 和 fastcgi_read_timeout 可以提供帮助。
  • 优化后端应用程序：最有效的长期解决方案是优化后端应用程序的性能，使其响应更快。
  • 检查后端日志：查找应用程序日志中运行时间过长的进程或错误。

7. SSL/TLS 错误

与 SSL 证书相关的错误会阻止用户安全地访问您的网站。

原因：证书路径不正确、证书过期、域名不匹配或 SSL 指令配置不当。

解决方案：

  • 验证证书路径：确保 ssl_certificate 和 ssl_certificate_key 指令指向正确且存在的​​文件。
    nginx ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
  • 检查证书过期：使用 openssl 等工具或检查证书提供商的仪表板，确保证书未过期。
    bash openssl x509 -in /path/to/your/certificate.pem -noout -dates
  • 确保域名匹配：验证证书的主体备用名称 (SAN) 或通用名称 (CN) 是否包含用户正在访问的域名。
  • 检查 ssl_protocols 和 ssl_ciphers：确保您使用的是现代、安全的协议和密码套件。

客户端错误

虽然 Nginx 是服务器，但某些客户端行为或配置可能表现为看似与服务器相关的问题。

  • ERR_CONNECTION_RESET：通常表示客户端和服务器之间的网络问题，或者任一端的防火墙主动关闭了连接。它也可能指向服务器应用程序崩溃并突然关闭连接。
  • 400 Bad Request：通常表示客户端发送了服务器无法理解的请求（例如，格式错误的标头）。这在标准浏览器中不太常见，但可能出现在自定义客户端或机器人上。

最小化错误的最佳实践

  • 配置管理：对 Nginx 配置文件使用版本控制。在部署前彻底测试配置 (nginx -t)。
  • 日志记录：配置全面的日志记录，并定期查看 error.log 以查找任何异常。
  • 监控：实施对 Nginx 服务器和后端应用程序的监控。这有助于在问题影响用户之前主动检测到它们。
  • 保持 Nginx 更新：定期将 Nginx 更新到最新的稳定版本，以受益于错误修复和安全补丁。
  • 了解您的应用程序：充分了解后端应用程序的行为、资源需求和常见的故障模式。

结论

排除 Nginx 错误是维护可靠 Web 形象的关键技能。通过系统地检查日志、验证配置以及理解权限问题、连接被拒和超时等常见错误模式，您可以高效地诊断和解决问题。请记住，始终测试配置更改，并考虑优化后端应用程序以获得更好的性能和稳定性。通过这些实践，您可以使 Nginx 服务器运行顺畅，并使您的网站对所有用户保持可访问性。