diff --git a/product/zh/docs-ptk/v0.1/config.md b/product/zh/docs-ptk/v0.1/config.md index 24492137c6a262679faf1b756aeedc5c3bbb691e..8a144c6a8df2fcb3413afb7b706807a7d521fcc7 100644 --- a/product/zh/docs-ptk/v0.1/config.md +++ b/product/zh/docs-ptk/v0.1/config.md @@ -5,8 +5,6 @@ author: Yao Qian date: 2021-09-14 --- - - # 配置文件 该文件包含介绍了安装集群所需的所有配置参数。 @@ -37,9 +35,73 @@ ptk encrypt PASSWORD ``` --- + ## Config + Config 数据库集群拓扑配置信息 +**示例**: + +- simple config example + +```yaml +# 集群级别的配置信息，其中 `db_port` 和 `ssh_option` 字段是 **可重用字段** +global: + cluster_name: DefaultCluster # 集群名称，PTK管理的集群的唯一标识 + db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入 +# 集群内的数据库实例服务器配置信息 +db_servers: + - host: 10.1.1.100 # 数据库实例服务器 IP (仅支持 IPv4) + - host: 10.1.1.101 # 数据库实例服务器 IP (仅支持 IPv4) +``` + +- complex config example + +```yaml +# 集群级别的配置信息，其中 `db_port` 和 `ssh_option` 字段是 **可重用字段** +global: + cluster_name: CustomCluster # 集群名称，PTK管理的集群的唯一标识 + user: omm # 运行数据库的操作系统用户名 + group: omm # 运行数据库的操作系统用户组 + db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入 + app_dir: /data/mogdb/app # 数据库部署文件、启动脚本和配置文件的存放路径 + data_dir: /data/mogdb/data # 数据库数据存储目录 + log_dir: /data/mogdb/log # 数据库运行日志和操作日志存储目录 + tool_dir: /data/mogdb/tool # 数据库工具目录 +# 集群内的数据库实例服务器配置信息 +db_servers: + - host: 10.1.1.100 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # 数据库主备实例日志传输 IP 列表 + ha_ips: + - 10.1.1.101 + - 10.1.1.102 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: primary # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + az_name: BJ # Available Zone (可用区) 名称 + az_priority: 1 # 可用区使用的优先级，数值越小优先级越高 + - host: 10.1.2.100 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # 数据库主备实例日志传输 IP 列表 + ha_ips: + - 10.1.2.101 + - 10.1.2.102 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: standby # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + az_name: BJ # Available Zone (可用区) 名称 + az_priority: 1 # 可用区使用的优先级，数值越小优先级越高 + - host: 10.1.2.100 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # 数据库主备实例日志传输 IP 列表 + ha_ips: + - 10.1.2.101 + - 10.1.2.102 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: cascade_standby # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + upstream_host: 10.1.2.100 # 当实例角色为 cascade_standby 时，该字段表示要跟随的上游备库 IP + az_name: SH # Available Zone (可用区) 名称 + az_priority: 2 # 可用区使用的优先级，数值越小优先级越高 +``` ### global @@ -47,6 +109,30 @@ Config 数据库集群拓扑配置信息 **描述**: 集群级别的配置信息，其中 `db_port` 和 `ssh_option` 字段是 **可重用字段**

