diff --git a/README.md b/README.md index 52d10c74..e18e9cf0 100644 --- a/README.md +++ b/README.md @@ -334,7 +334,7 @@ CNCF API Gateway Landscape. ## Logos -- [Apache APISIX logo(PNG)](logos/apache-apisix.png) +- [Apache APISIX logo(PNG)](https://github.com/apache/apisix/tree/master/logos/apache-apisix.png) - [Apache APISIX logo source](https://apache.org/logos/#apisix) ## Acknowledgments @@ -343,4 +343,4 @@ Inspired by Kong and Orange. ## License -[Apache 2.0 License](LICENSE) +[Apache 2.0 License](https://github.com/apache/apisix/tree/master/LICENSE) diff --git a/docs/en/latest/architecture-design.md b/docs/en/latest/architecture-design.md index 8971f76a..99952972 100644 --- a/docs/en/latest/architecture-design.md +++ b/docs/en/latest/architecture-design.md @@ -91,7 +91,7 @@ The route mainly consists of three parts: matching rules (e.g uri, host, remote_ The following image shows an example of some Route rules. When some attribute values are the same, the figure is identified by the same color. - + We configure all the parameters directly in the Route, it's easy to set up, and each Route has a relatively high degree of freedom. But when our Route has more repetitive configurations (such as enabling the same plugin configuration or upstream information), once we need update these same properties, we have to traverse all the Routes and modify them, so it's adding a lot of complexity of management and maintenance. diff --git a/docs/en/latest/install-dependencies.md b/docs/en/latest/install-dependencies.md index 41917cbc..fc294a86 100644 --- a/docs/en/latest/install-dependencies.md +++ b/docs/en/latest/install-dependencies.md @@ -21,7 +21,6 @@ title: Install Dependencies # --> -- [Install Dependencies](#install-dependencies) - [Note](#note) - [CentOS 7](#centos-7) - [Fedora 31 & 32](#fedora-31--32) @@ -35,11 +34,11 @@ title: Install Dependencies - 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. -- If you want use Tengine instead of OpenResty, please take a look at this installation step script [Install Tengine at Ubuntu](../.travis/linux_tengine_runner.sh). +- If you want use Tengine instead of OpenResty, please take a look at this installation step script [Install Tengine at Ubuntu](https://github.com/apache/apisix/blob/master/.travis/linux_tengine_runner.sh). - 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. -- On some platforms, installing LuaRocks via the package manager will cause Lua to be upgraded to Lua 5.3, so we recommend installing LuaRocks via source code. if you install OpenResty and its OpenSSL develop library (openresty-openssl111-devel for rpm and openresty-openssl111-dev for deb) via the official repository, then [we provide a script for automatic installation](../utils/linux-install-luarocks.sh). If you compile OpenResty yourself, you can refer to the above script and change the path in it. If you don't specify the OpenSSL library path when you compile, you don't need to configure the OpenSSL variables in LuaRocks, because the system's OpenSSL is used by default. If the OpenSSL library is specified at compile time, then you need to ensure that LuaRocks' OpenSSL configuration is consistent with OpenResty's. +- On some platforms, installing LuaRocks via the package manager will cause Lua to be upgraded to Lua 5.3, so we recommend installing LuaRocks via source code. if you install OpenResty and its OpenSSL develop library (openresty-openssl111-devel for rpm and openresty-openssl111-dev for deb) via the official repository, then [we provide a script for automatic installation](https://github.com/apache/apisix/blob/master/utils/linux-install-luarocks.sh). If you compile OpenResty yourself, you can refer to the above script and change the path in it. If you don't specify the OpenSSL library path when you compile, you don't need to configure the OpenSSL variables in LuaRocks, because the system's OpenSSL is used by default. If the OpenSSL library is specified at compile time, then you need to ensure that LuaRocks' OpenSSL configuration is consistent with OpenResty's. - WARNING: If you are using OpenResty which is older than `1.17.8`, please installing openresty-openss-devel instead of openresty-openssl111-devel. diff --git a/docs/en/latest/plugin-develop.md b/docs/en/latest/plugin-develop.md index 1c8992df..d7510b41 100644 --- a/docs/en/latest/plugin-develop.md +++ b/docs/en/latest/plugin-develop.md @@ -23,15 +23,19 @@ title: Plugin Develop ## table of contents -- [**where to put your plugins**](#where-to-put-your-plugins) -- [**check dependencies**](#check-dependencies) -- [**name and config**](#name-and-config) -- [**schema and check**](#schema-and-check) -- [**choose phase to run**](#choose-phase-to-run) -- [**implement the logic**](#implement-the-logic) -- [**write test case**](#write-test-case) -- [**register public API**](#register-public-api) -- [**register control API**](#register-control-api) +- [table of contents](#table-of-contents) +- [where to put your plugins](#where-to-put-your-plugins) +- [check dependencies](#check-dependencies) +- [name and config](#name-and-config) +- [schema and check](#schema-and-check) +- [choose phase to run](#choose-phase-to-run) +- [implement the logic](#implement-the-logic) + - [conf parameter](#conf-parameter) + - [ctx parameter](#ctx-parameter) +- [write test case](#write-test-case) + - [Attach the test-nginx execution process:](#attach-the-test-nginx-execution-process) + - [Register public API](#register-public-api) + - [Register control API](#register-control-api) ## where to put your plugins @@ -65,7 +69,7 @@ Now using `require "apisix.plugins.3rd-party"` will load your plugin, just like ## check dependencies if you have dependencies on external libraries, check the dependent items. if your plugin needs to use shared memory, it - needs to declare in **apisix/cli/ngx_tpl.lua**, for example : +needs to declare in **apisix/cli/ngx_tpl.lua**, for example : ```nginx lua_shared_dict plugin-limit-req 10m; @@ -82,18 +86,18 @@ if you have dependencies on external libraries, check the dependent items. if yo ``` The plugin itself provides the init method. It is convenient for plugins to perform some initialization after - the plugin is loaded. +the plugin is loaded. Note : if the dependency of some plugin needs to be initialized when Nginx start, you may need to add logic to the initialization - method "http_init" in the file __apisix/init.lua__, and you may need to add some processing on generated part of Nginx - configuration file in __apisix/cli/ngx_tpl.lua__ file. But it is easy to have an impact on the overall situation according to the - existing plugin mechanism, we do not recommend this unless you have a complete grasp of the code. +method "http_init" in the file __apisix/init.lua__, and you may need to add some processing on generated part of Nginx +configuration file in __apisix/cli/ngx_tpl.lua__ file. But it is easy to have an impact on the overall situation according to the +existing plugin mechanism, we do not recommend this unless you have a complete grasp of the code. ## name and config Determine the name and priority of the plugin, and add to conf/config-default.yaml. For example, for the example-plugin plugin, - you need to specify the plugin name in the code (the name is the unique identifier of the plugin and cannot be - duplicate), you can see the code in file "__apisix/plugins/example-plugin.lua__" : +you need to specify the plugin name in the code (the name is the unique identifier of the plugin and cannot be +duplicate), you can see the code in file "__apisix/plugins/example-plugin.lua__" : ```lua local plugin_name = "example-plugin" @@ -159,15 +163,15 @@ $(INSTALL) apisix/plugins/skywalking/*.lua $(INST_LUADIR)/apisix/plugins/skywalk ## schema and check Write [Json Schema](https://json-schema.org) descriptions and check functions. Similarly, take the example-plugin plugin as an example to see its - configuration data : +configuration data: ```json { - "example-plugin" : { - "i": 1, - "s": "s", - "t": [1] - } + "example-plugin": { + "i": 1, + "s": "s", + "t": [1] + } } ``` @@ -235,12 +239,12 @@ Here is the consumer configuration for key-auth plugin: ```json { - "username": "Joe", - "plugins": { - "key-auth": { - "key": "Joe's key" - } + "username": "Joe", + "plugins": { + "key-auth": { + "key": "Joe's key" } + } } ``` @@ -339,11 +343,11 @@ conf: ```json { - "rejected_code":503, - "burst":0, - "default_conn_delay":0.1, - "conn":1, - "key":"remote_addr" + "rejected_code": 503, + "burst": 0, + "default_conn_delay": 0.1, + "conn": 1, + "key": "remote_addr" } ``` @@ -395,7 +399,7 @@ A test case consists of three parts : - __Output check__ : status, header, body, error log check When we request __/t__, which config in the configuration file, the Nginx will call "__content_by_lua_block__" instruction to - complete the Lua script, and finally return. The assertion of the use case is response_body return "done", +complete the Lua script, and finally return. The assertion of the use case is response_body return "done", "__no_error_log__" means to check the "__error.log__" of Nginx. There must be no ERROR level record. The log files for the unit test are located in the following folder: 't/servroot/logs'. diff --git a/docs/en/latest/plugins/hmac-auth.md b/docs/en/latest/plugins/hmac-auth.md index 2843f3db..ffd7e28e 100644 --- a/docs/en/latest/plugins/hmac-auth.md +++ b/docs/en/latest/plugins/hmac-auth.md @@ -23,12 +23,16 @@ title: hmac-auth ## Summary - - [**Name**](#name) - - [**Attributes**](#attributes) - - [**How To Enable**](#how-to-enable) - - [**Test Plugin**](#test-plugin) - - [**Disable Plugin**](#disable-plugin) - - [**Generate Signature Examples**](#generate-signature-examples) +- [Summary](#summary) +- [Name](#name) +- [Attributes](#attributes) +- [How To Enable](#how-to-enable) +- [Test Plugin](#test-plugin) + - [generate signature:](#generate-signature) + - [Use the generated signature to try the request](#use-the-generated-signature-to-try-the-request) +- [Custom header key](#custom-header-key) +- [Disable Plugin](#disable-plugin) +- [Generate Signature Examples](#generate-signature-examples) ## Name @@ -38,15 +42,15 @@ The `consumer` then adds its key to request header to verify its request. ## Attributes -| Name | Type | Requirement | Default | Valid | Description | -| -------------- | ------------- | ----------- | ------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| access_key | string | required | | | Different `consumer` objects should have different values, and it should be unique. If different consumers use the same `access_key`, a request matching exception will occur. | -| secret_key | string | required | | | Use as a pair with `access_key`. | -| algorithm | string | optional | "hmac-sha256" | ["hmac-sha1", "hmac-sha256", "hmac-sha512"] | Encryption algorithm. | -| clock_skew | integer | optional | 0 | | The clock skew allowed by the signature in seconds. For example, if the time is allowed to skew by 10 seconds, then it should be set to `10`. especially, `0` means not checking `Date` | -| signed_headers | array[string] | optional | | | Restrict the headers that are added to the encrypted calculation. After the specified, the client request can only specify the headers within this range. When this item is empty, all the headers specified by the client request will be added to the encrypted calculation | -| keep_headers | boolean | optional | false | [ true, false ] | Whether it is necessary to keep the request headers of `X-HMAC-SIGNATURE`, `X-HMAC-ALGORITHM` and `X-HMAC-SIGNED-HEADERS` in the http request after successful authentication. true: means to keep the http request header, false: means to remove the http request header. | -| encode_uri_params | boolean | optional | true | [ true, false ] | Whether to encode the uri parameter in the signature, for example: `params1=hello%2Cworld` is encoded, `params2=hello,world` is not encoded. true: means to encode the uri parameter in the signature, false: not to encode the uri parameter in the signature. | +| Name | Type | Requirement | Default | Valid | Description | +| ----------------- | ------------- | ----------- | ------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| access_key | string | required | | | Different `consumer` objects should have different values, and it should be unique. If different consumers use the same `access_key`, a request matching exception will occur. | +| secret_key | string | required | | | Use as a pair with `access_key`. | +| algorithm | string | optional | "hmac-sha256" | ["hmac-sha1", "hmac-sha256", "hmac-sha512"] | Encryption algorithm. | +| clock_skew | integer | optional | 0 | | The clock skew allowed by the signature in seconds. For example, if the time is allowed to skew by 10 seconds, then it should be set to `10`. especially, `0` means not checking `Date` | +| signed_headers | array[string] | optional | | | Restrict the headers that are added to the encrypted calculation. After the specified, the client request can only specify the headers within this range. When this item is empty, all the headers specified by the client request will be added to the encrypted calculation | +| keep_headers | boolean | optional | false | [ true, false ] | Whether it is necessary to keep the request headers of `X-HMAC-SIGNATURE`, `X-HMAC-ALGORITHM` and `X-HMAC-SIGNED-HEADERS` in the http request after successful authentication. true: means to keep the http request header, false: means to remove the http request header. | +| encode_uri_params | boolean | optional | true | [ true, false ] | Whether to encode the uri parameter in the signature, for example: `params1=hello%2Cworld` is encoded, `params2=hello,world` is not encoded. true: means to encode the uri parameter in the signature, false: not to encode the uri parameter in the signature. | ## How To Enable @@ -105,15 +109,15 @@ The calculation formula of the signature is `signature = HMAC-SHAx-HEX(secret_ke * Split the `query` into several items according to the & separator, each item is in the form of key=value or only key. * According to whether the uri parameter is encoded, there are two situations: * When `encode_uri_params` is true: - * Encoding each item after disassembly is divided into the following two situations. - * When the item has only key, the conversion formula is uri_encode(key) + "=". - * When the item is in the form of key=value, the conversion formula is in the form of uri_encode(key) + "=" + uri_encode(value). Here value can be an empty string. - * After converting each item, sort by key in lexicographic order (ASCII code from small to large), and connect them with the & symbol to generate the corresponding canonical_query_string. + * Encoding each item after disassembly is divided into the following two situations. + * When the item has only key, the conversion formula is uri_encode(key) + "=". + * When the item is in the form of key=value, the conversion formula is in the form of uri_encode(key) + "=" + uri_encode(value). Here value can be an empty string. + * After converting each item, sort by key in lexicographic order (ASCII code from small to large), and connect them with the & symbol to generate the corresponding canonical_query_string. * When `encode_uri_params` is false: - * Encoding each item after disassembly is divided into the following two situations. - * When the item has only key, the conversion formula is key + "=". - * When the item is in the form of key=value, the conversion formula is in the form of key + "=" + value. Here value can be an empty string. - * After converting each item, sort by key in lexicographic order (ASCII code from small to large), and connect them with the & symbol to generate the corresponding canonical_query_string. + * Encoding each item after disassembly is divided into the following two situations. + * When the item has only key, the conversion formula is key + "=". + * When the item is in the form of key=value, the conversion formula is in the form of key + "=" + value. Here value can be an empty string. + * After converting each item, sort by key in lexicographic order (ASCII code from small to large), and connect them with the & symbol to generate the corresponding canonical_query_string. > The signed_headers_string generation steps are as follows: @@ -178,9 +182,9 @@ hash = hmac.new(secret, message, hashlib.sha256) print(base64.b64encode(hash.digest())) ``` -Type | Hash | -----------|----------------------------------------------| -SIGNATURE | 8XV1GB7Tq23OJcoz6wjqTs4ZLxr9DiLoY4PxzScWGYg= | +| Type | Hash | +| --------- | -------------------------------------------- | +| SIGNATURE | 8XV1GB7Tq23OJcoz6wjqTs4ZLxr9DiLoY4PxzScWGYg= | ### Use the generated signature to try the request @@ -295,16 +299,16 @@ Need to pay attention to the handling of newline characters in signature strings Example inputs: -Variable | Value ----|--- -secret | this is secret key -message | this is signature string +| Variable | Value | +| -------- | ------------------------ | +| secret | this is secret key | +| message | this is signature string | Example outputs: -Type | Hash ----|--- -hexit | ad1b76c7e5054009380edca35d3f36cc5b6f45c82ee02ea3af64197ebddb9345 -base64 | rRt2x+UFQAk4DtyjXT82zFtvRcgu4C6jr2QZfr3bk0U= +| Type | Hash | +| ------ | ---------------------------------------------------------------- | +| hexit | ad1b76c7e5054009380edca35d3f36cc5b6f45c82ee02ea3af64197ebddb9345 | +| base64 | rRt2x+UFQAk4DtyjXT82zFtvRcgu4C6jr2QZfr3bk0U= | Please refer to [**HMAC Generate Signature Examples**](../examples/plugins-hmac-auth-generate-signature.md) diff --git a/docs/en/latest/stream-proxy.md b/docs/en/latest/stream-proxy.md index 7eced3ed..19484d06 100644 --- a/docs/en/latest/stream-proxy.md +++ b/docs/en/latest/stream-proxy.md @@ -32,11 +32,11 @@ By default, no any stream proxy is enabled. ```yaml apisix: - stream_proxy: # TCP/UDP proxy - tcp: # TCP proxy address list + stream_proxy: # TCP/UDP proxy + tcp: # TCP proxy address list - 9100 - "127.0.0.1:9101" - udp: # UDP proxy address list + udp: # UDP proxy address list - 9200 - "127.0.0.1:9211" ``` @@ -60,7 +60,7 @@ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f03 It means APISIX will proxy the request to `127.0.0.1:1995` which the client remote address is `127.0.0.1`. -For more use cases, please take a look at [test case](../t/stream-node/sanity.t). +For more use cases, please take a look at [test case](https://github.com/apache/apisix/blob/master/t/stream-node/sanity.t). ## More Limit Options diff --git a/docs/es/latest/README.md b/docs/es/latest/README.md index 510a3f09..a0d55d63 100644 --- a/docs/es/latest/README.md +++ b/docs/es/latest/README.md @@ -323,7 +323,7 @@ Una gran variedad de compañías y organizacioes usan APISIX para investigación -Se alienta a los usuarios a sumarse a la página [Powered By](powered-by.md). +Se alienta a los usuarios a sumarse a la página [Powered By](https://github.com/apache/apisix/blob/master/powered-by.md). ## Landscape (panorama) diff --git a/docs/zh/latest/FAQ.md b/docs/zh/latest/FAQ.md index 4169933d..fa8b93c6 100644 --- a/docs/zh/latest/FAQ.md +++ b/docs/zh/latest/FAQ.md @@ -34,7 +34,7 @@ APISIX 基于 etcd 来完成配置的保存和同步，而不是 postgres 或者 ## APISIX 的性能怎么样？ -APISIX 设计和开发的目标之一，就是业界最高的性能。具体测试数据见这里：[benchmark](https://github.com/apache/apisix/blob/master/benchmark.md) +APISIX 设计和开发的目标之一，就是业界最高的性能。具体测试数据见这里：[benchmark](https://github.com/apache/apisix/blob/master/docs/en/latest/benchmark.md) APISIX 是当前性能最好的 API 网关，单核 QPS 达到 2.3 万，平均延时仅有 0.6 毫秒。 @@ -58,7 +58,7 @@ APISIX 是当前性能最好的 API 网关，单核 QPS 达到 2.3 万，平均 4. 变化通知 5. 高性能 -APISIX 需要一个配置中心，上面提到的很多功能是传统关系型数据库和KV数据库是无法提供的。与 etcd 同类软件还有 Consul、ZooKeeper等，更详细比较可以参考这里：[etcd why](https://github.com/etcd-io/etcd/blob/master/Documentation/learning/why.md#comparison-chart)，在将来也许会支持其他配置存储方案。 +APISIX 需要一个配置中心，上面提到的很多功能是传统关系型数据库和 KV 数据库是无法提供的。与 etcd 同类软件还有 Consul、ZooKeeper 等，更详细比较可以参考这里：[etcd why](https://etcd.io/docs/v3.4.0/learning/why/)，在将来也许会支持其他配置存储方案。 ## 为什么在用 Luarocks 安装 APISIX 依赖时会遇到超时，很慢或者不成功的情况？ @@ -78,8 +78,8 @@ luarocks 服务。 运行 `luarocks config rocks_servers` 命令（这个命令 比如，`foo.com/product/index.html?id=204&page=2`, 根据 URL 中 query string 中的 `id` 作为条件来灰度发布： -1. A组：id <= 1000 -2. B组：id > 1000 +1. A 组：id <= 1000 +2. B 组：id > 1000 有两种不同的方法来实现： @@ -114,7 +114,7 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/2 -H 'X-API-KEY: edd1c9f034335 ``` 更多的 lua-resty-radixtree 匹配操作，可查看操作列表： -https://github.com/iresty/lua-resty-radixtree#operator-list +https://github.com/api7/lua-resty-radixtree#operator-list 2、通过 traffic-split 插件来实现 @@ -207,15 +207,15 @@ Server: APISIX web server ## 如何修改日志等级 -默认的APISIX日志等级为`warn`，如果需要查看`core.log.info`的打印结果需要将日志等级调整为`info`。 +默认的 APISIX 日志等级为`warn`，如果需要查看`core.log.info`的打印结果需要将日志等级调整为`info`。 具体步骤： -1、修改conf/config.yaml中的nginx log配置参数`error_log_level: "warn"`为`error_log_level: "info"`。 +1、修改 conf/config.yaml 中的 nginx log 配置参数`error_log_level: "warn"`为`error_log_level: "info"`。 2、重启抑或 reload APISIX -之后便可以在logs/error.log中查看到info的日志了。 +之后便可以在 logs/error.log 中查看到 info 的日志了。 ## 如何加载自己编写的插件 @@ -227,26 +227,26 @@ Apache APISIX 的插件支持热加载。 默认情况下，APISIX 在处理 HTTP 请求时只监听 9080 端口。如果你想让 APISIX 监听多个端口，你需要修改配置文件中的相关参数，具体步骤如下： -1. 修改`conf/config.yaml`中 HTTP 端口监听的参数`node_listen`，示例： +1. 修改 `conf/config.yaml` 中 HTTP 端口监听的参数`node_listen`，示例： - ``` - apisix: - node_listen: - - 9080 - - 9081 - - 9082 - ``` + ``` + apisix: + node_listen: + - 9080 + - 9081 + - 9082 + ``` - 处理 HTTPS 请求也类似，修改`conf/config.yaml`中 HTTPS 端口监听的参数``ssl.listen_port``，示例： + 处理 HTTPS 请求也类似，修改`conf/config.yaml`中 HTTPS 端口监听的参数`ssl.listen_port`，示例： - ``` - apisix: - ssl: - listen_port: - - 9443 - - 9444 - - 9445 - ``` + ``` + apisix: + ssl: + listen_port: + - 9443 + - 9444 + - 9445 + ``` 2.重启抑或 reload APISIX diff --git a/docs/zh/latest/README.md b/docs/zh/latest/README.md index 031fcbb5..3c63ab11 100644 --- a/docs/zh/latest/README.md +++ b/docs/zh/latest/README.md @@ -66,7 +66,7 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵 - **多协议** - [TCP/UDP 代理](stream-proxy.md): 动态 TCP/UDP 代理。 - - [Dubbo 代理](plugins/dubbo-proxy.md): 动态代理 HTTP 请求到 Dubbo 后端。 + - [Dubbo 代理](../../en/latest/plugins/dubbo-proxy.md): 动态代理 HTTP 请求到 Dubbo 后端。 - [动态 MQTT 代理](plugins/mqtt-proxy.md): 支持用 `client_id` 对 MQTT 进行负载均衡，同时支持 MQTT [3.1.\*](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) 和 [5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html) 两个协议标准。 - [gRPC 代理](grpc-proxy.md)：通过 APISIX 代理 gRPC 连接，并使用 APISIX 的大部分特性管理你的 gRPC 服务。 - [gRPC 协议转换](plugins/grpc-transcode.md)：支持协议的转换，这样客户端可以通过 HTTP/JSON 来访问你的 gRPC API。 @@ -91,13 +91,13 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵 - **精细化路由** - - [支持全路径匹配和前缀匹配](router-radixtree.md#how-to-use-libradixtree-in-apisix) - - [支持使用 Nginx 所有内置变量做为路由的条件](/router-radixtree.md#how-to-filter-route-by-nginx-builtin-variable)，所以你可以使用 `cookie`, `args` 等做为路由的条件，来实现灰度发布、A/B 测试等功能 + - [支持全路径匹配和前缀匹配](../../en/latest/router-radixtree.md#how-to-use-libradixtree-in-apisix) + - [支持使用 Nginx 所有内置变量做为路由的条件](../../en/latest/router-radixtree.md#how-to-filter-route-by-nginx-builtin-variable)，所以你可以使用 `cookie`, `args` 等做为路由的条件，来实现灰度发布、A/B 测试等功能 - 支持[各类操作符做为路由的判断条件](https://github.com/iresty/lua-resty-radixtree#operator-list)，比如 `{"arg_age", ">", 24}` - 支持[自定义路由匹配函数](https://github.com/iresty/lua-resty-radixtree/blob/master/t/filter-fun.t#L10) - IPv6：支持使用 IPv6 格式匹配路由 - 支持路由的[自动过期(TTL)](admin-api.md#route) - - [支持路由的优先级](router-radixtree.md#3-match-priority) + - [支持路由的优先级](../../en/latest/router-radixtree.md#3-match-priority) - [支持批量 Http 请求](plugins/batch-requests.md) - **安全防护** @@ -119,7 +119,7 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵 - OpenTracing 可观测性: 支持 [Apache Skywalking](plugins/skywalking.md) 和 [Zipkin](plugins/zipkin.md)。 - 对接外部服务发现：除了内置的 etcd 外，还支持 `Consul` 和 `Nacos` 的 [DNS 发现模式](https://github.com/apache/apisix/issues/1731#issuecomment-646392129)，以及 [Eureka](discovery.md)。 - 监控和指标: [Prometheus](plugins/prometheus.md) - - 集群：APISIX 节点是无状态的，创建配置中心集群请参考 [etcd Clustering Guide](https://github.com/etcd-io/etcd/blob/master/Documentation/op-guide/clustering.md)。 + - 集群：APISIX 节点是无状态的，创建配置中心集群请参考 [etcd Clustering Guide](https://etcd.io/docs/v3.4.0/op-guide/clustering/)。 - 高可用：支持配置同一个集群内的多个 etcd 地址。 - [控制台](https://github.com/apache/apisix-dashboard): 操作 APISIX 集群。 - 版本控制：支持操作的多次回滚。 @@ -251,7 +251,7 @@ CentOS 7, Ubuntu 16.04, Ubuntu 18.04, Debian 9, Debian 10, macOS, **ARM64** Ubun 使用 AWS 的 8 核心服务器来压测 APISIX，QPS 可以达到 140000，同时延时只有 0.2 毫秒。 -[性能测试脚本](benchmark/run.sh)，以及[测试方法和过程](https://gist.github.com/membphis/137db97a4bf64d3653aa42f3e016bd01)已经开源，欢迎补充。 +[性能测试脚本](https://github.com/apache/apisix/blob/master/benchmark/run.sh)，以及[测试方法和过程](https://gist.github.com/membphis/137db97a4bf64d3653aa42f3e016bd01)已经开源，欢迎补充。 ## Apache APISIX 和 Kong 的比较 @@ -327,7 +327,7 @@ CentOS 7, Ubuntu 16.04, Ubuntu 18.04, Debian 9, Debian 10, macOS, **ARM64** Ubun -欢迎用户把自己加入到 [Powered By](powered-by.md) 页面。 +欢迎用户把自己加入到 [Powered By](https://github.com/apache/apisix/blob/master/powered-by.md) 页面。 ## 全景图 diff --git a/docs/zh/latest/admin-api.md b/docs/zh/latest/admin-api.md index bf7f70a7..eb83d819 100644 --- a/docs/zh/latest/admin-api.md +++ b/docs/zh/latest/admin-api.md @@ -23,15 +23,16 @@ title: Admin API ## 目录 -* [Route](#route) -* [Service](#service) -* [Consumer](#consumer) -* [Upstream](#upstream) -* [SSL](#ssl) -* [Global Rule](#global-rule) -* [Plugin Config](#plugin-config) -* [Plugin Metadata](#plugin-metadata) -* [Plugin](#plugin) +- [目录](#目录) +- [Route](#route) +- [Service](#service) +- [Consumer](#consumer) +- [Upstream](#upstream) +- [SSL](#ssl) +- [Global Rule](#global-rule) +- [Plugin Config](#plugin-config) +- [Plugin Metadata](#plugin-metadata) +- [Plugin](#plugin) ## Route @@ -44,54 +45,54 @@ title: Admin API > 请求方法： -|名字 |请求 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 | 请求 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 的区别可以参考后面的示例 | > URL 请求参数： -|名字 |可选项 |类型 |说明 |示例| -|---------|---------|----|-----------|----| -|ttl |可选 |辅助 |超过这个时间会被自动删除，单位：秒|ttl=1| +| 名字 | 可选项 | 类型 | 说明 | 示例 | +| ---- | ------ | ---- | ---------------------------------- | ----- | +| ttl | 可选 | 辅助 | 超过这个时间会被自动删除，单位：秒 | ttl=1 | > body 请求参数： -|名字 |可选项 |类型 |说明 |示例| -|---------|---------|----|-----------|----| -|uri |与 `uris` 二选一 |匹配规则|除了如 `/foo/bar`、`/foo/gloo` 这种全量匹配外，使用不同 [Router](architecture-design.md#router) 还允许更高级匹配，更多见 [Router](architecture-design.md#router)。|"/hello"| -|uris |与 `uri` 二选一 |匹配规则|非空数组形式，可以匹配多个 `uri`|["/hello", "/world"]| -|plugins |`plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 |Plugin|详见 [Plugin](architecture-design.md#plugin) || -|script |`plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 |Script|详见 [Script](architecture-design.md#script) || -|upstream |`plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 |Upstream|启用的 Upstream 配置，详见 [Upstream](architecture-design.md#upstream)|| -|upstream_id|`plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 |Upstream|启用的 upstream id，详见 [Upstream](architecture-design.md#upstream)|| -|service_id|`plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 |Service|绑定的 Service 配置，详见 [Service](architecture-design.md#service)|| -|plugin_config_id|可选，无法跟 script 一起配置|Plugin|绑定的 Plugin config 配置，详见 [Plugin config](architecture-design.md#plugin-config)|| -|name |可选 |辅助 |标识路由名称|route-xxxx| -|desc |可选 |辅助 |标识描述、使用场景等。|客户 xxxx| -|host |可选 |匹配规则|当前请求域名，比如 `foo.com`；也支持泛域名，比如 `*.foo.com`。|"foo.com"| -|hosts |可选 |匹配规则|非空列表形态的 `host`，表示允许有多个不同 `host`，匹配其中任意一个即可。|{"foo.com", "*.bar.com"}| -|remote_addr|可选 |匹配规则|客户端请求 IP 地址: `192.168.1.101`、`192.168.1.102` 以及 CIDR 格式的支持 `192.168.1.0/24`。特别的，APISIX 也完整支持 IPv6 地址匹配：`::1`，`fe80::1`, `fe80::1/64` 等。|"192.168.1.0/24"| -|remote_addrs|可选 |匹配规则|非空列表形态的 `remote_addr`，表示允许有多个不同 IP 地址，符合其中任意一个即可。|{"127.0.0.1", "192.0.0.0/8", "::1"}| -|methods |可选 |匹配规则|如果为空或没有该选项，代表没有任何 `method` 限制，也可以是一个或多个的组合：`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`，`CONNECT`，`TRACE`。|{"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](https://github.com/api7/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"}| -|enable_websocket|可选 |辅助| 是否启用 `websocket`(boolean), 缺省 `false`.|| -|status |可选 |辅助| 是否启用此路由, 缺省 `1`。|`1` 表示启用，`0` 表示禁用| -|create_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670| -|update_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670| +| 名字 | 可选项 | 类型 | 说明 | 示例 | +| ---------------- | ----------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| uri | 与 `uris` 二选一 | 匹配规则 | 除了如 `/foo/bar`、`/foo/gloo` 这种全量匹配外，使用不同 [Router](architecture-design.md#router) 还允许更高级匹配，更多见 [Router](architecture-design.md#router)。 | "/hello" | +| uris | 与 `uri` 二选一 | 匹配规则 | 非空数组形式，可以匹配多个 `uri` | ["/hello", "/world"] | +| plugins | `plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 | Plugin | 详见 [Plugin](architecture-design.md#plugin) | | +| script | `plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 | Script | 详见 [Script](architecture-design.md#script) | | +| upstream | `plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 | Upstream | 启用的 Upstream 配置，详见 [Upstream](architecture-design.md#upstream) | | +| upstream_id | `plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 | Upstream | 启用的 upstream id，详见 [Upstream](architecture-design.md#upstream) | | +| service_id | `plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 | Service | 绑定的 Service 配置，详见 [Service](architecture-design.md#service) | | +| plugin_config_id | 可选，无法跟 script 一起配置 | Plugin | 绑定的 Plugin config 配置，详见 [Plugin config](architecture-design.md#plugin-config) | | +| name | 可选 | 辅助 | 标识路由名称 | route-xxxx | +| desc | 可选 | 辅助 | 标识描述、使用场景等。 | 客户 xxxx | +| host | 可选 | 匹配规则 | 当前请求域名，比如 `foo.com`；也支持泛域名，比如 `*.foo.com`。 | "foo.com" | +| hosts | 可选 | 匹配规则 | 非空列表形态的 `host`，表示允许有多个不同 `host`，匹配其中任意一个即可。 | {"foo.com", "\*.bar.com"} | +| remote_addr | 可选 | 匹配规则 | 客户端请求 IP 地址: `192.168.1.101`、`192.168.1.102` 以及 CIDR 格式的支持 `192.168.1.0/24`。特别的，APISIX 也完整支持 IPv6 地址匹配：`::1`，`fe80::1`, `fe80::1/64` 等。 | "192.168.1.0/24" | +| remote_addrs | 可选 | 匹配规则 | 非空列表形态的 `remote_addr`，表示允许有多个不同 IP 地址，符合其中任意一个即可。 | {"127.0.0.1", "192.0.0.0/8", "::1"} | +| methods | 可选 | 匹配规则 | 如果为空或没有该选项，代表没有任何 `method` 限制，也可以是一个或多个的组合：`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`，`CONNECT`，`TRACE`。 | {"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](https://github.com/api7/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"} | +| enable_websocket | 可选 | 辅助 | 是否启用 `websocket`(boolean), 缺省 `false`. | | +| status | 可选 | 辅助 | 是否启用此路由, 缺省 `1`。 | `1` 表示启用，`0` 表示禁用 | +| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 | +| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 | 有两点需要特别注意： -* 除了 `uri`/`uris` 是必选的之外，`plugins`、`script`、`upstream`/`upstream_id`、`service_id` 这三类必须选择其中至少一个。 -* 对于同一类参数比如 `uri`与 `uris`，`upstream` 与 `upstream_id`，`host` 与 `hosts`，`remote_addr` 与 `remote_addrs` 等，是不能同时存在，二者只能选择其一。如果同时启用，接口会报错。 +- 除了 `uri`/`uris` 是必选的之外，`plugins`、`script`、`upstream`/`upstream_id`、`service_id` 这三类必须选择其中至少一个。 +- 对于同一类参数比如 `uri`与 `uris`，`upstream` 与 `upstream_id`，`host` 与 `hosts`，`remote_addr` 与 `remote_addrs` 等，是不能同时存在，二者只能选择其一。如果同时启用，接口会报错。 route 对象 json 配置内容： @@ -288,29 +289,29 @@ HTTP/1.1 200 OK > 请求方法： -|名字 |请求 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 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留| +| 名字 | 请求 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 |可选 |Plugin|详见 [Plugin](architecture-design.md#plugin) || -|upstream | upstream 或 upstream_id 两个选一个 |Upstream|启用的 Upstream 配置，详见 [Upstream](architecture-design.md#upstream)|| -|upstream_id| upstream 或 upstream_id 两个选一个 |Upstream|启用的 upstream id，详见 [Upstream](architecture-design.md#upstream)|| -|name |可选 |辅助 |标识服务名称。|| -|desc |可选 |辅助 |服务描述、使用场景等。|| -|labels |可选 |匹配规则|标识附加属性的键值对|{"version":"v2","build":"16","env":"production"}| -|enable_websocket|可选 |辅助| 是否启用 `websocket`(boolean), 缺省 `false`.|| -|create_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670| -|update_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670| +| 名字 | 可选项 | 类型 | 说明 | 示例 | +| ---------------- | ---------------------------------- | -------- | ---------------------------------------------------------------------- | ------------------------------------------------ | +| plugins | 可选 | Plugin | 详见 [Plugin](architecture-design.md#plugin) | | +| upstream | upstream 或 upstream_id 两个选一个 | Upstream | 启用的 Upstream 配置，详见 [Upstream](architecture-design.md#upstream) | | +| upstream_id | upstream 或 upstream_id 两个选一个 | Upstream | 启用的 upstream id，详见 [Upstream](architecture-design.md#upstream) | | +| name | 可选 | 辅助 | 标识服务名称。 | | +| desc | 可选 | 辅助 | 服务描述、使用场景等。 | | +| labels | 可选 | 匹配规则 | 标识附加属性的键值对 | {"version":"v2","build":"16","env":"production"} | +| enable_websocket | 可选 | 辅助 | 是否启用 `websocket`(boolean), 缺省 `false`. | | +| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 | +| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 | serivce 对象 json 配置内容： @@ -440,23 +441,23 @@ HTTP/1.1 200 OK > 请求方法： -|名字 |请求 uri|请求 body|说明 | -|---------|-------------------------|--|------| -|GET |/apisix/admin/consumers|无|获取资源列表| -|GET |/apisix/admin/consumers/{id}|无|获取资源| -|PUT |/apisix/admin/consumers|{...}|创建资源| -|DELETE |/apisix/admin/consumers/{id}|无|删除资源| +| 名字 | 请求 uri | 请求 body | 说明 | +| ------ | ---------------------------- | --------- | ------------ | +| GET | /apisix/admin/consumers | 无 | 获取资源列表 | +| GET | /apisix/admin/consumers/{id} | 无 | 获取资源 | +| PUT | /apisix/admin/consumers | {...} | 创建资源 | +| DELETE | /apisix/admin/consumers/{id} | 无 | 删除资源 | > body 请求参数： -|名字 |可选项 |类型 |说明 |示例| -|---------|---------|----|-----------|----| -|username|必需|辅助|Consumer 名称。|| -|plugins|可选|Plugin|该 Consumer 对应的插件配置，它的优先级是最高的：Consumer > Route > Service。对于具体插件配置，可以参考 [Plugins](#plugin) 章节。|| -|desc |可选 |辅助|consumer描述|| -|labels |可选 |匹配规则|标识附加属性的键值对|{"version":"v2","build":"16","env":"production"}| -|create_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670| -|update_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670| +| 名字 | 可选项 | 类型 | 说明 | 示例 | +| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | +| username | 必需 | 辅助 | Consumer 名称。 | | +| plugins | 可选 | Plugin | 该 Consumer 对应的插件配置，它的优先级是最高的：Consumer > Route > Service。对于具体插件配置，可以参考 [Plugins](#plugin) 章节。 | | +| desc | 可选 | 辅助 | consumer 描述 | | +| labels | 可选 | 匹配规则 | 标识附加属性的键值对 | {"version":"v2","build":"16","env":"production"} | +| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 | +| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 | consumer 对象 json 配置内容： @@ -512,54 +513,54 @@ Date: Thu, 26 Dec 2019 08:17:49 GMT > 请求方法： -|名字 |请求 uri|请求 body|说明 | -|---------|-------------------------|--|------| -|GET |/apisix/admin/upstreams|无|获取资源列表| -|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 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。| +| 名字 | 请求 uri | 请求 body | 说明 | +| ------ | ----------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | /apisix/admin/upstreams | 无 | 获取资源列表 | +| 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 |必需|枚举||负载均衡算法|| -|nodes |必需，不能和 `service_name` 一起用|Node|哈希表，内部元素的 key 是上游机器地址列表，格式为`地址 + Port`，其中地址部分可以是 IP 也可以是域名，比如 `192.168.1.100:80`、`foo.com:80`等。value 则是节点的权重，特别的，当权重值为 `0` 有特殊含义，通常代表该上游节点失效，永远不希望被选中。`nodes` 可以为空，这通常用作占位符。客户端命中这样的上游会返回 502。|`192.168.1.100:80`| -|service_name |必需，不能和 `nodes` 一起用|string|服务发现时使用的服务名，见[集成服务发现注册中心](./discovery.md)|`a-bootiful-client`| -|discovery_type |必需，如果设置了 `service_name` |string|服务发现类型，见[集成服务发现注册中心](./discovery.md)|`eureka`| -|key |条件必需|匹配类型|该选项只有类型是 `chash` 才有效。根据 `key` 来查找对应的 node `id`，相同的 `key` 在同一个对象中，永远返回相同 id，目前支持的 Nginx 内置变量有 `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`，其中 `arg_***` 是来自URL的请求参数，[Nginx 变量列表](http://nginx.org/en/docs/varindex.html)|| -|checks |可选|health_checker|配置健康检查的参数，详细可参考[health-check](../health-check.md)|| -|retries |可选|整型|使用底层的 Nginx 重试机制将请求传递给下一个上游，默认启用重试且次数为后端可用的 node 数量。如果指定了具体重试次数，它将覆盖默认值。`0` 代表不启用重试机制。|| -|timeout |可选|超时时间对象|设置连接、发送消息、接收消息的超时时间|| -|hash_on |可选|辅助|`hash_on` 支持的类型有 `vars`（Nginx内置变量），`header`（自定义header），`cookie`，`consumer`，默认值为 `vars`| -|name |可选 |辅助|标识上游服务名称、使用场景等。|| -|desc |可选 |辅助|上游服务描述、使用场景等。|| -|pass_host |可选|枚举|`pass` 透传客户端请求的 host, `node` 不透传客户端请求的 host, 使用 upstream node 配置的 host, `rewrite` 使用 `upstream_host` 配置的值重写 host 。默认为 `pass`。|| -|upstream_host |可选|辅助|只在 `pass_host` 配置为 `rewrite` 时有效。|| -|scheme|可选 |辅助|跟上游通信时使用的 scheme。需要是 ['http', 'https', 'grpc', 'grpcs'] 其中的一个，默认是 'http'。| -|labels |可选 |匹配规则|标识附加属性的键值对|{"version":"v2","build":"16","env":"production"}| -|create_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670| -|update_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670| +| 名字 | 可选项 | 类型 | 说明 | 示例 | +| -------------- | ---------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | --- | +| type | 必需 | 枚举 | | 负载均衡算法 | | +| nodes | 必需，不能和 `service_name` 一起用 | Node | 哈希表，内部元素的 key 是上游机器地址列表，格式为`地址 + Port`，其中地址部分可以是 IP 也可以是域名，比如 `192.168.1.100:80`、`foo.com:80`等。value 则是节点的权重，特别的，当权重值为 `0` 有特殊含义，通常代表该上游节点失效，永远不希望被选中。`nodes` 可以为空，这通常用作占位符。客户端命中这样的上游会返回 502。 | `192.168.1.100:80` | +| service_name | 必需，不能和 `nodes` 一起用 | string | 服务发现时使用的服务名，见[集成服务发现注册中心](./discovery.md) | `a-bootiful-client` | +| discovery_type | 必需，如果设置了 `service_name` | string | 服务发现类型，见[集成服务发现注册中心](./discovery.md) | `eureka` | +| key | 条件必需 | 匹配类型 | 该选项只有类型是 `chash` 才有效。根据 `key` 来查找对应的 node `id`，相同的 `key` 在同一个对象中，永远返回相同 id，目前支持的 Nginx 内置变量有 `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`，其中 `arg_***` 是来自 URL 的请求参数，[Nginx 变量列表](http://nginx.org/en/docs/varindex.html) | | +| checks | 可选 | health_checker | 配置健康检查的参数，详细可参考[health-check](health-check.md) | | +| retries | 可选 | 整型 | 使用底层的 Nginx 重试机制将请求传递给下一个上游，默认启用重试且次数为后端可用的 node 数量。如果指定了具体重试次数，它将覆盖默认值。`0` 代表不启用重试机制。 | | +| timeout | 可选 | 超时时间对象 | 设置连接、发送消息、接收消息的超时时间 | | +| hash_on | 可选 | 辅助 | `hash_on` 支持的类型有 `vars`（Nginx 内置变量），`header`（自定义 header），`cookie`，`consumer`，默认值为 `vars` | +| name | 可选 | 辅助 | 标识上游服务名称、使用场景等。 | | +| desc | 可选 | 辅助 | 上游服务描述、使用场景等。 | | +| pass_host | 可选 | 枚举 | `pass` 透传客户端请求的 host, `node` 不透传客户端请求的 host, 使用 upstream node 配置的 host, `rewrite` 使用 `upstream_host` 配置的值重写 host 。默认为 `pass`。 | | +| upstream_host | 可选 | 辅助 | 只在 `pass_host` 配置为 `rewrite` 时有效。 | | +| scheme | 可选 | 辅助 | 跟上游通信时使用的 scheme。需要是 ['http', 'https', 'grpc', 'grpcs'] 其中的一个，默认是 'http'。 | +| labels | 可选 | 匹配规则 | 标识附加属性的键值对 | {"version":"v2","build":"16","env":"production"} | +| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 | +| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 | `type` 可以是以下的一种： -* `roundrobin`: 带权重的 roundrobin -* `chash`: 一致性哈希 -* `ewma`: 选择延迟最小的节点，计算细节参考 https://en.wikipedia.org/wiki/EWMA_chart -* `least_conn`: 选择 `(active_conn + 1) / weight` 最小的节点。注意这里的 `active connection` 概念跟 Nginx 的相同：它是当前正在被请求使用的连接。 +- `roundrobin`: 带权重的 roundrobin +- `chash`: 一致性哈希 +- `ewma`: 选择延迟最小的节点，计算细节参考 https://en.wikipedia.org/wiki/EWMA_chart +- `least_conn`: 选择 `(active_conn + 1) / weight` 最小的节点。注意这里的 `active connection` 概念跟 Nginx 的相同：它是当前正在被请求使用的连接。 `hash_on` 比较复杂，这里专门说明下： -1. 设为 `vars` 时，`key` 为必传参数，目前支持的 Nginx 内置变量有 `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`，其中 `arg_***` 是来自URL的请求参数，[Nginx 变量列表](http://nginx.org/en/docs/varindex.html) -1. 设为 `header` 时, `key` 为必传参数，其值为自定义的 header name, 即 "http_`key`" -1. 设为 `cookie` 时, `key` 为必传参数，其值为自定义的 cookie name，即 "cookie_`key`" -1. 设为 `consumer` 时，`key` 不需要设置。此时哈希算法采用的 `key` 为认证通过的 `consumer_name`。 -1. 如果指定的 `hash_on` 和 `key` 获取不到值时，就是用默认值：`remote_addr`。 +1. 设为 `vars` 时，`key` 为必传参数，目前支持的 Nginx 内置变量有 `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`，其中 `arg_***` 是来自 URL 的请求参数，[Nginx 变量列表](http://nginx.org/en/docs/varindex.html) +2. 设为 `header` 时, `key` 为必传参数，其值为自定义的 header name, 即 "http\_`key`" +3. 设为 `cookie` 时, `key` 为必传参数，其值为自定义的 cookie name，即 "cookie\_`key`" +4. 设为 `consumer` 时，`key` 不需要设置。此时哈希算法采用的 `key` 为认证通过的 `consumer_name`。 +5. 如果指定的 `hash_on` 和 `key` 获取不到值时，就是用默认值：`remote_addr`。 upstream 对象 json 配置内容： @@ -678,27 +679,27 @@ HTTP/1.1 200 OK > 请求方法： -|名字 |请求 uri|请求 body|说明 | -|---------|-------------------------|--|------| -|GET |/apisix/admin/ssl|无|获取资源列表| -|GET |/apisix/admin/ssl/{id}|无|获取资源| -|PUT |/apisix/admin/ssl/{id}|{...}|根据 id 创建资源| -|POST |/apisix/admin/ssl |{...}|创建资源，id 由后台服务自动生成| -|DELETE |/apisix/admin/ssl/{id}|无|删除资源| +| 名字 | 请求 uri | 请求 body | 说明 | +| ------ | ---------------------- | --------- | ------------------------------- | +| GET | /apisix/admin/ssl | 无 | 获取资源列表 | +| GET | /apisix/admin/ssl/{id} | 无 | 获取资源 | +| PUT | /apisix/admin/ssl/{id} | {...} | 根据 id 创建资源 | +| POST | /apisix/admin/ssl | {...} | 创建资源，id 由后台服务自动生成 | +| DELETE | /apisix/admin/ssl/{id} | 无 | 删除资源 | > body 请求参数： -|名字 |可选项 |类型 |说明 |示例| -|---------|---------|----|-----------|----| -|cert|必需|证书|https 证书|| -|key|必需|私钥|https 证书私钥|| -|certs|可选|证书字符串数组|当你想给同一个域名配置多个证书时，除了第一个证书需要通过cert传递外，剩下的证书可以通过该参数传递上来|| -|keys|可选|私钥字符串数组|certs 对应的证书私钥，注意要跟 certs 一一对应|| -|snis|必需|匹配规则|非空数组形式，可以匹配多个 SNI|| -|labels|可选|匹配规则|标识附加属性的键值对|{"version":"v2","build":"16","env":"production"}| -|create_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670| -|update_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670| -|status|可选 |辅助| 是否启用此SSL, 缺省 `1`。|`1` 表示启用，`0` 表示禁用| +| 名字 | 可选项 | 类型 | 说明 | 示例 | +| ----------- | ------ | -------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | +| cert | 必需 | 证书 | https 证书 | | +| key | 必需 | 私钥 | https 证书私钥 | | +| certs | 可选 | 证书字符串数组 | 当你想给同一个域名配置多个证书时，除了第一个证书需要通过 cert 传递外，剩下的证书可以通过该参数传递上来 | | +| keys | 可选 | 私钥字符串数组 | certs 对应的证书私钥，注意要跟 certs 一一对应 | | +| snis | 必需 | 匹配规则 | 非空数组形式，可以匹配多个 SNI | | +| labels | 可选 | 匹配规则 | 标识附加属性的键值对 | {"version":"v2","build":"16","env":"production"} | +| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 | +| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 | +| status | 可选 | 辅助 | 是否启用此 SSL, 缺省 `1`。 | `1` 表示启用，`0` 表示禁用 | ssl 对象 json 配置内容： @@ -721,22 +722,22 @@ ssl 对象 json 配置内容： > 请求方法： -|名字 |请求 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 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。| +| 名字 | 请求 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](architecture-design.md#plugin) || -|create_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670| -|update_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670| +| 名字 | 可选项 | 类型 | 说明 | 示例 | +| ----------- | ------ | ------ | --------------------------------------------- | ---------- | +| plugins | 必需 | Plugin | 详见 [Plugin](architecture-design.md#plugin) | | +| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 | +| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 | [Back to TOC](#目录) @@ -748,14 +749,14 @@ ssl 对象 json 配置内容： > 请求方法： -|名字 |请求 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 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。| +| 名字 | 请求 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 请求参数： @@ -777,11 +778,11 @@ ssl 对象 json 配置内容： > 请求方法: -|Method |请求 URI|请求 body|说明 | -|---------|-------------------------|--|------| -|GET |/apisix/admin/plugin_metadata/{plugin_name}|无|获取资源| -|PUT |/apisix/admin/plugin_metadata/{plugin_name}|{...}|根据 plugin name 创建资源| -|DELETE |/apisix/admin/plugin_metadata/{plugin_name}|无|删除资源| +| Method | 请求 URI | 请求 body | 说明 | +| ------ | ------------------------------------------- | --------- | ------------------------- | +| GET | /apisix/admin/plugin_metadata/{plugin_name} | 无 | 获取资源 | +| PUT | /apisix/admin/plugin_metadata/{plugin_name} | {...} | 根据 plugin name 创建资源 | +| DELETE | /apisix/admin/plugin_metadata/{plugin_name} | 无 | 删除资源 | > body 请求参数： @@ -806,18 +807,18 @@ Content-Type: text/plain *地址*：/apisix/admin/plugins/{plugin_name} -*说明*: 插件 +*说明*:  插件 -> 请求方法: +> 请求方法: -|名字      |请求 uri|请求 body|说明        | -|---------|-------------------------|--|------| -|GET      |/apisix/admin/plugins/list|无|获取资源列表| -|GET      |/apisix/admin/plugins/{plugin_name}|无|获取资源| +| 名字        | 请求  uri | 请求  body | 说明          | +| ----------- | ----------------------------------- | ---------- | ------------- | +| GET       | /apisix/admin/plugins/list | 无 | 获取资源列表 | +| GET       | /apisix/admin/plugins/{plugin_name} | 无 | 获取资源 | -> body 请求参数： +> body  请求参数： -获取插件 ({plugin_name}) 数据结构的 json object 。 +获取插件  ({plugin_name})  数据结构的  json object 。 例子: @@ -835,8 +836,8 @@ $ curl "http://127.0.0.1:9080/apisix/admin/plugins/key-auth" -H 'X-API-KEY: > 请求方法: -|Method |请求 URI|请求 body|说明 | -|---------|-------------------------|--|------| -|GET |/apisix/admin/plugins?all=true|无|获取资源| +| Method | 请求 URI | 请求 body | 说明 | +| ------ | ------------------------------ | --------- | -------- | +| GET | /apisix/admin/plugins?all=true | 无 | 获取资源 | [Back to TOC](#目录) diff --git a/docs/zh/latest/architecture-design.md b/docs/zh/latest/architecture-design.md index ba836bb9..7dc6be87 100644 --- a/docs/zh/latest/architecture-design.md +++ b/docs/zh/latest/architecture-design.md @@ -376,7 +376,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13 }' ``` -更多细节可以参考[健康检查的文档](../health-check.md)。 +更多细节可以参考[健康检查的文档](./health-check.md)。 下面是几个使用不同`hash_on`类型的配置示例： @@ -484,7 +484,7 @@ APISIX 区别于其他 API 网关的一大特点是允许用户选择不同 Rout - `apisix.router.http`: HTTP 请求路由。 - - `radixtree_uri`: （默认）只使用 `uri` 作为主索引。基于 `radixtree` 引擎，支持全量和深前缀匹配，更多见 [如何使用 router-radixtree](../router-radixtree.md)。 + - `radixtree_uri`: （默认）只使用 `uri` 作为主索引。基于 `radixtree` 引擎，支持全量和深前缀匹配，更多见 [如何使用 router-radixtree](../../en/latest/router-radixtree.md)。 - `绝对匹配`：完整匹配给定的 `uri` ，比如 `/foo/bar`，`/foo/glo`。 - `前缀匹配`：末尾使用 `*` 代表给定的 `uri` 是前缀匹配。比如 `/foo*`，则允许匹配 `/foo/`、`/foo/a`和`/foo/b`等。 - `匹配优先级`：优先尝试绝对匹配，若无法命中绝对匹配，再尝试前缀匹配。 @@ -515,14 +515,14 @@ APISIX 区别于其他 API 网关的一大特点是允许用户选择不同 Rout -1. 授权认证：比如有 [key-auth](../plugins/key-auth.md)、[JWT](plugins/jwt-auth.md) 等。 +1. 授权认证：比如有 [key-auth](plugins/key-auth.md)、[JWT](plugins/jwt-auth.md) 等。 2. 获取 consumer_name：通过授权认证，即可自然获取到对应的 Consumer name，它是 Consumer 对象的唯一识别标识。 3. 获取 Consumer 上绑定的 Plugin 或 Upstream 信息：完成对不同 Consumer 做不同配置的效果。 概括一下，Consumer 是某类服务的消费者，需与用户认证体系配合才能使用。 比如不同的 Consumer 请求同一个 API，网关服务根据当前请求用户信息，对应不同的 Plugin 或 Upstream 配置。 -此外，大家也可以参考 [key-auth](../plugins/key-auth.md) 认证授权插件的调用逻辑，辅助大家来进一步理解 Consumer 概念和使用。 +此外，大家也可以参考 [key-auth](plugins/key-auth.md) 认证授权插件的调用逻辑，辅助大家来进一步理解 Consumer 概念和使用。 如何对某个 Consumer 开启指定插件，可以看下面例子： diff --git a/docs/zh/latest/discovery.md b/docs/zh/latest/discovery.md index b0d03676..051a4e36 100644 --- a/docs/zh/latest/discovery.md +++ b/docs/zh/latest/discovery.md @@ -21,17 +21,17 @@ title: 集成服务发现注册中心 # --> -* [**摘要**](#摘要) -* [**当前支持的注册中心**](#当前支持的注册中心) -* [**如何扩展注册中心**](#如何扩展注册中心) - * [**基本步骤**](#基本步骤) - * [**以 Eureka 举例**](#以-Eureka-举例) - * [**实现 eureka.lua**](#实现-eurekalua) - * [**Eureka 与 APISIX 之间数据转换逻辑**](#Eureka-与-APISIX-之间数据转换逻辑) -* [**注册中心配置**](#注册中心配置) - * [**初始化服务发现**](#初始化服务发现) - * [**Eureka 的配置**](#Eureka-的配置) -* [**upstream 配置**](#upstream-配置) +* [摘要](#摘要) +* [当前支持的注册中心](#当前支持的注册中心) +* [如何扩展注册中心？](#如何扩展注册中心) + * [基本步骤](#基本步骤) + * [以 Eureka 举例](#以-eureka-举例) + * [实现 eureka.lua](#实现-eurekalua) + * [Eureka 与 APISIX 之间数据转换逻辑](#eureka-与-apisix-之间数据转换逻辑) +* [注册中心配置](#注册中心配置) + * [初始化服务发现](#初始化服务发现) + * [Eureka 的配置](#eureka-的配置) +* [upstream 配置](#upstream-配置) ## 摘要 @@ -43,13 +43,13 @@ title: 集成服务发现注册中心 2. 网关会准实时地从注册中心获取服务实例信息； 3. 当用户通过网关请求服务时，网关从注册中心获取的实例列表中选择一个进行代理； -常见的注册中心：Eureka, Etcd, Consul, Nacos, Zookeeper等 +常见的注册中心：Eureka, Etcd, Consul, Nacos, Zookeeper 等 ## 当前支持的注册中心 目前支持 Eureka 和基于 DNS 的服务注册发现，如 Consul 等。 -基于 DNS 的服务注册发现见 [基于 DNS 的服务支持发现](../dns.md#service-discovery-via-dns)。 +基于 DNS 的服务注册发现见 [基于 DNS 的服务支持发现](../../en/latest/dns.md#service-discovery-via-dns)。 Eureka 的支持方式见下文。 @@ -67,32 +67,32 @@ APISIX 要扩展注册中心其实是件非常容易的事情，其基本步骤 #### 实现 eureka.lua -首先在 `apisix/discovery/` 目录中添加 [`eureka.lua`](../../apisix/discovery/eureka.lua); +首先在 `apisix/discovery/` 目录中添加 [`eureka.lua`](../../../apisix/discovery/eureka.lua); 然后在 `eureka.lua` 实现用于初始化的 `init_worker` 函数以及用于获取服务实例节点列表的 `nodes` 函数即可： - ```lua - local _M = { - version = 0.1, - } +```lua +local _M = { + version = 0.1, +} - function _M.nodes(service_name) - ... ... - end +function _M.nodes(service_name) + ... ... +end - function _M.init_worker() - ... ... - end +function _M.init_worker() + ... ... +end - return _M - ``` +return _M +``` #### Eureka 与 APISIX 之间数据转换逻辑 -APISIX是通过 `upstream.nodes` 来配置上游服务的，所以使用注册中心后，通过注册中心获取服务的所有 node 后，赋值给 `upstream.nodes` 来达到相同的效果。那么 APISIX 是怎么将 Eureka 的数据转成 node 的呢？ 假如从 Eureka 获取如下数据： +APISIX 是通过 `upstream.nodes` 来配置上游服务的，所以使用注册中心后，通过注册中心获取服务的所有 node 后，赋值给 `upstream.nodes` 来达到相同的效果。那么 APISIX 是怎么将 Eureka 的数据转成 node 的呢？ 假如从 Eureka 获取如下数据： ```json { @@ -144,11 +144,11 @@ APISIX是通过 `upstream.nodes` 来配置上游服务的，所以使用注册 ```json [ { - "host" : "192.168.1.100", - "port" : 8761, - "weight" : 100, - "metadata" : { - "management.port": "8761", + "host": "192.168.1.100", + "port": 8761, + "weight": 100, + "metadata": { + "management.port": "8761" } } ] @@ -162,8 +162,7 @@ APISIX是通过 `upstream.nodes` 来配置上游服务的，所以使用注册 ```yaml discovery: - eureka: - ... + eureka: ... ``` 此名称要与 `apisix/discovery/` 目录中实现对应注册中心的文件名保持一致。 @@ -177,16 +176,16 @@ discovery: ```yaml discovery: eureka: - host: # it's possible to define multiple eureka hosts addresses of the same eureka cluster. + host: # it's possible to define multiple eureka hosts addresses of the same eureka cluster. - "http://${username}:${password}@${eureka_host1}:${eureka_port1}" - "http://${username}:${password}@${eureka_host2}:${eureka_port2}" prefix: "/eureka/" - fetch_interval: 30 # 从 eureka 中拉取数据的时间间隔，默认30秒 - weight: 100 # default weight for node + fetch_interval: 30 # 从 eureka 中拉取数据的时间间隔，默认30秒 + weight: 100 # default weight for node timeout: - connect: 2000 # 连接 eureka 的超时时间，默认2000ms - send: 2000 # 向 eureka 发送数据的超时时间，默认2000ms - read: 5000 # 从 eureka 读数据的超时时间，默认5000ms + connect: 2000 # 连接 eureka 的超时时间，默认2000ms + send: 2000 # 向 eureka 发送数据的超时时间，默认2000ms + read: 5000 # 从 eureka 读数据的超时时间，默认5000ms ``` 通过 `discovery.eureka.host` 配置 eureka 的服务器地址。 @@ -203,7 +202,7 @@ discovery: ## upstream 配置 -APISIX是通过 `upstream.discovery_type`选择使用的服务发现， `upstream.service_name` 与注册中心的服务名进行关联。下面是将 URL 为 "/user/*" 的请求路由到注册中心名为 "USER-SERVICE" 的服务上例子： +APISIX 是通过 `upstream.discovery_type`选择使用的服务发现， `upstream.service_name` 与注册中心的服务名进行关联。下面是将 URL 为 "/user/\*" 的请求路由到注册中心名为 "USER-SERVICE" 的服务上例子： ```shell $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d ' diff --git a/docs/zh/latest/health-check.md b/docs/zh/latest/health-check.md index 5180e05e..4f854c63 100644 --- a/docs/zh/latest/health-check.md +++ b/docs/zh/latest/health-check.md @@ -21,9 +21,9 @@ title: 健康检查 # --> -## Upstream的健康检查 +## Upstream 的健康检查 -APISIX的健康检查使用[lua-resty-healthcheck](https://github.com/Kong/lua-resty-healthcheck)实现，你可以在upstream中使用它。 +APISIX 的健康检查使用[lua-resty-healthcheck](https://github.com/Kong/lua-resty-healthcheck)实现，你可以在 upstream 中使用它。 注意只有在 upstream 被请求时才会开始健康检查。 如果一个 upstream 被配置但没有被请求，那么就不会有健康检查。 @@ -82,33 +82,37 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13 监控检查的配置内容在`checks`中，`checks`包含两个类型：`active` 和 `passive`，详情如下 -* `active`: 要启动探活健康检查，需要在upstream配置中的 `checks.active` 添加如下配置项。 +* `active`: 要启动探活健康检查，需要在 upstream 配置中的 `checks.active` 添加如下配置项。 - * `active.timeout`: 主动健康检查 socket 超时时间（秒为单位），支持小数点。比如 `1.01` 代表 `1010` 毫秒，`2` 代表 `2000` 毫秒。 + * `active.timeout`: 主动健康检查 socket 超时时间（秒为单位），支持小数点。比如 `1.01` 代表 `1010` 毫秒，`2` 代表 `2000` 毫秒。 - * `active.http_path`: 用于发现upstream节点健康可用的HTTP GET请求路径。 - * `active.host`: 用于发现upstream节点健康可用的HTTP请求主机名。 - * `active.port`: 用于发现upstream节点健康可用的自定义主机端口（可选），配置此项会覆盖 `upstream` 节点中的端口。 + * `active.http_path`: 用于发现 upstream 节点健康可用的 HTTP GET 请求路径。 + * `active.host`: 用于发现 upstream 节点健康可用的 HTTP 请求主机名。 + * `active.port`: 用于发现 upstream 节点健康可用的自定义主机端口（可选），配置此项会覆盖 `upstream` 节点中的端口。 - `healthy`的阀值字段： - * `active.healthy.interval`: 健康的目标节点的健康检查间隔时间（以秒为单位），最小值为1。 - * `active.healthy.successes`: 确定目标是否健康的成功次数，最小值为1。 + `healthy`的阀值字段： - `unhealthy`的阀值字段： - * `active.unhealthy.interval`: 针对不健康目标节点的健康检查之间的间隔（以秒为单位），最小值为1。 - * `active.unhealthy.http_failures`: 确定目标节点不健康的http请求失败次数，最小值为1。 - * `active.req_headers`: 其他请求标头。数组格式，可以填写多个标题。 + * `active.healthy.interval`: 健康的目标节点的健康检查间隔时间（以秒为单位），最小值为 1。 + * `active.healthy.successes`: 确定目标是否健康的成功次数，最小值为 1。 -* `passive`: 要启用被动健康检查，需要在upstream配置中的 `checks.passive` 添加如下配置项。 + `unhealthy`的阀值字段： - `healthy`的阀值字段： - * `passive.healthy.http_statuses`: 如果当前HTTP响应状态码是其中任何一个，则将upstream节点设置为 `healthy` 状态。否则，请忽略此请求。 - * `passive.healthy.successes`: 如果upstream节点被检测成功（由 `passive.healthy.http_statuses` 定义）的次数超过 `successes` 次，则将该节点设置为 `healthy` 状态。 + * `active.unhealthy.interval`: 针对不健康目标节点的健康检查之间的间隔（以秒为单位），最小值为 1。 + * `active.unhealthy.http_failures`: 确定目标节点不健康的 http 请求失败次数，最小值为 1。 + * `active.req_headers`: 其他请求标头。数组格式，可以填写多个标题。 - `unhealthy`的阀值字段： - * `passive.unhealthy.http_statuses`: 如果当前HTTP响应状态码是其中任何一个，则将upstream节点设置为 `unhealthy` 状态。否则，请忽略此请求。 - * `passive.unhealthy.tcp_failures`: 如果TCP通讯失败次数超过 `tcp_failures` 次，则将upstream节点设置为 `unhealthy` 状态。 - * `passive.unhealthy.timeouts`: 如果被动健康检查超时次数超过 `timeouts` 次，则将upstream节点设置为 `unhealthy` 状态。 - * `passive.unhealthy.http_failures`: 如果被动健康检查的HTTP请求失败（由 `passive.unhealthy.http_statuses` 定义）的次数超过 `http_failures`次，则将upstream节点设置为 `unhealthy` 状态。 +* `passive`: 要启用被动健康检查，需要在 upstream 配置中的 `checks.passive` 添加如下配置项。 -健康检查信息可以通过 [控制接口](../control-api.md) 中的 `GET /v1/healthcheck` 接口得到。 + `healthy`的阀值字段： + + * `passive.healthy.http_statuses`: 如果当前 HTTP 响应状态码是其中任何一个，则将 upstream 节点设置为 `healthy` 状态。否则，请忽略此请求。 + * `passive.healthy.successes`: 如果 upstream 节点被检测成功（由 `passive.healthy.http_statuses` 定义）的次数超过 `successes` 次，则将该节点设置为 `healthy` 状态。 + + `unhealthy`的阀值字段： + + * `passive.unhealthy.http_statuses`: 如果当前 HTTP 响应状态码是其中任何一个，则将 upstream 节点设置为 `unhealthy` 状态。否则，请忽略此请求。 + * `passive.unhealthy.tcp_failures`: 如果 TCP 通讯失败次数超过 `tcp_failures` 次，则将 upstream 节点设置为 `unhealthy` 状态。 + * `passive.unhealthy.timeouts`: 如果被动健康检查超时次数超过 `timeouts` 次，则将 upstream 节点设置为 `unhealthy` 状态。 + * `passive.unhealthy.http_failures`: 如果被动健康检查的 HTTP 请求失败（由 `passive.unhealthy.http_statuses` 定义）的次数超过 `http_failures`次，则将 upstream 节点设置为 `unhealthy` 状态。 + +健康检查信息可以通过 [控制接口](../../en/latest/control-api.md) 中的 `GET /v1/healthcheck` 接口得到。 diff --git a/docs/zh/latest/install-dependencies.md b/docs/zh/latest/install-dependencies.md index 5a278f12..3e7e5c1d 100644 --- a/docs/zh/latest/install-dependencies.md +++ b/docs/zh/latest/install-dependencies.md @@ -34,11 +34,11 @@ title: 安装依赖 - 目前 Apache APISIX 默认使用 HTTP 协议与 etcd 集群通信，这并不安全，如果希望保障数据的安全性和完整性。 请为您的 etcd 集群配置证书及对应私钥，并在您的 Apache APISIX etcd endpoints 配置列表中明确使用 `https` 协议前缀。请查阅 `conf/config-default.yaml` 中 etcd 一节相关的配置来了解更多细节。 -- 如果你要想使用 Tengine 替代 OpenResty，请参考 [Install Tengine at Ubuntu](../../.travis/linux_tengine_runner.sh)。 +- 如果你要想使用 Tengine 替代 OpenResty，请参考 [Install Tengine at Ubuntu](https://github.com/apache/apisix/blob/master/.travis/linux_tengine_runner.sh)。 - 如果是 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 在特定编译条件下的问题。 -- 在某些平台上，通过包管理器安装 LuaRocks 会导致 Lua 被升级为 Lua 5.3，所以我们建议通过源代码的方式安装 LuaRocks。如果你通过官方仓库安装 OpenResty 和 OpenResty 的 OpenSSL 开发库（rpm 版本：openresty-openssl111-devel，deb 版本：openresty-openssl111-dev），那么 [我们提供了自动安装的脚本](../../utils/linux-install-luarocks.sh)。如果你是自己编译的 OpenResty，可以参考上述脚本并修改里面的路径。如果编译时没有指定 OpenSSL 库的路径，那么无需配置 LuaRocks 内跟 OpenSSL 相关的变量，因为默认都是用的系统自带的 OpenSSL。如果编译时指定了 OpenSSL 库，那么需要保证 LuaRocks 的 OpenSSL 配置跟 OpenResty 的相一致。 +- 在某些平台上，通过包管理器安装 LuaRocks 会导致 Lua 被升级为 Lua 5.3，所以我们建议通过源代码的方式安装 LuaRocks。如果你通过官方仓库安装 OpenResty 和 OpenResty 的 OpenSSL 开发库（rpm 版本：openresty-openssl111-devel，deb 版本：openresty-openssl111-dev），那么 [我们提供了自动安装的脚本](https://github.com/apache/apisix/tree/master/utils/linux-install-luarocks.sh)。如果你是自己编译的 OpenResty，可以参考上述脚本并修改里面的路径。如果编译时没有指定 OpenSSL 库的路径，那么无需配置 LuaRocks 内跟 OpenSSL 相关的变量，因为默认都是用的系统自带的 OpenSSL。如果编译时指定了 OpenSSL 库，那么需要保证 LuaRocks 的 OpenSSL 配置跟 OpenResty 的相一致。 - 警告：如果你正在使用低于 `1.17.8` 的 OpenResty 版本，请安装 openresty-openssl-devel，而不是 openresty-openssl111-devel。 diff --git a/docs/zh/latest/plugin-develop.md b/docs/zh/latest/plugin-develop.md index 8f282703..3d6fc300 100644 --- a/docs/zh/latest/plugin-develop.md +++ b/docs/zh/latest/plugin-develop.md @@ -23,14 +23,18 @@ title: 插件开发 ## 目录 -- [**检查外部依赖**](#检查外部依赖) -- [**插件命名与配置**](#插件命名与配置) -- [**配置描述与校验**](#配置描述与校验) -- [**确定执行阶段**](#确定执行阶段) -- [**编写执行逻辑**](#编写执行逻辑) -- [**编写测试用例**](#编写测试用例) -- [**注册公共接口**](#注册公共接口) -- [**注册控制接口**](#注册控制接口) +- [目录](#目录) +- [检查外部依赖](#检查外部依赖) +- [插件命名与配置](#插件命名与配置) +- [配置描述与校验](#配置描述与校验) +- [确定执行阶段](#确定执行阶段) +- [编写执行逻辑](#编写执行逻辑) + - [conf 参数](#conf-参数) + - [ctx 参数](#ctx-参数) +- [编写测试用例](#编写测试用例) + - [附上 test-nginx 执行流程](#附上-test-nginx-执行流程) + - [注册公共接口](#注册公共接口) + - [注册控制接口](#注册控制接口) ## 检查外部依赖 @@ -54,8 +58,8 @@ title: 插件开发 插件本身提供了 init 方法。方便插件加载后做初始化动作。 注：如果部分插件的功能实现，需要在 Nginx 初始化启动，则可能需要在 __apisix/init.lua__ 文件的初始化方法 http_init 中添加逻辑，并且 - 可能需要在 __apisix/cli/ngx_tpl.lua__ 文件中，对 Nginx 配置文件生成的部分，添加一些你需要的处理。但是这样容易对全局产生影响，根据现有的 - 插件机制，我们不建议这样做，除非你已经对代码完全掌握。 +可能需要在 __apisix/cli/ngx_tpl.lua__ 文件中，对 Nginx 配置文件生成的部分，添加一些你需要的处理。但是这样容易对全局产生影响，根据现有的 +插件机制，我们不建议这样做，除非你已经对代码完全掌握。 ## 插件命名与配置 @@ -114,11 +118,11 @@ $(INSTALL) apisix/plugins/skywalking/*.lua $(INST_LUADIR)/apisix/plugins/skywalk ```json { - "example-plugin" : { - "i": 1, - "s": "s", - "t": [1] - } + "example-plugin": { + "i": 1, + "s": "s", + "t": [1] + } } ``` @@ -177,7 +181,7 @@ local _M = { 你可能之前见过 key-auth 这个插件在它的模块定义时设置了 `type = 'auth'`。 当一个插件设置 `type = 'auth'`，说明它是个认证插件。 -认证插件需要在执行后选择对应的consumer。举个例子，在 key-auth 插件中，它通过 `apikey` 请求头获取对应的 consumer，然后通过 `consumer.attach_consumer` 设置它。 +认证插件需要在执行后选择对应的 consumer。举个例子，在 key-auth 插件中，它通过 `apikey` 请求头获取对应的 consumer，然后通过 `consumer.attach_consumer` 设置它。 为了跟 `consumer` 资源一起使用，认证插件需要提供一个 `consumer_schema` 来检验 `consumer` 资源的 `plugins` 属性里面的配置。 @@ -185,18 +189,18 @@ local _M = { ```json { - "username": "Joe", - "plugins": { - "key-auth": { - "key": "Joe's key" - } + "username": "Joe", + "plugins": { + "key-auth": { + "key": "Joe's key" } + } } ``` 你在创建 [Consumer](https://github.com/apache/apisix/blob/master/docs/zh/latest/admin-api.md#consumer) 时会用到它。 -为了检验这个配置，这个插件使用了如下的schema: +为了检验这个配置，这个插件使用了如下的 schema: ```lua local consumer_schema = { @@ -278,11 +282,11 @@ conf: ```json { - "rejected_code":503, - "burst":0, - "default_conn_delay":0.1, - "conn":1, - "key":"remote_addr" + "rejected_code": 503, + "burst": 0, + "default_conn_delay": 0.1, + "conn": 1, + "key": "remote_addr" } ``` @@ -300,7 +304,7 @@ end ## 编写测试用例 针对功能，完善各种维度的测试用例，对插件做个全方位的测试吧！插件的测试用例，都在 __t/plugin__ 目录下，可以前去了解。 -项目测试框架采用的 [****test-nginx****](https://github.com/openresty/test-nginx) 。 +项目测试框架采用的 [****test-nginx****](https://github.com/openresty/test-nginx) 。 一个测试用例 __.t__ 文件，通常用 \__DATA\__ 分割成 序言部分 和 数据部分。这里我们简单介绍下数据部分， 也就是真正测试用例的部分，仍然以 key-auth 插件为例： @@ -328,7 +332,7 @@ done 一个测试用例主要有三部分内容： -- 程序代码： Nginx location 的配置内容 +- 程序代码： Nginx location 的配置内容 - 输入： http 的 request 信息 - 输出检查： status ，header ，body ，error_log 检查 @@ -336,7 +340,7 @@ done 用例的断言是 response_body 返回 "done"，__no_error_log__ 表示会对 Nginx 的 error.log 检查， 必须没有 ERROR 级别的记录。 -### 附上test-nginx 执行流程 +### 附上 test-nginx 执行流程 根据我们在 Makefile 里配置的 PATH，和每一个 __.t__ 文件最前面的一些配置项，框架会组装成一个完整的 nginx.conf 文件， __t/servroot__ 会被当成 Nginx 的工作目录，启动 Nginx 实例。根据测试用例提供的信息，发起 http 请求并检查 http 的返回项， @@ -367,7 +371,7 @@ end ### 注册控制接口 -如果你只想暴露 API 到 localhost 或内网，你可以通过 [Control API](../control-api.md) 来暴露它。 +如果你只想暴露 API 到 localhost 或内网，你可以通过 [Control API](../../en/latest/control-api.md) 来暴露它。 Take a look at example-plugin plugin: diff --git a/docs/zh/latest/plugins/batch-requests.md b/docs/zh/latest/plugins/batch-requests.md index aa42e30a..89dcfde3 100644 --- a/docs/zh/latest/plugins/batch-requests.md +++ b/docs/zh/latest/plugins/batch-requests.md @@ -23,18 +23,24 @@ title: batch-requests ## 目录 -- [**简介**](#简介) -- [**属性**](#属性) -- [**如何启用**](#如何启用) -- [**如何配置**](#如何配置) -- [**元数据**](#元数据) -- [**批量接口请求/响应**](#批量接口请求/响应) -- [**测试插件**](#测试插件) -- [**禁用插件**](#禁用插件) +- [目录](#目录) +- [简介](#简介) +- [属性](#属性) +- [接口](#接口) +- [如何启用](#如何启用) +- [如何配置](#如何配置) +- [元数据](#元数据) +- [批量接口请求/响应](#批量接口请求响应) + - [接口请求参数:](#接口请求参数) + - [HttpRequest](#httprequest) + - [接口响应参数：](#接口响应参数) + - [HttpResponse](#httpresponse) +- [测试插件](#测试插件) +- [禁用插件](#禁用插件) ## 简介 -`batch-requests` 插件可以一次接受多个请求并以 [http pipeline](https://en.wikipedia.org/wiki/HTTP_pipelining) 的方式在网关发起多个http请求，合并结果后再返回客户端，这在客户端需要访问多个接口时可以显著地提升请求性能。 +`batch-requests` 插件可以一次接受多个请求并以 [http pipeline](https://en.wikipedia.org/wiki/HTTP_pipelining) 的方式在网关发起多个 http 请求，合并结果后再返回客户端，这在客户端需要访问多个接口时可以显著地提升请求性能。 > **提示** > @@ -46,7 +52,7 @@ title: batch-requests ## 接口 -插件会增加 `/apisix/batch-requests` 这个接口，你可能需要通过 [interceptors](../../plugin-interceptors.md) +插件会增加 `/apisix/batch-requests` 这个接口，你可能需要通过 [interceptors](../plugin-interceptors.md) 来保护它。 ## 如何启用 @@ -66,9 +72,9 @@ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/batch-requests -H 'X-API ## 元数据 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ | -| max_body_size | integer | 必选 | 1048576 | > 0 | 请求体的最大大小，单位为字节。| +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +| ------------- | ------- | ------ | ------- | ------ | ------------------------------ | +| max_body_size | integer | 必选 | 1048576 | > 0 | 请求体的最大大小，单位为字节。 | ## 批量接口请求/响应 @@ -140,30 +146,30 @@ curl --location --request POST 'http://127.0.0.1:9080/apisix/batch-requests' \ ```json [ - { - "status": 200, - "reason": "OK", - "body": "{\"ret\":500,\"msg\":\"error\",\"game_info\":null,\"gift\":[],\"to_gets\":0,\"get_all_msg\":\"\"}", - "headers": { - "Connection": "keep-alive", - "Date": "Sat, 11 Apr 2020 17:53:20 GMT", - "Content-Type": "application/json", - "Content-Length": "81", - "Server": "APISIX web server" - } - }, - { - "status": 200, - "reason": "OK", - "body": "{\"ret\":500,\"msg\":\"error\",\"game_info\":null,\"gift\":[],\"to_gets\":0,\"get_all_msg\":\"\"}", - "headers": { - "Connection": "keep-alive", - "Date": "Sat, 11 Apr 2020 17:53:20 GMT", - "Content-Type": "application/json", - "Content-Length": "81", - "Server": "APISIX web server" - } + { + "status": 200, + "reason": "OK", + "body": "{\"ret\":500,\"msg\":\"error\",\"game_info\":null,\"gift\":[],\"to_gets\":0,\"get_all_msg\":\"\"}", + "headers": { + "Connection": "keep-alive", + "Date": "Sat, 11 Apr 2020 17:53:20 GMT", + "Content-Type": "application/json", + "Content-Length": "81", + "Server": "APISIX web server" } + }, + { + "status": 200, + "reason": "OK", + "body": "{\"ret\":500,\"msg\":\"error\",\"game_info\":null,\"gift\":[],\"to_gets\":0,\"get_all_msg\":\"\"}", + "headers": { + "Connection": "keep-alive", + "Date": "Sat, 11 Apr 2020 17:53:20 GMT", + "Content-Type": "application/json", + "Content-Length": "81", + "Server": "APISIX web server" + } + } ] ``` diff --git a/docs/zh/latest/plugins/hmac-auth.md b/docs/zh/latest/plugins/hmac-auth.md index 6f8a2295..3b3bbb18 100644 --- a/docs/zh/latest/plugins/hmac-auth.md +++ b/docs/zh/latest/plugins/hmac-auth.md @@ -23,12 +23,16 @@ title: hmac-auth ## 目录 - - [**名字**](#名字) - - [**属性**](#属性) - - [**如何启用**](#如何启用) - - [**测试插件**](#测试插件) - - [**禁用插件**](#禁用插件) - - [**签名生成示例**](#签名生成示例) +- [目录](#目录) +- [名字](#名字) +- [属性](#属性) +- [如何启用](#如何启用) +- [测试插件](#测试插件) + - [签名生成公式](#签名生成公式) + - [使用生成好的签名进行请求尝试](#使用生成好的签名进行请求尝试) +- [自定义 header 名称](#自定义-header-名称) +- [禁用插件](#禁用插件) +- [签名生成示例](#签名生成示例) ## 名字 @@ -38,15 +42,15 @@ title: hmac-auth ## 属性 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| -------------- | ------------- | ------ | ------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| access_key | string | 必须 | | | 不同的 `consumer` 对象应有不同的值，它应当是唯一的。不同 consumer 使用了相同的 `access_key` ，将会出现请求匹配异常。 | -| secret_key | string | 必须 | | | 与 `access_key` 配对使用。 | -| algorithm | string | 可选 | "hmac-sha256" | ["hmac-sha1", "hmac-sha256", "hmac-sha512"] | 加密算法。 | -| clock_skew | integer | 可选 | 0 | | 签名允许的时间偏移，以秒为单位的计时。比如允许时间偏移 10 秒钟，那么就应设置为 `10`。特别地，`0` 表示不对 `Date` 进行检查。 | -| signed_headers | array[string] | 可选 | | | 限制加入加密计算的 headers ，指定后客户端请求只能在此范围内指定 headers ，此项为空时将把所有客户端请求指定的 headers 加入加密计算。如： ["User-Agent", "Accept-Language", "x-custom-a"] | -| keep_headers | boolean | 可选 | false | [ true, false ] | 认证成功后的 http 请求中是否需要保留 `X-HMAC-SIGNATURE`、`X-HMAC-ALGORITHM` 和 `X-HMAC-SIGNED-HEADERS` 的请求头。true: 表示保留 http 请求头，false: 表示移除 http 请求头。 | -| encode_uri_param | boolean | 可选 | true | [ true, false ] | 是否对签名中的 uri 参数进行编码,例如: `params1=hello%2Cworld` 进行了编码，`params2=hello,world` 没有进行编码。true: 表示对签名中的 uri 参数进行编码，false: 不对签名中的 uri 参数编码。 | +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +| ---------------- | ------------- | ------ | ------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| access_key | string | 必须 | | | 不同的 `consumer` 对象应有不同的值，它应当是唯一的。不同 consumer 使用了相同的 `access_key` ，将会出现请求匹配异常。 | +| secret_key | string | 必须 | | | 与 `access_key` 配对使用。 | +| algorithm | string | 可选 | "hmac-sha256" | ["hmac-sha1", "hmac-sha256", "hmac-sha512"] | 加密算法。 | +| clock_skew | integer | 可选 | 0 | | 签名允许的时间偏移，以秒为单位的计时。比如允许时间偏移 10 秒钟，那么就应设置为 `10`。特别地，`0` 表示不对 `Date` 进行检查。 | +| signed_headers | array[string] | 可选 | | | 限制加入加密计算的 headers ，指定后客户端请求只能在此范围内指定 headers ，此项为空时将把所有客户端请求指定的 headers 加入加密计算。如： ["User-Agent", "Accept-Language", "x-custom-a"] | +| keep_headers | boolean | 可选 | false | [ true, false ] | 认证成功后的 http 请求中是否需要保留 `X-HMAC-SIGNATURE`、`X-HMAC-ALGORITHM` 和 `X-HMAC-SIGNED-HEADERS` 的请求头。true: 表示保留 http 请求头，false: 表示移除 http 请求头。 | +| encode_uri_param | boolean | 可选 | true | [ true, false ] | 是否对签名中的 uri 参数进行编码,例如: `params1=hello%2Cworld` 进行了编码，`params2=hello,world` 没有进行编码。true: 表示对签名中的 uri 参数进行编码，false: 不对签名中的 uri 参数编码。 | ## 如何启用 @@ -178,9 +182,9 @@ hash = hmac.new(secret, message, hashlib.sha256) print(base64.b64encode(hash.digest())) ``` -Type | Hash | -----------|----------------------------------------------| -SIGNATURE | 8XV1GB7Tq23OJcoz6wjqTs4ZLxr9DiLoY4PxzScWGYg= | +| Type | Hash | +| --------- | -------------------------------------------- | +| SIGNATURE | 8XV1GB7Tq23OJcoz6wjqTs4ZLxr9DiLoY4PxzScWGYg= | ### 使用生成好的签名进行请求尝试 @@ -220,7 +224,7 @@ Accept-Ranges: bytes ... ``` -* 签名信息分开分别放到请求头： +- 签名信息分开分别放到请求头： ```shell $ curl http://127.0.0.1:9080/index.html -H 'X-HMAC-SIGNATURE: base64_encode(SIGNATURE)' -H 'X-HMAC-ALGORITHM: ALGORITHM' -H 'Date: DATE' -H 'X-HMAC-ACCESS-KEY: ACCESS_KEY' -H 'X-HMAC-SIGNED-HEADERS: SIGNED_HEADERS' -i @@ -292,16 +296,16 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f 示例入参说明: -Variable | Value ----|--- -secret | this is secret key -message | this is signature string +| Variable | Value | +| -------- | ------------------------ | +| secret | this is secret key | +| message | this is signature string | 示例出参说明： -Type | Hash ----|--- -hexit | ad1b76c7e5054009380edca35d3f36cc5b6f45c82ee02ea3af64197ebddb9345 -base64 | rRt2x+UFQAk4DtyjXT82zFtvRcgu4C6jr2QZfr3bk0U= +| Type | Hash | +| ------ | ---------------------------------------------------------------- | +| hexit | ad1b76c7e5054009380edca35d3f36cc5b6f45c82ee02ea3af64197ebddb9345 | +| base64 | rRt2x+UFQAk4DtyjXT82zFtvRcgu4C6jr2QZfr3bk0U= | -具体代码请参考：[**HMAC Generate Signature Examples**](../../examples/plugins-hmac-auth-generate-signature.md) +具体代码请参考：[**HMAC Generate Signature Examples**](../examples/plugins-hmac-auth-generate-signature.md) diff --git a/docs/zh/latest/plugins/jwt-auth.md b/docs/zh/latest/plugins/jwt-auth.md index 0601afcf..176de680 100644 --- a/docs/zh/latest/plugins/jwt-auth.md +++ b/docs/zh/latest/plugins/jwt-auth.md @@ -39,19 +39,19 @@ title: jwt-auth ## 属性 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -|:--------------|:--------|:------|:--------|:----------------------------|:-----------------------------------------------------------------------------------------------| +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +| :------------ | :------ | :----- | :------ | :-------------------------- | :------------------------------------------------------------------------------------------------------------ | | key | string | 必须 | | | 不同的 `consumer` 对象应有不同的值，它应当是唯一的。不同 consumer 使用了相同的 `key` ，将会出现请求匹配异常。 | -| secret | string | 可选 | | | 加密秘钥。如果您未指定，后台将会自动帮您生成。 | -| public_key | string | 可选 | | | RSA公钥， `algorithm` 属性选择 `RS256` 算法时必填 | -| private_key | string | 可选 | | | RSA私钥， `algorithm` 属性选择 `RS256` 算法时必填 | -| algorithm | string | 可选 | "HS256" | ["HS256", "HS512", "RS256"] | 加密算法 | -| exp | integer | 可选 | 86400 | [1,...] | token 的超时时间 | -| base64_secret | boolean | 可选 | false | | 密钥是否为 base64 编码 | +| secret | string | 可选 | | | 加密秘钥。如果您未指定，后台将会自动帮您生成。 | +| public_key | string | 可选 | | | RSA 公钥， `algorithm` 属性选择 `RS256` 算法时必填 | +| private_key | string | 可选 | | | RSA 私钥， `algorithm` 属性选择 `RS256` 算法时必填 | +| algorithm | string | 可选 | "HS256" | ["HS256", "HS512", "RS256"] | 加密算法 | +| exp | integer | 可选 | 86400 | [1,...] | token 的超时时间 | +| base64_secret | boolean | 可选 | false | | 密钥是否为 base64 编码 | ## 接口 -插件会增加 `/apisix/plugin/jwt/sign` 这个接口，你可能需要通过 [interceptors](../../plugin-interceptors.md) +插件会增加 `/apisix/plugin/jwt/sign` 这个接口，你可能需要通过 [interceptors](../plugin-interceptors.md) 来保护它。 ## 如何启用 diff --git a/docs/zh/latest/plugins/limit-count.md b/docs/zh/latest/plugins/limit-count.md index 39db1f94..420471b3 100644 --- a/docs/zh/latest/plugins/limit-count.md +++ b/docs/zh/latest/plugins/limit-count.md @@ -23,15 +23,17 @@ title: limit-count ## 目录 +- [目录](#目录) - [简介](#简介) - [参数](#参数) - [如何使用](#如何使用) + - [开启插件](#开启插件) - [测试插件](#测试插件) - [移除插件](#移除插件) ## 简介 -和 [GitHub API 的限速](https://developer.github.com/v3/#rate-limiting)类似， +和 [GitHub API 的限速](https://docs.github.com/en/rest/reference/rate-limit)类似， 在指定的时间范围内，限制总的请求个数。并且在 HTTP 响应头中返回剩余可以请求的个数。 ## 参数 diff --git a/docs/zh/latest/plugins/openid-connect.md b/docs/zh/latest/plugins/openid-connect.md index f40c53d0..51092fa0 100644 --- a/docs/zh/latest/plugins/openid-connect.md +++ b/docs/zh/latest/plugins/openid-connect.md @@ -23,9 +23,12 @@ title: openid-connect ## 目录 -- [**定义**](#定义) -- [**属性列表**](#属性列表) -- [**令牌自省**](#令牌自省) +- [目录](#目录) +- [定义](#定义) +- [属性列表](#属性列表) + - [令牌自省](#令牌自省) + - [公钥自省](#公钥自省) +- [故障排除](#故障排除) ## 定义 @@ -131,4 +134,4 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13 ## 故障排除 -如果 APISIX 无法解析/连接到身份提供者，请检查/修改DNS设置（`conf / config.yaml`）。 +如果 APISIX 无法解析/连接到身份提供者，请检查/修改 DNS 设置（`conf / config.yaml`）。 diff --git a/docs/zh/latest/plugins/prometheus.md b/docs/zh/latest/plugins/prometheus.md index 7a88f9ac..cdd521d0 100644 --- a/docs/zh/latest/plugins/prometheus.md +++ b/docs/zh/latest/plugins/prometheus.md @@ -21,7 +21,7 @@ title: prometheus # --> -此插件是提供符合prometheus数据格式的监控指标数据。 +此插件是提供符合 prometheus 数据格式的监控指标数据。 ## 属性 @@ -29,7 +29,7 @@ title: prometheus ## 接口 -插件会增加 `/apisix/prometheus/metrics` 这个接口，你可能需要通过 [interceptors](../../plugin-interceptors.md) +插件会增加 `/apisix/prometheus/metrics` 这个接口，你可能需要通过 [interceptors](../plugin-interceptors.md) 来保护它。 ## 如何开启插件 @@ -70,16 +70,16 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13 curl -i http://127.0.0.1:9080/apisix/prometheus/metrics ``` -把该uri地址配置到 prometheus 中去,就会自动完成指标数据提取. +把该 uri 地址配置到 prometheus 中去,就会自动完成指标数据提取. 例子如下: ```yaml scrape_configs: - - job_name: 'apisix' - metrics_path: '/apisix/prometheus/metrics' + - job_name: "apisix" + metrics_path: "/apisix/prometheus/metrics" static_configs: - - targets: ['127.0.0.1:9080'] + - targets: ["127.0.0.1:9080"] ``` 我们也可以在 prometheus 控制台中去检查状态: @@ -88,13 +88,13 @@ scrape_configs: ![](../../../assets/images/plugin/prometheus02.png) -## 如何修改暴露指标的uri +## 如何修改暴露指标的 uri -我们可以在 `conf/config.yaml` 的 `plugin_attr` 修改默认的uri +我们可以在 `conf/config.yaml` 的 `plugin_attr` 修改默认的 uri -| 名称 | 类型 | 默认值 | 描述 | -| ---------- | ------ | ---------------------------- | ------------- | -| export_uri | string | "/apisix/prometheus/metrics" | 暴露指标的uri | +| 名称 | 类型 | 默认值 | 描述 | +| ---------- | ------ | ---------------------------- | -------------- | +| export_uri | string | "/apisix/prometheus/metrics" | 暴露指标的 uri | 配置示例: @@ -121,14 +121,14 @@ plugin_attr: ### 可有的指标 * `Status codes`: upstream 服务返回的 HTTP 状态码，每个服务返回状态码的次数或者所有服务的状态码次数总和都可以统计到。 -* `Bandwidth`: 流经apisix的总带宽(可分出口带宽和入口带宽). 每个服务指标或者是所有服务指标的总和都可以统计到。 -* `etcd reachability`: apisix 连接 etcd 的可用性，用 0 和 1来表示。 +* `Bandwidth`: 流经 apisix 的总带宽(可分出口带宽和入口带宽). 每个服务指标或者是所有服务指标的总和都可以统计到。 +* `etcd reachability`: apisix 连接 etcd 的可用性，用 0 和 1 来表示。 * `Connections`: 各种的 Nginx 连接指标，如 active（正处理的活动连接数），reading（nginx 读取到客户端的 Header 信息数），writing（nginx 返回给客户端的 Header 信息数），已建立的连接数。. * `Batch process entries`: 批处理未发送数据计数器，当你使用了批处理发送插件，比如：sys logger, http logger, sls logger, tcp logger, udp logger and zipkin, 那么你将会在此指标中看到批处理当前尚未发送的数据的数量。 * `Latency`: 每个服务的请求用时和 APISIX 处理耗时的直方图。 * `Info`: 当前 APISIX 节点信息。 -这里是apisix的原始的指标数据集: +这里是 apisix 的原始的指标数据集: ``` $ curl http://127.0.0.2:9080/apisix/prometheus/metrics diff --git a/docs/zh/latest/plugins/server-info.md b/docs/zh/latest/plugins/server-info.md index 2837dc54..2fbd9dcb 100644 --- a/docs/zh/latest/plugins/server-info.md +++ b/docs/zh/latest/plugins/server-info.md @@ -23,6 +23,7 @@ title: server-info ## 目录 +- [目录](#目录) - [插件简介](#插件简介) - [插件属性](#插件属性) - [插件接口](#插件接口) @@ -37,15 +38,15 @@ title: server-info 服务信息中每一项的含义如下： -| 名称 | 类型 | 描述 | -|---------|------|-------------| -| up_time | integer | APISIX 服务实例当前的运行时间（单位：秒）, 如果对 APISIX 进行热更新操作，该值将被重置；普通的 reload 操作不会影响该值。 | -| boot_time | integer | APISIX 服务实例的启动时间（UNIX 时间戳），如果对 APIISIX 进行热更新操作，该值将被重置；普通的 reload 操作不会影响该值。| -| last_report_time | integer | 最近一次服务信息上报的时间 （UNIX 时间戳）。| -| id | string | APISIX 服务实例 id 。| -| etcd_version | string | etcd 集群的版本信息，如果 APISIX 和 etcd 集群之间存在网络分区，该值将设置为 `"unknown"`。| -| version | string | APISIX 版本信息。 | -| hostname | string | APISIX 所部署的机器或 pod 的主机名信息。| +| 名称 | 类型 | 描述 | +| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- | +| up_time | integer | APISIX 服务实例当前的运行时间（单位：秒）, 如果对 APISIX 进行热更新操作，该值将被重置；普通的 reload 操作不会影响该值。 | +| boot_time | integer | APISIX 服务实例的启动时间（UNIX 时间戳），如果对 APIISIX 进行热更新操作，该值将被重置；普通的 reload 操作不会影响该值。 | +| last_report_time | integer | 最近一次服务信息上报的时间 （UNIX 时间戳）。 | +| id | string | APISIX 服务实例 id 。 | +| etcd_version | string | etcd 集群的版本信息，如果 APISIX 和 etcd 集群之间存在网络分区，该值将设置为 `"unknown"`。 | +| version | string | APISIX 版本信息。 | +| hostname | string | APISIX 所部署的机器或 pod 的主机名信息。 | ## 插件属性 @@ -53,7 +54,7 @@ title: server-info ## 插件接口 -该插件在 [Control API](../../control-api.md) 下暴露了一个 API 接口 `/v1/server_info`。 +该插件在 [Control API](../../../en/latest/control-api.md) 下暴露了一个 API 接口 `/v1/server_info`。 ## 启用插件 @@ -74,10 +75,10 @@ plugins: # plugin list 我们可以在 `conf/config.yaml` 文件的 `plugin_attr` 一节中修改上报配置。 -| 名称 | 类型 | 默认值 | 描述 | -| ------------ | ------ | -------- | -------------------------------------------------------------------- | -| report_interval | integer | 60 | 上报服务信息至 etcd 的间隔（单位：秒，最大值：3600，最小值：60）| -| report_ttl | integer | 7200 | etcd 中服务信息保存的 TTL（单位：秒，最大值：86400，最小值：3600）| +| 名称 | 类型 | 默认值 | 描述 | +| --------------- | ------- | ------ | ------------------------------------------------------------------ | +| report_interval | integer | 60 | 上报服务信息至 etcd 的间隔（单位：秒，最大值：3600，最小值：60） | +| report_ttl | integer | 7200 | etcd 中服务信息保存的 TTL（单位：秒，最大值：86400，最小值：3600） | 下面的例子将 `report_interval` 修改成了 10 分钟，并将 `report_ttl` 修改成了 1 小时： diff --git a/docs/zh/latest/plugins/udp-logger.md b/docs/zh/latest/plugins/udp-logger.md index c5c2863f..72b470f6 100644 --- a/docs/zh/latest/plugins/udp-logger.md +++ b/docs/zh/latest/plugins/udp-logger.md @@ -23,28 +23,29 @@ title: udp-logger ## 摘要 -- [**定义**](#定义) -- [**属性列表**](#属性列表) -- [**如何开启**](#如何开启) -- [**测试插件**](#测试插件) -- [**禁用插件**](#禁用插件) +- [摘要](#摘要) +- [定义](#定义) +- [属性列表](#属性列表) +- [如何开启](#如何开启) +- [测试插件](#测试插件) +- [禁用插件](#禁用插件) ## 定义 -`udp-logger` 是用于将日志数据发送到UDP服务的插件。 +`udp-logger` 是用于将日志数据发送到 UDP 服务的插件。 -以实现将日志数据以JSON格式发送到监控工具或其它UDP服务的能力。 +以实现将日志数据以 JSON 格式发送到监控工具或其它 UDP 服务的能力。 -此插件提供了将批处理数据批量推送到外部UDP服务器的功能。如果您没有收到日志数据，请放心一些时间，它会在我们的批处理处理器中的计时器功能到期后自动发送日志 +此插件提供了将批处理数据批量推送到外部 UDP 服务器的功能。如果您没有收到日志数据，请放心一些时间，它会在我们的批处理处理器中的计时器功能到期后自动发送日志 -有关Apache APISIX中Batch-Processor的更多信息，请参考。 -[Batch-Processor](../../batch-processor.md) +有关 Apache APISIX 中 Batch-Processor 的更多信息，请参考。 +[Batch-Processor](../batch-processor.md) ## 属性列表 | 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | ---------------- | ------- | ------ | ------------ | ------- | ------------------------------------------------ | -| host | string | 必须 | | | UDP 服务的IP地址或主机名 | +| host | string | 必须 | | | UDP 服务的 IP 地址或主机名 | | port | integer | 必须 | | [0,...] | 目标端口 | | timeout | integer | 可选 | 1000 | [1,...] | 发送数据超时间 | | name | string | 可选 | "udp logger" | | 用于识别批处理器 | @@ -91,7 +92,7 @@ hello, world ## 禁用插件 -想要禁用“udp-logger”插件，是非常简单的，将对应的插件配置从json配置删除，就会立即生效，不需要重新启动服务： +想要禁用“udp-logger”插件，是非常简单的，将对应的插件配置从 json 配置删除，就会立即生效，不需要重新启动服务： ```shell $ curl http://127.0.0.1:2379/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d value=' diff --git a/docs/zh/latest/plugins/wolf-rbac.md b/docs/zh/latest/plugins/wolf-rbac.md index 4ed258d3..a9c6ee5b 100644 --- a/docs/zh/latest/plugins/wolf-rbac.md +++ b/docs/zh/latest/plugins/wolf-rbac.md @@ -33,15 +33,15 @@ title: wolf-rbac ## 名字 `wolf-rbac` 是一个认证及授权(rbac)插件，它需要与 `consumer` 一起配合才能工作。同时需要添加 `wolf-rbac` 到一个 `service` 或 `route` 中。 -rbac功能由[wolf](https://github.com/iGeeky/wolf)提供, 有关 `wolf` 的更多信息, 请参考[wolf文档](https://github.com/iGeeky/wolf)。 +rbac 功能由[wolf](https://github.com/iGeeky/wolf)提供, 有关 `wolf` 的更多信息, 请参考[wolf 文档](https://github.com/iGeeky/wolf)。 ## 属性 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| ------------- | ------ | ------ | ------------------------ | ------ | ---------------------------------------------------------------- | -| server | string | 可选 | "http://127.0.0.1:10080" | | 设置 `wolf-server` 的访问地址 | -| appid | string | 可选 | "unset" | | 设置应用id, 该应用id, 需要是在 `wolf-console` 中已经添加的应用id | -| header_prefix | string | 可选 | "X-" | | 自定义http头的前缀。`wolf-rbac`在鉴权成功后, 会在请求头(用于传给后端)及响应头(用于传给前端)中添加3个头: `X-UserId`, `X-Username`, `X-Nickname` | +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +| ------------- | ------ | ------ | ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| server | string | 可选 | "http://127.0.0.1:10080" | | 设置 `wolf-server` 的访问地址 | +| appid | string | 可选 | "unset" | | 设置应用 id, 该应用 id, 需要是在 `wolf-console` 中已经添加的应用 id | +| header_prefix | string | 可选 | "X-" | | 自定义 http 头的前缀。`wolf-rbac`在鉴权成功后, 会在请求头(用于传给后端)及响应头(用于传给前端)中添加 3 个头: `X-UserId`, `X-Username`, `X-Nickname` | ## 接口 @@ -51,17 +51,17 @@ rbac功能由[wolf](https://github.com/iGeeky/wolf)提供, 有关 `wolf` 的更 * /apisix/plugin/wolf-rbac/change_pwd * /apisix/plugin/wolf-rbac/user_info -你可能需要通过 [interceptors](../../plugin-interceptors.md) 来保护它们。 +你可能需要通过 [interceptors](../plugin-interceptors.md) 来保护它们。 ## 依赖项 ### 安装 wolf, 并启动服务 -[Wolf快速起步](https://github.com/iGeeky/wolf/blob/master/quick-start-with-docker/README-CN.md) +[Wolf 快速起步](https://github.com/iGeeky/wolf/blob/master/quick-start-with-docker/README-CN.md) ### 添加应用, 管理员, 普通用户, 权限, 资源 及给用户授权. -[Wolf管理使用](https://github.com/iGeeky/wolf/blob/master/docs/usage.md) +[Wolf 管理使用](https://github.com/iGeeky/wolf/blob/master/docs/usage.md) ## 如何启用 @@ -87,7 +87,7 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f 然后在 consumer 页面中添加 wolf-rbac 插件： ![](../../../assets/images/plugin/wolf-rbac-2.png) -注意: 上面填写的 `appid` 需要在wolf控制台中已经存在的. +注意: 上面填写的 `appid` 需要在 wolf 控制台中已经存在的. 2. 创建 Route 或 Service 对象，并开启 `wolf-rbac` 插件。 @@ -112,9 +112,9 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1 #### 首先进行登录获取 `wolf-rbac` token: -下面的 `appid`, `username`, `password` 必须为wolf系统中真实存在的. +下面的 `appid`, `username`, `password` 必须为 wolf 系统中真实存在的. -* 以POST application/json方式登陆. +* 以 POST application/json 方式登陆. ```shell curl http://127.0.0.1:9080/apisix/plugin/wolf-rbac/login -i \ @@ -130,7 +130,7 @@ Server: APISIX web server {"rbac_token":"V1#restful#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts","user_info":{"nickname":"test","username":"test","id":"749"}} ``` -* 以POST x-www-form-urlencoded方式登陆 +* 以 POST x-www-form-urlencoded 方式登陆 ```shell curl http://127.0.0.1:9080/apisix/plugin/wolf-rbac/login -i \ @@ -236,7 +236,7 @@ HTTP/1.1 200 OK ## 禁用插件 -当你想去掉 `rbac-wolf` 插件的时候，很简单，在routes中的插件配置中把对应的 `插件` 配置删除即可，无须重启服务，即刻生效： +当你想去掉 `rbac-wolf` 插件的时候，很简单，在 routes 中的插件配置中把对应的 `插件` 配置删除即可，无须重启服务，即刻生效： ```shell curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' diff --git a/docs/zh/latest/stream-proxy.md b/docs/zh/latest/stream-proxy.md index 6fb0be17..35a02f53 100644 --- a/docs/zh/latest/stream-proxy.md +++ b/docs/zh/latest/stream-proxy.md @@ -21,21 +21,21 @@ title: TCP/UDP 动态代理 # --> -众多的闻名的应用和服务，像 LDAP、 MYSQL 和 RTMP ，选择 TCP 作为通信协议。 但是像 DNS、 syslog 和 RADIUS 这类非事务性的应用，他们选择了UDP协议。 +众多的闻名的应用和服务，像 LDAP、 MYSQL 和 RTMP ，选择 TCP 作为通信协议。 但是像 DNS、 syslog 和 RADIUS 这类非事务性的应用，他们选择了 UDP 协议。 APISIX 可以对 TCP/UDP 协议进行代理并实现动态负载均衡。 在 nginx 世界，称 TCP/UDP 代理为 stream 代理，在 APISIX 这里我们也遵循了这个声明. ## 如何开启 Stream 代理? -在 `conf/config.yaml` 配置文件设置 `stream_proxy` 选项， 指定一组需要进行动态代理的IP地址。默认情况不开启stream代理。 +在 `conf/config.yaml` 配置文件设置 `stream_proxy` 选项， 指定一组需要进行动态代理的 IP 地址。默认情况不开启 stream 代理。 ```yaml apisix: - stream_proxy: # TCP/UDP proxy - tcp: # TCP proxy address list + stream_proxy: # TCP/UDP proxy + tcp: # TCP proxy address list - 9100 - "127.0.0.1:9101" - udp: # UDP proxy address list + udp: # UDP proxy address list - 9200 - "127.0.0.1:9211" ``` @@ -57,8 +57,8 @@ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f03 }' ``` -例子中 APISIX 对客户端IP为 `127.0.0.1` 的请求代理转发到上游主机 `127.0.0.1:1995`。 -更多用例，请参照 [test case](../../t/stream-node/sanity.t). +例子中 APISIX 对客户端 IP 为 `127.0.0.1` 的请求代理转发到上游主机 `127.0.0.1:1995`。 +更多用例，请参照 [test case](../../../t/stream-node/sanity.t). ## 更多限制选项 diff --git a/docs/en/latest/powered-by.md b/powered-by.md similarity index 100% rename from docs/en/latest/powered-by.md rename to powered-by.md