diff --git a/pitr/README-zh.md b/pitr/README-zh.md new file mode 100644 index 00000000..76947dde --- /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 git@github.com: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 e169a3bb..d1fb769e 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