**可重用字段**
如果实例级别设置了该字段，则对应实例使用实例级别的值；
如果实例级别未配置该字段，则继承 global 级别的字段的值。 +**示例**: + +- simple global example + +```yaml +global: + cluster_name: DefaultCluster # 集群名称，PTK管理的集群的唯一标识 + db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入 +``` + +- complex global example + +```yaml +global: + cluster_name: CustomCluster # 集群名称，PTK管理的集群的唯一标识 + user: omm # 运行数据库的操作系统用户名 + group: omm # 运行数据库的操作系统用户组 + db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入 + app_dir: /data/mogdb/app # 数据库部署文件、启动脚本和配置文件的存放路径 + data_dir: /data/mogdb/data # 数据库数据存储目录 + log_dir: /data/mogdb/log # 数据库运行日志和操作日志存储目录 + tool_dir: /data/mogdb/tool # 数据库工具目录 +``` + **新增于**: v0.1 ### db_servers @@ -55,16 +141,87 @@ Config 数据库集群拓扑配置信息 **描述**: 集群内的数据库实例服务器配置信息 -**新增于**: v0.1 +**示例**: + +- simple db servers example +```yaml +db_servers: + - host: 10.1.1.100 # 数据库实例服务器 IP (仅支持 IPv4) + - host: 10.1.1.101 # 数据库实例服务器 IP (仅支持 IPv4) +``` + +- complex db servers example + +```yaml +db_servers: + - host: 10.1.1.100 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # 数据库主备实例日志传输 IP 列表 + ha_ips: + - 10.1.1.101 + - 10.1.1.102 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: primary # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + az_name: BJ # Available Zone (可用区) 名称 + az_priority: 1 # 可用区使用的优先级，数值越小优先级越高 + - host: 10.1.2.100 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # 数据库主备实例日志传输 IP 列表 + ha_ips: + - 10.1.2.101 + - 10.1.2.102 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: standby # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + az_name: BJ # Available Zone (可用区) 名称 + az_priority: 1 # 可用区使用的优先级，数值越小优先级越高 + - host: 10.1.2.100 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # 数据库主备实例日志传输 IP 列表 + ha_ips: + - 10.1.2.101 + - 10.1.2.102 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: cascade_standby # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + upstream_host: 10.1.2.100 # 当实例角色为 cascade_standby 时，该字段表示要跟随的上游备库 IP + az_name: SH # Available Zone (可用区) 名称 + az_priority: 2 # 可用区使用的优先级，数值越小优先级越高 +``` + +**新增于**: v0.1 --- + ## Global + Global 定义配置文件中全局参数 Appears in: + - Config.global +**示例**: + +- simple global example + +```yaml +cluster_name: DefaultCluster # 集群名称，PTK管理的集群的唯一标识 +db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入 +``` + +- complex global example + +```yaml +cluster_name: CustomCluster # 集群名称，PTK管理的集群的唯一标识 +user: omm # 运行数据库的操作系统用户名 +group: omm # 运行数据库的操作系统用户组 +db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入 +app_dir: /data/mogdb/app # 数据库部署文件、启动脚本和配置文件的存放路径 +data_dir: /data/mogdb/data # 数据库数据存储目录 +log_dir: /data/mogdb/log # 数据库运行日志和操作日志存储目录 +tool_dir: /data/mogdb/tool # 数据库工具目录 +``` + ### cluster_name **类型**: string @@ -72,6 +229,9 @@ Appears in: **描述**: 集群名称，PTK管理的集群的唯一标识 **示例**: + +- cluster name example + ```yaml cluster_name: cluster1 ``` @@ -85,6 +245,9 @@ cluster_name: cluster1 **描述**: 运行数据库的操作系统用户名
默认为："omm" **示例**: + +- os user example + ```yaml user: omm ``` @@ -98,6 +261,9 @@ user: omm **描述**: 运行数据库的操作系统用户组
默认和操作系统用户同名 **示例**: + +- os user group example + ```yaml group: omm ``` @@ -127,6 +293,9 @@ group: omm **描述**: 数据库的运行端口
默认值: 26000 **示例**: + +- db port example + ```yaml db_port: 26000 ``` @@ -140,6 +309,9 @@ db_port: 26000 **描述**: 数据库部署文件、启动脚本和配置文件的存放路径
默认值: "/opt/mogdb/app" **示例**: + +- db app dir example + ```yaml app_dir: /opt/mogdb/app ``` @@ -153,6 +325,9 @@ app_dir: /opt/mogdb/app **描述**: 数据库数据存储目录
默认值: "/opt/mogdb/data" **示例**: + +- db data dir example + ```yaml data_dir: /opt/mogdb/data ``` @@ -166,6 +341,9 @@ data_dir: /opt/mogdb/data **描述**: 数据库运行日志和操作日志存储目录
默认值: "/opt/mogdb/log" **示例**: + +- db log dir example + ```yaml log_dir: /opt/mogdb/log ``` @@ -179,6 +357,9 @@ log_dir: /opt/mogdb/log **描述**: 数据库工具目录
默认值: "/opt/mogdb/tool" **示例**: + +- db tool dir example + ```yaml tool_dir: /opt/mogdb/tool ``` @@ -192,6 +373,9 @@ tool_dir: /opt/mogdb/tool **描述**: 数据库临时目录
默认值: "/tmp" **示例**: + +- db tmp dir example + ```yaml tmp_dir: /tmp ``` @@ -212,25 +396,63 @@ tmp_dir: /tmp **描述**: SSH 登录信息，登录用户需为 **root** 或者具有 sudo 权限的用户
不设置时为本地执行 -**示例**: -```yaml -ssh_option: - host: 10.1.1.100 - port: 22 - user: root - key_file: ~/.ssh/id_rsa -``` - **新增于**: v0.1 - --- + ## DBServer + DBServer 集群内的数据库实例服务器配置信息 Appears in: + - Config.db_servers +**示例**: + +- simple db servers example + +```yaml +- host: 10.1.1.100 # 数据库实例服务器 IP (仅支持 IPv4) +- host: 10.1.1.101 # 数据库实例服务器 IP (仅支持 IPv4) +``` + +- complex db servers example + +```yaml +- host: 10.1.1.100 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # 数据库主备实例日志传输 IP 列表 + ha_ips: + - 10.1.1.101 + - 10.1.1.102 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: primary # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + az_name: BJ # Available Zone (可用区) 名称 + az_priority: 1 # 可用区使用的优先级，数值越小优先级越高 +- host: 10.1.2.100 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # 数据库主备实例日志传输 IP 列表 + ha_ips: + - 10.1.2.101 + - 10.1.2.102 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: standby # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + az_name: BJ # Available Zone (可用区) 名称 + az_priority: 1 # 可用区使用的优先级，数值越小优先级越高 +- host: 10.1.2.100 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # 数据库主备实例日志传输 IP 列表 + ha_ips: + - 10.1.2.101 + - 10.1.2.102 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: cascade_standby # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + upstream_host: 10.1.2.100 # 当实例角色为 cascade_standby 时，该字段表示要跟随的上游备库 IP + az_name: SH # Available Zone (可用区) 名称 + az_priority: 2 # 可用区使用的优先级，数值越小优先级越高 +``` + ### host **类型**: string @@ -238,6 +460,9 @@ Appears in: **描述**: 数据库实例服务器 IP (仅支持 IPv4) **示例**: + +- db host ip example + ```yaml host: 10.1.1.100 ``` @@ -251,6 +476,9 @@ host: 10.1.1.100 **描述**: 数据库端口
默认为空，复用全局的端口配置 26000 **示例**: + +- db port example + ```yaml db_port: 26000 ``` @@ -264,6 +492,9 @@ db_port: 26000 **描述**: 数据库主备实例日志传输 IP 列表
默认与服务器 IP 一致 **示例**: + +- db HA ip list example + ```yaml ha_ips: - 10.1.1.100 @@ -286,13 +517,15 @@ ha_ips: **描述**: 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 **可选值**: -- primary +- primary - standby - - cascade_standby **示例**: + +- db role example + ```yaml role: primary ``` @@ -306,6 +539,9 @@ role: primary **描述**: 当实例角色为 cascade_standby 时，该字段表示要跟随的上游备库 IP **示例**: + +- cascade db upstream example + ```yaml upstream_host: 10.1.1.101 ``` @@ -319,6 +555,9 @@ upstream_host: 10.1.1.101 **描述**: Available Zone (可用区) 名称
默认值："AZ1" **示例**: + +- db az example + ```yaml az_name: AZ1 ``` @@ -337,7 +576,7 @@ az_name: AZ1 **类型**: string -**描述**: 数据库 Xlog 日志目录设置
默认值为数据库数据目录下 pg_xlog 目录 +**描述**: 数据库 Xlog 日志目录设置
默认为空，若需配置，值不能为数据目录的子目录 **新增于**: v0.1 @@ -348,6 +587,9 @@ az_name: AZ1 **描述**: 用户根据个性化需要配置数据库参数和值，该字段配置的内容将会在数据库启动前写入到 postgresql.conf 文件中 **示例**: + +- db config example + ```yaml db_conf: key: value @@ -361,29 +603,29 @@ db_conf: **描述**: SSH 登录信息，登录用户需为 **root** 或者具有 sudo 权限的用户
不设置时为本地执行 -**示例**: -```yaml -ssh_option: - host: 10.1.1.100 - port: 22 - user: root - key_file: ~/.ssh/id_rsa -``` - **新增于**: v0.1 - --- + ## SSHOption -SSHOption SSH 登录认证信息 -支持密码和密钥两种方式，二者需至少设置一种 +SSHOption SSH 登录认证信息，支持密码和密钥两种方式，二者需至少设置一种 Appears in: + - Global.ssh_option - DBServer.ssh_option - SSHOption.proxy +**示例**: + +```yaml +host: 10.1.1.100 +port: 22 +user: root +key_file: ~/.ssh/id_rsa +``` + ### host **类型**: string @@ -407,6 +649,9 @@ Appears in: **描述**: SSH 登录用户
默认值：root **示例**: + +- ssh user example + ```yaml user: root ``` @@ -420,6 +665,9 @@ user: root **描述**: SSH 登录用户密码
该字段支持明文和密文填写，推荐使用 ptk encrypt 加密后填写 **示例**: + +- ssh password example + ```yaml password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= ``` @@ -433,6 +681,9 @@ password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WW **描述**: SSH 登录密钥文件路径
默认为空 **示例**: + +- ssh key file example + ```yaml key_file: ~/.ssh/id_rsa ``` @@ -454,9 +705,13 @@ key_file: ~/.ssh/id_rsa **描述**: SSH 登录连接超时时间，支持单位 m(分),s(秒)
默认值: "1m" **示例**: + +- ssh connect timeout example + ```yaml conn_timeout: 1m ``` + ```yaml conn_timeout: 30s ``` @@ -470,9 +725,13 @@ conn_timeout: 30s **描述**: SSH 执行单条命令时的超时时间
默认值: "1m" **示例**: + +- ssh execute timeout example + ```yaml exec_timeout: 1m ``` + ```yaml exec_timeout: 30s ``` @@ -485,13 +744,4 @@ exec_timeout: 30s **描述**: 跳板服务器登录信息，如果目标服务器无法直连时，支持通过中间跳板机方式连接 -**示例**: -```yaml -proxy: - host: 10.1.1.100 - port: 22 - user: root - key_file: ~/.ssh/id_rsa -``` - **新增于**: v0.1 diff --git a/product/zh/docs-ptk/v0.1/debug.md b/product/zh/docs-ptk/v0.1/debug.md new file mode 100644 index 0000000000000000000000000000000000000000..33a89b325d0ece7e04f0b7bcbb5282b58f4ae261 --- /dev/null +++ b/product/zh/docs-ptk/v0.1/debug.md @@ -0,0 +1,36 @@ +--- +title: 故障排查 +summary: 故障排查 +author: Yao Qian +date: 2022-05-30 +--- + +## 故障排查 + +### 40xx 错误码 + +以 40XX 开头的错误码，例如（`PTK-4030`），代表用户提交的配置文件内的数据存在不合适，需用户根据具体错误码对应的提示信息，进行修正后重新执行指令。 + +### 50xxx 错误码 + +以 50XXX 开头的错误码，例如（`PTK-50000`），代表 PTK 在运行期间发生的错误类型。 + +具体的分类规划参考以下: + +```wiki +- 500XX 程序异常或未知错误 +- 501XX 集群，元数据 +- 502XX 文件或文件夹 +- 503XX 系统用户或组 +- 504XX 磁盘 +- 505XX 内存 +- 506XX 网络 +- 507XX 防火墙 +- 508XX 系统其他 +- 509XX gs_ctl 操作 +- 510XX 环境变量 +``` + +用户需根据不同的情况，查看对应的系统或运行参数。 + +如果遇到程序崩溃或存在明确的 Bug ，请及时反馈给 PTK 开发者来进行修复升级。 \ No newline at end of file diff --git a/product/zh/docs-ptk/v0.1/faq.md b/product/zh/docs-ptk/v0.1/faq.md new file mode 100644 index 0000000000000000000000000000000000000000..8c97ec932712b1f917f9e4510cdd489cbd90d797 --- /dev/null +++ b/product/zh/docs-ptk/v0.1/faq.md @@ -0,0 +1,18 @@ +--- +title: FAQ +summary: FAQ +author: Yao Qian +date: 2022-05-30 +--- + +## FAQ + +### 同一个服务器是否可以部署多个实例吗？ + +同一个服务器是可以部署多个实例的，不过由于数据库在使用时依赖环境变量，所以需要在配置数据库时通过定义不同的系统用户来隔离环境变量即可。 + +### PTK安装后，是否还支持 gs_om 操作？ + +可以。ptk 安装后的集群兼容 gs_om，生成了 gs_om 需要使用到的 `cluster_static_config`，`upgrade_version` 等文件。 + +> 注意：`gs_om`需要用户互信，需用户自行配置。 diff --git a/product/zh/docs-ptk/v0.1/install.md b/product/zh/docs-ptk/v0.1/install.md new file mode 100644 index 0000000000000000000000000000000000000000..4f65a505cc5f958a1a3f476fca0e1928c100afbe --- /dev/null +++ b/product/zh/docs-ptk/v0.1/install.md @@ -0,0 +1,52 @@ +--- +title: 软件安装 +summary: 软件安装 +author: Yao Qian +date: 2022-05-30 +--- + +## 安装 PTK + +### 在线安装 + +> 注意： +> 该方式目前不支持 Windows 系统 + +PTK 的在线安装过程非常简单，无论是 MacOS 还是 Linux 系统，执行以下指令即可自动安装成功： + +```shell +curl --proto '=https' --tlsv1.2 -sSf https://cdn-mogdb.enmotech.com/ptk/install.sh | sh +``` + +该指令会自动将 PTK 安装在 `$HOME/.ptk` 目录下，该目录以后会作为 PTK 工具的工作目录， +其产生的缓存文件、数据文件、以及集群的配置信息，备份信息等文件均会存储到该目录下。 +同时，安装指令会自动将 `$HOME/.ptk/bin` 的路径加入到对应 SHELL Profile 文件的 PATH 环境变量中， +这样在用户登录到服务器后就可以直接使用 `ptk` 指令了。 + +### 离线安装 + +如果你需要安装的服务器无法直接访问外网或者是需要在 Windows 系统上使用 PTK 工具，此时可以通过手动方式进行安装。 + +请按照以下操作步骤进行安装： + +第一步：先在个人电脑上下载你所要安装的机器的对应安装包，以下是不同系统架构的最新版的安装包下载链接: + +- MacOS ARM64: [ptk_darwin_arm64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/latest/ptk_darwin_arm64.tar.gz) +- MacOS X86: [ptk_darwin_x86_64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/latest/ptk_darwin_x86_64.tar.gz) +- Linux ARM64: [ptk_linux_arm64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/latest/ptk_linux_arm64.tar.gz) +- Linux X86: [ptk_linux_x86_64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/latest/ptk_linux_x86_64.tar.gz) +- Windows X86: [ptk_windows_x86_64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/latest/ptk_windows_x86_64.tar.gz) + +第二步：下载好安装包以后，通过内网将安装包拷贝到目标服务器上解压； + +第三步：解压后会得到一个名为 `ptk` 的二进制文件，该文件即为 PTK 的可执行文件，可以根据个人偏好，将该文件移动到合适的目录（推荐 `$HOME/.ptk/bin/` 目录，需手动创建），然后将所在所在目录添加到 PATH 环境变量中即可； + +### 升级 PTK + +如果是离线方式安装的，重新下载最新的安装包后替换覆盖服务器上的二进制文件即可升级到最新版。 + +如果是在线方式安装的，执行以下指令即可自动升级： + +```shell +ptk self upgrade +``` diff --git a/product/zh/docs-ptk/v0.1/overview.md b/product/zh/docs-ptk/v0.1/overview.md index fccb116507c76a507e44fea002488ba5eaa1fc99..9f5631fd03a23d5539619e511f68acf73a2ec960 100644 --- a/product/zh/docs-ptk/v0.1/overview.md +++ b/product/zh/docs-ptk/v0.1/overview.md @@ -5,8 +5,6 @@ author: Yao Qian date: 2022-05-30 --- -# PTK 使用文档 - ## PTK 简介 PTK (Provisioning Toolkit)是一款针对 MogDB 数据库开发的软件安装和运维工具，旨在帮助用户更便捷的部署，体验或验证 MogDB 数据库。 @@ -32,372 +30,4 @@ PTK (Provisioning Toolkit)是一款针对 MogDB 数据库开发的软件安装 | SUSE 12SP5 | x86_64 | | Ubuntu 18.04 | x86_64 | -更多操作系统适配测试中... - -## 安装 PTK - -### 在线安装 - -> 注意： -> 该方式目前不支持 Windows 系统 - -PTK 的在线安装过程非常简单，无论是 MacOS 还是 Linux 系统，执行以下指令即可自动安装成功： - -```shell -curl --proto '=https' --tlsv1.2 -sSf https://cdn-mogdb.enmotech.com/ptk/install.sh | sh -``` - -该指令会自动将 PTK 安装在 `$HOME/.ptk` 目录下，该目录以后会作为 PTK 工具的工作目录， -其产生的缓存文件、数据文件、以及集群的配置信息，备份信息等文件均会存储到该目录下。 -同时，安装指令会自动将 `$HOME/.ptk/bin` 的路径加入到对应 SHELL Profile 文件的 PATH 环境变量中， -这样在用户登录到服务器后就可以直接使用 `ptk` 指令了。 - -### 离线安装 - -如果你需要安装的服务器无法直接访问外网或者是需要在 Windows 系统上使用 PTK 工具，此时可以通过手动方式进行安装。 - -请按照以下操作步骤进行安装： - -第一步：先在个人电脑上下载你所要安装的机器的对应安装包，以下是不同系统架构的最新版的安装包下载链接: - -- MacOS ARM64: [ptk_darwin_arm64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/latest/ptk_darwin_arm64.tar.gz) -- MacOS X86: [ptk_darwin_x86_64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/latest/ptk_darwin_x86_64.tar.gz) -- Linux ARM64: [ptk_linux_arm64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/latest/ptk_linux_arm64.tar.gz) -- Linux X86: [ptk_linux_x86_64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/latest/ptk_linux_x86_64.tar.gz) -- Windows X86: [ptk_windows_x86_64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/latest/ptk_windows_x86_64.tar.gz) - -第二步：下载好安装包以后，通过内网将安装包拷贝到目标服务器上解压； - -第三步：解压后会得到一个名为 `ptk` 的二进制文件，该文件即为 PTK 的可执行文件，可以根据个人偏好，将该文件移动到合适的目录（推荐 `$HOME/.ptk/bin/` 目录，需手动创建），然后将所在所在目录添加到 PATH 环境变量中即可； - -### 升级 PTK - -如果是离线方式安装的，重新下载最新的安装包后替换覆盖服务器上的二进制文件即可升级到最新版。 - -如果是在线方式安装的，执行以下指令即可自动升级： - -```shell -ptk self upgrade -``` - -## 使用 - -当安装成功 PTK 以后，可以在终端运行 `ptk -h` 来查看帮助信息； - -```text -$ ptk -h -ptk is a command-line management tool that can help you to -deploy or manage MogDB clusters. - -Usage: - ptk [flags] [args...] - ptk [command] - -Available Commands: - env Print ptk environment information - gen-xml Generate an XML file - self Modify the ptk installation - completion Generate the autocompletion script for the specified shell - -Pre Install Commands: - checkos Check cluster servers os dependencies - encrypt Provides a convenient way to encrypt your text/password - template Print template of configuration - -Install Commands: - install Install the MogDB database cluter based on topology configuration - uninstall Uninstall a MogDB database cluster - -Post Install Commands: - ls List MogDB clusters - start Start db instance or cluster - stop Stop db instance or cluster - restart Restart db instance or cluster - status Show status of db instance or cluster - -Flags: - -f, --file string Specify a configuration file of cluster - -h, --help Help for ptk - --log-file string Specify a log output file - --log-format string Specify the log message format. Options: [text, json] (default "text") - --log-level string Specify the log level. Options: [debug, info, warning, error, panic] (default "info") - -v, --version Print version of ptk - -Use "ptk [command] --help" for more information about a command. -``` - -以下是主要的子命令： - -| 命令 | 用途 | -| ----------- | -------------------------------------------- | -| `checkos` | 检查要安装的服务器环境是否满足安装需求 | -| `template` | 安装配置模板，支持交互式创建模块 | -| `encrypt` | 加密给定字符串（用于加密密码后写入配置文件） | -| `install` | 安装数据库集群 | -| `uninstall` | 卸载数据库集群 | -| `ls` | 列出通过当前PTK工具安装的数据库集群列表 | -| `start` | 启动数据库集群或指定实例 | -| `stop` | 停止数据库集群或指定实例 | -| `restart` | 重启数据库集群或指定实例 | -| `status` | 显示数据库集群或指定实例的运行状态 | -| `query` | 查询数据库集群的主备复制状态信息 | -| `env` | 显示 PTK 支持的环境变量列表 | -| `gen-xml` | 兼容从 PTK 配置文件直接生成适用于 gs_om 的 XML 文件 | -| `self` | PTK 自身操作 | -| `completion` | 生成不同 SHELL 的自动补全脚本 | - -可以通过 `-v|--version` 参数来查看 PTK 版本信息，以下为示例： - -```shell -$ ptk -v -PTK Version: v0.1.0 -Go Version: go1.17.1 -Build Date: 2022-05-27T09:32:14Z -Git Hash: 6aba9ea -``` - -从版本信息可以得知 PTK 的版本号，编译的 Golang 版本，构建时间以及构建时的哈希值。 - -关于每个命令的帮助信息，可以通过每个子命令的 `-h` 参数查看，例如: `ptk checkos -h` - -## 系统检查 - -在安装数据库之前，你需要先对要安装数据库的服务器进行一下系统参数以及软件依赖等检查，确保安装过程可以顺利执行。 - -PTK 内置了 `checkos` 的指令来辅助你进行检查操作，在检查过程中，PTK 会对服务器上以下这些模块进行检查： - -| 类别编号 | 类别 | 检查项 | 说明 | -| -------- | ------------ | ----------------------------- | -------------------- | -| A1 | 系统版本 | Check_OS_Version | 检查系统版本 | -| A2 | 内核版本 | Check_Kernel_Version | 检查内核版本 | -| A3 | 字符集 | Check_Unicode | 检查字符集 | -| A4 | 时区 | Check_TimeZone | 检查时区 | -| A5 | 内存交换区 | Check_Swap_Memory_Configure | 检查 swap 内存配置 | -| A6 | sysctl参数 | Check_SysCtl_Parameter | 检查 sysctl 参数 | -| A7 | 文件系统 | Check_FileSystem_Configure | 检查文件系统配置 | -| A8 | 磁盘配置 | Check_Disk_Configure | 检查磁盘配置 | -| A9 | 预读块设置 | Check_BlockDev_Configure | 检查块设备配置 | -| | | Check_Logical_Block | 检查逻辑块 | -| A10 | IO调度 | Check_IO_Request | 检查 IO 请求参数 | -| | | Check_Asynchronous_IO_Request | 检查异步 IO 请求参数 | -| | | Check_IO_Configure | 检查 IO 配置 | -| A11 | 网络配置 | Check_Network_Configure | 检查网络配置 | -| A12 | 时钟一致性 | Check_Time_Consistency | 检查时钟一致性 | -| A13 | 防火墙配置 | Check_Firewall_Service | 检查防火墙配置 | -| A14 | 透明大页配置 | Check_THP_Service | 检查透明大页配置 | - -在使用 PTK 进行系统检查时，需提供一个集群配置文件（`-f`）以及指定要检查的内容（`-i`），如果不知道要检查的内容，默认会检查以上表格内的所有项目。 - -如果需要针对个别类别进行检查，可以通过以逗号连接类别编号来进行指定。 - -使用示例： - -```shell -ptk checkos -i A1,A2,A3 # 要检查多个状态，请按以下格式输入项目：“-i A1,A2,A3”。 -ptk checkos -i A # 检查全部检查项 -ptk checkos -i A --detail # 加上--detail 会显示详细信息 -``` - -PTK 的检查结果分为四个等级： - -- **OK**：符合预期值，满足安装需求 -- **Warning**: 不符合预期值，但可以满足安装需求 -- **Abnormal**: 不满足安装要求，可能会导致安装过程失败，需根据 PTK 给出的修改建议脚本，人工执行修改 -- **ExecuteError**: 执行错误，该等级表示 PTK 在检查时执行命令失败，可能为内部BUG或SSH连接错误等，不确定检查是否通过，需反馈给开发者 - -在安装数据库之前，需确保所有的检查项都在 **OK** 或 **Warning** 级别，如果存在 **Abnormal** 的检查结果，在安装时会报错退出。 - -## 数据库集群安装 - -当有了配置文件，并且系统检查也都通过后，就可以开始数据库安装了。 - -使用 PTK 安装数据库集群很简单，如果所有参数均使用默认值，安装仅需输入一下指即可： - -```shell -$ ptk install -f config.yaml -y -``` - -`-f` 指定配置文件路径，`-y` 表示自动所有交互式问询回复 Yes。（注：当配置文件中没有配置数据库初始密码时，`-y` 无法跳过询问密码流程） - -默认 PTK 会安装 PTK 发布时 MogDB 的最新版，可以通过 `ptk install -h` 查看 `--db-version` 的默认值。 - -如果你想要指定安装不同的版本或者想要安装自己编译的安装包，PTK 也是支持的。 - -PTK 安装指令提供了 `--db-version` 参数，来允许用户指定要安装的 MogDB 版本，例如：`ptk install -f config.yaml --db-version 2.0.1 -y` (支持的版本列表请查看 [MogDB 下载页](https://www.mogdb.io/downloads/mogdb/)) - -如果你希望安装自己编译的安装包或者社区的 openGauss 包，需通过 `-p|--pkg` 参数指定本地安装包路径或者网络下载地址。PTK 会自动下载后从PTK所在的机器分发到所有需要部署的机器上。 - -更多选项： - -- `-e|--env` : 环境变量将被添加到安装后的数据库系统用户的 **.bashrc** 文件中 -- `--launch-db-timeout`: 启动数据库超时时间，默认 5 分钟。 -- `--pre-run`: 支持添加安装前的一个钩子 shell 脚本路径，在集群安装前，自动在集群内所有机器上执行指定的脚本 -- `--post-run`: 支持添加安装后的一个钩子 shell 脚本路径，在集群安装成功后，自动在集群内所有机器上执行指定的脚本 -- `--skip-check-distro` : 跳过系统发行版检查，直接安装 -- `--skip-create-user`: PTK 默认会自动创建用户，指定该参数可以跳过创建用户，当指定该参数时，服务器上用户必须已经存在 -- `--skip-launch-db`: 安装完成后不启动数据库 -- `--skip-rollback`: PTK 在安装过程中如果出现错误，默认会回滚之前的所有操作来清理环境，指定该参数可以禁止回滚操作。 - -## 数据库集群卸载 - -> 注意： -> -> 操作卸载数据库集群之前，请反复确认当前集群是否确实可以卸载！ - -数据库集群的卸载仅需在 PTK 所在的服务器上执行 `ptk uninstall (-f CONFIG.YAML|--name CLUSTER_NAME)` 指令。 - -执行卸载时支持通过 config.yaml 指定集群，也可以通过集群名称来指定，使用集群名称来指定的前提是 `ptk ls` 可以正常查询到该集群。 - -在卸载前，PTK 会交互时的询问用户，以确认要删除的集群拓扑信息，确认是否要连带删除系统用户，以及确认是否要连带删除数据库数据。请在回答每一个问题时，确认你的回答，避免由于误操作导致不可恢复的数据丢失！ - -## 数据库集群管理 - -### 查看集群列表 - -当数据库集群安装成功后，可以通过 `ptk ls` 来查看当前用户已经安装过的集群列表（由于 PTK 的元数据存储于 `$HOME/.ptk` 目录下，所以仅能查看当前用户安装的，无法查看其他用户安装的集群列表）。 - -```shell -$ ptk ls - cluster_name | instances | user | data_dir -----------------+--------------------+--------+------------------- - single | 172.16.0.183:21000 | single | /opt/mogdb2/data - vmx_cluster34 | 172.16.0.114:23000 | vmx | /opt/vmx/data - | 172.16.0.190:23000 | | -``` - -可以在输出表中得到集群的名称，集群内的实例列表，运行的系统用户以及实例的数据目录。 - -一旦集群安装成功后，之后在卸载或管理操作时，PTK 支持使用 `-f` 指定配置文件来管理集群，同时也支持 `--name` 指定集群名称来管理集群。 - -### 启动/停止/重启 - -PTK 支持集群的整体启动和停止，同时也支持集群内单个实例的启停。 - -当启停集群时，需指定集群的集群名称或者集群的配置文件。通过集群名称管理集群时，必须该集群是通过 PTK 进行安装的，可以通过 `ptk ls` 查询到即可。 - -具体的启停使用示例，请参考 1.8 节。 - -### 查询集群状态 - -如果想查看数据库集群的运行状态是否正常，可以通过 `status` 子命令查看。 - -例如： - -```shell -$ ptk status --name vmx_cluster34 - -[ Cluster State ] - -cluster_name : vmx_cluster34 -cluster_state : Normal -current_az : AZ_ALL - -[ Datanode State ] - - node | node_ip | port | instance | state ---------------------+--------------+-------+----------+----------- - 6001 172.16.0.114 | 172.16.0.114 | 23000 | 6001 | P Normal - 6002 172.16.0.190 | 172.16.0.190 | 23000 | 6002 | S Normal -``` - -如果项查询更详细的主备复制状态信息，可以通过添加 `--detail` 参数。 - -## 用法示例 - -> 以下示例中 **CLUSTER_NAME** 需替换为实际的集群名 - -### 创建配置文件 - -```shell -ptk template create -o config.yaml -``` - -### 检查服务器 - -```shell -ptk checkos -f config.yaml -i A -``` - -### 安装集群 - -```shell -ptk install -f config.yaml -``` - -### 查询集群状态 - -```shell -ptk status --name CLUSTER_NAME -# 等价于 -ptk status -f config.yaml - -# 查看详细信息 -ptk status --name CLUSTER_NAME --detail -``` - -### 启停集群 - -```shell -# start -ptk start --name CLUSTER_NAME -# 等价于 -ptk start -f config.yaml -# start a node -ptk start -f config.yaml -H HOST_IP -# start a node with security-mode -ptk start -f config.yaml -H HOST_IP --security-mode on - -# stop -ptk stop --name CLUSTER_NAME -# 等价于 -ptk stop -f config.yaml -# stop a node -ptk stop -f config.yaml -H HOST_IP -# stop a node with mode(f:fast, i:immediate) -ptk stop -f config.yaml -H HOST_IP --mode f - -# restart -ptk restart --name CLUSTER_NAME -# 等价于 -ptk restart -f config.yaml -# restart a node -ptk restart -f config.yaml -H HOST_IP [--security-model on/off] [--mode f/i] -``` - -### 卸载集群 - -```shell -ptk uninstall --name CLUSTER_NAME -# 等价于 -ptk uninstall -f config.yaml -``` - -## 故障排查 - -### 40xx 错误码 - -以 40XX 开头的错误码，例如（`PTK-4030`），代表用户提交的配置文件内的数据存在不合适，需用户根据具体错误码对应的提示信息，进行修正后重新执行指令。 - -### 50xxx 错误码 - -以 50XXX 开头的错误码，例如（`PTK-50000`），代表 PTK 在运行期间发生的错误类型。 - -具体的分类规划参考以下: - -```wiki -- 500XX 程序异常或未知错误 -- 501XX 集群，元数据 -- 502XX 文件或文件夹 -- 503XX 系统用户或组 -- 504XX 磁盘 -- 505XX 内存 -- 506XX 网络 -- 507XX 防火墙 -- 508XX 系统其他 -- 509XX gs_ctl 操作 -- 510XX 环境变量 -``` - -用户需根据不同的情况，查看对应的系统或运行参数。 - -如果遇到程序崩溃或存在明确的 Bug ，请及时反馈给 PTK 开发者来进行修复升级。 \ No newline at end of file +*更多操作系统适配测试中...* diff --git a/product/zh/docs-ptk/v0.1/release.md b/product/zh/docs-ptk/v0.1/release.md index 49187138435c46e920df77375ff6eefda277f155..0a941bd70f79181bc9f23c8dfd0372617c463c35 100644 --- a/product/zh/docs-ptk/v0.1/release.md +++ b/product/zh/docs-ptk/v0.1/release.md @@ -2,12 +2,12 @@ title: 发布记录 summary: 发布记录 author: Yao Qian -date: 2022-05-30 +date: 2022-06-01 --- # 发布记录 -## v0.1.0 (2022.5.31) +## v0.1.0 (2022.6.1) - [ptk_0.1.0_linux_x86_64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/v0.1.0/ptk_0.1.0_linux_x86_64.tar.gz) - [ptk_0.1.0_linux_arm64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/v0.1.0/ptk_0.1.0_linux_arm64.tar.gz) diff --git a/product/zh/docs-ptk/v0.1/toc.md b/product/zh/docs-ptk/v0.1/toc.md index 3fdd0eea8295983b232774408368c51a302d7002..3f1f80eb126ecfc2641597d94557b295d9bb4610 100644 --- a/product/zh/docs-ptk/v0.1/toc.md +++ b/product/zh/docs-ptk/v0.1/toc.md @@ -4,6 +4,10 @@ ## PTK 文档目录 -+ [使用文档](/overview.md) -+ [配置参数说明](/config.md) ++ [关于PTK](/overview.md) ++ [软件安装](/install.md) ++ [快速上手](/usage.md) ++ [配置参数](/config.md) ++ [故障排查](/debug.md) ++ [FAQ](/faq.md) + [发布记录](/release.md) diff --git a/product/zh/docs-ptk/v0.1/usage.md b/product/zh/docs-ptk/v0.1/usage.md new file mode 100644 index 0000000000000000000000000000000000000000..e61837c336d55b096375d6299126e0efa8a55d7f --- /dev/null +++ b/product/zh/docs-ptk/v0.1/usage.md @@ -0,0 +1,298 @@ +--- +title: 快速上手 +summary: 快速上手 +author: Yao Qian +date: 2022-05-30 +--- + +## 快速上手 + +当安装成功 PTK 以后，可以在终端运行 `ptk -h` 来查看帮助信息； + +```text +$ ptk -h +ptk is a command-line management tool that can help you to +deploy or manage MogDB clusters. + +Usage: + ptk [flags] [args...] + ptk [command] + +Available Commands: + env Print ptk environment information + gen-xml Generate an XML file + self Modify the ptk installation + completion Generate the autocompletion script for the specified shell + +Pre Install Commands: + checkos Check cluster servers os dependencies + encrypt Provides a convenient way to encrypt your text/password + template Print template of configuration + +Install Commands: + install Install the MogDB database cluter based on topology configuration + uninstall Uninstall a MogDB database cluster + +Post Install Commands: + ls List MogDB clusters + start Start db instance or cluster + stop Stop db instance or cluster + restart Restart db instance or cluster + status Show status of db instance or cluster + +Flags: + -f, --file string Specify a configuration file of cluster + -h, --help Help for ptk + --log-file string Specify a log output file + --log-format string Specify the log message format. Options: [text, json] (default "text") + --log-level string Specify the log level. Options: [debug, info, warning, error, panic] (default "info") + -v, --version Print version of ptk + +Use "ptk [command] --help" for more information about a command. +``` + +以下是主要的子命令： + +| 命令 | 用途 | +| ----------- | -------------------------------------------- | +| `checkos` | 检查要安装的服务器环境是否满足安装需求 | +| `template` | 安装配置模板，支持交互式创建模块 | +| `encrypt` | 加密给定字符串（用于加密密码后写入配置文件） | +| `install` | 安装数据库集群 | +| `uninstall` | 卸载数据库集群 | +| `ls` | 列出通过当前PTK工具安装的数据库集群列表 | +| `start` | 启动数据库集群或指定实例 | +| `stop` | 停止数据库集群或指定实例 | +| `restart` | 重启数据库集群或指定实例 | +| `status` | 显示数据库集群或指定实例的运行状态 | +| `env` | 显示 PTK 支持的环境变量列表 | +| `gen-xml` | 兼容从 PTK 配置文件直接生成适用于 gs_om 的 XML 文件 | +| `self` | PTK 自身操作 | +| `completion` | 生成不同 SHELL 的自动补全脚本 | + +可以通过 `-v|--version` 参数来查看 PTK 版本信息，以下为示例： + +```shell +$ ptk -v +PTK Version: v0.1.0 +Go Version: go1.17.1 +Build Date: 2022-05-27T09:32:14Z +Git Hash: 6aba9ea +``` + +从版本信息可以得知 PTK 的版本号，编译的 Golang 版本，构建时间以及构建时的哈希值。 + +关于每个命令的帮助信息，可以通过每个子命令的 `-h` 参数查看，例如: `ptk checkos -h` + +## 系统检查 + +在安装数据库之前，你需要先对要安装数据库的服务器进行一下系统参数以及软件依赖等检查，确保安装过程可以顺利执行。 + +PTK 内置了 `checkos` 的指令来辅助你进行检查操作，在检查过程中，PTK 会对服务器上以下这些模块进行检查： + +| 类别编号 | 类别 | 检查项 | 说明 | +| -------- | ------------ | ----------------------------- | -------------------- | +| A1 | 系统版本 | Check_OS_Version | 检查系统版本 | +| A2 | 内核版本 | Check_Kernel_Version | 检查内核版本 | +| A3 | 字符集 | Check_Unicode | 检查字符集 | +| A4 | 时区 | Check_TimeZone | 检查时区 | +| A5 | 内存交换区 | Check_Swap_Memory_Configure | 检查 swap 内存配置 | +| A6 | sysctl参数 | Check_SysCtl_Parameter | 检查 sysctl 参数 | +| A7 | 文件系统 | Check_FileSystem_Configure | 检查文件系统配置 | +| A8 | 磁盘配置 | Check_Disk_Configure | 检查磁盘配置 | +| A9 | 预读块设置 | Check_BlockDev_Configure | 检查块设备配置 | +| | | Check_Logical_Block | 检查逻辑块 | +| A10 | IO调度 | Check_IO_Request | 检查 IO 请求参数 | +| | | Check_Asynchronous_IO_Request | 检查异步 IO 请求参数 | +| | | Check_IO_Configure | 检查 IO 配置 | +| A11 | 网络配置 | Check_Network_Configure | 检查网络配置 | +| A12 | 时钟一致性 | Check_Time_Consistency | 检查时钟一致性 | +| A13 | 防火墙配置 | Check_Firewall_Service | 检查防火墙配置 | +| A14 | 透明大页配置 | Check_THP_Service | 检查透明大页配置 | +| A15 | 依赖包 | Check_Dependent_Package | 检查数据库系统安装依赖 | + +在使用 PTK 进行系统检查时，需提供一个集群配置文件（`-f`）以及指定要检查的内容（`-i`），如果不知道要检查的内容，默认会检查以上表格内的所有项目。 + +如果需要针对个别类别进行检查，可以通过以逗号连接类别编号来进行指定。 + +使用示例： + +```shell +ptk checkos -i A1,A2,A3 # 要检查多个状态，请按以下格式输入项目：“-i A1,A2,A3”。 +ptk checkos -i A # 检查全部检查项 +ptk checkos -i A --detail # 加上--detail 会显示详细信息 +``` + +PTK 的检查结果分为四个等级： + +- **OK**：符合预期值，满足安装需求 +- **Warning**: 不符合预期值，但可以满足安装需求 +- **Abnormal**: 不满足安装要求，可能会导致安装过程失败，需根据 PTK 给出的修改建议脚本，人工执行修改 +- **ExecuteError**: 执行错误，该等级表示 PTK 在检查时执行命令失败，可能为内部BUG或SSH连接错误等，不确定检查是否通过，需反馈给开发者 + +在安装数据库之前，需确保所有的检查项都在 **OK** 或 **Warning** 级别，如果存在 **Abnormal** 的检查结果，在安装时会报错退出。 + +## 数据库集群安装 + +当有了配置文件，并且系统检查也都通过后，就可以开始数据库安装了。 + +使用 PTK 安装数据库集群很简单，如果所有参数均使用默认值，安装仅需输入一下指即可： + +```shell +$ ptk install -f config.yaml -y +``` + +`-f` 指定配置文件路径，`-y` 表示自动所有交互式问询回复 Yes。（注：当配置文件中没有配置数据库初始密码时，`-y` 无法跳过询问密码流程） + +默认 PTK 会安装 PTK 发布时 MogDB 的最新版，可以通过 `ptk install -h` 查看 `--db-version` 的默认值。 + +如果你想要指定安装不同的版本或者想要安装自己编译的安装包，PTK 也是支持的。 + +PTK 安装指令提供了 `--db-version` 参数，来允许用户指定要安装的 MogDB 版本，例如：`ptk install -f config.yaml --db-version 2.0.1 -y` (支持的版本列表请查看 [MogDB 下载页](https://www.mogdb.io/downloads/mogdb/)) + +如果你希望安装自己编译的安装包或者社区的 openGauss 包，需通过 `-p|--pkg` 参数指定本地安装包路径或者网络下载地址。PTK 会自动下载后从PTK所在的机器分发到所有需要部署的机器上。 + +更多选项： + +- `-e|--env` : 环境变量将被添加到安装后的数据库系统用户的 **.bashrc** 文件中 +- `--launch-db-timeout`: 启动数据库超时时间，默认 5 分钟。 +- `--pre-run`: 支持添加安装前的一个钩子 shell 脚本路径，在集群安装前，自动在集群内所有机器上执行指定的脚本 +- `--post-run`: 支持添加安装后的一个钩子 shell 脚本路径，在集群安装成功后，自动在集群内所有机器上执行指定的脚本 +- `--skip-check-distro` : 跳过系统发行版检查，直接安装 +- `--skip-create-user`: PTK 默认会自动创建用户，指定该参数可以跳过创建用户，当指定该参数时，服务器上用户必须已经存在 +- `--skip-launch-db`: 安装完成后不启动数据库 +- `--skip-rollback`: PTK 在安装过程中如果出现错误，默认会回滚之前的所有操作来清理环境，指定该参数可以禁止回滚操作。 + +## 数据库集群卸载 + +> 注意： +> +> 操作卸载数据库集群之前，请反复确认当前集群是否确实可以卸载！ + +数据库集群的卸载仅需在 PTK 所在的服务器上执行 `ptk uninstall (-f CONFIG.YAML|--name CLUSTER_NAME)` 指令。 + +执行卸载时支持通过 config.yaml 指定集群，也可以通过集群名称来指定，使用集群名称来指定的前提是 `ptk ls` 可以正常查询到该集群。 + +在卸载前，PTK 会交互时的询问用户，以确认要删除的集群拓扑信息，确认是否要连带删除系统用户，以及确认是否要连带删除数据库数据。请在回答每一个问题时，确认你的回答，避免由于误操作导致不可恢复的数据丢失！ + +## 数据库集群管理 + +### 查看集群列表 + +当数据库集群安装成功后，可以通过 `ptk ls` 来查看当前用户已经安装过的集群列表（由于 PTK 的元数据存储于 `$HOME/.ptk` 目录下，所以仅能查看当前用户安装的，无法查看其他用户安装的集群列表）。 + +```shell +$ ptk ls + cluster_name | instances | user | data_dir +----------------+--------------------+--------+------------------- + single | 172.16.0.183:21000 | single | /opt/mogdb_single/data + cluster | 172.16.0.114:23000 | cluster| /opt/mogdb_cluster/data + | 172.16.0.190:23000 | | +``` + +可以在输出表中得到集群的名称，集群内的实例列表，运行的系统用户以及实例的数据目录。 + +一旦集群安装成功后，之后在卸载或管理操作时，PTK 支持使用 `-f` 指定配置文件来管理集群，同时也支持 `--name` 指定集群名称来管理集群。 + +### 启动/停止/重启 + +PTK 支持集群的整体启动和停止，同时也支持集群内单个实例的启停。 + +当启停集群时，需指定集群的集群名称或者集群的配置文件。通过集群名称管理集群时，必须该集群是通过 PTK 进行安装的，可以通过 `ptk ls` 查询到即可。 + +具体的启停使用示例，请参考 1.8 节。 + +### 查询集群状态 + +如果想查看数据库集群的运行状态是否正常，可以通过 `status` 子命令查看。 + +例如： + +```shell +$ ptk status --name CLUSTER_NAME + +[ Cluster State ] + +cluster_name : CLUSTER_NAME +cluster_state : Normal +current_az : AZ_ALL + +[ Datanode State ] + + node | node_ip | port | instance | state +--------------------+--------------+-------+----------+----------- + 6001 172.16.0.114 | 172.16.0.114 | 23000 | 6001 | P Normal + 6002 172.16.0.190 | 172.16.0.190 | 23000 | 6002 | S Normal +``` + +如果项查询更详细的主备复制状态信息，可以通过添加 `--detail` 参数。 + +## 用法示例 + +> 以下示例中 **CLUSTER_NAME** 需替换为实际的集群名 + +### 创建配置文件 + +```shell +ptk template create -o config.yaml +``` + +### 检查服务器 + +```shell +ptk checkos -f config.yaml -i A +``` + +### 安装集群 + +```shell +ptk install -f config.yaml +``` + +### 查询集群状态 + +```shell +ptk status --name CLUSTER_NAME +# 等价于 +ptk status -f config.yaml + +# 查看详细信息 +ptk status --name CLUSTER_NAME --detail +``` + +### 启停集群 + +```shell +# start +ptk start --name CLUSTER_NAME +# 等价于 +ptk start -f config.yaml +# start a node +ptk start -f config.yaml -H HOST_IP +# start a node with security-mode +ptk start -f config.yaml -H HOST_IP --security-mode on + +# stop +ptk stop --name CLUSTER_NAME +# 等价于 +ptk stop -f config.yaml +# stop a node +ptk stop -f config.yaml -H HOST_IP +# stop a node with mode(f:fast, i:immediate) +ptk stop -f config.yaml -H HOST_IP --mode f + +# restart +ptk restart --name CLUSTER_NAME +# 等价于 +ptk restart -f config.yaml +# restart a node +ptk restart -f config.yaml -H HOST_IP [--security-model on/off] [--mode f/i] +``` + +### 卸载集群 + +```shell +ptk uninstall --name CLUSTER_NAME +# 等价于 +ptk uninstall -f config.yaml +``` \ No newline at end of file diff --git a/scripts/build_pdf.sh b/scripts/build_pdf.sh index 0018697b3a7204d7ae53e0d62a24dc6b627d6b17..83616ab9d1671de65c1101f50fa4e2d5586ee151 100755 --- a/scripts/build_pdf.sh +++ b/scripts/build_pdf.sh @@ -493,7 +493,7 @@ if [[ ${nobuild} != "no" ]]; then h1 "Build MogDB Manager" generate_manager_pdf fi - # build mogha pdf + # build ptk pdf if [[ "${build_all}" == "yes" ]] || [[ "${only_build_ptk}" == "yes" ]]; then h1 "Build PTK " generate_ptk_pdf