管理设计篇之"网关模式" [2026重制版]

# docker-compose-kong.yml
version: '3.8'

networks:
  kong-net:
    driver: bridge

services:
  # PostgreSQL 数据库
  kong-database:
    image: postgres:16-alpine
    container_name: kong-db
    environment:
      POSTGRES_USER: kong
      POSTGRES_DB: kong
      POSTGRES_PASSWORD: ${KONG_PG_PASSWORD:-kong_password}
    ports:
      - "15432:5432"
    networks:
      - kong-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kong -d kong"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Kong 迁移初始化
  kong-migration:
    image: kong:3.7.0-ubuntu
    container_name: kong-migration
    depends_on:
      kong-database:
        condition: service_healthy
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: ${KONG_PG_PASSWORD:-kong_password}
      KONG_CASSANDRA_CONTACT_POINTS: kong-database
    command: kong migrations bootstrap
    networks:
      - kong-net
    restart on-failure

  # Kong 网关节点
  kong-gateway:
    image: kong:3.7.0-ubuntu
    container_name: kong-gateway
    depends_on:
      kong-migration:
        condition: service_completed_successfully
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: ${KONG_PG_PASSWORD:-kong_password}
      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
      # 关键插件配置
      KONG_PLUGINS: bundled,cors,key-auth,rate-limiting,jwt,oauth2,proxy-cache,request-transformer,response-transformer,acl,ip-restriction
      KONG_NGINX_PROXY_REAL_IP_RECURSIVE: "on"
      KONG_TRUSTED_PROXIES: 0.0.0.0/0,::/0
    ports:
      - "8000:8000"   # Proxy 端口 (HTTP)
      - "8443:8443"   # Proxy 端口 (HTTPS)
      - "8001:8001"   # Admin API 端口
      - "8444:8444"   # Admin API HTTPS
      - "8002:8002"   # Manager GUI
    networks:
      - kong-net
    healthcheck:
      test: ["CMD", "kong", "health"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Kong Manager GUI (可选)
  kong-manager:
    image: kong:3.7.0-ubuntu
    container_name: kong-manager
    depends_on:
      kong-gateway:
        condition: service_healthy
    environment:
      KONG_ADMIN_LISTEN: 0.0.0.0:8002
      KONG_ADMIN_GUI_URL: http://localhost:8002
      KONG_DATABASE: off
      KONG_DECLARATIVE_CONFIG: ""
    ports:
      - "8002:8002"
    networks:
      - kong-net

# ====== 1. 创建上游服务 ======

# 用户服务
curl -i -X POST http://localhost:8001/services \
  --data name=user-service \
  --data url=http://user-service:8081 \
  --data connect_timeout=5000 \
  --data write_timeout=5000 \
  --data read_timeout=5000 \
  --data retries=3

# 订单服务
curl -i -X POST http://localhost:8001/services \
  --data name=order-service \
  --data url=http://order-service:8083 \
  --data connect_timeout=5000 \
  --data write_timeout=10000 \
  --data read_timeout=10000

# ====== 2. 创建路由规则 ======

# 用户服务路由
curl -i -X POST http://localhost:8001/services/user-service/routes \
  --data name=user-route \
  --data paths[]=/api/user \
  --data methods[]=GET,POST,PUT,DELETE \
  --data strip_path=true

# 订单服务路由
curl -i -X POST http://localhost:8001/services/order-service/routes \
  --data name=order-route \
  --data paths[]=/api/order \
  --data methods[]=POST,GET \
  --data strip_path=true

# ====== 3. 启用 JWT 认证插件 ======
curl -i -X POST http://localhost:8001/plugins \
  --name jwt \
  --config.secret_is_base64=false \
  --config.key_claim_name=iss \
  --config.claims_to_verify=exp,nbf

# ====== 4. 启用限流插件 ======
curl -i -X POST http://localhost:8001/plugins \
  --name rate-limiting \
  --config.minute=100 \
  --config.policy=local \
  --config.limit_by=consumer,ip \
  --config.error_code=429 \
  --config.error_message='{"error":"Rate limit exceeded"}'

# kong.yaml - 声明式配置文件
_format_version: "3.0"

_info:
  defaults: true
  select_tags:
    - production

services:
  # 用户服务
  - name: user-service
    url: http://user-service.default.svc.cluster.local:8081
    routes:
      - name: user-api
        paths:
          - /api/user
        methods:
          - GET
          - POST
          - PUT
        strip_path: true
        plugins:
          - name: cors
            config:
              origins:
                - "*"
              methods:
                - GET
                - POST
                - PUT
                - DELETE
                - OPTIONS
              headers:
                - Accept
                - Authorization
                - Content-Type
              exposed_headers:
                - X-Request-ID
              credentials: true
              max_age: 3600

  # 订单服务
  - name: order-service
    url: http://order-service.default.svc.cluster.local:8083
    routes:
      - name: order-api
        paths:
          - /api/order
        strip_path: true
        plugins:
          - name: key-auth
          - name: rate-limiting
            config:
              minute: 50
              policy: redis
              redis_host: redis.default.svc.cluster.local
              redis_port: 6379
              redis_password: ${REDIS_PASSWORD}
              limit_by: consumer
              error_code: 429
              error_message: '{"error":"Too many requests"}'
          - name: request-transformer
            config:
              add:
                headers:
                  - X-Gateway-Version:3.7.0
                  - X-Request-Time:${request.timestamp}

plugins:
  # 全局 JWT 认证
  - name: jwt
    enabled: true
    protocols:
      - https
    config:
      secret_is_base64: false
      claims_to_verify:
        - exp
        - nbf
      key_claim_name: iss

  # 全局 CORS
  - name: cors
    enabled: true
    config:
      origins:
        - "https://app.example.com"
        - "https://admin.example.com"
      methods:
        - GET
        - POST
        - PUT
        - DELETE
        - OPTIONS
      max_age: 3600

consumers:
  - username: mobile-app
    plugins:
      - name: key-auth
        config:
          key: ${MOBILE_API_KEY}
      - name: acl
        config:
          groups:
            - mobile
      - name: rate-limiting
        config:
          minute: 200

  - username: web-admin
    plugins:
      - name: key-auth
        config:
          key: ${ADMIN_API_KEY}
      - name: acl
        config:
          groups:
            - admin
      - name: rate-limiting
        config:
          minute: 1000

upstreams:
  - name: user-service-upstream
    algorithm: least-connections
    healthchecks:
      active:
        type: http
        http_path: /health
        healthy:
          interval: 10
          successes: 3
        unhealthy:
          interval: 5
          http_failures: 3
    targets:
      - target: user-service-0.user-service:8081
        weight: 100
      - target: user-service-1.user-service:8081
        weight: 100

# 安装 APISIX (Helm)
helm repo add apisix https://charts.apisix.io/
helm repo update

helm install apisix apisix/apisix \
  --namespace apisix \
  --create-namespace \
  --set dashboard.enabled=true \
  --set ingress-controller.enabled=true \
  --set etcd.enabled=true \
  --set etcd.replicaCount=3 \
  --set gateway.type=LoadBalancer \
  --set gateway.http.enabled=true \
  --set admin.credentials.admin=${APISIX_ADMIN_KEY} \
  --set admin.credentials.viewer=${APISIX_VIEWER_KEY}

# apisix-routes.yaml - APISIX 路由配置
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  name: ecommerce-routes
  namespace: default
spec:
  http:
    # 用户服务路由
    - name: user-service-route
      match:
        hosts:
          - api.example.com
        paths:
          - /api/user/*
        methods:
          - GET
          - POST
      backends:
        - serviceName: user-service
          servicePort: 8081
      plugins:
        - name: jwt-auth
          enable: true
          config:
            key: user-jwt-secret
        - name: limit-count
          enable: true
          config:
            count: 100
            time_window: 60
            rejected_code: 429
            key_type: var_combination
            key: remote_addr + consumer_name

    # 订单服务路由 - 金丝雀发布
    - name: order-service-canary
      match:
        hosts:
          - api.example.com
        paths:
          - /api/order/*
      backends:
        - serviceName: order-service-v1
          servicePort: 8083
          weight: 90
        - serviceName: order-service-v2
          servicePort: 8083
          weight: 10
      plugins:
        - name: canary
          enable: true
          config:
            variables:
              - canary-version: v2
        - name: proxy-rewrite
          enable: true
          config:
            regex_uri: ["^/api/order/(.*)", "/$1"]

    # 支付服务路由 - 需要 mTLS
    - name: payment-service-route
      match:
        hosts:
          - internal.example.com
        paths:
          - /api/payment/*
      backends:
        - serviceName: payment-service
          servicePort: 8084
      plugins:
        - name: client-control-mtls
          enable: true
          config:
            ca: |
              -----BEGIN CERTIFICATE-----
              ...CA证书...
              -----END CERTIFICATE-----

# 安装 Envoy Gateway
helm install eg oci://docker.io/envoyproxy/gateway-helm \
  --version v1.1.0 \
  --namespace envoy-gateway-system \
  --create-namespace

# 安装 Gateway API CRDs (如果尚未安装)
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/standard-install.yaml

# envoy-gateway-config.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy-gateway-class
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ecommerce-gateway
  namespace: default
spec:
  gatewayClassName: envoy-gateway-class
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      hostname: "*.example.com"
      allowedRoutes:
        namespaces:
          from: All
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "api.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: api-tls-secret
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: api-routes
  namespace: default
spec:
  parentRefs:
    - name: ecommerce-gateway
      sectionName: https
  hostnames:
    - "api.example.com"
  rules:
    # 用户服务路由
    - matches:
        - path:
            type: PathPrefix
            value: /api/user
      backendRefs:
        - name: user-service
          port: 8081
          weight: 100
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            set:
              - name: X-Source
                value: "envoy-gateway"

    # 订单服务路由 - 带限流
    - matches:
        - path:
            type: PathPrefix
            value: /api/order
      backendRefs:
        - name: order-service
          port: 8083
      extensions:
        filters:
          - type: RateLimitFilter
            rateLimitFilter:
              unit: Minute
              requests: 100