Merge pull request #10265 from HJianBo/improve-some-options-desc

docs: improve some mqtt options description
2023-04-01 16:43:15 +02:00 · 2023-04-01 16:43:15 +02:00 · b17548f382
parent 53d760ec69 1ff8ecf604
commit b17548f382
1 changed files with 54 additions and 52 deletions
--- a/apps/emqx/i18n/emqx_schema_i18n.conf
+++ b/apps/emqx/i18n/emqx_schema_i18n.conf
@ -666,15 +666,15 @@ mqtt 下所有的配置作为全局的默认值存在，它可以被 <code>zone<

    mqtt_idle_timeout {
        desc {
-            en: """After the TCP connection is established, if the MQTT CONNECT packet from the client is
-not received within the time specified by <code>idle_timeout</code>, the connection will be disconnected.
-After the CONNECT packet has been accepted by EMQX, if the connection idles for this long time,
-then the Erlang process is put to hibernation to save OS resources. Note: long <code>idle_timeout</code>
-interval may impose risk at the system if large number of malicious clients only establish connections
-but do not send any data."""
-            zh: """TCP 连接建立后，如果在 <code>idle_timeout</code> 指定的时间内未收到客户端的 MQTT CONNECT 报文，则连接将被断开。
-如果连接在 CONNECT 报文被 EMQX 接受之后空闲超过该时长，那么服务这个连接的 Erlang 进程会进入休眠以节省系统资源。
-注意，该配置值如果设置过大的情况下，如果大量恶意客户端只连接，但不发任何数据，可能会导致系统资源被恶意消耗。"""
+            en: """Configure the duration of time that a connection can remain idle (i.e., without any data transfer) before being:
+  - Automatically disconnected  if no CONNECT package is received from the client yet.
+  - Put into hibernation mode to save resources if some CONNECT packages are already received.
+Note: Please set the parameter with caution as long idle time will lead to resource waste."""
+            zh: """设置连接被断开或进入休眠状态前的等待时间，空闲超时后，
+  - 如暂未收到客户端的 CONNECT 报文，连接将断开；
+  - 如已收到客户端的 CONNECT 报文，连接将进入休眠模式以节省系统资源。
+
+注意：请合理设置该参数值，如等待时间设置过长，可能造成系统资源的浪费。"""
        }
        label: {
            en: """Idle Timeout"""
@ -783,8 +783,8 @@ but do not send any data."""

    mqtt_ignore_loop_deliver {
        desc {
-            en: """Ignore loop delivery of messages for MQTT v3.1.1/v3.1.0, similar to <code>No Local</code> subscription option in MQTT 5.0."""
-            zh: """是否为 MQTT v3.1.1/v3.1.0 客户端忽略投递自己发布的消息，类似于 MQTT 5.0 中的 <code>No Local</code> 订阅选项。"""
+            en: """Whether the messages sent by the MQTT v3.1.1/v3.1.0 client will be looped back to the publisher itself, similar to <code>No Local</code> in MQTT 5.0."""
+            zh: """设置由 MQTT v3.1.1/v3.1.0 客户端发布的消息是否将转发给其本身；类似 MQTT 5.0 协议中的 <code>No Local</code> 选项。"""
        }
        label: {
            en: """Ignore Loop Deliver"""
@ -794,10 +794,10 @@ but do not send any data."""

    mqtt_strict_mode {
        desc {
-            en: """Parse MQTT messages in strict mode.
-When set to true, invalid utf8 strings in for example client ID, topic name, etc. will cause the client to be disconnected"""
+            en: """Whether to parse MQTT messages in strict mode.
+In strict mode, invalid utf8 strings in for example client ID, topic name, etc. will cause the client to be disconnected."""
            zh: """是否以严格模式解析 MQTT 消息。
-当设置为 true 时，例如客户端 ID、主题名称等中的无效 utf8 字符串将导致客户端断开连接。"""
+严格模式下，如客户端 ID、主题名称等中包含无效 utf8 字符串，连接将被断开。"""
        }
        label: {
            en: """Strict Mode"""
@ -807,8 +807,10 @@ When set to true, invalid utf8 strings in for example client ID, topic name, etc

    mqtt_response_information {
        desc {
-            en: """Specify the response information returned to the client. This feature is disabled if is set to \"\". Applies only to clients using MQTT 5.0."""
-            zh: """指定返回给客户端的响应信息。如果设置为 \"\"，则禁用此功能。仅适用于使用 MQTT 5.0 协议的客户端。"""
+            en: """UTF-8 string, for creating the response topic, for example, if set to <code>reqrsp/</code>, the publisher/subscriber will communicate using the topic prefix <code>reqrsp/</code>.
+To disable this feature, input <code>\"\"</code> in the text box below. Only applicable to MQTT 5.0 clients."""
+            zh: """UTF-8 字符串，用于指定返回给客户端的响应主题，如 <code>reqrsp/</code>，此时请求和应答客户端都需要使用 <code>reqrsp/</code> 前缀的主题来完成通讯。
+如希望禁用此功能，请在下方的文字框中输入<code>\"\"</code>；仅适用于 MQTT 5.0 客户端。"""
        }
        label: {
            en: """Response Information"""
@ -818,23 +820,23 @@ When set to true, invalid utf8 strings in for example client ID, topic name, etc

    mqtt_server_keepalive {
        desc {
-            en: """The keep alive that EMQX requires the client to use. If configured as <code>disabled</code>, it means that the keep alive specified by the client will be used. Requires <code>Server Keep Alive</code> in MQTT 5.0, so it is only applicable to clients using MQTT 5.0 protocol."""
-            zh: """EMQX 要求客户端使用的保活时间，配置为 <code>disabled</code> 表示将使用客户端指定的保活时间。需要用到 MQTT 5.0 中的 <code>Server Keep Alive</code>，因此仅适用于使用 MQTT 5.0 协议的客户端。"""
+            en: """The keep alive duration required by EMQX. To use the setting from the client side, choose disabled from the drop-down list. Only applicable to MQTT 5.0 clients."""
+            zh: """EMQX 要求的保活时间，如设为 disabled，则将使用客户端指定的保持连接时间；仅适用于 MQTT 5.0 客户端。"""
        }
        label: {
            en: """Server Keep Alive"""
-            zh: """服务端保持连接"""
+            zh: """服务端保活时间"""
        }
    }

    mqtt_keepalive_backoff {
        desc {
-            en: """The backoff multiplier used by the broker to determine the client keep alive timeout. If EMQX doesn't receive any packet in <code>Keep Alive * Backoff * 2</code> seconds, EMQX will close the current connection."""
-            zh: """Broker 判定客户端保活超时使用的退避乘数。如果 EMQX 在 <code>Keep Alive * Backoff * 2</code> 秒内未收到任何报文，EMQX 将关闭当前连接。"""
+            en: """The coefficient EMQX uses to confirm whether the keep alive duration of the client expires. Formula: Keep Alive * Backoff * 2"""
+            zh: """EMQX 判定客户端保活超时使用的阈值系数。计算公式为：Keep Alive * Backoff * 2"""
        }
        label: {
            en: """Keep Alive Backoff"""
-            zh: """保持连接退避乘数"""
+            zh: """保活超时阈值系数"""
        }
    }

@ -978,14 +980,14 @@ To configure <code>\"topic/1\" > \"topic/2\"</code>:

    mqtt_use_username_as_clientid {
        desc {
-            en: """Whether to user Client ID as Username.
-This setting takes effect later than <code>Use Peer Certificate as Username</code> (<code>peer_cert_as_username</code>) and <code>Use peer certificate as Client ID</code> (<code>peer_cert_as_clientid</code>)."""
+            en: """Whether to use Username as Client ID.
+This setting takes effect later than <code>Use Peer Certificate as Username</code> and <code>Use peer certificate as Client ID</code>."""
            zh: """是否使用用户名作为客户端 ID。
-此设置的作用时间晚于 <code>使用对端证书作为用户名</code>（<code>peer_cert_as_username</code>） 和 <code>使用对端证书作为客户端 ID</code>（<code>peer_cert_as_clientid</code>）。"""
+此设置的作用时间晚于 <code>对端证书作为用户名</code> 和 <code>对端证书作为客户端 ID</code>。"""
        }
        label: {
            en: """Use Username as Client ID"""
-            zh: """使用用户名作为客户端 ID"""
+            zh: """用户名作为客户端 ID"""
        }
    }

@ -993,22 +995,22 @@ This setting takes effect later than <code>Use Peer Certificate as Username</cod
        desc {
            en: """Use the CN, DN field in the peer certificate or the entire certificate content as Username. Only works for the TLS connection.
 Supported configurations are the following:
- <code>cn</code>: Take the CN field of the certificate as Username
- <code>dn</code>: Take the DN field of the certificate as Username
- <code>crt</code>: Take the content of the <code>DER</code> or <code>PEM</code> certificate as Username
- <code>pem</code>: Convert <code>DER</code> certificate content to <code>PEM</code> format as Username
- <code>md5</code>: Take the MD5 value of the content of the <code>DER</code> or <code>PEM</code> certificate as Username"""
-            zh: """使用对端证书中的 CN、DN 字段或整个证书内容来作为用户名。仅适用于 TLS 连接。
-目前支持配置为以下内容：
- <code>cn</code>: 取证书的 CN 字段作为 Username
- <code>dn</code>: 取证书的 DN 字段作为 Username
- <code>crt</code>: 取 <code>DER</code> 或 <code>PEM</code> 证书的内容作为 Username
- <code>pem</code>: 将 <code>DER</code> 证书内容转换为 <code>PEM</code> 格式后作为 Username
- <code>md5</code>: 取 <code>DER</code> 或 <code>PEM</code> 证书的内容的 MD5 值作为 Username"""
+- <code>cn</code>: CN field of the certificate
+- <code>dn</code>: DN field of the certificate
+- <code>crt</code>: Content of the <code>DER</code> or <code>PEM</code> certificate
+- <code>pem</code>: Convert <code>DER</code> certificate content to <code>PEM</code> format and use as Username
+- <code>md5</code>: MD5 value of the <code>DER</code> or <code>PEM</code> certificate"""
+            zh: """使用对端证书中的 CN、DN 字段或整个证书内容来作为用户名；仅适用于 TLS 连接。
+目前支持：
+- <code>cn</code>: 取证书的 CN 字段
+- <code>dn</code>: 取证书的 DN 字段
+- <code>crt</code>: 取 <code>DER</code> 或 <code>PEM</code> 的证书内容
+- <code>pem</code>: 将 <code>DER</code> 证书转换为 <code>PEM</code> 格式作为用户名
+- <code>md5</code>: 取 <code>DER</code> 或 <code>PEM</code> 证书内容的 MD5 值"""
        }
        label: {
            en: """Use Peer Certificate as Username"""
-            zh: """使用对端证书作为用户名"""
+            zh: """对端证书作为用户名"""
        }
    }

@ -1016,22 +1018,22 @@ Supported configurations are the following:
        desc {
            en: """Use the CN, DN field in the peer certificate or the entire certificate content as Client ID. Only works for the TLS connection.
 Supported configurations are the following:
- <code>cn</code>: Take the CN field of the certificate as Client ID
- <code>dn</code>: Take the DN field of the certificate as Client ID
- <code>crt</code>: Take the content of the <code>DER</code> or <code>PEM</code> certificate as Client ID
- <code>pem</code>: Convert <code>DER</code> certificate content to <code>PEM</code> format as Client ID
- <code>md5</code>: Take the MD5 value of the content of the <code>DER</code> or <code>PEM</code> certificate as Client ID"""
-            zh: """使用对端证书中的 CN、DN 字段或整个证书内容来作为客户端 ID。仅适用于 TLS 连接。
-目前支持配置为以下内容：
- <code>cn</code>: 取证书的 CN 字段作为 Client ID
- <code>dn</code>: 取证书的 DN 字段作为 Client ID
- <code>crt</code>: 取 <code>DER</code> 或 <code>PEM</code> 证书的内容作为 Client ID
- <code>pem</code>: 将 <code>DER</code> 证书内容转换为 <code>PEM</code> 格式后作为 Client ID
- <code>md5</code>: 取 <code>DER</code> 或 <code>PEM</code> 证书的内容的 MD5 值作为 Client ID"""
+- <code>cn</code>: CN field of the certificate
+- <code>dn</code>: DN field of the certificate
+- <code>crt</code>: <code>DER</code> or <code>PEM</code> certificate
+- <code>pem</code>: Convert <code>DER</code> certificate content to <code>PEM</code> format and use as Client ID
+- <code>md5</code>: MD5 value of the <code>DER</code> or <code>PEM</code> certificate"""
+            zh: """使用对端证书中的 CN、DN 字段或整个证书内容来作为客户端 ID。仅适用于 TLS 连接；
+目前支持：
+- <code>cn</code>: 取证书的 CN 字段
+- <code>dn</code>: 取证书的 DN 字段
+- <code>crt</code>: 取 <code>DER</code> 或 <code>PEM</code> 证书的内容
+- <code>pem</code>: 将 <code>DER</code> 证书内容转换为 <code>PEM</code> 格式作为客户端 ID
+- <code>md5</code>: 取 <code>DER</code> 或 <code>PEM</code> 证书内容的 MD5 值"""
        }
        label: {
            en: """Use Peer Certificate as Client ID"""
-            zh: """使用对端证书作为客户端 ID"""
+            zh: """对端证书作为客户端 ID"""
        }
    }