[GitHub] dongeforever commented on a change in pull request #707: [RIP-9]add the msg trace and acl feature content of RocketMQ doc part.

[GitBox <gi...@apache.org>]

dongeforever commented on a change in pull request #707: [RIP-9]add the msg trace and acl feature content of RocketMQ doc part.
URL: https://github.com/apache/rocketmq/pull/707#discussion_r249632391
 
 

 ##########
 File path: docs/cn/acl/user_guide.md
 ##########
 @@ -0,0 +1,80 @@
+# 权限控制
+## 前言
+该文档主要介绍如何快速部署和使用支持权限控制特性的RocketMQ 集群。
+
+## 1.权限控制特性介绍
+权限控制（ACL）主要为RocketMQ提供Topic资源级别的用户访问控制。用户在使用RocketMQ权限控制时，可以在Client客户端通过 RPCHook注入AccessKey和SecretKey签名；同时，将对应的权限控制属性（包括Topic访问权限、IP白名单和AccessKey和SecretKey签名等）设置在distribution/conf/plain_acl.yml的配置文件中。Broker端对AccessKey所拥有的权限进行校验，校验不过，抛出异常；
+ACL客户端可以参考：**org.apache.rocketmq.example.simple**包下面的**AclClient**代码。
+
+## 2. 权限控制的定义与属性值
+### 2.1权限定义
+对RocketMQ的Topic资源访问权限控制定义主要如下表所示，分为以下四种：
+| 权限 | 含义 |
+| --- | --- |
+| DENY | 拒绝 |
+| ANY | PUB 或者 SUB 权限 |
+| PUB | 发送权限 |
+| SUB | 订阅权限 |
+
+### 2.2 权限定义的关键属性
+| 字段 | 取值 | 含义 |
+| --- | --- | --- |
+| globalWhiteRemoteAddresses | \*;192.168.\*.\*;192.168.0.1 | 全局IP白名单 |
+| accessKey | 字符串 | Access Key |
+| secretKey | 字符串 | Secret Key |
+| whiteRemoteAddress | \*;192.168.\*.\*;192.168.0.1 | 用户IP白名单 |
+| admin | true;false | 是否管理员账户 |
+| defaultTopicPerm | DENY;PUB;SUB;PUB\|SUB | 默认的Topic权限 |
+| defaultGroupPerm | DENY;PUB;SUB;PUB\|SUB | 默认的ConsumerGroup权限 |
+| topicPerms | topic=权限 | 各个Topic的权限 |
+| groupPerms | group=权限 | 各个ConsumerGroup的权限 |
+
+具体可以参考**distribution/conf/plain_acl.yml**配置文件
+
+## 3. 支持权限控制的集群部署
+在**distribution/conf/plain_acl.yml**配置文件中按照上述说明定义好权限属性后，打开**aclEnable**开关变量即可开启RocketMQ集群的ACL特性。这里贴出Broker端开启ACL特性的properties配置文件内容：
+```
+brokerClusterName=DefaultCluster
+brokerName=broker-a
+brokerId=0
+deleteWhen=04
+fileReservedTime=48
+brokerRole=ASYNC_MASTER
+flushDiskType=ASYNC_FLUSH
+storePathRootDir=/data/rocketmq/rootdir-a-m
+storePathCommitLog=/data/rocketmq/commitlog-a-m
+autoCreateSubscriptionGroup=true
+## if acl is open,the flag will be true
+aclEnable=true
+listenPort=10911
+brokerIP1=XX.XX.XX.XX1
+namesrvAddr=XX.XX.XX.XX:9876
+```
+
+## 4. 权限控制主要流程
+ACL主要流程分为两部分，主要包括权限解析和权限校验。
+
+### 3.1 权限解析
+Broker端对客户端的RequestCommand请求进行解析，拿到需要鉴权的属性字段。
 
 Review comment:
   here should number it as '4.1'.
   There are similar problems in other parts of the doc

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on 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


With regards,
Apache Git Services