Nginx基础教程（24）Nginx开发综述之开发基本流程：给Nginx“加特林”：从零开始造模块

原创于 2025-11-28 08:39:44 发布 · 143 阅读

2 ·

CC 4.0 BY-SA版权

文章标签：

#nginx #elasticsearch #运维

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

30 篇文章

订阅专栏

解锁Nginx的隐藏技能，让你的Web服务器变身超级赛亚人

引言：为什么我们需要给Nginx开发模块？

想象一下，Nginx就像一个精密的瑞士军刀，它已经自带了很多实用的工具（功能）。但有时候，你需要一个特殊的工具来解决特定问题，比如……嗯，打开太空罐头？这时候，你就需要自定义一个工具附件了。

在Web开发的世界里，这种“特殊工具”的需求无处不在：可能是一个复杂的身份验证系统，一个定制化的日志处理器，或者一个与公司内部系统无缝对接的缓存模块。这时候，开发自己的Nginx模块就成了终极解决方案。

别担心，这听起来很高大上，但实际上远比想象中简单。跟着我，让我们一起揭开Nginx模块开发的神秘面纱！

第一章：准备工作——打造你的Nginx开发环境

任何伟大的工程都需要稳固的基础，Nginx模块开发也不例外。

1.1 搭建开发环境

在Ubuntu系统上，只需要几个命令就能准备好所需环境：

sudo apt-get update
sudo apt-get install build-essential libpcre3-dev zlib1g-dev -y

这些包装了编译Nginx所需的基本开发工具和库。

1.2 获取Nginx源码

接下来，我们需要获取Nginx源代码。假设我们使用Nginx 1.14.0版本：

git clone -b release-1.14.0 --depth 1 https://github.com/nginx/nginx.git

--depth 1参数表示只拉取最新代码，不要完整的历史记录，这样下载更快。

1.3 编译Nginx

进入nginx目录，执行：

auto/configure && make

这会在objs目录下生成Nginx可执行文件。测试一下：

$ objs/nginx -v
nginx version: nginx/1.14.0

恭喜！你的基础开发环境已经准备好了。

第二章：Nginx模块架构探秘

在开始编码之前，我们需要理解Nginx是如何组织代码的。

2.1 Nginx源码结构

Nginx的源代码布局非常清晰：

auto — 构建脚本
src/core — 基本类型和函数：字符串、数组、日志、内存池等
src/event — 事件核心
src/http — HTTP核心模块和通用代码
src/os — 平台特定代码
src/stream — 流模块

2.2 模块化架构设计

Nginx采用了高度模块化的设计，每个功能都被封装在独立的模块中。这种设计使得Nginx具有惊人的可扩展性。模块分为几种类型：

核心模块：如ngx_core_module
事件模块：如ngx_epoll_module
HTTP模块：如ngx_http_module
邮件模块：如ngx_mail_module
流模块：如ngx_stream_module

今天我们的重点是HTTP模块的开发。

2.3 进程模型简介

Nginx采用master-worker多进程模型。master进程负责监控worker进程，而worker进程处理实际的客户端请求。这种架构既保证了稳定性，又充分利用了多核CPU的性能。

理解这一点很重要，因为我们的模块将会运行在worker进程中。

第三章：创建你的第一个Nginx模块

好了，现在到了最有趣的部分——实际动手编码！

3.1 建立模块目录结构

在nginx源码目录旁边，创建我们的模块目录：

nginx/ # nginx代码仓库
├── auto/ # nginx构建脚本目录
└── src/ # nginx源码目录
nginx-hello-module/ # 模块源码目录
├── config # 模块配置脚本
└── hello_module.c # 模块源码文件

3.2 编写模块配置脚本

config文件告诉Nginx构建系统如何编译我们的模块：

ngx_addon_name=ngx_http_hello_module
ngx_module_type=HTTP
ngx_module_name="$ngx_addon_name"
ngx_module_srcs="$ngx_addon_dir/hello_module.c"

. auto/module

这个脚本定义了模块名称、类型和源文件，然后调用Nginx的模块配置脚本。

3.3 定义模块的基本结构

现在我们来创建hello_module.c文件，首先是包含必要的头文件：

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

这三个头文件是每个Nginx HTTP模块都必须包含的。它们提供了Nginx核心功能、HTTP处理的API定义。

3.4 创建模块上下文

模块上下文包含了模块的生命周期回调函数：

static ngx_http_module_t ngx_http_hello_module_ctx = {
    NULL, /* preconfiguration */
    NULL, /* postconfiguration */
    NULL, /* create main configuration */
    NULL, /* init main configuration */
    NULL, /* create server configuration */
    NULL, /* merge server configuration */
    NULL, /* create location configuration */
    NULL /* merge location configuration */
};

对于简单的模块，这些回调函数都可以设为NULL。

3.5 定义配置指令

配置指令是模块与用户交互的接口。我们先定义一个空的指令数组：

static ngx_command_t ngx_http_hello_commands[] = {
    ngx_null_command
};

ngx_null_command是一个空对象，用作指令数组的结束标记。

3.6 声明模块主体

最后，我们定义模块主体结构：

ngx_module_t ngx_http_hello_module = {
    NGX_MODULE_V1,
    &ngx_http_hello_module_ctx, /* module context */
    ngx_http_hello_commands, /* module directives */
    NGX_HTTP_MODULE, /* module type */
    NULL, /* init master */
    NULL, /* init module */
    NULL, /* init process */
    NULL, /* init thread */
    NULL, /* exit thread */
    NULL, /* exit process */
    NULL, /* exit master */
    NGX_MODULE_V1_PADDING
};

这个结构包含了模块的所有信息，是模块的入口点。

