Merge pull request #2547 from emqx/0618-jwt-authz-update

docs(authz & jwt): Update topic placeholders and acl example

Author: zmstone

en_US/access-control/authn/jwt.md

@@ -69,10 +69,11 @@ Example:
       "topic": "t/${clientid}"
     },
     {
-      // Allows the client to subscribe to the topic t/1 with QoS 1, while QoS 0 or 2 is allowed
-      "permission": "deny",
+      "permission": "allow",
       "action": "subscribe",
-      "topic": "t/1",
+      // The 'eq' prefix means the rule matches 't/1/#', but not 't/1/x' or 't/1/y'
+      "topic": "eq t/1/#",
+      // Matches QoS 1, but not QoS 0 or 2
       "qos": [1]
     },
     {

en_US/access-control/authz/authz.md

@@ -102,7 +102,15 @@ EMQX also allows placeholders to be used in topics to support dynamic themes. Th
 
 Placeholders can be used as topic segments, like `a/b/${username}/c/d`.
 
-To avoid placeholder interpolation, one may use special `eq` syntax: `eq a/b/${username}/c/d`. This topic is treated as `a/b/${username}/c/d` literally, without interpolation.
+To avoid placeholder interpolation, starting from EMQX 5.4, you can escape `$` as `${$}`. For example, `t/${$}{username}` is treated as `t/${username}` literally without interpolation, rather than the topic name with `username` replaced.
+
+::: tip
+
+If you use the `eq` syntax in query statements, note that the topic following `eq` does not support placeholder interpolation. This behavior can change in future versions. 
+
+The `eq` syntax is to match exactly a topic filter, but not any topic that matches the filter. For example, `eq t/#` matches `t/#`, not `t/1` or `t/2`.
+
+:::
 
 ### Authorization Check Priority
 

zh_CN/access-control/authn/jwt.md

@@ -65,10 +65,11 @@
       "topic": "t/${clientid}"
     },
     {
-      // 允许客户端以 QoS 1 订阅 t/1 主题，使用 QoS 0 或 2 则是允许的
-      "permission": "deny",
+      "permission": "allow",
       "action": "subscribe",
-      "topic": "t/1",
+      // `eq` 前缀意味着该规则仅适用于主题过滤器 t/1/#，但不适用于 t/1/x 或 t/1/y 等
+      "topic": "eq t/1/#",
+      // 该规则只匹配 QoS 1 但不匹配 QoS 0 或 2
       "qos": [1]
     },
     {

zh_CN/access-control/authz/authz.md

@@ -116,7 +116,15 @@ EMQX 还允许在主题中使用占位符，在匹配规则时将当前客户端
 
 <!-- TODO 调查与 4.x 版本是否存在差异-->
 
-为了避免占位符跟想要的主题冲突的问题，EMQX 5.0 中引入了一个 `eq` 语法，例如 `eq a/b/${username}/c/d`。
+为了避免占位符跟想要的主题冲突的问题，从 EMQX 5.4 开始，可以使用 `${$}` 来对 `$` 进行转义。例如 `t/${$}{username}` 表示 `t/${username}` 本身，而不是将 username 替换进去之后的主题名称。
+
+::: tip
+
+如果在查询语句中使用`eq` 语法，需要注意，`eq` 后面的主题不支持占位符替换，这个行为可能会在后续版本中改变。
+
+`eq` 语法用于精确匹配一个订阅主题通配符，而不是匹配该通配符的其他主题。 例如 `eq t/#` 精确匹配 `t/#` 但不匹配 `t/1` 或 `t/2` 等等。
+
+ :::
 
 ### 授权检查优先级
 

zh_CN/access-control/authz/file.md

@@ -12,7 +12,7 @@ EMQX 支持基于 ACL 文件中存储的规则进行授权检查。您可在文
 ## 文件格式
 基于文件的授权权限列表简单轻量，适合配置通用的规则。对于上百条或者更面向客户端的规则，推荐使用其他授权来源。基于文件的权限列表可以作为防护置于授权链末端。
 
-基于文件进行授权检查前，您需要将授权规则以 [Erlang 元组](https://www.erlang.org/doc/reference_manual/data_types.html#tuple) 数据列表的形式存储在文件中。
+基于文件进行授权检查前，您需要将授权规则以 [Erlang 元组](https://www.erlang.org/doc/reference_manual/data_types.html#tuple)数据列表的形式存储在文件中。
 
 基本语法和概念如下：