Apache APISIX独立模式：YAML配置文件管理指南

概述

Apache APISIX独立模式（Standalone Mode）是一种无需依赖etcd等外部配置中心的部署方式，通过本地YAML文件管理所有路由规则和配置。这种模式特别适合Kubernetes环境和对配置中心有特殊要求的场景，提供了声明式API配置和热重载能力。

独立模式的核心优势

🔥 热重载机制

APISIX每秒检测配置文件变化，实现无重启配置更新：

sequenceDiagram
    participant User
    participant APISIX
    participant ConfigFile
    
    User->>ConfigFile: 修改apisix.yaml
    Note over ConfigFile: 文件内容变更
    APISIX->>ConfigFile: 每秒检测变化
    ConfigFile-->>APISIX: 返回更新内容
    APISIX->>APISIX: 内存热更新
    APISIX-->>User: 配置生效（无重启）

📊 与传统模式对比

特性	独立模式	传统模式
配置中心	本地YAML文件	etcd
部署复杂度	低	中等
热更新	支持（秒级）	支持
Kubernetes友好	极高	中等
Admin API	禁用	启用

配置独立模式

基础配置

在 conf/config.yaml 中启用独立模式：

deployment:
  role: data_plane
  role_data_plane:
    config_provider: yaml
#END

配置文件结构

所有路由规则存储在 conf/apisix.yaml 文件中，必须包含 #END 标记：

routes:
  -
    uri: /hello
    upstream:
      nodes:
        "127.0.0.1:1980": 1
      type: roundrobin
#END

完整配置示例

路由配置

单路由配置

