跳到主要内容

启动配置

启动配置定义 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 和 etcd.request_timeout_ms 都是可选的，默认不设置；不设置即不施加任何超时，设为 0 含义相同。dial_timeout_ms 限制建立连接的整个过程——TCP 连接、TLS 握手，以及设置了 etcd.user 时进行的认证交互。这两个键都够不到的只有已经建立起来的配置 watch 流，而这是有意为之——但创建该 watch 的握手会受 request_timeout_ms 限制。除非你希望缓慢的 etcd 快速失败，否则请保持 request_timeout_ms 不设置。它限制的是配置读取，而配置读取的耗时会随资源规模增长，并且会在每一次 watch 重连时再次执行：一个读取无法在其中完成的上限，会让没有快照缓存的网关永远无法绑定代理监听器；而在已经开始提供服务的网关上，它会让已应用的配置悄悄落后于存储。参见 etcd 配置存储。

无论是否设置 etcd.user，网关连不上 etcd 都不会终止启动：进程照常启动，让代理监听器保持关闭，并在某次读取成功时完成绑定。而在启动那次连接上被 etcd 拒绝的凭据会终止启动，因为等待并不能把它们修好。更晚到达的拒绝——例如一个通过了认证、却读不了该前缀的用户——则会被重试，网关保持运行，代理监听器不绑定。参见启动与第一个配置。

不要同时配置 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/* 路由可信监控网络

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

这两个监听器的启动时机也不同。指标/状态监听器在进程启动时即绑定。使用 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"

使用 etcd 或 AISIX Cloud 作为资源来源时，在应用第一个配置之前，这两条命令得到的是被拒绝的连接而不是响应，因为在那之前代理监听器尚未绑定。使用资源文件的网关则会立即绑定。参见启动与第一个配置。

如果代理监听器有响应，但资源没有出现，请检查所配置的资源来源，不要更改监听器设置。如果它拒绝连接，则说明网关还没有应用任何配置——请检查它能否连上该来源。使用配置传播追踪变更从来源到面向调用方路径的过程。

下一步​

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