Nginx模块架构与生命周期

Nginx 模块遵循统一的架构模式，生命周期由核心框架驱动，模块通过回调参与各阶段初始化与资源清理。

模块类型

6 种模块类型

核心模块接口

typedef struct {
    const char      *name;          // 模块名称
    void           *(*create_conf)(ngx_cycle_t *cycle);  // 创建配置
    char           *(*init_conf)(ngx_cycle_t *cycle, void *conf);  // 初始化配置
} ngx_core_module_t;

模块生命周期

7 个生命周期回调

ngx_module_t ngx_http_my_module = {
    NGX_MODULE_V1,
    &ngx_http_my_module_ctx,
    ngx_http_my_commands,
    NGX_HTTP_MODULE,
    ngx_http_my_init_master,      // 1. master 进程初始化
    ngx_http_my_init_module,      // 2. 模块初始化（配置解析后）
    ngx_http_my_init_process,     // 3. worker 进程初始化
    NULL,                         // 4. 初始化线程
    NULL,                         // 5. 退出线程
    ngx_http_my_exit_process,     // 6. worker 进程退出
    ngx_http_my_exit_master,      // 7. master 进程退出
    NGX_MODULE_V1_PADDING
};

生命周期执行流程

master 进程启动
  → ngx_http_my_init_master()        // 创建 master 级资源

configure 解析完成
  → ngx_http_my_init_module()        // 模块级初始化

fork worker 进程
  → ngx_http_my_init_process()       // 创建 worker 级资源（连接池、共享内存）

处理请求...

worker 进程退出
  → ngx_http_my_exit_process()       // 清理 worker 资源

master 进程退出
  → ngx_http_my_exit_master()        // 清理 master 资源

回调函数详解

init_master

static ngx_int_t
ngx_http_my_init_master(ngx_log_t *log)
{
    // 创建 master 级共享资源
    // 如：共享内存、互斥锁
    return NGX_OK;
}

init_module

static ngx_int_t
ngx_http_my_init_module(ngx_cycle_t *cycle)
{
    ngx_http_my_main_conf_t  *mcf;

    mcf = (ngx_http_my_main_conf_t *) ngx_http_cycle_get_module_main_conf(cycle, ngx_http_my_module);
    if (mcf == NULL) {
        return NGX_OK;  // 未配置该模块，跳过
    }

    // 初始化模块数据结构
    // 如：初始化哈希表、预计算数据
    return NGX_OK;
}

init_process

static ngx_int_t
ngx_http_my_init_process(ngx_cycle_t *cycle)
{
    // 每个 worker 进程执行一次
    // 创建进程级资源
    // 如：连接上游、初始化定时器
    return NGX_OK;
}

exit_process

static void
ngx_http_my_exit_process(ngx_cycle_t *cycle)
{
    // worker 退出前清理
    // 如：关闭连接、刷新缓存
}

模块间依赖

依赖声明

// 模块声明依赖关系
NGX_MODULE_V1,
...

// 获取其他模块配置
ngx_http_core_main_conf_t *cmcf;
cmcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_core_module);

// 访问 upstream 模块
ngx_http_upstream_main_conf_t *umcf;
umcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_upstream_module);

模块加载顺序

核心模块（core）
  → 事件模块（events）
  → HTTP 核心模块（http_core）
  → HTTP 过滤器模块（filter）
  → HTTP 内容模块（content）

模块加载顺序由 objs/ngx_modules.c 中的数组顺序决定，过滤器模块必须在内容模块之前。

模块上下文

HTTP 模块上下文

static ngx_http_module_t ngx_http_my_module_ctx = {
    ngx_http_my_preconfiguration,   // 配置解析前
    ngx_http_my_postconfiguration,  // 配置解析后，注册 handler
    NULL,                           // 创建 main 配置
    NULL,                           // 初始化 main 配置
    NULL,                           // 创建 server 配置
    NULL,                           // 合并 server 配置
    NULL,                           // 创建 location 配置
    NULL                            // 合并 location 配置
};

要点总结

• Nginx 模块分 6 种类型，HTTP 模块最常见，通过 ngx_module_t 统一定义
• 生命周期包含 7 个回调：init_master/init_module/init_process/exit_process/exit_master
• init_module 在配置解析后执行，init_process 在每个 worker 启动时执行
• 模块通过 ngx_http_conf_get_module_main_conf 获取其他模块配置
• 模块加载顺序由 ngx_modules.c 数组决定，过滤器需在内容模块前