title: Admin API keywords:

  • APISIX
  • API 网关
  • Admin API
  • 路由
  • 插件
  • 上游 description: 本文介绍了 Apache APISIX Admin API 支持的功能，你可以通过 Admin API 来获取、创建、更新以及删除资源。

描述

Admin API 是一组用于配置 Apache APISIX 路由、上游、服务、SSL 证书等功能的 RESTful API。

你可以通过 Admin API 来获取、创建、更新以及删除资源。同时得益于 APISIX 的热加载能力，资源配置完成后 APISIX 将会自动更新配置，无需重启服务。如果你想要了解其工作原理，请参考 Architecture Design。

相关配置

当 APISIX 启动时，Admin API 默认情况下将会监听 9180 端口，并且会占用前缀为 /apisix/admin 的 API。

因此，为了避免你设计的 API 与 /apisix/admin 冲突，你可以通过修改配置文件 /conf/config.yaml 中的配置修改默认监听端口。

APISIX 支持设置 Admin API 的 IP 访问白名单，防止 APISIX 被非法访问和攻击。你可以在 ./conf/config.yaml 文件中的 deployment.admin.allow_admin 选项中，配置允许访问的 IP 地址。

在下文出现的 X-API-KEY 指的是 ./conf/config.yaml 文件中的 deployment.admin.admin_key.key，它是 Admin API 的访问 token。

:::tip 提示

建议你修改 Admin API 默认的监听端口、IP 访问白名单以及 Admin API 的 token，以保证你的 API 安全。

:::

deployment:
    admin:
        admin_key:
        - name: admin
            key: edd1c9f034335f136f87ad84b625c8f1  # 使用默认的 Admin API Key 存在安全风险，部署到生产环境时请及时更新
            role: admin
        allow_admin:                    # http://nginx.org/en/docs/http/ngx_http_access_module.html#allow
            - 127.0.0.0/24
        admin_listen:
            ip: 0.0.0.0                 # Admin API 监听的 IP，如果不设置，默认为“0.0.0.0”。
            port: 9180                  # Admin API 监听的 端口，必须使用与 node_listen 不同的端口。

使用环境变量

要通过环境变量进行配置，可以使用 ${{VAR}} 语法。例如：

deployment:
  admin:
    admin_key:
    - name: admin
      key: ${{ADMIN_KEY}}
      role: admin
    allow_admin:
    - 127.0.0.0/24
    admin_listen:
      ip: 0.0.0.0
      port: 9180

然后在 make init 之前运行 export ADMIN_KEY=$your_admin_key.

如果找不到配置的环境变量，将抛出错误。

此外，如果要在未设置环境变量时使用默认值，请改用 ${{VAR:=default_value}}。例如：

deployment:
  admin:
    admin_key:
    - name: admin
      key: ${{ADMIN_KEY:=edd1c9f034335f136f87ad84b625c8f1}}
      role: admin
    allow_admin:
    - 127.0.0.0/24
    admin_listen:
      ip: 0.0.0.0
      port: 9180

首先查找环境变量 ADMIN_KEY，如果该环境变量不存在，它将使用 edd1c9f034335f136f87ad84b625c8f1 作为默认值。

您还可以在 yaml 键中指定环境变量。这在 standalone 模式 中特别有用，您可以在其中指定上游节点，如下所示：

routes:
  -
    uri: "/test"
    upstream:
      nodes:
        "${{HOST_IP}}:${{PORT}}": 1
      type: roundrobin
#END

强制删除

默认情况下，Admin API 会检查资源间的引用关系，将会拒绝删除正在使用中的资源。

可以通过在删除请求中添加请求参数 force=true 来进行强制删除，例如：

:::note

您可以这样从 config.yaml 中获取 admin_key 并存入环境变量：

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

:::

$ curl http://127.0.0.1:9180/apisix/admin/upstreams/1 -H "X-API-KEY: $admin_key" -X PUT -d '{
    "nodes": {
        "127.0.0.1:8080": 1
    },
    "type": "roundrobin"
}'
$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '{
    "uri": "/*",
    "upstream_id": 1
}'
{"value":{"priority":0,"upstream_id":1,"uri":"/*","create_time":1689038794,"id":"1","status":1,"update_time":1689038916},"key":"/apisix/routes/1"}

$ curl http://127.0.0.1:9180/apisix/admin/upstreams/1 -H "X-API-KEY: $admin_key" -X DELETE
{"error_msg":"can not delete this upstream, route [1] is still using it now"}
$ curl "http://127.0.0.1:9180/apisix/admin/upstreams/1?force=anyvalue" -H "X-API-KEY: $admin_key" -X DELETE
{"error_msg":"can not delete this upstream, route [1] is still using it now"}
$ curl "http://127.0.0.1:9180/apisix/admin/upstreams/1?force=true" -H "X-API-KEY: $admin_key" -X DELETE
{"deleted":"1","key":"/apisix/upstreams/1"}

v3 版本新功能

在 APISIX v3 版本中，Admin API 支持了一些不向下兼容的新特性，比如支持新的响应体格式、支持分页查询、支持过滤资源等。

支持新的响应体格式

APISIX 在 v3 版本对响应体做了以下调整：

  • 移除旧版本响应体中的 action 字段；
  • 调整获取资源列表时的响应体结构，新的响应体结构示例如下：

返回单个资源：

    {
    "modifiedIndex": 2685183,
    "value": {
        "id": "1",
        ...
    },
    "key": "/apisix/routes/1",
    "createdIndex": 2684956
    }

返回多个资源：

    {
    "list": [
        {
        "modifiedIndex": 2685183,
        "value": {
            "id": "1",
            ...
        },
        "key": "/apisix/routes/1",
        "createdIndex": 2684956
        },
        {
        "modifiedIndex": 2685163,
        "value": {
            "id": "2",
            ...
        },
        "key": "/apisix/routes/2",
        "createdIndex": 2685163
        }
    ],
    "total": 2
    }

支持分页查询

获取资源列表时支持分页查询，目前支持分页查询的资源如下：

参数如下：

名称默认值范围描述
page1[1, ...]页数，默认展示第一页。
page_size[10, 500]每页资源数量。如果不配置该参数，则展示所有查询到的资源。

示例如下：

curl "http://127.0.0.1:9180/apisix/admin/routes?page=1&page_size=10" \
-H "X-API-KEY: $admin_key" -X GET

{
  "total": 1,
  "list": [
    {
      ...
    }
  ]
}

支持过滤资源

在 APISIX v3 版本中，在获取资源列表时，你可以使用 name、label 和 uri 参数过滤资源。支持参数如下：

