You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@rocketmq.apache.org by wl...@apache.org on 2019/03/29 03:11:40 UTC
[rocketmq] branch develop updated: update the format of RocketMQ User Guide

This is an automated email from the ASF dual-hosted git repository.

wlliqipeng pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/rocketmq.git


The following commit(s) were added to refs/heads/develop by this push:
     new 5e8974a  update the format of RocketMQ User Guide
5e8974a is described below

commit 5e8974a444fb10a77591a39a2a249657ea852d1f
Author: wlliqipeng <qi...@alibaba-inc.com>
AuthorDate: Fri Mar 29 11:11:01 2019 +0800

    update the format of RocketMQ User Guide
---
 docs/cn/README.md               | 48 +++++++++++++++++++++++++++++++++++++++++
 docs/cn/RocketMQ_Example.md     |  2 ++
 docs/cn/acl/user_guide.md       |  4 ++--
 docs/cn/architecture.md         |  6 +++---
 docs/cn/best_practice.md        |  2 +-
 docs/cn/concept.md              | 35 +++++++++++++++---------------
 docs/cn/design.md               |  3 ++-
 docs/cn/dledger/deploy_guide.md |  2 ++
 docs/cn/dledger/quick_start.md  |  2 ++
 docs/cn/features.md             | 26 +++++++++++-----------
 docs/cn/index.md                |  0
 docs/cn/msg_trace/user_guide.md |  3 +--
 docs/cn/operation.md            |  4 +++-
 13 files changed, 98 insertions(+), 39 deletions(-)

diff --git a/docs/cn/README.md b/docs/cn/README.md
new file mode 100644
index 0000000..8229107
--- /dev/null
+++ b/docs/cn/README.md
@@ -0,0 +1,48 @@
+Apache RocketMQ开发者指南
+--------
+
+#####这个开发者指南是帮忙您快速了解,并使用 Apache RocketMQ
+
+### 1. 概念和特性
+
+- [概念(Concept)](concept.md)：介绍RocketMQ的基本概念模型。
+
+- [特性(Features)](features.md)：介绍RocketMQ实现的功能特性。 
+
+
+### 2. 架构设计
+
+- [架构(Architecture)](architecture.md)：介绍RocketMQ部署架构和技术架构。
+
+- [设计(Design)](design.md)：介绍RocketMQ关键机制的设计原理，主要包括消息存储、通信机制、消息过滤、负载均衡、事物消息等。
+
+
+### 3. 样例
+
+- [样例(Example)](RocketMQ_Example.md) ：介绍RocketMQ的常见用法，包括基本样例、顺序消息样例、延时消息样例、批量消息样例、过滤消息样例、事物消息样例等。
+
+
+### 4. 最佳实践
+- [最佳实践（Best Practice）](best_practice.md)：介绍RocketMQ的最佳实践，包括生产者、消费者、Broker以及NameServer的最佳实践，客户端的配置方式以及JVM和linux的最佳参数配置。
+- [消息轨迹指南(Message Trace)](msg_trace/user_guide.md)：介绍RocketMQ消息轨迹的使用方法。
+- [权限管理(Auth Management)](acl/user_guide.md)：介绍如何快速部署和使用支持权限控制特性的RocketMQ集群。
+
+- [dledger快速搭建(Quick Start)](dledger/quick_start.md)：介绍Dledger的快速搭建方法。
+
+- [集群部署(Cluster Deployment)](dledger/deploy_guide.md)：介绍Dledger的集群部署方式。
+
+### 5. 运维管理
+- [集群部署(Operation)](operation.md)：介绍单Master模式、多Master模式、多Master多slave模式等RocketMQ集群各种形式的部署方法以及运维工具mqadmin的使用方式。
+
+
+
+### 6. API Reference（待补充）
+
+- [DefaultMQProducer API Reference](client/java/API_Reference_DefaultMQProducer.md)
+
+
+
+
+
+
+
diff --git a/docs/cn/RocketMQ_Example.md b/docs/cn/RocketMQ_Example.md
index 885b00a..6b06e2e 100644
--- a/docs/cn/RocketMQ_Example.md
+++ b/docs/cn/RocketMQ_Example.md
@@ -1,3 +1,5 @@
+#样例
+----
 1 基本样例
 --------
 
diff --git a/docs/cn/acl/user_guide.md b/docs/cn/acl/user_guide.md
index deeb2fa..838ed2e 100644
--- a/docs/cn/acl/user_guide.md
+++ b/docs/cn/acl/user_guide.md
@@ -1,6 +1,6 @@
 # 权限控制
