配置文件

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 端点。
    - "http://127.0.0.1:2379"
  prefix: "/aisix"                    # AISIX 在 etcd 中使用的 Key 前缀。
  # env_id: "ENVIRONMENT_ID"          # 自托管 etcd Key 的可选环境作用域。
  # user: "aisix"                     # 可选的 etcd 用户名。
  # password_env: "AISIX_ETCD_PASSWORD" # 包含 etcd 密码的环境变量。
  dial_timeout_ms: 5000               # 建立 etcd 连接的超时时间。
  request_timeout_ms: 5000            # 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 的 Key。
    - "YOUR_ADMIN_KEY"
  # 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 链路追踪设置。
      endpoint: "http://127.0.0.1:4317"
      sample_ratio: 1.0

# managed:                            # 网关使用 AISIX 托管控制面时启用。
#   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 模式的主节点组。
  #   # username: "default"                      # Cluster 或 Sentinel 数据节点的 ACL 用户。
  #   # password: "replace-me"                   # Cluster 或 Sentinel 数据节点的 ACL 密码。
  #   # database: 0                              # Sentinel 主节点的数据库索引。
  #   # 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 模式的主节点组。
  #   # username: "default"                      # Cluster 或 Sentinel 数据节点的 ACL 用户。
  #   # password: "replace-me"                   # Cluster 或 Sentinel 数据节点的 ACL 密码。
  #   # database: 0                              # Sentinel 主节点的数据库索引。
  #   # single 模式下，请将凭证放在 Redis URL 中。
  # concurrency_ttl_secs: 300          # 仅适用于 Redis 后端，用于回收过期的并发槽位。

upstream:                             # 向模型服务提供方发起出站调用的连接层。以下为默认值。
  pool_idle_timeout_secs: 30          # 应低于网关与模型服务提供方之间最短的空闲超时。
  # connect_timeout_ms: 5000          # DNS、TCP 和 TLS 的时间预算。0 表示禁用。
  # tcp_keepalive_secs: 60            # 首次 Keepalive 探测前的空闲时间。0 表示禁用。
  # tcp_keepalive_interval_secs: 30   # Keepalive 探测间隔。
  # tcp_keepalive_retries: 5          # 丢弃连接前允许的未确认探测次数。
  # pool_max_idle_per_host: 32        # 每个上游主机的空闲连接上限。未设置表示不限制。

downstream:                           # 接收客户端入站调用的连接层。以下为默认值。
  idle_timeout_secs: 0                # 关闭两次请求间空闲的连接。0 表示从不关闭。
  # sse_keepalive_interval_secs: 15   # 静默流式响应的心跳间隔。0 表示禁用。

# 可选的部署级 AWS Bedrock 安全护栏流量覆盖项。
# bedrock_endpoint_url: "https://bedrock-runtime.us-east-1.amazonaws.com"

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

调整上游连接层

upstream 配置块控制网关如何打开并复用到模型服务提供方的连接。默认值适合直接通过互联网访问服务提供方的网关。当网关位于负载均衡器、NAT 网关、企业代理或服务网格之后时，请调整这些设置。

应首先检查 pool_idle_timeout_secs。网关会复用池化连接，因此该值必须低于到模型服务提供方的路径上任何位置的最短空闲超时。如果中间跳点先于网关关闭空闲连接，连接池最终会分配一个已被远端关闭的连接，使访问健康模型服务提供方的请求也发生传输错误。

当较慢的模型尚未生成首 Token 时，TCP Keepalive 可让相同中间跳点继续感知该连接。否则，NAT 或负载均衡器的空闲计时器可能清除正在合法等待长耗时请求的连接。

每个时长字段都接受 0，用于单独关闭对应设置。

调整下游连接层

downstream 配置块与 upstream 对称，用于控制网关接受的客户端连接，或接受来自其前方网关的连接。

idle_timeout_secs 会关闭在两次请求之间处于空闲状态的连接，即响应已完整写入且下一请求尚未开始。进行中的请求无论模型耗时多久都不会中断，流式响应也不会。相同的截止时间还会限制新连接在发送第一个请求行和请求头前可以等待多久，因此应显著高于最慢客户端的往返时延。

默认值为 0，表示永不关闭空闲连接，而将决定权交给对端。该默认值是有意设置的。网关前方的组件会维护自己的连接池；先关闭连接的节点会使对端仍将该连接视为可用，这与出站方向中 pool_idle_timeout_secs 所避免的故障相同。如果设置 idle_timeout_secs，请让它高于前方节点的连接池空闲超时，并仅在需要回收空闲连接时设置。

sse_keepalive_interval_secs 会在模型尚未产生任何内容时，向流式响应发送 SSE 注释。如果没有此心跳，首 Token 较慢的模型会被客户端与网关之间的代理误认为连接已放弃。所有符合规范的 SSE 客户端都会忽略该注释，此设置适用于所有流式端点。

两项设置同时适用于代理监听器和 Admin 监听器。idle_timeout_secs 适用于 HTTP/1.1 连接。

各超时设置之间的关系

以下每项设置限制请求的不同阶段，不能互相替代。

设置	位置	限制的阶段
upstream.connect_timeout_ms	启动配置	发送请求前，与模型服务提供方之间的 DNS、TCP 和 TLS。
upstream.pool_idle_timeout_secs	启动配置	响应完成后，到模型服务提供方的未使用连接在池中保留多久。
downstream.idle_timeout_secs	启动配置	已接受的客户端连接在没有请求时保持打开多久。
timeout	模型	从发送到最后一个字节的完整上游调用。
stream_timeout	模型	流式响应两个分块之间的间隔，包括等待第一个分块以及之后的每次间隔；每个分块都会重置计时器。它不是流总时长上限。

两个连接池设置负责连接复用，模型设置限制正在进行的请求。TCP Keepalive 是网络层存活探测，不限制请求层的任何阶段。

对于网关链路，每个跳点都遵循同一规则：一个节点的客户端侧空闲超时必须留有余量地低于下一节点的服务器侧空闲超时。违反这一顺序会导致健康路径偶发传输错误。

选择配置文件

直接运行二进制文件时，可通过 --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_ 为前缀的环境变量覆盖项。

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