【APISIX】配置IPv4/IPv6双栈以及纯IPv6监听

编码如写诗

发布于 2025-06-11 14:31:53

3290

随着IPv4地址资源日益枯竭，以及中央网信办等主管部门近年来持续推动IPv6规模化部署，IPv6技术在国内得到快速普及。当前政企单位对网络接入提出了更高要求：既要支持IPv4/IPv6双栈部署，又需满足部分场景下纯IPv6网络的运行需求。作为现代核心网关组件，APISIX需要率先对IPv6协议栈的支持，以应对新形势下的网络接入需求。

1.说明

本文将演示修改node_listen和admin_listen部分对IPV4和IPV6双栈的支持和只监听IPV6。作者使用apisix版本为: 3.11.0,以下内容皆在apisix:3.11.0版本中配置和测试

2.node_listen 端口

默认配置示例

该默认配置会开启双栈，同时支持IPV4和IPV6

apisix:
  node_listen: 9080                # APISIX listening port
  enable_heartbeat: true
  enable_admin: true
  enable_admin_cors: true
  enable_debug: false
  enable_dev_mode: false          # Sets nginx worker_processes to 1 if set to true
  enable_reuseport: true          # Enable nginx SO_REUSEPORT switch if set to true.
  enable_ipv6: true               #默认开启ipv6支持，此处可以省略
  config_center: etcd             # etcd: use etcd to store the config value
                                  # yaml: fetch the config value from local yaml file `/your_path/conf/apisix.yaml`

查看9080端口

通过netstat -tuln | grep 9080命令查看端口信息

可以看到同时生效了

配置只监听ipv6

apisix:
  node_listen:
    - ip: "[::]"
      port: 9080

再次查看9080端口

通过netstat -tuln | grep 9080命令查看端口信息

可以看到此时只监听了IPV6的9080

3.admin_listen

说明：admin_listen仅支持一种协议。若需要双栈支持需要修改lua代码

配置仅支持IPV4

直接用默认配置，就是只支持IPV4的

deployment:                    
  admin:                       
    enable_admin_cors: true       
    enable_admin_ui: true         
    allow_admin:                  
      - 127.0.0.0/24              
    admin_listen:                 
      ip: 0.0.0.0                 
      port: 9180

查看9180端口

通过netstat -tuln | grep 9180命令查看端口信息

配置仅支持IPV6

deployment:                    
  admin:                       
    enable_admin_cors: true       
    enable_admin_ui: true         
    allow_admin:                  
      - 127.0.0.0/24              
    admin_listen:                 
      ip: "[::]"                 
      port: 9180

查看端口信息

配置IPV4和IPV6双栈

起初原本以为通过给admin_listen添加数组的形式就可以实现，如下

deployment:                    
  admin:                       
    enable_admin_cors: true       
    enable_admin_ui: true         
    allow_admin:                  
      - 127.0.0.0/24              
    admin_listen:       #实际不生效          
      - ip: "[::]"                 
        port: 9180                  
      - ip: 0.0.0.0
        port: 9180

结果无论怎么修改测试，发现只有一个tcp 9180，后通过修改9180端口为其他端口发现，使用数组形式，其实未生效。

通过查看apisix源码，可以发现，只监听了一个ip和一个port，如下源码：

-- listen in admin use a separate port, support specific IP, compatible with the original style
local admin_server_addr
if yaml_conf.apisix.enable_admin then
    local ip = yaml_conf.deployment.admin.admin_listen.ip
    local port = yaml_conf.deployment.admin.admin_listen.port
    admin_server_addr = validate_and_get_listen_addr("admin port", "0.0.0.0", ip,
                                                      9180, port)
end

可以看到，这里直接获取admin_listen中的ip和port，然后组装给admin_server_addr ，而admin_server_addr 在ngx_tpl.lua模板中直接传给nginx.conf的listen

...
server {
    {%if https_admin then%}
    ...

    {% else %}
    listen {* admin_server_addr *}; #这里
    {%end%}
    log_not_found off;
    # admin configuration snippet starts
   ...

通过上述模板最终生成配置文件：/usr.local/apisix/conf/nginx.conf

通过查看上述源码后发现admin_listen只支持一种ip协议，所以如果想要双栈就需要修改源码。

这里以最简单的实现为例，直接在ngx_tpl.lua中579行添加一个ipv6的支持

...
server {
    {%if https_admin then%}
    ...

    {% else %}
    listen {* admin_server_addr *}; #这里
    listen [::]:9180; #添加此行IPV6支持
    {%end%}
    log_not_found off;
    # admin configuration snippet starts
   ...

重启apisix或者在apisix容器中执行/usr/local/openresty//luajit/bin/luajit ./apisix/cli/apisix.lua init

再次查看端口信息

通过netstat -tuln | grep 9180命令查看端口信息

可以看到此时IPV4和IPV6都以监听

进阶

如果感觉ngx_tpl.lua不方便配置改动，可以通过修改上述源码，实现admin_listen数组配置。以便在conf.yaml中直接配置。

4.总结

本文基于APISIX 3.11.0版本，演示了如何配置node_listen和admin_listen以支持IPv4与IPv6双栈或仅监听IPv6。APISIX的node_listen配置灵活，可轻松实现双栈或纯IPv6监听；而admin_listen因源码限制，需手动修改代码以支持双栈，未来可通过优化源码实现更便捷的配置方式。

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2025-06-10，如有侵权请联系 cloudcommunity@tencent.com 删除

配置