-## 前言
-该文档主要介绍如何快速部署和使用支持权限控制特性的RocketMQ 集群。
+----
+
 
 ## 1.权限控制特性介绍
 权限控制（ACL）主要为RocketMQ提供Topic资源级别的用户访问控制。用户在使用RocketMQ权限控制时，可以在Client客户端通过 RPCHook注入AccessKey和SecretKey签名；同时，将对应的权限控制属性（包括Topic访问权限、IP白名单和AccessKey和SecretKey签名等）设置在distribution/conf/plain_acl.yml的配置文件中。Broker端对AccessKey所拥有的权限进行校验，校验不过，抛出异常；
diff --git a/docs/cn/architecture.md b/docs/cn/architecture.md
index 12493a6..9fc12da 100644
--- a/docs/cn/architecture.md
+++ b/docs/cn/architecture.md
@@ -1,6 +1,6 @@
 # 架构设计
-
-## 技术架构
+---
+##1 技术架构
 ![](image/rocketmq_architecture_1.png)
 
 RocketMQ架构上主要分为四部分，如上图所示:
@@ -20,7 +20,7 @@ RocketMQ架构上主要分为四部分，如上图所示:
 
 ![](image/rocketmq_architecture_2.png)
 
-## 部署架构
+##2 部署架构
 
 
 ![](image/rocketmq_architecture_3.png)
diff --git a/docs/cn/best_practice.md b/docs/cn/best_practice.md
index ffa76b9..731a24b 100755
--- a/docs/cn/best_practice.md
+++ b/docs/cn/best_practice.md
@@ -1,6 +1,6 @@
 #  最佳实践
 
-
+---
 ## 1   生产者
 
 ### 1.1 发送消息注意事项
diff --git a/docs/cn/concept.md b/docs/cn/concept.md
index ef59050..2fd22b2 100644
--- a/docs/cn/concept.md
+++ b/docs/cn/concept.md
@@ -1,37 +1,38 @@
 # 基本概念
-## 消息模型（Message Model）
+----
+## 1 消息模型（Message Model）
 
 RocketMQ主要由 Producer、Broker、Consumer 三部分组成，其中Producer 负责生产消息，Consumer 负责消费消息，Broker 负责存储消息。Broker 在实际部署过程中对应一台服务器，每个 Broker 可以存储多个Topic的消息，每个Topic的消息也可以分片存储于不同的 Broker。Message Queue 用于存储消息的物理地址，每个Topic中的消息地址存储于多个 Message Queue 中。ConsumerGroup 由多个Consumer 实例构成。
-##  消息生产者（Producer）
+## 2 消息生产者（Producer）
  负责生产消息，一般由业务系统负责生产消息。一个消息生产者会把业务应用系统里产生的消息发送到broker服务器。RocketMQ提供多种发送方式，同步发送、异步发送、顺序发送、单向发送。同步和异步方式均需要Broker返回确认信息，单向发送不需要。
-## 消息消费者（Consumer）
+##3 消息消费者（Consumer）
  负责消费消息，一般是后台系统负责异步消费。一个消息消费者会从Broker服务器拉取消息、并将其提供给应用程序。从用户应用的角度而言提供了两种消费形式：拉取式消费、推动式消费。
-## 主题（Topic）
+##4 主题（Topic）
   表示一类消息的集合，每个主题包含若干条消息，每条消息只能属于一个主题，是RocketMQ进行消息订阅的基本单位。
-##代理服务器（Broker Server）
+##5 代理服务器（Broker Server）
 消息中转角色，负责存储消息、转发消息。代理服务器在RocketMQ系统中负责接收从生产者发送来的消息并存储、同时为消费者的拉取请求作准备。代理服务器也存储消息相关的元数据，包括消费者组、消费进度偏移和主题和队列消息等。
-## 名字服务（Name Server）
+##6 名字服务（Name Server）
  名称服务充当路由消息的提供者。生产者或消费者能够通过名字服务查找各主题相应的Broker IP列表。多个Namesrv实例组成集群，但相互独立，没有信息交换。
-## 拉取式消费（Pull Consumer）
+##7 拉取式消费（Pull Consumer）
   Consumer消费的一种类型，应用通常主动调用Consumer的拉消息方法从Broker服务器拉消息、主动权由应用控制。一旦获取了批量消息，应用就会启动消费过程。
-## 推动式消费（Push Consumer）
+##8 推动式消费（Push Consumer）
  Consumer消费的一种类型，该模式下Broker收到数据后会主动推送给消费端，该消费模式一般实时性较高。
