暂无图片
暂无图片
暂无图片
暂无图片
暂无图片
首页 / 极限网关 INFINI Gateway 配置文件核心解读

极限网关 INFINI Gateway 配置文件核心解读

铭毅天下Elasticsearch 2025-02-18
307

本文围绕给定的极限网关（Infinilabs Gateway）配置文件，从宏观到微观、逐层展开进行讲解。

希望能帮助读者快速理解并上手这个配置文件的各项功能与含义。

一、概述

在微服务、分布式和大数据的应用场景下，网关常常承担流量路由、访问控制、日志与指标采集以及后端数据聚合等重要职责。

极限网关（Infinilabs Gateway）就是这样一个通用、高扩展的网关解决方案，能够对接Elasticsearch、EasySearch 等后端系统，

并提供多种高级功能如批量处理、流量切分、数据索引聚合以及系统监控等。

这篇文章的核心是通过一份完整的极限网关配置文件，从顶部到底部依次讲解其配置结构、常见用法与注意点。

阅读顺序大体为：

  1. 环境配置（env）
  2. 全局路径/基础配置（path、configs.auto_reload等）
  3. 网关基础功能：gateway、stats、statsd、api
  4. 后端Elasticsearch服务定义（elasticsearch）
  5. 入口、路由与流程（entry、router、flow）
  6. 批处理与管道（pipeline）
  7. 监控与Metrics（metrics）
  8. 磁盘队列配置（disk_queue）
  9. Badger KV存储配置（badger）
  10. Floating IP配置（floating_ip）
  11. Elasticsearch模块全局配置（elastic）

通过这种自上而下的拆解，可以帮你在面对类似的复杂配置时，有一个主次分明、逻辑清晰的学习思路。

二、环境变量配置（env）

env:
  LOGGING_ES_ENDPOINT: https://localhost:9200/
  LOGGING_ES_USER: elastic
  LOGGING_ES_PASS: changeme
  PROD_ES_ENDPOINT: https://localhost:9200/
  PROD_ES_USER: elastic
  PROD_ES_PASS: changeme
  GW_BINDING: "0.0.0.0:8000"
  API_BINDING: "0.0.0.0:2900"

这一部分主要用于定义网关在运行时使用的环境变量，包括：

  • LOGGING_ES_ENDPOINT PROD_ES_ENDPOINT：分别代表用于日志收集和生产（正式）环境的Elasticsearch访问地址。
  • LOGGING_ES_USER LOGGING_ES_PASS、PROD_ES_USER PROD_ES_PASS：对应的Elasticsearch账户与密码。
  • GW_BINDING：网关对外暴露的主端口与IP绑定。
  • API_BINDING：网关系统管理API对外暴露的端口与IP绑定。

这些环境变量在配置文件的后续部分可以通过 $[[env.VAR_NAME]]
的方式引入，达到可移植、可覆盖的效果。例如，正式环境和测试环境可以通过不同的环境变量注入来使用同一套配置文件。

三、基础路径及通用配置

path.data: data
path.logs: log
path.configs: config
configs.auto_reload: false

  • path.data：数据存储目录，网关会将一些持久化数据放在这里（如Badger KV数据、队列文件等）。
  • path.logs：日志文件的存储目录。
  • path.configs：额外存放网关配置文件的目录。
  • configs.auto_reload：是否自动重新加载网关配置文件。大多数情况下在生产环境中建议设置为false
    ，以避免频繁改动引发不必要的运行波动。

四、网关基础功能

4.1 网关层配置（gateway）

gateway:
  disable_reuse_port_by_default: true

  • disable_reuse_port_by_default：用于控制端口复用选项。有些Linux内核支持SO_REUSEPORT
    ，可以在同一个端口上运行多个监听进程。

不过如果环境不支持或不需要此功能，可以设置为true
来禁用，防止意外冲突。

4.2 网关内部统计（stats）与StatsD（statsd）

stats:
  enabled: true
  persist: true
  no_buffer: true
  buffer_size: 1000
  flush_interval_ms: 1000