名称描述
name根据资源的 name 属性进行查询，如果资源本身没有 name 属性则不会出现在查询结果中。
label根据资源的 label 属性进行查询，如果资源本身没有 label 属性则不会出现在查询结果中。
uri该参数仅在 Route 资源上支持。如果 Route 的 uri 等于查询的 uri 或 uris 包含查询的 uri，则该 Route 资源出现在查询结果中。

:::tip 提示

当使用多个过滤参数时，APISIX 将对不同过滤参数的查询结果取交集。

:::

以下示例将返回一个路由列表，该路由列表中的所有路由需要满足以下条件：路由的 name 包含字符串 test；uri 包含字符串 foo；对路由的 label 没有限制，因为 label 为空字符串。

curl 'http://127.0.0.1:9180/apisix/admin/routes?name=test&uri=foo&label=' \
-H "X-API-KEY: $admin_key" -X GET

返回结果：

{
  "total": 1,
  "list": [
    {
      ...
    }
  ]
}

支持引用过滤资源

:::note

这个特性于 APISIX 3.13.0 引入。

APISIX 支持通过 service_id 和 upstream_id 查询路由和 Stream 路由。现在不支持其他资源或字段。

:::

在获取资源列表时，你可以使用 filter 参数过滤资源。

它以以下方式编码：

filter=escape_uri(key1=value1&key2=value2)

以下是一个使用 service_id 进行路由列表过滤的例子。当同时设置了多个过滤条件，结果将为它们的交集。

curl 'http://127.0.0.1:9180/apisix/admin/routes?filter=service_id%3D1' \
-H "X-API-KEY: $admin_key" -X GET

{
  "total": 1,
  "list": [
    {
      ...
    }
  ]
}

Route

Route 也称之为路由，可以通过定义一些规则来匹配客户端的请求，然后根据匹配结果加载并执行相应的插件，并把请求转发给到指定 Upstream（上游）。

请求地址

路由资源请求地址：/apisix/admin/routes/{id}?ttl=0

请求方法

名称请求 URI请求 body描述
GET/apisix/admin/routes无获取资源列表。
GET/apisix/admin/routes/{id}无获取资源。
PUT/apisix/admin/routes/{id}{...}根据 id 创建资源。
POST/apisix/admin/routes{...}创建资源，id 将会自动生成。
DELETE/apisix/admin/routes/{id}无删除指定资源。
PATCH/apisix/admin/routes/{id}{...}标准 PATCH，修改指定 Route 的部分属性，其他不涉及的属性会原样保留；如果你需要删除某个属性，可以将该属性的值设置为 null；当需要修改属性的值为数组时，该属性将全量更新。
PATCH/apisix/admin/routes/{id}/{path}{...}SubPath PATCH，通过 {path} 指定 Route 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。两种 PATCH 的区别，请参考使用示例。

URI 请求参数

名称必选项类型描述示例
ttl否辅助路由的有效期。超过定义的时间，APISIX 将会自动删除路由，单位为秒。ttl=1

body 请求参数

名称必选项类型描述示例值
uri是，与 uris 二选一。匹配规则除了如 /foo/bar、/foo/gloo 这种全量匹配外，使用不同 Router 还允许更高级匹配，更多信息请参考 Router。“/hello”
uris是，不能与 uri 二选一。匹配规则非空数组形式，可以匹配多个 uri。[“/hello”, “/world”]
plugins否PluginPlugin 配置，请参考 Plugin。
script否ScriptScript 配置，请参考 Script。
upstream否UpstreamUpstream 配置，请参考 Upstream。
upstream_id否Upstream需要使用的 Upstream id，请参考 Upstream。
service_id否Service需要绑定的 Service id，请参考 Service。
plugin_config_id否，不能与 Script 共同使用。Plugin需要绑定的 Plugin Config id，请参考 Plugin Config。
name否辅助路由名称。route-test
desc否辅助路由描述信息。用来测试的路由。
host否，与 hosts 二选一。匹配规则当前请求域名，比如 foo.com；也支持泛域名，比如 *.foo.com。“foo.com”
hosts否，与 host 二选一。匹配规则非空列表形态的 host，表示允许有多个不同 host，匹配其中任意一个即可。[“foo.com”, “*.bar.com”]
remote_addr否，与 remote_addrs 二选一。匹配规则客户端请求的 IP 地址。支持 IPv4 地址，如：192.168.1.101 以及 CIDR 格式的支持 192.168.1.0/24；支持 IPv6 地址匹配，如 ::1，fe80::1，fe80::1/64 等。“192.168.1.0/24”
remote_addrs否，与 remote_addr 二选一。匹配规则非空列表形态的 remote_addr，表示允许有多个不同 IP 地址，符合其中任意一个即可。[“127.0.0.1”, “192.0.0.0/8”, “::1”]
methods否匹配规则如果为空或没有该选项，则表示没有任何 method 限制。你也可以配置一个或多个的组合：GET，POST，PUT，DELETE，PATCH，HEAD，OPTIONS，CONNECT，TRACE，PURGE。[“GET”, “POST”]
priority否匹配规则如果不同路由包含相同的 uri，则根据属性 priority 确定哪个 route 被优先匹配，值越大优先级越高，默认值为 0。priority = 10
vars否匹配规则由一个或多个[var, operator, val]元素组成的列表，类似 [[var, operator, val], [var, operator, val], ...]]。例如：["arg_name", "==", "json"] 则表示当前请求参数 name 是 json。此处 var 与 NGINX 内部自身变量命名是保持一致的，所以也可以使用 request_uri、host 等。更多细节请参考 lua-resty-expr。[[“arg_name”, “==”, “json”], [“arg_age”, “>”, 18]]
filter_func否匹配规则用户自定义的过滤函数。可以使用它来实现特殊场景的匹配要求实现。该函数默认接受一个名为 vars 的输入参数，可以用它来获取 NGINX 变量。function(vars) return vars[“arg_name”] == “json” end
labels否匹配规则标识附加属性的键值对。{“version”:“v2”,“build”:“16”,“env”:“production”}
timeout否辅助为 Route 设置 Upstream 连接、发送消息和接收消息的超时时间（单位为秒）。该配置将会覆盖在 Upstream 中配置的 timeout 选项。{“connect”: 3, “send”: 3, “read”: 3}
enable_websocket否辅助当设置为 true 时，启用 websocket(boolean), 默认值为 false。
status否辅助当设置为 1 时，启用该路由，默认值为 1。1 表示启用，0 表示禁用。

:::note 注意

  • 对于同一类参数比如 uri与 uris，upstream 与 upstream_id，host 与 hosts，remote_addr 与 remote_addrs 等，是不能同时存在，二者只能选择其一。如果同时启用，则会出现异常。
  • 在 vars 中，当获取 Cookie 的值时，Cookie name 是区分大小写字母的。例如：var = cookie_x_foo 与 var = cookie_X_Foo 表示不同的 cookie。

