配置文件

本页汇总 AISIX 配置文件结构、常用字段和运行时相关设置。

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

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

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

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

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

下面是自托管 config.yaml 中的常见配置项：

config.yaml
etcd:
  endpoints:                          # 用于存储动态网关资源的 etcd 端点。
    - "http://127.0.0.1:2379"
  prefix: "/aisix"                    # AISIX 在 etcd 中使用的键前缀。
  dial_timeout_ms: 5000               # 建立 etcd 连接的超时时间。
  request_timeout_ms: 5000            # etcd 请求超时时间。
  # tls:                              # 用于保护 etcd 连接的 TLS 或 mTLS 设置。
  #   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" # 可选的 SNI 和证书名称覆盖。

proxy:
  addr: "0.0.0.0:3000"                # 面向调用方代理 API 的监听地址。
  request_body_limit_bytes: 10485760  # 最大请求体大小。示例值为 10 MiB。
  # tls:                              # 代理监听端口使用的 HTTPS 证书和私钥。
  #   cert_file: "/etc/aisix/tls/proxy.crt"
  #   key_file: "/etc/aisix/tls/proxy.key"
  # real_ip:                          # AISIX 位于可信代理之后时的调用方 IP 解析。
  #   trusted_proxies:
  #     - "10.0.0.0/8"
  #   recursive: true
  #   header: "x-forwarded-for"

admin:
  addr: "127.0.0.1:3001"              # Admin API 监听地址。
  admin_keys:                         # 允许调用 Admin API 的密钥。
    - "admin-local-only-change-me"
  # tls:                              # Admin 监听端口使用的 HTTPS 证书和私钥。
  #   cert_file: "/etc/aisix/tls/admin.crt"
  #   key_file: "/etc/aisix/tls/admin.key"

observability:
  service_name: "aisix"               # 遥测中使用的服务名称。
  log_level: "info"                   # 进程日志级别。
  access_log: true                    # 是否输出访问日志。
  metrics:
    prometheus:
      enabled: true                   # 是否暴露 Prometheus 指标。
      path: "/metrics"                # 指标端点路径。
      # addr: "0.0.0.0:9090"          # 可选的专用指标监听地址。
    otlp:
      enabled: false                  # 保留的启动期 OTLP 指标设置。
      endpoint: "http://127.0.0.1:4317"
  tracing:
    otlp:
      enabled: false                  # 保留的启动期 OTLP tracing 设置。
      endpoint: "http://127.0.0.1:4317"
      sample_ratio: 1.0

# managed:                            # 当该网关由 AISIX Cloud 托管时启用。
#   enabled: true

cache:
  backend: "memory"                   # 旧版兼容开关。运行时后端由缓存策略选择。
  # redis:                            # 选择 Redis 的缓存策略使用的 Redis 连接。
  #   mode: "single"
  #   url: "redis://127.0.0.1:6379"
  #   # nodes: ["redis://10.0.0.1:6379"]        # Cluster 模式种子节点。
  #   # sentinels: ["redis://10.0.0.1:26379"]   # Sentinel 模式节点。
  #   # master_name: "mymaster"                  # Sentinel 模式 master 分组。
  #   # username: "default"                      # Cluster 或 Sentinel 数据节点 ACL 用户。
  #   # password: "replace-me"                   # Cluster 或 Sentinel 数据节点 ACL 密码。
  #   # database: 0                              # Sentinel master 数据库索引。
  #   # single 模式下，请将凭证写入 Redis URL。

ratelimit:
  backend: "memory"                   # 限流计数器后端。跨副本共享计数器时请使用 redis。
  # redis:
  #   mode: "single"
  #   url: "redis://127.0.0.1:6379"
  #   # nodes: ["redis://10.0.0.1:6379"]        # Cluster 模式种子节点。
  #   # sentinels: ["redis://10.0.0.1:26379"]   # Sentinel 模式节点。
  #   # master_name: "mymaster"                  # Sentinel 模式 master 分组。
  #   # username: "default"                      # Cluster 或 Sentinel 数据节点 ACL 用户。
  #   # password: "replace-me"                   # Cluster 或 Sentinel 数据节点 ACL 密码。
  #   # database: 0                              # Sentinel master 数据库索引。
  #   # single 模式下，请将凭证写入 Redis URL。
  # concurrency_ttl_secs: 300          # 仅 Redis 后端支持，用于回收过期并发槽位。

# 可选的部署级 AWS Bedrock Guardrails 流量覆盖项。
# 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:0.1.0

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

加载顺序

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

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

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

选择配置文件​

加载顺序​

选择配置文件

加载顺序