statsd:
  enabled: false
  ...

  • stats.enabled：打开网关内部统计功能，用于收集请求数、处理延迟、错误数等信息。
  • persist：是否将统计信息做持久化；如果希望重启后保留历史度量数据，可以启用此功能。
  • no_buffer：是否禁用统计的缓冲机制（直接写入）。
  • statsd相关：当使用第三方StatsD服务采集日志或指标时，可以在这里进行配置，如目标host/port、命名空间、协议等。本例中statsd.enabled
    为false
    ，说明当前未启用。

4.3 系统API（api）

api:
  enabled: true
  network:
    binding: $[[env.API_BINDING]]
  security:
    enabled: false
    username: admin
    password: $[[keystore.API_PASS]]

  • api.enabled：开启系统API，便于在0.0.0.0:2900
    （示例环境变量中的值）对网关进行管理和监控。
  • security.enabled：是否开启API访问的认证。可以设置为true
    后，通过username
    与password
    （也可用keystore来存储敏感信息）进行保护。

五、Elasticsearch服务定义（elasticsearch）

elasticsearch:
  - name: prod
    enabled: true
    endpoints:
      - $[[env.PROD_ES_ENDPOINT]]
    discovery:
      enabled: false
    basic_auth:
      username: $[[env.PROD_ES_USER]]
      password: $[[env.PROD_ES_PASS]]
    traffic_control.max_bytes_per_node: 1010485760
    metadata_cache_enabled: false

  - name: logging-server
    enabled: true
    endpoints:
      - $[[env.LOGGING_ES_ENDPOINT]]
    basic_auth:
      username: $[[env.LOGGING_ES_USER]]
      password: $[[env.LOGGING_ES_PASS]]
    discovery:
      enabled: false

  • name：区分不同的Elasticsearch集群。例如：
    • prod
      用于正式集群
    • logging-server
      用于日志采集
  • endpoints：后端Elasticsearch节点的地址，可以是多个。
  • discovery.enabled：是否启用自动发现集群节点的功能。
  • basic_auth：如果后端集群需要认证，需在此配置用户名和密码。
  • traffic_control.max_bytes_per_node：流量控制配置，用于限制单节点的请求字节数。
  • metadata_cache_enabled：是否开启元数据缓存，用于缓存Elasticsearch的索引、映射等信息，提升性能。

通过这种方式，网关可以同时连接多个Elasticsearch后端，并对不同后端进行不同的策略控制。

六、入口（entry）、路由（router）与流程（flow）

6.1 入口（entry）

entry:
  - name: my_es_entry
    enabled: true
    router: my_router
    max_concurrency: 10000
    network:
      binding: $[[env.GW_BINDING]]
      reuse_port: true
    tls:
      enabled: true

  • entry.name：给入口流量的监听端口/实例起名字，比如my_es_entry
    。
  • router：指定将请求交给哪条路由（这里是my_router
    ）。
  • max_concurrency：最大并发数。
  • network.binding：通过环境变量决定绑定在0.0.0.0:8000
    端口对外提供服务。
  • tls.enabled：是否启用TLS。可以配置cert_file
    、key_file
    等自定义证书，或者使用内置机制自动生成。

6.2 路由（router）

router:
  - name: my_router
    default_flow: default_flow
    tracing_flow: logging_flow
    rules:
      - method:
          - "*"
        pattern:
          - "/_bulk"
          - "/{any_index}/_bulk"
        flow:
          - async_bulk_flow

  • router.name：路由的名称。
  • default_flow：如果没有匹配任何规则，则走默认流程（default_flow
    ）。
  • tracing_flow：额外的追踪流程（如日志）。一般在进行请求追踪或需要特殊处理时使用。
  • rules：定义请求匹配规则，包括method
    和pattern
    。
    • 在本例中，所有HTTP方法（*
      ）下，如果URL匹配/_bulk
      或/{any_index}/_bulk
      ，就进入async_bulk_flow
      这个流程。

6.3 流程（flow）

