最近想要监控 nginx 的流量状态，尤其是状态码的监控，发现了一个功能强大的模块nginx-module-vts。他并不是官方的模块，需要手动编译后加载。Nginx安装时自动打开了动态模块加载功能，可以在添加第三方模块时不用重新编译nginx。

一、背景

  1. 模块加载

Nginx 官方模块分为两类：

  • 静态模块：在编译 Nginx 时直接链接进二进制，无法在不重新编译整个 Nginx 的情况下增删。
  • 动态模块：编译为独立的 .so 文件，运行时通过 load_module 指令加载，无需重装或重启整个 Nginx。

生产环境中，我们通常使用发行版（apt/yum）或官方预编译包安装的 Nginx。如果只想加一个 nginx-module-vts 监控模块，重编译整个 Nginx 风险高、代价大。动态模块让我们可以在不改动原有 Nginx 二进制的前提下，单独编译这个模块并热加载。

  1. 安装环境

  • Linux：debian13.6
  • Nginx：1.26.3
  • nginx-module-vts：0.2.6

二、动态编译与加载步骤

整体流程：

1
获取 Nginx 源码 → 获取模块源码 → 编译模块(.so) → 加载模块 → 配置并验证

步骤 1：获取 Nginx 源码

先确认当前运行的 Nginx 版本，再到官网下载完全相同版本的源码。

1
2
3
4
5
6
7
# 确认运行版本
sudo nginx -v
nginx version: nginx/1.26.3

# 下载并解压同版本源码
wget https://nginx.org/download/nginx-1.26.3.tar.gz
tar -xf nginx-1.26.3.tar.gz

步骤 2：获取模块源码

从github下载 nginx-module-vts 模块的源码：

1
2
wget https://github.com/vozlt/nginx-module-vts/archive/refs/tags/v0.2.6.tar.gz -O nginx-module-vts-0.2.6.tar.gz
tar -zxvf nginx-module-vts-0.2.6.tar.gz

步骤 3：编译模块

核心点：./configure 必须包含原 Nginx 的全部参数。

3.1 取出原 Nginx 的 configure 参数

1
2
3
4
5
sudo nginx -V
nginx version: nginx/1.26.3
built with OpenSSL 3.5.6 7 Apr 2026
TLS SNI support enabled
configure arguments: --with-cc-opt='-g -O2 -Werror=implicit-function-declaration -ffile-prefix-map=/build/reproducible-path/nginx-1.26.3=. -fstack-protector-strong -fstack-clash-protection -Wformat -Werror=format-security -fcf-protection -fPIC -Wdate-time -D_FORTIFY_SOURCE=2' --with-ld-opt='-Wl,-z,relro -Wl,-z,now -fPIC' --prefix=/usr/share/nginx --conf-path=/etc/nginx/nginx.conf --http-log-path=/var/log/nginx/access.log --error-log-path=stderr --lock-path=/var/lock/nginx.lock --pid-path=/run/nginx.pid --modules-path=/usr/lib/nginx/modules --http-client-body-temp-path=/var/lib/nginx/body --http-fastcgi-temp-path=/var/lib/nginx/fastcgi --http-proxy-temp-path=/var/lib/nginx/proxy --http-scgi-temp-path=/var/lib/nginx/scgi --http-uwsgi-temp-path=/var/lib/nginx/uwsgi --with-compat --with-debug --with-pcre-jit --with-http_ssl_module --with-http_stub_status_module --with-http_realip_module --with-http_auth_request_module --with-http_v2_module --with-http_v3_module --with-http_dav_module --with-http_slice_module --with-threads --with-http_addition_module --with-http_flv_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_mp4_module --with-http_random_index_module --with-http_secure_link_module --with-http_sub_module --with-mail_ssl_module --with-stream_ssl_module --with-stream_ssl_preread_module --with-stream_realip_module --with-http_geoip_module=dynamic --with-http_image_filter_module=dynamic --with-http_perl_module=dynamic --with-http_xslt_module=dynamic --with-mail=dynamic --with-stream=dynamic --with-stream_geoip_module=dynamic

3.2 配置并编译模块

1
2
3
4
5
6
7
8
9
10
11
12
13
14
sudo apt install -y build-essential
cd nginx-1.26.3/

编译方法一（目前所有nginx版本通用）：