-## 生产者组（Producer Group）
+##9 生产者组（Producer Group）
   同一类Producer的集合，这类Producer发送同一类消息且发送逻辑一致。如果发送的是事物消息且原始生产者在发送之后崩溃，则Broker服务器会联系同一生产者组的其他生产者实例以提交或回溯消费。
-## 消费者组（Consumer Group）
+##10 消费者组（Consumer Group）
   同一类Consumer的集合，这类Consumer通常消费同一类消息且消费逻辑一致。消费者组使得在消息消费方面，实现负载均衡和容错的目标变得非常容易。要注意的是，消费者组的消费者实例必须订阅完全相同的Topic。RocketMQ 支持两种消息模式：集群消费（Clustering）和广播消费（Broadcasting）。
-## 集群消费（Clustering）
+##11 集群消费（Clustering）
 集群消费模式下,相同Consumer Group的每个Consumer实例平均分摊消息。
-## 广播消费（Broadcasting）
+##12 广播消费（Broadcasting）
 广播消费模式下，相同Consumer Group的每个Consumer实例都接收全量的消息。
-## 普通顺序消息（Normal Ordered Message）
+##13 普通顺序消息（Normal Ordered Message）
 普通顺序消费模式下，消费者通过同一个消费队列收到的消息是有顺序的，不同消息队列收到的消息则可能是无顺序的。
-## 严格顺序消息（Strictly Ordered Message）
+##14 严格顺序消息（Strictly Ordered Message）
 严格顺序消息模式下，消费者收到的所有消息均是有顺序的。
-## 代理服务器（Broker Server）
+##15 代理服务器（Broker Server）
 消息中转角色，负责存储消息、转发消息。代理服务器在RocketMQ系统中负责接收从生产者发送来的消息并存储、同时为消费者的拉取请求作准备。代理服务器也存储消息相关的元数据，包括消费者组、消费进度偏移和主题和队列消息等。
-## 消息（Message）
+##16 消息（Message）
 消息系统所传输信息的物理载体，生产和消费数据的最小单位，每条消息必须属于一个主题。RocketMQ中每个消息拥有唯一的Message ID，且可以携带具有业务标识的Key。系统提供了通过Message ID和Key查询消息的功能。
-## 标签（Tag）
+##17 标签（Tag）
  为消息设置的标志，用于同一主题下区分不同类型的消息。来自同一业务单元的消息，可以根据不同业务目的在同一主题下设置不同标签。标签能够有效地保持代码的清晰度和连贯性，并优化RocketMQ提供的查询系统。消费者可以根据Tag实现对不同子主题的不同消费逻辑，实现更好的扩展性。
 
diff --git a/docs/cn/design.md b/docs/cn/design.md
index 5b11912..e30b466 100644
--- a/docs/cn/design.md
+++ b/docs/cn/design.md
@@ -1,5 +1,6 @@
 
-##  设计(design)
+#  设计(design)
+---
 ### 1 消息存储
 
 ![](image/rocketmq_design_1.png)
diff --git a/docs/cn/dledger/deploy_guide.md b/docs/cn/dledger/deploy_guide.md
index faebb96..886f1e5 100644
--- a/docs/cn/dledger/deploy_guide.md
+++ b/docs/cn/dledger/deploy_guide.md
@@ -1,3 +1,5 @@
+#Dledger集群搭建
+---
 ## 前言
 该文档主要介绍如何部署自动容灾切换的 RocketMQ-on-DLedger Group。
 
diff --git a/docs/cn/dledger/quick_start.md b/docs/cn/dledger/quick_start.md
index 3d1989a..9c37b3a 100644
--- a/docs/cn/dledger/quick_start.md
+++ b/docs/cn/dledger/quick_start.md
@@ -1,3 +1,5 @@
+#Dledger快速搭建
+---
 ### 前言
 该文档主要介绍如何快速构建和部署基于 DLedger 的可以自动容灾切换的 RocketMQ 集群。
 
diff --git a/docs/cn/features.md b/docs/cn/features.md
index 4bfe944..dee2443 100644
--- a/docs/cn/features.md
+++ b/docs/cn/features.md
@@ -1,7 +1,8 @@
 # 特性(features)
-## 订阅与发布
+----
+##1 订阅与发布
 消息的发布是指某个生产者向某个topic发送消息；消息的订阅是指某个消费者关注了某个topic中带有某些tag的消息，进而从该topic消费数据。
