diff --git a/docs/en/latest/FAQ.md b/docs/en/latest/FAQ.md index 8a669b0f9c2d..a19b5e96fbfe 100644 --- a/docs/en/latest/FAQ.md +++ b/docs/en/latest/FAQ.md @@ -756,15 +756,15 @@ deployment: password: etcd_password # password for etcd ``` -For other ETCD configurations, such as expiration times, retries, and so on, you can refer to the `ETCD` section in the `conf/config-default.yaml` file. +For other ETCD configurations, such as expiration times, retries, and so on, you can refer to the `etcd` section in the sample configuration `conf/config.yaml.example` file. -## What is the difference between SSLs and tls.client_cert in upstream configurations, and ssl_trusted_certificate in config-default.yaml? +## What is the difference between SSLs, `tls.client_cert` in upstream configurations, and `ssl_trusted_certificate` in `config.yaml`? The `ssls` is managed through the `/apisix/admin/ssls` API. It's used for managing TLS certificates. These certificates may be used during TLS handshake (between Apache APISIX and its clients). Apache APISIX uses Server Name Indication (SNI) to differentiate between certificates of different domains. The `tls.client_cert`, `tls.client_key`, and `tls.client_cert_id` in upstream are used for mTLS communication with the upstream. -The `ssl_trusted_certificate` in config-default.yaml configures a trusted CA certificate. It is used for verifying some certificates signed by private authorities within APISIX, to avoid APISIX rejects the certificate. Note that it is not used to trust the certificates of APISIX upstream, because APISIX does not verify the legality of the upstream certificates. Therefore, even if the upstream uses an invalid TLS certificate, it can still be accessed without configuring a root certificate. +The `ssl_trusted_certificate` in `config.yaml` configures a trusted CA certificate. It is used for verifying some certificates signed by private authorities within APISIX, to avoid APISIX rejects the certificate. Note that it is not used to trust the certificates of APISIX upstream, because APISIX does not verify the legality of the upstream certificates. Therefore, even if the upstream uses an invalid TLS certificate, it can still be accessed without configuring a root certificate. ## Where can I find more answers? diff --git a/docs/en/latest/benchmark.md b/docs/en/latest/benchmark.md index bc86cf97d77d..8ddddc6bad05 100644 --- a/docs/en/latest/benchmark.md +++ b/docs/en/latest/benchmark.md @@ -140,7 +140,7 @@ For more reference on how to run the benchmark test, you can see this [PR](https :::tip -If you want to run the benchmark with a large number of connections, You may have to update the **keepalive** config in the [conf/config-default.yaml](https://github.com/apache/apisix/blob/master/conf/config-default.yaml#L242). Connections exceeding this number will become short connections. You can run the following command to test the benchmark with a large number of connections: +If you want to run the benchmark with a large number of connections, You may have to update the [**keepalive**](https://github.com/apache/apisix/blob/master/conf/config.yaml.example#L241) config by adding the configuration to [`config.yaml`](https://github.com/apache/apisix/blob/master/conf/config.yaml) and reload APISIX. Connections exceeding this number will become short connections. You can run the following command to test the benchmark with a large number of connections: ```bash wrk -t200 -c5000 -d30s http://127.0.0.1:9080/hello diff --git a/docs/en/latest/customize-nginx-configuration.md b/docs/en/latest/customize-nginx-configuration.md index e5098b043e55..9a6baa512d0d 100644 --- a/docs/en/latest/customize-nginx-configuration.md +++ b/docs/en/latest/customize-nginx-configuration.md @@ -21,11 +21,11 @@ title: Customize Nginx configuration # --> -The Nginx configuration used by APISIX is generated via the template file `apisix/cli/ngx_tpl.lua` and the options from `conf/config-default.yaml` / `conf/config.yaml`. +The Nginx configuration used by APISIX is generated via the template file `apisix/cli/ngx_tpl.lua` and the parameters in `apisix/cli/config.lua` and `conf/config.yaml`. You can take a look at the generated Nginx configuration in `conf/nginx.conf` after running `./bin/apisix start`. -If you want to customize the Nginx configuration, please read through the `nginx_config` in `conf/config-default.yaml`. You can override the default value in the `conf/config.yaml`. For instance, you can inject some snippets in the `conf/nginx.conf` via configuring the `xxx_snippet` entries: +If you want to customize the Nginx configuration, please read through the `nginx_config` in `conf/config.default.example`. You can override the default value in the `conf/config.yaml`. For instance, you can inject some snippets in the `conf/nginx.conf` via configuring the `xxx_snippet` entries: ```yaml ... diff --git a/docs/en/latest/install-dependencies.md b/docs/en/latest/install-dependencies.md index 83545f2cfdc6..049c1a69dee7 100644 --- a/docs/en/latest/install-dependencies.md +++ b/docs/en/latest/install-dependencies.md @@ -25,7 +25,7 @@ title: Install Dependencies - Since v2.0 Apache APISIX would not support the v2 protocol storage to etcd anymore, and the minimum etcd version supported is v3.4.0. What's more, etcd v3 uses gRPC as the messaging protocol, while Apache APISIX uses HTTP(S) to communicate with etcd cluster, so be sure the [etcd gRPC gateway](https://etcd.io/docs/v3.4.0/dev-guide/api_grpc_gateway/) is enabled. -- Now by default Apache APISIX uses HTTP protocol to talk with etcd cluster, which is insecure. Please configure certificate and corresponding private key for your etcd cluster, and use "https" scheme explicitly in the etcd endpoints list in your Apache APISIX configuration, if you want to keep the data secure and integral. See the etcd section in `conf/config-default.yaml` for more details. +- Now by default Apache APISIX uses HTTP protocol to talk with etcd cluster, which is insecure. Please configure certificate and corresponding private key for your etcd cluster, and use "https" scheme explicitly in the etcd endpoints list in your Apache APISIX configuration, if you want to keep the data secure and integral. See the etcd section in `conf/config.yaml.example` for more details. - If it is OpenResty 1.19, APISIX will use OpenResty's built-in LuaJIT to run `bin/apisix`; otherwise it will use Lua 5.1. If you encounter `luajit: lj_asm_x86.h:2819: asm_loop_ fixup: Assertion '((intptr_t)target & 15) == 0' failed`, this is a problem with the low version of OpenResty's built-in LuaJIT under certain compilation conditions. diff --git a/docs/en/latest/installation-guide.md b/docs/en/latest/installation-guide.md index 779f65b33b01..b3cc514864a1 100644 --- a/docs/en/latest/installation-guide.md +++ b/docs/en/latest/installation-guide.md @@ -271,7 +271,7 @@ You can configure your APISIX deployment in two ways: apisix start -c ``` -APISIX will use the configurations added in this configuration file and will fall back to the default configuration if anything is not configured. +APISIX will use the configurations added in this configuration file and will fall back to the default configuration if anything is not configured. The default configurations can be found in `apisix/cli/config.lua` and should not be modified. For example, to configure the default listening port to be `8000` without changing other configurations, your configuration file could look like this: @@ -297,12 +297,6 @@ deployment: :::warning -APISIX's default configuration can be found in `conf/config-default.yaml` file and it should not be modified. It is bound to the source code and the configuration should only be changed by the methods mentioned above. - -::: - -:::warning - The `conf/nginx.conf` file is automatically generated and should not be modified. ::: diff --git a/docs/en/latest/plugin-develop.md b/docs/en/latest/plugin-develop.md index 406dce0e6e74..ff9cfae79a0f 100644 --- a/docs/en/latest/plugin-develop.md +++ b/docs/en/latest/plugin-develop.md @@ -117,36 +117,36 @@ local _M = { Note: The priority of the new plugin cannot be same to any existing ones, you can use the `/v1/schema` method of [control API](./control-api.md#get-v1schema) to view the priority of all plugins. In addition, plugins with higher priority value will be executed first in a given phase (see the definition of `phase` in [choose-phase-to-run](#choose-phase-to-run)). For example, the priority of example-plugin is 0 and the priority of ip-restriction is 3000. Therefore, the ip-restriction plugin will be executed first, then the example-plugin plugin. It's recommended to use priority 1 ~ 99 for your plugin unless you want it to run before some builtin plugins. -In the "__conf/config-default.yaml__" configuration file, the enabled plugins (all specified by plugin name) are listed. +By default, most APISIX plugins are [enabled](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua): -```yaml -plugins: # plugin list - - limit-req - - limit-count - - limit-conn - - key-auth - - prometheus - - node-status - - jwt-auth - - zipkin - - ip-restriction - - grpc-transcode - - serverless-pre-function - - serverless-post-function - - openid-connect - - proxy-rewrite - - redirect +```lua title="apisix/cli/config.lua" +local _M = { + ... + plugins = { + "real-ip", + "ai", + "client-control", + "proxy-control", + "request-id", + "zipkin", + "ext-plugin-pre-req", + "fault-injection", + "mocking", + "serverless-pre-function", + ... + }, ... +} ``` Note: the order of the plugins is not related to the order of execution. -To enable your plugin, copy this plugin list into `conf/config.yaml`, and add your plugin name. For instance: +To enable your custom plugin, add the list of plugins into `conf/config.yaml` and append your plugin name. For instance: ```yaml -plugins: # copied from config-default.yaml - ... - - your-plugin +plugins: # see `conf/config.yaml.example` for an example + - ... # add existing plugins + - your-plugin # add your custom plugin ``` If your plugin has a new code directory of its own, and you need to redistribute it with the APISIX source code, you will need to modify the `Makefile` to create directory, such as: diff --git a/docs/en/latest/plugins/aws-lambda.md b/docs/en/latest/plugins/aws-lambda.md index 2cfca463749b..f9344859d43c 100644 --- a/docs/en/latest/plugins/aws-lambda.md +++ b/docs/en/latest/plugins/aws-lambda.md @@ -104,7 +104,7 @@ Server: APISIX/2.10.2 "Hello, APISIX!" ``` -Another example of a request where the client communicates with APISIX via HTTP/2 is shown below (make sure you have configured `enable_http2: true` for a in your default configuration file (`config-default.yaml`). You can do this by uncommenting the port `9081` from the field `apisix.node_listen`): +Another example of a request where the client communicates with APISIX via HTTP/2 is shown below. Before proceeding, make sure you have configured `enable_http2: true` in your configuration file `config.yaml` for port `9081` and reloaded APISIX. See [`config.yaml.example`](https://github.com/apache/apisix/blob/master/conf/config.yaml.example) for the example configuration. ```shell curl -i -XGET --http2 --http2-prior-knowledge localhost:9081/aws\?name=APISIX diff --git a/docs/en/latest/plugins/azure-functions.md b/docs/en/latest/plugins/azure-functions.md index f68b6f3b497f..07663eb07e37 100644 --- a/docs/en/latest/plugins/azure-functions.md +++ b/docs/en/latest/plugins/azure-functions.md @@ -119,7 +119,7 @@ Server: APISIX/2.10.2 Hello, APISIX ``` -Another example of a request where the client communicates with APISIX via HTTP/2 is shown below (make sure you have configured `enable_http2: true` in your default configuration file (`config-default.yaml`). You can do this by uncommenting the port `9081` from the field `apisix.node_listen`): +Another example of a request where the client communicates with APISIX via HTTP/2 is shown below. Before proceeding, make sure you have configured `enable_http2: true` in your configuration file `config.yaml` for port `9081` and reloaded APISIX. See [`config.yaml.example`](https://github.com/apache/apisix/blob/master/conf/config.yaml.example) for the example configuration. ```shell curl -i -XGET --http2 --http2-prior-knowledge http://localhost:9081/azure\?name=APISIX diff --git a/docs/en/latest/plugins/inspect.md b/docs/en/latest/plugins/inspect.md index cbd876ceb687..9f5b3fe0843f 100644 --- a/docs/en/latest/plugins/inspect.md +++ b/docs/en/latest/plugins/inspect.md @@ -87,16 +87,23 @@ The `info` is a hash table which contains below keys: ## Enable Plugin -Plugin is enabled by default (`conf/config-default.yaml`): - -```yaml title="conf/config-default.yaml" -plugins: - - inspect - -plugin_attr: - inspect: - delay: 3 - hooks_file: "/usr/local/apisix/plugin_inspect_hooks.lua" +Plugin is enabled by default: + +```yaml title="apisix/cli/config.lua" +local _M = { + plugins = { + "inspect", + ... + }, + plugin_attr = { + inspect = { + delay = 3, + hooks_file = "/usr/local/apisix/plugin_inspect_hooks.lua" + }, + ... + }, + ... +} ``` ## Example usage diff --git a/docs/en/latest/pubsub.md b/docs/en/latest/pubsub.md index 62112fb4596c..ec756229e71d 100644 --- a/docs/en/latest/pubsub.md +++ b/docs/en/latest/pubsub.md @@ -106,9 +106,13 @@ Add the required fields to the plugin schema definition and write them to the co The `kafka-proxy` plugin [kafka-proxy.lua](https://github.com/apache/apisix/blob/master/apisix/plugins/kafka-proxy.lua). -Add this plugin to the list of plugins in the APISIX configuration file. +Add this plugin to [the existing list of plugins](https://github.com/apache/apisix/blob/master/apisix/cli/config.yaml.example) in the APISIX configuration file [`config.yaml`](https://github.com/apache/apisix/blob/master/conf/config.yaml). For instance: -The plugins list [config-default.yaml](https://github.com/apache/apisix/blob/master/conf/config-default.yaml). +```yaml title="conf/config.yaml" +plugins: # see `conf/config.yaml.example` for an example + - ... # add existing plugins + - kafka-proxy +``` #### Results diff --git a/docs/en/latest/terminology/plugin.md b/docs/en/latest/terminology/plugin.md index 66fff7afdd3c..0312c6622900 100644 --- a/docs/en/latest/terminology/plugin.md +++ b/docs/en/latest/terminology/plugin.md @@ -38,22 +38,51 @@ If existing APISIX Plugins do not meet your needs, you can also write your own p ## Plugins installation -APISIX comes with a default configuration file called `config-default.yaml` and a user-defined configuration file called `config.yaml`. These files are located in the `conf` directory. If the same key (e.g. `plugins`) exists in both files, the configuration values for the key in `config.yaml` will overwrite those in `config-default.yaml`. +By default, most APISIX plugins are [installed](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua): + +```lua title="apisix/cli/config.lua" +local _M = { + ... + plugins = { + "real-ip", + "ai", + "client-control", + "proxy-control", + "request-id", + "zipkin", + "ext-plugin-pre-req", + "fault-injection", + "mocking", + "serverless-pre-function", + ... + }, + ... +} +``` -The `plugins` block is where you can declare the Plugins loaded to your APISIX instance: +If you would like to make adjustments to plugins installation, add the customized `plugins` configuration to `config.yaml`. For example: ```yaml plugins: - - real-ip # loaded + - real-ip # installed + - ai + - real-ip - ai - client-control - proxy-control - request-id - zipkin - # - skywalking # not loaded -... + - ext-plugin-pre-req + - fault-injection + # - mocking # not install + - serverless-pre-function + ... # other plugins ``` +See `config.yaml.example`(https://github.com/apache/apisix/blob/master/conf/config.yaml.example) for a complete configuration reference. + +You should reload APISIX for configuration changes to take effect. + ## Plugins execution lifecycle An installed plugin is first initialized. The configuration of the plugin is then checked against the defined [JSON Schema](https://json-schema.org) to make sure the plugins configuration schema is correct. diff --git a/docs/zh/latest/FAQ.md b/docs/zh/latest/FAQ.md index 181588ba0de9..d605d091b9c1 100644 --- a/docs/zh/latest/FAQ.md +++ b/docs/zh/latest/FAQ.md @@ -760,15 +760,15 @@ deployment: password: etcd_password # password for etcd ``` -关于 ETCD 的其他配置，比如过期时间、重试次数等等，你可以参考 `conf/config-default.yaml` 文件中的 `ETCD` 部分。 +关于 ETCD 的其他配置，比如过期时间、重试次数等等，你可以参考 `conf/config.yaml.example` 文件中的 `etcd` 部分。 -## SSLs 对象与 `upstream` 对象中的 `tls.client_cert` 以及 `config-default.yaml` 中的 `ssl_trusted_certificate` 区别是什么？ +## SSLs 对象与 `upstream` 对象中的 `tls.client_cert` 以及 `config.yaml` 中的 `ssl_trusted_certificate` 区别是什么？ Admin API 中 `/apisix/admin/ssls` 用于管理 SSL 对象，如果 APISIX 需要接收来自外网的 HTTPS 请求，那就需要用到存放在这里的证书完成握手。SSL 对象中支持配置多个证书，不同域名的证书 APISIX 将使用 Server Name Indication (SNI) 进行区分。 Upstream 对象中的 `tls.client_cert`、`tls.client_key` 与 `tls.client_cert_id` 用于存放客户端的证书，适用于需要与上游进行 [mTLS 通信](https://apisix.apache.org/zh/docs/apisix/tutorials/client-to-apisix-mtls/)的情况。 -`config-default.yaml` 中的 `ssl_trusted_certificate` 用于配置一个受信任的根证书。它仅用于在 APISIX 内部访问某些具有自签名证书的服务时，避免提示拒绝对方的 SSL 证书。注意：它不用于信任 APISIX 上游的证书，因为 APISIX 不会验证上游证书的合法性。因此，即使上游使用了无效的 TLS 证书，APISIX 仍然可以与其通信，而无需配置根证书。 +`config.yaml` 中的 `ssl_trusted_certificate` 用于配置一个受信任的根证书。它仅用于在 APISIX 内部访问某些具有自签名证书的服务时，避免提示拒绝对方的 SSL 证书。注意：它不用于信任 APISIX 上游的证书，因为 APISIX 不会验证上游证书的合法性。因此，即使上游使用了无效的 TLS 证书，APISIX 仍然可以与其通信，而无需配置根证书。 ## 如果在使用 APISIX 过程中遇到问题，我可以在哪里寻求更多帮助？ diff --git a/docs/zh/latest/benchmark.md b/docs/zh/latest/benchmark.md index 874fd9c7ce13..2ceda912d7d6 100644 --- a/docs/zh/latest/benchmark.md +++ b/docs/zh/latest/benchmark.md @@ -139,7 +139,7 @@ wrk -d 60 --latency http://127.0.0.1:9080/hello :::tip -如果你想测试大量连接的基准测试，你可能需要更新 [`./conf/config-default.yaml`](https://github.com/apache/apisix/blob/master/conf/config-default.yaml#L242) 中的 **keepalive** 配置项，否则超过配置数量的连接将成为短连接。你可以使用以下命令运行大量连接的基准测试： +如果您想使用大量连接运行基准测试，您可能需要更新 [**keepalive**](https://github.com/apache/apisix/blob/master/conf/config.yaml.example#L241) 配置，将配置添加到 [`config.yaml`](https://github.com/apache/apisix/blob/master/conf/config.yaml) 并重新加载 APISIX。否则超过配置数量的连接将成为短连接。你可以使用以下命令运行大量连接的基准测试： ```bash wrk -t200 -c5000 -d30s http://127.0.0.1:9080/hello diff --git a/docs/zh/latest/customize-nginx-configuration.md b/docs/zh/latest/customize-nginx-configuration.md index 78880d262dbc..0817f63fccd4 100644 --- a/docs/zh/latest/customize-nginx-configuration.md +++ b/docs/zh/latest/customize-nginx-configuration.md @@ -21,11 +21,11 @@ title: 自定义 Nginx 配置 # --> -APISIX 会通过 `apisix/cli/ngx_tpl.lua` 这个模板和 `conf/config-default.yaml` 加 `conf/config.yaml` 的配置生成 Nginx 配置文件。 +APISIX 使用的 Nginx 配置是通过模板文件 `apisix/cli/ngx_tpl.lua` 以及 `apisix/cli/config.lua` 和`conf/config.yaml` 中的参数生成的。 在执行完 `./bin/apisix start`，你可以在 `conf/nginx.conf` 看到生成的 Nginx 配置文件。 -在自定义 Nginx 配置文件之前，烦请仔细阅读 `conf/config-default.yaml`。你可以在 `conf/config.yaml` 里面覆盖掉默认值。举个例子，你可以通过 `xxx_snippet` 之类的配置，在 `conf/nginx.conf` 里面注入你的自定义配置： +如果你需要自定义 Nginx 配置，请阅读 `conf/config.default.example` 中的 `nginx_config`。你可以在 `conf/config.yaml` 中覆盖默认值。例如，你可以在 `conf/nginx.conf` 中通过配置 `xxx_snippet` 条目注入一些代码片段： ```yaml ... diff --git a/docs/zh/latest/install-dependencies.md b/docs/zh/latest/install-dependencies.md index c7d36f5112d7..c545c8cc93a9 100644 --- a/docs/zh/latest/install-dependencies.md +++ b/docs/zh/latest/install-dependencies.md @@ -25,7 +25,7 @@ title: 安装依赖 - Apache APISIX 从 v2.0 开始不再支持 `v2` 版本的 etcd，并且 etcd 最低支持版本为 v3.4.0，因此请使用 etcd 3.4.0+。更重要的是，因为 etcd v3 使用 gRPC 作为消息传递协议，而 Apache APISIX 使用 HTTP(S) 与 etcd 集群通信，因此请确保启用 [etcd gRPC gateway](https://etcd.io/docs/v3.4.0/dev-guide/api_grpc_gateway/) 功能。 -- 目前 Apache APISIX 默认使用 HTTP 协议与 etcd 集群通信，这并不安全，如果希望保障数据的安全性和完整性。请为您的 etcd 集群配置证书及对应私钥，并在您的 Apache APISIX etcd endpoints 配置列表中明确使用 `https` 协议前缀。请查阅 `conf/config-default.yaml` 中 etcd 一节相关的配置来了解更多细节。 +- 目前 Apache APISIX 默认使用 HTTP 协议与 etcd 集群通信，这并不安全，如果希望保障数据的安全性和完整性。请为您的 etcd 集群配置证书及对应私钥，并在您的 Apache APISIX etcd endpoints 配置列表中明确使用 `https` 协议前缀。请查阅 `conf/config.yaml.example` 中 `etcd` 一节相关的配置来了解更多细节。 - 如果是 OpenResty 1.19，APISIX 会使用 OpenResty 内置的 LuaJIT 来运行 `bin/apisix`；否则会使用 Lua 5.1。如果运行过程中遇到 `luajit: lj_asm_x86.h:2819: asm_loop_fixup: Assertion '((intptr_t)target & 15) == 0' failed`，这是低版本 OpenResty 内置的 LuaJIT 在特定编译条件下的问题。 diff --git a/docs/zh/latest/installation-guide.md b/docs/zh/latest/installation-guide.md index df06485fe802..59cdf20405ef 100644 --- a/docs/zh/latest/installation-guide.md +++ b/docs/zh/latest/installation-guide.md @@ -265,7 +265,7 @@ brew services start etcd ### 配置 APISIX -通过修改本地 `./conf/config.yaml` 文件，或者在启动 APISIX 时使用 `-c` 或 `--config` 添加文件路径参数 `apisix start -c `，完成对 APISIX 服务本身的基本配置。 +通过修改本地 `./conf/config.yaml` 文件，或者在启动 APISIX 时使用 `-c` 或 `--config` 添加文件路径参数 `apisix start -c `，完成对 APISIX 服务本身的基本配置。默认配置不应修改，可以在 `apisix/cli/config.lua` 中找到。 比如将 APISIX 默认监听端口修改为 8000，其他配置保持默认，在 `./conf/config.yaml` 中只需这样配置： @@ -291,11 +291,6 @@ deployment: :::warning -APISIX 的默认配置可以在 `./conf/config-default.yaml` 文件中看到，该文件与 APISIX 源码强绑定，请不要手动修改 `./conf/config-default.yaml` 文件。如果需要自定义任何配置，都应在 `./conf/config.yaml` 文件中完成。 -::: - -:::warning - 请不要手动修改 APISIX 安装目录下的 `./conf/nginx.conf` 文件。当 APISIX 启动时，会根据 `config.yaml` 的配置自动生成新的 `nginx.conf` 并自动启动服务。 ::: diff --git a/docs/zh/latest/plugin-develop.md b/docs/zh/latest/plugin-develop.md index c425a8d2cc97..c893088f454a 100644 --- a/docs/zh/latest/plugin-develop.md +++ b/docs/zh/latest/plugin-develop.md @@ -109,30 +109,38 @@ local _M = { 注：新插件的优先级（priority 属性）不能与现有插件的优先级相同，您可以使用 [control API](./control-api.md#get-v1schema) 的 `/v1/schema` 方法查看所有插件的优先级。另外，同一个阶段里面，优先级 ( priority ) 值大的插件，会优先执行，比如 `example-plugin` 的优先级是 0，`ip-restriction` 的优先级是 3000，所以在每个阶段，会先执行 `ip-restriction` 插件，再去执行 `example-plugin` 插件。这里的“阶段”的定义，参见后续的 [确定执行阶段](#确定执行阶段) 这一节。对于你的插件，建议采用 1 到 99 之间的优先级。 -在 __conf/config-default.yaml__ 配置文件中，列出了启用的插件（都是以插件名指定的）： +默认情况下，大多数 APISIX 插件都是[启用](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua)的状态： -```yaml -plugins: # plugin list - - limit-req - - limit-count - - limit-conn - - key-auth - - prometheus - - node-status - - jwt-auth - - zipkin - - ip-restriction - - grpc-transcode - - serverless-pre-function - - serverless-post-function - - openid-connect - - proxy-rewrite - - redirect +```lua title="apisix/cli/config.lua" +local _M = { ... + plugins = { + "real-ip", + "ai", + "client-control", + "proxy-control", + "request-id", + "zipkin", + "ext-plugin-pre-req", + "fault-injection", + "mocking", + "serverless-pre-function", + ... + }, + ... +} ``` 注：先后顺序与执行顺序无关。 +要启用您的自定义插件，请将插件列表添加到 `conf/config.yaml` 并附加您的插件名称。例如： + +```yaml +plugins: # 请参阅 `conf/config.yaml.example` 示例 + - ... # 添加现有插件 + - your-plugin # 添加您的自定义插件 +``` + 特别需要注意的是，如果你的插件有新建自己的代码目录，那么就需要修改 Makefile 文件，新增创建文件夹的操作，比如： ``` diff --git a/docs/zh/latest/terminology/plugin.md b/docs/zh/latest/terminology/plugin.md index b8a224233a97..ba42e814cd17 100644 --- a/docs/zh/latest/terminology/plugin.md +++ b/docs/zh/latest/terminology/plugin.md @@ -37,22 +37,51 @@ APISIX 提供了许多现有的插件，可以定制和编排以满足你的需 ## 插件安装 -APISIX 附带一个`config-default.yaml`的默认配置文件和一个 `config.yaml` 的用户自定义配置文件。这些文件位于`conf`目录中。如果两个文件中都存在相同的键 (例如`plugins`)，则`config.yaml`文件中该键的配置值将覆盖`config-default.yaml`文件中的配置值。 +默认情况下，大多数 APISIX 插件都已[安装](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua)： + +```lua title="apisix/cli/config.lua" +local _M = { + ... + plugins = { + "real-ip", + "ai", + "client-control", + "proxy-control", + "request-id", + "zipkin", + "ext-plugin-pre-req", + "fault-injection", + "mocking", + "serverless-pre-function", + ... + }, + ... +} +``` -例如： +如果您想调整插件安装，请将自定义的 `plugins` 配置添加到 `config.yaml` 中。例如： ```yaml plugins: - - real-ip # 安装 + - real-ip # 安装 + - ai + - real-ip - ai - client-control - proxy-control - request-id - zipkin - # - skywalking # 未安装 -... + - ext-plugin-pre-req + - fault-injection + # - mocking # 不安装 + - serverless-pre-function + ... # 其它插件 ``` +完整配置参考请参见 [`config.yaml.example`](https://github.com/apache/apisix/blob/master/conf/config.yaml.example)。 + +重新加载 APISIX 以使配置更改生效。 + ## 插件执行生命周期 安装的插件首先会被初始化。然后会检查插件的配置，以确保插件配置遵循定义的[JSON Schema](https://json-schema.org)。