:::

Route 对象 JSON 配置示例：

{
    "id": "1",                            # id，非必填
    "uris": ["/a","/b"],                  # 一组 URL 路径
    "methods": ["GET","POST"],            # 可以填多个方法
    "hosts": ["a.com","b.com"],           # 一组 host 域名
    "plugins": {},                        # 指定 route 绑定的插件
    "priority": 0,                        # apisix 支持多种匹配方式，可能会在一次匹配中同时匹配到多条路由，此时优先级高的优先匹配中
    "name": "路由 xxx",
    "desc": "hello world",
    "remote_addrs": ["127.0.0.1"],        # 一组客户端请求 IP 地址
    "vars": [["http_user", "==", "ios"]], # 由一个或多个 [var, operator, val] 元素组成的列表
    "upstream_id": "1",                   # upstream 对象在 etcd 中的 id，建议使用此值
    "upstream": {},                       # upstream 信息对象，建议尽量不要使用
    "timeout": {                          # 为 route 设置 upstream 的连接、发送消息、接收消息的超时时间。
        "connect": 3,
        "send": 3,
        "read": 3
    },
    "filter_func": ""                     # 用户自定义的过滤函数，非必填
}

使用示例

  • 创建一个路由：

    curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PUT -i -d '
{
    "uri": "/index.html",
    "hosts": ["foo.com", "*.bar.com"],
    "remote_addrs": ["127.0.0.0/8"],
    "methods": ["PUT", "GET"],
    "enable_websocket": true,
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'

    HTTP/1.1 201 Created
Date: Sat, 31 Aug 2019 01:17:15 GMT
...

  • 创建一个有效期为 60 秒的路由，过期后自动删除：

    curl 'http://127.0.0.1:9180/apisix/admin/routes/2?ttl=60' \
-H "X-API-KEY: $admin_key" -X PUT -i -d '
{
    "uri": "/aa/index.html",
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'

    HTTP/1.1 201 Created
Date: Sat, 31 Aug 2019 01:17:15 GMT
...

  • 在路由中新增一个上游节点：

    curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "upstream": {
        "nodes": {
            "127.0.0.1:1981": 1
        }
    }
}'

    HTTP/1.1 200 OK
...

    执行成功后，上游节点将更新为：

    {
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 1
}

  • 更新路由中上游节点的权重：

    curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "upstream": {
        "nodes": {
            "127.0.0.1:1981": 10
        }
    }
}'

    HTTP/1.1 200 OK
...

    执行成功后，上游节点将更新为：

    {
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 10
}

  • 从路由中删除一个上游节点：

    curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "upstream": {
        "nodes": {
            "127.0.0.1:1980": null
        }
    }
}'

    HTTP/1.1 200 OK
...

    执行成功后，Upstream nodes 将更新为：

    {
    "127.0.0.1:1981": 10
}

  • 更新路由中的 methods 数组

    curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '{
    "methods": ["GET", "POST"]
}'

    HTTP/1.1 200 OK
...

    执行成功后，methods 将不保留原来的数据，将更新为：

    ["GET", "POST"]

  • 使用 sub path 更新路由中的上游节点：

    curl http://127.0.0.1:9180/apisix/admin/routes/1/upstream/nodes \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "127.0.0.1:1982": 1
}'

    HTTP/1.1 200 OK
...

    执行成功后，nodes 将不保留原来的数据，整个更新为：

    {
    "127.0.0.1:1982": 1
}

  • 使用 sub path 更新路由中的 methods：

    curl http://127.0.0.1:9180/apisix/admin/routes/1/methods \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '["POST", "DELETE", "PATCH"]'

    HTTP/1.1 200 OK
...

    执行成功后，methods 将不保留原来的数据，更新为：

    ["POST", "DELETE", "PATCH"]

  • 禁用路由

    curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "status": 0
}'

    HTTP/1.1 200 OK
...

    执行成功后，status 将更新为：

    {
    "status": 0
}

  • 启用路由

    curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "status": 1
}'

    HTTP/1.1 200 OK
...

    执行成功后，status 将更新为：

    {
    "status": 1
}

应答参数

目前是直接返回与 etcd 交互后的结果。

Service

Service 是某类 API 的抽象（也可以理解为一组 Route 的抽象）。它通常与上游服务抽象是一一对应的，Route 与 Service 之间，通常是 N:1 的关系。

请求地址

服务资源请求地址：/apisix/admin/services/{id}

请求方法

名称请求 URI请求 body描述
GET/apisix/admin/services无获取资源列表。
GET/apisix/admin/services/{id}无获取资源。
PUT/apisix/admin/services/{id}{...}创建指定 id 资源。
POST/apisix/admin/services{...}创建资源，id 由后台服务自动生成。
DELETE/apisix/admin/services/{id}无删除资源。
PATCH/apisix/admin/services/{id}{...}标准 PATCH，修改已有 Service 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；注意：当需要修改属性的值为数组时，该属性将全量更新。
PATCH/apisix/admin/services/{id}/{path}{...}SubPath PATCH，通过 {path} 指定 Service 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。

body 请求参数

名称必选项类型描述示例
plugins否PluginPlugin 配置，请参考 Plugin。
upstream与 upstream_id 二选一。UpstreamUpstream 配置，请参考 Upstream。
upstream_id与 upstream 二选一。Upstream需要使用的 upstream id，请参考 Upstream。
name否辅助服务名称。
desc否辅助服务描述。
labels否匹配规则标识附加属性的键值对。{“version”:“v2”,“build”:“16”,“env”:“production”}
enable_websocket否辅助websocket(boolean) 配置，默认值为 false。
hosts否匹配规则非空列表形态的 host，表示允许有多个不同 host，匹配其中任意一个即可。[“foo.com”, “*.bar.com”]

Service 对象 JSON 配置示例：

{
    "id": "1",                # id
    "plugins": {},            # 指定 service 绑定的插件
    "upstream_id": "1",       # upstream 对象在 etcd 中的 id，建议使用此值
    "upstream": {},           # upstream 信息对象，不建议使用
    "name": "test svc",       # service 名称
    "desc": "hello world",    # service 描述
    "enable_websocket": true, # 启动 websocket 功能
    "hosts": ["foo.com"]
}

使用示例

  • 创建一个 Service：

    curl http://127.0.0.1:9180/apisix/admin/services/201  \
-H "X-API-KEY: $admin_key" -X PUT -i -d '
{
    "plugins": {
        "limit-count": {
            "count": 2,
            "time_window": 60,
            "rejected_code": 503,
            "key": "remote_addr"
        }
    },
    "enable_websocket": true,
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'

    HTTP/1.1 201 Created
...

  • 在 Service 中添加一个上游节点：

    curl http://127.0.0.1:9180/apisix/admin/services/201 \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "upstream": {
        "nodes": {
            "127.0.0.1:1981": 1
        }
    }
}'

    HTTP/1.1 200 OK
