Nginx 开发笔记

添加第三方模块

  • 添加config脚本

    config是一个shell脚本,里面定义编译模块时需要使用的环境变量。 假设我们需要编译一个第三方的Http模块,则需要定义如下三个环境变量:

ngx_addon_name; //模块名称,例如ngx_http_test_module  
HTTP_MODULES; //模块编译顺序。一般是添加在核心模块之后"$HTTP_MODULES ngx_http_test_module";  
NGX_ADDON_SRCS; //模块代码路径. 例如"$NGX_ADDON_SRCS xxxxx/ngx_http_test_module.c"  
  • 调用configure

    调用configure --add-path=xxxx(模块目录路径). configure会判断模块目录里面是否存在config脚本,如果有则调用config。

  • 执行build

    configure执行成功之后,会生成Makefile。 执行make/make install 会生成最新的nginx可执行程序。

  • 自定义调整

    默认情况下,自己开发的模块调用顺序都在nginx核心模块之后。 安装上面的步骤,会将自定义的模块放在核心模块之后调用。 如果需要放在核心模块之前调用,那么通过configure生成Makefile之后,不再执行make。修改objs/ngx_modules.c文件,调整里面的模块顺序。而后在执行make/make install.


常用结构体说明


ngx_ module_ t

typedef struct ngx_module_s      ngx_module_t;  
struct ngx_module_s {  
    /* 下面的ctx_index、index、spare0、spare1、spare2、spare3、version变量不需要在定义时赋值,可以用Nginx准备好的宏NGX_MODULE_V1来定义,它已经定义好了这7个值。  
    #define NGX_MODULE_V1          0, 0, 0, 0, 0, 0, 1  
    对于一类模块(由下面的type成员决定类别)而言,ctx_index表示当前模块在这类模块中的序号。这个成员常常是由管理这类模块的一个Nginx核心模块设置的,对于所有的HTTP模块而言,ctx_index是由核心模块ngx_http_module设置的。ctx_index非常重要,Nginx的模块化设计非常依赖于各个模块的顺序,它们既用于表达优先级,也用于表明每个模块的位置,借以帮助Nginx框架快速获得某个模块的数据*/  

    ngx_uint_t            ctx_index;  

    /*index表示当前模块在ngx_modules数组中的序号。注意,ctx_index表示的是当前模块在一类模块中的序号,而index表示当前模块在所有模块中的序号,它同样关键。Nginx启动时会根据ngx_modules数组设置各模块的index值。例如:  
ngx_max_module = 0;  
for (i = 0; ngx_modules[i]; i++) {  
    ngx_modules[i]->index = ngx_max_module++;  
}  
*/  
    ngx_uint_t            index;  

    //spare系列的保留变量,暂未使用  
    ngx_uint_t            spare0;  
    ngx_uint_t            spare1;  
    ngx_uint_t            spare2;  
    ngx_uint_t            spare3;  
    //模块的版本,便于将来的扩展。目前只有一种,默认为1  
    ngx_uint_t            version;  

    /*ctx用于指向一类模块的上下文结构体,Nginx模块有许多种类,不同类模块之间的功能差别很大。例如,事件类型的模块主要处理I/O事件相关的功能,HTTP类型的模块主要处理HTTP应用层的功能。这样,每个模块都有了自己的特性,而ctx将会指向特定类型模块的公共接口。例如,在HTTP模块中,ctx需要指向ngx_http_module_t结构体*/  
    void                 *ctx;  

    //commands将处理nginx.conf中的配置项  
    ngx_command_t        *commands;  

    /*type表示该模块的类型,它与ctx指针是紧密相关的。在官方Nginx中,它的取值范围是以下5种:NGX_HTTP_MODULE、NGX_CORE_MODULE、NGX_CONF_MODULE、NGX_EVENT_MODULE、NGX_MAIL_MODULE。实际上,还可以自定义新的模块类型*/  
    ngx_uint_t            type;  

    /*在Nginx的启动、停止过程中,以下7个函数指针表示有7个执行点会分别调用这7种方法。对于任一个方法而言,如果不需要Nginx在某个时刻执行它,那么简单地把它设为NULL空指针即可*/  

