Nginx 模块-细节详探

秒速五厘米 2022-03-29 10:26 164阅读 0赞

本文主要基于

[http://www.codinglabs.org/html/intro-of-nginx-module-development.html][http_www.codinglabs.org_html_intro-of-nginx-module-development.html]

和

[http://www.evanmiller.org/nginx-modules-guide.html\#compiling][http_www.evanmiller.org_nginx-modules-guide.html_compiling]

的学习些的

## nginx模块要负责三种角色 ##

handler：接收请求+产生Output

filters：处理hander产生的output

load-balancer：负载均衡，选择一个后端server发送请求（如果把nginx当做负载均衡服务器的话，这个角色必须实现）

--------------------

## nginx内部流程(非常重要) ##

图片讲解：

[![clip\_image001][clip_image001]][clip_image001_clip_image001]

英文[讲解][http_www.evanmiller.org_nginx-modules-guide.html_compiling]：

Client sends HTTP request → Nginx chooses the appropriate handler based on the location config → (if applicable) load-balancer picks a backend server → Handler does its thing and passes each output buffer to the first filter → First filter passes the output to the second filter → second to third → third to fourth → etc. → Final response sent to client

中文讲解：

客户端发送http请求 -- nginx根据配置文件conf中的location来确定由哪个handler处理-- handler执行完request返回output给filter--第一个filter处理output -- 第二个filter处理output--- … -- 生成Response

--------------------

## Nginx模块的几个数据结构 ##

**1 Module Configuration Struct(s) 模块配置结构**

**2 Module Directives 模块命令结构**

**3 The Module Context模块内容**

**3.1 create\_loc\_conf**

**3.2 merge\_loc\_conf**

**4 The Module Definition模块整合**

**5 Module Installation模块安装**

### 1 模块配置结构： ###

这个结构的命名规则为ngx\_http\_\[module-name\]\_\[main|srv|loc\]\_conf\_t。

main,srv,loc表示这个模块的作用范围是配置文件中的main/server/location三种范围（这个需要记住，后面会经常用到）

例子：

typedef struct {
    
    ngx_str_t ed; //echo模块只有一个参数 比如 echo "hello"
    
    } ngx_http_echo_loc_conf_t; //echo 模块

### 2 模块命令结构：   例子： ###

static ngx_command_t ngx_http_echo_commands[] = {
    
    { ngx_string("echo"), //命令名字
    
    NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1, //代表是local配置，带一个参数
    
    ngx_http_echo, //组装模块配置结构
    
    NGX_HTTP_LOC_CONF_OFFSET, //上面的组装模块配置获取完参数后存放到哪里？使用这个和下面的offset参数来进行定位
    
    offsetof(ngx_http_echo_loc_conf_t, ed), //同上
    
    NULL // Finally, post is just a pointer to other crap the module might need while it's reading the configuration. It's often NULL.我也没理解是什么意思。通常情况下设置为NULL
    
    },
    
    ngx_null_command //必须使用ngx_null_command作为commands的结束标记
    
    };

###### 注1： ######

ngx\_http\_echo 是组装模块配置结构的函数指针，有三个参数：

ngx\_conf\_t \*cf 包含这个命令的所有参数

ngx\_command\_t \*cmd 执行这个command命令结构的指针

void \*conf 模块订制的配置结构

这个函数比较不好理解，其功能是把参数传到命令结构体中，并且把合适的值放入到模块配置结构中。我们称之为"setup function"。它会在命令运行的时候被调用。

nginx已经提供了几个现成的方法了：

ngx\_conf\_set\_flag\_slot

ngx\_conf\_set\_str\_slot

ngx\_conf\_set\_num\_slot

ngx\_conf\_set\_size\_slot

…

所以你可以这样定义cmd:

{ ngx_string("add_after_body"),
    
    NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,
    
    ngx_conf_set_str_slot,
    
    NGX_HTTP_LOC_CONF_OFFSET,
    
    offsetof(ngx_http_addition_conf_t, after_body),
    
    NULL },

也可以这样：

static ngx_command_t ngx_http_echo_commands[] = {
    
    { ngx_string("echo"),
    
    NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,
    
    ngx_http_echo,
    
    NGX_HTTP_LOC_CONF_OFFSET,
    
    offsetof(ngx_http_echo_loc_conf_t, ed),
    
    NULL },
    
    ngx_null_command
    
    };
    
    static char *
    
    ngx_http_echo(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_echo_handler; //这里指定了handler，那么就会使用新的handler进行处理
    
    ngx_conf_set_str_slot(cf,cmd,conf); //这里还是使用系统的函数
    
    return NGX_CONF_OK;
    
    }

### 3 模块内容 ###

static ngx\_http\_module\_t ngx\_http\_circle\_gif\_module\_ctx = \{

NULL, /\* preconfiguration \*/

NULL, /\* postconfiguration 这里是放置filter的地方，在filter章节会说\*/

NULL, /\* create main configuration \*/

NULL, /\* init main configuration \*/

NULL, /\* create server configuration \*/

NULL, /\* merge server configuration \*/

ngx\_http\_circle\_gif\_create\_loc\_conf, /\* create location configuration \*/

ngx\_http\_circle\_gif\_merge\_loc\_conf /\* merge location configuration \*/

\};

模块的内容ngx\_http\_<module name>\_module\_ctx是为了定义各种钩子函数，就是nginx在各个不同的时期将会运行的函数。

一般的location只需要配置create location configuration（在创建location配置的时候运行）和merge location configuration（和server config如何合并，一般包含如果配置有错误的话应该抛出异常）

这两个函数的例子：（来自[https://github.com/evanmiller/nginx\_circle\_gif/][https_github.com_evanmiller_nginx_circle_gif]）

static void \*

ngx\_http\_circle\_gif\_create\_loc\_conf(ngx\_conf\_t \*cf)

ngx\_http\_circle\_gif\_loc\_conf\_t \*conf;

conf = ngx\_pcalloc(cf->pool, sizeof(ngx\_http\_circle\_gif\_loc\_conf\_t));

if (conf == NULL) \{

return NGX\_CONF\_ERROR;

conf->min\_radius = NGX\_CONF\_UNSET\_UINT; //对conf中的每个参数进行配置，min\_redius和max\_redius是nginx\_circle\_gif模块的配置结构的字段

conf->max\_radius = NGX\_CONF\_UNSET\_UINT;

return conf;

和

static char \*

ngx\_http\_circle\_gif\_merge\_loc\_conf(ngx\_conf\_t \*cf, void \*parent, void \*child)

ngx\_http\_circle\_gif\_loc\_conf\_t \*prev = parent; //server的loc配置

ngx\_http\_circle\_gif\_loc\_conf\_t \*conf = child; // 自己的loca配置

ngx\_conf\_merge\_uint\_value(conf->min\_radius, prev->min\_radius, 10);

ngx\_conf\_merge\_uint\_value(conf->max\_radius, prev->max\_radius, 20);

if (conf->min\_radius < 1) \{

ngx\_conf\_log\_error(NGX\_LOG\_EMERG, cf, 0,

"min\_radius must be equal or more than 1");

return NGX\_CONF\_ERROR; //这里负责抛出错误

if (conf->max\_radius < conf->min\_radius) \{

ngx\_conf\_log\_error(NGX\_LOG\_EMERG, cf, 0,

"max\_radius must be equal or more than min\_radius");

return NGX\_CONF\_ERROR; //这里负责抛出错误

return NGX\_CONF\_OK;

注1 ： ngx\_conf\_merge\_uint\_value是nginx core中自带的函数

ngx\_conf\_merge\_<data type>\_value

ngx\_conf\_merge\_uint\_value(conf->min\_radius, prev->min\_radius, 10);的意思是：

如果设置了conf->min\_redius的话使用conf->min\_redius

如果没有设置conf->min\_redius的话使用 prev->min\_radius

如果两个都没有设置的话使用10

更多函数请看 [core/ngx\_conf\_file.h][core_ngx_conf_file.h]

### 4 模块整合 ###

ngx\_module\_t ngx\_http\_<module name>\_module = \{

NGX\_MODULE\_V1,

&ngx\_http\_<module name>\_module\_ctx, /\* module context 模块内容 \*/

ngx\_http\_<module name>\_commands, /\* module directives 模块命令\*/

NGX\_HTTP\_MODULE, /\* module type 模块类型，HTTP模块，或者HTTPS\*/

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

\};

5 模块安装

模块安装文件的编写依赖于这个模块是handler,filter还是load-balancer的工作角色

下面开始是Handler，filter,load-balancer的编写和安装

1 Handler安装

还记得在模块命令的时候有设置handler的语句吗？

clcf->handler = ngx\_http\_echo\_handler;

这个语句就是handler的安装

2 Handler编写

Handler的执行有四部：

读入模块配置

处理功能业务

产生HTTP header

产生HTTP body

读入模块配置

例子：

static ngx_int_t
    
    ngx_http_circle_gif_handler(ngx_http_request_t *r)
    
    {
    
    ngx_http_circle_gif_loc_conf_t *circle_gif_config;
    
    circle_gif_config = ngx_http_get_module_loc_conf(r, ngx_http_circle_gif_module);
    
    ...

就是使用nginx已经有的函数ngx\_http\_get\_module\_loc\_conf,第一个参数是当前请求，第二个参数是前面写好的模块

处理功能业务

这个部分是我们要模块处理的实际部分

用需求举例：

这个模块有个命令是 getRedisInfo 192.168.0.1 //获取redis的信息

那么这个功能业务就是(伪代码)：

case cmd->opcode

"getRedisInfo" :

获取redis 的信息

这里应该把所有这个模块设置的命令的业务逻辑都写好

产生HTTP Header

例子：

r->headers\_out.status = NGX\_HTTP\_OK;

r->headers\_out.content\_length\_n = 100;

r->headers\_out.content\_type.len = sizeof("image/gif") - 1;

r->headers\_out.content\_type.data = (u\_char \*) "image/gif";

ngx\_http\_send\_header(r);

产生HTTP Body

这个部分是最重要的一步

[借用codingLabs][http_www.codinglabs.org_html_intro-of-nginx-module-development.html]的图讲解一下nginx的IO

[![clip\_image002][clip_image002]][clip_image002_clip_image002]

handler是可以一次产生出一个输出，也可以产生出多个输出使用ngx\_chain\_t的链表来进行连接

struct ngx\_chain\_s \{

ngx\_buf\_t \*buf;

ngx\_chain\_t \*next;

\};

buf中有pos和last来代表out数据在内存中的位置，next是代表下一个ngx\_chain\_t

下面来说一下只有一个ngx\_chain\_t的设置

#### 1 申明 ####

ngx\_buf\_t \*b;

ngx\_chain\_t out

#### 2 设置buffer ####

b = ngx\_pcalloc(r->pool, sizeof(ngx\_buf\_t));

if (b == NULL) \{

ngx\_log\_error(NGX\_LOG\_ERR, r->connection->log, 0,

"Failed to allocate response buffer.");

return NGX\_HTTP\_INTERNAL\_SERVER\_ERROR;

b->pos = some\_bytes; /\* first position in memory of the data \*/

b->last = some\_bytes + some\_bytes\_length; /\* last position \*/

b->memory = 1; /\* content is in read-only memory \*/

/\* (i.e., filters should copy it rather than rewrite in place) \*/

b->last\_buf = 1; /\* there will be no more buffers in the request \*/

#### 3 模块加入链表 ####

out.buf = b;

out.next = NULL; //如果有下一个链表可以放到这里

#### 4 返回 ####

return ngx\_http\_output\_filter(r, &out);

## 2 Filter的编写和安装 ##

Filter作为过滤器又可以细分为两个过滤器: Header filters 和 body filters

Filter的安装

filter是在模块内容设置的时候加上的

例子：

static ngx\_http\_module\_t ngx\_http\_chunked\_filter\_module\_ctx = \{

NULL, /\* preconfiguration \*/

ngx\_http\_chunked\_filter\_init, /\* postconfiguration \*/

...

\};

static ngx\_int\_t

ngx\_http\_chunked\_filter\_init(ngx\_conf\_t \*cf)

ngx\_http\_next\_header\_filter = ngx\_http\_top\_header\_filter;

ngx\_http\_top\_header\_filter = ngx\_http\_chunked\_header\_filter;

ngx\_http\_next\_body\_filter = ngx\_http\_top\_body\_filter;

ngx\_http\_top\_body\_filter = ngx\_http\_chunked\_body\_filter;

return NGX\_OK;

注1: ngx\_http\_top\_hreader\_filter是什么意思呢？

当handler生成了response的时候，它调用了两个方法：ngx\_http\_output\_filter和ngx\_http\_send\_header

ngx\_http\_output\_filter会调用ngx\_http\_top\_body\_filter

ngx\_http\_send\_header会调用ngx\_top\_header\_filter

Filter的编写

Header filters

分为三个部分：

是否操作这个handler的response

操作response

调用下一个filter

[例子][http_www.evanmiller.org_nginx-modules-guide.html_compiling]：

static
    
    ngx_int_t ngx_http_not_modified_header_filter(ngx_http_request_t *r)
    
    {
    
    time_t if_modified_since;
    
    if_modified_since = ngx_http_parse_time(r->headers_in.if_modified_since->value.data,
    
    r->headers_in.if_modified_since->value.len);
    
    /* step 1: decide whether to operate */
    
    if (if_modified_since != NGX_ERROR && 
    
    if_modified_since == r->headers_out.last_modified_time) {
    
    /* step 2: operate on the header */
    
    r->headers_out.status = NGX_HTTP_NOT_MODIFIED; //返回304
    
    r->headers_out.content_type.len = 0; //长度设置为0
    
    ngx_http_clear_content_length(r); //清空
    
    ngx_http_clear_accept_ranges(r); //清空
    
    }
    
    /* step 3: call the next filter */
    
    return ngx_http_next_header_filter(r);
    
    }

Body filters

假设有个需求：在每个request后面插入"<l!-- Served by Nginx -->"

1 要找出最后chain的最后一个buf

ngx_chain_t *chain_link;
    
    int chain_contains_last_buffer = 0;
    
    for ( chain_link = in; chain_link != NULL; chain_link = chain_link->next ) {
    
    if (chain_link->buf->last_buf)
    
    chain_contains_last_buffer = 1;
    
    }

2 创建一个新的buf

ngx_buf_t *b;
    
    b = ngx_calloc_buf(r->pool);
    
    if (b == NULL) {
    
    return NGX_ERROR;
    
    }

3 放数据在新buf上

b->pos = (u_char *) "";
    
    b->last = b->pos + sizeof("") - 1;

4 把新buf放入一个新chain\_t

ngx_chain_t *added_link;
    
    added_link = ngx_alloc_chain_link(r->pool);
    
    if (added_link == NULL)
    
    return NGX_ERROR;
    
    added_link->buf = b;
    
    added_link->next = NULL;

5 把新的chain链接到原来的chain\_link中

chain\_link->next = added\_link;

6 重新设置last\_buf

chain\_link->buf->last\_buf = 0;

added\_link->buf->last\_buf = 1;

7 传给下一个filter

return ngx\_http\_next\_body\_filter(r, in);

## 最后一点是如何写和编译nginx模块 ##

必须写两个文件**config**和**ngx\_http\_<your module>\_module.c**

其中config会被./configure包含

ngx\_addon\_name=ngx\_http\_<your module>\_module

HTTP\_MODULES="$HTTP\_MODULES ngx\_http\_<your module>\_module"

NGX\_ADDON\_SRCS="$NGX\_ADDON\_SRCS $ngx\_addon\_dir/ngx\_http\_<your module>\_module.c"

几乎都是填空

ngx\_http\_<your module>\_module.c文件就是你的所有模块代码

编译nginx：

./configure --add-module=path/to/your/new/module/directory \#这里是config放置的地方

\----------------------

作者：yjf512（轩脉刃）

出处：http://www.cnblogs.com/yjf512/

本文版权归yjf512和cnBlog共有，欢迎转载，但未经作者同意必须保留此段声明

[http_www.codinglabs.org_html_intro-of-nginx-module-development.html]: http://www.codinglabs.org/html/intro-of-nginx-module-development.html
[http_www.evanmiller.org_nginx-modules-guide.html_compiling]: http://www.evanmiller.org/nginx-modules-guide.html#compiling
[clip_image001]: https://images.cnblogs.com/cnblogs_com/yjf512/201204/201204011235583378.png
[clip_image001_clip_image001]: /images/20220329/af53c143c9c14e77a1c7ef8e673a1a58.png
[https_github.com_evanmiller_nginx_circle_gif]: https://github.com/evanmiller/nginx_circle_gif/
[core_ngx_conf_file.h]: http://www.evanmiller.org/lxr/http/source/core/ngx_conf_file.h#L254
[clip_image002]: https://images.cnblogs.com/cnblogs_com/yjf512/201204/201204011235595820.png
[clip_image002_clip_image002]: /images/20220329/5a66c2b2206746b98d21245b9fd02460.png