routes:
  -
    id: route-1
    uri: /api/v1/users/*
    methods: ["GET", "POST"]
    upstream:
      nodes:
        "192.168.1.10:8080": 100
        "192.168.1.11:8080": 50
      type: roundrobin
      retries: 3
      timeout:
        connect: 3s
        send: 10s
        read: 10s
#END

多路由配置

routes:
  -
    uri: /service-a/*
    upstream:
      nodes:
        "10.0.0.1:8080": 1
      type: roundrobin
  
  -
    uri: /service-b/*
    upstream:
      nodes:
        "10.0.0.2:8080": 1
      type: chash
      key: cookie_session
#END

服务与上游分离配置

routes:
  -
    uri: /payment/*
    service_id: payment-service
    plugins:
      limit-count:
        count: 100
        time_window: 60
        key: remote_addr
        rejected_code: 503

services:
  -
    id: payment-service
    upstream_id: payment-upstream

upstreams:
  -
    id: payment-upstream
    nodes:
      "payment-1:8080": 100
      "payment-2:8080": 100
      "payment-3:8080": 100
    type: roundrobin
    checks:
      active:
        type: http
        http_path: /health
        healthy:
          interval: 5s
          successes: 2
        unhealthy:
          interval: 2s
          http_failures: 3
#END

插件配置示例

plugins:
  - name: jwt-auth
  - name: limit-req
  - name: prometheus
  - name: zipkin
    stream: false

routes:
  -
    uri: /secure/api/*
    plugins:
      jwt-auth:
        key: user-key
        secret: my-secret-key
      limit-req:
        rate: 10
        burst: 20
        key: remote_addr
    upstream:
      nodes:
        "secure-backend:8080": 1
      type: roundrobin
#END

SSL证书配置

ssls:
  -
    cert: |
      -----BEGIN CERTIFICATE-----
      MIIDrzCCApegAwIBAgIJAI3Meu/gJVTLMA0GCSqGSIb3DQEBCwUAMG4xCzAJBgNV
      ... (证书内容)
      -----END CERTIFICATE-----
    key: |
      -----BEGIN PRIVATE KEY-----
      MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCf6sMQke4OUrPf
      ... (私钥内容)
      -----END PRIVATE KEY-----
    snis:
      - "api.example.com"
      - "*.example.com"
#END

全局规则配置

global_rules:
  -
    id: global-security
    plugins:
      ip-restriction:
        whitelist:
          - "192.168.0.0/24"
          - "10.0.0.0/8"
      response-rewrite:
        headers:
          X-Frame-Options: "DENY"
          X-Content-Type-Options: "nosniff"
          X-XSS-Protection: "1; mode=block"
#END

环境变量支持

独立模式支持环境变量注入，增强配置灵活性：

routes:
  -
    uri: /dynamic/*
    upstream:
      nodes:
        "${{UPSTREAM_HOST}}:${{UPSTREAM_PORT}}": 1
      type: roundrobin

plugins:
  - name: http-logger
    batch_max_size: 1
    uri: "http://${{LOG_SERVER}}:1980/log"
#END

高级配置模式

插件配置复用

plugin_configs:
  -
    id: rate-limit-config
    plugins:
      limit-req:
        rate: 100
        burst: 200
        key: remote_addr
      limit-count:
        count: 1000
        time_window: 3600
        key: remote_addr

routes:
  -
    uri: /high-traffic/*
    plugin_config_id: rate-limit-config
    upstream:
      nodes:
        "backend:8080": 1
      type: roundrobin
#END

消费者认证配置

consumers:
  -
    username: api-consumer
    plugins:
      key-auth:
        key: consumer-key-123
      rate-limiting:
        rate: 50
        burst: 100

  -
    username: internal-service
    plugins:
      jwt-auth:
        key: internal-key
        secret: internal-secret

routes:
  -
    uri: /protected/*
    plugins:
      key-auth: {}
      consumer-restriction:
        whitelist:
          - api-consumer
          - internal-service
    upstream:
      nodes:
        "protected-backend:8080": 1
      type: roundrobin
#END

监控与调试

健康检查配置

upstreams:
  -
    id: health-checked-upstream
    nodes:
      "server-1:8080": 100
      "server-2:8080": 100
    type: roundrobin
    checks:
      active:
        type: http
        http_path: /health
        timeout: 3s
        healthy:
          interval: 5s
          successes: 2
        unhealthy:
          interval: 2s
          http_failures: 3
      passive:
        type: http
        healthy:
          http_statuses: [200, 201, 202]
          successes: 2
        unhealthy:
          http_statuses: [500, 502, 503, 504]
          http_failures: 3
#END

日志配置

routes:
  -
    uri: /logged-api/*
    plugins:
      http-logger:
        batch_max_size: 10
        batch_timeout: 5
        uri: http://logstash:5044
        include_req_body: true
        include_resp_body: false
    upstream:
      nodes:
        "backend:8080": 1
      type: roundrobin
#END

最佳实践

1. 配置文件组织

# 按功能模块组织配置
routes:
  # 用户服务路由
  - &user-service
    uri: /users/*
    upstream_id: user-upstream
  
  # 订单服务路由  
  - &order-service
    uri: /orders/*
    upstream_id: order-upstream

upstreams:
  - &user-upstream
    id: user-upstream
    nodes:
      "user-service-1:8080": 100
      "user-service-2:8080": 100
  
  - &order-upstream  
    id: order-upstream
    nodes:
      "order-service-1:8080": 100
      "order-service-2:8080": 100

# 全局配置
global_rules:
  - id: security-headers
    plugins:
      response-rewrite:
        headers:
          X-Content-Type-Options: "nosniff"
          X-Frame-Options: "DENY"
#END

2. 环境特定配置

# 开发环境配置
routes:
  -
    uri: /dev-api/*
    upstream:
      nodes:
        "dev-backend:8080": 1
      type: roundrobin
    plugins:
      # 开发环境禁用限流
      # limit-req: 
      #   rate: 1000
      #   burst: 2000

# 生产环境配置（通过环境变量切换）
routes:
  -
    uri: /api/*
    upstream:
      nodes:
        "${{PROD_BACKEND}}:8080": 1
      type: roundrobin
    plugins:
      limit-req:
        rate: 100
        burst: 200
        key: remote_addr
#END

3. 配置验证与调试

APISIX提供配置验证机制，确保YAML文件语法正确：

# 检查配置文件语法
apisix check-config

# 查看当前加载的配置
apisix debug

故障排除

常见问题及解决方案

问题现象	可能原因	解决方案
配置不生效	文件缺少#END标记	确保文件以#END结尾
热重载失败	文件权限问题	检查文件读写权限
语法错误	YAML格式错误	使用yamlint验证语法
环境变量未替换	变量格式错误	使用${{VAR}}格式

调试技巧

# 查看APISIX错误日志
tail -f logs/error.log

# 检查配置加载状态
curl http://127.0.0.1:9080/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'

# 监控配置文件变化
watch -n 1 'stat conf/apisix.yaml'

性能优化建议

1. 文件监控间隔：默认1秒检测，生产环境可适当调整
2. 配置精简：避免不必要的配置项，减少解析时间
3. 批量更新：多个配置变更尽量一次完成
4. 缓存优化：合理使用APISIX内置缓存机制

总结

Apache APISIX独立模式通过YAML配置文件提供了灵活、高效的配置管理方案，特别适合云原生环境和需要声明式配置的场景。掌握YAML配置文件的正确使用方法和最佳实践，能够充分发挥APISIX的性能优势，构建稳定可靠的API网关服务。

通过本文的详细指南，您应该能够：

• 理解独立模式的工作原理和优势
• 掌握各种配置项的编写方法
• 实现生产环境的配置最佳实践
• 快速排查和解决配置相关问题

独立模式让APISIX配置管理变得更加简单和可控，是现代化微服务架构的理想选择。