KNEP Docker镜像文档

镜像概述和主要用途

KNEP（Kong Native Event Proxy）是一款专为Kong API网关打造的原生事件代理工具，旨在提供高效、可靠的Kong事件捕获与转发能力。作为Kong生态的重要组件，KNEP能够实时收集Kong网关在运行过程中产生的各类事件（如请求处理、插件操作、节点状态变化等），并将这些事件转发至指定的目标服务（如消息队列、日志系统、监控平台等），助力用户实现对Kong网关的事件驱动型管理与集成。

核心功能和特性

• 原生Kong事件捕获：深度集成Kong网关，支持捕获Kong核心事件（如request、response、plugin_updated、node_health等），覆盖网关运行全生命周期。
• 多目标事件转发：支持将事件转发至多种目标服务，包括Kafka、RabbitMQ、HTTP端点、文件系统等，满足不同集成场景需求。
• 灵活事件过滤：提供基于事件类型、属性的过滤规则，支持按需求筛选关注的事件，减少无效数据传输。
• 低延迟与高可靠：采用轻量级架构设计，事件处理延迟低；支持本地缓存与重试机制，确保事件可靠投递。
• 动态配置管理：支持通过环境变量或配置文件动态调整代理参数（如目标服务地址、认证信息、转发策略等），无需重启即可生效。

使用场景和适用范围

典型使用场景

• Kong网关实时监控：将Kong的请求/响应事件转发至监控平台（如Prometheus、Grafana），实时监控网关流量、错误率等关键指标。
• 日志聚合与分析：收集Kong的访问日志、错误日志事件，转发至ELK Stack（Elasticsearch、Logstash、Kibana）或Splunk，实现日志集中存储与分析。
• 事件驱动型插件扩展：基于KNEP转发的事件触发自定义业务逻辑（如请求异常时自动调用告警接口、流量突增时触发扩容策略）。
• 多集群Kong事件同步：在分布式Kong集群中，通过KNEP实现跨节点事件同步，确保集群状态一致性。

适用范围

• Kong网关用户（社区版/企业版均可）。
• 需要对Kong网关进行事件驱动型管理的团队。
• 构建基于API网关的微服务事件生态的场景。

使用方法和配置说明

基本使用（Docker Run）

最简启动命令

docker run -d \
  --name knep \
  -e KONG_ADMIN_URL=[***] \  # Kong Admin API地址
  -e TARGET_TYPE=kafka \                      # 目标服务类型（支持kafka/http/file等）
  -e TARGET_KAFKA_BROKERS=kafka:9092 \        # Kafka broker地址（TARGET_TYPE=kafka时必填）
  -e TARGET_KAFKA_TOPIC=kong-events \         # Kafka主题（TARGET_TYPE=kafka时必填）
  your-registry/knep:latest

环境变量配置说明

目标服务专项配置

• Kafka目标（TARGET_TYPE=kafka）：

  • TARGET_KAFKA_BROKERS：Kafka broker列表（如broker1:9092,broker2:9092）
  • TARGET_KAFKA_TOPIC：事件投递的Kafka主题
  • TARGET_KAFKA_COMPRESSION：消息压缩方式（none/gzip/snappy），默认none
  • TARGET_KAFKA_RETRY_MAX：投递失败重试次数，默认3

• HTTP目标（TARGET_TYPE=http）：

  • TARGET_HTTP_URL：接收事件的HTTP端点URL
  • TARGET_HTTP_METHOD：HTTP请求方法（POST/PUT），默认POST
  • TARGET_HTTP_TIMEOUT：HTTP请求超时时间（秒），默认5

Docker Compose配置示例

以下是KNEP与Kong、Kafka集成的docker-compose示例：

version: '3.8'

services:
  kong:
    image: kong:latest
    ports:
      - "8000:8000"   # 代理端口
      - "8001:8001"   # Admin API端口
    environment:
      - KONG_DATABASE=off
      - KONG_PROXY_ACCESS_LOG=/dev/stdout
      - KONG_ADMIN_LISTEN=0.0.0.0:8001

  zookeeper:
    image: confluentinc/cp-zookeeper:latest
    environment:
      - ZOOKEEPER_CLIENT_PORT=2181

  kafka:
    image: confluentinc/cp-kafka:latest
    depends_on:
      - zookeeper
    environment:
      - KAFKA_BROKER_ID=1
      - KAFKA_ZOOKEEPER_CONNECT=zookeeper:2181
      - KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092
      - KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1

  knep:
    image: your-registry/knep:latest
    depends_on:
      - kong
      - kafka
    environment:
      - KONG_ADMIN_URL=[***]
      - TARGET_TYPE=kafka
      - TARGET_KAFKA_BROKERS=kafka:9092
      - TARGET_KAFKA_TOPIC=kong-events
      - EVENT_FILTER_TYPES=request,response,plugin_updated
      - LOG_LEVEL=info

事件格式说明

KNEP转发的事件为JSON格式，包含以下核心字段：

{
  "event_type": "request",          // 事件类型（如request/response/plugin_updated）
  "timestamp": 1695000000,          // 事件发生时间戳（Unix秒级）
  "kong_node_id": "node-123",       // 产生事件的Kong节点ID
  "data": {                         // 事件详细数据（因事件类型而异）
    "request_id": "req-abc123",
    "method": "GET",
    "path": "/api/v1/users",
    "status": 200,
    // ... 其他请求相关字段
  }
}

具体事件类型及对应data字段定义可参考KNEP官方文档。