【实战经验如何动态配置 NGINX Map？

NGINX 向云原生演进，All in OpenNJet

Map 指令介绍

Map 指令是 NGINX 配置文件中的一个指令，它用于在请求处理期间创建自定义变量，并根据指定的键值对映射关系进行值的映射。Map 指令是由 ngx_http_map_module 模块提供的，默认情况下安装 NGINX 都会安装该模块。Map 指令可以用于许多场景，例如根据请求的路径生成重写规则、根据请求头判断是否启用缓存、根据查询参数配置不同的后端服务等。

Map 指令的三个参数：

1、default ： 指定源变量匹配不到任何表达式时将使用的默认值。当没有设置 default，将会用一个空的字符串作为默认的结果；

2、hostnames ： 允许用前缀或者后缀掩码指定域名作为源变量值，这个参数必须写在值映射列表的最前面；

3、include ： 包含一个或多个含有映射值的文件；
 

Map 指令的语法如下：

map $variable $new_variable {
    key value;
    key value;
    # 可以添加更多的键值对
    default value;
}

其中：

• $variable 是要映射的输入变量的名称。
• $new_variable 是映射结果的新变量的名称。
• key 是输入变量可能的值。
• value 是与每个键关联的映射值。
• default 是当输入变量不匹配任何键时的默认值。

这个指令允许你根据输入变量的不同值来设置新的变量值。这在配置 NGINX 时非常有用，可以根据不同的情况来定制服务器的行为。

经典使用场景

• 路径重写：您可以使用 Map 模块来根据请求的 URI 重写 URL，例如将旧的 URL 映射到新的 URL。

map $uri $new_uri {
  /old-path /new-path;
  /another-old-path /another-new-path;
}

server {
  location / {
    rewrite ^ $new_uri permanent;
  }
}

• 请求分发：您可以使用 map 模块将请求分发到不同的后端服务器，根据某些条件进行选择。

map $arg_backend $backend {
  default backend1;
  server1 backend2;
  server2 backend3;
}

upstream backend1 {
  server backend1.example.com;
}

upstream backend2 {
  server backend2.example.com;
}

upstream backend3 {
  server backend3.example.com;
}

server {
  location / {
    proxy_pass http://$backend;
  }

• 权限控制：您可以使用 map 模块根据客户端 IP 地址或其他条件来控制访问权限。

map $remote_addr $allowed {
  192.168.1.0/24 1;
  default 0;
}

server {
  location /private {
    if ($allowed = 0) {
      return 403;
    }
    # 允许访问私有内容
  }
}

这些是一些 NGINX map 模块的常见使用场景，您可以根据具体需求自定义映射规则以满足您的需求。

如何利用 OpenNJet 实现 Map 指令动态配置？

NGINX Map 指令支持静态配置，不支持动态配置。它主要用于在请求处理期间创建一个键值对映射，以便根据输入值查找相应的值。这个映射在 NGINX 配置文件中定义，并在服务器启动时加载。那么，今天给大家分享下如何利用好 OpenNJet 提供动态修改 Map 指令中键值的映射关系，不需要重新加载或重启 OpenNJet 实例。

OpenNJet 传送门：njet.org.cn/

这样做有什么好处呢？
 

配置说明

基础配置：

njet.conf

worker_processes auto;
cluster_name njet;
node_name node1;
error_log logs/error.log error;

helper ctrl modules/njt_helper_ctrl_module.so conf/njet_ctrl.conf;
helper broker modules/njt_helper_broker_module.so;

load_module modules/njt_http_location_module.so;
load_module modules/njt_http_vtsc_module.so;
load_module modules/njt_http_dyn_map_module.so;

events {
    worker_connections  1024;
}

http {
    map $arg_service $backend_svr {
       default "127.0.0.1:18081";
    }

    include mime.types;
    server {
        listen       8080;
        location / {
           proxy_pass http://$backend_svr;
        }
    }

    server {
        listen 18081;
        return 200 "default service 18081\n";
    }
}

ctrl.conf

load_module modules/njt_http_sendmsg_module.so;
load_module modules/njt_ctrl_config_api_module.so; 
load_module modules/njt_helper_health_check_module.so;
load_module modules/njt_http_upstream_api_module.so; 
load_module modules/njt_http_location_api_module.so;
load_module modules/njt_doc_module.so;
load_module modules/njt_http_vtsd_module.so;

error_log logs/error_ctrl.log error;

events {
    worker_connections  1024;
}

http {
    include mime.types;
    access_log off;
    server {
        listen       8081;
        keepalive_timeout 0;

        location / {
            return 200 "njet control panel\n";
        }
        location /hc {
            health_check_api;
        }
        
        location /api {
             api write=on;
        }
        
        location /kv {
            dyn_sendmsg_kv;
        }
        
        location /config {
            config_api;
        }
        
        location /doc {
            doc_api;
        }
        location /dyn_loc {
           dyn_location_api;
        }
  
        location /metrics {
            vhost_traffic_status_display;
            vhost_traffic_status_display_format html;
        }
    }
}

更多验证，点击 OpenNJet 查看执行效果。

OpenNJet 动态配置 Map 提供了更灵活、高性能、简化管理和实时更新的优势，使您能够更好地管理和优化您的服务器配置。

OpenNJet 最早是基于 NGINX1.19 基础 fork 并独立演进，OpenNJet 具有高性能、稳定、易扩展的特点，同时也解决了 NGINX 长期存在的难于动态配置、管理功能影响业务等问题。作为底层引擎，OpenNJet 利用动态加载机制可以实现不同的产品形态，如 API 网关、消息代理、出入向代理，负载均衡，WAF 等等。在云原生架构中，OpenNJet 除了提供南北向通信网关的功能以外，还提供了服务网格中东西向通信、透明流量劫持、熔断、遥测与故障注入等新功能特性。

Gitee    邮件组
邀您开源共建：njet.org.cn/