第四章：让模块“活”起来——添加实际功能

现在我们的模块还是一个空壳，让我们给它注入灵魂！

4.1 添加配置指令

首先，我们添加一个配置指令hello_string，让用户能够自定义输出的字符串：

static char *ngx_http_hello(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);

static ngx_command_t ngx_http_hello_commands[] = {
    {
        ngx_string("hello_string"),
        NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,
        ngx_http_hello,
        NGX_HTTP_LOC_CONF_OFFSET,
        0,
        NULL
    },
    ngx_null_command
};

这段代码定义了一个名为hello_string的指令，它接受一个参数，并指定了处理函数为ngx_http_hello。

4.2 实现配置处理函数

当Nginx在配置文件中遇到hello_string指令时，会调用我们的处理函数：

static char *ngx_http_hello(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
    ngx_str_t *value;
    
    value = cf->args->elts;
    
    if (value[1].len == 0) {
        return NGX_CONF_ERROR;
    }
    
    return NGX_CONF_OK;
}

这个函数目前只是简单检查参数是否有效。

4.3 创建请求处理函数

请求处理函数是模块的核心，它负责生成发送给客户端的响应：

static ngx_int_t ngx_http_hello_handler(ngx_http_request_t *r)
{
    ngx_str_t response = ngx_string("Hello, Nginx Module World!");
    ngx_buf_t *b;
    ngx_chain_t out;
    
    // 设置响应头
    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = response.len;
    
    // 分配缓冲区
    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 = response.data;
    b->last = response.data + response.len;
    b->memory = 1;
    b->last_buf = 1;
    
    // 发送响应头
    ngx_http_send_header(r);
    
    // 发送响应体
    return ngx_http_output_filter(r, &out);
}

这个函数创建了一个简单的"Hello, Nginx Module World!"响应。

4.4 注册请求处理函数

我们需要在模块初始化时注册请求处理函数：

static ngx_int_t ngx_http_hello_init(ngx_conf_t *cf)
{
    ngx_http_handler_pt *h;
    ngx_http_core_main_conf_t *cmcf;
    
    cmcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_core_module);
    h = ngx_array_push(&cmcf->phases[NGX_HTTP_CONTENT_PHASE].handlers);
    if (h == NULL) {
        return NGX_ERROR;
    }
    
    *h = ngx_http_hello_handler;
    return NGX_OK;
}

同时更新模块上下文以使用这个初始化函数：

static ngx_http_module_t ngx_http_hello_module_ctx = {
    NULL, /* preconfiguration */
    ngx_http_hello_init, /* postconfiguration */
    // ... 其他回调保持不变
};

第五章：编译与测试——见证奇迹的时刻

5.1 编译模块

在nginx源码目录下，执行以下命令来编译我们的模块：

auto/configure --add-dynamic-module=../nginx-hello-module/
make modules

如果一切顺利，会在objs目录下生成ngx_http_hello_module.so文件。

5.2 配置Nginx使用模块

在nginx.conf配置文件中添加以下内容：

load_module modules/ngx_http_hello_module.so;

http {
    server {
        listen 8080;
        
        location /hello {
            hello_string "World";
        }
    }
}

5.3 测试模块

启动或重新加载Nginx配置后，访问http://yourserver:8080/hello，你应该能看到"Hello, Nginx Module World!"的响应！

第六章：深入理解——Nginx模块开发高级话题

6.1 处理配置数据

在实际的模块中，我们通常需要保存和使用配置数据。这需要通过创建配置结构体来实现：

typedef struct {
    ngx_str_t hello_string;
    ngx_int_t hello_counter;
} ngx_http_hello_loc_conf_t;

然后实现create_loc_conf和merge_loc_conf回调函数来管理这些配置。

6.2 访问请求参数

Nginx提供了丰富的API来访问请求的各个部分：

r->uri：获取请求URI
r->args：获取查询参数
r->headers_in：获取请求头
r->method：获取HTTP方法

6.3 内存管理

Nginx使用内存池来管理内存，这意味着我们不需要手动释放内存。使用ngx_palloc和ngx_pcalloc从内存池分配内存。

6.4 错误处理

Nginx定义了一套返回码来处理错误情况：

NGX_OK — 操作成功
NGX_ERROR — 操作失败
NGX_AGAIN — 操作未完成，需要再次调用
NGX_DECLINED — 操作被拒绝，这不是错误
NGX_ABORT — 函数被中止

第七章：热更新——不停机升级的魔法

Nginx支持热更新，这意味着我们可以在不中断服务的情况下更新配置甚至Nginx自身。

7.1 重新加载配置

向Nginx主进程发送HUP信号或执行nginx -s reload可以重新加载配置：

nginx -s reload

主进程会检查新配置的语法，然后启动新的工作进程，并优雅地关闭旧工作进程。

7.2 热更新模块

由于我们的模块是动态加载的，更新模块后只需要重新执行make modules并重新加载配置即可，无需重启Nginx服务。

结语：你的Nginx模块开发之旅才刚刚开始

恭喜你！已经成功创建了第一个Nginx模块。这只是一个开始，Nginx模块生态系统有着无限的可能性。

从简单的响应生成器，到复杂的负载均衡算法、自定义缓存实现、安全过滤器，甚至是完整的协议支持——所有这些都可以通过Nginx模块来实现。

记住，强大的能力也意味着重大的责任。在生产环境中使用自定义模块时，一定要充分测试，确保模块的稳定性和安全性。

现在，去创造一些令人惊叹的东西吧！

以上内容仅供参考和学习，在生产环境中使用自定义Nginx模块前，请务必进行充分测试。本文示例基于Nginx 1.14.0，不同版本间API可能有所变化。