    /*虽然从字面上理解应当在master进程启动时回调init_master,但到目前为止,框架代码从来不会调用它,因此,可将init_master设为NULL */  
    ngx_int_t           (*init_master)(ngx_log_t *log);  
    /*init_module回调方法在初始化所有模块时被调用。在master/worker模式下,这个阶段将在启动worker子进程前完成*/  
    ngx_int_t           (*init_module)(ngx_cycle_t *cycle);  
    /* init_process回调方法在正常服务前被调用。在master/worker模式下,多个worker子进程已经产生,在每个worker进程的初始化过程会调用所有模块的init_process函数*/  
    ngx_int_t           (*init_process)(ngx_cycle_t *cycle);  
    /* 由于Nginx暂不支持多线程模式,所以init_thread在框架代码中没有被调用过,设为NULL*/  
    ngx_int_t           (*init_thread)(ngx_cycle_t *cycle);  
    // 同上,exit_thread也不支持,设为NULL  
    void                (*exit_thread)(ngx_cycle_t *cycle);  
    /* exit_process回调方法在服务停止前调用。在master/worker模式下,worker进程会在退出前调用它*/  
    void                (*exit_process)(ngx_cycle_t *cycle);  
    // exit_master回调方法将在master进程退出前被调用  
    void                (*exit_master)(ngx_cycle_t *cycle);  

    /*以下8个spare_hook变量也是保留字段,目前没有使用,但可用Nginx提供的NGX_MODULE_V1_PADDING宏来填充。看一下该宏的定义:#define NGX_MODULE_V1_PADDING  0, 0, 0, 0, 0, 0, 0, 0*/  
    uintptr_t             spare_hook0;  
    uintptr_t             spare_hook1;  
    uintptr_t             spare_hook2;  
    uintptr_t             spare_hook3;  
    uintptr_t             spare_hook4;  
    uintptr_t             spare_hook5;  
    uintptr_t             spare_hook6;  
    uintptr_t             spare_hook7;  
}; 


ngx_ http_ module_ t

//HTTP框架在读取,重载配置文件时定义了由ngx_http_module_t接口描述的8个阶段
typedef struct {  
    ngx_int_t   (*preconfiguration)(ngx_conf_t *cf);  //解析配置文件前调用
    ngx_int_t   (*postconfiguration)(ngx_conf_t *cf); //完成配置文件解析后调用

    void       *(*create_main_conf)(ngx_conf_t *cf);  //当需要创建数据结构用户存储main级别的全局配置项时候调用
    char       *(*init_main_conf)(ngx_conf_t *cf, void *conf); //初始化main级别配置项

    void       *(*create_srv_conf)(ngx_conf_t *cf); //当需要创建数据结构用户存储srv级别的全局配置项时候调用
    char       *(*merge_srv_conf)(ngx_conf_t *cf, void *prev, void *conf); //srv覆盖策略

    void       *(*create_loc_conf)(ngx_conf_t *cf); //当需要创建数据结构用户存储loc级别的全局配置项时候调用
    char       *(*merge_loc_conf)(ngx_conf_t *cf, void *prev, void *conf); //loc覆盖策略
} ngx_http_module_t;


ngx_ command_ s
struct ngx_command_s  
{ 
    ngx_str_t name; //配置项名称 
    ngx_uint_t type;  //type决定这个配置项可以在哪些块(如http、server、location、if、upstream块等)中出现,以及可以携带的参数类型和个数等。type可以取多个值,例如:NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1。
    char*(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf); //set回调方法
    ngx_uint_t conf;  //conf用于指示配置项所处内存的相对偏移位置,仅在type中没有设置NGX_DIRECT_CONF和NGX_MAIN_CONF时才会生效。对于HTTP模块,conf是必须要设置的。
    ngx_uint_t offset; //offset表示当前配置项在整个存储配置项的结构体中的偏移位置(以字节(Byte)为单位)。举个例子,在32位机器上,int(整型)类型长度是4字节
    void *post; //如果自定义了配置项的回调方法,那么post指针的用途完全由用户来定义。如果不使用它,那么随意设为NULL即可。如果想将一些数据结构或者方法的指针传过来,那么使用post也可以。
};