...

    执行成功后，上游节点将更新为：

    {
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 1
}

  • 更新一个上游节点的权重：

    curl http://127.0.0.1:9180/apisix/admin/services/201 \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "upstream": {
        "nodes": {
            "127.0.0.1:1981": 10
        }
    }
}'

    HTTP/1.1 200 OK
...

    执行成功后，上游节点将更新为：

    {
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 10
}

  • 删除 Service 中的一个上游节点：

    curl http://127.0.0.1:9180/apisix/admin/services/201 \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "upstream": {
        "nodes": {
            "127.0.0.1:1980": null
        }
    }
}'

    HTTP/1.1 200 OK
...

    执行成功后，上游节点将更新为：

    {
    "127.0.0.1:1981": 10
}

  • 替换 Service 的上游节点：

    curl http://127.0.0.1:9180/apisix/admin/services/201/upstream/nodes \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "127.0.0.1:1982": 1
}'

    HTTP/1.1 200 OK
...

    执行成功后，上游节点不再保留原来的数据，将更新为：

    {
    "127.0.0.1:1982": 1
}

应答参数

目前是直接返回与 etcd 交互后的结果。

Consumer

Consumer 是某类服务的消费者，需要与用户认证体系配合才能使用。Consumer 使用 username 作为唯一标识，仅支持使用 HTTP PUT 方法创建 Consumer。

请求地址

Consumer 资源请求地址：/apisix/admin/consumers/{username}

请求方法

名称请求 URI请求 body描述
GET/apisix/admin/consumers无获取资源列表。
GET/apisix/admin/consumers/{username}无获取资源。
PUT/apisix/admin/consumers{...}创建资源。
DELETE/apisix/admin/consumers/{username}无删除资源。

body 请求参数

名称必选项类型描述示例值
username是辅助Consumer 名称。
group_id否辅助Consumer Group 名称。
plugins否Plugin该 Consumer 对应的插件配置，它的优先级是最高的：Consumer > Route > Plugin Config > Service。对于具体插件配置，请参考 Plugins。
desc否辅助consumer 描述。
labels否匹配规则标识附加属性的键值对。{“version”:“v2”,“build”:“16”,“env”:“production”}

Consumer 对象 JSON 配置示例：

{
    "plugins": {},          # 指定 consumer 绑定的插件
    "username": "name",     # 必填
    "desc": "hello world"   # consumer 描述
}

当认证插件与 Consumer 一起使用时，需要提供用户名、密码等信息；当认证插件与 Route 或 Service 绑定时，则不需要任何参数，因为此时 APISIX 是根据用户请求数据来判断用户对应的是哪个 Consumer。

:::note 注意

从 APISIX v2.2 版本开始，同一个 Consumer 可以绑定多个认证插件。

:::

使用示例

  • 创建 Consumer，并指定认证插件 key-auth，并开启指定插件 limit-count：

    curl http://127.0.0.1:9180/apisix/admin/consumers  \
-H "X-API-KEY: $admin_key" -X PUT -i -d '
{
    "username": "jack",
    "plugins": {
        "key-auth": {
            "key": "auth-one"
        },
        "limit-count": {
            "count": 2,
            "time_window": 60,
            "rejected_code": 503,
            "key": "remote_addr"
        }
    }
}'

    HTTP/1.1 200 OK
Date: Thu, 26 Dec 2019 08:17:49 GMT
...

{"key":"\/apisix\/consumers\/jack","value":{"username":"jack","update_time":1666260780,"plugins":{"limit-count":{"key_type":"var","count":2,"rejected_code":503,"show_limit_quota_header":true,"time_window":60,"key":"remote_addr","allow_degradation":false,"policy":"local"},"key-auth":{"key":"auth-one"}},"create_time":1666260780}}

应答参数

目前是直接返回与 etcd 交互后的结果。

Credential

Credential 用以存放 Consumer 的认证凭证。当需要为 Consumer 配置多个凭证时，可以使用 Credential。

请求地址

Credential 资源请求地址：/apisix/admin/consumers/{username}/credentials/{credential_id}

请求方法

名称请求 URI请求 body描述
GET/apisix/admin/consumers/{username}/credentials无获取资源列表。
GET/apisix/admin/consumers/{username}/credentials/{credential_id}无获取资源。
PUT/apisix/admin/consumers/{username}/credentials/{credential_id}{...}创建资源。
DELETE/apisix/admin/consumers/{username}/credentials/{credential_id}无删除资源。

body 请求参数

名称必选项类型描述示例值
plugins是Plugin该 Credential 对应的插件配置。
name否辅助消费者 Credential 名credential_primary
desc否辅助Credential 描述。
labels否匹配规则标识附加属性的键值对。{“version”:“v2”,“build”:“16”,“env”:“production”}

Credential 对象 JSON 配置示例：

{
    "plugins": {
      "key-auth": {
        "key": "auth-one"
      }
    },
    "desc": "hello world"
}

使用示例

前提：已创建 Consumer jack。

创建 Credential，并启用认证插件 key-auth：

curl http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials/auth-one  \
-H "X-API-KEY: $admin_key" -X PUT -i -d '
{
    "plugins": {
        "key-auth": {
            "key": "auth-one"
        }
    }
}'

HTTP/1.1 200 OK
Date: Thu, 26 Dec 2019 08:17:49 GMT
...

{"key":"\/apisix\/consumers\/jack\/credentials\/auth-one","value":{"update_time":1666260780,"plugins":{"key-auth":{"key":"auth-one"}},"create_time":1666260780}}

Upstream

Upstream 是虚拟主机抽象，对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到 Route（或 Service) 上，当 Upstream 有重复时，需要用“引用”方式避免重复。

请求地址

Upstream 资源请求地址：/apisix/admin/upstreams/{id}

请求方法

名称请求 URI请求 body描述
GET/apisix/admin/upstreams/{id}无获取资源。
PUT/apisix/admin/upstreams/{id}{...}创建指定 id 的资源。
POST/apisix/admin/upstreams{...}创建资源，id 由后台服务自动生成。
DELETE/apisix/admin/upstreams/{id}无删除资源。
PATCH/apisix/admin/upstreams/{id}{...}标准 PATCH，修改已有 Upstream 的部分属性，其他不涉及的属性会原样保留；如果需要删除某个属性，可将该属性的值设置为 null；注意：当需要修改属性的值为数组时，该属性将全量更新。
PATCH/apisix/admin/upstreams/{id}/{path}{...}SubPath PATCH，通过 {path} 指定 Upstream 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。

