docs: add usage restriction introduction of Pitr (apache#453)

* docs: adjust content style * docs: add restriction of Pitr
mlycore · Nov 15, 2023 · ce37e06 · ce37e06
1 parent c61169c
commit ce37e06
Show file tree

Hide file tree

Showing 2 changed files with 60 additions and 40 deletions.
diff --git a/pitr/README-zh.md b/pitr/README-zh.md
@@ -1,33 +1,33 @@
 # 目录
 ```shell
 使用说明
-  前置条件
-    服务器说明
-    环境说明
-      编译说明（可选）
-    SSL 配置
-      生成新的 SSL 密钥对（可选）
-  部署说明
-    步骤1：获取 Pitr 二进制
-      下载二进制包
-      自行编译
-    步骤2：准备 ShardingSphere Proxy 配置
-    步骤3：配置 OpenGauss
-    步骤4：为 Pitr Agent 部署 SSL 证书
-    步骤5：启动 Pitr Agent
-  测试说明
-    准备测试数据
-    测试用例
-      备份
-      恢复
+    前置准备
+        服务器说明
+        环境说明
+            编译说明（可选）
+        SSL 配置
+            生成新的 SSL 密钥对（可选）
+    部署说明
+        步骤1：获取 Pitr 二进制
+            下载二进制包
+            自行编译
+        步骤2：准备 ShardingSphere Proxy 配置
+        步骤3：配置 OpenGauss
+        步骤4：为 Pitr Agent 部署 SSL 证书
+        步骤5：启动 Pitr Agent
+    测试说明
+        准备测试数据
+        测试用例
+            备份
+            恢复
 ```
 
 
 # 使用说明 
 
 本工具是面向 Apache ShardingSphere 和 OpenGauss 构建的分布式数据库集群提供的按时间点恢复（PITR，Point-in-time Recovery）功能的命令行工具。
 
-## 前置条件 
+## 前置准备
 
 在开始之前，你需要准备如下三台服务器，并设置相关运行环境和安装所需依赖软件。这三台服务器的拓扑结构示意如下：
 
@@ -375,4 +375,14 @@ delete from t_user where user_id=2;
 验证数据:
 ```SQL
 select * from t_user;
-```
+```
+
+# 使用限制
+
+- 全局备份任务需要在没有进行中的事务的时间点进行开启，由 ShardingSphere 来加锁保证
+- ShardingSphere 备份元数据存储在 Pitr cli 本地，如果需要另一台设备上需要恢复，需要复制对应备份数据到对应设备
+- 恢复操作需要停机，并且为同步操作，用户需保证完全恢复成功
+- 恢复前后 OpenGauss 数据节点的 IP 地址和端口需保持不变
+- 多个 Pitr cli 客户端同时操作，只有一个 Pitr cli 客户端可执行成功
+- 当恢复失败时，OpenGauss 数据节点存在状态不一致，需用户重新发起恢复操作，保证最终恢复成功
+- 恢复时，保证 ShardingSphere 备份和恢复的版本一致，确保元数据兼容
diff --git a/pitr/README.md b/pitr/README.md
@@ -1,24 +1,25 @@
 # Content
 ```shell
-  Prerequisition 
-    Servers
-    Environment 
-      Compilation (optional) 
-    SSL Configurations 
-      Generate new SSL keypair (Optional) 
-  Deployment 
-    Step 1: Get Pitr tools 
-      Get binary release 
-      Compile it yourself 
-    Step 2: Get ShardingSphere Proxy Configurations 
-    Step 3: Set OpenGauss Configurations
-    Step 4: Deploy SSL certs for Pitr Agent  
-    Step 5: Start Pitr Agent 
-  Test
-    Prepare Test Data 
-    Test Case 
-      Backup
-      Recovery 
+README
+    Prerequisition 
+        Servers
+        Environment 
+            Compilation (optional) 
+        SSL Configurations 
+            Generate new SSL keypair (Optional) 
+    Deployment 
+        Step 1: Get Pitr tools 
+            Get binary release 
+            Compile it yourself 
+        Step 2: Get ShardingSphere Proxy Configurations 
+        Step 3: Set OpenGauss Configurations
+        Step 4: Deploy SSL certs for Pitr Agent  
+        Step 5: Start Pitr Agent 
+    Test
+        Prepare Test Data 
+        Test Case 
+            Backup
+            Recovery 
 ```
 
 # README
@@ -378,3 +379,12 @@ Verify data:
 select * from t_user;
 ```
 
+# Restrictions
+
+- Global backup tasks need to be executed while there is no uncommitted transaction, and this will be ensuranced by ShardingSphere lock.
+- The backup metadata of ShardingSphere will be stored on the same host with the Pitr cli. You need to copy this metadata backup to the another host first where you want to start recovery.
+- The recovery operation need to stop service, and it is a synchonized operation. Users have to make sure the success of the recovery operation.
+- OpenGauss data nodes should use the same IP and port while backup and recovery
+- Only one Pitr cli could successfully if multiple cli are executed simutaneously
+- OpenGauss servers may under inconsistent status if recovery fails. Users need to try to recovery again until it is succeed.
+- Using the same version of ShardingSphere while backup and recovery to make sure the metadata is compatible.