配置文件

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 以使更改生效。

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 设置为与你的环境匹配的任何其他值。

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

在 APISIX 中，你可以在 config.yaml、apisix.yaml 或 apisix.json 配置文件中使用环境变量来配置在部署期间应该可配置的值，使用 ${{ENV_VAR}} 语法或 ${{ENV_VAR:default_value}} 语法。

在 apisix.yaml 等独立模式配置文件中，系统会在解析 YAML 之前解析环境变量。如果占位符未加引号，解析后的值可能会被识别为数字、布尔值等原生 YAML 类型；如果需要保留字符串类型，请为占位符加上引号。

示例

如果你在本地运行 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

在 apisix.json 中使用环境变量

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

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

apisix.json

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

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

设置回退值

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

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 请求。