跳到主要内容

启动配置参考

本参考介绍用于定义监听器、资源来源连接、TLS、可观测性、缓存和限流后端以及 AISIX Cloud 连接等进程级设置的启动配置文件。

模型、调用方 API Key、服务提供方密钥、安全护栏、缓存策略和可观测性导出器不在启动配置中定义。对于开源 AISIX 网关，这些资源由 resources.yaml 文件或 etcd 提供；对于连接到 AISIX Cloud 的网关，则由控制面提供。

AISIX 接受 YAML、TOML 或 JSON 格式的启动配置文件。常见文件包括：

  • config.yaml：AISIX 加载的本地启动配置文件。
  • config.example.yaml：不使用控制面、以配置存储为后端的完整网关示例，可复制或挂载为实际加载的 config.yaml。
  • config.managed.yaml：AISIX Cloud 在运行时提供资源时使用的网关引导配置。

下列示例使用 YAML，因为打包的示例配置采用 YAML。TOML 和 JSON 文件也可以定义相同的启动字段。面向任务的设置流程请参见启动配置。

配置模式​

每台 AISIX 网关都使用启动配置文件。管理模式决定动态资源来自何处，以及哪些设置由运维人员直接管理。

网关配置资源来源选择方式变更到达方式
使用资源文件的开源 AISIX 网关声明式文件resources_file启动时加载，并在收到 SIGHUP 时重新加载。
使用配置存储的开源 AISIX 网关自行管理的 etcd 集群etcd首次同步后持续接收 etcd Watch 事件。
连接到 AISIX Cloud 的 AISIX 网关AISIX Cloud 控制面managed.enabled: true 和生成的连接设置网关通过托管的 etcd 连接接收控制面投影的资源。

无论使用哪种模式，代理、下游、上游、缓存、限流后端和本地可观测性设置仍属于网关启动设置。AISIX Cloud 提供模型、Key、策略和导出器等动态资源，但不会替换这些进程级设置。

对于开源 AISIX 网关，admin.enabled 默认为 true，但默认的 admin.addr 值 127.0.0.1:0 无法用作监听地址。要公开只读 Admin API，请将 admin.addr 设置为私有地址或回环地址，并至少配置一个 admin.admin_keys 值。将 admin.enabled 设置为 false 可禁用监听器。请通过资源文件或直接写入 etcd 来配置资源。连接到 AISIX Cloud 的网关绝不会绑定网关 Admin API。

常用启动配置​

以下示例展示使用 etcd 的开源 AISIX 网关以及常见启动设置。网关也可以改为通过 resources_file 加载动态资源；请参阅资源来源。

config.yaml
etcd:
  endpoints:                          # 用于存储动态网关资源的 etcd 端点。
    - "http://127.0.0.1:2379"
  prefix: "/aisix"                    # AISIX 在 etcd 中使用的 Key 前缀。
  # env_id: "ENVIRONMENT_ID"          # etcd 中网关资源的可选环境范围。
  # 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: 0       # 请求体大小上限。默认值 0 表示不限制：服务提供方接受的请求
                                      # 可能大于任何固定网关默认值（Anthropic 接受 32 MB），因此
                                      # 网关侧固定上限会拒绝原本可由上游处理的请求。设置字节数可限制
                                      # 单请求内存；超限请求会以调用方对应的错误信封返回 413。
                                      # 升级说明：早期版本默认值为 10485760（10 MiB）。如果网关
                                      # 直接接收不受信任客户端的请求，请在此设置值，或在网关前的
                                      # Load Balancer/Ingress 上执行请求体大小限制。
  # thread_per_core: true             # 使用各自拥有监听器和上游连接池的独立 Worker 提供服务。
                                      # 省略时，在 Linux 上启用，在其他平台关闭。设为 false 可使用
                                      # 单个共享运行时。启动时应用，更改后需要重启。
                                      # 请参阅“部署 > 每核一线程 Worker”。
  # workers: 4                        # 任一服务模式下的代理 Worker 线程数。省略时会跟随进程
                                      # 可用的并行度，因此容器 CPU limit 或 taskset CPU 亲和性
                                      # 掩码都可以确定其大小。最小值为 1。启动时应用。
  # 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"
  # url_rewrites:                     # 路由前在入口级重写路径（第一条匹配规则生效）。
  #   - name: per-server-mcp-compat   # 网关日志中使用的可选标签。
  #     match: "^/mcp-servers/([^/]+)/mcp$"  # 针对原始请求路径的正则表达式。
  #     rewrite: "/mcp/$1"            # 替换匹配部分；规则错误会导致启动失败。
  #                                   # 完整语义请参阅“部署 > URL 重写”。

admin:
  enabled: false

observability:
  service_name: "aisix"               # 遥测数据中使用的服务名称。
  log_level: "info"                   # 进程日志级别。
  metrics:
    prometheus:
      enabled: true                   # 是否暴露 Prometheus 指标。
      path: "/metrics"                # 指标端点路径。
      addr: "0.0.0.0:9090"            # 专用指标/状态监听地址。

