启动配置参考
本参考介绍用于定义监听器、资源来源连接、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 加载动态资源；请参阅资源来源。
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 握手和认证
# 交互。不设置和 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: # 代理监听器的 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 主节点的数据库索引。
# # timeout_secs: 5 # 限制一次 Redis 往返和一次连接尝试，最小值为 1。
# # 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 主节点的数据库索引。
# # timeout_secs: 5 # 限制一次 Redis 往返和一次连接尝试，最小值为 1。
# # 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 且受支持的 HTTP 上游。
# 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"
启动配置的更改会在网关重启后生效。
限制请求体大小
proxy.request_body_limit_bytes 默认为 0，表示网关侧不设上限。服务提供方接受的请求可能大于任何单一固定默认值，因此设置上限可能会拒绝原本可由所选服务提供方处理的请求。早期 AISIX 版本的默认值为 10485760 字节（10 MiB）。
如果网关直接接受来自不受信任客户 端的请求，并且必须限制单请求内存，请设置一个字节数。也可以在网关前的负载均衡器或 Ingress 上实施请求体大小限制。
AISIX 会以 413 Content Too Large 拒绝超限请求，但不保证调用方一定能收到该响应。对于声明了超限 Content-Length 的请求，AISIX 会先排空请求体，以便在同一连接上返回 413。排空操作受字节数和时间限制；如果调用方未能在限制内发送完毕，网关会停止读取，此时调用方通常看到连接关闭或重置。分块请求体会在处理程序读取时被拒绝，不使用同一排空路径。
在 Content-Length 路径上，aisix::body_limit 日志条目和 aisix_proxy_request_body_limit_rejections_total 可区分排空完成、达到上限、超时或客户端读取错误。有关字段与关联分析流程，请参阅访问日志与请求关联。
调整上游连接层
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 会移除部署级默认值。
值为零时的行为因字段而异。upstream.timeout_ms: 0 会移除部署级请求截止时间，模型上的 timeout: 0 会停止该请求超时的回退链。相比之下，upstream.stream_timeout_ms: 0 会回退到 upstream.timeout_ms，而模型上的 stream_timeout: 0 会继续回退到剩余的流超时 和请求超时链。因此，流超时值为零时仍可能存在有效的流式截止时间。
upstream.tls 提供出站连接的部署级 TLS 设置。ca_file 适用于 HTTP 请求路径、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 可从声明式资源文件加载这些资源：
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：
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 | 否 | 包含 etcd 密码的环境变量名称。 |
etcd.dial_timeout_ms | 否 | 可选，限制与某个 etcd 端点建立连接的整个过程，单位毫秒：TCP 连接、叠加在其上的 TLS 握手，以及设置了 etcd.user 时进行的认证交互。默认不设置；不设置和 0 都不施加任何超时。 |
etcd.request_timeout_ms | 否 | 可选，限制单次 etcd 请求-响应调用的时间，单位毫秒。默认不设置；不设置和 0 都不施加任何超时。设置前请先阅读下面的说明。 |
etcd.tls | 否 | mTLS 连接的客户端 CA、证书、密钥以及可选的服务器名称覆盖项。三个证书文件字段必须同时提供。 |
两个 etcd 超时设置都是可选的，默认不设置。不写某个键，就表示对它所覆盖的调用不施加任何超时；把它设为 0 含义完全相同。这里的 0 表示「不设上限」而不是「回退到更外层的设置」，是因为这两个键是扁平的单层启动设置，没有可以回退的外层——这一点与模型的 stream_timeout 不同，后者的 0 会回退到其解析链的下一层。
dial_timeout_ms 限制的是建立连接的整个过程，而不只是 TCP 连接本身：叠加在连接器之上的 TLS 握手，以及设置了 etcd.user 时客户端所做的认证交互，都在它的覆盖范围之内。request_timeout_ms 限制单次请求-响应调用：网关在启动时以及每次重连时发起的全前缀配置读取、建立配置 watch 的握手、Admin API 自身的读取，以及这些调用在所需连接尚未建立时各自发起的那一次连接。
建立 watch 和消费 watch 受不受限制，是有意区分开的。建立 watch 是一次请求-响应交互——网关发出创建请求，等待 etcd 确认——因此设置了 request_timeout_ms 时它会被限制。随之返回的长连接流则永远不受它约束，因为任何这类上限都会在一段安静到没有产生事件的时间里到期，让网关不断重连而不是持续 watch。给建立过程加上上限，堵住的是一种原本无从察觉的故障：etcd 能正常响应配置读取、却始终不确认 watch 时，网关会一直提供它拿到的第一份快照，对之后的每一次变更都视而不见，而 /status/config 仍然报告来源已连接。
上面提到的、已经建立起来的 watch 流，是这两个键都不加约束的唯一一处交互，而这是有意为之。网关对 etcd 做的其他一切都落在其中某个键之下，建立连接时的认证交互也不例外：启动阶段由 dial_timeout_ms 覆盖，之后某次调用需要自行建立连接时由 request_timeout_ms 覆盖。
建立连接超时算作「没能连上 etcd」，而不是「etcd 拒绝了网关」，因此 dial_timeout_ms 到期会进入重试路径，而不会结束启动。哪些 etcd 故障会被一直等待、哪一种会终止启动，参见启动与第一个配置。
除非你确实希望缓慢的 etcd 快速失败，否则请保持 request_timeout_ms 不设置。配置读取的耗时会随资源规模增长，因此一个读取无法在其中完成的上限会让每次尝试都被中断，网关会无限重试同一次读取。自建 etcd 的网关在未显式设置 managed.snapshot_cache_path 时不保留快照缓存，这种情况下代理监听器根本不会被绑定。而在启用了快照缓存的部署中，实例会基于恢复出来的快照完成绑定，并在该上限持续中断读取期间一直提供这份快照，于是它的流量看起来是健康的，配置却已悄悄不再跟随存储变化。参见启动与第一个配置。
因此 request_timeout_ms 不只是一个启动期的开关。它所限制的全前缀读取会在每一次 watch 重连时再次执行，而那时代理监听器早已绑定，所以取值过小会以两种完全不同的方式出问题。在没有快照缓存的网关上，启动阶段代理端口根本不会打开，这很难被忽略。而在那之后，流量层面毫无变化——网关继续提供已经应用的那份配置，没有任何请求失败——与此同时每一次重连读取都被中断，已应用的配置离存储越来越远。真正点名这个配置键的是网关日志：其中的告警会带上 range read exceeded 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.user 时，网关在建立连接的过程中认证一次，此后这条连接终其一生都携带那次交互返回的 Token。即便 Token 背后的凭据完全有效，etcd 也可能不再接受这个 Token。面向部署的成因是认证存储的 revision 发生了变化：在签发 JWT Token 的集群上，任何人对认证存储做的任何改动——新增用户、授予角色、修改权限——都会让此前签发的每一个 Token 失效，其中也包括这个网关持有的那一个。Token 走到 --auth-token-ttl 的尽头也会到达同样的状态。
网关会自行恢复。当 etcd 以「拒绝这条连接所携带的 Token」来响应某次调用时——通常报为 invalid auth token，另外 revision of auth store is old 和 user name is empty 这两种应答也被识别为同一件事——网关会丢弃该连接、建立一条新连接（由此重新完成认证），并把该调用重试一次。在此之前，它会一直持有被拒绝的 Token 直到进程被重启，期间读不到任何配置。etcd 确实拒绝了凭据（authentication failed, invalid user ID or password）则有意不在这个列表中，仍然在第一次响应时就失败；再怎么重试也不会把错误的密码变成正确的密码。如果在刚刚完成认证的连接上 Token 仍然被拒绝，网关会把它作为「Token 被拒绝」而不是「凭据被拒绝」报出，以免这两件事被当作同一回事来排查。
这对健康的连接不产生任何代价，但它改变了设置 request_timeout_ms 之后的最坏情况：一次尝试会分别限制它的建立连接和调用，而重试拿到的是一个完整的新窗口，而不是上一次剩下的部分，因此走过这条恢复路径的一次配置读取最长可达所配置取值的四倍。两个超时键默认都不设置，因此默认部署不受影响；如果要设置一个很紧的取值，请把这个倍数考虑进去。
从现有配置存储迁移到资源文件时，请使用 aisix export。
AISIX Cloud
网关从 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_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:1.2.0
如果未设置 AISIX_CONFIG_PATH，入口程序会使用 /etc/aisix/config.yaml。
加载顺序
AISIX 按以下顺序加载启动配置：
- 内置默认值。
--config或AISIX_CONFIG所选路径中的文件内容。- 以
AISIX_为前缀的环境变量覆盖项。
环境变量覆盖项只作用于启动配置字段。覆盖语法和 AISIX Cloud 连接变量请参见环境变量。