跳到主要内容
版本：3.18.0

配置文件

APISIX 在 /conf 下有以下配置文件：

  • config.yaml
  • config.yaml.example
  • apisix.yaml
  • debug.yaml

此外，如果你希望在 文件驱动的独立模式 下使用 JSON，你可以将 apisix.json 放在 /conf 下。

本文档提供了有关如何使用配置文件以及如何按环境管理配置文件的参考。

用法​

config.yaml 和 config.yaml.example​

APISIX 带有一个配置文件 config.yaml，用于自定义许多参数，包括监听接口、部署模式、插件属性等。

这些参数的默认值可以在 apisix/cli/config.lua 中找到。

你可以在 config.yaml.example 中找到 config.yaml 的示例配置文件：

apisix:
  # node_listen: 9080               # APISIX listening port (single)
  node_listen:                      # APISIX listening ports (multiple)
    - 9080
  #   - port: 9081
  #     enable_http2: true          # If not set, the default value is `false`.
  #   - ip: 127.0.0.2
  #     port: 9082
  #     enable_http2: true
  enable_admin: true
  enable_dev_mode: false
  enable_reuseport: true
  # ...

config.yaml 中的配置在启动时加载一次。如果你对此文件进行了任何更新，请 重新加载 APISIX 以使更改生效。

选择 AI Gateway HTTP 客户端​

AI Proxy、AI Proxy Multi 和 AI Request Rewrite 默认使用 ngx_http_ffi_client 向 LLM 上游发送请求。若已安装的运行时不提供 FFI 客户端模块，或需要使用 Lua 客户端路径，请将共享插件属性设为 lua-resty-http：

config.yaml
plugin_attr:
  ai-proxy:
    http_client: lua-resty-http

可接受的值为 ngx_http_ffi_client 和 lua-resty-http。未知值会导致插件属性校验失败；在不含 resty.ngx_http_ffi_client 的运行时中选择 ngx_http_ffi_client，会在创建客户端时使 AI 上游请求失败。

规划共享内存​

本版本中，多个不可驱逐的共享内存区采用更大的默认值，以降低生产环境指标、服务发现状态和追踪信息耗尽内存区的可能性。这些内存区由所有 Worker 共享，因此不要将配置的大小乘以 Worker 数量。

功能或内存区当前默认值之前默认值
仅 HTTP 的 prometheus-metrics128 MiB10 MiB
启用 Stream 插件时的 prometheus-metrics128 MiB15 MiB
HTTP Nacos 服务发现64 MiB10 MiB
Stream Nacos 服务发现64 MiB10 MiB
Consul 服务发现 shared_size64 MiB1 MiB
Kubernetes 服务发现 shared_size64 MiB1 MiB
SkyWalking tracing_buffer32 MiB10 MiB

某些内存区仅在启用相应插件或服务发现时生成，而运行时级别的 Nacos 内存区会由 APISIX 运行时模板生成。升级内存受限的网关前，请将生成的 NGINX 配置以及已启用的插件和服务发现与容器或主机内存限制进行比较。只有在确认能容纳预期指标基数、服务发现清单或追踪负载后，才保留显式设置的较小值；这些内存区不会驱逐旧条目来腾出空间。

信任转发头​

APISIX 会在 Lua 插件运行前，在 NGINX rewrite 阶段清理 X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-Port 和 RFC 7239 Forwarded 头。仅将 apisix.trusted_addresses 配置为应接受其转发头的负载均衡器地址或网络：

config.yaml
apisix:
  trusted_addresses:
    - 192.168.1.0/24
    - 2001:db8:1234::/48