# managed:                            # 网关使用 AISIX Cloud 控制面时启用。
#   enabled: true

# cache:                              # 选择 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          # 应低于网关与服务提供方之间最短的空闲超时。
  # timeout_ms: 6000000               # 模型及其组/路由器均未设置 timeout 时的默认请求截止时间（6000 秒）。0 表示禁用兜底值。
  # stream_timeout_ms: 0              # 默认流式分块间隔截止时间。0 表示回退到 timeout_ms。
  # retries: 2                        # 模型及其组/路由器均未设置 retries 时，可重试失败后的尝试次数。0 表示禁用重试。
  # 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        # 每个上游主机的空闲连接上限。未设置表示不限制。
                                      # 对 Worker 本地连接池的每个 Worker 分别生效。
  # tls:                              # 网关执行出站调用时信任的证书。
  #   ca_file: "/etc/aisix/tls/private-ca.pem"    # 除平台自身 CA 外额外信任的 CA。
  #   client_cert_file: "/etc/aisix/tls/client.crt"  # 用于要求 mTLS 的上游。
  #   client_key_file: "/etc/aisix/tls/client.key"   # 必须与 client_cert_file 一起提供。
  #   verify: true                    # false 表示接受任意证书，仅用于测试环境。

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"

启动配置的更改会在网关重启后生效。

调整上游连接层​

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

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

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

在 Linux 上默认启用的每核一线程服务模式中，普通代理调度使用 Worker 本地连接池，pool_max_idle_per_host 对每个 Worker 分别生效。因此，一个进程到单个主机的空闲连接数最多可达到该上限乘以 proxy.workers。使用专用客户端的请求路径（例如配置了自定义 TLS 的服务提供方密钥）会保留独立的进程级连接池，不计入该倍数。有关服务模式及其容量规划影响，请参阅每核一线程 Worker。

timeout_ms 和 stream_timeout_ms 是每个模型 timeout 和 stream_timeout 字段的部署级默认值。请求会使用第一个已设置值：目标模型、请求所经由的路由模型或语义路由器、最后是这些默认值。6000 秒默认值是防止请求永久挂起的兜底值，并非响应速度目标；它确保已经接受连接却永久静默的上游不能无限占用请求，同时不会截断合法的长耗时请求（深度推理调用可能超过十分钟；如需更严格限制，请设置每个模型的 timeout）。模型可通过 timeout: 0 跳过兜底值；设置 timeout_ms: 0 会移除部署级默认值。

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

upstream.tls 决定网关在这些连接上信任哪些证书。它覆盖请求的所有出站路径：模型端点、安全护栏服务、MCP 与 A2A 上游、OIDC Discovery、Realtime WebSocket、Amazon Bedrock 和日志导出。

如果上游证书由私有或企业 CA 签发，请设置 ca_file。这些 CA 会在平台自身 CA 之外额外受信任，因此公共服务提供方仍可访问。各端点的信任、mTLS 和 Redis 后端设置请参见 TLS 与 mTLS。

调整下游连接层​

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

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

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

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

这两个设置都适用于代理监听器。idle_timeout_secs 适用于 HTTP/1.1 连接。

各超时设置之间的关系​

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

设置位置限制的阶段
upstream.connect_timeout_ms启动配置发送请求前，与服务提供方之间的 DNS、TCP 和 TLS。
upstream.timeout_ms启动配置模型与其所经由的路由模型/语义路由器均未设置 timeout 时的默认值。
upstream.stream_timeout_ms启动配置stream_timeout 的默认值；0 表示回退到 upstream.timeout_ms。
upstream.pool_idle_timeout_secs启动配置响应完成后，到服务提供方的未使用连接在池中保留多久。
downstream.idle_timeout_secs启动配置已接受的客户端连接在没有请求时保持打开多久。
timeout模型从发送到最后一个字节的完整上游调用，依次从模型、路由模型/语义路由器、upstream.timeout_ms 解析；模型上的 0 表示禁用。
stream_timeout模型流式响应两个分块之间的间隔，包括等待第一个分块和之后的每次间隔；每个分块都会重置计时器。它不是流总时长上限。值为 0 或未设置时，依次回退到组/路由器级的 stream_timeout、timeout，再到部署默认值。

两个连接池设置管理连接复用；模型设置限制正在处理的请求。TCP keepalive 是网络层活性探测，不会限制请求层的任何阶段。

通用代理用户通常会寻找 connect/send(write)/read 三种超时。对应关系如下：connect_timeout_ms 是连接超时；stream_timeout 是流式响应的读取超时（同样采用分块间隔语义），非流式响应则使用更严格的端到端 timeout。系统没有单独的发送超时，因为停滞的请求上传已经受相同的端到端或流式预算限制，未确认的发送还会更早在 TCP 层中断。通用代理需要三个设置，是因为它没有每请求截止时间概念；网关具备该概念，因此可以用更少的设置覆盖同一需求。

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