body 请求参数

APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上游做主被动健康检查、重试等逻辑。详细信息如下：

名称必选项类型描述示例
type否枚举负载均衡算法，默认值是roundrobin。
nodes是，与 service_name 二选一。Node哈希表或数组。当它是哈希表时，内部元素的 key 是上游机器地址列表，格式为地址 +（可选的）端口，其中地址部分可以是 IP 也可以是域名，比如 192.168.1.100:80、foo.com:80等。对于哈希表的情况，如果 key 是 IPv6 地址加端口，则必须用中括号将 IPv6 地址括起来。value 则是节点的权重。当它是数组时，数组中每个元素都是一个哈希表，其中包含 host、weight 以及可选的 port、priority。nodes 可以为空，这通常用作占位符。客户端命中这样的上游会返回 502。192.168.1.100:80, [::1]:80
service_name是，与 nodes 二选一。string服务发现时使用的服务名，请参考 集成服务发现注册中心。a-bootiful-client
discovery_type是，与 service_name 配合使用。string服务发现类型，请参考 集成服务发现注册中心。eureka
key条件必需匹配类型该选项只有类型是 chash 才有效。根据 key 来查找对应的节点 id，相同的 key 在同一个对象中，则返回相同 id。目前支持的 NGINX 内置变量有 uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***，其中 arg_*** 是来自 URL 的请求参数，详细信息请参考 NGINX 变量列表。
checks否health_checker配置健康检查的参数，详细信息请参考 health-check。
retries否整型使用 NGINX 重试机制将请求传递给下一个上游，默认启用重试机制且次数为后端可用的节点数量。如果指定了具体重试次数，它将覆盖默认值。当设置为 0 时，表示不启用重试机制。
retry_timeout否number限制是否继续重试的时间，若之前的请求和重试请求花费太多时间就不再继续重试。当设置为 0 时，表示不启用重试超时机制。
timeout否超时时间对象设置连接、发送消息、接收消息的超时时间，以秒为单位。{"connect": 0.5,"send": 0.5,"read": 0.5}
hash_on否辅助hash_on 支持的类型有 vars（NGINX 内置变量），header（自定义 header），cookie，consumer，默认值为 vars。
name否辅助标识上游服务名称、使用场景等。
desc否辅助上游服务描述、使用场景等。
pass_host否枚举请求发给上游时的 host 设置选型。 [pass，node，rewrite] 之一，默认是 pass。pass: 将客户端的 host 透传给上游； node: 使用 upstream node 中配置的 host； rewrite: 使用配置项 upstream_host 的值。
upstream_host否辅助指定上游请求的 host，只在 pass_host 配置为 rewrite 时有效。
scheme否辅助跟上游通信时使用的 scheme。对于 7 层代理，可选值为 [http, https, grpc, grpcs]。对于 4 层代理，可选值为 [tcp, udp, tls]。默认值为 http，详细信息请参考下文。
labels否匹配规则标识附加属性的键值对。{“version”:“v2”,“build”:“16”,“env”:“production”}
tls.client_cert否，不能和 tls.client_cert_id 一起使用https 证书设置跟上游通信时的客户端证书，详细信息请参考下文。
tls.client_key否，不能和 tls.client_cert_id 一起使用https 证书私钥设置跟上游通信时的客户端私钥，详细信息请参考下文。
tls.client_cert_id否，不能和 tls.client_cert、tls.client_key 一起使用SSL设置引用的 SSL id，详见 SSL。
tls.verify否，目前仅支持 Kafka 上游。Boolean开启服务器证书验证功能，目前仅支持 Kafka 上游。
keepalive_pool.size否辅助动态设置 keepalive 指令，详细信息请参考下文。
keepalive_pool.idle_timeout否辅助动态设置 keepalive_timeout 指令，详细信息请参考下文。
keepalive_pool.requests否辅助动态设置 keepalive_requests 指令，详细信息请参考下文。

type 详细信息如下：

  • roundrobin: 带权重的 Round Robin。
  • chash: 一致性哈希。
  • ewma: 选择延迟最小的节点，请参考 EWMA_chart。
  • least_conn: 选择 (active_conn + 1) / weight 最小的节点。此处的 active connection 概念跟 NGINX 的相同，它是当前正在被请求使用的连接。
  • 用户自定义的 balancer，需要可以通过 require("apisix.balancer.your_balancer") 来加载。

hash_on 详细信息如下：

  • 设为 vars 时，key 为必传参数，目前支持的 NGINX 内置变量有 uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***，其中 arg_*** 是来自 URL 的请求参数。详细信息请参考 NGINX 变量列表。
  • 设为 header 时，key 为必传参数，其值为自定义的 Header name，即 “http_key”。
  • 设为 cookie 时，key 为必传参数，其值为自定义的 cookie name，即 “cookie_key”。请注意 cookie name 是区分大小写字母的。例如：cookie_x_foo 与 cookie_X_Foo 表示不同的 cookie。
  • 设为 consumer 时，key 不需要设置。此时哈希算法采用的 key 为认证通过的 consumer_name。

以下特性需要 APISIX 运行于 APISIX-Runtime：

  • scheme 可以设置成 tls，表示 TLS over TCP。
  • tls.client_cert/key 可以用来跟上游进行 mTLS 通信。他们的格式和 SSL 对象的 cert 和 key 一样。
  • tls.client_cert_id 可以用来指定引用的 SSL 对象。只有当 SSL 对象的 type 字段为 client 时才能被引用，否则请求会被 APISIX 拒绝。另外，SSL 对象中只有 cert 和 key 会被使用。
  • keepalive_pool 允许 Upstream 有自己单独的连接池。它下属的字段，比如 requests，可以用于配置上游连接保持的参数。

Upstream 对象 JSON 配置示例：

{
    "id": "1",                  # id
    "retries": 1,               # 请求重试次数
    "timeout": {                # 设置连接、发送消息、接收消息的超时时间，每项都为 15 秒
        "connect":15,
        "send":15,
        "read":15
    },
    "nodes": {"host:80": 100},  # 上游机器地址列表，格式为`地址 + 端口`
                                # 等价于 "nodes": [ {"host":"host", "port":80, "weight": 100} ],
    "type":"roundrobin",
    "checks": {},               # 配置健康检查的参数
    "hash_on": "",
    "key": "",
    "name": "upstream-xxx",     # upstream 名称
    "desc": "hello world",      # upstream 描述
    "scheme": "http"            # 跟上游通信时使用的 scheme，默认是 `http`
}

使用示例

创建 Upstream 并对 nodes 的数据进行修改

  1. 创建 Upstream：

    curl http://127.0.0.1:9180/apisix/admin/upstreams/100  \
