Nginx基础教程（28）Nginx模块体系之源码分析：别再说看不懂Nginx模块了！源码里竟藏了这些秘密

原创于 2025-11-28 09:12:03 发布 · 268 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#nginx #xcode #运维

Nginx基础教程专栏收录该内容

30 篇文章

订阅专栏

一行行Nginx源码背后，隐藏着百万程序员梦寐以求的高性能秘诀。

01 初探Nginx：源码深处的秘密花园

Nginx的诞生，源自一个程序员对高性能的执着追求。由俄罗斯程序员Igor Sysoev在2002年创建，Nginx如今已成为全球顶级互联网公司的首选，市场份额高达33.3%。

但究竟是什么让Nginx如此高效？答案就隐藏在其源码中。

与传统的多进程/多线程模型不同，Nginx使用单个线程处理数千个并发连接，通过epoll（Linux）、kqueue（BSD）等系统调用实现高效并发处理。

这种设计使得Nginx在相同硬件条件下能够处理更多请求，内存占用也更低——空闲状态下仅需几MB内存。

Nginx的高度模块化架构也是其成功的关键因素。它可以在不修改核心的前提下增加任意功能，自2004年发布至今，已经拥有百余个官方及非官方的功能模块。

02 源码架构：Nginx的骨架之美

打开Nginx源代码目录，你会发现其布局清晰而有条理，体现了优秀的设计理念：

- auto/          # 构建脚本
- src/           # 主要源代码
  - core/        # 基本类型和函数 - 字符串、数组、日志、池等
  - event/       # 事件核心
    - modules/   # 事件通知模块：epoll、kqueue、select等
  - http/        # 核心HTTP模块和通用代码
    - modules/   # 其他HTTP模块
    - v2/        # HTTP/2
  - mail/        # 邮件代理服务器和模块
  - os/          # 平台特定代码
    - unix/
    - win32/
  - stream/      # 流模块
  - misc/        # 杂项

每个目录都有明确的职责划分，核心数据结构与协议实现分离，模块之间通过清晰的接口进行通信。这种结构不仅便于代码维护，也为扩展开发提供了良好基础。

在编码层面，Nginx有着自己的一套规范。每个源文件都必须以正确的#include指令开头：

所有文件都需要#include <ngx_config.h>和#include <ngx_core.h>
HTTP相关代码需要额外包含#include <ngx_http.h>
邮件和流代码则分别包含对应的头文件

这种一致性确保了代码的可移植性和可维护性。

03 模块分类：Nginx的大家族

Nginx官方将模块按功能分为5类，它们各司其职，共同构建了强大的Nginx生态系统。

核心模块：Nginx的心脏

核心模块是Nginx中最重要的一类模块，包含ngx_core_module、ngx_http_module、ngx_events_module等。

它们是Nginx正常运行的基础，提供错误日志记录、配置文件解析、事件驱动机制、进程管理等核心功能。

事件模块：高并发的发动机

事件模块定义了一系列可以运行在不同操作系统、不同内核版本的事件驱动模块。Nginx的事件处理框架完美地支持各类操作系统提供的事件驱动模型，包括epoll、poll、select、kqueue、eventport等。

事件模块是Nginx高并发能力的核心，它负责监听和处理所有网络事件，确保在少量线程下能够处理大量并发连接。

HTTP模块：Web服务的多面手

与处理HTTP请求密切相关，HTTP模块包含的模块数量远多于其他类型的模块。Nginx的大量功能是通过HTTP模块实现的。

从端口配置、网页编码设置到SSL支持、反向代理，HTTP模块涵盖了Web服务的方方面面。

邮件模块：不为人知的能手

邮件服务模块主要用于支持Nginx的邮件服务，包括对POP3协议、IMAP协议和SMTP协议的支持。虽然不如HTTP模块知名，但邮件模块让Nginx成为了一个全能的代理服务器。

配置模块：一切配置的基石

配置模块是其他模块的基础，因为其他模块在生效前都需要依赖配置模块处理配置指令并完成各自的准备工作。

配置模块指导所有模块按照配置文件提供功能，是Nginx可配置、可定制、可扩展的基础。

04 模块接口：Nginx的通用语言

虽然Nginx模块数量众多、功能复杂多样，但并没有给开发人员带来多少困扰，因为所有的模块都遵循同一个ngx_module_t接口设计规范。

ngx_module_s结构体是Nginx源码中非常重要的一个结构体，它包含了一个模块的基本信息。