资源来源​

请只配置一个资源来源。来源选择会影响资源的加载方式，但不会改变面向调用方的代理 API。

资源文件​

开源 AISIX 网关只会从一个来源读取动态资源。设置 resources_file 可从声明式资源文件加载这些资源：

config.yaml
resources_file: /etc/aisix/resources.yaml

resources_file 与 etcd 配置互斥，同时配置会导致启动失败。resources_file 也不能与 managed.enabled: true 组合使用，因为连接到 AISIX Cloud 的网关会从控制面接收资源。

设置 resources_file 后，网关会在启动时加载该文件，并在收到 SIGHUP 时重新加载。所有资源类型和字段请参见资源文件参考。操作流程请参见开源 AISIX 网关快速入门，验证或 etcd 导出请参见 CLI 参考。配置状态会显示运行中的网关加载了哪些内容。

etcd 配置存储​

当配置自动化直接向 etcd 写入资源时，请设置 etcd.endpoints：

config.yaml
etcd:
  endpoints:
    - "https://etcd.example.com:2379"
  prefix: "/aisix"
  dial_timeout_ms: 5000
  request_timeout_ms: 5000
  tls:
    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"
字段必填说明
etcd.endpoints是一个或多个 etcd 端点。未设置 resources_file 时，开源 AISIX 网关必须配置此字段。
etcd.prefix否包含 AISIX 资源的 Key 前缀。默认为 /aisix；共享资源的网关必须使用相同前缀。
etcd.env_id否写入方使用环境范围 Key 时，Key 布局中包含的环境范围。
etcd.user否etcd 用户名。
etcd.password_env否包含 etcd 密码的环境变量名称。
etcd.dial_timeout_ms否建立连接的超时时间。默认为 5000。
etcd.request_timeout_ms否etcd 请求超时时间。默认为 5000。
etcd.tls否mTLS 连接的客户端 CA、证书、密钥以及可选的服务器名称覆盖项。三个证书文件字段必须同时提供。

从现有配置存储迁移到资源文件时，请使用 aisix export。

AISIX Cloud​

网关从 AISIX Cloud 接收资源时，请将 managed.enabled 设置为 true。请使用生成的网关安装代码片段，不要手动组合引导值；它会为所选环境提供正确的控制面端点和证书材料。

config.yaml
managed:
  enabled: true
  cp_base_url: "https://aisix.example.com"
  cp_etcd_endpoint: "aisix.example.com:443"
  mtls_dir: "/var/lib/aisix/mtls"
  dp_id_file: "/var/lib/aisix/dp_id"
  snapshot_cache_path: "/var/lib/aisix/config_cache.json"
  heartbeat_interval_secs: 15

连接证书、私钥和 CA 可以作为一组完整的内联字段（cp_cert_pem、cp_key_pem 和 cp_ca_pem）提供，也可以作为一组完整的文件路径字段（cp_cert_file、cp_key_file 和 cp_ca_file）提供。请勿在同一组凭证中混用内联和文件形式。请将凭证材料保存在环境变量或挂载的 Secret 文件中，不要提交到启动配置。

字段必填说明
managed.enabled是启用 AISIX Cloud 连接并禁用网关 Admin API 监听器。
managed.cp_base_url是用于心跳、遥测、证书轮换和预算检查的 AISIX Cloud 控制面 Origin。
managed.cp_etcd_endpoint否采用 host:port 形式的显式托管 etcd 端点。省略时，AISIX 会从 cp_base_url 派生。
managed.cp_ca_cert_file否控制面 HTTP 和 etcd TLS 连接使用的额外 CA 证书包，本地部署控制面使用私有 CA 时通常需要。
managed.mtls_dir否AISIX 用于持久化生成的 mTLS 证书包的目录。默认为 /var/lib/aisix/mtls。
managed.dp_id_file否AISIX 持久化网关 ID 的文件。默认为 /var/lib/aisix/dp_id。
managed.snapshot_cache_path否控制面中断和重启期间使用的最后已知配置缓存。连接到 AISIX Cloud 时默认为 /var/lib/aisix/config_cache.json；设置为空字符串可禁用。
managed.heartbeat_interval_secs否心跳间隔秒数。默认为 15，并限制在 5–300 范围内。

托管连接在配置状态中显示为 source.type: "etcd"，因为网关会通过托管配置存储连接使用控制面投影的资源。有关证书签发和安装流程，请参阅连接 AISIX 网关。这些字段的环境变量形式请参阅 AISIX Cloud 连接变量。

选择配置文件​

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

环境变量覆盖项只作用于启动配置字段。覆盖语法和 AISIX Cloud 连接变量请参见环境变量。