-## 消息顺序
+##2 消息顺序
 消息有序指的是一类消息消费时，能按照发送的顺序来消费。例如：一个订单产生了三条消息分别是订单创建、订单付款、订单完成。消费时要按照这个顺序消费才能有意义，但是同时订单之间是可以并行消费的。RocketMQ可以严格的保证消息有序。
 
 顺序消息分为全局顺序消息与分区顺序消息，全局顺序是指某个Topic下的所有消息都要保证顺序；部分顺序消息只要保证每一组消息被顺序消费即可。
@@ -11,9 +12,9 @@
 - 分区顺序
 对于指定的一个 Topic，所有消息根据 sharding key 进行区块分区。 同一个分区内的消息按照严格的 FIFO 顺序进行发布和消费。 Sharding key 是顺序消息中用来区分不同分区的关键字段，和普通消息的 Key 是完全不同的概念。
 适用场景：性能要求高，以 sharding key 作为分区字段，在同一个区块中严格的按照 FIFO 原则进行消息发布和消费的场景。
-## 消息过滤
+##3 消息过滤
 RocketMQ的消费者可以根据Tag进行消息过滤，也支持自定义属性过滤。消息过滤目前是在Broker端实现的，优点是减少了对于Consumer无用消息的网络传输，缺点是增加了Broker的负担、而且实现相对复杂。
-## 消息可靠性
+##4 消息可靠性
 RocketMQ支持消息的高可靠，影响消息可靠性的几种情况：
 1) Broker正常关闭
 2) Broker异常Crash
@@ -26,15 +27,15 @@ RocketMQ支持消息的高可靠，影响消息可靠性的几种情况：
 
 5)、6)属于单点故障，且无法恢复，一旦发生，在此单点上的消息全部丢失。RocketMQ在这两种情况下，通过异步复制，可保证99%的消息不丢，但是仍然会有极少量的消息可能丢失。通过同步双写技术可以完全避免单点，同步双写势必会影响性能，适合对消息可靠性要求极高的场合，例如与Money相关的应用。注：RocketMQ从3.0版本开始支持同步双写。
 
-## 至少一次
+##5 至少一次
 至少一次(At least Once)指每个消息必须投递一次。Consumer先Pull消息到本地，消费完成后，才向服务器返回ack，如果没有消费一定不会ack消息，所以RocketMQ可以很好的支持此特性。
 
-## 回溯消费
+##6 回溯消费
 回溯消费是指Consumer已经消费成功的消息，由于业务上需求需要重新消费，要支持此功能，Broker在向Consumer投递成功消息后，消息仍然需要保留。并且重新消费一般是按照时间维度，例如由于Consumer系统故障，恢复后需要重新消费1小时前的数据，那么Broker要提供一种机制，可以按照时间维度来回退消费进度。RocketMQ支持按照时间回溯消费，时间维度精确到毫秒。
 
-## 事务消息
+##7 事务消息
 RocketMQ事务消息（Transactional Message）是指应用本地事务和发送消息操作可以被定义到全局事务中，要么同时成功，要么同时失败。RocketMQ的事务消息提供类似 X/Open XA 的分布事务功能，通过事务消息能达到分布式事务的最终一致。
-## 定时消息
+##8 定时消息
 定时消息（延迟队列）是指消息发送到broker后，不会立即被消费，等待特定时间投递给真正的topic。
 broker有配置项messageDelayLevel，默认值为“1s 5s 10s 30s 1m 2m 3m 4m 5m 6m 7m 8m 9m 10m 20m 30m 1h 2h”，18个level。可以配置自定义messageDelayLevel。注意，messageDelayLevel是broker的属性，不属于某个topic。发消息时，设置delayLevel等级即可：msg.setDelayLevel(level)。level有以下三种情况：
 
@@ -46,19 +47,20 @@ broker有配置项messageDelayLevel，默认值为“1s 5s 10s 30s 1m 2m 3m 4m 5
 
 需要注意的是，定时消息会在第一次写入和调度写入真实topic时都会计数，因此发送数量、tps都会变高。
 