更为巧妙的是，init_master、init_module、init_process等7个钩子函数让每个模块能够在Master进程和Worker进程启动与退出、初始化等阶段嵌入各自的逻辑，这大大提高了模块实现的灵活性。

ngx_module_t中有一个类型为void*的ctx成员，其定义了该模块的公共接口。它是ngx_module_t和各类模块的纽带。

对于核心模块，ctx变量指向的是名为ngx_core_module_t的结构体。而对于HTTP模块，ctx变量指向的是名为ngx_http_module_t的结构体。

这种设计兼顾统一化与差异化思想，以最简单、实用的方式实现了模块的多态性。

05 进程模型：Master与Worker的二人转

Nginx采用单Master多Worker的进程模型，这是其高稳定性和高并发能力的核心。

Master进程就像一位经验丰富的管理者，以root权限运行，负责管理Worker进程，监听工作进程状态。

当工作进程异常退出时，Master进程会立即重启新进程，确保服务不中断。

Worker进程则是真正的执行者，以低权限用户（如nginx）运行，增强了安全性。它们负责处理客户端请求，使用异步非阻塞I/O模型。

Worker进程相互独立，无共享状态，避免了进程间通信开销。

这种架构的优势显而易见：单个Worker进程崩溃不会影响整体服务，Master进程会很快启动新的Worker进程。

同时，低权限运行的Worker进程减小了安全风险。

06 事件驱动：异步非阻塞的魔法

Nginx高性能的核心在于其事件驱动模型。与为每个连接创建线程或进程的传统方法不同，Nginx使用单个线程处理多个连接，通过事件循环监听Socket事件。

其工作流程如下：

Worker进程通过epoll/kqueue监听所有连接的事件。
当某个连接有数据可读时，Worker处理该请求。
如果I/O操作（如读写磁盘或网络）不能立即完成，Worker不会阻塞等待，而是继续处理其他连接。
当异步操作完成时，会触发事件，Worker回来继续处理该请求。

这种异步非阻塞的设计避免了线程/进程切换的开销，使Nginx能够以极少资源处理大量并发连接。

Nginx的事件驱动模型由事件收集器、事件发送器和事件处理器三部分基本单元组成。

其中，事件收集器负责收集worker进程的各种IO请求，事件发送器负责将IO事件发送到事件处理器，而事件处理器负责各种事件的响应工作。

07 实战开发：亲手编写Nginx模块

理论说了这么多，让我们亲自动手，开发一个简单的"Hello World"处理程序模块，它在访问特定URL时返回问候语。

第一步：定义模块结构

每个Nginx模块都需要定义ngx_module_t结构，这是模块的"身份证"：

#include <ngx_config.h>
#include <ngx_core.h>
#include <ngx_http.h>

static ngx_int_t ngx_http_hello_world_handler(ngx_http_request_t *r);

// 指令定义
static ngx_command_t ngx_http_hello_world_commands[] = {
    {
        ngx_string("hello_world"),          // 指令名
        NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS,  // 使用位置和参数限制
        ngx_http_hello_world_set,           // 设置函数
        NGX_HTTP_LOC_CONF_OFFSET,           // 保存位置
        0,                                  // 偏移量
        NULL                                // 后处理函数
    },
    ngx_null_command                        // 结束标记
};

// 模块上下文
static ngx_http_module_t ngx_http_hello_world_module_ctx = {
    NULL,                                  // 前置配置
    NULL,                                  // 创建主配置
    NULL,                                  // 初始化主配置
    NULL,                                  // 创建服务器配置
    NULL,                                  // 合并服务器配置
    NULL,                                  // 创建位置配置
    NULL,                                  // 合并位置配置
};

第二步：实现模块核心功能

接下来，我们需要实现模块的核心处理函数：

// 处理hello_world指令的函数
static char *ngx_http_hello_world_set(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
    ngx_http_core_loc_conf_t *clcf;
    
    clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
    clcf->handler = ngx_http_hello_world_handler;
    
    return NGX_CONF_OK;
}

