Nginx 配置解析

概述

在上一篇文章《 Nginx 启动初始化过程》简单介绍了 Nginx 启动的过程，并分析了其启动过程的源码。在启动过程中有一个步骤非常重要，就是调用函数 ngx_init_cycle()，该函数的调用为配置解析提供了接口。配置解析接口大概可分为两个阶段：准备数据阶段和配置解析阶段；

准备数据阶段包括：

  • 准备内存；

  • 准备错误日志；

  • 准备所需数据结构；

配置解析阶段是调用函数：

      
    if (ngx_conf_param(&conf) != NGX_CONF_OK) {  
        environ = senv;  
        ngx_destroy_cycle_pools(&conf);  
        return NULL;  
    }  
  
    if (ngx_conf_parse(&conf, &cycle->conf_file) != NGX_CONF_OK) {  
        environ = senv;  
        ngx_destroy_cycle_pools(&conf);  
        return NULL;  
    }

配置解析

ngx_conf_t 结构体

该结构体用于 Nginx 在解析配置文件时描述每个指令的属性，也是Nginx 程序中非常重要的一个数据结构，其定义于文件：src/core/ngx_conf_file.h

配置文件信息 conf_file

conf_file 是存放 Nginx 配置文件的相关信息。ngx_conf_file_t 结构体的定义如下：

配置上下文 ctx

Nginx 的配置文件是分块配置的，常见的有http 块、server 块、location 块以及upsteam 块和 mail 块等。每一个这样的配置块代表一个作用域。高一级配置块的作用域包含了多个低一级配置块的作用域，也就是有作用域嵌套的现象。这样，配置文件中的许多指令都会同时包含在多个作用域内。比如，http 块中的指令都可能同时处于http 块、server 块和location 块等三层作用域内。

在 Nginx 程序解析配置文件时，每一条指令都应该记录自己所属的作用域范围，而配置文件上下文ctx 变量就是用来存放当前指令所属的作用域的。在Nginx 配置文件的各种配置块中，http 块可以包含子配置块，这在存储结构上比较复杂。

指令类型 type

Nginx 程序中的不同的指令类型以宏的形式定义在不同的源码头文件中，指令类型是core 模块类型的定义在文件：src/core/ngx_conf_file.h

这些是 core 类型模块支持的指令类型。其中的 NGX_DIRECT_CONF类指令在 Nginx 程序进入配置解析函数之前已经初始化完成，所以在进入配置解析函数之后可以将它们直接解析并存储到实际的数据结构中，从配置文件的结构上来看，它们一般指的就是那些游离于配置块之外、处于配置文件全局块部分的指令。NGX_MAIN_CONF 类指令包括event、http、mail、upstream 等可以形成配置块的指令，它们没有自己的初始化函数。Nginx 程序在解析配置文件时如果遇到 NGX_MAIN_CONF 类指令，将转入对下一级指令的解析。 以下是 event 类型模块支持的指令类型。

以下是 http 类型模块支持的指令类型，其定义在文件：src/http/ngx_http_config.h

通用模块配置解析

配置解析模块在 src/core/ngx_conf_file.c 中实现。模块提供的接口函数主要是ngx_conf_parse。另外，模块提供另一个单独的接口ngx_conf_param，用来解析命令行传递的配置，这个接口也是对ngx_conf_parse 的包装。首先看下配置解析函数 ngx_conf_parse，其定义如下：

从配置解析函数的源码可以看出，该函数分为两个阶段：语法分析和 指令解析。语法分析由 ngx_conf_read_token()函数完成。指令解析有两种方式：一种是Nginx 内建的指令解析机制；另一种是自定义的指令解析机制。自定义指令解析源码如下所示：

而Nginx 内置解析机制有函数ngx_conf_handler() 实现。其定义如下：

HTTP 模块配置解析

这里主要是结构体 ngx_command_t ，我们在文章 《Nginx 模块开发》 对该结构体作了介绍，其定义如下：

若在上面的通用配置解析中，定义了如下的 http 配置项结构，则回调用http 配置项，并对该http 配置项进行解析。此时，解析的是http block 块设置。

http 是作为一个 core 模块被 nginx 通用解析过程解析的，其核心就是http{} 块指令回调，它完成了http 解析的整个功能，从初始化到计算配置结果。http{} 块指令的流程是：

  • 创建并初始化上下文结构；

  • 调用通用模块配置解析流程解析；

  • 根据解析结果进行配置项合并处理；

创建并初始化上下文结构

当 Nginx 检查到 http{…} 配置项时，HTTP 配置模型就会启动，则会建立一个ngx_http_conf_ctx_t 结构，该结构定义在文件中：src/http/ngx_http_config.h

此时，HTTP 框架为所有 HTTP 模块建立 3 个数组，分别存放所有 HTTP 模块的create_main_conf、create_srv_conf 、create_loc_conf 方法返回的地址指针。ngx_http_conf_ctx_t 结构的三个成员分别指向这 3 个数组。例如下面的例子是设置 create_main_conf、create_srv_conf 、create_loc_conf 返回的地址。

