启动配置

启动配置定义 AISIX 在提供流量服务前所需的进程级设置。它控制网关如何接收动态资源、绑定哪些监听器、使用哪些共享后端，以及如何连接 AISIX Cloud。

动态资源单独配置。模型、模型服务提供方密钥、调用方 API Key、安全护栏、缓存策略、限流策略和可观测性导出器来自资源文件、配置存储或 AISIX Cloud 控制面。

了解配置来源

AISIX 为不同职责使用不同配置来源：

配置	适用对象	来源
进程设置	每个网关	启动配置文件，可选择使用环境变量覆盖
动态网关资源	开源 AISIX 网关	声明式 resources.yaml 文件或 etcd
动态网关资源	连接 AISIX Cloud 的网关	AISIX Cloud 控制面
On-Premises 控制面设置	On-Premises AISIX Cloud 部署	Docker Compose 环境变量或 Helm values

本页介绍网关启动配置。有关 On-Premises 控制面设置，请参阅 On-Premises 配置参考。

选择动态资源来源

网关从一个来源读取动态资源。在配置监听器和运行时依赖之前，请先在启动配置中选择该来源。

资源文件

开源网关的常规工作流使用声明式资源文件：

config.yaml

resources_file: /etc/aisix/resources.yaml

proxy:
  addr: "0.0.0.0:3000"

admin:
  enabled: false

observability:
  metrics:
    prometheus:
      enabled: true
      path: "/metrics"
      addr: "0.0.0.0:9090"

网关在启动时加载该文件，并在收到 SIGHUP 后重新加载。应用资源变更前，请先进行验证：

aisix validate --resources /etc/aisix/resources.yaml

完整工作流请参阅开源 AISIX 网关快速入门，受支持的资源类型请参阅资源文件参考。

配置存储

当现有自动化系统通过共享存储管理开源 AISIX 网关资源时，请使用 etcd：

config.yaml

etcd:
  endpoints:
    - "http://127.0.0.1:2379"
  prefix: "/aisix"

对于应接收相同资源的网关实例，请保持前缀稳定。只有当配置系统写入环境级键时才使用 env_id。存储要求 mTLS 时，请配置 etcd.tls。

etcd.dial_timeout_ms 默认为 5000 毫秒，etcd.request_timeout_ms 默认不设置、无上限。设置任一字段前，请先阅读 etcd 配置存储中的准确作用范围和失败行为。对配置读取来说过短的 request_timeout_ms 可能阻止代理监听器绑定，也可能让运行中的网关配置落后于存储。

etcd 无法提供第一个配置时，网关通常会保持代理监听器关闭并重试。如何区分可达性、超时和凭据故障，请参见网关正在运行，但代理端口拒绝连接。

配置来源是唯一能让代理监听器无限期保持关闭的启动依赖。无法连接 ratelimit.redis 或 cache.redis 时，AISIX 会执行有界的启动连接尝试，在此期间可能延迟所有监听器。尝试结束后，Redis 不再阻止监听器启动，受影响的子系统进入降级模式。每个监听器仍须满足自身的启用和配置条件。

不要同时配置 resources_file 和 etcd；AISIX 会在启动时拒绝这种组合。

AISIX Cloud

生成的网关安装片段会将 managed.enabled 设置为 true，并提供控制面端点、证书包、运行时状态目录和网关身份路径。之后，网关会从控制面接收环境资源。

不要将 managed.enabled: true 与 resources_file 组合使用。有关证书签发和完整连接流程，请参阅连接 AISIX 网关。

配置共享运行时状态

AISIX 始终提供进程内响应缓存。当缓存策略需要在多个网关实例之间共享条目时，请配置 Redis：

config.yaml

cache:
  redis:
    mode: single
    url: "redis://127.0.0.1:6379"

配置 cache.redis 后，缓存策略即可使用 Redis。每个缓存策略会选择内存或 Redis。

限流计数器默认使用进程内存。当请求、Token 或并发限制必须作用于多个实例时，请配置共享 Redis 后端：

config.yaml

ratelimit:
  backend: redis
  redis:
    mode: single
    url: "redis://127.0.0.1:6379"

缓存和限流 Redis 连接支持单节点、Cluster 和 Sentinel 部署。当任一功能属于生产流量路径时，请使用符合可用性要求的 Redis 拓扑。

配置运行时监听器

AISIX 将调用方流量与运维状态分离：

监听器	用途	暴露范围
代理	面向调用方的 AI API，以及 /livez 和 /readyz	预期调用方或入口层
指标/状态	Prometheus 指标和 /status/* 路由	可信监控网络
诊断	/debug/pprof/heap 上的堆 profile；参见内存诊断	仅回环地址（默认）

请设置显式代理地址。指标/状态路由不需要应用身份认证，因此绝不能将该监听器暴露到公网。

指标/状态监听器通常在进程启动时绑定。使用 etcd 或 AISIX Cloud 作为资源来源时，代理监听器只有在网关应用第一个配置之后才会绑定。使用资源文件的网关会在加载文件后绑定。参见启动与第一个配置。

只有当 AISIX 应直接终止 HTTPS 时，才使用监听器 TLS。只有网关运行在可信负载均衡器或 Ingress 之后时，才解析转发的客户端地址。暴露模型请参阅网络与安全，独立 TLS 上下文请参阅 TLS 与 mTLS。

配置进程可观测性

启动期可观测性设置控制进程日志和指标/状态监听器：

config.yaml

observability:
  service_name: "aisix"
  log_level: "info"
  metrics:
    prometheus:
      enabled: true
      path: "/metrics"
      addr: "0.0.0.0:9090"

这些设置不同于动态可观测性导出器。启动设置控制进程和本地 Prometheus 监听器。运行时遥测投递请通过可观测性导出器配置。

配置关闭行为

收到 SIGTERM 时，网关会立即把自己报告为未就绪，但仍会继续接受新连接一段时间，让前面的负载均衡器有时间在监听器关闭之前把它移出流量：

config.yaml

shutdown:
  min_drain_secs: 30

请把该窗口设置为大于为该实例做负载均衡的组件的发现延迟，并为随后的进行中请求排空留出足够的平台终止时间。参见关闭与排空。

加载并验证配置

AISIX 先应用内置默认值，再加载启动配置文件，最后应用 AISIX_ 环境变量覆盖项。嵌套字段名之间使用 __：

export AISIX_PROXY__ADDR="0.0.0.0:3000"

有关文件格式、字段行为、文件选择和加载优先级，请参阅启动配置参考。有关覆盖语法，请参阅环境变量。

启动网关后，请在指标/状态监听器上检查 AISIX 是否已应用有效配置：

curl -sSi "http://127.0.0.1:9090/status/ready"
curl -sS "http://127.0.0.1:9090/status/config"

/status/ready 返回 200 后，再检查代理监听器：

curl -i "http://127.0.0.1:3000/livez"
curl -i "http://127.0.0.1:3000/readyz"

如果这些命令被拒绝，请使用指标/状态结果和故障排除诊断第一个配置为何尚未应用。如果命令有响应但某项资源变更缺失，请使用配置传播从来源一路追踪变更到面向调用方的路径。

下一步

继续阅读每核一线程 Worker，确定代理监听器背后的 Worker 池规模，然后阅读网络与安全，保护此处配置的监听器、存储和凭证。