2021-03-10 15:14:41 +08:00
|
|
|
|
---
|
|
|
|
|
|
title: Plugin
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
<!--
|
|
|
|
|
|
#
|
|
|
|
|
|
# Licensed to the Apache Software Foundation (ASF) under one or more
|
|
|
|
|
|
# contributor license agreements. See the NOTICE file distributed with
|
|
|
|
|
|
# this work for additional information regarding copyright ownership.
|
|
|
|
|
|
# The ASF licenses this file to You under the Apache License, Version 2.0
|
|
|
|
|
|
# (the "License"); you may not use this file except in compliance with
|
|
|
|
|
|
# the License. You may obtain a copy of the License at
|
|
|
|
|
|
#
|
|
|
|
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
|
#
|
|
|
|
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
|
|
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
|
|
# See the License for the specific language governing permissions and
|
|
|
|
|
|
# limitations under the License.
|
|
|
|
|
|
#
|
|
|
|
|
|
-->
|
|
|
|
|
|
|
|
|
|
|
|
`Plugin` 表示将在 `HTTP` 请求/响应生命周期期间执行的插件配置。
|
|
|
|
|
|
|
|
|
|
|
|
`Plugin` 配置可直接绑定在 `Route` 上，也可以被绑定在 `Service` 或 `Consumer`上。而对于同一
|
|
|
|
|
|
个插件的配置，只能有一份是有效的，配置选择优先级总是 `Consumer` > `Route` > `Service`。
|
|
|
|
|
|
|
|
|
|
|
|
在 `conf/config.yaml` 中，可以声明本地 APISIX 节点都支持哪些插件。这是个白名单机制，不在该
|
|
|
|
|
|
白名单的插件配置，都将会被自动忽略。这个特性可用于临时关闭或打开特定插件，应对突发情况非常有效。
|
|
|
|
|
|
如果你想在现有插件的基础上新增插件，注意需要拷贝 `conf/config-default.yaml` 的插件节点内容到 `conf/config.yaml` 的插件节点中。
|
|
|
|
|
|
|
|
|
|
|
|
插件的配置可以被直接绑定在指定 Route 中，也可以被绑定在 Service 中，不过 Route 中的插件配置
|
|
|
|
|
|
优先级更高。
|
|
|
|
|
|
|
|
|
|
|
|
一个插件在一次请求中只会执行一次，即使被同时绑定到多个不同对象中（比如 Route 或 Service）。
|
|
|
|
|
|
插件运行先后顺序是根据插件自身的优先级来决定的，例如：
|
|
|
|
|
|
|
|
|
|
|
|
```lua
|
|
|
|
|
|
local _M = {
|
|
|
|
|
|
version = 0.1,
|
|
|
|
|
|
priority = 0, -- 这个插件的优先级为 0
|
|
|
|
|
|
name = plugin_name,
|
|
|
|
|
|
schema = schema,
|
|
|
|
|
|
metadata_schema = metadata_schema,
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
插件配置作为 Route 或 Service 的一部分提交的，放到 `plugins` 下。它内部是使用插件
|
|
|
|
|
|
名字作为哈希的 key 来保存不同插件的配置项。
|
|
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
|
{
|
|
|
|
|
|
...
|
|
|
|
|
|
"plugins": {
|
|
|
|
|
|
"limit-count": {
|
|
|
|
|
|
"count": 2,
|
|
|
|
|
|
"time_window": 60,
|
|
|
|
|
|
"rejected_code": 503,
|
|
|
|
|
|
"key": "remote_addr"
|
|
|
|
|
|
},
|
|
|
|
|
|
"prometheus": {}
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
并不是所有插件都有具体配置项，比如 `prometheus` 下是没有任何具体配置项，这时候用一个空的对象
|
|
|
|
|
|
标识即可。
|
|
|
|
|
|
|
|
|
|
|
|
如果一个请求因为某个插件而被拒绝，会有类似这样的 warn 日志：`ip-restriction exits with http status code 403`。
|
2021-06-16 19:04:30 +08:00
|
|
|
|
|
|
|
|
|
|
## 热加载
|
|
|
|
|
|
|
|
|
|
|
|
APISIX 的插件是热加载的，不管你是新增、删除还是修改插件，都不需要重启服务。
|
|
|
|
|
|
|
|
|
|
|
|
只需要通过 admin API 发送一个 HTTP 请求即可：
|
|
|
|
|
|
|
|
|
|
|
|
```shell
|
|
|
|
|
|
curl http://127.0.0.1:9080/apisix/admin/plugins/reload -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
注意：如果你已经在路由规则里配置了某个插件（比如在 `route` 的 `plugins` 字段里面添加了它），然后
|
|
|
|
|
|
禁用了该插件，在执行路由规则的时候会跳过这个插件。
|
|
|
|
|
|
|
|
|
|
|
|
## stand-alone 模式下的热加载
|
|
|
|
|
|
|
|
|
|
|
|
参考 [stand alone 模式](../stand-alone.md) 文档里关于配置插件的内容。
|