-## 消息重试
+##9 消息重试
 Consumer消费消息失败后，要提供一种重试机制，令消息再消费一次。Consumer消费消息失败通常可以认为有以下几种情况：
 - 由于消息本身的原因，例如反序列化失败，消息数据本身无法处理（例如话费充值，当前消息的手机号被注销，无法充值）等。这种错误通常需要跳过这条消息，再消费其它消息，而这条失败的消息即使立刻重试消费，99%也不成功，所以最好提供一种定时重试机制，即过10秒后再重试。
 - 由于依赖的下游应用服务不可用，例如db连接不可用，外系统网络不可达等。遇到这种错误，即使跳过当前失败的消息，消费其他消息同样也会报错。这种情况建议应用sleep 30s，再消费下一条消息，这样可以减轻Broker重试消息的压力。
 
 RocketMQ会为每个消费组都设置一个Topic名称为“%RETRY%+consumerGroup”的重试队列（这里需要注意的是，这个Topic的重试队列是针对消费组，而不是针对每个Topic设置的），用于暂时保存因为各种异常而导致Consumer端无法消费的消息。考虑到异常恢复起来需要一些时间，会为重试队列设置多个重试级别，每个重试级别都有与之对应的重新投递延时，重试次数越多投递延时就越大。RocketMQ对于重试消息的处理是先保存至Topic名称为“SCHEDULE_TOPIC_XXXX”的延迟队列中，后台定时任务按照对应的时间进行Delay后重新保存至“%RETRY%+consumerGroup”的重试队列中。
-## 消息重投
+##10 消息重投
 生产者在发送消息时，同步消息失败会重投，异步消息有重试，oneway没有任何保证。消息重投保证消息尽可能发送成功、不丢失，但可能会造成消息重复，消息重复在RocketMQ中是无法避免的问题。消息重复在一般情况下不会发生，当出现消息量大、网络抖动，消息重复就会是大概率事件。另外，生产者主动重发、consumer负载变化也会导致重复消息。如下方法可以设置消息重试策略：
 
 - retryTimesWhenSendFailed:同步发送失败重投次数，默认为2，因此生产者会最多尝试发送retryTimesWhenSendFailed + 1次。不会选择上次失败的broker，尝试向其他broker发送，最大程度保证消息不丢。超过重投次数，抛出异常，由客户端保证消息不丢。当出现RemotingException、MQClientException和部分MQBrokerException时会重投。
 - retryTimesWhenSendAsyncFailed:异步发送失败重试次数，异步重试不会选择其他broker，仅在同一个broker上做重试，不保证消息不丢。
 - retryAnotherBrokerWhenNotStoreOK:消息刷盘（主或备）超时或slave不可用（返回状态非SEND_OK），是否尝试发送到其他broker，默认false。十分重要消息可以开启。
-## 流量控制
+
+## 11 流量控制
 生产者流控，因为broker处理能力达到瓶颈；消费者流控，因为消费能力达到瓶颈。
 
 生产者流控：
@@ -75,7 +77,7 @@ RocketMQ会为每个消费组都设置一个Topic名称为“%RETRY%+consumerGro
 - 消费者本地缓存消息跨度超过consumeConcurrentlyMaxSpan时，默认2000。
 
 消费者流控的结果是降低拉取频率。
-## 死信队列
+##12 死信队列
 死信队列用于处理无法被正常消费的消息。当一条消息初次消费失败，消息队列会自动进行消息重试；达到最大重试次数后，若消费依然失败，则表明消费者在正常情况下无法正确地消费该消息，此时，消息队列 不会立刻将消息丢弃，而是将其发送到该消费者对应的特殊队列中。
 
 RocketMQ将这种正常情况下无法被消费的消息称为死信消息（Dead-Letter Message），将存储死信消息的特殊队列称为死信队列（Dead-Letter Queue）。在RocketMQ中，可以通过使用console控制台对死信队列中的消息进行重发来使得消费者实例再次进行消费。
diff --git a/docs/cn/index.md b/docs/cn/index.md
deleted file mode 100644
index e69de29..0000000
diff --git a/docs/cn/msg_trace/user_guide.md b/docs/cn/msg_trace/user_guide.md
index 0320e16..828d8c0 100644
--- a/docs/cn/msg_trace/user_guide.md
+++ b/docs/cn/msg_trace/user_guide.md
@@ -1,6 +1,5 @@
 # 消息轨迹
-## 前言
-该文档主要介绍如何快速部署和使用支持消息轨迹特性的RocketMQ 集群。
+----
 
 ## 1. 消息轨迹数据关键属性
 | Producer端| Consumer端 | Broker端 |
diff --git a/docs/cn/operation.md b/docs/cn/operation.md
index ecd3707..ae85a30 100644
--- a/docs/cn/operation.md
+++ b/docs/cn/operation.md
@@ -1,4 +1,6 @@
-## 运维管理
+
+# 运维管理
+---
 
 ### 1   集群搭建