Eric的知识库

外观

配置文件

约 4438 字大约 15 分钟

2025-10-10

打开conf文件夹的 nginx.conf 文件，Nginx服务器的基础配置，默认的配置也存放在此。

注：在 nginx.conf 的注释符号为： #

关键配置文件关系

Nginx的核心配置在nginx.conf 文件中，但除了nginx.conf 外Nginx还有很多配置子目录，这些子目录都有不同的应用场景。

nginx.conf (主配置)
    ├── conf.d/*.conf (通用配置)
    ├── sites-enabled/* (虚拟主机)
    └── mime.types (MIME类型)

最佳实践建议

  1. 保持主配置简洁：在 nginx.conf 中只保留核心配置

  2. 使用模块化配置：将不同功能拆分到 conf.d/ 中的独立文件

  3. 利用站点管理：使用 sites-available/ 和 sites-enabled/ 管理虚拟主机

  4. 合理组织网站文件：为每个站点创建独立的目录

  5. 定期日志轮转：配置 logrotate 管理日志文件大小

模块化配置实例

/etc/nginx/
├── nginx.conf          # 主配置文件（包含http块）
├── conf.d/
│   ├── gzip.conf       # gzip相关配置
│   └── security.conf   # 安全相关配置
└── sites-enabled/
    ├── example.com     # example.com的server配置
    └── api.com         # api.com的server配置

本文先只讲主配置文件中的内容，其他配置文件待学成后补充...

主配置文件

打开 nginx.conf 文件，可以看到代码的大致结构：

...              #全局块

events {         #events块
   ...
}

http      #http块
{
    ...   #http全局块
    server        #server块
    { 
        ...       #server全局块
        location [PATTERN]   #location块
        {
            ...
        }
        location [PATTERN] 
        {
            ...
        }
    }
    server
    {
      ...
    }
    ...     #http全局块
}

可以看到，Nginx配置文件通常包含3个模块：

  • 全局块：比如工作进程数，定义日志路径；

  • Events块：设置处理轮询事件模型，每个工作进程最大连接数及http层的keep-alive超时时间；

  • http块：路由匹配、静态文件服务器、反向代理、负载均衡等。

    其中http块又可以进一步分成3块：

    • http全局块里的配置对所有站点生效
    • server块配置仅对单个站点生效
    • location块的配置仅对单个页面或url生效

全局块

全局块是默认配置文件从开始到events块之间的一部分内容，主要设置一些影响Nginx服务器整体运行的配置指令，因此，这些指令的作用域是Nginx服务器全局。

通常包括配置运行 Nginx 服务器的用户（组）、允许生成的 worker process 数、Nginx 进程 PID 存放路径、日志的存放路径和类型以及配置文件引入等。

events {
  # 指定可以运行 nginx 服务的用户和用户组
  # user [user] [group]
  # 将user指令注释掉，或者配置成 nobody 的话所有用户都可以运行
  # user nobody nobody;
  # user 指令在 Windows 上不生效，如果指定具体用户和用户组会报警告
  # nginx: [warn] "user" is not supported, ignored in D:\software\nginx-1.18.0/conf/nginx.conf:2
  user root;
  
  # 指定并发工作的进程数，可以配置具体数字，也可使用自动模式
  # worker_processes number | auto；
  # 如下配置：指定 4 个工作进程，此时会生成一个 master 进程和 4 个工作进程，总共五个
  #  因此，可以配置工作进程数为本机 CPU 核心数 n -1
  worker_processes 4;
  
  # 指定包含 nginx 主进程的 PID 数值的文件路径
  # 用途：进程管理、监控与诊断、方便进行自动化脚本控制
  pid logs/nginx.pid;
  
  # 指定错误日志的路径和日志级别
  # error_log [path] [debug | info | notice | warn | error | crit | alert | emerg] 
  # 其中debug级别的日志需要编译时使用--with-debug开启debug开关
  error_log  logs/error.log  info;
  # 此指令可以在（全局块 < http 块 < server 块 < location 块）中配置，下面简单介绍下区别：
  # 首先就是，配置在越低级的块中优先级越高；
  # 各个级别的配置块中设置的日志指令，将应用于各自所有下级；
  # server 块的配置，目的是不同的服务器配置不同的日志文件或日志级别；
  # location 块是最具体的配置级别，它可为特定的 URI 路径或模式设置专门的日志指令。
}

events块

events 块涉及的指令主要影响 Nginx 服务器与用户的网络连接。

常用到的设置包括：

  • 是否开启对多 worker process 下的网络连接进行序列化；
  • 是否允许同时接收多个网络连接；
  • 选取哪种事件驱动模型处理连接请求；
  • 每个worker process可以同时支持的最大连接数等。
# 当某一时刻只有一个网络连接到来时，【多个睡眠进程】会被同时唤醒，但只有【一个进程】可获得连接
# 如果【每次唤醒的进程数目太多】，会影响一部分系统性能
# 开启的时候，将会对多个 Nginx 进程接收连接进行序列化，【防止多个进程对连接的争抢】
# 有两个枚举值，默认是开启状态，因此可以不进行专门配置
# accept_mutex on | off;
accept_mutex on;
 
# multi_accept 配置，决定了当有多个工作进程监听同一个端口时，这些进程如何处理到来的新请求，语法：
# multi_accept on | off;
# off 时：当有新连接到来时，【所有等待的工作进程都会被唤醒】来接受连接，这样可以【提高处理效率】，尤其是在高并发的场景下
# on 时：当有新连接到来时，【只有一个工作进程数会被唤醒】，其他仍处于休眠状态 ，目的是【控制资源的使用】，避免在高并发情况下系统资源的过度消耗
# 如果在支持 kqueue 高效多路复用机制的操作系统（FreeBSD、macOS 等）上运行 Nginx，那么这条指令会被忽略
# 【默认是 off 状态】
multi_accept off;
 
# 指定使用哪种网络 IO 模型，影响到 Nginx 处理并发连接的能力，语法：
# use method
# 其中 method 可选择的内容有：
# 【Windows 默认 select】【Linux 默认 epoll】【FreeBSD 默认 kqueue】
# select：这是最基本的网络 IO 模型，适用于低并发场景，它在处理大量连接时可能会变得效率低下
# poll：相比 select，poll 能够处理更多的文件描述符，但在某些系统上性能提升有限
# kqueue：这是 FreeBSD 系统特有的高效网络 IO 模型，适用于高并发环境
# epoll：这是Linux 系统下的高效网络 IO 模型，同样适合处理大量并发连。
# rtsig：这是一种实时信号驱动的网络 IO 模型，它可以在不使用线程的情况下处理事件
# dev/poll：这是 Solaris 操作系统特有的网络 IO 模型，类似于 poll
# eventport：这是 NetBSD 和 GNU/Hurd 系统上的事件端口模型，用于处理网络事件
# /dev/poll：这是 macOS 系统上的网络 IO 模型，类似于 poll
use epoll
 
# 设置允许每一个 worker process 同时开启的最大连接数
# 当每个工作进程接受的连接数超过这个值时将不再接收连接，当所有的工作进程都接收满时，连接进入 logback，logback 满后连接被拒绝
worker_connections  1024;
# 注意：worker_connections * worker_process <= 系统的最大打开文件数
#       worker_connections <= 单个进程支持打开的最大文件数
# 下文继续详解...

http块

http 块是 Nginx 服务器配置中的重要部分，代理、缓存和日志定义等绝大多数的功能和第三方模块的配置都可以放在这个模块中。

http 块中可以包含自己的全局块，其中配置的指令包括文件引入、MIME-Type 定义、日志自定义、是否使用 sendfile 传输文件、连接超时时间、单连接请求数上限等。

http {
  # include 指令，用于包含其他的配置文件，提高配置可读性，避免单个配置文件过大，但必须符合配置规范
  # 下面的指令将 mime.types 包含进来，mime.types 和 nginx.conf 同级目录，不同级的话需要指定具体路径
  include  mime.types;
  # 浏览器可以显示的内容有 HTML、XML、GIF 及 Flash 等种类繁多的文本、媒体等资源，浏览器为区分这些资源，需要使用MIME Type
  # 换言之，MIME Type 是网络资源的媒体类型。Nginx 服务器作为 Web 服务器，必须能够识别前端请求的资源类型
  
  # default_type 指令默认类型，如果不加此指令【默认值为 text/plain】
  # 当 Web 程序无法识别对应文件 MIME 类型时，Nginx 会使用 default_type 指定的类型来告诉浏览器如何处理这个文件
  # application/octet-stream，这是一种通用的二进制流数据类型，通常用于未知或未指定类型的文件，浏览器不会直接打开未知文件，而是提示下载
  # 这样可以确保在没有明确指定 MIME 类型的情况下，用户不会被误导直接在浏览器中打开可能是执行代码的文件，更加安全
  # 此指令还可以在 http 块、server 块或者 location 块中进行配置
  default_type  application/octet-stream;
  
  # log_format 指令，用于定义日志格式，变量意义见后文表格
  # main 为定义的格式名称，这样 access_log 就可以直接使用这个变量了
  log_format  main '$remote_addr - $remote_user [$time_local] "$request" '
                  '$status $body_bytes_sent "$http_referer" '
                  '"$http_user_agent" "$http_x_forwarded_for"';
  # access_log 指令
  # 在全局块中，我们介绍过 errer_log 指令，其用于配置 Nginx 进程运行时的日志存放和级别
  # 此处所指的日志与常规的不同，它是指记录 Nginx 服务器【提供服务过程应答前端请求的日志】
  # buffer=size：设置内存缓存区的大小，不实时写入日志文件，可以减少磁盘 I/O 操作的次数
  # access_log path [format [buffer=size]]
  # 如果你要关闭 access_log，你可以使用下面的命令：access_log off;
  # 此指令可以在 http 块、server 块或者 location 块中进行设置
  access_log  logs/access.log  main;
  
  # sendfile 指令用于配置，是否使用 sendfile()系统调用来高效的传输文件数据，【特别适合于提供静态内容的场景】，语法：
  # sendfile  on | off;
  # 【默认值是 off】但在大多数提供静态内容的 Nginx 服务器上，建议将其设置为 on 以利用其带来的性能优势
  # sendfile()系统调用模式，允许内核直接将文件数据从磁盘传输到网络 socket，而非先将数据读取到用户空间缓冲区，再写入到 socket 的内核缓冲区
  # 这样可以减少数据在用户空间和内核空间之间的拷贝次数，从而显著提高静态文件传输的效率
  # 此指令可以在 http 块、server 块或者 location 块中进行配置
  sendfile  on;
  
  # sendfile_max_chunk 指令用于限制每个 sendfile()调用传输数据的最大块大小，语法：
  # sendfile_max_chunk size;
  # 此指令的最优值取决于具体的系统环境和网络条件
  # 在高速网络环境中，较大的块大小可能更有利于提高传输效率；而在低速网络或高延迟的环境中，较小的块大小可能更合适
  # 此外，还需要考虑到服务器的硬件资源，如 CPU 和内存的限制
  # size 值如果大于 0，Nginx 进程的每个 worker process 每次调用 sendfile()传输的数据量最大不能超过这个值
  # 如果设置为0，则无限制【默认值为 0】
  # 此指令可以在 http 块、server 块或 location 块中配置
  sendfile_max_chunk 128k;
  
  # 配置连接超时时间，与用户建立会话连接后，Nginx 服务器可以保持这些连接打开一段时间，语法：
  # keepalive_timeout timeout [header_timeout]
  # timeout：服务器端对连接的保持时间【默认值为 75s】针对的是整个 TCP 连接的生命周期
  # header_timeout：为可选项，是 timeout 的一个子集，在应答报文头部的 Keep-Alive 域设置超时时间，仅控制发送响应头之后的保持时间
  # 此指令可以在 http 块、server 块或 location 块中配置
  # 下面配置的含义是，在服务器端保持连接的时间设置为 120s，发给用户端的应答报文头部中 Keep-Alive 域的超时时间设置为 100s
  keepalive_timeout 120s 100s;
  
  # keepalive_requests 指令配置【单连接请求数上限】达到上限后自动关闭
  # 【默认值为100】这意味着在默认配置下，Nginx 会在处理了100个请求后关闭长连接
  # 此指令可以在 http 块、server 块或 location 块中配置
  keepalive_requests 100;
  
  # error_page 指令用于定义在出现特定错误时 Nginx 应该如何响应
  # 当发生错误时，如请求的资源不存在（404错误）或服务器内部错误（500错误），Nginx 可以使用 error_page 指令来定制错误响应
  # error_page <HTTP_Error> <value1> <value2>;
  # <HTTP_Error>：表示要处理的 HTTP 错误状态码，如 404、500 等
  # <value1>：表示当出现 <HTTP_Error> 错误时，Nginx 返回的错误页面的 uri
  # <value2>：可选参数，表示是否允许重新定义该错误页面。默认为“=”，即允许重新定义。如果设置为“=@”，则表示不允许重新定义
  error_page 404 /404.html;
  # http 块中的 error_page 允许你指定一个特定的页面作为错误响应，而 location快中的 return 则只能返回标准的错误响应代码和消息

  server {
    ...
  }

}

其中关于log_format的变量值定义:

参数名参数意义
$remote_addr客户端 IP
$remote_user远程客户端用户名，一般为：'-'
$time_local时间和时区
$request请求的 url 以及 method
$status响应状态码
$body_bytes_send响应客户端内容字节数
$http_referer记录用户从哪个链接跳转过来的
$http_user_agent用户所使用的代理，一般来时都是浏览器
$http_x_forwarded_for通过代理服务器来记录客户端的 IP

server块

server 块是 Nginx 配置文件中用于定义一个虚拟主机的核心指令。它允许在一台物理服务器上，通过不同的域名、端口或 IP 地址来运行多个独立的网站或应用。

你可以把 server 块理解为 Nginx 的“站点配置单元”。一个 Nginx 实例可以包含多个 server 块，每个块负责处理特定的一组请求。

以下是 server 块中常见的核心指令：

listen

  • 功能：指定服务器监听的 IP地址和端口
  • 常见用法：
http{
  ...

  server {
    listen 80; # 监听所有 IPv4 地址的 80 端口。

    listen 443 ssl; # 监听 443 端口，并启用 SSL（用于 HTTPS）。

    listen [::]:80; # 监听所有 IPv6 地址的 80 端口。

    listen 127.0.0.1:8080; # 只监听本地回环地址的 8080 端口。
  
    # 以上四选一
  }

  ...
}

server_name

  • 功能：定义此 server 块响应的域名（主机头）。Nginx 会根据客户端请求中的 Host 头部来匹配到正确的 server 块。

  • 匹配优先级（从高到低）：

    1. 精确名称：server_name www.example.com;

    2. 以通配符 * 开头：server_name *.example.com;（匹配 a.example.com，但不匹配 a.b.example.com）

    3. 以通配符 * 结尾：server_name www.example.*;

    4. 正则表达式（以 ~ 开头）：server_name ~^(?<subdomain>.+)\.example\.com$;（可以使用捕获组）

  • 特殊值：

    • ""（空字符串）：匹配没有 Host 头部的请求。

    • _（下划线）：一个无效的域名，通常用作“捕获所有”或默认服务器。

root

  • 功能：设置请求的根目录。当请求 /css/style.css 时，Nginx 会去 root 指定的目录下寻找该文件。

  • 示例：root /var/www/example;，那么请求 /index.html 将对应服务器上的 /var/www/example/index.html 文件。

index

  • 功能：定义当请求以 / 结尾时，Nginx 尝试查找的默认索引文件。

  • 示例：index index.html index.htm index.php;

location

  • 功能：这是 server 块中最重要的指令之一。它用于根据请求的 URI（路径）来进一步配置如何处理请求。

  • 语法：location [修饰符] 匹配模式 { ... }

  • 修饰符：

    • =：精确匹配。location = /logo.png { ... } 只匹配 /logo.png。

    • ~：正则表达式匹配（区分大小写）。location ~ \.php$ { ... } 匹配所有以 .php 结尾的请求。

    • ~*：正则表达式匹配（不区分大小写）。location ~* \.(gif|jpg|jpeg)$ { ... }匹配图片文件。

    • ^~：如果该前缀是最佳匹配，则停止搜索正则表达式。

    • （无）：前缀匹配。location /admin/ { ... } 匹配所有以 /admin/ 开头的请求。

  • 示例

    server {
  listen 80;
  server_name example.com;
  root /var/www/example;

  # 静态文件处理
  location /static/ {
    alias /path/to/your/django/project/static/;
    # 缓存设置
    expires 30d;
    add_header Cache-Control "public, immutable";
    access_log off;
  }
  
  # 媒体文件处理
  location /media/ {
    alias /path/to/your/django/project/media/;
    expires 30d;
    add_header Cache-Control "public";
    access_log off;
  }
  
  # 将所有动态请求代理到 Gunicorn
  location / {
    proxy_pass http://127.0.0.1:8000;  # Gunicorn 默认端口
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
      
    # 超时设置
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
  }
  
  # 禁止访问隐藏文件
  location ~ /\. {
      deny all;
      access_log off;
      log_not_found off;
  }
}

默认 Server 块

当没有 server_name 能匹配请求的 Host 头时，Nginx 会使用监听该端口的默认服务器。

  • 定义默认服务器的方法是在 listen 指令后加上 default_server 参数。

  • 如果没有显式指定，第一个监听该端口的 server 块将成为默认服务器。

# 显式指定默认服务器，用于处理未知域名的请求
server {
    listen 80 default_server;
    server_name _;
    return 444; # 直接关闭连接，或者返回一个自定义错误页面
}

完整的 Server 块配置

下面是一个结合了上述指令的、功能完整的 server 块示例，用于一个使用 Django（Python）框架的网站。

# /etc/nginx/sites-available/your_django_site

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    
    # 根目录指向 Django 项目
    root /var/www/example;
    
    # 允许上传大文件
    client_max_body_size 50M;
    
    # 静态文件处理
    location /static/ {
        alias /var/www/example/staticfiles/;
        expires 30d;
        access_log off;
    }
    
    # 媒体文件处理
    location /media/ {
        alias /var/www/example/media/;
        expires 30d;
        access_log off;
    }
    
    # 所有其他请求交给 Django
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    # 禁止访问隐藏文件
    location ~ /\. {
        deny all;
    }
}

对应的 Django配置

ALLOWED_HOSTS = ['yourdomain.com', 'www.yourdomain.com', 'localhost']

STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')

MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

豫ICP备2024103624号 | Eric Miller | Released under the MIT License.

Copyright © 2024 Eric Miller