Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add Chinese version of Pitr doc #452

Merged
merged 2 commits into from
Nov 13, 2023
Merged

docs: add Chinese version of Pitr doc #452

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b92e073
docs: add README Chinese version[D
mlycore Nov 13, 2023
6427130
docs: add content
mlycore Nov 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
378 changes: 378 additions & 0 deletions pitr/README-zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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;
```
Loading
Loading