-H "X-API-KEY: $admin_key" -i -X PUT -d '
{
    "type":"roundrobin",
    "nodes":{
        "127.0.0.1:1980": 1
    }
}'

    HTTP/1.1 201 Created
...

  2. 在 Upstream 中添加一个节点：

    curl http://127.0.0.1:9180/apisix/admin/upstreams/100 \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "nodes": {
        "127.0.0.1:1981": 1
    }
}'

    HTTP/1.1 200 OK
...

    执行成功后，nodes 将更新为：

    {
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 1
}

  3. 更新 Upstream 中单个节点的权重：

    curl http://127.0.0.1:9180/apisix/admin/upstreams/100 \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "nodes": {
        "127.0.0.1:1981": 10
    }
}'

    HTTP/1.1 200 OK
...

    执行成功后，nodes 将更新为：

    {
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 10
}

  4. 删除 Upstream 中的一个节点：

    curl http://127.0.0.1:9180/apisix/admin/upstreams/100 \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "nodes": {
        "127.0.0.1:1980": null
    }
}'

    HTTP/1.1 200 OK
...

    执行成功后，nodes 将更新为：

    {
    "127.0.0.1:1981": 10
}

  5. 更新 Upstream 的 nodes：

    curl http://127.0.0.1:9180/apisix/admin/upstreams/100/nodes \
-H "X-API-KEY: $admin_key" -X PATCH -i -d '
{
    "127.0.0.1:1982": 1
}'

    HTTP/1.1 200 OK
...

    执行成功后，nodes 将不再保留原来的数据：

    {
    "127.0.0.1:1982": 1
}

将客户端请求代理到上游 https 服务

  1. 创建 Route 并配置 Upstream 的 Scheme 为 https：

    curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "uri": "/get",
    "upstream": {
        "type": "roundrobin",
        "scheme": "https",
        "nodes": {
            "httpbin.org:443": 1
        }
    }
}'

    执行成功后，请求与上游通信时的 Scheme 将为 https。

  2. 发送请求进行测试：

    curl http://127.0.0.1:9080/get

    {
"args": {},
"headers": {
    "Accept": "*/*",
    "Host": "127.0.0.1",
    "User-Agent": "curl/7.29.0",
    "X-Amzn-Trace-Id": "Root=1-6058324a-0e898a7f04a5e95b526bb183",
    "X-Forwarded-Host": "127.0.0.1"
},
"origin": "127.0.0.1",
"url": "https://127.0.0.1/get"
}

    请求成功，表示代理上游 https 生效了。

    :::tip 提示

    每个节点均可以配置优先级，只有在高优先级的节点不可用或者尝试过，才会访问一个低优先级的节点。

    :::

    由于上游节点的默认优先级是 0，你可以将一些节点的优先级设置为负数，让其作为备份节点。例如：

    {
    "uri": "/hello",
    "upstream": {
        "type": "roundrobin",
        "nodes": [
            {"host": "127.0.0.1", "port": 1980, "weight": 2000},
            {"host": "127.0.0.1", "port": 1981, "weight": 1, "priority": -1}
        ],
        "checks": {
            "active": {
                "http_path": "/status",
                "healthy": {
                    "interval": 1,
                    "successes": 1
                },
                "unhealthy": {
                    "interval": 1,
                    "http_failures": 1
                }
            }
        }
    }
}

    节点 127.0.0.2 只有在 127.0.0.1 不可用或者尝试过之后才会被访问，因此它是 127.0.0.1 的备份。

应答参数

目前是直接返回与 etcd 交互后的结果。

SSL

你可以使用该资源创建 SSL 证书。

请求地址

SSL 资源请求地址：/apisix/admin/ssls/{id}

请求方法

名称请求 URI请求 body描述
GET/apisix/admin/ssls无获取资源列表。
GET/apisix/admin/ssls/{id}无获取资源。
PUT/apisix/admin/ssls/{id}{...}创建指定 id 的资源。
POST/apisix/admin/ssls{...}创建资源，id 由后台服务自动生成。
DELETE/apisix/admin/ssls/{id}无删除资源。

body 请求参数

名称必选项类型描述示例
cert是证书HTTP 证书。该字段支持使用 APISIX Secret 资源，将值保存在 Secret Manager 中。
key是私钥HTTPS 证书私钥。该字段支持使用 APISIX Secret 资源，将值保存在 Secret Manager 中。
certs否证书字符串数组当你想给同一个域名配置多个证书时，除了第一个证书需要通过 cert 传递外，剩下的证书可以通过该参数传递上来。该字段支持使用 APISIX Secret 资源，将值保存在 Secret Manager 中。
keys否私钥字符串数组certs 对应的证书私钥，需要与 certs 一一对应。该字段支持使用 APISIX Secret 资源，将值保存在 Secret Manager 中。
client.ca否证书设置将用于客户端证书校验的 CA 证书。该特性需要 OpenResty 为 1.19 及以上版本。
client.depth否辅助设置客户端证书校验的深度，默认为 1。该特性需要 OpenResty 为 1.19 及以上版本。
client.skip_mtls_uri_regex否PCRE 正则表达式数组用来匹配请求的 URI，如果匹配，则该请求将绕过客户端证书的检查，也就是跳过 MTLS。[“/hello[0-9]+”, “/foobar”]
snis是匹配规则非空数组形式，可以匹配多个 SNI。
desc否辅助证书描述。certs for production env
labels否匹配规则标识附加属性的键值对。{“version”:“v2”,“build”:“16”,“env”:“production”}
type否辅助标识证书的类型，默认值为 server。client 表示证书是客户端证书，APISIX 访问上游时使用；server 表示证书是服务端证书，APISIX 验证客户端请求时使用。
status否辅助当设置为 1 时，启用此 SSL，默认值为 1。1 表示启用，0 表示禁用
ssl_protocols否tls 协议字符串数组用于控制服务器与客户端之间使用的 SSL/TLS 协议版本。更多的配置示例，请参考SSL 协议。["TLSv1.1", "TLSv1.2", "TLSv1.3"]

SSL 对象 JSON 配置示例：

{
    "id": "1",          # id
    "cert": "cert",     # 证书
    "key": "key",       # 私钥
    "snis": ["t.com"]   # HTTPS 握手时客户端发送的 SNI
}

更多的配置示例，请参考证书。

Global Rules

Global Rule 可以设置全局运行的插件，设置为全局规则的插件将在所有路由级别的插件之前优先运行。

请求地址

Global Rule 资源请求地址：/apisix/admin/global_rules/{id}

请求方法