./configure --with-cc-opt='-g -O2 -Werror=implicit-function-declaration -ffile-prefix-map=/build/reproducible-path/nginx-1.26.3=. -fstack-protector-strong -fstack-clash-protection -Wformat -Werror=format-security -fcf-protection -fPIC -Wdate-time -D_FORTIFY_SOURCE=2' --with-ld-opt='-Wl,-z,relro -Wl,-z,now -fPIC' --prefix=/usr/share/nginx --conf-path=/etc/nginx/nginx.conf --http-log-path=/var/log/nginx/access.log --error-log-path=stderr --lock-path=/var/lock/nginx.lock --pid-path=/run/nginx.pid --modules-path=/usr/lib/nginx/modules --http-client-body-temp-path=/var/lib/nginx/body --http-fastcgi-temp-path=/var/lib/nginx/fastcgi --http-proxy-temp-path=/var/lib/nginx/proxy --http-scgi-temp-path=/var/lib/nginx/scgi --http-uwsgi-temp-path=/var/lib/nginx/uwsgi --with-compat --with-debug --with-pcre-jit --with-http_ssl_module --with-http_stub_status_module --with-http_realip_module --with-http_auth_request_module --with-http_v2_module --with-http_v3_module --with-http_dav_module --with-http_slice_module --with-threads --with-http_addition_module --with-http_flv_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_mp4_module --with-http_random_index_module --with-http_secure_link_module --with-http_sub_module --with-mail_ssl_module --with-stream_ssl_module --with-stream_ssl_preread_module --with-stream_realip_module --with-http_geoip_module=dynamic --with-http_image_filter_module=dynamic --with-http_perl_module=dynamic --with-http_xslt_module=dynamic --with-mail=dynamic --with-stream=dynamic --with-stream_geoip_module=dynamic --add-dynamic-module=/home/ops/nginx-module-vts-0.2.6
make modules

其中最后的--add-dynamic-module=注意改成自己vts的目录

编译方法二（nginx 1.23及以后得版本可以用）：
cd nginx-1.26.3
./configure --with-compat --add-dynamic-module=/home/ops/nginx-module-vts-0.2.6
make modules

编译成功后，模块文件出现在：

1
nginx-1.26.3/objs/ngx_http_vhost_traffic_status_module.so

3.3 常见编译报错

1
2
3
4
5
6
7
8
9
10
11
12
13
报错1：
./configure: error: the HTTP rewrite module requires the PCRE library.

sudo apt-get install -y libpcre2-dev

如果要是用编译方法一，可以将相关依赖都安装上
sudo apt install -y build-essential libpcre2-dev zlib1g-dev libssl-dev libxslt1-dev libgd-dev libgeoip-dev

报错2：
./configure: error: C compiler cc is not found

sudo apt install -y build-essential
安装编译相关依赖，并检查磁盘空间是否耗尽

3.4 复制到模块目录

1
2
3
4
5
# 查看原 Nginx 的 modules 路径（来自上面的 configure 输出，通常是 /etc/nginx/modules 或 /usr/lib/nginx/modules）
sudo nginx -V 2>&1 | grep -o '\-\-modules-path=[^ ]*' | cut -d= -f2
/usr/lib/nginx/modules

sudo cp ~/nginx-1.26.3/objs/ngx_http_vhost_traffic_status_module.so /usr/lib/nginx/modules

步骤 4：加载模块（.so 文件）

编辑主配置文件 nginx.conf，在**最顶部（events/http 块之外）**加入 load_module：

1
2
3
sudo vim /etc/nginx/nginx.conf

load_module modules/ngx_http_vhost_traffic_status_module.so;

⚠️ load_module 必须出现在 events {} 和 http {} 之前，否则配置检查会失败。

步骤 5：配置vts

在 http {} 块内启用统计区，在需要暴露的 server {} 块内配置展示路由：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
sudo vim /etc/nginx/nginx.conf

http {     

	# 启用流量统计共享内存区
    vhost_traffic_status_zone;
    ...
    ...
    }
    
sudo vim /etc/nginx/sites-enabled/default

    server {
        listen 80;
        server_name _;

        # 状态页（建议加访问控制）
        location /vts {
            vhost_traffic_status_display;
            vhost_traffic_status_display_format html;

            # 安全加固：仅允许内网或指定 IP 访问
            # allow 10.0.0.0/8;
            # deny all;
        }

步骤 6：校验并加载

1
2
3
4
5
6
7
8
9
# 配置语法检查
nginx -t
# 输出 nginx: configuration file /etc/nginx/nginx.conf test is successful
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful


# 平滑重载（不中断连接）
nginx -s reload

打开浏览器访问 http://<your-server>/vts，应看到流量状态页。