直接对端转发行为
未配置可信列表保留入站 X-Forwarded-For 链并追加直接对端；以 APISIX 观测到的值替换 Proto、Host 和 Port，并清除 Forwarded。
位于 trusted_addresses 中保留入站 X-Forwarded-For 链并追加直接对端；若对端提供了入站 Proto、Host、Port 和 Forwarded，则恢复这些值，否则使用 APISIX 观测到的值。
不在已配置的可信列表中丢弃入站 X-Forwarded-For 链，使上游只接收直接对端；以观测值替换 Proto、Host 和 Port，并清除 Forwarded。

信任一个网络会允许该网络中的任何对端提供这些携带身份信息的值。请将列表限制为你控制的代理。

APISIX 会保留客户端提供的值，以供审计和诊断：

上下文已清理或生效的值原始客户端值
Lua 插件ctx.var.http_x_forwarded_proto、ctx.var.http_x_forwarded_host、ctx.var.http_x_forwarded_port 和 ctx.var.http_x_forwarded_forctx.var.original_x_forwarded_proto、ctx.var.original_x_forwarded_host、ctx.var.original_x_forwarded_port、ctx.var.original_x_forwarded_for 和 ctx.var.original_forwarded
NGINX 配置$scheme、$var_x_forwarded_host 和 $var_x_forwarded_port$original_x_forwarded_proto、$original_x_forwarded_host、$original_x_forwarded_port、$original_x_forwarded_for 和 $original_forwarded

Lua 不再公开 ctx.var.var_x_forwarded_proto、ctx.var.var_x_forwarded_host 或 ctx.var.var_x_forwarded_port。NGINX 仍会定义 $var_x_forwarded_host 和 $var_x_forwarded_port；对于已清理的协议，请使用 $scheme。

在 NGINX access-log 格式、if 或 map 中，$http_x_forwarded_proto、$http_x_forwarded_host、$http_x_forwarded_port 和 $http_forwarded 会保留 APISIX 替换头之前缓存的原始客户端值。需要明确已清理或原始语义时，请使用上表中的变量。配置了可信列表时，$http_x_forwarded_for 使用生效值，并会为不受信任的对端清空。

apisix.yaml​

在 APISIX 文件驱动的独立部署模式下，apisix.yaml 用于配置 APISIX 资源，例如 路由、上游、消费者 等。

这些配置在启动时由 APISIX 加载到内存中。对此文件的更改不需要重新加载 APISIX，因为会定期监控该文件的更改。

有关如何配置 apisix.yaml 的更多信息，请参阅 文件驱动的独立模式。

apisix.json​

apisix.json 是文件驱动的独立部署模式下 apisix.yaml 的 JSON 等效项，用于配置 APISIX 资源。

有关如何配置 apisix.json 的更多信息，请参阅 文件驱动的独立模式。

debug.yaml​

你可以使用 debug.yaml 中的配置选项启用和自定义 APISIX 调试模式。

对此文件的更改不需要重新加载 APISIX，因为会定期监控该文件的更改。

要了解更多信息，请参阅 使用调试模式。

按环境管理配置文件​

为不同的环境（例如开发、暂存和生产）保持单独的配置文件可以提供多种好处，包括增加灵活性、提高安全性和更易于维护。

APISIX 支持按环境分离配置文件。你可以设置 APISIX_PROFILE 环境变量来区分 APISIX 应使用哪组其他配置文件。

默认情况下，当未设置 APISIX_PROFILE 时，APISIX 查找以下配置文件：

  • conf/config.yaml
  • conf/apisix.yaml
  • conf/debug.yaml

如果 APISIX_PROFILE 的值设置为 prod，APISIX 将查找以下配置文件：

  • conf/config-prod.yaml
  • conf/apisix-prod.yaml
  • conf/debug-prod.yaml

你可以将 APISIX_PROFILE 设置为与你的环境匹配的任何其他值。

在配置文件中使用环境变量​

使用 ${{ENV_VAR}} 引用必填环境变量，或使用 ${{ENV_VAR:=default_value}} 提供回退值。APISIX 无法获取必填变量时会报告错误。

不同配置文件的环境变量替换时机和类型规则不同：

