You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2021/04/28 10:42:17 UTC
[GitHub] [apisix] juzhiyuan opened a new pull request #4155: docs: improve Auth plugins' documentation
juzhiyuan opened a new pull request #4155:
URL: https://github.com/apache/apisix/pull/4155
### What this PR does / why we need it:
This PR aims to improve auth plugins' documentation in Chinese.
- [x] key-auth
- [x] jwt-auth
- [x] basic-auth
### Pre-submission checklist:
* [x] Did you explain what problem does this PR solve? Or what new features have been added?
* [ ] Have you added corresponding test cases?
* [x] Have you modified the corresponding document?
* [x] Is this PR backward compatible? **If it is not backward compatible, please discuss on the [mailing list](https://github.com/apache/apisix/tree/master#community) first**
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-832613243
Each Plugin PR will have both Chinese & English changes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on a change in pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#discussion_r625469378
##########
File path: docs/zh/latest/plugins/basic-auth.md
##########
@@ -21,128 +21,154 @@ title: basic-auth
#
-->
-## 目录
+## 简介
-- [**名字**](#名字)
-- [**属性**](#属性)
-- [**如何启用**](#如何启用)
-- [**测试插件**](#测试插件)
-- [**禁用插件**](#禁用插件)
+启用该插件后，客户端访问路由、服务时需提供正确的用户名与密码，插件将从 HTTP 请求头 Authorization 中获取凭证信息。
-## 名字
+:::caution 注意
Review comment:
Those contents are used in the docs site, this syntax will be rendered as `Admonitions Box`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-831345303
@iamayushdas ok! Once this PR is merged without incorrect contents, then you could start doing it :)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-828988879
I see there have a wrong check 😳😳
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-830135151
I use `Control` according to MDN[1], does this mean they are different?
[1] https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] iamayushdas commented on pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
iamayushdas commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-831273389
> For docs in English, I would prefer submitting a new PR
okay i will be working on EN docs in next PR, will take help from @guoqqqi or @Yiyiyimu if i do wrong
while understanding chinese
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on a change in pull request #4155: docs: improve Auth plugins' documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#discussion_r622199359
##########
File path: docs/zh/latest/plugins/basic-auth.md
##########
@@ -21,128 +21,154 @@ title: basic-auth
#
-->
-## 目录
+## 简介
-- [**名字**](#名字)
-- [**属性**](#属性)
-- [**如何启用**](#如何启用)
-- [**测试插件**](#测试插件)
-- [**禁用插件**](#禁用插件)
+启用该插件后，客户端访问路由、服务时需提供正确的用户名与密码，插件将从 HTTP 请求头 Authorization 中获取凭证信息。
-## 名字
+:::caution 注意
Review comment:
https://docusaurus.io/docs/next/markdown-features/admonitions
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] Yiyiyimu commented on a change in pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
Yiyiyimu commented on a change in pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#discussion_r622830616
##########
File path: docs/zh/latest/plugins/key-auth.md
##########
@@ -21,129 +21,138 @@ title: key-auth
#
-->
-## 目录
+## 简介
-- [**名字**](#名字)
-- [**属性**](#属性)
-- [**如何启用**](#如何启用)
-- [**测试插件**](#测试插件)
-- [**禁用插件**](#禁用插件)
+启用该插件后，客户端访问路由、服务时需提供正确的密钥，插件将从 HTTP 请求头中获取凭证信息。
-## 名字
+:::caution 注意
+该插件需配合 Consumer 共同使用，为路由、服务增加该插件时，不需要进行配置。详情请见下方示例。
+:::
-`key-auth` 是一个认证插件，它需要与 `consumer` 一起配合才能工作。
+## 参数
-添加 Key Authentication 到一个 `service` 或 `route`。 然后，`consumer` 将其密钥添加到查询字符串参数或标头中以验证其请求。
+| 参数名 | 类型 | 必选 | 默认值 | 描述 |
+| :----: | :----: | :---: | :----: | :--------------------------------------------------------------------------------------------: |
+| key | 字符串 | 是 | | 消费者访问资源进行身份验证时，需使用的密钥。请注意，不同消费者配置该插件时，需使用不同的密钥。 |
-## 属性
+## 使用 AdminAPI 启用插件
-consumer 端配置：
+首先，创建消费者并配置 key-auth 插件（密钥为：auth-key）：
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---- | ------ | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------- |
-| key | string | 必需 | | | 不同的 `consumer` 对象应有不同的值，它应当是唯一的。不同 consumer 使用了相同的 `key` ，将会出现请求匹配异常。 |
-
-router 端配置：
-
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---- | ------ | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------- |
-| header | string | 可选| apikey | | 设置我们从哪个 header 获取 key。 |
-
-## 如何启用
-
-1. 创建一个 consumer 对象，并设置插件 `key-auth` 的值。
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "username": "jack",
- "plugins": {
- "key-auth": {
- "key": "auth-one"
- }
- }
-}'
-```
-
-你可以使用浏览器打开 dashboard：`http://127.0.0.1:9080/apisix/dashboard/`，通过 web 界面来完成上面的操作，先增加一个 consumer：
-
-
-然后在 consumer 页面中添加 key-auth 插件：
-
-
-2. 创建 route 或 service 对象，并开启 `key-auth` 插件。
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+```bash
+$ curl -X PUT http://127.0.0.1:9080/apisix/admin/consumers -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -d '
{
- "methods": ["GET"],
- "uri": "/index.html",
- "id": 1,
- "plugins": {
- "key-auth": {}
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "39.97.63.215:80": 1
- }
+ "username": "consumer_username",
+ "plugins": {
+ "key-auth": {
+ "key": "auth-key"
}
-}'
+ }
+}
+'
```
-如果不想从默认的 `apikey` header 获取 key，可以自定义 header：
+其次，创建路由并绑定 key-auth 插件（该插件无需进行配置）：
-```json
+```bash
+$ curl -X PUT http://127.0.0.1:9080/apisix/admin/routes/1 -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -d '
{
- "key-auth": {
- "header": "Authorization"
+ "methods": ["GET"],
+ "uri": "/get",
+ "plugins": {
+ "key-auth": {}
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
}
+ }
}
+'
```
-## 测试插件
+最后，我们访问路由进行测试：
-下面是一个正常通过 `key-auth` 验证的请求:
+```bash
+# 场景1：访问路由时，不携带密钥
-```shell
-$ curl http://127.0.0.2:9080/index.html -H 'apikey: auth-one' -i
-HTTP/1.1 200 OK
-...
-```
-
-如果当前请求没有正确设置 `apikey` ，将得到一个 `401` 的应答。
+## Request
+$ curl -i -X GET http://127.0.0.1:9080/get
-```shell
-$ curl http://127.0.0.2:9080/index.html -i
+## Response
HTTP/1.1 401 Unauthorized
-...
+Date: Wed, 28 Apr 2021 09:02:40 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.5
+
{"message":"Missing API key found in request"}
-$ curl http://127.0.0.2:9080/index.html -H 'apikey: abcabcabc' -i
+# 场景2：访问路由时，携带错误密钥
+
+## Request
+$ curl -i -X GET http://127.0.0.1:9080/get -H "apikey: wrong-key"
+
+## Response
HTTP/1.1 401 Unauthorized
-...
+Date: Wed, 28 Apr 2021 09:03:40 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.5
+
{"message":"Invalid API key in request"}
+
+# 场景3：访问路由时，携带正确密钥（在 HTTP 请求头中）
+
+## Request
+$ curl -i -X GET http://127.0.0.1:9080/get -H "apikey: auth-key"
+
+## Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+Content-Length: 325
+Connection: keep-alive
+Date: Wed, 28 Apr 2021 09:03:53 GMT
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Credentials: true
+Server: APISIX/2.5
+
+{
+ "args": {},
+ "headers": {
+ "Accept": "*/*",
+ "Apikey": "auth-key",
+ "Host": "127.0.0.1",
+ "User-Agent": "curl/7.29.0",
+ "X-Amzn-Trace-Id": "Root=1-608924f9-4a20a14821ce0ae97337e9f8",
+ "X-Forwarded-Host": "127.0.0.1"
+ },
+ "origin": "127.0.0.1, 8.210.41.192",
+ "url": "http://127.0.0.1/get"
+}
```
-## 禁用插件
+## 使用 AdminAPI 禁用插件
-当你想去掉 `key-auth` 插件的时候，很简单，在插件的配置中把对应的 `json` 配置删除即可，无须重启服务，即刻生效：
+如果希望禁用插件，只需更新路由配置，从 plugins 字段移除该插件即可：
-```shell
-$ curl http://127.0.0.1:2379/v2/keys/apisix/routes/1 -X PUT -d value='
+```bash
+$ curl -X PUT http://127.0.0.1:9080/apisix/admin/routes/1 -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -d '
{
- "methods": ["GET"],
- "uri": "/index.html",
- "id": 1,
- "plugins": {
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "39.97.63.215:80": 1
- }
+ "methods": ["GET"],
+ "uri": "/get",
+ "plugins": {
+ "key-auth": {}
Review comment:
need to remove it from plugin list 🤣
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on a change in pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#discussion_r622781292
##########
File path: docs/zh/latest/plugins/key-auth.md
##########
@@ -21,129 +21,138 @@ title: key-auth
#
-->
-## 目录
+## 简介
-- [**名字**](#名字)
-- [**属性**](#属性)
-- [**如何启用**](#如何启用)
-- [**测试插件**](#测试插件)
-- [**禁用插件**](#禁用插件)
+启用该插件后，客户端访问路由、服务时需提供正确的密钥，插件将从 HTTP 请求头中获取凭证信息。
-## 名字
+:::caution 注意
+该插件需配合 Consumer 共同使用，为路由、服务增加该插件时，不需要进行配置。详情请见下方示例。
+:::
-`key-auth` 是一个认证插件，它需要与 `consumer` 一起配合才能工作。
+## 参数
-添加 Key Authentication 到一个 `service` 或 `route`。 然后，`consumer` 将其密钥添加到查询字符串参数或标头中以验证其请求。
+| 参数名 | 类型 | 必选 | 默认值 | 描述 |
+| :----: | :----: | :---: | :----: | :--------------------------------------------------------------------------------------------: |
+| key | 字符串 | 是 | | 消费者访问资源进行身份验证时，需使用的密钥。请注意，不同消费者配置该插件时，需使用不同的密钥。 |
-## 属性
+## 使用 AdminAPI 启用插件
-consumer 端配置：
+首先，创建消费者并配置 key-auth 插件（密钥为：auth-key）：
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---- | ------ | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------- |
-| key | string | 必需 | | | 不同的 `consumer` 对象应有不同的值，它应当是唯一的。不同 consumer 使用了相同的 `key` ，将会出现请求匹配异常。 |
-
-router 端配置：
-
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---- | ------ | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------- |
-| header | string | 可选| apikey | | 设置我们从哪个 header 获取 key。 |
-
-## 如何启用
-
-1. 创建一个 consumer 对象，并设置插件 `key-auth` 的值。
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "username": "jack",
- "plugins": {
- "key-auth": {
- "key": "auth-one"
- }
- }
-}'
-```
-
-你可以使用浏览器打开 dashboard：`http://127.0.0.1:9080/apisix/dashboard/`，通过 web 界面来完成上面的操作，先增加一个 consumer：
-
-
-然后在 consumer 页面中添加 key-auth 插件：
-
-
-2. 创建 route 或 service 对象，并开启 `key-auth` 插件。
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+```bash
+$ curl -X PUT http://127.0.0.1:9080/apisix/admin/consumers -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -d '
{
- "methods": ["GET"],
- "uri": "/index.html",
- "id": 1,
- "plugins": {
- "key-auth": {}
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "39.97.63.215:80": 1
- }
+ "username": "consumer_username",
+ "plugins": {
+ "key-auth": {
+ "key": "auth-key"
}
-}'
+ }
+}
+'
```
-如果不想从默认的 `apikey` header 获取 key，可以自定义 header：
+其次，创建路由并绑定 key-auth 插件（该插件无需进行配置）：
-```json
+```bash
+$ curl -X PUT http://127.0.0.1:9080/apisix/admin/routes/1 -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -d '
{
- "key-auth": {
- "header": "Authorization"
+ "methods": ["GET"],
+ "uri": "/get",
+ "plugins": {
+ "key-auth": {}
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
}
+ }
}
+'
```
-## 测试插件
+最后，我们访问路由进行测试：
-下面是一个正常通过 `key-auth` 验证的请求:
+```bash
+# 场景1：访问路由时，不携带密钥
-```shell
-$ curl http://127.0.0.2:9080/index.html -H 'apikey: auth-one' -i
-HTTP/1.1 200 OK
-...
-```
-
-如果当前请求没有正确设置 `apikey` ，将得到一个 `401` 的应答。
+## Request
+$ curl -i -X GET http://127.0.0.1:9080/get
-```shell
-$ curl http://127.0.0.2:9080/index.html -i
+## Response
HTTP/1.1 401 Unauthorized
-...
+Date: Wed, 28 Apr 2021 09:02:40 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.5
+
{"message":"Missing API key found in request"}
-$ curl http://127.0.0.2:9080/index.html -H 'apikey: abcabcabc' -i
+# 场景2：访问路由时，携带错误密钥
+
+## Request
+$ curl -i -X GET http://127.0.0.1:9080/get -H "apikey: wrong-key"
+
+## Response
HTTP/1.1 401 Unauthorized
-...
+Date: Wed, 28 Apr 2021 09:03:40 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.5
+
{"message":"Invalid API key in request"}
+
+# 场景3：访问路由时，携带正确密钥（在 HTTP 请求头中）
+
+## Request
+$ curl -i -X GET http://127.0.0.1:9080/get -H "apikey: auth-key"
+
+## Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+Content-Length: 325
+Connection: keep-alive
+Date: Wed, 28 Apr 2021 09:03:53 GMT
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Credentials: true
+Server: APISIX/2.5
+
+{
+ "args": {},
+ "headers": {
+ "Accept": "*/*",
+ "Apikey": "auth-key",
+ "Host": "127.0.0.1",
+ "User-Agent": "curl/7.29.0",
+ "X-Amzn-Trace-Id": "Root=1-608924f9-4a20a14821ce0ae97337e9f8",
+ "X-Forwarded-Host": "127.0.0.1"
+ },
+ "origin": "127.0.0.1, 8.210.41.192",
+ "url": "http://127.0.0.1/get"
+}
```
-## 禁用插件
+## 使用 AdminAPI 禁用插件
-当你想去掉 `key-auth` 插件的时候，很简单，在插件的配置中把对应的 `json` 配置删除即可，无须重启服务，即刻生效：
+如果希望禁用插件，只需更新路由配置，从 plugins 字段移除该插件即可：
-```shell
-$ curl http://127.0.0.1:2379/v2/keys/apisix/routes/1 -X PUT -d value='
+```bash
+$ curl -X PUT http://127.0.0.1:9080/apisix/admin/routes/1 -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -d '
{
- "methods": ["GET"],
- "uri": "/index.html",
- "id": 1,
- "plugins": {
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "39.97.63.215:80": 1
- }
+ "methods": ["GET"],
+ "uri": "/get",
+ "plugins": {
+ "key-auth": {}
Review comment:
typo?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan edited a comment on pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
juzhiyuan edited a comment on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-831629657
@iamayushdas, after discussing with @Yiyiyimu, I agree with him, this is more challenge for a non-CN speaker, you could pick other issues like `Web Test` or `Featrures` or `bugfix` issues.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] spacewander commented on pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
spacewander commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-830645502
I mean you should change `Access-Controll-Max-Age` to `Access-Control-Max-Age`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-831641900
> Please fix English doc first
@moonming Please review Chinese docs first.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] Yiyiyimu commented on a change in pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
Yiyiyimu commented on a change in pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#discussion_r622831829
##########
File path: docs/zh/latest/plugins/limit-conn.md
##########
@@ -21,62 +21,62 @@ title: limit-conn
#
-->
-限制并发请求（或并发连接）插件。
+## 简介
-### 属性
+启用该插件后，网关将根据预设参数限制该路由并发请求数量。
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ------------------ | ------- | -------- | ------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| conn | integer | required | | conn > 0 | 允许的最大并发请求数。超过 `conn` 的限制、但是低于 `conn` + `burst` 的请求，将被延迟处理。 |
-| burst | integer | required | | burst >= 0 | 允许被延迟处理的并发请求数。 |
-| default_conn_delay | number | required | | default_conn_delay > 0 | 默认的典型连接(或请求)的处理延迟时间。 |
-| key | object | required | | ["remote_addr", "server_addr", "http_x_real_ip", "http_x_forwarded_for", "consumer_name"] | 用户指定的限制并发级别的关键字，可以是客户端 IP 或服务端 IP。<br />例如，可以使用主机名（或服务器区域）作为关键字，以便限制每个主机名的并发性。 否则，我们也可以使用客户端地址作为关键字，这样我们就可以避免单个客户端用太多的并行连接或请求淹没我们的服务。 <br />当前接受的 key 有："remote_addr"（客户端 IP 地址）, "server_addr"（服务端 IP 地址）, 请求头中的"X-Forwarded-For" 或 "X-Real-IP", "consumer_name"（consumer 的 username）。 |
-| rejected_code | string | optional | 503 | [200,...,599] | 当请求超过 `conn` + `burst` 这个阈值时，返回的 HTTP 状态码 |
+## 参数
-**注：key 是可以被用户自定义的，只需要修改插件的一行代码即可完成。并没有在插件中放开是处于安全的考虑。**
Review comment:
Yeah so it might be better to move it to FAQ in this PR or I guess we'll forget about it 🤣
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] Yiyiyimu commented on a change in pull request #4155: docs: improve Auth plugins' documentation
Posted by GitBox <gi...@apache.org>.
Yiyiyimu commented on a change in pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#discussion_r622678605
##########
File path: docs/zh/latest/plugins/key-auth.md
##########
@@ -21,129 +21,138 @@ title: key-auth
#
-->
-## 目录
+## 简介
-- [**名字**](#名字)
-- [**属性**](#属性)
-- [**如何启用**](#如何启用)
-- [**测试插件**](#测试插件)
-- [**禁用插件**](#禁用插件)
+启用该插件后，客户端访问路由、服务时需提供正确的密钥，插件将从 HTTP 请求头中获取凭证信息。
-## 名字
+:::caution 注意
+该插件需配合 Consumer 共同使用，为路由、服务增加该插件时，不需要进行配置。详情请见下方示例。
+:::
-`key-auth` 是一个认证插件，它需要与 `consumer` 一起配合才能工作。
+## 参数
-添加 Key Authentication 到一个 `service` 或 `route`。 然后，`consumer` 将其密钥添加到查询字符串参数或标头中以验证其请求。
+| 参数名 | 类型 | 必选 | 默认值 | 描述 |
+| :----: | :----: | :---: | :----: | :--------------------------------------------------------------------------------------------: |
+| key | 字符串 | 是 | | 消费者访问资源进行身份验证时，需使用的密钥。请注意，不同消费者配置该插件时，需使用不同的密钥。 |
-## 属性
+## 使用 AdminAPI 启用插件
-consumer 端配置：
+首先，创建消费者并配置 key-auth 插件（密钥为：auth-key）：
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---- | ------ | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------- |
-| key | string | 必需 | | | 不同的 `consumer` 对象应有不同的值，它应当是唯一的。不同 consumer 使用了相同的 `key` ，将会出现请求匹配异常。 |
-
-router 端配置：
-
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---- | ------ | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------- |
-| header | string | 可选| apikey | | 设置我们从哪个 header 获取 key。 |
-
-## 如何启用
-
-1. 创建一个 consumer 对象，并设置插件 `key-auth` 的值。
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "username": "jack",
- "plugins": {
- "key-auth": {
- "key": "auth-one"
- }
- }
-}'
-```
-
-你可以使用浏览器打开 dashboard：`http://127.0.0.1:9080/apisix/dashboard/`，通过 web 界面来完成上面的操作，先增加一个 consumer：
-
-
-然后在 consumer 页面中添加 key-auth 插件：
-
-
-2. 创建 route 或 service 对象，并开启 `key-auth` 插件。
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+```bash
+$ curl -X PUT http://127.0.0.1:9080/apisix/admin/consumers -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -d '
{
- "methods": ["GET"],
- "uri": "/index.html",
- "id": 1,
- "plugins": {
- "key-auth": {}
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "39.97.63.215:80": 1
- }
+ "username": "consumer_username",
+ "plugins": {
+ "key-auth": {
+ "key": "auth-key"
}
-}'
+ }
+}
+'
```
-如果不想从默认的 `apikey` header 获取 key，可以自定义 header：
+其次，创建路由并绑定 key-auth 插件（该插件无需进行配置）：
-```json
+```bash
+$ curl -X PUT http://127.0.0.1:9080/apisix/admin/routes/1 -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -d '
{
- "key-auth": {
- "header": "Authorization"
+ "methods": ["GET"],
+ "uri": "/get",
+ "plugins": {
+ "key-auth": {}
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
}
+ }
}
+'
```
-## 测试插件
+最后，我们访问路由进行测试：
-下面是一个正常通过 `key-auth` 验证的请求:
+```bash
+# 场景1：访问路由时，不携带密钥
-```shell
-$ curl http://127.0.0.2:9080/index.html -H 'apikey: auth-one' -i
-HTTP/1.1 200 OK
-...
-```
-
-如果当前请求没有正确设置 `apikey` ，将得到一个 `401` 的应答。
+## Request
+$ curl -i -X GET http://127.0.0.1:9080/get
-```shell
-$ curl http://127.0.0.2:9080/index.html -i
+## Response
HTTP/1.1 401 Unauthorized
-...
+Date: Wed, 28 Apr 2021 09:02:40 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.5
+
{"message":"Missing API key found in request"}
-$ curl http://127.0.0.2:9080/index.html -H 'apikey: abcabcabc' -i
+# 场景2：访问路由时，携带错误密钥
+
+## Request
+$ curl -i -X GET http://127.0.0.1:9080/get -H "apikey: wrong-key"
+
+## Response
HTTP/1.1 401 Unauthorized
-...
+Date: Wed, 28 Apr 2021 09:03:40 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.5
+
{"message":"Invalid API key in request"}
+
+# 场景3：访问路由时，携带正确密钥（在 HTTP 请求头中）
+
+## Request
+$ curl -i -X GET http://127.0.0.1:9080/get -H "apikey: auth-key"
+
+## Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+Content-Length: 325
+Connection: keep-alive
+Date: Wed, 28 Apr 2021 09:03:53 GMT
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Credentials: true
+Server: APISIX/2.5
+
+{
+ "args": {},
+ "headers": {
+ "Accept": "*/*",
+ "Apikey": "auth-key",
+ "Host": "127.0.0.1",
+ "User-Agent": "curl/7.29.0",
+ "X-Amzn-Trace-Id": "Root=1-608924f9-4a20a14821ce0ae97337e9f8",
+ "X-Forwarded-Host": "127.0.0.1"
+ },
+ "origin": "127.0.0.1, 8.210.41.192",
+ "url": "http://127.0.0.1/get"
+}
```
-## 禁用插件
+## 使用 AdminAPI 禁用插件
-当你想去掉 `key-auth` 插件的时候，很简单，在插件的配置中把对应的 `json` 配置删除即可，无须重启服务，即刻生效：
+如果希望禁用插件，只需更新路由配置，从 plugins 字段移除该插件即可：
-```shell
-$ curl http://127.0.0.1:2379/v2/keys/apisix/routes/1 -X PUT -d value='
+```bash
+$ curl -X PUT http://127.0.0.1:9080/apisix/admin/routes/1 -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -d '
{
- "methods": ["GET"],
- "uri": "/index.html",
- "id": 1,
- "plugins": {
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "39.97.63.215:80": 1
- }
+ "methods": ["GET"],
+ "uri": "/get",
+ "plugins": {
+ "key-auth": {}
Review comment:
typo here
##########
File path: docs/zh/latest/plugins/limit-conn.md
##########
@@ -21,62 +21,62 @@ title: limit-conn
#
-->
-限制并发请求（或并发连接）插件。
+## 简介
-### 属性
+启用该插件后，网关将根据预设参数限制该路由并发请求数量。
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ------------------ | ------- | -------- | ------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| conn | integer | required | | conn > 0 | 允许的最大并发请求数。超过 `conn` 的限制、但是低于 `conn` + `burst` 的请求，将被延迟处理。 |
-| burst | integer | required | | burst >= 0 | 允许被延迟处理的并发请求数。 |
-| default_conn_delay | number | required | | default_conn_delay > 0 | 默认的典型连接(或请求)的处理延迟时间。 |
-| key | object | required | | ["remote_addr", "server_addr", "http_x_real_ip", "http_x_forwarded_for", "consumer_name"] | 用户指定的限制并发级别的关键字，可以是客户端 IP 或服务端 IP。<br />例如，可以使用主机名（或服务器区域）作为关键字，以便限制每个主机名的并发性。 否则，我们也可以使用客户端地址作为关键字，这样我们就可以避免单个客户端用太多的并行连接或请求淹没我们的服务。 <br />当前接受的 key 有："remote_addr"（客户端 IP 地址）, "server_addr"（服务端 IP 地址）, 请求头中的"X-Forwarded-For" 或 "X-Real-IP", "consumer_name"（consumer 的 username）。 |
-| rejected_code | string | optional | 503 | [200,...,599] | 当请求超过 `conn` + `burst` 这个阈值时，返回的 HTTP 状态码 |
+## 参数
-**注：key 是可以被用户自定义的，只需要修改插件的一行代码即可完成。并没有在插件中放开是处于安全的考虑。**
Review comment:
Is there any reason to remove this line?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-831648865
After reviewing Chinese versions, I will submit PRs to update EN.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-831085744
> I mean you should change `Access-Controll-Max-Age` to `Access-Control-Max-Age`
Done
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] spacewander commented on a change in pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
spacewander commented on a change in pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#discussion_r625459642
##########
File path: docs/zh/latest/plugins/api-breaker.md
##########
@@ -21,98 +21,69 @@ title: api-breaker
#
-->
-## 目录
+## 简介
-- [**定义**](#定义)
-- [**属性列表**](#属性列表)
-- [**启用方式**](#启用方式)
-- [**测试插件**](#测试插件)
-- [**禁用插件**](#禁用插件)
+启用该插件后，网关将根据配置判断上游是否异常，若异常，则直接返回预设的错误码，且在一定时间内不再访问上游。
-## 定义
+## 参数
-该插件实现 API 熔断功能，帮助我们保护上游业务服务。
+| 参数名称 | 类型 | 必选 | 默认值 | 使用范围 | 描述 |
+| :---------------------: | :--------: | :---: | :----: | :-------: | :--------------------------------------------------------------------------------: |
+| break_response_code | 整数型 | 是 | | 200 ~ 599 | 上游不健康时，将返回该状态码。 |
Review comment:
The indentation should be left alignment. The center alignment can't be maintained by humans. Please fix all the similar places.
##########
File path: docs/zh/latest/plugins/basic-auth.md
##########
@@ -21,128 +21,154 @@ title: basic-auth
#
-->
-## 目录
+## 简介
-- [**名字**](#名字)
-- [**属性**](#属性)
-- [**如何启用**](#如何启用)
-- [**测试插件**](#测试插件)
-- [**禁用插件**](#禁用插件)
+启用该插件后，客户端访问路由、服务时需提供正确的用户名与密码，插件将从 HTTP 请求头 Authorization 中获取凭证信息。
-## 名字
+:::caution 注意
Review comment:
Is it necessary to use docusaurus special syntax? Why not use `****` directly?
##########
File path: docs/zh/latest/plugins/cors.md
##########
@@ -21,85 +21,99 @@ title: cors
#
-->
-## 目录
-
-- [**简介**](#简介)
-- [**属性**](#属性)
-- [**如何启用**](#如何启用)
-- [**测试插件**](#测试插件)
-- [**禁用插件**](#禁用插件)
-
## 简介
-`cors` 插件可以让你为服务端启用 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) 的返回头。
+启用该插件后，网关将针对路由根据预设参数设置 CORS 规则，以便消费者在浏览器中发起请求。
-## 属性
+## 术语
-| 名称 | 类型 | 可选项 | 默认值 | 有效值 | 描述 |
-| ---------------- | ------- | ------ | ------ | ------ | ------------------------------------------------------------ |
-| allow_origins | string | 可选 | "*" | | 允许跨域访问的 Origin，格式如：`scheme`://`host`:`port`，比如: https://somehost.com:8081 。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Origin 都通过，但请注意这样存在安全隐患。 |
-| allow_methods | string | 可选 | "*" | | 允许跨域访问的 Method，比如: `GET`，`POST`等。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Method 都通过，但请注意这样存在安全隐患。 |
-| allow_headers | string | 可选 | "*" | | 允许跨域访问时请求方携带哪些非 `CORS规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所 有 Header 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Method 都通过，但请注意这样存在安全隐患。 |
-| expose_headers | string | 可选 | "*" | | 允许跨域访问时响应方携带哪些非 `CORS规范` 以外的 Header， 多个值使用 `,` 分割。 |
-| max_age | integer | 可选 | 5 | | 浏览器缓存 CORS 结果的最大时间，单位为秒，在这个时间范围内浏览器会复用上一次的检查结果，`-1` 表示不缓存。请注意各个浏览器允许的的最大时间不同，详情请参考 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#Directives)。 |
-| allow_credential | boolean | 可选 | false | | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。根据 CORS 规范，如果设置该选项为 `true`，那么将不能在其他选项中使用 `*`。 |
-| allow_origins_by_regex | array | 可选 | nil | | 使用正则表达式数组来匹配允许跨域访问的 Origin, 如[".*\.test.com"] 可以匹配任何test.com的子域名`*`。 |
+- Origin：请求首部字段 Origin 指示了请求来自于哪个站点。该字段仅指示服务器名称，并不包含任何路径信息。该首部用于 CORS 请求或者 POST 请求。除了不包含路径信息，该字段与 Referer 首部字段相似。
-> **提示**
->
-> 请注意 `allow_credential` 是一个很敏感的选项，谨慎选择开启。开启之后，其他参数默认的 `*` 将失效，你必须显式指定它们的值。
-> 使用 `**` 时要充分理解它引入了一些安全隐患，比如 CSRF，所以确保这样的安全等级符合自己预期再使用。
+## 参数
-## 如何启用
+| 参数名 | 类型 | 必选 | 默认值 | 描述 |
+| :--------------------: | :--------: | :---: | :----: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+| allow_origins | 字符串 | 否 | * | `Access-Control-Allow-Origin` 请求头表示允许跨域的 Origin 白名单，格式：`协议://主机名:端口号`。当有多个值时，使用 `,` 分隔。当 `allow_credential = false` 时，可以使用 `*` 以允许任意 Origin；当 `allow_credential = true` 时，可以使用 `**` 强制允许任意 Origin，但这会产生安全问题，不推荐使用。 |
+| allow_methods | 字符串 | 否 | * | `Access-Control-Allow-Methods` 请求头表示允许跨域的 HTTP 方法白名单，例如：`GET/POST/PUT` 等 。当有多个值时，使用 `,` 分隔。当 `allow_credential = false` 时，可以使用 `*` 以允许任意 HTTP 方法；当 `allow_credential = true` 时，可以使用 `**` 强制允许任意 HTTP 方法，但这会产生安全问题，不推荐使用。 |
+| allow_headers | 字符串 | 否 | * | `Access-Control-Allow-Headers` 请求头表示当访问跨域资源时，允许消费者携带哪些非 CORS 规范以外的 HTTP 请求头。当有多个值时，使用 `,` 分隔。当 `allow_credential = false` 时，可以使用 `*` 以允许任意 HTTP 请求头；当 `allow_credential = true` 时，可以使用 `**` 强制允许任意 HTTP 请求头，但这会产生安全问题，不推荐使用。 |
+| expose_headers | 字符串 | 否 | * | `Access-Control-Expose-Headers` 响应头表示当访问跨域资源时，允许响应方返回哪些 HTTP 请求头。有多个值时，使用 `,` 分隔。 |
+| max_age | 整数型 | 否 | 5 | `Access-Control-Max-Age` 响应头表示 `preflight request` 预检请求的返回结果（即 Access-Control-Allow-Methods 与 Access-Control-Allow-Headers 提供的信息）可以被缓存多久。单位为秒，在该时间范围内浏览器将复用上一次的检查结果，`-1` 表示不缓存。注意：不同浏览器允许的最大时间不同，具体请见 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Access-Control-Max-Age)。 |
+| allow_credential | 布尔值 | 否 | false | `Access-Control-Allow-Credentials` 响应头表示是否可以将对请求的响应暴露给前端 JS，只有 `allow_credential = true` 才可以，此时其它选项不可以为 `*`。 |
+| allow_origins_by_regex | 字符串数组 | 否 | nil | 使用正则表达式数组以匹配允许跨域访问的 Origin，如 `["*.test.com"]` 可以匹配 `test.com` 的子域名 `*`。 |
-创建 `Route` 或 `Service` 对象，并配置 `cors` 插件。
+## 使用 AdminAPI 启用插件
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+首先，创建路由并绑定该插件，以下示例使用了 `cors` 插件的默认配置，即允许任意 Origin 访问。
+
+```bash
+$ curl -X PUT http://127.0.0.1:9080/apisix/admin/routes/1 -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -d '
{
- "uri": "/hello",
- "plugins": {
- "cors": {}
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:8080": 1
- }
+ "methods": ["GET"],
+ "uri": "/get",
+ "plugins": {
+ "cors": {}
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
}
-}'
+ }
+}
+'
```
-## 测试插件
+接着，访问路由进行测试：
+
+```bash
+# 场景1：在未启用 CORS 插件时，访问资源：
+
+## Request
+$ curl -i http://127.0.0.1:9080/get -v
Review comment:
Would be better if we can provide a refined example without `-v`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-831641725
> Is it necessary to use docusaurus special syntax? Why not use **** directly?
Those contents are used in the docs site, this syntax will be rendered as `Admonitions Box`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan closed pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
juzhiyuan closed pull request #4155:
URL: https://github.com/apache/apisix/pull/4155
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-831087183
For docs in English, I would prefer submitting a new PR ✌️
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on a change in pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#discussion_r623922741
##########
File path: docs/zh/latest/plugins/key-auth.md
##########
@@ -21,129 +21,138 @@ title: key-auth
#
-->
-## 目录
+## 简介
-- [**名字**](#名字)
-- [**属性**](#属性)
-- [**如何启用**](#如何启用)
-- [**测试插件**](#测试插件)
-- [**禁用插件**](#禁用插件)
+启用该插件后，客户端访问路由、服务时需提供正确的密钥，插件将从 HTTP 请求头中获取凭证信息。
-## 名字
+:::caution 注意
+该插件需配合 Consumer 共同使用，为路由、服务增加该插件时，不需要进行配置。详情请见下方示例。
+:::
-`key-auth` 是一个认证插件，它需要与 `consumer` 一起配合才能工作。
+## 参数
-添加 Key Authentication 到一个 `service` 或 `route`。 然后，`consumer` 将其密钥添加到查询字符串参数或标头中以验证其请求。
+| 参数名 | 类型 | 必选 | 默认值 | 描述 |
+| :----: | :----: | :---: | :----: | :--------------------------------------------------------------------------------------------: |
+| key | 字符串 | 是 | | 消费者访问资源进行身份验证时，需使用的密钥。请注意，不同消费者配置该插件时，需使用不同的密钥。 |
-## 属性
+## 使用 AdminAPI 启用插件
-consumer 端配置：
+首先，创建消费者并配置 key-auth 插件（密钥为：auth-key）：
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---- | ------ | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------- |
-| key | string | 必需 | | | 不同的 `consumer` 对象应有不同的值，它应当是唯一的。不同 consumer 使用了相同的 `key` ，将会出现请求匹配异常。 |
-
-router 端配置：
-
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---- | ------ | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------- |
-| header | string | 可选| apikey | | 设置我们从哪个 header 获取 key。 |
-
-## 如何启用
-
-1. 创建一个 consumer 对象，并设置插件 `key-auth` 的值。
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "username": "jack",
- "plugins": {
- "key-auth": {
- "key": "auth-one"
- }
- }
-}'
-```
-
-你可以使用浏览器打开 dashboard：`http://127.0.0.1:9080/apisix/dashboard/`，通过 web 界面来完成上面的操作，先增加一个 consumer：
-
-
-然后在 consumer 页面中添加 key-auth 插件：
-
-
-2. 创建 route 或 service 对象，并开启 `key-auth` 插件。
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+```bash
+$ curl -X PUT http://127.0.0.1:9080/apisix/admin/consumers -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -d '
{
- "methods": ["GET"],
- "uri": "/index.html",
- "id": 1,
- "plugins": {
- "key-auth": {}
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "39.97.63.215:80": 1
- }
+ "username": "consumer_username",
+ "plugins": {
+ "key-auth": {
+ "key": "auth-key"
}
-}'
+ }
+}
+'
```
-如果不想从默认的 `apikey` header 获取 key，可以自定义 header：
+其次，创建路由并绑定 key-auth 插件（该插件无需进行配置）：
-```json
+```bash
+$ curl -X PUT http://127.0.0.1:9080/apisix/admin/routes/1 -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -d '
{
- "key-auth": {
- "header": "Authorization"
+ "methods": ["GET"],
+ "uri": "/get",
+ "plugins": {
+ "key-auth": {}
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
}
+ }
}
+'
```
-## 测试插件
+最后，我们访问路由进行测试：
-下面是一个正常通过 `key-auth` 验证的请求:
+```bash
+# 场景1：访问路由时，不携带密钥
-```shell
-$ curl http://127.0.0.2:9080/index.html -H 'apikey: auth-one' -i
-HTTP/1.1 200 OK
-...
-```
-
-如果当前请求没有正确设置 `apikey` ，将得到一个 `401` 的应答。
+## Request
+$ curl -i -X GET http://127.0.0.1:9080/get
-```shell
-$ curl http://127.0.0.2:9080/index.html -i
+## Response
HTTP/1.1 401 Unauthorized
-...
+Date: Wed, 28 Apr 2021 09:02:40 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.5
+
{"message":"Missing API key found in request"}
-$ curl http://127.0.0.2:9080/index.html -H 'apikey: abcabcabc' -i
+# 场景2：访问路由时，携带错误密钥
+
+## Request
+$ curl -i -X GET http://127.0.0.1:9080/get -H "apikey: wrong-key"
+
+## Response
HTTP/1.1 401 Unauthorized
-...
+Date: Wed, 28 Apr 2021 09:03:40 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.5
+
{"message":"Invalid API key in request"}
+
+# 场景3：访问路由时，携带正确密钥（在 HTTP 请求头中）
+
+## Request
+$ curl -i -X GET http://127.0.0.1:9080/get -H "apikey: auth-key"
+
+## Response
+HTTP/1.1 200 OK
+Content-Type: application/json
+Content-Length: 325
+Connection: keep-alive
+Date: Wed, 28 Apr 2021 09:03:53 GMT
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Credentials: true
+Server: APISIX/2.5
+
+{
+ "args": {},
+ "headers": {
+ "Accept": "*/*",
+ "Apikey": "auth-key",
+ "Host": "127.0.0.1",
+ "User-Agent": "curl/7.29.0",
+ "X-Amzn-Trace-Id": "Root=1-608924f9-4a20a14821ce0ae97337e9f8",
+ "X-Forwarded-Host": "127.0.0.1"
+ },
+ "origin": "127.0.0.1, 8.210.41.192",
+ "url": "http://127.0.0.1/get"
+}
```
-## 禁用插件
+## 使用 AdminAPI 禁用插件
-当你想去掉 `key-auth` 插件的时候，很简单，在插件的配置中把对应的 `json` 配置删除即可，无须重启服务，即刻生效：
+如果希望禁用插件，只需更新路由配置，从 plugins 字段移除该插件即可：
-```shell
-$ curl http://127.0.0.1:2379/v2/keys/apisix/routes/1 -X PUT -d value='
+```bash
+$ curl -X PUT http://127.0.0.1:9080/apisix/admin/routes/1 -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -d '
{
- "methods": ["GET"],
- "uri": "/index.html",
- "id": 1,
- "plugins": {
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "39.97.63.215:80": 1
- }
+ "methods": ["GET"],
+ "uri": "/get",
+ "plugins": {
+ "key-auth": {}
Review comment:
ok 😂
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-831629657
After discuss with @Yiyiyimu, I agree with him, this is more challenge for a non-CN speaker, you could pick other issues like `Web Test` or `Featrures` or `bugfix` issues.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on a change in pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#discussion_r625469631
##########
File path: docs/zh/latest/plugins/api-breaker.md
##########
@@ -21,98 +21,69 @@ title: api-breaker
#
-->
-## 目录
+## 简介
-- [**定义**](#定义)
-- [**属性列表**](#属性列表)
-- [**启用方式**](#启用方式)
-- [**测试插件**](#测试插件)
-- [**禁用插件**](#禁用插件)
+启用该插件后，网关将根据配置判断上游是否异常，若异常，则直接返回预设的错误码，且在一定时间内不再访问上游。
-## 定义
+## 参数
-该插件实现 API 熔断功能，帮助我们保护上游业务服务。
+| 参数名称 | 类型 | 必选 | 默认值 | 使用范围 | 描述 |
+| :---------------------: | :--------: | :---: | :----: | :-------: | :--------------------------------------------------------------------------------: |
+| break_response_code | 整数型 | 是 | | 200 ~ 599 | 上游不健康时，将返回该状态码。 |
Review comment:
🤔 ok
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-832612967
Hi, to prevent from misleading PRs or contents, I will split them into smaller PRs.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-830138361
Hi @Yiyiyimu, I have added some other plugins, this PR is ready for review. (10 Plugins in Chinese)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] Yiyiyimu commented on pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
Yiyiyimu commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-831568914
> okay i will be working on EN docs in next PR, will take help from @guoqqqi or @Yiyiyimu if i do wrong
> while understanding chinese
Hi @iamayushdas Thanks for the volunteer! But as I told you before, it might not be a good idea to do the Chinese-English translation for a non-CNEN-bilingual speaker, since it is not a good idea to fully rely on translation tools to do the job. I think we still need a Chinese contributor on this kind of task.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan edited a comment on pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan edited a comment on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-830135151
I use `Control` according to MDN[1], does this mean they are different? 😳😳
[1] https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan edited a comment on pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan edited a comment on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-828988879
I see there has a wrong check 😳😳 `Access-Control-Allow-Credentials`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on a change in pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#discussion_r625475491
##########
File path: docs/zh/latest/plugins/api-breaker.md
##########
@@ -21,98 +21,69 @@ title: api-breaker
#
-->
-## 目录
+## 简介
-- [**定义**](#定义)
-- [**属性列表**](#属性列表)
-- [**启用方式**](#启用方式)
-- [**测试插件**](#测试插件)
-- [**禁用插件**](#禁用插件)
+启用该插件后，网关将根据配置判断上游是否异常，若异常，则直接返回预设的错误码，且在一定时间内不再访问上游。
-## 定义
+## 参数
-该插件实现 API 熔断功能，帮助我们保护上游业务服务。
+| 参数名称 | 类型 | 必选 | 默认值 | 使用范围 | 描述 |
+| :---------------------: | :--------: | :---: | :----: | :-------: | :--------------------------------------------------------------------------------: |
+| break_response_code | 整数型 | 是 | | 200 ~ 599 | 上游不健康时，将返回该状态码。 |
Review comment:
done
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] Yiyiyimu commented on pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
Yiyiyimu commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-830869151
> Hi @Yiyiyimu, I have added some other plugins, this PR is ready for review. (10 Plugins in Chinese)
New docs LGTM 🚀
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] spacewander commented on pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
spacewander commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-829225611
>
>
> I see there has a wrong check 😳😳 `Access-Control-Allow-Credentials`
>
> 
The check is correct. You should change `Access-Controll-Max-Age`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on a change in pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#discussion_r622781066
##########
File path: docs/zh/latest/plugins/limit-conn.md
##########
@@ -21,62 +21,62 @@ title: limit-conn
#
-->
-限制并发请求（或并发连接）插件。
+## 简介
-### 属性
+启用该插件后，网关将根据预设参数限制该路由并发请求数量。
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ------------------ | ------- | -------- | ------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| conn | integer | required | | conn > 0 | 允许的最大并发请求数。超过 `conn` 的限制、但是低于 `conn` + `burst` 的请求，将被延迟处理。 |
-| burst | integer | required | | burst >= 0 | 允许被延迟处理的并发请求数。 |
-| default_conn_delay | number | required | | default_conn_delay > 0 | 默认的典型连接(或请求)的处理延迟时间。 |
-| key | object | required | | ["remote_addr", "server_addr", "http_x_real_ip", "http_x_forwarded_for", "consumer_name"] | 用户指定的限制并发级别的关键字，可以是客户端 IP 或服务端 IP。<br />例如，可以使用主机名（或服务器区域）作为关键字，以便限制每个主机名的并发性。 否则，我们也可以使用客户端地址作为关键字，这样我们就可以避免单个客户端用太多的并行连接或请求淹没我们的服务。 <br />当前接受的 key 有："remote_addr"（客户端 IP 地址）, "server_addr"（服务端 IP 地址）, 请求头中的"X-Forwarded-For" 或 "X-Real-IP", "consumer_name"（consumer 的 username）。 |
-| rejected_code | string | optional | 503 | [200,...,599] | 当请求超过 `conn` + `burst` 这个阈值时，返回的 HTTP 状态码 |
+## 参数
-**注：key 是可以被用户自定义的，只需要修改插件的一行代码即可完成。并没有在插件中放开是处于安全的考虑。**
Review comment:
I would prefer putting this line in FAQ or somewhere else 🤔 Our parameters have the most common values already.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] moonming commented on pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
moonming commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-831638101
> For docs in English, I would prefer submitting a new PR ✌️
English doc first
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on a change in pull request #4155: docs: improve plugins' documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#discussion_r623925548
##########
File path: docs/zh/latest/plugins/limit-conn.md
##########
@@ -21,62 +21,62 @@ title: limit-conn
#
-->
-限制并发请求（或并发连接）插件。
+## 简介
-### 属性
+启用该插件后，网关将根据预设参数限制该路由并发请求数量。
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ------------------ | ------- | -------- | ------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| conn | integer | required | | conn > 0 | 允许的最大并发请求数。超过 `conn` 的限制、但是低于 `conn` + `burst` 的请求，将被延迟处理。 |
-| burst | integer | required | | burst >= 0 | 允许被延迟处理的并发请求数。 |
-| default_conn_delay | number | required | | default_conn_delay > 0 | 默认的典型连接(或请求)的处理延迟时间。 |
-| key | object | required | | ["remote_addr", "server_addr", "http_x_real_ip", "http_x_forwarded_for", "consumer_name"] | 用户指定的限制并发级别的关键字，可以是客户端 IP 或服务端 IP。<br />例如，可以使用主机名（或服务器区域）作为关键字，以便限制每个主机名的并发性。 否则，我们也可以使用客户端地址作为关键字，这样我们就可以避免单个客户端用太多的并行连接或请求淹没我们的服务。 <br />当前接受的 key 有："remote_addr"（客户端 IP 地址）, "server_addr"（服务端 IP 地址）, 请求头中的"X-Forwarded-For" 或 "X-Real-IP", "consumer_name"（consumer 的 username）。 |
-| rejected_code | string | optional | 503 | [200,...,599] | 当请求超过 `conn` + `burst` 这个阈值时，返回的 HTTP 状态码 |
+## 参数
-**注：key 是可以被用户自定义的，只需要修改插件的一行代码即可完成。并没有在插件中放开是处于安全的考虑。**
Review comment:
I reconsidered this case, do we really need this tip for users? 🤔
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] membphis commented on pull request #4155: docs: improve plugins' documentation (Chinese)
Posted by GitBox <gi...@apache.org>.
membphis commented on pull request #4155:
URL: https://github.com/apache/apisix/pull/4155#issuecomment-832565111
split this PR into smaller ones are better
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org