名称请求 URI请求 body描述
GET/apisix/admin/global_rules无获取资源列表。
GET/apisix/admin/global_rules/{id}无获取资源。
PUT/apisix/admin/global_rules/{id}{...}将创建指定 id 的资源。
DELETE/apisix/admin/global_rules/{id}无删除资源。
PATCH/apisix/admin/global_rules/{id}{...}标准 PATCH，修改已有 Global Rule 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；注意：当需要修改属性的值为数组时，该属性将全量更新。
PATCH/apisix/admin/global_rules/{id}/{path}{...}SubPath PATCH，通过 {path} 指定 Global Rule 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。

body 请求参数

名称必选项类型描述示例值
plugins是Plugin插件配置。详细信息请参考 Plugin。

Consumer Group

你可以使用该资源配置一组可以在 Consumer 间复用的插件。

请求地址

Consumer Group 资源请求地址：/apisix/admin/consumer_groups/{id}

请求方法

名称请求 URI请求 body描述
GET/apisix/admin/consumer_groups无获取资源列表。
GET/apisix/admin/consumer_groups/{id}无获取资源。
PUT/apisix/admin/consumer_groups/{id}{...}将创建指定 id 的资源。
DELETE/apisix/admin/consumer_groups/{id}无删除资源。
PATCH/apisix/admin/consumer_groups/{id}{...}标准 PATCH，修改已有 Consumer Group 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；注意：当需要修改属性的值为数组时，该属性将全量更新。
PATCH/apisix/admin/consumer_groups/{id}/{path}{...}SubPath PATCH，通过 {path} 指定 Consumer Group 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。

body 请求参数

名称必选项类型描述示例值
plugins是Plugin插件配置。详细信息请参考 Plugin。
name否辅助消费者组名。premium-tier
desc否辅助标识描述、使用场景等。Consumer 测试。
labels否辅助标识附加属性的键值对。{“version”:“v2”,“build”:“16”,“env”:“production”}

Plugin Config

你可以使用 Plugin Config 资源创建一组可以在路由间复用的插件。

请求地址

Plugin Config 资源请求地址：/apisix/admin/plugin_configs/{id}

请求方法

名称请求 URI请求 body描述
GET/apisix/admin/plugin_configs无获取资源列表。
GET/apisix/admin/plugin_configs/{id}无获取资源。
PUT/apisix/admin/plugin_configs/{id}{...}根据 id 创建资源。
DELETE/apisix/admin/plugin_configs/{id}无删除资源。
PATCH/apisix/admin/plugin_configs/{id}{...}标准 PATCH，修改已有 Plugin Config 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；注意：当需要修改属性的值为数组时，该属性将全量更新。
PATCH/apisix/admin/plugin_configs/{id}/{path}{...}SubPath PATCH，通过 {path} 指定 Plugin Config 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。

body 请求参数

名称必选项类型描述示例值
plugins是Plugin更多信息请参考 Plugin。
desc否辅助标识描述、使用场景等。customer xxxx
labels否辅助标识附加属性的键值对。{“version”:“v2”,“build”:“16”,“env”:“production”}

Plugin Metadata

你可以使用 Plugin Metadata 资源配置插件元数据。

请求地址

Plugin Config 资源请求地址：/apisix/admin/plugin_metadata/{plugin_name}

请求方法

Method请求 URI请求 body描述
GET/apisix/admin/plugin_metadata无获取所有插件元数据列表。
GET/apisix/admin/plugin_metadata/{plugin_name}无获取资源。
PUT/apisix/admin/plugin_metadata/{plugin_name}{...}根据 plugin name 创建资源。
DELETE/apisix/admin/plugin_metadata/{plugin_name}无删除资源。

body 请求参数

根据插件 ({plugin_name}) 的 metadata_schema 定义的数据结构的 JSON 对象。

使用示例

curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/example-plugin  \
-H "X-API-KEY: $admin_key" -i -X PUT -d '
{
    "skey": "val",
    "ikey": 1
}'

HTTP/1.1 201 Created
Date: Thu, 26 Dec 2019 04:19:34 GMT
Content-Type: text/plain

Plugin

你可以通过该资源获取插件列表。

请求地址

Plugin 资源请求地址：/apisix/admin/plugins/{plugin_name}

请求参数

名称描述默认
subsystem插件子系统。http

可以在子系统上过滤插件，以便在通过查询参数传递的子系统中搜索 ({plugin_name})

请求方法

名称       请求 URI请求 body描述         
GET      /apisix/admin/plugins/list无获取资源列表。
GET      /apisix/admin/plugins/{plugin_name}无获取资源。
GET/apisix/admin/plugins?all=true无获取所有插件的所有属性。
GET/apisix/admin/plugins?all=true&subsystem=stream无获取所有 Stream 插件的属性。
GET/apisix/admin/plugins?all=true&subsystem=http无获取所有 HTTP 插件的属性。
PUT/apisix/admin/plugins/reload无根据代码中所做的更改重新加载插件。
GETapisix/admin/plugins/{plugin_name}?subsystem=stream无获取指定 Stream 插件的属性。
GETapisix/admin/plugins/{plugin_name}?subsystem=http无获取指定 HTTP 插件的属性。

:::caution

获取所有插件属性的接口 /apisix/admin/plugins?all=true 将很快被弃用。

:::

使用示例

获取插件  ({plugin_name})  数据结构的 JSON 对象。

  • 获取插件列表

    curl "http://127.0.0.1:9180/apisix/admin/plugins/list" \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'

    ["zipkin","request-id",...]

  • 获取指定插件的属性

    curl "http://127.0.0.1:9180/apisix/admin/plugins/key-auth?subsystem=http" \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'

    {"$comment":"this is a mark for our injected plugin schema","properties":{"header":{"default":"apikey","type":"string"},"hide_credentials":{"default":false,"type":"boolean"},"_meta":{"properties":{"filter":{"type":"array","description":"filter determines whether the plugin needs to be executed at runtime"},"disable":{"type":"boolean"},"error_response":{"oneOf":[{"type":"string"},{"type":"object"}]},"priority":{"type":"integer","description":"priority of plugins by customized order"}},"type":"object"},"query":{"default":"apikey","type":"string"}},"type":"object"}

:::tip

你可以使用 /apisix/admin/plugins?all=true 接口获取所有插件的所有属性，每个插件包括 name，priority，type，schema，consumer_schema 和 version。

这个 API 将很快被弃用。

:::

Stream Route

Stream Route 是用于 TCP/UDP 动态代理的路由。详细信息请参考 TCP/UDP 动态代理。

请求地址

Plugin 资源请求地址：/apisix/admin/stream_routes/{id}

请求方法

名称请求 URI请求 body描述
GET/apisix/admin/stream_routes无获取资源列表。
GET/apisix/admin/stream_routes/{id}无获取资源。
PUT/apisix/admin/stream_routes/{id}{...}创建指定 id 的资源。
POST/apisix/admin/stream_routes{...}创建资源，id 由后台服务自动生成。
DELETE/apisix/admin/stream_routes/{id}无删除资源。

