diff --git a/product/en/docs-ptk/v0.1/toc.md b/product/en/docs-ptk/v0.1/toc.md new file mode 100644 index 0000000000000000000000000000000000000000..84c1d0a495645036e9fb148993f8ba0e08233aaa --- /dev/null +++ b/product/en/docs-ptk/v0.1/toc.md @@ -0,0 +1,9 @@ + + +# Documentation + +## PTK Documentation + ++ [Usage](/overview.md) ++ [Configuration](/config.md) ++ [Release Note](/release.md) diff --git a/product/zh/docs-ptk/v0.1/config.md b/product/zh/docs-ptk/v0.1/config.md new file mode 100644 index 0000000000000000000000000000000000000000..24492137c6a262679faf1b756aeedc5c3bbb691e --- /dev/null +++ b/product/zh/docs-ptk/v0.1/config.md @@ -0,0 +1,497 @@ +--- +title: Configuration File +summary: Configuration File +author: Yao Qian +date: 2021-09-14 +--- + + + +# 配置文件 + +该文件包含介绍了安装集群所需的所有配置参数。 + +在安装数据库集群时，需用户提供一个描述集群拓扑的配置文件，该配置文件在 PTK 的大多数子命令中都会使用到。 + +PTK 提供了交互式创建配置文件的功能，通过运行下面的指令可以进入交互流程: + +```shell +ptk template create +``` + +你只需要按照终端提示的步骤逐步完成配置，最终会在当前文件夹下生成 config.yaml 文件。 +另外，如果想要不使用交互式创建，直接生成一个默认配置的文件，可以运行命令: + +```shell +ptk template > config.yaml +``` + +运行后可以生成一个 config.yaml 的文件，需用户根据自己的实际情况配置里面的参数。 + +在非交互式修改配置时，配置中的系统用户密码 (user_password)，数据库密码 (db_password)，SSH密码 (ssh_option.password) 或密钥口令 (ssh_option.passphrase) 等敏感字段， + +建议使用 PTK 提供的加密命令进行加密后填写： + +```shell +ptk encrypt PASSWORD +``` + +--- +## Config +Config 数据库集群拓扑配置信息 + + +### global + +**类型**: Global + +**描述**: 集群级别的配置信息，其中 `db_port` 和 `ssh_option` 字段是 **可重用字段**

