跳到主要内容

启动配置

启动配置定义 AISIX 在处理流量前需要的静态设置，覆盖配置存储、监听地址、指标、缓存后端和托管启动模式等进程级事项。

动态资源则不同。模型、调用方 API Key、服务提供方密钥、安全护栏、缓存策略和可观测性导出器会在稍后从配置存储加载。

最小自托管示例​

可以先从一个很小的自托管 config.yaml 开始，然后只添加当前部署需要的设置：

config.yaml
etcd:
  endpoints:
    - "http://127.0.0.1:2379"
  prefix: "/aisix"
  dial_timeout_ms: 5000
  request_timeout_ms: 5000

proxy:
  addr: "0.0.0.0:3000"
  request_body_limit_bytes: 10485760

admin:
  addr: "127.0.0.1:3001"
  admin_keys:
    - "YOUR_ADMIN_KEY"

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

cache:
  backend: "memory"

ratelimit:
  backend: "memory"

加载顺序与覆盖​

AISIX 按以下顺序加载启动配置：

  1. 默认值
  2. 文件内容
  3. 环境变量覆盖项

环境变量覆盖项以 AISIX_ 开头，并在嵌套配置字段之间使用 __。当容器镜像需要保持同一个配置文件，而部署系统要注入监听地址、凭证或托管模式值时，这很有用。

使用环境变量设置嵌套启动值：

export AISIX_PROXY__ADDR="0.0.0.0:3000"

连接运行时依赖​

动态资源要进入代理路径，AISIX 必须先有配置存储。etcd 块告诉 AISIX 启动后从哪里读取这些资源。

大多数自托管部署会让 AISIX 指向一个 etcd 端点，并保持稳定前缀，使所有网关资源位于同一个键空间下：

config.yaml
etcd:
  endpoints:
    - "http://127.0.0.1:2379"
  prefix: "/aisix"
  dial_timeout_ms: 5000
  request_timeout_ms: 5000

只有当部署模型需要环境级标识时才使用 env_id。当配置存储要求 TLS 或 mTLS 时，请添加 etcd.tls。

AISIX 始终会构建进程内内存缓存。当缓存策略需要在多个网关实例之间共享缓存响应时，请添加 Redis：

config.yaml
cache:
  redis:
    mode: single
    url: "redis://127.0.0.1:6379"

匹配的缓存策略会为每个请求选择内存或 Redis。cache.backend 字段为兼容性保留，不再选择全局缓存后端。当 cache.backend 为 redis 时，如果缺少 Redis 块或网关无法连接，启动仍会失败。

Redis Cluster 请使用带 nodes 的 mode: cluster；由 Sentinel 管理的 master 请使用带 sentinels 和 master_name 的 mode: sentinel。

限流计数器默认使用本地内存。当多个网关实例需要共享请求、token 和并发计数器时，请使用 Redis：

config.yaml
ratelimit:
  backend: redis
  redis:
    mode: single
    url: "redis://127.0.0.1:6379"

选择 Redis 后端时，启动配置需要包含 ratelimit.redis 块。使用内存后端时，计数器保存在各自网关进程中。

限流 Redis 后端支持与响应缓存相同的 single、cluster 和 sentinel 连接模式。concurrency_ttl_secs 控制 Redis 后端并发槽位在被回收前可以保留多久。

暴露运行时监听器​

AISIX 将调用方流量、自托管管理和指标拆分为不同监听器关注点。

代理监听器是模型流量面向调用方的入口：

config.yaml
proxy:
  addr: "0.0.0.0:3000"
  request_body_limit_bytes: 10485760

本地开发时，绑定到 loopback 可以保持网关私有。对于容器或入口部署，请绑定到入口层或调用方网络可访问的接口。请求体限制应足够覆盖预期流量，但不要设置得过于随意。

Admin 监听器是自托管部署的管理入口：

config.yaml
admin:
  addr: "127.0.0.1:3001"
  admin_keys:
    - "YOUR_ADMIN_KEY"

请尽量将 Admin 监听器绑定到 loopback 或私有接口。默认地址使用 loopback 临时端口，因此自托管部署应设置显式私有地址。Admin Key 是静态启动配置，不是调用方 API Key 资源。

只有当 AISIX 需要直接终止 HTTPS 时才使用监听器 TLS。只有当 AISIX 位于可信负载均衡器或入口之后，并由其设置转发客户端 IP 请求头时，才配置真实客户端 IP 解析。默认情况下，AISIX 不信任任何转发请求头，而使用直接 TCP 对端。

配置可观测性​

启动期可观测性设置控制进程级日志和 Prometheus 暴露。

为 Prometheus 抓取配置专用指标监听器：

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

当前版本中，请将 access_log、metrics.otlp 和 tracing.otlp 视为保留或部分支持配置。代理处理器仍会输出结构化访问日志，OTLP 指标尚未接线，启动期 OTLP tracing 不会安装完整导出流水线。

启动期可观测性设置不同于动态可观测性导出器。启动设置控制进程；动态导出器资源控制运行时遥测投递。通过 Admin API 添加动态导出器请参见可观测性导出器。

选择自托管或托管模式​

启动配置也决定网关以自托管模式还是托管模式运行。

只有当 AISIX Cloud 是控制面时，才启用托管模式：

config.yaml
managed:
  enabled: true
  mtls_dir: "/var/lib/aisix/mtls"
  dp_id_file: "/var/lib/aisix/dp_id"

当 managed.enabled = true 时，Admin API 不会绑定，本地 playground 端点不会暴露，动态资源会通过托管配置路径读取。AISIX Cloud 使用基于证书的托管引导；证书包可以以内联 PEM 值或挂载文件路径提供。

当需要通过 :3001 进行本地控制时，请使用自托管启动配置。当网关不应暴露本地 Admin 写 API 时，请使用托管启动配置。

验证启动配置​

更新启动配置后，启动网关并验证代理监听器：

curl -sS "http://127.0.0.1:3000/livez"

自托管模式下，还要验证 Admin 监听器：

curl -sS "http://127.0.0.1:3001/livez"

如果进程已启动但模型资源不可见，请先检查 etcd 连接和前缀是否一致。启动成功本身并不能证明动态配置读取健康。

如果代理监听器可达但 Admin 监听器不可达，请检查是否设置了 managed.enabled = true。托管模式下，Admin API 会有意不绑定。

如果环境变量覆盖项没有生效，请确认 AISIX_ 前缀和嵌套字段 __ 分隔符。

下一步​

你已经了解启动设置如何启动网关进程和监听器。接下来阅读配置传播，了解运行时更新时序。