flow:
  - name: default_flow
    filter:
      - basic_auth:
          valid_users:
              $[[env.PROD_ES_USER]]: $[[env.PROD_ES_PASS]]
      - elasticsearch:
          elasticsearch: prod
          max_connection_per_node: 1000

  - name: logging_flow
    filter:
      - logging:
          queue_name: request_logging
          max_request_body_size: 4096
          max_response_body_size: 4096

  - name: async_bulk_flow
    filter:
      - bulk_reshuffle:
          when:
            contains:
              _ctx.request.path: /_bulk
          elasticsearch: prod
          level: node
          partition_size: 10
          continue_metadata_missing: true
          fix_null_id: true
      - elasticsearch:
          elasticsearch: prod
          max_connection_per_node: 1000

  • flow.name：流程名称。
  • filter：过滤器链，一个流程可以包含多个过滤器，每个过滤器完成不同的功能。
    • level: node
      表示在节点级别做转发，partition_size: 10
      进一步进行分区。
    • continue_metadata_missing: true
      当无法获取元数据时，是否继续执行下一个过滤器。
    • fix_null_id: true
      遇到批量请求中没有ID的文档时，自动修正或生成ID。
    • basic_auth
      ：在default_flow
      中进行基础认证，只允许配置中的用户/密码访问。
    • elasticsearch
      ：将请求转发给指定的Elasticsearch集群（prod
      ），max_connection_per_node
      限制单节点的连接数。
    • logging
      ：将请求信息写入到request_logging
      队列，这些日志可以后续批量索引到logging-server
      。
    • bulk_reshuffle
      ：对_bulk
      操作进行打散或分发（分到多个节点、分区），提升批量操作的并行度、吞吐量。

通过配置入口、路由、流程三层结构，实现了从接收请求到执行特定逻辑的完整路径定义。

七、批处理与管道（pipeline）

pipeline:
  - name: pipeline_logging_merge
    auto_start: true
    keep_running: true
    processor:
      - indexing_merge:
          input_queue: "logging"
          idle_timeout_in_seconds: 1
          elasticsearch: "logging-server"
          index_name: ".infini_logs"
          output_queue:
            name: "gateway-pipeline-logs"
            label:
              tag: "pipeline_logging"
          worker_size: 1
          bulk_size_in_kb: 1

pipeline 块定义了一系列后台“管道”作业，用于处理数据队列中的消息或日志。每个管道可以包含多个processor（处理器）：

  1. indexing_merge
    • 从input_queue: "logging"
      读取消息，合并后写入到指定的Elasticsearch（logging-server
      ），索引名.infini_logs
      。
    • 可配置idle_timeout_in_seconds
      ，表示当合并不足批量阈值时，等待多少秒就强制提交。
    • output_queue
      表明处理结果或处理过的消息可以继续写入下一个队列，供后续处理。
  2. bulk_indexing
    • 用于执行真正的批量写入操作。可进行压缩、设置批大小（MB或文档数），以及处理重试规则等。

通过pipeline
，可以将网关获得的各种请求、日志、指标进行异步写入ES或其他存储，大大提高吞吐与可用性。

八、监控配置（metrics）

metrics:
  enabled: true
  queue: metrics
  logging_queue: logging
  instance:
    enabled: true
  network:
    enabled: true
    summary: true
    sockets: true

  • metrics.enabled：开启网关内部监控。
  • queue 和 logging_queue：指标数据和日志数据所使用的队列。
  • instance.enabled：是否监控网关实例级别信息（CPU、内存等）。
  • network.enabled：是否监控网络层面的吞吐、连接数等。

这部分配置保证了网关能够把自身的性能状况收集并输出到对应的管道里。

九、磁盘队列配置（disk_queue）

disk_queue:
  prepare_files_to_read: true
  eof_retry_delay_in_ms: 500
  cleanup_files_on_init: false
  retention:
    max_num_of_local_files: 20
  compress:
    segment:
      enabled: true
    delete_after_compress: true
    idle_threshold: 20

  • disk_queue：当网关负载较大或对持久化与弹性需求较高时，可以将队列内容写到本地磁盘文件，防止因内存或网络异常导致数据丢失。
  • prepare_files_to_read：预先准备队列文件以便读操作。
  • cleanup_files_on_init：是否在启动时清理残留文件。
  • retention.max_num_of_local_files：最多保留多少队列文件。超过此数量会自动清理最早的文件。
  • compress.segment.enabled：对已处理完成的队列文件进行压缩，节省空间。
  • delete_after_compress：压缩后删除原始文件。
  • idle_threshold：在多少个文件都已消费并且已压缩后，触发额外操作（如进一步清理）。

十、Badger KV存储（badger）

