You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2021/09/13 04:09:01 UTC
[apisix] branch master updated: docs: add Chinese version of
control-api.md (#5019)
This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new cd97d82 docs: add Chinese version of control-api.md (#5019)
cd97d82 is described below
commit cd97d827abf6791611ce355b12555531dbd7b53d
Author: RedemptionC <84...@qq.com>
AuthorDate: Mon Sep 13 12:08:55 2021 +0800
docs: add Chinese version of control-api.md (#5019)
Co-authored-by: tzssangglass <tz...@gmail.com>
Co-authored-by: 罗泽轩 <sp...@gmail.com>
---
docs/zh/latest/config.json | 4 +
docs/zh/latest/control-api.md | 202 ++++++++++++++++++++++++++++++++++
docs/zh/latest/health-check.md | 2 +-
docs/zh/latest/plugin-develop.md | 4 +-
docs/zh/latest/plugins/server-info.md | 2 +-
5 files changed, 210 insertions(+), 4 deletions(-)
diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json
index cf13b25..266c6d1 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -132,6 +132,10 @@
{
"type": "doc",
"id": "admin-api"
+ },
+ {
+ "type": "doc",
+ "id": "control-api"
}
]
},
diff --git a/docs/zh/latest/control-api.md b/docs/zh/latest/control-api.md
new file mode 100644
index 0000000..acd2b02
--- /dev/null
+++ b/docs/zh/latest/control-api.md
@@ -0,0 +1,202 @@
+---
+title: Control API
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+control API 可以被用来：
+
+* 暴露 APISIX 内部状态信息
+* 控制单个 APISIX 的数据平面的行为
+
+默认情况下，control API 是启用的，监听 `127.0.0.1:9090`。你可以通过修改 `apisix/conf/config.yaml` 中的 control 部分来更改设置，如下：
+
+```yaml
+apisix:
+ ...
+ enable_control: true
+ control:
+ ip: "127.0.0.1"
+ port: 9090
+```
+
+注意: control API server 不应该被配置成监听公网地址。
+
+## 通过插件添加的 control API
+
+APISIX 中一些插件添加了自己的 control API。如果你对他们感兴趣，请参阅对应插件的文档。
+
+## 独立于插件的 control API
+
+以下是支持的 API:
+
+### GET /v1/schema
+
+引入自 2.2 版本
+
+使用以下格式返回被该 APISIX 实例使用的 json schema：
+
+```json
+{
+ "main": {
+ "route": {
+ "properties": {...}
+ },
+ "upstream": {
+ "properties": {...}
+ },
+ ...
+ },
+ "plugins": {
+ "example-plugin": {
+ "consumer_schema": {...},
+ "metadata_schema": {...},
+ "schema": {...},
+ "type": ...,
+ "priority": 0,
+ "version": 0.1
+ },
+ ...
+ },
+ "stream-plugins": {
+ "mqtt-proxy": {
+ ...
+ },
+ ...
+ }
+}
+```
+
+只有启用了的插件才会被包含在返回结果中 `plugins` 部分。(返回结果中的)一些插件可能会缺失如 `consumer_schema` 或者 `type` 字段，这取决于插件的定义。
+
+### GET /v1/healthcheck
+
+引入自 2.3 版本
+
+使用以下格式返回当前的 [health check](health-check.md) 状态
+
+```json
+[
+ {
+ "healthy_nodes": [
+ {
+ "host": "127.0.0.1",
+ "port": 1980,
+ "priority": 0,
+ "weight": 1
+ }
+ ],
+ "name": "upstream#/upstreams/1",
+ "nodes": [
+ {
+ "host": "127.0.0.1",
+ "port": 1980,
+ "priority": 0,
+ "weight": 1
+ },
+ {
+ "host": "127.0.0.2",
+ "port": 1988,
+ "priority": 0,
+ "weight": 1
+ }
+ ],
+ "src_id": "1",
+ "src_type": "upstreams"
+ },
+ {
+ "healthy_nodes": [
+ {
+ "host": "127.0.0.1",
+ "port": 1980,
+ "priority": 0,
+ "weight": 1
+ }
+ ],
+ "name": "upstream#/routes/1",
+ "nodes": [
+ {
+ "host": "127.0.0.1",
+ "port": 1980,
+ "priority": 0,
+ "weight": 1
+ },
+ {
+ "host": "127.0.0.1",
+ "port": 1988,
+ "priority": 0,
+ "weight": 1
+ }
+ ],
+ "src_id": "1",
+ "src_type": "routes"
+ }
+]
+```
+
+每个 entry 包含以下字段：
+
+* src_type：表示 health checker 的来源。值是 `[routes,services,upstreams]` 其中之一
+* src_id：表示创建 health checker 的对象的id。例如，假设 id 为 1 的 Upstream 对象创建了一个 health checker，那么 `src_type` 就是 `upstreams`，`src_id` 就是 1
+* name： 表示 health checker 的名称
+* nodes： health checker 的目标节点
+* healthy_nodes： 表示 health checker 检测到的健康节点
+
+用户也可以通过 `/v1/healthcheck/$src_type/$src_id` 来获取指定 health checker 的状态。
+
+例如，`GET /v1/healthcheck/upstreams/1` 返回：
+
+```json
+{
+ "healthy_nodes": [
+ {
+ "host": "127.0.0.1",
+ "port": 1980,
+ "priority": 0,
+ "weight": 1
+ }
+ ],
+ "name": "upstream#/upstreams/1",
+ "nodes": [
+ {
+ "host": "127.0.0.1",
+ "port": 1980,
+ "priority": 0,
+ "weight": 1
+ },
+ {
+ "host": "127.0.0.2",
+ "port": 1988,
+ "priority": 0,
+ "weight": 1
+ }
+ ],
+ "src_id": "1",
+ "src_type": "upstreams"
+}
+```
+
+### POST /v1/gc
+
+引入自 2.8 版本
+
+在 http 子系统中触发一次全量 GC
+
+注意，当你启用 stream proxy 时，APISIX 将为 stream 子系统运行另一个 Lua 虚拟机。它不会触发这个 Lua 虚拟机中的全量 GC。
diff --git a/docs/zh/latest/health-check.md b/docs/zh/latest/health-check.md
index a75f995..6344006 100644
--- a/docs/zh/latest/health-check.md
+++ b/docs/zh/latest/health-check.md
@@ -121,4 +121,4 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
* `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` 接口得到。
+健康检查信息可以通过 [控制接口](./control-api.md) 中的 `GET /v1/healthcheck` 接口得到。
diff --git a/docs/zh/latest/plugin-develop.md b/docs/zh/latest/plugin-develop.md
index 56ff135..af7f593 100644
--- a/docs/zh/latest/plugin-develop.md
+++ b/docs/zh/latest/plugin-develop.md
@@ -73,7 +73,7 @@ local _M = {
}
```
-注：新插件的优先级（ priority 属性 ）不能与现有插件的优先级相同，您可以使用 [control API](../../en/latest/control-api.md#get-v1schema) 的 `/v1/schema` 方法查看所有插件的优先级。另外，同一个阶段里面，优先级( priority )值大的插件，会优先执行，比如 `example-plugin` 的优先级是 0 ，`ip-restriction` 的优先级是 3000 ，所以在每个阶段，会先执行 `ip-restriction` 插件，再去执行 `example-plugin` 插件。这里的“阶段”的定义，参见后续的[确定执行阶段](#确定执行阶段)这一节。对于你的插件，建议采用 1 到 99 之间的优先级。
+注：新插件的优先级（ priority 属性 ）不能与现有插件的优先级相同，您可以使用 [control API](./control-api.md#get-v1schema) 的 `/v1/schema` 方法查看所有插件的优先级。另外，同一个阶段里面，优先级( priority )值大的插件，会优先执行，比如 `example-plugin` 的优先级是 0 ，`ip-restriction` 的优先级是 3000 ，所以在每个阶段，会先执行 `ip-restriction` 插件，再去执行 `example-plugin` 插件。这里的“阶段”的定义，参见后续的[确定执行阶段](#确定执行阶段)这一节。对于你的插件，建议采用 1 到 99 之间的优先级。
在 __conf/config-default.yaml__ 配置文件中，列出了启用的插件（都是以插件名指定的）：
@@ -378,7 +378,7 @@ end
### 注册控制接口
-如果你只想暴露 API 到 localhost 或内网，你可以通过 [Control API](../../en/latest/control-api.md) 来暴露它。
+如果你只想暴露 API 到 localhost 或内网，你可以通过 [Control API](./control-api.md) 来暴露它。
Take a look at example-plugin plugin:
diff --git a/docs/zh/latest/plugins/server-info.md b/docs/zh/latest/plugins/server-info.md
index 2fbd9dc..3abe779 100644
--- a/docs/zh/latest/plugins/server-info.md
+++ b/docs/zh/latest/plugins/server-info.md
@@ -54,7 +54,7 @@ title: server-info
## 插件接口
-该插件在 [Control API](../../../en/latest/control-api.md) 下暴露了一个 API 接口 `/v1/server_info`。
+该插件在 [Control API](../control-api.md) 下暴露了一个 API 接口 `/v1/server_info`。
## 启用插件