启动配置参考
本参考介绍用于定义监听器、资源来源连接、TLS、可观测性、缓存和限流后端以及托管连接等进程级设置的启 动配置文件。
模型、调用方 API Key、服务提供方密钥、安全护栏、缓存策略和可观测性导出器不在启动配置中定义。对于开源 AISIX 网关，这些资源由 resources.yaml 文件或 etcd 提供；对于连接到 AISIX Enterprise 或 AISIX Cloud 的网关，则由控制面提供。
AISIX 接受 YAML、TOML 或 JSON 格式的启动配置文件。常见文件包括：
config.yaml：AISIX 加载的本地启动配置文件。config.example.yaml：不使用控制面、以配置存储为后端的完整网关示例，可复制或挂载为实际加载的config.yaml。config.managed.yaml：控制面在运行时提供资源时使用的网关引导配置。
下列示例使用 YAML，因为打包的示例配置采用 YAML。TOML 和 JSON 文件也可以定义相同的启动字段。面向任务的设置流程请参见启动配置。
配置模式
每台 AISIX 网关都使用启动配置文件。管理模式决定动态资源来自何处，以及哪些设置由运维人员直接管理。
| 网关配置 | 资源来源 | 选择方式 | 变更到达方式 |
|---|---|---|---|
| 使用资源文件的开源 AISIX 网关 | 声明式文件 | resources_file | 启动时加载，并在收到 SIGHUP 时重新加载。 |
| 使用配置存储的开源 AISIX 网关 | 自行管理的 etcd 集群 | etcd | 首次同步后持续接收 etcd Watch 事件。 |
| 连接到 AISIX Enterprise 或 AISIX Cloud 的 AISIX 网关 | 控制面 | managed.enabled: true 和生成的连接设置 | 网关通过托管的 etcd 连接接收控制面投影的资源。 |
无论使用哪种模式，代理、下游、上游、缓存、限流后端和本地可观测性设置仍属于网关启动设置。控制面提供模型、Key、策略和导出器等动态资源，但不会替换这些进程级设置。
对于开源 AISIX 网关，admin.enabled 默认为 true。默认的 admin.addr 值 127.0.0.1:0 会在回环地址上选择临时端口，不提供固定的可发现端口。要公开只读 Admin API，请将 admin.addr 设置为带固定端口的私有地址或回环地址，并至少配置一个 admin.admin_keys 值。将 admin.enabled 设置为 false 可禁用监听器。请通过资源文件或直接写入 etcd 来配置资源。连接到 AISIX Enterprise 或 AISIX Cloud 的网关绝不会绑定网关 Admin API。
常用启动配置
以下示例展示使用 etcd 的开源 AISIX 网关以及常见启动设置。网关也可以改为通过 resources_file 加载动态资源；请参阅 资源来源。
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 的单次连接尝试——TCP 连接、TLS 握手和认证交互。
# 默认 5000；显式写 0 表示不施加超时。
# request_timeout_ms: 5000 # 可选，限制单次 etcd 请求-响应调用（含配置读取）的时间。不设置
# 和 0 都表示不施加超时。设置前请先阅读「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 表示不限制。
# 设置字节数可限制单请求内存。拒绝行为请参阅下文
# “限制请求体大小”。
# thread_per_core: true # 使用各自拥有监听器和上游连接池的独立 Worker 提供服务。
# 省略时，在 Linux 上启用，在其他平台关闭。设为 false 可使用
# 单个共享运行时。启动时应用，更改后需要重启。
# 请参阅“部署 > 每核一线程 Worker”。
# workers: 4 # 任一服务模式下的代理 Worker 线程数。省略时会跟随进程
# 可用的并行度，因此容器 CPU limit 或 taskset CPU 亲和性
# 掩码都可以确定其大小。最小值为 1。启动时应用。
# tls: # addr 所描述的那一个监听器的 HTTPS 证书和密钥。
# cert_file: "/etc/aisix/tls/proxy.crt"
# key_file: "/etc/aisix/tls/proxy.key"
# listeners: # 多个代理监听器，每个有各自可选的 TLS——用于需要同时提供
# HTTPS 和明文 HTTP 的部署。一旦设置，它就是代理监听器的
# 完整集合：只有这些地址会被绑定，上面的 addr 会被忽略
#（它仍是必填字段，网关会在启动时记录一行日志说明这一点），
# 并且上面的 tls 必须不存在。每个监听器提供相同的路由和配置。
# 规则和环境变量写法参阅 部署 > TLS 与 mTLS。
# - addr: "0.0.0.0:3443"
# tls:
# cert_file: "/etc/aisix/tls/proxy.crt"
# key_file: "/etc/aisix/tls/proxy.key"
# - addr: "0.0.0.0:3000"
# 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" # 遥测数据中使用的服务名称，包括 OTLP 的 service.name。
log_level: "info" # 进程日志级别。
access_log: true # 每个请求写一行访问日志（info 级别）。设为 false 关闭。
metrics:
prometheus:
enabled: true # 是否暴露 Prometheus 指标。
path: "/metrics" # 指标端点路径。
addr: "0.0.0.0:9090" # 专用指标/状态监听地址。
# debug: # 提供 GET /debug/pprof/heap 的诊断监听器。
# enabled: true # 无身份认证，请保持绑定在回环地址。
# addr: "127.0.0.1:9091" # 绑定失败只记录日志，不会阻止网关启动。
# heap_profiling:
# auto_dump: # 内存接近内存上限时自动写出堆 profile。
# enabled: true
# thresholds: [0.8, 0.9] # 内存上限的比例，每个值须在 (0, 1] 内。
# dir: "/var/lib/aisix/heap" # 不存在时自动创建。请使用在重启后仍保留的卷。
# keep: 5 # 每个主机名保留的 profile 数量，至少为 1。
# # 参见 可观测性 > 内存诊断。
# managed: # 网关使用控制面时启用。
# 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" # Redis ACL 用户，所有模式生效；覆盖 URL 中的凭据。
# # password: "replace-me" # Redis ACL 密码，所有模式生效；覆盖 URL 中的凭据。
# # database: 0 # 数据库索引，single 和 sentinel 模式生效。
# # timeout_secs: 5 # 约束一次 Redis 往返和一次连接尝试，最小值为 1。
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" # Redis ACL 用户，所有模式生效；覆盖 URL 中的凭据。
# # password: "replace-me" # Redis ACL 密码，所有模式生效；覆盖 URL 中的凭据。
# # database: 0 # 数据库索引，single 和 sentinel 模式生效。
# # timeout_secs: 5 # 约束一次 Redis 往返和一次连接尝试，最小值为 1。
# concurrency_ttl_secs: 300 # Redis 租约 TTL；活跃流会续约其槽位。
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 的时间预算。在 /v1/realtime 上还
# 覆盖 WebSocket 升级握手。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 且受支持的 HTTP 上游。
# client_key_file: "/etc/aisix/tls/client.key" # 必须与 client_cert_file 一起提供。
# verify: true # false 表 示在受支持的位置禁用验证，仅用于测试环境。
# media_fetch: # 下载上游无法自行读取的 Chat 媒体 URL。
# enabled: true # false 表示改为以 400 拒绝这类 URL。
# max_bytes: 52428800 # 每个 URL 的最大下载量（50 MiB）。
# 参见“服务提供方兼容性 > 原生服务提供方的媒体内容”。
# bedrock:
# mantle_endpoint: null # Bedrock Mantle 基础 URL，用于 bedrock-runtime 拒绝计数的
# Claude Token 计数。null 表示按服务提供方密钥 的区域推导为
# https://bedrock-mantle.<region>.api.aws。VPC 端点或 GovCloud 时设置。
# outbound: # 访问 API 调用方提供的 URL 的请求，例如媒体下载。
# ssrf_protection: # 服务端请求伪造（SSRF）防护。
# enabled: true # false 表示关闭地址检查，此时忽略 allowed_hosts。
# allowed_hosts: [] # 即使解析到非公网地址也允许访问的主机。
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"
启动配置的更改会在网关重启后生效。
限制请求体大小
proxy.request_body_limit_bytes 默认为 0，表示网关侧不设上限。服务提供方接受的请求可能大于任何单一固定默认值，因此设置上限可能会拒绝原本可由所选服务提供方处理的请求。早期 AISIX 版本的默认值为 10485760 字节（10 MiB）。
如果网关直接接受来自不受信任客户端的请求，并且必须限制单请求内存，请设置一个字节数。也可以在网关前的负载均衡器或 Ingress 上实施请求体大小限制。
该上限同样覆盖网关为请求下载的媒体 URL：下载的字节与入站请求体一起计算，合计超过上限的请求会得到同样的 413。参见原生服务提供方的媒体内容。
未超过上限的请求在等待上游期间同样保留在内存中，约为其请求体大小的两倍。参见为大请求体规划内存。
AISIX 会以 413 Content Too Large 拒绝超限请求，但不保证调用方一定能收到该响应。对于声明了超限 Content-Length 的请求，AISIX 会先排空请求体，以便在同一连接上返回 413。排空操作受字节数和时间限制；如果调用方未能在限制内发送完毕，网关会停止读取，此时调用方通常看到连接关闭或重置。分块请求体会在处理程序读取时被拒绝，不使用同一排空路径。
在 Content-Length 路径上，aisix::body_limit 日志条目和 aisix_proxy_request_body_limit_rejections_total 可区分排空完成、达到上限、超时或客户端读取错误。有关字段与关联分析流程，请参阅访问日志与请求关联。
调整上游连接层
upstream 配置块控制网关发起出站调用时如何打开并复用连接。默认值适合直接通过互联网访问服务提供方的网关。当网关位于负载均衡器、NAT 网关、企业代理或服务网格之后时，请调整这些设置。
它的作用范围不止服务提供方的 HTTP 调用。网关为 Amazon Bedrock 构建的 AWS SDK 客户端——模型服务提供方路径和 Amazon Bedrock 安全护栏——网关为 /v1/realtime 打开的 Realtime WebSocket，以及把遥测数据导出到 S3、Google Cloud Storage 和 Azure Blob Storage 的对象存储导出器，同样受这些设置控制。私有化部署的 MinIO 或内网 S3 兼容存储，与网关其余出站流量处在同一个私有 CA 之后、跨越同样的负载均衡和 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 会移除部署级默认值。
值为零时的行为因字段而异。upstream.timeout_ms: 0 会移除部署级请求截止时间，模型上的 timeout: 0 会停止该请求超时的回退链。相比之下，upstream.stream_timeout_ms: 0 会回退到 upstream.timeout_ms，而模型上的 stream_timeout: 0 会继续回退到剩余的流超时和请求超时链。因此，流超时值为零时仍可能存在有效的流式截止时间。
各设置作用于哪些出站路径
网关的出站客户端建立在不止一种 HTTP 栈之上，而这些栈暴露的可调项并不相同。某项设置在某个栈上没有对应入口时，它在那里不会生效，也不会报错。
| 设置 | 服务提供方 HTTP 调用 | Amazon Bedrock（模型服务提供方与安全护栏） | Realtime WebSocket（/v1/realtime） | 对象存储导出器（S3、GCS、Azure） |
|---|---|---|---|---|
connect_timeout_ms | 生效 | 生效 | 生效，且覆盖的拨号阶段更多——见下文 | 生效 |
pool_idle_timeout_secs | 生效 | 生效 | 不适用——每个会话各自拨号，不存在连接池 | 生效，但取值 0 例外——见下文 |
pool_max_idle_per_host | 生效 | 不生效——AWS SDK 的连接构建器没有对应项 | 不适用——原因同上 | 生效 |
tcp_keepalive_secs、tcp_keepalive_interval_secs、tcp_keepalive_retries | 生效 | 不生效——原因同上 | 不生效——WebSocket 拨号不设置套接字选项 | 不生效——对象存储客户端没有对应项 |
timeout_ms、stream_timeout_ms | 生效 | 生效（由网关而非传输层执行） | 作为事件之间的会话空闲上限生效，而非请求截止时间 | 不适用——这两项约束的是模型请求 |
tls.ca_file | 生效 | 生效 | 生效 | 生效 |
tls.client_cert_file、tls.client_key_file | 生效 | 不生效——首次构建 Bedrock 客户端时打印 WARN | 不生效——WebSocket 客户端不出示证书 | 不生效 |
tls.verify | 生效 | 不生效——证书仍会被校验；首次构建 Bedrock 客户端时打印 WARN | 生效 | 生效 |
有三行值得单独说明，因为在这几处，符合直觉的预期恰好是错的：
- **
connect_timeout_ms在 Realtime 拨号上覆盖的阶段比别处更多。**在其他所有路径上，这份预算到 TLS 结束为止，也就是发送请求之前。在/v1/realtime上，它还覆盖 HTTP 101 升级交互，因为这段拨号没有别的截止时间——会话空闲上限要等套接字建立之后才开始计时。因此，完成 TLS 之后却始终不回应升级的上游会在connect_timeout_ms处失败，而不是把客户端连接一直挂到内核放弃重试。失败走的是原本处理上游不可达的同一分支：向客户端发送类型为upstream_error的error事件、以1011关闭连接，并在访问日志和用量记录中记为502。 - **
tcp_keepalive_*到不了对象存储导出器。**如果你调 keepalive 是为了让导出到内网 MinIO 的连接扛住 NAT 或负载均衡器的空闲计时器，这些设置在那里不起作用，也不会有任何告警。请改为调整网络跳点，或者调整导出器自身的批量发送间隔。 - **
pool_idle_timeout_secs: 0在两条路径上含义不同。**在服务提供方 HTTP 调用上，0表示池化连接永不过期。对象存储客户端无法表达这个语义，因此0会让它保持 90 秒的客户端默认值。这个方向是偏保守的——连接仍会被回收——但 它确实是一处差异，所以在分析导出器行为时不要把0理解成「永不过期」。
Bedrock 那两行 tls 是全表唯一会打印警告的单元格，因为「关闭校验或配置了双向 TLS，却静默地没有生效」属于安全相关的意外。其余各项都是静默的。
upstream.tls 提供出站连接的部署级 TLS 设置。ca_file 适用于 HTTP 请求路径、Realtime WebSocket、Amazon Bedrock 和对象存储导出；客户端证书和验证设置支持的传输范围更窄。
如果上游证书由私有或企业 CA 签发，请设置 ca_file。这些 CA 会在平台自身 CA 之外额外受信任，因此公共服务提供方仍可访问。有关支持矩阵、各端点的信任、mTLS 和 Redis 后端设置，请参见 TLS 与 mTLS。
upstream.media_fetch 控制网关如何为无法自行读取 URL 的上游（例如 Amazon Bedrock）下载 Chat 请求中的图片、音频或文件 URL。除非 NO_PROXY 覆盖该主机，下载会经过 HTTPS_PROXY、HTTP_PROXY 和 ALL_PROXY 环境变量，并按 upstream.tls 校验证书。
outbound.ssrf_protection 决定访问 API 调用方所提供 URL 的请求可以到达哪些地址，目前即媒体下载。enabled 为 true（默认值）时，除非 allowed_hosts 列出该主机，这类请求只会访问公网地址；false 表示关闭该检查。运维人员配置的 URL（例如服务提供方密钥的 api_base）不受影响。地址规则、代理行为和限制参见原生服务提供方的媒体内容。
upstream.bedrock.mantle_endpoint 指定 Bedrock Mantle 主机：当 Bedrock 的 CountTokens 拒绝为某个 Claude 模型计数时，由它为 /v1/messages/count_tokens 计数。参见 Messages API 上的 Claude。
调整下游连接层
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；在 /v1/realtime 上还包括 HTTP 101 升级握手。 |
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 可从声明式资源文件加载这些资源：
resources_file: /etc/aisix/resources.yaml
resources_file 与 etcd 配置互斥，同时配置会导致启动失败。resources_file 也不能与 managed.enabled: true 组合使用，因为连接到 AISIX Enterprise 或 AISIX Cloud 的网关会从控制面接收资源。
设置 resources_file 后，网关会在启动时加载该文件；首次加载失败时会退出。收到 SIGHUP 时会重新加载文件。所有资源类型和字段请参见资源文件参考。操作流程请参见开源 AISIX 网关快速入门，验证或 etcd 导出请参见 CLI 参考。配置状态会显示运行中的网关加载了哪些内容。
etcd 配置存储
当配置自动化直接向 etcd 写入资源时，请设置 etcd.endpoints：
etcd:
endpoints:
- "https://etcd.example.com:2379"
prefix: "/aisix"
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 时，AISIX 才会进行认证。 |
etcd.password_env | 否 | 包含 etcd 密码的环境变量名称。只有同时设置此字段和 etcd.user 时，AISIX 才会进行认证。 |
etcd.dial_timeout_ms | 否 | 限制与 etcd 的单次连接尝试，单位毫秒：TCP 连接、叠加在其上的 TLS 握手，以及同时设置两个凭据字段时进行的认证交互。默认值为 5000。整次连接按每个已配置端点各获得一份该预算，因此总预算为 dial_timeout_ms 乘以端点数（至少按 1 计）。显式写 0 表示不施加任何超时，即 1.4.0 之前该字段的行为。 |
etcd.request_timeout_ms | 否 | 可选，限制单次 etcd 请求-响应调用的时间，单位毫秒。默认不设置；不设置和 0 都不施加任何超时。与 dial_timeout_ms 不同，该字段有意保持无上限的默认值。设置前请先阅读下面的说明。 |
etcd.tls | 否 | mTLS 连接的客户端 CA、证书、密钥以及可选的服务器名称覆盖项。三个证书文件字段必须同时提供。 |
配置 etcd 超时
dial_timeout_ms 默认为 5000 毫秒，request_timeout_ms 默认不设置、无上限；两个字段显式写 0 都表示不设上限。两者的默认值有意不同：建立连接的开销不随配置规模增长，而请求-响应读取的开销会，因此给读取加上默认上限，反而会中断那次一旦失败就让网关无内容可服务的调用。与模型超时不同，这些字段没有回退链。
| 设置 | 受限的工作 | 不受限制的工作 |
|---|---|---|
dial_timeout_ms | 单次连接尝试：TCP、TLS 和身份认证。整次连接按每个已配置端点各获得一份该取值 | 连接建立后的 etcd 调用 |
request_timeout_ms | 单次请求-响应调用，包括全前缀配置读取、创建 watch 的握手、Admin API 读取，以及该调用发起的连接 | 已建立的 watch 流 |
已经建立的 watch 流有意不设上限，避免安静期触发重连。request_timeout_ms 限制的是创建 watch 的握手。如果该字段未设置且握手停滞，即使 /status/config 报告来源已连接，网关也可能一直提供第一个快照，而收不到后续变更。配置请求超时可以限制握手，并让网关重试。
dial_timeout_ms 到期会被视为端点不可达，并进入重试路径。网关会输出警告并持续重试。初始连接完成后，启用 Prometheus 指标时会绑定指标/状态监听器；启用了 Admin 监听器的开源网关也会绑定该监听器。只有在 AISIX 应用实时配置或恢复可用快照后，代理监听器才会绑定。etcd 在初始连接上拒绝凭据则属于致命故障。可观察到的差异请参见网关正在运行，但代理端口拒绝连接。
只有需要让缓慢的 etcd 调用快速失败时，才设置 request_timeout_ms。配置读取耗时会随资源集增大，因此取值过短会在不同阶段产生不同影响：
| 读取超时的时间 | 网关行为 |
|---|---|
| 第一个配置前，且没有快照缓存 | 网关会重试，但代理监听器不会绑定。 |
| 第一次实时读取前，且已恢复快照 | 代理监听器继续提供快照，但配置落后于存 储。 |
| watch 重连后的读取期间 | 网关继续提供已经应用的配置，而存储的新变更保持待处理状态。 |
最后一种情况下，日志会警告全量读取超过 etcd.request_timeout_ms。/status/config 报告 source.connected: false 和 last_failure.last_error_kind: fetch，而 state 仍可能为 synced，因为它描述的是已应用的快照。请对 aisix_config_reload_failures_total{reason="fetch"} 告警。除非需要有限的故障上限，否则请保持该超时不设置。
恢复 etcd 身份认证
同时设置 etcd.user 和 etcd.password_env 后，AISIX 会复用身份认证返回的 Token。使用简单 Token 时，--auth-token-ttl 控制有效期；使用 JWT Token 时，--auth-token 中的 ttl 设置控制有效期，认证存储修订版本变化也可能让已签发的 Token 失效。即使配置的用户名和密码仍然正确，这些事件也可能要求 AISIX 重新认证。
AISIX 将 invalid auth token、revision of auth store is old 和 user name is empty 识别为过期 Token 响应。它会丢弃连接、重新认证，并重试一次调用。authentication failed, invalid user ID or password 等凭据故障不会作为过期 Token 重试。
设置 request_timeout_ms 时，请为过期 Token 恢复最多留出该取值的四个窗口。冷连接在恢复开始前可能消耗两个窗口：初始连接一个，被拒绝的调用一个；之后新连接和认证消耗一个，重试调用再消耗一个。缓存连接会跳过初始连接，最多消耗三个窗口。每次连接内部还受 dial_timeout_ms × 已配置端点数限制；该内部上限可能更早结束连接，但恢复过程不会在 request_timeout_ms 窗口之外再增加一份独立的连接预算。
从现有配置存储迁移到资源文件时，请使用 aisix export。
AISIX Enterprise 或 AISIX Cloud
网关从控制面接收资源时，请将 managed.enabled 设置为 true。请使用生成的网关安装代码片段，不要手动组合引导值；它会为所选环境提供正确的控制面端点和证书材料。
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_enabled: false
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 | 是 | 启用托管连接并禁用网关 Admin API 监听器。 |
managed.cp_base_url | 是 | 用于心跳、遥测、证书轮换和预算检查的控制面 Origin。 |
managed.cp_etcd_endpoint | 否 | 采用 host:port 形式的显式托管 etcd 端点。省略时，AISIX 会从 cp_base_url 派生。 |
managed.cp_ca_cert_file | 否 | 控制面 HTTP 和 etcd TLS 连接使用的额外 CA 证书包，AISIX Enterprise 控制面使用私有 CA 时通常需要。 |
managed.mtls_dir | 否 | AISIX 用于持久化生成的 mTLS 证书包的目录。默认为 /var/lib/aisix/mtls。 |
managed.dp_id_file | 否 | AISIX 持久 化网关 ID 的文件。默认为 /var/lib/aisix/dp_id。 |
managed.snapshot_cache_enabled | 否 | 启用跨重启的磁盘配置恢复。无论网关从控制面接收资源，还是直接从 etcd 读取资源，均默认为 false。无论该开关如何设置，运行中的网关都会在内存中保留已接受的配置。 |
managed.snapshot_cache_path | 否 | 开启持久化后的缓存文件位置。省略或设为 null 时使用 /var/lib/aisix/config_cache.json；空字符串禁用持久化。仅配置路径不会启用缓存。 |
managed.heartbeat_interval_secs | 否 | 心跳间隔秒数。默认为 15，并限制在 5–300 范围内。 |
托管连接在配置状态中显示为 source.type: "etcd"，因为网关会通过托管配置存储连接使用控制面投影的资源。有关证书签发和安装流程，请参阅连接 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:1.7.0
如果未设置 AISIX_CONFIG_PATH，入口程序会使用 /etc/aisix/config.yaml。
加载顺序
AISIX 按以下顺序加载启动配置：
- 内置默认值。
--config所选路径中的文件内容。- 以
AISIX_为前缀的环境变量覆盖项。
环境变量覆盖项只作用于启动配置字段。覆盖语法和托管连接变量请参见环境变量。