调用通用模块配置解析流程解析

从源码 src/http/ngx_http.c 中可以看到，http 块的配置解析是调用通用模块的配置解析函数，其实现如下：

根据解析结果进行配置项合并处理

HTTP 配置解析流程

从上面的分析中可以总结出 HTTP 配置解析的流程如下：

  • Nginx 进程进入主循环，在主循环中调用配置解析器解析配置文件nginx.conf;

  • 在配置文件中遇到 http{} 块配置，则 HTTP 框架开始初始化并启动，其由函数 ngx_http_block() 实现；

  • HTTP 框架初始化所有 HTTP 模块的序列号，并创建 3 个类型为 ngx_http_conf_ctx_t 结构的数组用于存储所有HTTP 模块的create_main_conf、create_srv_conf、create_loc_conf方法返回的指针地址；

  • 调用每个 HTTP 模块的 preconfiguration 方法；

  • HTTP 框架调用函数 ngx_conf_parse() 开始循环解析配置文件 *nginx.conf *中的http{}块里面的所有配置项；

  • HTTP 框架处理完毕 http{} 配置项，根据解析配置项的结果，必要时进行配置项合并处理；

  • 继续处理其他 http{} 块之外的配置项，直到配置文件解析器处理完所有配置项后通知Nginx 主循环配置项解析完毕。此时，Nginx 才会启动Web 服务器；

合并配置项

HTTP 框架解析完毕 http{} 块配置项时，会根据解析的结果进行合并配置项操作，即合并 http{}、server{}、location{} 不同块下各HTTP 模块生成的存放配置项的结构体。其合并过程如下所示：

  • 若 HTTP 模块实现了 merge_srv_conf 方法，则将 http{} 块下create_srv_conf 生成的结构体与遍历每一个 server{}配置块下的结构体进行merge_srv_conf 操作；

  • 若 HTTP 模块实现了 merge_loc_conf 方法，则将 http{} 块下create_loc_conf 生成的结构体与嵌套每一个server{} 配置块下的结构体进行merge_loc_conf 操作；

  • 若 HTTP 模块实现了 merge_loc_conf 方法，则将server{} 块下create_loc_conf 生成的结构体与嵌套每一个location{}配置块下的结构体进行merge_loc_conf 操作；

  • 若 HTTP 模块实现了 merge_loc_conf 方法，则将location{} 块下create_loc_conf 生成的结构体与嵌套每一个location{}配置块下的结构体进行merge_loc_conf 操作；

以下是合并配置项操作的源码实现：

处理自定义的配置

在文章中 《Nginx 模块开发》，我们给出了“Hello World” 的开发例子，在这个开发例子中，我们定义了自己的配置项，配置项名称的结构体定义如下：

为了处理我们定义的配置项结构，因此，我们把 ngx_command_t 结构体定义如下：

处理方法 ngx_http_hello_string 和ngx_http_hello_counter 定义如下：

error 日志

Nginx 日志模块为其他模块提供了基本的日志记录功能，日志模块定义如下：src/​core/​ngx_log.c

Nginx 日志模块对于支持可变参数提供了三个接口，这三个接口定义在文件：src/​core/​ngx_log.h

Nginx 日志模块记录日志的核心功能是由ngx_log_error_core 方法实现，ngx_log_error 和ngx_log_debug 宏定义只是对其进行简单的封装，一般情况下日志调用只需要这两个宏定义。 ngx_log_error 和 ngx_log_debug 宏定义都包括参数 level、log、err、fmt，下面分别对这些参数进行简单的介绍：

level 参数：对于 ngx_log_error 宏来说，level 表示当前日志的级别，其取值如下所示：

使用 ngx_log_error 宏记录日志时，若传入的level 级别小于或等于log 参数中的日志级别，就会输出日志内容，否则忽略该日志。 在使用 ngx_log_debug 宏时，参数level 不同于ngx_log_error 宏的level 参数，它表达的不是日志级别，而是日志类型。ngx_log_debug 宏记录日志时必须是NGX_LOG_DEBUG 调试级别，这里的level 取值如下：

当 HTTP 模块调用ngx_log_debug 宏记录日志时，传入的level 参数是NGX_LOG_DEBUG_HTTP，此时，若log 参数不属于HTTP 模块，若使用event 事件模块的log，则不会输出任何日志。

log 参数：log 参数的结构定义如下：src/core/ngx_log.h；从其结构中可以知道，若只想把相应的信息记录到日志文件中，则不需要关系参数 log 的构造。

err 参数：err 参数是错误编码，一般是执行系统调用失败后取得的errno 参数。当err 不为 0 时，Nginx 日志模块将会在正常日志输出这个错误编码以及其对应的字符串形成的错误信息。

fmt 参数：fmt 参数类似于C 语言中的printf 函数的输出格式。

参考资料：

《深入理解 Nginx 》

《nginx 启动阶段》

《Nginx高性能Web服务器详解》

PreviousNginx 启动初始化过程NextNginx 中的 upstream 与 subrequest 机制

Last updated

Was this helpful?