// 请求处理函数
static ngx_int_t ngx_http_hello_world_handler(ngx_http_request_t *r)
{
    ngx_int_t    rc;
    ngx_buf_t   *b;
    ngx_chain_t  out;
    
    // 只支持GET和HEAD方法
    if (!(r->method & (NGX_HTTP_GET|NGX_HTTP_HEAD))) {
        return NGX_HTTP_NOT_ALLOWED;
    }
    
    // 丢弃请求体
    rc = ngx_http_discard_request_body(r);
    if (rc != NGX_OK) {
        return rc;
    }
    
    // 设置响应头
    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = sizeof("Hello World!") - 1;
    
    ngx_http_send_header(r);
    
    // 对于HEAD请求，只发送头部
    if (r->method == NGX_HTTP_HEAD) {
        return NGX_OK;
    }
    
    // 分配缓冲区
    b = ngx_pcalloc(r->pool, sizeof(ngx_buf_t));
    if (b == NULL) {
        return NGX_HTTP_INTERNAL_SERVER_ERROR;
    }
    
    // 设置响应体
    out.buf = b;
    out.next = NULL;
    
    b->pos = (u_char *) "Hello World!";
    b->last = b->pos + sizeof("Hello World!") - 1;
    b->memory = 1;
    b->last_buf = 1;
    
    // 发送响应
    return ngx_http_output_filter(r, &out);
}

第三步：完成模块定义

最后，我们需要完善模块定义：

// 模块定义
ngx_module_t ngx_http_hello_world_module = {
    NGX_MODULE_V1,                        // 模块标准字段
    &ngx_http_hello_world_module_ctx,     // 模块上下文
    ngx_http_hello_world_commands,        // 模块指令
    NGX_HTTP_MODULE,                      // 模块类型
    NULL,                                 // 初始化Master进程
    NULL,                                 // 初始化模块
    NULL,                                 // 初始化进程
    NULL,                                 // 初始化线程
    NULL,                                 // 退出线程
    NULL,                                 // 退出进程
    NULL,                                 // 退出Master进程
    NGX_MODULE_V1_PADDING
};

第四步：编译和测试

要编译这个模块，我们需要创建一个config文件：

ngx_addon_name=ngx_http_hello_world_module
HTTP_MODULES="$HTTP_MODULES ngx_http_hello_world_module"
NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_hello_world_module.c"

然后在Nginx配置中使用这个模块：

location /hello {
    hello_world;
}

现在，当你访问http://your-server/hello时，就能看到"Hello World!"消息了！

08 错误处理：Nginx的健壮之道

在模块开发过程中，错误处理是保证Nginx稳定运行的关键。Nginx定义了一套统一的返回码，使错误处理更加一致：

NGX_OK — 操作成功
NGX_ERROR — 操作失败
NGX_AGAIN — 操作未完成；需要再次调用该函数
NGX_DECLINED — 操作被拒绝，例如，因为配置中已禁用。这绝不是错误
NGX_BUSY — 资源不可用
NGX_DONE — 操作完成或在其他地方继续。也用作备选成功代码

对于系统错误，Nginx提供了ngx_errno和ngx_socket_errno宏来获取最后的错误代码。这些宏在POSIX系统上映射到errno，在Windows上映射到GetLastError()。

连续多次访问ngx_errno或ngx_socket_errno的值可能会导致性能问题。

如果错误值可能被多次使用，请将其存储在ngx_err_t类型的局部变量中。

09 字符串处理：Nginx的安全之道

在C语言中，字符串处理是容易出错的地方，Nginx通过定义自己的字符串类型和相关函数来解决这一问题。

Nginx字符串类型ngx_str_t定义如下：

typedef struct {
    size_t      len;
    u_char     *data;
} ngx_str_t;

与传统的C字符串（以null结尾）不同，ngx_str_t包含长度字段，可以安全地处理二进制数据。

Nginx提供了一系列字符串操作函数，包括：

ngx_strcmp(), ngx_strncmp() - 字符串比较
ngx_strstr() - 查找子串
ngx_strlen() - 获取长度（当字符串可能包含null字节时）
ngx_memcpy(), ngx_memmove() - 内存拷贝

这些函数经过精心优化，既保证了安全性，又提供了高性能。

10 内存管理：Nginx的高效秘诀

Nginx实现了自己的内存管理机制，其中最核心的是**内存池（memory pool）**概念。

内存池允许Nginx在处理请求时批量分配内存，并在请求结束时一次性释放，这大大减少了内存分配和释放的开销，也避免了内存泄漏。

Nginx还实现了共享内存机制，用于在不同Worker进程间共享数据，如缓存、会话状态等。

共享内存通过ngx_shm_dict模块管理，支持动态添加共享内存。

模块化设计使得Nginx如同乐高积木，每个模块都可以独立开发、测试和维护，然后像拼图一样组合在一起，构建出强大而灵活的Web服务器。

从简单的配置修改到复杂的模块开发，Nginx为每个层次的开发者都提供了施展才华的空间。