**可重用字段**
如果实例级别设置了该字段，则对应实例使用实例级别的值；
如果实例级别未配置该字段，则继承 global 级别的字段的值。 + +**新增于**: v0.1 + +### db_servers + +**类型**: []DBServer + +**描述**: 集群内的数据库实例服务器配置信息 + +**新增于**: v0.1 + + +--- +## Global +Global 定义配置文件中全局参数 + +Appears in: +- Config.global + +### cluster_name + +**类型**: string + +**描述**: 集群名称，PTK管理的集群的唯一标识 + +**示例**: +```yaml +cluster_name: cluster1 +``` + +**新增于**: v0.1 + +### user + +**类型**: string + +**描述**: 运行数据库的操作系统用户名
默认为："omm" + +**示例**: +```yaml +user: omm +``` + +**新增于**: v0.1 + +### group + +**类型**: string + +**描述**: 运行数据库的操作系统用户组
默认和操作系统用户同名 + +**示例**: +```yaml +group: omm +``` + +**新增于**: v0.1 + +### user_password + +**类型**: string + +**描述**: 运行数据库的操作系统用户密码
该字段支持明文和密文填写，推荐使用 ptk encrypt 加密
默认为空，不设置 + +**新增于**: v0.1 + +### db_password + +**类型**: string + +**描述**: 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入
该字段支持明文和密文填写，推荐使用 ptk encrypt 加密 + +**新增于**: v0.1 + +### db_port + +**类型**: int + +**描述**: 数据库的运行端口
默认值: 26000 + +**示例**: +```yaml +db_port: 26000 +``` + +**新增于**: v0.1 + +### app_dir + +**类型**: string + +**描述**: 数据库部署文件、启动脚本和配置文件的存放路径
默认值: "/opt/mogdb/app" + +**示例**: +```yaml +app_dir: /opt/mogdb/app +``` + +**新增于**: v0.1 + +### data_dir + +**类型**: string + +**描述**: 数据库数据存储目录
默认值: "/opt/mogdb/data" + +**示例**: +```yaml +data_dir: /opt/mogdb/data +``` + +**新增于**: v0.1 + +### log_dir + +**类型**: string + +**描述**: 数据库运行日志和操作日志存储目录
默认值: "/opt/mogdb/log" + +**示例**: +```yaml +log_dir: /opt/mogdb/log +``` + +**新增于**: v0.1 + +### tool_dir + +**类型**: string + +**描述**: 数据库工具目录
默认值: "/opt/mogdb/tool" + +**示例**: +```yaml +tool_dir: /opt/mogdb/tool +``` + +**新增于**: v0.1 + +### tmp_dir + +**类型**: string + +**描述**: 数据库临时目录
默认值: "/tmp" + +**示例**: +```yaml +tmp_dir: /tmp +``` + +**新增于**: v0.1 + +### core_file_dir + +**类型**: string + +**描述**: 数据库 core dump 时，错误日志文件目录，设置后会修改系统配置参数 `kernel.core_pattern`
默认为空 + +**新增于**: v0.1 + +### ssh_option + +**类型**: SSHOption + +**描述**: 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 + +### host + +**类型**: string + +**描述**: 数据库实例服务器 IP (仅支持 IPv4) + +**示例**: +```yaml +host: 10.1.1.100 +``` + +**新增于**: v0.1 + +### db_port + +**类型**: int + +**描述**: 数据库端口
默认为空，复用全局的端口配置 26000 + +**示例**: +```yaml +db_port: 26000 +``` + +**新增于**: v0.1 + +### ha_ips + +**类型**: []string + +**描述**: 数据库主备实例日志传输 IP 列表
默认与服务器 IP 一致 + +**示例**: +```yaml +ha_ips: + - 10.1.1.100 +``` + +**新增于**: v0.1 + +### ha_port + +**类型**: int + +**描述**: 数据库主备实例日志传输端口
默认和数据库端口一致 + +**新增于**: v0.1 + +### role + +**类型**: string + +**描述**: 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + +**可选值**: +- primary + +- standby + +- cascade_standby + +**示例**: +```yaml +role: primary +``` + +**新增于**: v0.1 + +### upstream_host + +**类型**: string + +**描述**: 当实例角色为 cascade_standby 时，该字段表示要跟随的上游备库 IP + +**示例**: +```yaml +upstream_host: 10.1.1.101 +``` + +**新增于**: v0.1 + +### az_name + +**类型**: string + +**描述**: Available Zone (可用区) 名称
默认值："AZ1" + +**示例**: +```yaml +az_name: AZ1 +``` + +**新增于**: v0.1 + +### az_priority + +**类型**: int + +**描述**: 可用区使用的优先级，数值越小优先级越高
默认值：1 + +**新增于**: v0.1 + +### xlog_dir + +**类型**: string + +**描述**: 数据库 Xlog 日志目录设置
默认值为数据库数据目录下 pg_xlog 目录 + +**新增于**: v0.1 + +### db_conf + +**类型**: map[string]string + +**描述**: 用户根据个性化需要配置数据库参数和值，该字段配置的内容将会在数据库启动前写入到 postgresql.conf 文件中 + +**示例**: +```yaml +db_conf: + key: value +``` + +**新增于**: v0.1 + +### ssh_option + +**类型**: SSHOption + +**描述**: 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 登录认证信息 +支持密码和密钥两种方式，二者需至少设置一种 + + +Appears in: +- Global.ssh_option +- DBServer.ssh_option +- SSHOption.proxy + +### host + +**类型**: string + +**描述**: 要连接的目标服务器 IP
当该机器为跳板机时必填；
当为数据库所在机器时可以留空，会继承 db_server 的 IP
默认为空 + +**新增于**: v0.1 + +### port + +**类型**: int + +**描述**: SSH 服务端口
默认值：22 + +**新增于**: v0.1 + +### user + +**类型**: string + +**描述**: SSH 登录用户
默认值：root + +**示例**: +```yaml +user: root +``` + +**新增于**: v0.1 + +### password + +**类型**: string + +**描述**: SSH 登录用户密码
该字段支持明文和密文填写，推荐使用 ptk encrypt 加密后填写 + +**示例**: +```yaml +password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= +``` + +**新增于**: v0.1 + +### key_file + +**类型**: string + +**描述**: SSH 登录密钥文件路径
默认为空 + +**示例**: +```yaml +key_file: ~/.ssh/id_rsa +``` + +**新增于**: v0.1 + +### passphrase + +**类型**: string + +**描述**: SSH 登录密钥文件口令
该字段支持明文和密文填写，推荐使用 ptk encrypt 加密后填写
默认为空 + +**新增于**: v0.1 + +### conn_timeout + +**类型**: Duration + +**描述**: SSH 登录连接超时时间，支持单位 m(分),s(秒)
默认值: "1m" + +**示例**: +```yaml +conn_timeout: 1m +``` +```yaml +conn_timeout: 30s +``` + +**新增于**: v0.1 + +### exec_timeout + +**类型**: Duration + +**描述**: SSH 执行单条命令时的超时时间
默认值: "1m" + +**示例**: +```yaml +exec_timeout: 1m +``` +```yaml +exec_timeout: 30s +``` + +**新增于**: v0.1 + +### proxy + +**类型**: SSHOption + +**描述**: 跳板服务器登录信息，如果目标服务器无法直连时，支持通过中间跳板机方式连接 + +**示例**: +```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/overview.md b/product/zh/docs-ptk/v0.1/overview.md new file mode 100644 index 0000000000000000000000000000000000000000..fccb116507c76a507e44fea002488ba5eaa1fc99 --- /dev/null +++ b/product/zh/docs-ptk/v0.1/overview.md @@ -0,0 +1,403 @@ +--- +title: PTK 使用文档 +summary: PTK 使用文档 +author: Yao Qian +date: 2022-05-30 +--- + +# PTK 使用文档 + +## PTK 简介 + +PTK (Provisioning Toolkit)是一款针对 MogDB 数据库开发的软件安装和运维工具，旨在帮助用户更便捷的部署，体验或验证 MogDB 数据库。 + +如果用户想要运行 MogDB 或者 MogDB 的相关组件时，仅需要执行一行命令即可实现。 + +## 使用场景 + +- 新用户通过 PTK 快速体验 MogDB +- 开发人员快速启动本地环境来做代码测试、基准测试和调试他们的代码 +- DBA 日常运维使用 +- 第三方运维平台的集成 + +## 通过 PTK 支持安装 MogDB 的操作系统 + +| 操作系统 | CPU架构 | +| ----------- | -------------- | +| CentOS 7 | x86_64 | +| RedHat 7 | x86_64 | +| openEuler | x86_64/arm | +| Kylin | x86_64/arm | +| UOS V20-D/E | x86_64/arm | +| 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 new file mode 100644 index 0000000000000000000000000000000000000000..49187138435c46e920df77375ff6eefda277f155 --- /dev/null +++ b/product/zh/docs-ptk/v0.1/release.md @@ -0,0 +1,16 @@ +--- +title: 发布记录 +summary: 发布记录 +author: Yao Qian +date: 2022-05-30 +--- + +# 发布记录 + +## v0.1.0 (2022.5.31) + +- [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) +- [ptk_0.1.0_darwin_x86_64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/v0.1.0/ptk_0.1.0_darwin_x86_64.tar.gz) +- [ptk_0.1.0_darwin_arm64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/v0.1.0/ptk_0.1.0_darwin_arm64.tar.gz) +- [ptk_0.1.0_windows_x86_64.tar.gz](https://cdn-mogdb.enmotech.com/ptk/v0.1.0/ptk_0.1.0_windows_x86_64.tar.gz) diff --git a/product/zh/docs-ptk/v0.1/toc.md b/product/zh/docs-ptk/v0.1/toc.md new file mode 100644 index 0000000000000000000000000000000000000000..3fdd0eea8295983b232774408368c51a302d7002 --- /dev/null +++ b/product/zh/docs-ptk/v0.1/toc.md @@ -0,0 +1,9 @@ + + +# 文档 + +## PTK 文档目录 + ++ [使用文档](/overview.md) ++ [配置参数说明](/config.md) ++ [发布记录](/release.md) diff --git a/scripts/build_pdf.sh b/scripts/build_pdf.sh index ed290a42cb75486a9e37477061bc48e054dc216f..0018697b3a7204d7ae53e0d62a24dc6b627d6b17 100755 --- a/scripts/build_pdf.sh +++ b/scripts/build_pdf.sh @@ -331,6 +331,32 @@ function generate_mogha_pdf() { done } +ptkDocsVersions=("v0.1") + +declare -A ptkZnTitle=( \ + ["toc"]="MogDB-PTK-指南" \ +) + +declare -A ptkEnTitle=( \ + ["toc"]="MogDB-PTK-Reference" \ +) + +function generate_ptk_pdf() { + for(( i=0;i<${#mogdbDocsLanguages[@]};i++)) + do + language=${mogdbDocsLanguages[i]} + for(( j=0;j<${#ptkDocsVersions[@]};j++)) + do + version=${ptkDocsVersions[j]} + if [[ "$language" == "zh" ]]; then + _generate_docs_pdf "docs-ptk" $language $version ptkZnTitle + elif [[ "$language" == "en" ]]; then + _generate_docs_pdf "docs-ptk" $language $version ptkEnTitle + fi + done + done +} + # function _generate_docs() { # local docsName=$1 # local languages=$2 @@ -426,6 +452,7 @@ while true; do --mogha ) build_all=no;only_build_mogha=yes;shift ;; --mogdb ) build_all=no;only_build_mogdb=yes;shift ;; --manager ) build_all=no;only_build_manager=yes;shift ;; + --ptk ) build_all=no;only_build_ptk=yes;shift ;; --tex ) build_tex=yes;shift ;; * ) break ;; esac @@ -466,6 +493,11 @@ if [[ ${nobuild} != "no" ]]; then h1 "Build MogDB Manager" generate_manager_pdf fi + # build mogha pdf + if [[ "${build_all}" == "yes" ]] || [[ "${only_build_ptk}" == "yes" ]]; then + h1 "Build PTK " + generate_ptk_pdf + fi fi diff --git a/src/styles/global.css b/src/styles/global.css index 87843bdfd44c37941a199fc0b04e067ffcf4c013..56b502bdc692ce325fcc53425a28f4b166270df5 100644 --- a/src/styles/global.css +++ b/src/styles/global.css @@ -55,6 +55,9 @@ li { .w-product-icon.manager { background-image: url(./images/tools/manager.png); } +.w-product-icon.ptk { + background-image: url(./images/tools/ptk.png); +} .w-product-icon.mdb { background-image: url(./images/tools/mdb.png); } @@ -77,6 +80,9 @@ li { .w-product-icon-menu.manager { background-image: url(./images/tools/menu/manager.png); } +.w-product-icon-menu.ptk { + background-image: url(./images/tools/menu/ptk.42x42.png); +} .w-product-icon-menu.mdb { background-image: url(./images/tools/menu/mdb.png); } @@ -99,6 +105,9 @@ li { .w-product-icon-mini.manager { background-image: url(./images/tools/mini/manager.png); } +.w-product-icon-mini.ptk { + background-image: url(./images/tools/mini/ptk.64x64.png); +} .w-product-icon-mini.mdb { background-image: url(./images/tools/mini/mdb.png); } diff --git a/src/styles/images/tools/menu/ptk.42x42.png b/src/styles/images/tools/menu/ptk.42x42.png new file mode 100644 index 0000000000000000000000000000000000000000..2ddb2b1160ce2e2f8328815a087210dd251bba21 Binary files /dev/null and b/src/styles/images/tools/menu/ptk.42x42.png differ diff --git a/src/styles/images/tools/mini/ptk.64x64.png b/src/styles/images/tools/mini/ptk.64x64.png new file mode 100644 index 0000000000000000000000000000000000000000..b47a6ed2633040dd9ff0ea03348ab48aaf39aee8 Binary files /dev/null and b/src/styles/images/tools/mini/ptk.64x64.png differ diff --git a/src/styles/images/tools/ptk.png b/src/styles/images/tools/ptk.png new file mode 100644 index 0000000000000000000000000000000000000000..a88274c9da7699a69cdc18c8096369ea450ae410 Binary files /dev/null and b/src/styles/images/tools/ptk.png differ diff --git a/src/utils/config.js b/src/utils/config.js index 940dd06550cca074aa594444fa174075878c9207..ea6e6d78f2da0ea425445e5e805c9f61fd73a616 100644 --- a/src/utils/config.js +++ b/src/utils/config.js @@ -19,6 +19,12 @@ zh: '图形化管理', en: 'Graphical Management', disabled: true + }, { + label: 'PTK', + value: 'ptk', + zh: '部署运维工具', + en: 'Provisioning Toolkit', + disabled: false } ] }, @@ -102,6 +108,13 @@ disabled: false } }, + ptk: { + 'v0.1': { + value: 'v0.1', + label: 'v0.1', + disabled: false + } + }, manager: null, mtk: { 'v2.0': {