文件替换时机类型行为
apisix.yaml解析 YAML 前由 YAML 确定结果类型。为占位符加引号，可将看起来像数字或布尔值的值保留为字符串。
config.yaml解析 YAML 后替换后的纯数字会转换为数字，true 或 false 会转换为布尔值。为占位符加引号不会阻止该转换。
apisix.json解析 JSON 后替换后的纯数字会转换为数字，true 或 false 会转换为布尔值。JSON 语法要求占位符位于引号内，但引号不会阻止该转换。

示例​

如果你在本地运行 APISIX（Docker 外部），你可以使用 export 命令设置环境变量：

export YOUR_VARIABLE=value

如果你在 Docker 中运行 APISIX，你应该在启动容器时使用 -e 标志设置环境变量。

在 config.yaml 中使用环境变量​

以下示例在环境变量中设置客户端请求和 Admin API 的监听端口。

例如，在环境变量中设置 APISIX_NODE_LISTEN:8132 和 ADMIN_API_PORT:9232。在 config.yaml 中，你可以按如下方式引用环境变量：

config.yaml
apisix:
  node_listen:
    - ${{APISIX_NODE_LISTEN}}
deployment:
  admin:
    admin_listen:
      port: ${{ADMIN_API_PORT}}

启动后，APISIX 将监听端口 8132 用于客户端请求，监听端口 9232 用于 Admin API 请求。

在 apisix.yaml 中使用环境变量​

以下示例在环境变量中设置路由的上游节点地址。

例如，在环境变量中设置 UPSTREAM_ADDR:httpbin.org。在 apisix.yaml 中，你可以按如下方式引用环境变量：

apisix.yaml
routes:
  - uri: /ip
    upstream:
      nodes:
        "${{UPSTREAM_ADDR}}": 1
      type: roundrobin

在独立模式下，APISIX 会热加载该配置，并开始通过此路由将请求代理到 httpbin.org。

apisix.yaml 中的环境变量会在解析 YAML 之前展开。例如，如果 ROUTE_ID 设置为 1001，请为占位符加上引号，使 YAML 将路由 ID 解析为字符串：

apisix.yaml
routes:
  - id: "${{ROUTE_ID}}"
    uri: /ip
    upstream:
      nodes:
        "${{UPSTREAM_ADDR}}": 1
      type: roundrobin

布尔值和其他数字也遵循相同规则。例如，如果 RETRIES=3，请使用 retries: ${{RETRIES}} 获得整数。如果 API_KEY=12345，请使用 key: "${{API_KEY}}" 将凭证保留为字符串。

在 apisix.json 中使用环境变量​

以下示例在环境变量中设置路由的上游节点地址。

例如，在环境变量中设置 UPSTREAM_ADDR:httpbin.org。在 apisix.json 中，你可以按如下方式引用环境变量：

apisix.json
{
    "routes": [
      {
        "uri": "/ip",
        "upstream": {
          "nodes": {
            "${{UPSTREAM_ADDR}}": 1
          },
          "type": "roundrobin"
        }
      }
    ]
}

在独立模式下，APISIX 将热加载配置并开始将请求代理到此路由到 httpbin.org。

与 apisix.yaml 不同，apisix.json 会先解析再执行替换。如果占位符解析为 3、true 或 false，即使占位符写在 JSON 字符串中，APISIX 也会将其转换为数字或布尔值。

设置回退值​

你还可以配置默认值，以便在未设置环境变量时回退，例如：

config.yaml
apisix:
  node_listen:
    - ${{APISIX_NODE_LISTEN:=9080}}
deployment:
  admin:
    admin_listen:
      port: ${{ADMIN_API_PORT:=9180}}

如果 APISIX 无法在环境中解析 APISIX_NODE_LISTEN 和 ADMIN_API_PORT 的值，它将默认监听端口 9080 用于客户端请求，监听端口 9180 用于 Admin API 请求。