badger:
  enabled: true
  single_bucket_mode: true
  path: ''
  memory_mode: false
  sync_writes: false
  ...

  • Badger 是一种本地KV数据库，用于缓存或存储网关所需的一些键值信息（如元数据、token、session等）。
  • single_bucket_mode：只使用一个bucket，简化管理。
  • path：存储路径，如果留空则默认在path.data/gateway/node/{nodeID}/badger/
    下。
  • memory_mode：是否只在内存中存储，不落地磁盘。
  • sync_writes：设置为true
    时，每次写都同步落盘，保证一致性但牺牲性能。一般在正式环境可酌情开启。

十一、Floating IP（floating_ip）

floating_ip:
  enabled: false
  netmask: 255.255.255.0
  ...

  • floating_ip.enabled：如果需要在集群中实现高可用或IP漂移（当主节点宕机时，备用节点自动接管IP），可以启用此功能；本例中关闭。
  • netmask / ip / interface：在不同的网络环境中配置虚IP和对应的子网、网卡。
  • priority：多个节点竞争时的优先级，数值越大代表优先级越高。

十二、Elasticsearch模块全局配置（elastic）

elastic:
  elasticsearch: prod
  enabled: true
  remote_configs: false
  health_check:
    enabled: true
    interval: 30s
  availability_check:
    enabled: true
    interval: 30s
  metadata_refresh:
    enabled: true
    interval: 60s
  cluster_settings_check:
    enabled: false
    interval: 60s

  • elasticsearch：指定一个默认使用的Elasticsearch服务（这里是prod
    ）。
  • health_check / availability_check / metadata_refresh：对ES服务做定期健康检查、可用性检查以及元数据（索引、mapping等）的刷新。
  • cluster_settings_check：可检查集群配置，但这里禁用。

这些全局配置确保网关与后端的Elasticsearch保持正确、最新的连接状态，并在发生故障时及时感知和处理。

总结

从上面的逐层拆解可以看出，极限网关配置文件具备高度灵活和可扩展的特点，覆盖了网关从“接收请求”到“数据索引与批量处理”再到“日志与监控”整个流程所需的方方面面。具体来说：

  1. 宏观层面：
    • env
      中的环境变量让部署可以一键切换配置；
    • gateway
      、stats
      、api
      等控制网关核心特征。
  2. 中观层面：
    • elasticsearch
      、entry
      、router
      、flow
      等用来定义后端服务、请求路由以及处理逻辑的流程。
    • pipeline
      、metrics
      处理异步任务和系统监控。
  3. 微观层面：
    • disk_queue
      、badger
      、floating_ip
      、elastic
      （模块级别的全局配置）提供数据持久化、KV存储、高可用与全局健康检查等。

在实际项目中，你可以按照以上层次来理解或修改配置，从最上层的网关功能目标（需要对接什么后端、启用何种路由/批处理），到中层的具体模块（pipeline、flow、metrics），再到底层存储与网络细节（disk_queue、badger、floating_ip）逐步展开，保证修改时的可控性与可追溯性。

希望这篇博客能帮助你对极限网关的配置有一个系统且清晰的认知，祝你配置顺利、上线无忧！

极限网关——一个面向Elasticsearch的高性能应用网关

如何防止 Elasticsearch 服务 OOM ？极限网关来为你的 ES 服务保驾护航！

Elasticsearch 国产化替代方案之一 Easysearch 的介绍与部署指南

读者留言：有 Elasticsearch 国产化替代品吗？现在国产化不让用 ES 了......

Elasticsearch 性能测试工具 Loadgen 之 001——部署及应用详解

Elasticsearch 性能测试工具 Loadgen 之 002——命令行及参数详解

Elasticsearch 性能测试工具 Loadgen 之 003——断言模式详解

Elasticsearch 性能测试工具 Loadgen 之 004——高级用法示例

更短时间更快习得更多干货！

和全球超2000+ Elastic 爱好者一起精进！

elastic6.cn——ElasticStack进阶助手


抢先一步学习进阶干货！

elasticsearch
文章转载自铭毅天下Elasticsearch，如果涉嫌侵权，请发送邮件至：contact@modb.pro进行举报，并提供相关证据，一经查实，墨天轮将立刻删除相关内容。

评论