From 1ad1c4d8251f4bcb84d9daa282b3f29286872fa1 Mon Sep 17 00:00:00 2001
From: TheR1sing3un <ther1sing3un@163.com>
Date: Mon, 6 Mar 2023 22:35:38 +0800
Subject: [PATCH] docs(docs): add docs about how to update to BrokerId version

1. add docs about how to update to BrokerId version
---
 docs/cn/controller/deploy.md | 26 ++++++++++++++++++++++++++
 docs/en/controller/deploy.md | 27 +++++++++++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/docs/cn/controller/deploy.md b/docs/cn/controller/deploy.md
index 013334e77d..a091dcf690 100644
--- a/docs/cn/controller/deploy.md
+++ b/docs/cn/controller/deploy.md
@@ -136,3 +136,29 @@ Broker若设置enableControllerMode=false，则仍然以之前方式运行。若
 （2）原DLedger模式升级到Controller切换架构
 
 由于原DLedger模式消息数据格式与Master-Slave下数据格式存在区别，不提供带数据原地升级的路径。在部署多组Broker的情况下，可以禁写某一组Broker一段时间（只要确认存量消息被全部消费即可，比如根据消息的保存时间来决定），然后清空store目录下除config/topics.json、subscriptionGroup.json下（保留topic和订阅关系的元数据）的其他文件后，进行空盘升级。
+
+### 持久化BrokerID版本的升级注意事项
+
+目前版本支持采用了新的持久化BrokerID版本的高可用架构，从该版本前的5.x升级到当前版本需要注意如下事项。
+
+4.x版本升级遵守上述流程即可。
+5.x非持久化BrokerID版本升级到持久化BrokerID版本按照如下流程:
+
+**升级Controller**
+
+1. 将旧版本Controller组停机。
+2. 清除Controller数据，即默认在`~/DLedgerController`下的数据文件。
+3. 上线新版Controller组。
+
+> 在上述升级Controller流程中，Broker仍可正常运行，但无法切换。
+
+**升级Broker**
+
+1. 将Broker从节点停机。
+2. 将Broker主节点停机。
+3. 将所有的Broker的Epoch文件删除，即默认为`~/store/epochFileCheckpoint`和`~/store/epochFileCheckpoint.bak`。
+4. 将原先的主Broker先上线，等待该Broker当选为master。(可使用`admin`命令的`getSyncStateSet`来观察)
+5. 将原来的从Broker全部上线。
+
+> 建议停机时先停从再停主，上线时先上原先的主再上原先的从，这样可以保证原来的主备关系。
+> 若需要改变升级前后主备关系，则需要停机时保证主、备的CommitLog对齐，否则可能导致数据被截断而丢失。
\ No newline at end of file
diff --git a/docs/en/controller/deploy.md b/docs/en/controller/deploy.md
index bba79607e4..84849510ef 100644
--- a/docs/en/controller/deploy.md
+++ b/docs/en/controller/deploy.md
@@ -108,3 +108,30 @@ From the compatibility statements above, it can be seen that NameServer can be u
 2. Upgrade from DLedger mode to Controller switching architecture
 
    Due to the differences in the format of message data in DLedger mode and Master-Slave mode, there is no in-place upgrade with data. In the case of deploying multiple groups of Brokers, it is possible to disable writing to a group of Brokers for a certain period of time (as long as it is confirmed that all existing messages have been consumed), and then upgrade and deploy the Controller and new Brokers. In this way, the new Brokers will consume messages from the existing Brokers and the existing Brokers will consume messages from the new Brokers until the consumption is balanced, and then the existing Brokers can be decommissioned.
+
+### Upgrade considerations for persistent BrokerID version
+
+The current version supports a new high-availability architecture with persistent BrokerID version. Upgrading from version 5.x to the current version requires the following considerations:
+
+For version 4.x, follow the above procedure to upgrade.
+
+For upgrading from non-persistent BrokerID version in 5.x to persistent BrokerID version, follow the procedure below:
+
+**Upgrade Controller**
+
+1. Stop the old version Controller group.
+2. Clear Controller data, i.e., data files located in `~/DLedgerController` by default.
+3. Bring up the new version Controller group. 
+
+> During the Controller upgrade process, Broker can still run normally but cannot failover.
+
+**Upgrade Broker**
+
+1. Stop the secondary Broker.
+2. Stop the primary Broker.
+3. Delete all Epoch files of all Brokers, i.e., `~/store/epochFileCheckpoint` and `~/store/epochFileCheckpoint.bak` by default.
+4. Bring up the original primary Broker and wait for it to be elected as master (you can use the `getSyncStateSet` command of admin to observe).
+5. Bring up all the original secondary Brokers.
+
+> It is recommended to stop the secondary Broker before stopping the primary Broker and bring up the original primary Broker before the original secondary during the online process. This can ensure the original primary-secondary relationship.
+> If you need to change the primary-secondary relationship before and after the upgrade, make sure that the CommitLog of the primary and secondary are aligned when shutting down. Otherwise, data may be truncated and lost.
\ No newline at end of file