Kong API 网关从入门到生产实践

一、API 网关的价值

在微服务架构中，每个服务都有自己的地址、端口和 API 规范。如果没有统一的入口层，客户端将面临：

需要记住 N 个服务的不同地址
每个服务都要独立实现认证、限流、日志
跨域问题需要每个服务单独处理
流量控制和熔断难以统一管理

Kong 是目前最流行的开源 API 网关（GitHub 38,000+ Star），基于 OpenResty（Nginx + LuaJIT），提供：

路由转发、负载均衡、健康检查
认证（JWT / OAuth2 / Key-Auth / HMAC）
流量控制（限流、熔断、重试）
日志与监控（Prometheus / Datadog / 自定义）
请求/响应转换

二、Docker Compose 快速部署

# docker-compose.yml
version: '3.8'
services:
  kong-database:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: kong
      POSTGRES_USER: kong
      POSTGRES_PASSWORD: kongpass
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "kong"]
      interval: 5s

  kong-migration:
    image: kong:3.6
    command: kong migrations bootstrap
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_PASSWORD: kongpass
    depends_on:
      kong-database:
        condition: service_healthy

  kong:
    image: kong:3.6
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_PASSWORD: kongpass
      KONG_PROXY_ACCESS_LOG: /dev/stdout
      KONG_ADMIN_ACCESS_LOG: /dev/stdout
      KONG_PROXY_ERROR_LOG: /dev/stderr
      KONG_ADMIN_ERROR_LOG: /dev/stderr
      KONG_ADMIN_LISTEN: 0.0.0.0:8001
      KONG_ADMIN_GUI_URL: http://localhost:8002
    ports:
      - "8000:8000"   # 代理端口（客户端访问）
      - "8443:8443"   # SSL 代理端口
      - "8001:8001"   # Admin API（管理用）
      - "8002:8002"   # Kong Manager GUI
    depends_on:
      kong-migration:
        condition: service_completed_successfully

volumes:
  pg_data:

三、核心概念与 API 配置

Kong 分层模型

Service → 上游服务地址 | Route → 匹配规则（路径/域名/方法） | Plugin → 扩展能力

# 1. 创建 Service（上游服务）
curl -X POST http://localhost:8001/services \
  -d name=user-service \
  -d url=http://192.168.1.10:3001

# 2. 创建 Route（将 /api/users 路由到 user-service）
curl -X POST http://localhost:8001/services/user-service/routes \
  -d name=user-route \
  -d paths[]=/api/users \
  -d strip_path=true \
  -d methods[]=GET \
  -d methods[]=POST

# 3. 配置限流插件
curl -X POST http://localhost:8001/services/user-service/plugins \
  -d name=rate-limiting \
  -d config.minute=100 \
  -d config.hour=5000 \
  -d config.policy=local

# 4. 配置 JWT 认证
curl -X POST http://localhost:8001/services/user-service/plugins \
  -d name=jwt \
  -d config.claims_to_verify=exp

# 5. 验证路由
curl http://localhost:8000/api/users

四、生产环境插件配置

全局限流策略

curl -X POST http://localhost:8001/plugins \
  -d name=rate-limiting \
  -d config.minute=1000 \
  -d config.hour=10000 \
  -d config.policy=cluster \
  -d config.fault_tolerant=true \
  -d config.hide_client_headers=false

CORS 跨域配置

curl -X POST http://localhost:8001/plugins \
  -d name=cors \
  -d config.origins=https://example.com \
  -d config.methods=GET,POST,PUT,DELETE,OPTIONS \
  -d config.headers=Authorization,Content-Type \
  -d config.exposed_headers=X-Custom-Header \
  -d config.credentials=true \
  -d config.max_age=3600

五、声明式配置（推荐生产模式）

# kong.yml — 声明式配置，无需数据库
_format_version: "3.0"
_transform: true

services:
  - name: user-api
    url: http://user-api:3001
    routes:
      - name: user-routes
        paths:
          - /api/users
        methods: [GET, POST, PUT, DELETE]
    plugins:
      - name: rate-limiting
        config:
          minute: 100
          policy: local
      - name: jwt

  - name: order-api
    url: http://order-api:3002
    routes:
      - name: order-routes
        paths:
          - /api/orders
    plugins:
      - name: request-transformer
        config:
          add:
            headers:
              - X-Service:order-api

💡 生产环境建议

高流量场景使用 DB-less 模式 + 声明式配置，避免数据库成为瓶颈。Admin API 严格限制内网访问（127.0.0.1 或内网 IP）。监控 kong_latency 和 upstream_latency 分别判断网关层和上游服务的性能瓶颈。