This is an automated email from the ASF dual-hosted git repository.
zhonghongsheng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/shardingsphere-on-cloud.git
The following commit(s) were added to refs/heads/main by this push:
new 94b5460 docs: add Chinese version of Pitr doc (#452)
94b5460 is described below
commit 94b5460b61e6b83fecca5d54db4e1eff4ce0e4c8
Author: liyao <[email protected]>
AuthorDate: Mon Nov 13 11:22:25 2023 +0800
docs: add Chinese version of Pitr doc (#452)
---
pitr/README-zh.md | 378 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
pitr/README.md | 29 ++++-
2 files changed, 404 insertions(+), 3 deletions(-)
diff --git a/pitr/README-zh.md b/pitr/README-zh.md
new file mode 100644
index 0000000..76947dd
--- /dev/null
+++ b/pitr/README-zh.md
@@ -0,0 +1,378 @@
+# 目录
+```shell
+使用说明
+ 前置条件
+ 服务器说明
+ 环境说明
+ 编译说明（可选）
+ SSL 配置
+ 生成新的 SSL 密钥对（可选）
+ 部署说明
+ 步骤1：获取 Pitr 二进制
+ 下载二进制包
+ 自行编译
+ 步骤2：准备 ShardingSphere Proxy 配置
+ 步骤3：配置 OpenGauss
+ 步骤4：为 Pitr Agent 部署 SSL 证书
+ 步骤5：启动 Pitr Agent
+ 测试说明
+ 准备测试数据
+ 测试用例
+ 备份
+ 恢复
+```
+
+
+# 使用说明
+
+本工具是面向 Apache ShardingSphere 和 OpenGauss
构建的分布式数据库集群提供的按时间点恢复（PITR，Point-in-time Recovery）功能的命令行工具。
+
+## 前置条件
+
+在开始之前，你需要准备如下三台服务器，并设置相关运行环境和安装所需依赖软件。这三台服务器的拓扑结构示意如下：
+
+```shell
++------------------------------+ +------------------+
+| | | OpenGauss Server |
+| Apache ShardingSphere Proxy | | Pitr Agent |
+| Apache Zookeeper | ----------> +------------------+
+| Pitr Cli (aka `gs_pitr`) | | OpenGauss Server |
+| | | Pitr Agent |
++------------------------------+ +------------------+
+```
+
+### 服务器说明
+
+你需要至少准备三台服务器，其中一台作为 Pitr 命令行工具的执行环境，它上面还会部署 Apache ShardingSphere，另外两台则用来部署
OpenGauss 和 Pitr agent。
+
+| | Role | Components |
+|:-:|:-:|:-:|
+|1| Pitr cli operation server | Pitr Cli + ShardingSphere Proxy + Zookeeper|
+|2| OpenGauss Server 1 | OpenGauss Server + Pitr Agent |
+|3| OpenGauss Server 2 | OpenGauss Server + Pitr Agent |
+
+### 环境说明
+
+在服务器都准备就绪后，你需要检查和确认如下内容：
+
+- Apache ShardingSphere 所在的服务器允许访问呢 OpenGauss 所在的服务器
+- 允许从外部访问 Apache ShardingSphere
+- 允许从外部通过 18080 端口访问 OpenGauss 服务器
+- 在 OpenGauss 服务器上设置如下环境变量：
+ - export PGDATABASE=tpccdb
+ - export PGPORT=13100
+- OpenGauss 使用用户 `omm` 并且可以访问数据库 `omm`
+- OpenGauss 开启了 `cbm tracking`
+- SSL 密钥对。用来提供 Pitr 命令行工具和 Pitr Agent 之间的安全通信，可以使用任何有效的密钥对
+
+#### 编译说明（可选）
+
+一般来说，Pitr 命令行工具，包括 cli 二进制和 agent 二进制都可以在 [Apache ShardingSphere-on-Cloud
的发布页](https://github.com/apache/shardingsphere-on-cloud/releases) 进行下载。
+
+如果希望自行编译二进制程序，你可以使用 Golang 1.20（推荐）以及 Linux
3.10.0-957.el7.x86_64（至少）作为编译环境，并按照如下步骤编译得到 Pitr 命令行工具 cli 和 agent。
+
+第一步：克隆项目
+
+```shell
+git clone [email protected]:apache/shardingsphere-on-cloud.git
+```
+
+第二步：编译 Pitr Agent
+
+```shell
+cd shardingsphere-on-cloud/pitr/agent
+make build
+```
+
+第三步：编译 Pitr Cli
+
+```shell
+cd shardingsphere-on-cloud/pitr/cli
+make build
+```
+
+### SSL 配置
+
+Pitr 命令行工具 cli 和 agent 的通信由一对 SSL 密钥对进行加密，你可以选择使用任何可用的密钥对或者生成一对新的密钥对，例如：
+
+- tls.key
+- tls.crt
+
+密钥对需要部署在 Pitr agent 所在的服务器上。
+
+#### 生成新的 SSL 密钥对（可选）
+
+如果你想要生成一对密钥对，请确保你拥有一个可用的 OpenSSL 环境。可以通过检查环境变量 OPENSSL_CONF 来查找 OpenSSL
使用的配置文件，默认的地址是 `/etc/pki/tls/openssl.cnf`。
+
+然后使用如下 `pitr/agent` 目录下的脚本并执行如下命令进行生成：
+
+```shell
+cd shardingsphere-on-cloud/pitr/agent
+make openssl-local
+```
+
+现在，正常情况下可以在 `./certs` 目录下得到一对新的密钥对。
+
+## 部署说明
+
+Pitr cli （即 `gs_pitr`）和 Pitr agent （即 `pitr-agent`）二进制都可以在[Apache
ShardingSphere on Cloud
的发布页](https://github.com/apache/shardingsphere-on-cloud/releases)下载，或者在你的环境中按前述步骤手动编译得到。
+
+整个部署过程由如下两个步骤构成：
+
+1. 根据步骤 1-2 部署 Apache ShardingSphere Proxy，Zookeeper 和 Pitr cli
+2. 根据步骤 3-5 部署 OpenGauss 和 Pitr agent
+
+### 步骤1: 获取 Pitr 二进制
+
+You can download pre-compiled Pitr tools binary release or compile them
yourself from source code.
+
+#### 下载二进制包
+
+二进制包以 .tar.gz
的文件存放在[发布页](https://github.com/apache/shardingsphere-on-cloud/releases)，你可以下载期望版本并解压得到二进制文件
`gs_pitr` 和 `pitr-agent`。
+
+#### 自行编译
+
+根据`前置条件`章节的`编译说明`小节获取具体的操作说明。
+
+在成功获取二进制文件后，你需要将 `gs_pitr` 放在和 Apache ShardingSphere Proxy 相同的服务器上，并将
`pitr-agent` 放在 OpenGauss 所在的所有服务器上。
+
+### 步骤 2: 准备 ShardingSphere Proxy 配置
+
+使用 OpenGauss 主机并替换如下配置中的 ${OPENGAUSS_SERVER_1} 和 ${OPENGAUSS_SERVER_2}：
+
+server.yaml
+
+```yaml
+mode:
+ type: Cluster
+ repository:
+ type: ZooKeeper
+ props:
+ namespace: governance
+ server-lists: localhost:2181
+ retryIntervalMilliseconds: 500
+ timeToLiveSeconds: 60
+ maxRetries: 3
+ operationTimeoutMilliseconds: 500
+
+authority:
+ users:
+ - user: root@%
+ password: root
+ - user: sharding
+ password: sharding
+ privilege:
+ type: ALL_PERMITTED
+
+globalClock:
+ enabled: true
+ type: TSO
+ provider: redis
+ props:
+ host: 127.0.0.1
+ port: 6379
+
+transaction:
+ defaultType: XA
+ providerType: Atomikos
+
+props:
+ proxy-frontend-database-protocol-type: openGauss
+
+```
+
+config-sharding.yaml
+```yaml
+databaseName: sharding_db
+dataSources:
+ ds_0:
+ url: jdbc:opengauss://${OPENGAUSS_SERVER_1}:13100/tpccdb?useSSL=false
+ username: root
+ password: root
+ connectionTimeoutMilliseconds: 30000
+ idleTimeoutMilliseconds: 60000
+ maxLifetimeMilliseconds: 1800000
+ maxPoolSize: 50
+ minPoolSize: 1
+
+ ds_1:
+ url: jdbc:opengauss://${OPENGAUSS_SERVER_2}:13100/tpccdb?useSSL=false
+ username: root
+ password: root
+ connectionTimeoutMilliseconds: 30000
+ idleTimeoutMilliseconds: 60000
+ maxLifetimeMilliseconds: 1800000
+ maxPoolSize: 50
+ minPoolSize: 1
+```
+
+然后使用脚本 `bin/start.sh` 来启动 ShardingSphere Proxy。脚本可以在
apache-shardingsphere-{version}-shardingsphere-proxy-bin.tar.gz 中找到。
+
+### 步骤 3: 配置 OpenGauss
+
+a. 在 postgres.conf 中开启 `cbm tracking`
+
+```shell
+enable_cbm_tracking = on
+```
+
+b. 执行 `gs_probackup init -B ${backup-path}` 来设置期望的备份路径
+
+然后可以启动所有的 OpenGauss 服务。
+
+
+### 步骤 4: 为 Pitr Agent 部署 SSL 证书
+
+在你启动 Pitr agent 之前，需要先为 Pitr agent 部署证书：
+
+如果 SSL 密钥对是按前述步骤自行编译的，证书文件所在的目录为
`shardingsphere-on-cloud/pitr/agent/certs`。你可以切换目录到证书目录，并执行如下命令：
+
+```shell
+scp tls.crt tls.key root@${OPENGAUSS_SERVER_1}:/home/omm/
+scp tls.crt tls.key root@${OPENGAUSS_SERVER_2}:/home/omm/
+```
+
+或者使用现有可用的密钥对同样需要将其部署到 OpenGauss 服务器上相同的路径下。
+
+### 步骤 5: 启动 Pitr Agent
+
+1. 拷贝二进制文件
+
+```shell
+cd shardingsphere-on-cloud/pitr/agent
+
+scp pitr-agent root@${OPENGAUSS_SERVER_1}:/home/omm/
+scp pitr-agent root@${OPENGAUSS_SERVER_2}:/home/omm/
+```
+
+2. 登录 OpenGauss 服务器并切换目录至 `/home/omm`
+
+这里是 `/home/omm` 目录下面的文件：
+
+```shell
+$ ll
+total 13M
+drwx------ 4 omm omm 32 Mar 2 14:22 data
+drwx------ 29 omm omm 4.0K May 23 11:37 pgdata
+-rwxr-xr-x 1 root root 13M May 16 18:25 pitr-agent
+-rwxr-xr-x 1 root root 1.1K May 16 18:26 tls.crt
+-rwxr-xr-x 1 root root 1.7K May 16 18:26 tls.key
+```
+
+3. 启动 Pitr Agent
+
+```shell
+./pitr-agent -pgdata /data/data-glt/d1 -port 18080 -tls-crt tls.crt -tls-key
tls.key -log-level debug
+```
+
+参数说明:
+- pgdata: OpenGauss 数据存储路径
+- port: Pitr agent 暴露端口
+- tls-crt: TLS 证书文件路径
+- tls-key: TLS 私钥文件路径
+- log-level: Pitr agent 日志级别
+
+## 测试说明
+
+### 准备测试数据
+
+你可以使用 `gspl` 连接到 ShardingSphere Proxy 并为测试生成数据：
+```shell
+gsql -h127.0.0.1 -p3307 -Usharding -Wsharding -d sharding_db
+```
+1. 检查存储节点
+
+```SQL
+SHOW STORAGE UNITS
+```
+
+2. 创建分片规则 `t_user`
+
+```SQL
+CREATE SHARDING TABLE RULE t_user(
+ STORAGE_UNITS(ds_0,ds_1),
+ SHARDING_COLUMN=user_id,
+ TYPE(NAME="hash_mod",PROPERTIES("sharding-count"="4"))
+);
+```
+3. 检查分片规则
+
+```SQL
+SHOW SHARDING TABLE RULE t_user;
+```
+
+4. 创建表 `t_user`
+```SQL
+CREATE TABLE t_user (
+ user_id INT NOT NULL,
+ order_id INT NOT NULL,
+ status VARCHAR(45) NULL,
+ PRIMARY KEY (user_id)
+);
+```
+
+5. 检查分表节点
+```SQL
+SHOW SHARDING TABLE NODES;
+```
+
+6. 插入测试数据
+```SQL
+insert into t_user( user_id, order_id, status) values(1,1,1);
+insert into t_user( user_id, order_id, status) values(2,2,2);
+insert into t_user( user_id, order_id, status) values(3,3,3);
+insert into t_user( user_id, order_id, status) values(4,4,4);
+
+select * from t_user;
+```
+
+### 测试用例
+
+#### 备份
+
+执行备份：
+```Shell
+./gs_pitr backup --host ${OPENGAUSS_SERVER_1} --password sharding --port 3307
--username sharding --agent-port 18080 --dn-threads-num 1 --dn-backup-path
"/home/omm/data" -b FULL
+```
+
+参数说明:
+- host: SharidngSphere Proxy 服务器
+- port: ShardingSphere Proxy 监听端口
+- username: ShardingSphere Proxy 连接用户名
+- password: ShardingSphere Proxy 连接密码
+- agent-port: Pitr Agent 监听端口
+- dn-threads-num: OpenGauss 并发备份数量
+- dn-threads-path: OpenGauss 备份文件路径
+- b: 备份模式
+
+检查备份并查看备份 id：
+```Shell
+./gs_pitr show
+```
+
+#### 恢复
+
+你需要先删除部分 `t_user` 表中的记录：
+```SQL
+delete from t_user where user_id=1;
+delete from t_user where user_id=2;
+```
+
+执行恢复：
+```Shell
+./gs_pitr restore --host ${OPENGAUSS_SERVER_1} --password sharding --port 3307
--username sharding --agent-port 18080 --dn-backup-path "/home/omm/data" --id
${BACKUP_ID}
+```
+
+参数说明:
+- host: ShardingSphere Proxy 服务器
+- port: ShardingSphere Proxy 监听端口
+- username: ShardingSphere Proxy 连接用户名
+- password: ShardingSphere Proxy 连接密码
+- agent-port: Pitr Agent 监听端口
+- dn-backup-path: OpenGauss 备份文件路径
+- id: 备份 id
+
+验证数据:
+```SQL
+select * from t_user;
+```
\ No newline at end of file
diff --git a/pitr/README.md b/pitr/README.md
index e169a3b..d1fb769 100644
--- a/pitr/README.md
+++ b/pitr/README.md
@@ -1,3 +1,26 @@
+# 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
This is a cli tool for point-in-time recovery of Apache ShardingSphere and
OpenGauss distributed database cluster.
@@ -77,11 +100,11 @@ The communication of Pitr cli and Pitr agent is secured by
TLS which needs a SSL
The key pair need to be deployed on the servers where Pitr agent and OpenGauss
are installed.
-#### Generate new TLS keypair (Optional)
+#### Generate new SSL keypair (Optional)
-If you want to generate a new key pair, please make sure you have a available
OpenSSL environment, check environment variable OPENSSL_CONF, generally it is
set to `/etc/pki/tls`.
+If you want to generate a new key pair, please make sure you have a available
OpenSSL environment, check environment variable OPENSSL_CONF, generally it is
set to `/etc/pki/tls/openssl.cnf`.
-Then using the script under Pitr agent code directory, execute the commands
below:
+Then using the script under `pitr/agent` code directory, execute the commands
below:
```shell
cd shardingsphere-on-cloud/pitr/agent