body 请求参数{#stream-route-body-request-parameters}

名称必选项类型描述示例值
name否辅助Stream 路由名。postgres-proxy
desc否辅助Stream 路由描述。proxy endpoint for postgresql
labels否匹配规则标识附加属性的键值对。{“version”:“17”,“service”:“user”,“env”:“production”}
upstream否UpstreamUpstream 配置，详细信息请参考 Upstream。
upstream_id否Upstream需要使用的 Upstream id，详细信息请 Upstream。
service_id否String需要使用的 Service id.
remote_addr否IPv4, IPv4 CIDR, IPv6过滤选项：如果客户端 IP 匹配，则转发到上游“127.0.0.1” 或 “127.0.0.1/32” 或 “::1”
server_addr否IPv4, IPv4 CIDR, IPv6过滤选项：如果 APISIX 服务器的 IP 与 server_addr 匹配，则转发到上游。“127.0.0.1” 或 “127.0.0.1/32” 或 “::1”
server_port否整数过滤选项：如果 APISIX 服务器的端口 与 server_port 匹配，则转发到上游。9090
sni否Host服务器名称。“test.com”
protocol.name否字符串xRPC 框架代理的协议的名称。“redis”
protocol.conf否配置协议特定的配置。

你可以查看 Stream Proxy 了解更多过滤器的信息。

Secret

Secret 指的是 Secrets Management（密钥管理），可以使用任何支持的密钥管理器，例如 vault。

请求地址

Secret 资源请求地址：/apisix/admin/secrets/{secretmanager}/{id}

请求方法

名称请求 URI请求 body描述
GET/apisix/admin/secretsNULL获取所有 secret 的列表。
GET/apisix/admin/secrets/{manager}/{id}NULL根据 id 获取指定的 secret。
PUT/apisix/admin/secrets/{manager}{...}创建新的 secret 配置。
DELETE/apisix/admin/secrets/{manager}/{id}NULL删除具有指定 id 的 secret。
PATCH/apisix/admin/secrets/{manager}/{id}{...}更新指定 secret 的选定属性。如果要删除一个属性，可以将该属性的值设置为 null。
PATCH/apisix/admin/secrets/{manager}/{id}/{path}{...}更新路径中指定的属性。其他属性的值保持不变。

body 请求参数

当 Secret Manager 是 Vault 时

名称必选项类型描述例子
uri是URIVault 服务器的 URI
prefix是字符串密钥前缀
token是字符串Vault 令牌
namespace否字符串Vault 命名空间，该字段无默认值admin

配置示例：

{
    "uri": "https://localhost/vault",
    "prefix": "/apisix/kv",
    "token": "343effad"
}

使用示例：

curl -i http://127.0.0.1:9180/apisix/admin/secrets/vault/test2 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "uri": "http://xxx/get",
    "prefix" : "apisix",
    "token" : "apisix"
}'

HTTP/1.1 200 OK
...

{"key":"\/apisix\/secrets\/vault\/test2","value":{"id":"vault\/test2","token":"apisix","prefix":"apisix","update_time":1669625828,"create_time":1669625828,"uri":"http:\/\/xxx\/get"}}

当 Secret Manager 是 AWS 时

名称必选项默认值描述
access_key_id是AWS 访问密钥 ID
secret_access_key是AWS 访问密钥
session_token否临时访问凭证信息
region否us-east-1AWS 区域
endpoint_url否https://secretsmanager.{region}.amazonaws.comAWS Secret Manager 地址

配置示例：

{
    "endpoint_url": "http://127.0.0.1:4566",
    "region": "us-east-1",
    "access_key_id": "access",
    "secret_access_key": "secret",
    "session_token": "token"
}

使用示例：

curl -i http://127.0.0.1:9180/apisix/admin/secrets/aws/test3 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "endpoint_url": "http://127.0.0.1:4566",
    "region": "us-east-1",
    "access_key_id": "access",
    "secret_access_key": "secret",
    "session_token": "token"
}'

HTTP/1.1 200 OK
...

{"value":{"create_time":1726069970,"endpoint_url":"http://127.0.0.1:4566","region":"us-east-1","access_key_id":"access","secret_access_key":"secret","id":"aws/test3","update_time":1726069970,"session_token":"token"},"key":"/apisix/secrets/aws/test3"}

当 Secret Manager 是 GCP 时

名称必选项默认值描述
auth_config是auth_config 和 auth_file 必须配置一个。
auth_config.client_email是谷歌服务帐号的 email 参数。
auth_config.private_key是谷歌服务帐号的私钥参数。
auth_config.project_id是谷歌服务帐号的项目 ID。
auth_config.token_uri否https://oauth2.googleapis.com/token请求谷歌服务帐户的令牌的 URI。
auth_config.entries_uri否https://secretmanager.googleapis.com/v1谷歌密钥服务访问端点 API。
auth_config.scope否https://www.googleapis.com/auth/cloud-platform谷歌服务账号的访问范围，可参考 OAuth 2.0 Scopes for Google APIs
auth_file是auth_config 和 auth_file 必须配置一个。
ssl_verify否true当设置为 true 时，启用 SSL 验证。

配置示例：

{
    "auth_config" : {
        "client_email": "email@apisix.iam.gserviceaccount.com",
        "private_key": "private_key",
        "project_id": "apisix-project",
        "token_uri": "https://oauth2.googleapis.com/token",
        "entries_uri": "https://secretmanager.googleapis.com/v1",
        "scope": ["https://www.googleapis.com/auth/cloud-platform"]
    }
}

使用示例：

curl -i http://127.0.0.1:9180/apisix/admin/secrets/gcp/test4 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "auth_config" : {
        "client_email": "email@apisix.iam.gserviceaccount.com",
        "private_key": "private_key",
        "project_id": "apisix-project",
        "token_uri": "https://oauth2.googleapis.com/token",
        "entries_uri": "https://secretmanager.googleapis.com/v1",
        "scope": ["https://www.googleapis.com/auth/cloud-platform"]
    }
}'

HTTP/1.1 200 OK
...

{"value":{"id":"gcp/test4","ssl_verify":true,"auth_config":{"token_uri":"https://oauth2.googleapis.com/token","scope":["https://www.googleapis.com/auth/cloud-platform"],"entries_uri":"https://secretmanager.googleapis.com/v1","client_email":"email@apisix.iam.gserviceaccount.com","private_key":"private_key","project_id":"apisix-project"},"create_time":1726070161,"update_time":1726070161},"key":"/apisix/secrets/gcp/test4"}

应答参数

当前的响应是从 etcd 返回的。