You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sy...@apache.org on 2022/08/04 01:19:55 UTC
[apisix] branch master updated: docs: refactor mqtt-proxy Chinese doc (#7570)
This is an automated email from the ASF dual-hosted git repository.
sylviasu 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 d5a6559d4 docs: refactor mqtt-proxy Chinese doc (#7570)
d5a6559d4 is described below
commit d5a6559d4759f009e43d40e1bd70d1aacfa16d64
Author: Fei Han <97...@users.noreply.github.com>
AuthorDate: Thu Aug 4 09:19:51 2022 +0800
docs: refactor mqtt-proxy Chinese doc (#7570)
* docs: refactor maqtt-proxy Chinese doc
---
docs/en/latest/plugins/mqtt-proxy.md | 8 ++--
docs/zh/latest/plugins/mqtt-proxy.md | 91 +++++++++++++++++++++++++++---------
2 files changed, 72 insertions(+), 27 deletions(-)
diff --git a/docs/en/latest/plugins/mqtt-proxy.md b/docs/en/latest/plugins/mqtt-proxy.md
index 09fd8bbc3..6b5dd18b4 100644
--- a/docs/en/latest/plugins/mqtt-proxy.md
+++ b/docs/en/latest/plugins/mqtt-proxy.md
@@ -5,7 +5,7 @@ keywords:
- API Gateway
- Plugin
- MQTT Proxy
-description: This document contains information about the Apache APISIX mqtt-proxy Plugin.
+description: This document contains information about the Apache APISIX mqtt-proxy Plugin. The `mqtt-proxy` Plugin is used for dynamic load balancing with `client_id` of MQTT.
---
<!--
@@ -127,9 +127,9 @@ MQTT connections with different client ID will be forwarded to different nodes b
Stream proxies use TCP connections and can accept TLS. Follow the guide about [how to accept tls over tcp connections](../stream-proxy.md/#accept-tls-over-tcp-connection) to open a stream proxy with enabled TLS.
-The `mqtt-proxy` plugin is enabled through TCP communications on the specified port for the stream proxy, and will also require clients to authenticate via TLS if tls is set to true.
+The `mqtt-proxy` plugin is enabled through TCP communications on the specified port for the stream proxy, and will also require clients to authenticate via TLS if `tls` is set to `true`.
-Configure `ssl` providing the CA certificate and the server certificate, together with a list of SNIs. Steps to protect `stream_routes` with `ssl` are equivalent to the ones to [protect Routes](../mtls.md/#protect-route)
+Configure `ssl` providing the CA certificate and the server certificate, together with a list of SNIs. Steps to protect `stream_routes` with `ssl` are equivalent to the ones to [protect Routes](../mtls.md/#protect-route).
### Create a stream_route using mqtt-proxy plugin and mTLS
@@ -154,7 +154,7 @@ curl 127.0.0.1:9180/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-The `sni` name must math one or more of the SNIs provided to the SSL object that you created with the CA and server certificates.
+The `sni` name must match one or more of the SNIs provided to the SSL object that you created with the CA and server certificates.
## Disable Plugin
diff --git a/docs/zh/latest/plugins/mqtt-proxy.md b/docs/zh/latest/plugins/mqtt-proxy.md
index bd97286ef..d9902e710 100644
--- a/docs/zh/latest/plugins/mqtt-proxy.md
+++ b/docs/zh/latest/plugins/mqtt-proxy.md
@@ -1,5 +1,11 @@
---
title: mqtt-proxy
+keywords:
+ - APISIX
+ - API 网关
+ - Plugin
+ - MQTT Proxy
+description: 本文档介绍了 Apache APISIX mqtt-proxy 插件的信息，通过 `mqtt-proxy` 插件可以使用 MQTT 的 `client_id` 进行动态负载平衡。
---
<!--
@@ -23,26 +29,26 @@ title: mqtt-proxy
## 描述
-`mqtt-proxy` 只工作在流模式，它可以帮助你根据 MQTT 的 `client_id` 实现动态负载均衡。
+通过 `mqtt-proxy` 插件可以使用 MQTT 的 `client_id` 进行动态负载平衡。它仅适用于 `stream` 模式。
这个插件支持 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 ) 两个协议。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| -------------- | ------- | ------ | ------ | ------ | ------------------------------------------------------ |
-| protocol_name | string | 必须 | | | 协议名称，正常情况下应为“ MQTT” |
-| protocol_level | integer | 必须 | | | 协议级别，MQTT `3.1.*` 应为 `4` ，MQTT `5.0` 应是`5`。 |
-| upstream | object | 废弃 | | | 推荐改用 route 上配置的上游信息 |
-| upstream.host | string | 必须 | | | 将当前请求转发到的上游的 IP 地址或域名 |
-| upstream.ip | string | 废弃 | | | 推荐使用“host”代替。将当前请求转发到的上游的 IP 地址 |
-| upstream.port | number | 必须 | | | 将当前请求转发到的上游的端口 |
+| 名称 | 类型 | 必选项 | 描述 |
+| -------------- | ------- | ----- | ------------------------------------------------------ |
+| protocol_name | string | 是 | 协议名称，正常情况下应为 `MQTT`。 |
+| protocol_level | integer | 是 | 协议级别，MQTT `3.1.*` 为 `4`，MQTT `5.0` 应是`5`。 |
+| upstream | object | 废弃 | 推荐使用 Route 上配置的上游信息。 |
+| upstream.host | string | 是 | 将当前请求转发到的上游的 IP 地址或域名。 |
+| upstream.ip | string | 废弃 | 推荐使用 `host` 代替。将当前请求转发到的上游的 IP 地址。 |
+| upstream.port | number | 是 | 将当前请求转发到的上游的端口。 |
-## 如何启用
+## 启用插件
-为了启用该插件，需要先在 `conf/config.yaml` 中首先开启 stream_proxy 配置，比如下面配置代表监听 9100 TCP 端口：
+为了启用该插件，需要先在配置文件（`./conf/config.yaml`）中加载 `stream_proxy` 相关配置。以下配置代表监听 `9100` TCP 端口：
-```yaml
+```yaml title=“./conf/config.yaml”
...
router:
http: 'radixtree_uri'
@@ -55,12 +61,13 @@ title: mqtt-proxy
...
```
-然后把 MQTT 请求发送到 9100 端口即可。
+现在你可以将请求发送到 `9100` 端口。
-下面是一个示例，在指定的 route 上开启了 `mqtt-proxy` 插件：
+你可以创建一个 stream 路由并启用 `mqtt-proxy` 插件。
```shell
-curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"mqtt-proxy": {
@@ -79,12 +86,13 @@ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f03
}'
```
-在 Docker 与 MacOS 结合使用的情况下，`host.docker.internal` 是 `host` 的正确参数。
+如果你在 macOS 中使用 Docker，则 `host.docker.internal` 是 `host` 的正确属性。
-这个插件暴露了一个变量 `mqtt_client_id`，我们可以用它来通过客户端 ID 进行负载均衡。比如说：
+该插件暴露了一个变量 `mqtt_client_id`，你可以使用它来通过客户端 ID 进行负载均衡。比如：
```shell
-curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"mqtt-proxy": {
@@ -111,14 +119,51 @@ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f03
}'
```
-不同客户端 ID 的 MQTT 连接将通过一致性哈希算法被转发到不同的节点。如果客户端 ID 为空，我们将通过客户端 IP 进行均衡。
+不同客户端 ID 的 MQTT 连接将通过一致性哈希算法被转发到不同的节点。如果客户端 ID 为空，将会通过客户端 IP 进行均衡。
-#### 禁用插件
+## 使用 mqtt-proxy 插件启用 mTLS
-当你想去掉插件的时候，很简单，在插件的配置中把对应的 json 配置删除即可，无须重启服务，即刻生效：
+Stream 代理可以使用 TCP 连接并且支持 TLS。请参考 [如何通过 tcp 连接接受 tls](../stream-proxy.md/#accept-tls-over-tcp-connection) 打开启用了 TLS 的 stream 代理。
+
+`mqtt-proxy` 插件通过 Stream 代理的指定端口的 TCP 通信启用，如果 `tls` 设置为 `true`，则还要求客户端通过 TLS 进行身份验证。
+
+配置 `ssl` 提供 CA 证书和服务器证书，以及 SNI 列表。使用 `ssl` 保护 `stream_routes` 的步骤等同于 [protect Routes](../mtls.md/#protect-route)。
+
+### 创建 stream_route 并配置 mqtt-proxy 插件和 mTLS
+
+通过以下示例可以创建一个配置了 `mqtt-proxy` 插件的 `stream_route`，需要提供 CA 证书、客户端证书和客户端密钥（对于不受主机信任的自签名证书，请使用 -k 选项）：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X DELETE
+curl 127.0.0.1:9180/apisix/admin/stream_routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "mqtt-proxy": {
+ "protocol_name": "MQTT",
+ "protocol_level": 4
+ }
+ },
+ "sni": "${your_sni_name}",
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": 1
+ },
+ "type": "roundrobin"
+ }
+}'
```
-现在就已经移除了 mqtt-proxy 插件了。
+:::note 注意
+
+`sni` 名称必须与提供的 CA 和服务器证书创建的 SSL 对象的一个或多个 SNI 匹配。
+
+:::
+
+## 禁用插件
+
+当你需要禁用该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X DELETE
+```