跳到主要内容

配置文件

AISIX AI 网关使用启动配置文件定义进程级设置，例如监听端口、etcd 连接、TLS、可观测性、缓存和限流后端，以及托管网关启动配置。

动态资源不在启动配置文件中定义。模型、调用方 API Key、服务提供方密钥、安全护栏、缓存策略和可观测性导出器会存储在 etcd 中，并通过 Admin API 或 AISIX 托管控制面管理。

AISIX 支持 YAML、TOML 或 JSON 启动配置文件。常见文件包括：

  • config.yaml：AISIX 加载的本地启动配置文件。
  • config.example.yaml：完整的自托管示例，可复制或挂载为实际加载的 config.yaml。
  • config.managed.yaml：控制面在运行时提供设置时使用的托管数据面引导配置。

下面示例使用 YAML，因为随包示例配置采用 YAML。TOML 和 JSON 文件也可以定义同样的启动字段。

常用启动配置​

下面的自托管示例使用 etcd，并展示常见启动设置：

config.yaml
etcd:
  endpoints:                          # etcd endpoints used to store dynamic gateway resources.
    - "http://127.0.0.1:2379"
  prefix: "/aisix"                    # Key prefix used by AISIX in etcd.
  # env_id: "ENVIRONMENT_ID"          # Optional environment scope for self-hosted etcd keys.
  # user: "aisix"                     # Optional etcd username.
  # password_env: "AISIX_ETCD_PASSWORD" # Environment variable containing the etcd password.
  dial_timeout_ms: 5000               # Timeout for establishing an etcd connection.
  request_timeout_ms: 5000            # Timeout for etcd requests.
  # tls:                              # TLS or mTLS settings for secure etcd connections.
  #   ca_cert_file: "/etc/aisix/mtls/ca.crt"
  #   client_cert_file: "/etc/aisix/mtls/client.crt"
  #   client_key_file: "/etc/aisix/mtls/client.key"
  #   domain_name: "etcd.example.com" # Optional SNI and certificate-name override.

proxy:
  addr: "0.0.0.0:3000"                # Address for caller-facing proxy APIs.
  request_body_limit_bytes: 10485760  # Maximum request body size. The example value is 10 MiB.
  # tls:                              # HTTPS certificate and key for the proxy listener.
  #   cert_file: "/etc/aisix/tls/proxy.crt"
  #   key_file: "/etc/aisix/tls/proxy.key"
  # real_ip:                          # Caller IP resolution when AISIX runs behind trusted proxies.
  #   trusted_proxies:
  #     - "10.0.0.0/8"
  #   recursive: true
  #   header: "x-forwarded-for"

admin:
  addr: "127.0.0.1:3001"              # Address for the Admin API.
  admin_keys:                         # Keys allowed to call the Admin API.
    - "YOUR_ADMIN_KEY"
  # tls:                              # HTTPS certificate and key for the admin listener.
  #   cert_file: "/etc/aisix/tls/admin.crt"
  #   key_file: "/etc/aisix/tls/admin.key"

observability:
  service_name: "aisix"               # Service name used in telemetry.
  log_level: "info"                   # Process log level.
  access_log: true                    # Whether to emit access logs.
  metrics:
    prometheus:
      enabled: true                   # Whether to expose Prometheus metrics.
      path: "/metrics"                # Metrics endpoint path.
      addr: "0.0.0.0:9090"            # Dedicated metrics listener address.
    otlp:
      enabled: false                  # Reserved startup OTLP metrics settings.
      endpoint: "http://127.0.0.1:4317"
  tracing:
    otlp:
      enabled: false                  # Reserved startup OTLP tracing settings.
      endpoint: "http://127.0.0.1:4317"
      sample_ratio: 1.0

# managed:                            # Enable when this gateway uses the AISIX managed control plane.
#   enabled: true

cache:
  backend: "memory"                   # Legacy compatibility knob. Cache policies choose the runtime backend.
  # redis:                            # Redis connection used by cache policies that select Redis.
  #   mode: "single"
  #   url: "redis://127.0.0.1:6379"
  #   # nodes: ["redis://10.0.0.1:6379"]        # Cluster mode seed nodes.
  #   # sentinels: ["redis://10.0.0.1:26379"]   # Sentinel mode nodes.
  #   # master_name: "mymaster"                  # Sentinel mode master group.
  #   # username: "default"                      # Cluster or Sentinel data-node ACL user.
  #   # password: "replace-me"                   # Cluster or Sentinel data-node ACL password.
  #   # database: 0                              # Sentinel master database index.
  #   # For single mode, put credentials in the Redis URL.

ratelimit:
  backend: "memory"                   # Rate-limit counter backend. Use redis for shared counters across replicas.
  # redis:
  #   mode: "single"
  #   url: "redis://127.0.0.1:6379"
  #   # nodes: ["redis://10.0.0.1:6379"]        # Cluster mode seed nodes.
  #   # sentinels: ["redis://10.0.0.1:26379"]   # Sentinel mode nodes.
  #   # master_name: "mymaster"                  # Sentinel mode master group.
  #   # username: "default"                      # Cluster or Sentinel data-node ACL user.
  #   # password: "replace-me"                   # Cluster or Sentinel data-node ACL password.
  #   # database: 0                              # Sentinel master database index.
  #   # For single mode, put credentials in the Redis URL.
  # concurrency_ttl_secs: 300          # Redis backend only. Reclaims stale concurrency slots.

# Optional deployment-wide override for AWS Bedrock guardrail traffic.
# bedrock_endpoint_url: "https://bedrock-runtime.us-east-1.amazonaws.com"

config.yaml 中的配置会在启动时加载。修改后需要重启网关才会生效。

选择配置文件​

直接运行二进制文件时，可通过 --config 或 AISIX_CONFIG 提供配置路径。

aisix --config config.yaml

运行官方容器镜像时，可以将配置文件挂载到 /etc/aisix/config.yaml，或将 AISIX_CONFIG_PATH 设置为容器内其它路径。

以下示例挂载生产配置文件，并让入口程序加载该文件：

docker run \
  -v "$(pwd)/config.prod.yaml:/etc/aisix/config.prod.yaml:ro" \
  -e AISIX_CONFIG_PATH="/etc/aisix/config.prod.yaml" \
  ghcr.io/api7/aisix:latest

如果未设置 AISIX_CONFIG_PATH，入口程序会使用 /etc/aisix/config.yaml。

加载顺序​

AISIX 按以下顺序加载启动配置：

  1. 内置默认值。
  2. --config 或 AISIX_CONFIG 所选路径中的文件内容。
  3. 以 AISIX_ 为前缀的环境变量覆盖项。

环境变量覆盖项只作用于启动配置字段。覆盖语法和托管网关变量请参见环境变量。