diff --git a/product/zh/docs-ptk/v0.6/command.md b/product/zh/docs-ptk/v0.6/command.md new file mode 100644 index 0000000000000000000000000000000000000000..977f6d8e3b8e67de3e45afa6b91e5d9ef3353926 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/command.md @@ -0,0 +1,75 @@ +--- +title: PTK命令参考 +summary: PTK命令参考 +author: Yao Qian +date: 2022-06-28 +--- + +## PTK + +PTK是一款部署和管理MogDB数据库集群的命令行工具 + +## 语法 + +```shell +ptk [flags] [args...] +``` + +## 全局选项 + +全局选项可以被应用到 PTK 下的任意子命令中 + +### -f, --file string + +- 指定集群配置文件 +- 数据类型：字符串 +- 用户在安装数据库时需明确指定拓扑配置文件路径，该配置可以通过 [`ptk template`](commands/ptk-template.md) 子命令创建。 + +### --log-file string + +- 运行日志输出到文件路径 +- 数据类型：字符串 +- 该选项默认为空，指定该选项时，PTK会在终端输出日志的同时输出日志到指定文件中。 + +### --log-format string + +- 指定日志的输出格式 +- 数据类型：字符串 +- PTK 的日志输出类型目前仅支持 `text` 文本格式和 `json` JSON格式 +- 默认值："text" + +### --log-level string + +- 指定输出日志的级别 +- 数据类型：字符串 +- 支持的日志级别有： [debug, info, warning, error, panic] +- 默认值："info" + +### -v, --version + +- 显示 PTK 的版本信息 +- 数据类型：布尔值 +- 默认值：false + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 更多子命令 + +* [ptk candidate](./commands/ptk-candidate.md) - 打印 PTK 支持的软件版本列表 +* [ptk checkos](./commands/ptk-checkos.md) - 检查集群服务器系统依赖是否满足安装数据库需求 +* [ptk encrypt](./commands/ptk-encrypt.md) - 提供一个便捷的方式来加密您的文本或密码 +* [ptk env](./commands/ptk-env.md) - 打印 PTK 环境变量信息 +* [ptk install](./commands/ptk-install.md) - 基于给定的拓扑配置部署MogDB数据库集群 +* [ptk ls](./commands/ptk-ls.md) - 列出所有MogDB集群列表 +* [ptk self](./commands/ptk-self.md) - 操作 PTK 自身安装包 +* [ptk cluster](./commands/ptk-cluster.md) -数据库集群操作 +* [ptk template](./commands/ptk-template.md) - 打印配置模板 +* [ptk uninstall](./commands/ptk-uninstall.md) - 卸载 MogDB 数据库集群 +* [ptk gen-om-xml](./commands/ptk-gen-om-xml.md) - 生成 gs_om 的 XML 配置文件 +* [ptk version](./commands/ptk-version.md) - 打印 PTK 版本 +* [ptk register](./commands/ptk-register.md) - 注册PTK系统内置类型 +* [ptk exec]((./commands/ptk-exec.md)) - 分发shell指令或脚本 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-candidate-cpu.md b/product/zh/docs-ptk/v0.6/commands/ptk-candidate-cpu.md new file mode 100644 index 0000000000000000000000000000000000000000..ff6c33efb873a4ac018234f9cd9cf5e5954eaf35 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-candidate-cpu.md @@ -0,0 +1,28 @@ +--- +title: "ptk candidate cpu" +summary: ptk candidate cpu +author: ptk +date: 2022-9-14 +--- + +## ptk candidate cpu + +列出支持的CPU型号名称 + +## 语法 + +```shell +ptk candidate cpu [flags] +``` + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +输出含有 `cpu model` 字段的表格 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-candidate-db.md b/product/zh/docs-ptk/v0.6/commands/ptk-candidate-db.md new file mode 100644 index 0000000000000000000000000000000000000000..dfa57e59fb08f063e1c00dc82b6d9a0f7e1fca1a --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-candidate-db.md @@ -0,0 +1,28 @@ +--- +title: "ptk candidate db" +summary: ptk candidate db +author: ptk +date: 2022-6-28 +--- + +## ptk candidate db + +列出支持安装的 MogDB 数据库版本列表 + +## 语法 + +```shell +ptk candidate db [flags] +``` + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +输出含有 `software` 和 `version` 字段的表格 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-candidate-os.md b/product/zh/docs-ptk/v0.6/commands/ptk-candidate-os.md new file mode 100644 index 0000000000000000000000000000000000000000..a40c93ff43678013bd2dcebdc0a137317cf1f625 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-candidate-os.md @@ -0,0 +1,28 @@ +--- +title: "ptk candidate os" +summary: ptk candidate os +author: ptk +date: 2022-6-28 +--- + +## ptk candidate os + +列出支持安装 MogDB 的操作系统 + +## 语法 + +```shell +ptk candidate os [flags] +``` + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +输出含有 `id`, `os` 和 `test versions`字段的表格 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-candidate.md b/product/zh/docs-ptk/v0.6/commands/ptk-candidate.md new file mode 100644 index 0000000000000000000000000000000000000000..f7c93576906d862d3882a3bde4112b9515b748f4 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-candidate.md @@ -0,0 +1,33 @@ +--- +title: "ptk candidate" +summary: ptk candidate +author: ptk +date: 2022-6-28 +--- + +## ptk candidate + +PTK 支持程度参考 + +## 语法 + +```shell +ptk candidate [flags] [command] +``` + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +输出 candiade 帮助信息 + +## 更多子命令 + +- [ptk candidate db](ptk-candidate-db.md) - 列出支持安装的 MogDB 数据库版本列表 +- [ptk candidate os](ptk-candidate-os.md) - 列出支持安装 MogDB 的操作系统 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-checkos.md b/product/zh/docs-ptk/v0.6/commands/ptk-checkos.md new file mode 100644 index 0000000000000000000000000000000000000000..533e9807382483881e18cbe0b109dd43ba72eae7 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-checkos.md @@ -0,0 +1,94 @@ +--- +title: "ptk checkos" +summary: ptk checkos +author: ptk +date: 2022-6-28 +--- + +## ptk checkos + +检查集群服务器系统参数或依赖是否满足安装数据库需求。 + +当检查结果中存在警告或异常时，PTK会自动在当前文件夹下生成一个 `root_fix_os.sh` 的 shell 修复脚本，里面包含了针对异常检查项的修复建议代码，用户可直接拷贝到终端执行修复。注意：多个机器时，该脚本中会包含所有机器的修复建议，需用户自己拷贝到对应服务器上执行。 + +PTK 支持以下检查项： + +- A1：操作系统版本 +- A2：内核版本 +- A3：字符集编码 +- A4：时区 +- A5：内存信息 +- A6：系统控制参数 +- A7：文件系统配置 +- A8：磁盘配置 +- A9：预读块大小 +- A10：IO 调度配置 +- A11：网卡配置 +- A12：时钟一致性 +- A13：防火墙状态 +- A14：透明大页配置 +- A15：系统依赖包 +- A16：CPU 指令集 + +默认检查全部项目，如果要指定具体的项目检查，可以通过 `-i` 选项指定具体的项目编号，多个项目编号以逗号分隔。 + +## 语法 + +```shell +ptk checkos [flags] +``` + +## 选项 + +### -i, --item string + +- 指定检查项目编号，多个编号间使用英文逗号分隔 +- 数据类型：字符串 +- 该选项默认指定全部检查项 + +### -o, --output string + +- 指定检查结果输出的文件路径 +- 数据类型：字符串 +- 该选项默认为空，结果会输出到标准输出 + +### --detail + +- 显示每个检查项的详细信息 +- 数据类型：布尔值 +- 该选项默认关闭，在命令中添加该选项可开启此功能 + +### --gen-warning-fix + +- 输出 abnormal 和 warning 项目的修复语句 +- 数据类型：布尔值 +- 该选项默认关闭，默认仅输出 abnormal 的项目修复语句 + +### --only-abnormal-detail + +- 仅显示Abnormal级别的错误信息 +- 数据类型：布尔值 +- 该选项默认关闭，默认包含Warning和Abnormal级别的错误信息，在命令中添加该选项可开启此功能 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +输出检查过程的日志信息，最后输出检查结果的表格。 + +检查结果级别分为4个等级： + +- `Normal`: 正常，无需处理 +- `Warning`: 警告，可根据情况处理，不处理也不影响安装和使用，但不是最佳实践 +- `Abnormal`: 异常，该级别的错误需用户根据生成的建议脚本修复，否则数据库可能启动失败 +- `ExecuteError`: 执行异常，该级别为内部代码运行异常，建议反馈给工程师处理解决 + +检查结果的表格包含以下字段： + +- Item: 检查项的名称 +- Level: 检查结果级别 +- (Message): 该字段默认不展示，当添加了 `--detail` 选项时展示，显示对应级别不同服务器上详细的异常信息 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-build.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-build.md new file mode 100644 index 0000000000000000000000000000000000000000..abfb1eb0b2cfd57da9ed74e8ecf7e4c39b9518ed --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-build.md @@ -0,0 +1,30 @@ +--- +title: "ptk cluster build" +summary: ptk cluster build +author: Jerad.K +date: 2023-01-10 +--- + +# ptk cluster build + +查看数据库参数信息 + +## 语法 + +ptk cluster build [flags] + +## 选项 + +### -n, --name string + +- 集群名称 +- 数据类型：字符串 + +### -H, --host string + +- 指定要build的实例IP +- 数据类型：字符串 + +## 输出 + +指定的host构建成功或失败 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-failover.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-failover.md new file mode 100644 index 0000000000000000000000000000000000000000..b722046505f3d947d743a0b51555d88833fa8a7b --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-failover.md @@ -0,0 +1,26 @@ +--- +title: "ptk cluster failover" +summary: ptk cluster failover +author: ptk +date: 2022-08-01 +--- + +# ptk cluster failover + +查看数据库参数信息 + +## 语法 + +ptk cluster failover [flags] + +## 选项 + +### -n, --name string + +- 集群名称 +- 数据类型：字符串 + +### -H, --host string + +- 指定要failover的实例IP +- 数据类型：字符串 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-install-mogha.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-install-mogha.md new file mode 100644 index 0000000000000000000000000000000000000000..17972330131af175cfc1fa847e5cb4ef730ba9a8 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-install-mogha.md @@ -0,0 +1,41 @@ +--- +title: "ptk cluster install-mogha" +summary: ptk cluster install-mogha +author: ptk +date: 2022-08-01 +--- + +## ptk cluster install-mogha + +安装MogDB插件 + +## 语法 + +ptk cluster -n CLUSTER_NAME install-mogha [flags] + +## 选项 + +### -n, --name string + +- 集群名称 +- 数据类型：字符串 + +### -d, --install-dir string + +- 指定 MogHA 安装目录 +- 数据类型：字符串 + +### -p, --mogha-pkg string + +- 指定 MogHA 本地安装包路径 +- 数据类型：字符串 + +### -c, --node-conf string + +- 指定 MogHA 配置文件路径 +- 数据类型：字符串 + +### --skip-start + +- 不启动 MogHA 服务 +- 数据类型：布尔值 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-install-plugin.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-install-plugin.md new file mode 100644 index 0000000000000000000000000000000000000000..ce9cca6a6e8e5e8e1cc69915fed7749150cf69c0 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-install-plugin.md @@ -0,0 +1,54 @@ +--- +title: "ptk cluster install-plugin" +summary: ptk cluster install-plugin +author: ptk +date: 2022-08-01 +--- + +## ptk cluster install-plugin + +安装MogDB插件 + +## 语法 + +ptk cluster install-plugin [flags] + +## 选项 + +### -H, --host strings + +- 指定待安装的主机 IP +- 数据类型：字符串 +- 默认将安装到集群中的所有主机 +- 可以多次指定 + +### -n, --name string + +- 集群名称 +- 数据类型：字符串 + +### --override + +- 是否覆盖现有插件文件 +- 数据类型：布尔值 + +### -p, --pkg string + +- 本地插件包路径，适用于离线安装 +- 数据类型：字符串 + +### -P, --plugin strings + +- 指定要安装的插件名称，默认会安装所有插件 +- 数据类型：字符串 +- 可以多次指定 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +操作日志 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-modify-comment.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-modify-comment.md new file mode 100644 index 0000000000000000000000000000000000000000..a941d225d5c796a7b8bde11d07e6d99587693a2e --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-modify-comment.md @@ -0,0 +1,26 @@ +--- +title: "ptk cluster modify-comment" +summary: ptk cluster modify-comment +author: ptk +date: 2022-08-01 +--- + +## ptk cluster modify-comment + +修改集群备注信息 + +## 语法 + +ptk cluster -n CLUSTER_NAME modify-comment [flags] + +## 选项 + +### -n, --name string + +- 集群名称 +- 数据类型：字符串 + +### --comment string + +- 新的备注信息 +- 数据类型：字符串 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-refresh.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-refresh.md new file mode 100644 index 0000000000000000000000000000000000000000..d578a10b088aa338c708e8773784571b3f5c3c91 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-refresh.md @@ -0,0 +1,35 @@ +--- +title: "ptk cluster refresh" +summary: ptk cluster refresh +author: ptk +date: 2022-08-01 +--- + +# ptk cluster refresh + +更新集群配置信息，主要用于集群内实例IP进行变更的场景。 + +> 注意：当在执行刷新变更IP时，需确保新IP和旧IP在目标机器均同时在线，待刷新配置完成后，再将旧IP进行卸载 + +本指令将会更新数据库实例的以下配置文件： + +- cluster_static_config +- postgresql.conf +- pg_hba.conf + +## 语法 + +ptk cluster refresh [flags] + +## 选项 + +### -n, --name string + +- 集群名称 +- 数据类型：字符串 + +### --replace-ip stringArray + +- 替换 db_server IP映射字符串, 格式为: old_ip=new_ip +- 数据类型：字符串 +- 可以多次指定 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-restart.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-restart.md new file mode 100644 index 0000000000000000000000000000000000000000..8e65fae910fa814d8999d0d4d05726e44edff357 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-restart.md @@ -0,0 +1,53 @@ +--- +title: "ptk cluster restart" +summary: ptk cluster restart +author: ptk +date: 2022-06-28 +--- + +## ptk cluster restart + +重启数据库集群或实例 + +## 语法 + +```shell +ptk cluster restart -n string [flags] +``` + +## 选项 + +### -n, --name string + +- 要操作的集群名称 +- 数据类型：字符串 + +### -H, --host string + +- 要操作的实例IP +- 数据类型：字符串 +- 该选项是为了支持允许查询单个实例的状态，默认查询整个集群的所有实例状态 + +### --security-mode string + +- 是否使用安全模式启动数据库 +- 数据类型：字符串 +- 可选项：on/off +- 默认值：off + +### --time-out duration + +- 执行超时时间 +- 数据类型：Duration +- Duration 类型支持的单位："h" 小时, "m" 分支, "s" 秒, "ms" +- 默认值："2m" + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +运行状态日志 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-scale-in.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-scale-in.md new file mode 100644 index 0000000000000000000000000000000000000000..7e1f90cfcb2f5a8e9442c55b3d4bb6975fcd4547 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-scale-in.md @@ -0,0 +1,55 @@ +--- +title: "ptk cluster scale-in" +summary: ptk cluster scale-in +author: ptk +date: 2022-08-01 +--- + +## ptk cluster scale-in + +对一个MogDB集群进行缩容 + +## 语法 + +```shell +ptk cluster -n CLUSTER_NAME scale-in -H HOST_IP [--stop-db] [--clear-user] [--clear-dir] [--clear-env] [-t 120] + +``` + +## 选项 + +### -n, --name string + +- 要操作的集群名称 +- 数据类型：字符串 + +### -H, --host strings + +- 要移除的机器IP +- 数据类型：字符串 +- 可以多次指定 + +### --force + +- 如果无法通过ssh连接目标主机，强制从集群升级节点的配置中删除目标实例 +- 数据类型： 布尔值 + +### --skip-clear-user + +- 不删除系统用户 +- 数据类型：布尔值 + +### --skip-clear-db + +- 不清理数据库相对目录 +- 数据类型：布尔值 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +操作日志 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-scale-out.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-scale-out.md new file mode 100644 index 0000000000000000000000000000000000000000..0cf78a2c88a156b8b65306ed9d6e48836e644c16 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-scale-out.md @@ -0,0 +1,69 @@ +--- +title: "ptk cluster scale-out" +summary: ptk cluster scale-out +author: ptk +date: 2022-08-01 +--- + +## ptk cluster scale-out + +对一个MogDB集群进行扩容 + +## 语法 + +```shell +ptk cluster -n CLUSTER_NAME scale-out -c scale-out.yaml [--skip-check-distro] [--skip-check-os] [--skip-create-user] [--skip-rollback] + +``` + +## 选项 + +### -n, --name string + +- 要操作的集群名称 +- 数据类型：字符串 + +### -c, --config string + +- 扩缩容配置文件路径 +- 数据类型：字符串 + +### --cpu string + +- 指定 CPU 厂商类型，通过 ptk candidate cpu 查看支持的列表 +- 数据类型：字符串 + +### --default-guc + +- 不自动优化 GUC 参数，使用数据库默认参数 +- 数据类型：布尔值 + +### --skip-check-distro + +- 跳过检查系统发行版 +- 数据类型：布尔值 + +### --skip-check-os + +- 跳过检查系统 +- 数据类型：布尔值 + +### --skip-create-user + +- 跳过创建用户 +- 数据类型：布尔值 + +### --skip-rollback + +- 扩容的失败的节点不做回滚操作 +- 数据类型：布尔值 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +操作日志 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-shell.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-shell.md new file mode 100644 index 0000000000000000000000000000000000000000..d801a64e7d39ba37f8a419b147ec322fd7d36fdc --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-shell.md @@ -0,0 +1,37 @@ +--- +title: "ptk cluster shell" +summary: ptk cluster shell +author: ptk +date: 2022-08-01 +--- + +# ptk cluster shell + +执行shell指令或脚本, 若不加参数进入终端模式 + +## 语法 + +ptk cluster shell [flags] + +## 选项 + +### -n, --name string + +- 集群名称 +- 数据类型：字符串 + +### -c, --command string + +- 要执行的 shell 指令 +- 数据类型：字符串 + +### -H, --host stringArray + +- 指定执行的机器IP，默认在集群内全部执行 +- 数据类型：字符串 +- 可多次指定 + +### -s, --script string + +- 指定要执行的 shell 脚本路径 +- 数据类型：字符串 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-show-config.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-show-config.md new file mode 100644 index 0000000000000000000000000000000000000000..21d8b811f6e3ab354264b32100605ff6ed20e34d --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-show-config.md @@ -0,0 +1,21 @@ +--- +title: "ptk cluster show-config" +summary: ptk cluster show-config +author: ptk +date: 2022-08-01 +--- + +# ptk cluster show-config + +显示指定集群的拓扑配置信息 + +## 语法 + +ptk cluster show-hba [flags] + +## 选项 + +### -n, --name string + +- 集群名称 +- 数据类型：字符串 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-show-guc.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-show-guc.md new file mode 100644 index 0000000000000000000000000000000000000000..10da76cf64757270340eb47d7a4790dadb103ab6 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-show-guc.md @@ -0,0 +1,27 @@ +--- +title: "ptk cluster show-guc" +summary: ptk cluster show-guc +author: ptk +date: 2022-08-01 +--- + +# ptk cluster show-guc + +查看数据库参数信息 + +## 语法 + +ptk cluster show-guc [flags] + +## 选项 + +### -n, --name string + +- 集群名称 +- 数据类型：字符串 + +### -k, --key strings + +- 指定要查看参数名 +- 数据类型：字符串 +- 可以多次指定不同参数名 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-show-hba.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-show-hba.md new file mode 100644 index 0000000000000000000000000000000000000000..92cf2ce335828f9fbaffb255523e0a36f5fac897 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-show-hba.md @@ -0,0 +1,27 @@ +--- +title: "ptk cluster show-hba" +summary: ptk cluster show-hba +author: ptk +date: 2022-08-01 +--- + +# ptk cluster show-hba + +查看数据库 pg_hba 信息 + +## 语法 + +ptk cluster show-hba [flags] + +## 选项 + +### -n, --name string + +- 集群名称 +- 数据类型：字符串 + +### -H, --host string + +- 指定要查看的实例IP +- 数据类型：字符串 +- 默认查看主库的配置 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-start.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-start.md new file mode 100644 index 0000000000000000000000000000000000000000..eeb1b2562e8efb880bee96b898be9b40fcf6a8ee --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-start.md @@ -0,0 +1,53 @@ +--- +title: "ptk cluster start" +summary: ptk cluster start +author: ptk +date: 2022-06-28 +--- + +## ptk cluster start + +启动数据库集群或实例 + +## 语法 + +```shell +ptk cluster start -n string [flags] +``` + +## 选项 + +### -n, --name string + +- 要操作的集群名称 +- 数据类型：字符串 + +### -H, --host string + +- 要操作的实例IP +- 数据类型：字符串 +- 该选项是为了支持允许查询单个实例的状态，默认查询整个集群的所有实例状态 + +### --security-mode string + +- 是否使用安全模式启动数据库 +- 数据类型：字符串 +- 可选项：on/off +- 默认值：off + +### --time-out duration + +- 执行超时时间 +- 数据类型：Duration +- Duration 类型支持的单位："h" 小时, "m" 分支, "s" 秒, "ms" +- 默认值："2m" + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +运行状态日志 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-status.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-status.md new file mode 100644 index 0000000000000000000000000000000000000000..4257ed3b7ce05bb0863f1b2f2b19f010ed0eea9f --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-status.md @@ -0,0 +1,49 @@ +--- +title: "ptk cluster status" +summary: ptk cluster status +author: ptk +date: 2022-06-28 +--- + +## ptk cluster status + +查询数据库集群或实例的运行状态 + +## 语法 + +```shell +ptk cluster status -n string [flags] +``` + +## 选项 + +### -n, --name string + +- 要操作的集群名称 +- 数据类型：字符串 + +### -H, --host string + +- 要操作的实例IP +- 数据类型：字符串 +- 该选项是为了支持允许查询单个实例的状态，默认查询整个集群的所有实例状态 + +### --detail + +- 是否显示详细的信息 +- 数据类型：布尔值 +- 默认值：false + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +分模块输出状态信息 + +- Cluster State: 集群状态 +- Datanode State: 每个实例节点状态 +- (Datanode Detail): 节点详细信息，默认不输出，指定 `--detail` 选项时显示 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-stop.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-stop.md new file mode 100644 index 0000000000000000000000000000000000000000..7984b32bea1d40db94cc081bb686060cef3028f5 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-stop.md @@ -0,0 +1,46 @@ +--- +title: "ptk cluster stop" +summary: ptk cluster stop +author: ptk +date: 2022-06-28 +--- + +## ptk cluster stop + +停止数据库集群或实例 + +## 语法 + +```shell +ptk cluster stop -n string [flags] +``` + +## 选项 + +### -n, --name string + +- 要操作的集群名称 +- 数据类型：字符串 + +### -H, --host string + +- 要操作的实例IP +- 数据类型：字符串 +- 该选项是为了支持允许查询单个实例的状态，默认查询整个集群的所有实例状态 + +### --time-out duration + +- 执行超时时间 +- 数据类型：Duration +- Duration 类型支持的单位："h" 小时, "m" 分支, "s" 秒, "ms" +- 默认值："2m" + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +运行状态日志 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster-switchover.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-switchover.md new file mode 100644 index 0000000000000000000000000000000000000000..8aa03287c3303bf1a0ecb8749de2e3de77ad72f7 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster-switchover.md @@ -0,0 +1,26 @@ +--- +title: "ptk cluster switchover" +summary: ptk cluster switchover +author: ptk +date: 2022-08-01 +--- + +# ptk cluster switchover + +查看数据库参数信息 + +## 语法 + +ptk cluster switchover [flags] + +## 选项 + +### -n, --name string + +- 集群名称 +- 数据类型：字符串 + +### -H, --host string + +- 指定要提升为主库的实例IP +- 数据类型：字符串 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-cluster.md b/product/zh/docs-ptk/v0.6/commands/ptk-cluster.md new file mode 100644 index 0000000000000000000000000000000000000000..eda249dc43a3b3676fa7cebec419d20435899205 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-cluster.md @@ -0,0 +1,24 @@ +--- +title: "ptk cluster" +summary: ptk cluster +author: ptk +date: 2022-06-28 +--- + +## ptk cluster + +数据库集群管理的操作 + +## 语法 + +```shell +ptk cluster [flags] +``` + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-completion-bash.md b/product/zh/docs-ptk/v0.6/commands/ptk-completion-bash.md new file mode 100644 index 0000000000000000000000000000000000000000..0c6a901edf456580f9cbe140fad3882714ee4da2 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-completion-bash.md @@ -0,0 +1,44 @@ +--- +title: "ptk completion bash" +summary: ptk completion bash +author: ptk +date: 2022-06-28 +--- + +## ptk completion bash + +为 bash shell 生成自动补全脚本。 + +这个脚本依赖于 'bash-completion' 包。 + +如果还没有安装，您可以通过操作系统的包管理器安装它。 + +在当前的 shell 会话中加载生效: + +```shell +Source <(ptk completion bash) +```` + +要为每个新会话加载生效，执行一次: + +**Linux:** + +```shell +ptk completion bash > /etc/bash_completion.d/ptk +```` + +**macOS:** + +```shell +ptk completion bash > /usr/local/etc/bash_completion.d/ ptk +``` + +您需要启动一个新的 shell 才能使这个设置生效。 + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-completion-fish.md b/product/zh/docs-ptk/v0.6/commands/ptk-completion-fish.md new file mode 100644 index 0000000000000000000000000000000000000000..df2aba7b92170b89334ab9d8910875488f4fb0f4 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-completion-fish.md @@ -0,0 +1,32 @@ +--- +title: "ptk completion fish" +summary: ptk completion fish +author: ptk +date: 2022-06-28 +--- + +## ptk completion fish + +为 fish 生成自动补全脚本。 + +在当前的 shell 会话中加载生效: + +```shell +ptk completion fish | source +``` + +要为每个新会话加载生效，需执行一次: + +```shell +ptk completion fish > ~/.config/fish/completions/ptk.fish +``` + +您需要启动一个新的 shell 才能使这个设置生效。 + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-completion-powershell.md b/product/zh/docs-ptk/v0.6/commands/ptk-completion-powershell.md new file mode 100644 index 0000000000000000000000000000000000000000..7a7492269a4f225f6facb822567e5c9746c1f0a8 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-completion-powershell.md @@ -0,0 +1,26 @@ +--- +title: "ptk completion powershell" +summary: ptk completion powershell +author: ptk +date: 2022-06-28 +--- + +## ptk completion powershell + +为 powershell 生成自动补全脚本。 + +在当前的shell会话中加载生效: + +```powershell +ptk completion powershell | Out-String | Invoke-Expression +``` + +要为每个新会话实现补全操作，请将上述命令的输出添加到你的 powershell profile。 + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-completion-zsh.md b/product/zh/docs-ptk/v0.6/commands/ptk-completion-zsh.md new file mode 100644 index 0000000000000000000000000000000000000000..bfce7f7a4cc7bef812f011f546b0d8597b011067 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-completion-zsh.md @@ -0,0 +1,47 @@ +--- +title: "ptk completion zsh" +summary: ptk completion zsh +author: ptk +date: 2022-06-28 +--- + +## ptk completion zsh + +为 zsh shell 生成自动补全脚本。 + +如果您的环境中还没有启用 shell 补全功能，那么您将需要 +启用它。可以执行以下操作一次: + +```shell +echo "autoload -U compinit;compinit" >> ~/.zshrc +``` + +在当前的 shell 会话中加载生效: + +```shell +source <(ptk completion zsh); compdef _ptk ptk +``` + +要为每个新会话加载完成，需操作一次： + +**Linux:** + +```shell +ptk completion zsh > "${fpath[1]}/_ptk" +``` + +**macOS:** + +```shell +ptk completion zsh > /usr/local/share/zsh/site-functions/_ptk +``` + +您需要启动一个新的 shell 才能使这个设置生效。 + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-completion.md b/product/zh/docs-ptk/v0.6/commands/ptk-completion.md new file mode 100644 index 0000000000000000000000000000000000000000..d10e229df8bcc1e5e8f57873daaffcd2bd238380 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-completion.md @@ -0,0 +1,29 @@ +--- +title: "ptk completion" +summary: ptk completion +author: ptk +date: 2022-06-28 +--- + +> 注意：该命令非必知的功能项，供专业人士参考。 + +## ptk completion + +为指定的 shell 生成 ptk 的自动补全脚本。 + +有关如何使用生成的脚本的详细信息，请参阅每个子命令的帮助。 + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 子命令 + +- [ptk completion bash](ptk-completion-bash.md): 生成bash的自动补全脚本 +- [ptk completion fish](ptk-completion-fish.md): 生成fish的自动补全脚本 +- [ptk completion powershell](ptk-completion-powershell.md): 生成powershell的自动补全脚本 +- [ptk completion zsh](ptk-completion-zsh.md): 生成zsh的自动补全脚本 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-demo.md b/product/zh/docs-ptk/v0.6/commands/ptk-demo.md new file mode 100644 index 0000000000000000000000000000000000000000..c00533f8f3f7c2250f5ec05c339c976485e23a01 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-demo.md @@ -0,0 +1,23 @@ +--- +title: "ptk demo" +summary: ptk demo +author: Jerad.K +date: 2023-01-10 +--- + +## ptk demo + +快速安装一个demo库提供使用 + +## 语法 + +```shell +ptk demo [flags] +``` + +## 选项 + +### --port int + +- 端口 +- 数据类型：整型 \ No newline at end of file diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-download.md b/product/zh/docs-ptk/v0.6/commands/ptk-download.md new file mode 100644 index 0000000000000000000000000000000000000000..2d6c8146160bb785e678249a9ad961c5f7383c22 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-download.md @@ -0,0 +1,46 @@ +--- +title: "ptk candidate" +summary: ptk candidate +author: ptk +date: 2022-6-28 +--- + +## ptk download + +在线下载 MogDB 数据库安装包 + +## 语法 + +```shell +ptk candidate [flags] +``` + +## 选项 + +### -O，--os + +- 指定系统ID（ID 可通过 [ptk candidate os](ptk-candidate-os.md) 指令查看） +- 数据类型：整型 +- 若不指定，默认自动探测当前系统 + +### -V，--db-version + +- 指定 MogDB 数据库版本（ 可通过 [ptk candidate db](ptk-candidate-db.md) 指令查看支持的版本列表） +- 数据类型：字符串 +- 默认值：PTK发布时的最新版 + +### --output + +- 下载到本地的文件路径 +- 数据类型：字符串 +- 默认值为空 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +输出文件下载进度日志 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-encrypt.md b/product/zh/docs-ptk/v0.6/commands/ptk-encrypt.md new file mode 100644 index 0000000000000000000000000000000000000000..0098e5f004e5d2e64d28d4f92da1c7fca0a9b522 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-encrypt.md @@ -0,0 +1,28 @@ +--- +title: "ptk encrypt" +summary: ptk encrypt +author: ptk +date: 2022-6-28 +--- + +## ptk encrypt + +加密指定的文本或密码，主要用于配置文件中的密码字段，PTK 不推荐将明文存储在配置文件中，所以需通过该命令来加密后写入 + +## 语法 + +```shell +ptk encrypt TEXT1 [TEXT2 TEXT3...] [flags] +``` + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +以键值对形式输出原文和密文，加密多个原文时，会以多行输出。 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-env.md b/product/zh/docs-ptk/v0.6/commands/ptk-env.md new file mode 100644 index 0000000000000000000000000000000000000000..9a1ead73891a522321cd24b35882cde4c87561b8 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-env.md @@ -0,0 +1,64 @@ +--- +title: "ptk env" +summary: ptk env +author: ptk +date: 2022-06-28 +--- + +## ptk env + +打印 PTK 支持的环境变量和值 + +## 语法 + +```shell +ptk env [key1 key2 ... keyN] [flags] +``` + +## 支持的环境变量 + +### PTK_HOME + +PTK 元数据的根目录，默认是安装用户家目录下 `.ptk` 文件夹 + +### PTK_DATA_DIR + +PTK 存放所管理的集群信息的目录，默认为 `$PTK_HOME/data` 文件夹 + +### PTK_SSH_CONNECT_TIMEOUT + +SSH 建立连接时的超时时间，默认 1 分钟。 + +值类型为字符串，支持的单位： h(小时)/m(分钟)/s(秒) + +### PTK_CMD_EXECUTE_TIMEOUT + +PTK 内部在运行每条 Shell 指令时的超时时间，默认 10 分钟。 + +值类型为字符串，支持的单位： h(小时)/m(分钟)/s(秒) + +### PTK_LOG_PATH + +运行日志输出文件路径，当配置了该环境变量时，PTK 运行时会在输出到标准输出的同时向该文件中写入日志。 + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +以键值对的形式显示环境变量的值 + +示例： + +```shell +PTK_HOME="/root/.ptk" +PTK_DATA_DIR="/root/.ptk/data" +PTK_SSH_CONNECT_TIMEOUT="1m0s" +PTK_CMD_EXECUTE_TIMEOUT="10m0s" +PTK_LOG_PATH="" +``` diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-exec.md b/product/zh/docs-ptk/v0.6/commands/ptk-exec.md new file mode 100644 index 0000000000000000000000000000000000000000..94aec314d588c659ab5e6146c6db058020c4e044 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-exec.md @@ -0,0 +1,54 @@ +--- +title: "ptk exec" +summary: ptk exec +author: ptk +date: 2022-11-09 +--- + +## ptk exec + +分发shell指令或脚本 + +## 语法 + +```shell +ptk exec [flags] +``` + +## 选项 + +### -c, --command string + +- 要执行的 shell 指令 +- 数据类型：字符串 + +### -s, --script string + +- 要执行的本地 shell 脚本文件路径 +- 数据类型：字符串 + +### -f, --file string + +- 指定一个配置文件，该配置文件可以是还未安装的集群 +- 数据类型：字符串 + +### -n, --name string + +- 已经安装的集群名称 +- 数据类型：字符串 + +### -H, --host stringArray + +- 指定集群内具体机器的IP执行指令 +- 数据类型：字符串，可多次指定 +- 默认在全部机器上执行 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +分块输出每个机器的执行结果 \ No newline at end of file diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-gen-om-xml.md b/product/zh/docs-ptk/v0.6/commands/ptk-gen-om-xml.md new file mode 100644 index 0000000000000000000000000000000000000000..f1c0273341d065dca47dfa39481b89d7d2673d5d --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-gen-om-xml.md @@ -0,0 +1,30 @@ +--- +title: "ptk gen-om-xml" +summary: ptk gen-om-xml +author: ptk +date: 2022-06-28 +--- + +## ptk gen-om-xml + +生成 gs_om 使用的 XML 配置文件 + +## 语法 + +```shell +ptk gen-om-xml -f CONFIG_FILE [flags] +``` + +## 选项 + +### -o, --output string + +- 指定输出的文件路径 +- 数据类型：字符串 +- 默认值: `config_[timestamp].xml`， timestamp 为时间戳 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-install.md b/product/zh/docs-ptk/v0.6/commands/ptk-install.md new file mode 100644 index 0000000000000000000000000000000000000000..b5e4155df14ac83a5a24b896a5f7bc5a80e2b812 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-install.md @@ -0,0 +1,149 @@ +--- +title: "ptk install" +summary: ptk install +author: ptk +date: 2022-6-28 +--- + +## ptk install + +基于给定的拓扑配置部署 MogDB 数据库集群 + +## 语法 + +```shell +ptk install -f CONFIG_YAML [flags] +``` + +## 选项 + +### -y, --assumeyes + +- 自动对所有提问回复Yes +- 数据类型：布尔值 +- 该选项默认关闭，在命令行中添加该参数使其生效 +- 默认值：false + +### --db-version string + +- 指定数据库的版本（仅支持有网络情况下在线安装） +- 数据类型：字符串 +- 可通过 'ptk candidate mogdb-server' 查看支持的 Mogdb Server 版本列表 +- 默认值："3.0.0" + +### -e, --env strings + +- 指定键值对形式的环境变量字符串，所有值将被添加到安装后系统用户环境变量中 +- 数据类型：字符串列表 +- 该选项支持多次指定，对应不同的值 + +### -p, --pkg string + +- 数据库安装包的文件路径或者下载地址 +- 数据类型：字符串 +- 该选项默认为空，使用 `--db-version` 默认值对应的安装包。该选项支持本地磁盘文件路径，同时也支持网络下载链接(需包含 `http://` 或 `https://` 的完整链接) + +### --no-cache + +- 不使用本地缓存的安装包 +- 数据类型：布尔值 +- 该选项默认关闭，PTK 会在本地元数据中查找是否有缓存的已经下载好的安装包，如果存在就直接使用缓存的安装包进行安装 +- 默认值：false + +### --cpu string + +- 指定要安装数据库机器的CPU型号 +- 数据类型：字符串 +- 可以通过 ptk candidate cpu 查看支持的CPU型号列表 + +### --launch-db-timeout duration + +- 启动数据库超时时间 +- 数据类型：Duration +- 该选项指定了在安装完成后启动数据的超时时间，超过指定时长后，报超时错误退出，需用户手动查看数据库的启动状态或手动启动。 +- Duration 类型支持的单位："h" 小时, "m" 分支, "s" 秒, "ms" 毫秒 +- 默认值："1m" + +### --pre-run string + +- 安装数据库**之前**需要执行的bash脚本路径 +- 数据类型：字符串 +- 该选项提供了一个 pre-hook 功能，允许用户提供一个bash脚本，PTK将在部署数据库前在集群内每台机器上运行 + +### --post-run string + +- 数据库**启动后**需要执行的bash脚本路径 +- 数据类型：字符串 +- 该选项提供了一个 post-hook 功能，允许用户提供一个bash脚本，PTK将在启动数据库成功后在集群内每台机器上运行 + +### --skip-check-distro + +- 跳过检查操作系统发行版 +- 数据类型：布尔值 +- 该选项默认关闭，在命令行添加该选项生效。一般用于测试场景，在PTK不支持的操作系统上测试数据库能够使用。 +- 默认值：false + +### --skip-check-os + +- 跳过检查系统环境 +- 数据类型：布尔值 +- 该选项默认关闭，在命令行添加该选项生效。当用户由于特殊原因无法直接修改系统参数时，PTK支持跳过检查进行安装。否则存在 abnormal 级别的检查结果时，安装过程会中支。 +- 默认值：false + +### --skip-create-user + +- 跳过创建系统用户 +- 数据类型：布尔值 +- 该选项默认关闭，在命令行添加该选项生效。当指定该选项时，需确保要安装的服务器上用户已经存在，否则会中止安装。当指定跳过创建用户时，PTK不自动创建互信，需用户自己创建SSH互信 +- 默认值：false + +### --install-cm + +- 安装 CM 相关组件 (3节点以上生效) +- 数据类型：布尔值 +- 该选项默认关闭，在命令行添加该选项生效。cm 组件提供了一层高可用和运维的能力，当用户选择其他高可用组件时，PTK支持默认不安装CM组件，以普通方式通过 gs_ctl 启动主备数据库。该选项针对3节点以上的集群，3节点以下，不支持安装 CM 组件。注意：由于 PTK 是通过 gs_ctl 工具来管理数据库实例的，所以安装了CM组件后，启停管理功能暂时不支持。 +- 默认值：false + +### --skip-launch-db + +- 安装完成后不启动数据库 +- 数据类型：布尔值 +- 该选项默认关闭，在命令行添加该选项生效。需注意的是，当指定了该选项安完成后，再次手动启动后，需用户进行一下初始用户密码的修改，否则通过 [`ptk cluster status`](ptk-cluster-status.md) 查看集群状态时，可能会出现 `ERROR: Please use "ALTER ROLE user_name PASSWORD 'password';" to set the password of user xx before other operation!` 的错误。 +- 默认值：false + +### --skip-rollback + +- 安装过程出错后，不进行操作的回滚 +- 数据类型：布尔值 +- 该选项默认关闭，在命令行添加该选项生效。PTK 默认会在执行安装出错时，回滚掉之前的所有操作，以保证系统中不会有安装过程的遗留文件或配置。需注意的时，该操作也依赖网络，需SSH保持畅通，如果回滚过程断网或其他报错，回滚也会中止，需人工进行清理操作。 +- 默认值：false + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +显示安装过程的日志信息，默认日志级别为 INFO，可以通过全局参数 `--log-level` 来修改日志级别。 +最后输出安装状态的表格，表格包含下列字段： + +- host: 服务器IP +- stage: 安装阶段 +- status: 安装状态 +- message: 安装结果信息 + +安装状态值： + +- precheck_success: 预检查成功 +- precheck_failed: 预检查失败 +- initial_db_success: 初始化数据库成功 +- initial_db_failed: 初始化数据库失败 +- initial_cm_success: 初初始化 CM 组件成功 +- initial_cm_failed: 初始化 CM 组件失败 +- rollback_success: 回滚成功 +- need_rollback_manually: 需手动回滚 +- start_success: 启动数据库成功 +- start_failed: 启动数据库失败 +- need_start_manually: 需手动启动数据库 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-ls.md b/product/zh/docs-ptk/v0.6/commands/ptk-ls.md new file mode 100644 index 0000000000000000000000000000000000000000..c976e43d12fe3e5e25dd0c6644d24cd7ef0c0cd1 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-ls.md @@ -0,0 +1,41 @@ +--- +title: "ptk ls" +summary: ptk ls +author: ptk +date: 2022-06-28 +--- + +## ptk ls + +列出当前用户已经安装的所有数据库列表，PTK以使用用户作为区分，所以不同用户之间仅能看到自己安装的列表 + +## 语法 + +```shell +ptk ls [flags] +``` + +## 选项 + +### -n, --only-name + +- 仅列出集群的名称 +- 数据类型：布尔值 +- 该选项默认关闭，显示集群的静态数据，在命令行中添加该选项使其生效。 +- 默认值：false + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +输出集群列表的表格，表格包含以下字段： + +- cluster_name: 集群名称 +- instances: 集群内的实例列表 +- user: 运行的操作系统用户 +- data_dir: 实例的数据目录 +- db_version: 数据库版本 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-meta-home.md b/product/zh/docs-ptk/v0.6/commands/ptk-meta-home.md new file mode 100644 index 0000000000000000000000000000000000000000..464779f901e8215395e59bc994738109535403d5 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-meta-home.md @@ -0,0 +1,18 @@ +--- +title: "ptk meta home" +summary: ptk meta home +author: Jerad.K +date: 2023-01-10 +--- + +# ptk meta home + +显示ptk元数据的所在目录 + +## 语法 + +ptk meta home + +## 输出 + +ptk元数据的所在目录 \ No newline at end of file diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-meta-prune.md b/product/zh/docs-ptk/v0.6/commands/ptk-meta-prune.md new file mode 100644 index 0000000000000000000000000000000000000000..6bc0a9f758fed4fca755842f84f17ec7c8d63917 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-meta-prune.md @@ -0,0 +1,29 @@ +--- +title: "ptk meta prune" +summary: ptk meta prune +author: Jerad.K +date: 2023-01-10 +--- + +# ptk meta prune + +清理集群元数据 + +## 语法 + +ptk meta prune [flags] + +## 选项 + +### -n, --name string + +- 集群名称 +- 数据类型：字符串 + +### --force + +- 强制执行 +- 数据类型：布尔 + +## 输出 +元数据清理成功或失败 \ No newline at end of file diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-meta.md b/product/zh/docs-ptk/v0.6/commands/ptk-meta.md new file mode 100644 index 0000000000000000000000000000000000000000..4ff6047af68952752338c77d99569ebdcb4fbb4d --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-meta.md @@ -0,0 +1,24 @@ +--- +title: "ptk meta" +summary: ptk meta +author: Jerad.K +date: 2023-01-10 +--- + +## ptk meta + +数据库元数据管理的操作 + +## 语法 + +```shell +ptk meta [flags] +``` + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-self-upgrade.md b/product/zh/docs-ptk/v0.6/commands/ptk-self-upgrade.md new file mode 100644 index 0000000000000000000000000000000000000000..23eefcbb406d95d55e5714b97be132dd7e288260 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-self-upgrade.md @@ -0,0 +1,24 @@ +--- +title: "ptk self upgrade" +summary: ptk self upgrade +author: ptk +date: 2022-06-28 +--- + +## ptk self upgrade + +下载并自动安装最新版的PTK + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +升级步骤日志，包含下载最新包并升级，最终显示 `upgrade ptk successfully` 就表示升级成功 + +可以通过 [`ptk version`](ptk-version.md) 查看升级后的版本 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-self.md b/product/zh/docs-ptk/v0.6/commands/ptk-self.md new file mode 100644 index 0000000000000000000000000000000000000000..b4bff5ed3b9cdf1aac048d47786ad668156cdad6 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-self.md @@ -0,0 +1,28 @@ +--- +title: "ptk self" +summary: ptk self +author: ptk +date: 2022-06-28 +--- + +## ptk self + +打印 PTK 的环境变量信息 + +## 语法 + +```shell +ptk self [command] +``` + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 子命令 + +- [ptk self upgrade](ptk-self-upgrade.md) 升级 PTK 版本 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-template-create.md b/product/zh/docs-ptk/v0.6/commands/ptk-template-create.md new file mode 100644 index 0000000000000000000000000000000000000000..691607d8f7eda31ac08ad85ca7db5f5ed5d10a1c --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-template-create.md @@ -0,0 +1,30 @@ +--- +title: "ptk template create" +summary: ptk template create +author: ptk +date: 2022-6-28 +--- + +## ptk template create + +以交互的方式创建配置模板 + +## 语法 + +```shell +ptk template create [flags] +``` + +## 选项 + +### -o, --output string + +- 指定用于存储模板的文件路径 +- 数据类型：字符串 +- 默认值："config.yaml" + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-template-mogha.md b/product/zh/docs-ptk/v0.6/commands/ptk-template-mogha.md new file mode 100644 index 0000000000000000000000000000000000000000..bf67da428e26d57d3f3155cf123d6d8f697cf140 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-template-mogha.md @@ -0,0 +1,32 @@ +--- +title: "ptk template mogha" +summary: ptk template mogha +author: ptk +date: 2022-08-01 +--- + +# ptk template mogha + +生成 MogHA 配置 + +## 语法 + +ptk template mogha [flags] + +## 选项 + +### -n, --cluster-name string + +- 集群名称 +- 数据类型：字符串 + +### -o, --output string + +- 指定输出文件 +- 数据类型：字符串 + +### --port int + +- 指定 MogHA 监听的端口 +- 数据类型：整型 +- 默认值：8081 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-template-scale-out.md b/product/zh/docs-ptk/v0.6/commands/ptk-template-scale-out.md new file mode 100644 index 0000000000000000000000000000000000000000..5779379606ad39e4a365d885b68327cee5d23389 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-template-scale-out.md @@ -0,0 +1,21 @@ +--- +title: "ptk template scale-out" +summary: ptk template scale-out +author: ptk +date: 2022-08-01 +--- + +# ptk template scale-out + +生成集群扩容配置 + +## 语法 + +ptk template scale-out [flags] + +## 选项 + +### -o, --output string + +- 指定输出文件 +- 数据类型：字符串 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-template.md b/product/zh/docs-ptk/v0.6/commands/ptk-template.md new file mode 100644 index 0000000000000000000000000000000000000000..b4c6db03958f5cbd46cbf1bb1f794a69c356bf23 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-template.md @@ -0,0 +1,70 @@ +--- +title: "ptk template" +summary: ptk template +author: ptk +date: 2022-6-28 +--- + +## ptk template + +打印配置模板，默认输出多实例的配置模板 + +## 语法 + +```shell +ptk template [flags] +``` + +## 选项 + +### -l, --local + +- 生成本地单实例数据库的配置文件 +- 数据类型：布尔值 +- 改选项默认关闭，在命令中添加该选项生效 +- 默认值：false + +### -d, --base-dir string + +- 指定数据库要安装的基目录 +- 数据类型：字符串 +- PTK会在该目录下自动分配数据库的数据目录，工具目录，应用目录等。 +- 默认值："/opt/mogdb" + +### -n, --cluster-name string + +- 指定集群名称 +- 数据类型：字符串 +- 如果不传该参数，PTK默认会随机生成一个集群名称 + +### -u, --user string + +- 运行数据库的系统用户名称 +- 数据类型：字符串 +- 默认值："omm" + +### -g, --group string + +- 运行数据库的系统用户组名称 +- 数据类型：字符串 +- 默认值：和 `-u` 指定的系统用户同名 + +### -p, --port int + +- 数据库运行端口 +- 数据类型：整型 +- 默认值：26000 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +以键值对形式输出原文和密文，加密多个原文时，会以多行输出。 + +## 更多子命令 + +- [ptk template create][ptk-template-create.md] diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-uninstall.md b/product/zh/docs-ptk/v0.6/commands/ptk-uninstall.md new file mode 100644 index 0000000000000000000000000000000000000000..d0bb8a3037d6b892e24267bc37b8b1cf8d06b595 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-uninstall.md @@ -0,0 +1,40 @@ +--- +title: "ptk uninstall" +summary: ptk uninstall +author: ptk +date: 2022-06-28 +--- + +## ptk uninstall + +卸载 MogDB 数据库集群 + +## 语法 + +```shell +ptk uninstall [flags] +``` + +## 选项 + +### -n, --name string + +- 指定要卸载的集群名称 +- 数据类型：字符串 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 示例 + +```shell +# 通过集群名称卸载 +ptk uninstall --name CLUSTER_NAME +``` + +## 输出 + +输出卸载过程步骤日志 diff --git a/product/zh/docs-ptk/v0.6/commands/ptk-version.md b/product/zh/docs-ptk/v0.6/commands/ptk-version.md new file mode 100644 index 0000000000000000000000000000000000000000..69d0e505d1583f6e54c26dd4bc869fac56855772 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/commands/ptk-version.md @@ -0,0 +1,37 @@ +--- +title: "ptk version" +summary: ptk version +author: ptk +date: 2022-06-28 +--- + +## ptk version + +打印 PTK 的版本信息 + +## 语法 + +```shell +ptk version [flags] +``` + +## 选项 + +### -h, --help + +- 输出帮助信息。 +- 数据类型：布尔值 +- 该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。 + +## 输出 + +版本信息类似如下： + +```text +PTK Version: v0.2.0 +Go Version: go1.17.1 +Build Date: 2022-06-28T07:28:33Z +Git Hash: df42c22 +``` + +里面包含 PTK 的版本，编译时的 Golang 版本，构建时间以及Git commit 信息 diff --git a/product/zh/docs-ptk/v0.6/config-samples.md b/product/zh/docs-ptk/v0.6/config-samples.md new file mode 100644 index 0000000000000000000000000000000000000000..81427c3df810453b3d55389c9d690b4d5f8f140a --- /dev/null +++ b/product/zh/docs-ptk/v0.6/config-samples.md @@ -0,0 +1,170 @@ +--- +title: Configuration Samples +summary: Configuration Samples +author: Yao Qian +date: 2021-11-09 +--- + +# 配置示例 + +## 本地单实例最简配置 + +```yaml +global: + cluster_name: cluster_1 + user: omm + db_port: 26000 + base_dir: /opt/mogdb + +db_servers: + - host: 127.0.0.1 +``` + +## 远程单实例定制化配置 + +```yaml +global: + cluster_name: cluster_2 + user: mogdb + db_port: 26000 + # 数据库密码加密后填写，加密方式 ptk encrypt + # 密码强度需 8~16 位，包含大小写和特殊字符 + db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= + base_dir: /opt/mogdb + # 自定义数据目录 + data_dir: /data/mogdb_data + +db_servers: + - host: "192.168.100.100" # 替换目标机器IP + # gs_initdb 的参数定制化 + gs_initdb_opts: + - --encoding=UTF-8 + - --dbcompatibility=A + # 数据库 postgresql.conf 中的参数定制化 + db_conf: + wal_level: logical + most_available_sync: on + ssh_option: + port: 22 + user: root + # 密码和密钥文件填写任何一个即可 + password: "" # ptk encrypt + key_file: ~/.ssh/id_rsa +``` + +## 单机多实例配置 + +> 单机多实例部署方式，仅用于**个人测试或学习**，由于这种部署方式集群内存在多个数据库实例共用IP，所以PTK的部分功能是受限的。 +> 单机多实例部署，必须将单机上不同的数据库实例指定不同的系统用户，端口以及安装目录，通过不同用户来隔离实例的环境变量。 +> 单机上不同实例的监听端口，至少需间隔 50 以上，因为数据库内部会依赖监听端口以上的部分端口进行集群内部通信 + +```yaml +global: + cluster_name: cluster_3 + +db_servers: + - host: 127.0.0.1 + user: mogdb1 + db_port: 26000 + base_dir: /home/mogdb1 + - host: 127.0.0.1 + user: mogdb2 + db_port: 27000 + base_dir: /home/mogdb2 +``` + +## 一主多备配置 + +### 不同服务器的SSH配置相同 + +```yaml +global: + cluster_name: cluster_4 + user: mogdb + db_port: 26000 + base_dir: /opt/mogdb + # 仅需在 global 里配置一份 ssh 信息即可 + ssh_option: + port: 22 + user: root + # 密码和密钥文件填写任何一个即可 + password: "" # ptk encrypt + key_file: ~/.ssh/id_rsa + +db_servers: + - host: 192.168.100.100 + role: primary + - host: 192.168.100.101 + role: standby + - host: 192.168.100.102 + role: standby +``` + +### 不同服务器SSH配置不同 + +```yaml +global: + cluster_name: cluster_5 + user: mogdb + db_port: 26000 + base_dir: /opt/mogdb + +db_servers: + - host: 192.168.100.100 + role: primary + ssh_option: + port: 22 + user: root + # 密码和密钥文件填写任何一个即可 + password: "" # ptk encrypt + key_file: ~/.ssh/id_rsa + - host: 192.168.100.101 + role: standby + ssh_option: + port: 22 + user: root + # 密码和密钥文件填写任何一个即可 + password: "" # ptk encrypt + key_file: ~/.ssh/id_rsa + - host: 192.168.100.102 + role: standby + ssh_option: + port: 22 + user: root + # 密码和密钥文件填写任何一个即可 + password: "" # ptk encrypt + key_file: ~/.ssh/id_rsa +``` + +## 无法直连数据库服务器，需通过跳板机访问的配置 + +不管是 global 级别还是 db_servers 级别的 ssh_option 都是支持一层跳板机登录的配置 + +```yaml +global: + cluster_name: cluster_6 + user: mogdb + db_port: 26000 + base_dir: /opt/mogdb + ssh_option: + port: 22 + user: root + # 密码和密钥文件填写任何一个即可 + password: "" # ptk encrypt + key_file: ~/.ssh/id_rsa + # 这部分配置跳板机的连接信息，上面是目标机器 + proxy: + host: 192.168.200.100 # 跳板机IP + port: 22 + user: root + password: "" # ptk encrypt + key_file: ~/.ssh/id_rsa + +db_servers: + - host: 192.168.100.100 + role: primary + - host: 192.168.100.101 + role: standby + - host: 192.168.100.102 + role: standby +``` diff --git a/product/zh/docs-ptk/v0.6/config.md b/product/zh/docs-ptk/v0.6/config.md new file mode 100644 index 0000000000000000000000000000000000000000..b7a1f3075ad69a174e41b007e4737b338550a907 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/config.md @@ -0,0 +1,1063 @@ +--- +title: Configuration File +summary: Configuration File +author: Yao Qian +date: 2021-09-14 +--- + +# 配置文件 + +PTK 的配置文件采用 [YAML格式](./yaml-grammar.md)。 + +该文件包含介绍了安装集群所需的所有配置参数。 + +在安装数据库集群时，需用户提供一个描述集群拓扑的配置文件，该配置文件在 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 数据库集群拓扑配置信息 + +**示例**: + +- simple config example + +```yaml +# 集群级别的配置信息，其中 `db_port` 和 `ssh_option` 字段是 **可重用字段** +global: + cluster_name: cluster_simple # 集群名称，PTK管理的集群的唯一标识 + db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入 +# 集群内的数据库实例服务器配置信息 +db_servers: + - host: 10.1.1.100 # 数据库实例服务器 IP (仅支持 IPv4) + - host: 10.1.1.101 # 数据库实例服务器 IP (仅支持 IPv4) +# 集群内的CM服务部署机器列表 +cm_servers: [] +``` + +- complex config example + +```yaml +# 集群级别的配置信息，其中 `db_port` 和 `ssh_option` 字段是 **可重用字段** +global: + cluster_name: cluster_complex # 集群名称，PTK管理的集群的唯一标识 + user: omm # 运行数据库的操作系统用户名 + group: omm # 运行数据库的操作系统用户组 + db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入 + base_dir: /opt/mogdb # 数据库安装的基础目录，指定该目录后，app_dir，data_dir，log_dir和tool_dir 参数中若未配置的，PTK 会自动在该安装目录下会创建对应的目录； + # （选填）MogDB 高可用组件 CM 配置信息，若不使用 CM 组件，可不填写该字段 + cm_option: + dir: /opt/mogdb/cm # CM 安装目录 + cm_server_port: 15300 # cm server 监听端口 + db_service_vip: "" # 数据库提供服务的虚拟IP +# 集群内的数据库实例服务器配置信息 +db_servers: + - host: 10.1.1.100 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # - name: db HA ip list example + ha_ips: + - 10.1.1.200 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: primary # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + az_name: BJ # Available Zone (可用区) 名称 + az_priority: 1 # 可用区使用的优先级，数值越小优先级越高 + # SSH 登录信息，登录用户需为 **root** 或者具有 sudo 权限的用户 + ssh_option: + port: 22 # SSH 登录用户 + user: root # SSH 登录用户密码 + password: pTk6LIBsPVplOpmxQToCPT9+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # SSH 登录密钥文件路径 + conn_timeout: 5m0s # SSH 执行单条命令时的超时时间 + exec_timeout: 5m0s # 跳板服务器登录信息，如果目标服务器无法直连时，支持通过中间跳板机方式连接 + - host: 10.1.1.101 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # - name: db HA ip list example + ha_ips: + - 10.1.1.201 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: standby # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + az_name: BJ # Available Zone (可用区) 名称 + az_priority: 1 # 可用区使用的优先级，数值越小优先级越高 + # SSH 登录信息，登录用户需为 **root** 或者具有 sudo 权限的用户 + ssh_option: + port: 22 # SSH 登录用户 + user: root # SSH 登录用户密码 + key_file: ~/.ssh/id_rsa # SSH 登录密钥文件口令 + conn_timeout: 5m0s # SSH 执行单条命令时的超时时间 + exec_timeout: 5m0s # 跳板服务器登录信息，如果目标服务器无法直连时，支持通过中间跳板机方式连接 + - host: 10.1.1.102 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # - name: db HA ip list example + ha_ips: + - 10.1.1.202 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: cascade_standby # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + upstream_host: 10.1.1.101 # 当实例角色为 cascade_standby 时，该字段表示要跟随的上游备库 IP + az_name: SH # Available Zone (可用区) 名称 + az_priority: 2 # 可用区使用的优先级，数值越小优先级越高 +# 集群内的CM服务部署机器列表 +cm_servers: + - host: 10.1.1.100 # CM Server 服务器 IP (仅支持 IPv4) + port: 0 # CM Server 监听端口 + role: "" + - host: 10.1.1.101 # CM Server 服务器 IP (仅支持 IPv4) + port: 25300 # CM Server 监听端口 + role: "" +``` + +### global + +**类型**: Global + +**描述**: 集群级别的配置信息，其中 `db_port` 和 `ssh_option` 字段是 **可重用字段**

**可重用字段**
如果实例级别设置了该字段，则对应实例使用实例级别的值；
如果实例级别未配置该字段，则继承 global 级别的字段的值。 + +**示例**: + +- simple global example + +```yaml +global: + cluster_name: cluster_simple # 集群名称，PTK管理的集群的唯一标识 + db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入 +``` + +- complex global example + +```yaml +global: + cluster_name: cluster_complex # 集群名称，PTK管理的集群的唯一标识 + user: omm # 运行数据库的操作系统用户名 + group: omm # 运行数据库的操作系统用户组 + db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入 + base_dir: /opt/mogdb # 数据库安装的基础目录，指定该目录后，app_dir，data_dir，log_dir和tool_dir 参数中若未配置的，PTK 会自动在该安装目录下会创建对应的目录； + # （选填）MogDB 高可用组件 CM 配置信息，若不使用 CM 组件，可不填写该字段 + cm_option: + dir: /opt/mogdb/cm # CM 安装目录 + cm_server_port: 15300 # cm server 监听端口 + db_service_vip: "" # 数据库提供服务的虚拟IP +``` + +**新增于**: v0.1 + +### db_servers + +**类型**: []DBServer + +**描述**: 集群内的数据库实例服务器配置信息 + +**示例**: + +- 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 # 数据库端口 + # - name: db HA ip list example + ha_ips: + - 10.1.1.200 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: primary # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + az_name: BJ # Available Zone (可用区) 名称 + az_priority: 1 # 可用区使用的优先级，数值越小优先级越高 + # SSH 登录信息，登录用户需为 **root** 或者具有 sudo 权限的用户 + ssh_option: + port: 22 # SSH 登录用户 + user: root # SSH 登录用户密码 + password: pTk6LIBsPVplOpmxQToCPT9+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # SSH 登录密钥文件路径 + conn_timeout: 5m0s # SSH 执行单条命令时的超时时间 + exec_timeout: 5m0s # 跳板服务器登录信息，如果目标服务器无法直连时，支持通过中间跳板机方式连接 + - host: 10.1.1.101 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # - name: db HA ip list example + ha_ips: + - 10.1.1.201 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: standby # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + az_name: BJ # Available Zone (可用区) 名称 + az_priority: 1 # 可用区使用的优先级，数值越小优先级越高 + # SSH 登录信息，登录用户需为 **root** 或者具有 sudo 权限的用户 + ssh_option: + port: 22 # SSH 登录用户 + user: root # SSH 登录用户密码 + key_file: ~/.ssh/id_rsa # SSH 登录密钥文件口令 + conn_timeout: 5m0s # SSH 执行单条命令时的超时时间 + exec_timeout: 5m0s # 跳板服务器登录信息，如果目标服务器无法直连时，支持通过中间跳板机方式连接 + - host: 10.1.1.102 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # - name: db HA ip list example + ha_ips: + - 10.1.1.202 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: cascade_standby # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + upstream_host: 10.1.1.101 # 当实例角色为 cascade_standby 时，该字段表示要跟随的上游备库 IP + az_name: SH # Available Zone (可用区) 名称 + az_priority: 2 # 可用区使用的优先级，数值越小优先级越高 +``` + +**新增于**: v0.1 + +### cm_servers + +**类型**: []CMServer + +**描述**: 集群内的CM服务部署机器列表 + +**示例**: + +- cm servers example + +```yaml +cm_servers: + - host: 10.1.1.100 # CM Server 服务器 IP (仅支持 IPv4) + port: 0 # CM Server 监听端口 + role: "" + - host: 10.1.1.101 # CM Server 服务器 IP (仅支持 IPv4) + port: 25300 # CM Server 监听端口 + role: "" +``` + +**新增于**: v0.5 + +--- + +## Global + +Global 定义配置文件中全局参数 + +Appears in: + +- Config.global + +**示例**: + +- simple global example + +```yaml +cluster_name: cluster_simple # 集群名称，PTK管理的集群的唯一标识 +db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入 +``` + +- complex global example + +```yaml +cluster_name: cluster_complex # 集群名称，PTK管理的集群的唯一标识 +user: omm # 运行数据库的操作系统用户名 +group: omm # 运行数据库的操作系统用户组 +db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入 +base_dir: /opt/mogdb # 数据库安装的基础目录，指定该目录后，app_dir，data_dir，log_dir和tool_dir 参数中若未配置的，PTK 会自动在该安装目录下会创建对应的目录； +# （选填）MogDB 高可用组件 CM 配置信息，若不使用 CM 组件，可不填写该字段 +cm_option: + dir: /opt/mogdb/cm # CM 安装目录 + cm_server_port: 15300 # cm server 监听端口 + db_service_vip: "" # 数据库提供服务的虚拟IP +``` + +### cluster_name + +**类型**: string + +**描述**: 集群名称，PTK管理的集群的唯一标识 + +**示例**: + +- cluster name example + +```yaml +cluster_name: cluster1 +``` + +**新增于**: v0.1 + +### user + +**类型**: string + +**描述**: 运行数据库的操作系统用户名
如果想一套主备在同一个服务器上部署，需在实例级别设置不同的用户来隔离环境
默认为："omm" + +**示例**: + +- os user example + +```yaml +user: omm +``` + +**新增于**: v0.1 + +### group + +**类型**: string + +**描述**: 运行数据库的操作系统用户组
默认和操作系统用户同名 + +**示例**: + +- os user group example + +```yaml +group: omm +``` + +**新增于**: v0.1 + +### user_password + +**类型**: string + +**描述**: 运行数据库的操作系统用户密码
该字段不支持明文填写，需使用 ptk encrypt 加密
默认为空，不设置 + +**新增于**: v0.1 + +### db_password + +**类型**: string + +**描述**: 数据库的初始用户密码，若配置文件中未填写，会在安装时通过交互式要求输入
该字段不支持明文填写，需使用 ptk encrypt 加密 + +**新增于**: v0.1 + +### db_port + +**类型**: int + +**描述**: 数据库的运行端口
如果在单个服务器上部署主备，需在实例级别设置不同的端口号
默认值: 26000 + +**示例**: + +- db port example + +```yaml +db_port: 26000 +``` + +**新增于**: v0.1 + +### base_dir + +**类型**: string + +**描述**: 数据库安装的基础目录，指定该目录后，app_dir，data_dir，log_dir和tool_dir 参数中若未配置的，PTK 会自动在该安装目录下会创建对应的目录；
无特殊要求情况下，我们推荐用户在安装时仅设置该参数即可
注意：若在单机上部署集群时，需在实例级别设置不同的安装目录
默认值: "/opt/mogdb" + +**示例**: + +- db base dir example + +```yaml +base_dir: /opt/mogdb +``` + +**新增于**: v0.1 + +### app_dir + +**类型**: string + +**描述**: []数据库部署文件、启动脚本和配置文件的存放路径
默认值: "/opt/mogdb/app" + +**示例**: + +- db app dir example + +```yaml +app_dir: /opt/mogdb/app +``` + +**新增于**: v0.1 + +### data_dir + +**类型**: string + +**描述**: 数据库数据存储目录
默认值: "/opt/mogdb/data" + +**示例**: + +- db data dir example + +```yaml +data_dir: /opt/mogdb/data +``` + +**新增于**: v0.1 + +### log_dir + +**类型**: string + +**描述**: 数据库运行日志和操作日志存储目录
默认值: "/opt/mogdb/log" + +**示例**: + +- db log dir example + +```yaml +log_dir: /opt/mogdb/log +``` + +**新增于**: v0.1 + +### tool_dir + +**类型**: string + +**描述**: 数据库工具目录
默认值: "/opt/mogdb/tool" + +**示例**: + +- db tool dir example + +```yaml +tool_dir: /opt/mogdb/tool +``` + +**新增于**: v0.1 + +### tmp_dir + +**类型**: string + +**描述**: 数据库临时目录
默认值: "/tmp" + +**示例**: + +- db tmp dir example + +```yaml +tmp_dir: /tmp +``` + +**新增于**: v0.1 + +### core_file_dir + +**类型**: string + +**描述**: 数据库 core dump 时，错误日志文件目录，设置后会修改系统配置参数 `kernel.core_pattern`
默认为空 + +**新增于**: v0.1 + +### ssh_option + +**类型**: SSHOption + +**描述**: SSH 登录信息，登录用户需为 **root** 或者具有 sudo 权限的用户
不设置时为本地执行 + +**新增于**: v0.1 + +### gs_initdb_opts + +**类型**: []string + +**描述**: 用户自定义配置 gs_initdb 初始化数据库时的参数。
特别地, 如果用户未配置 locale 参数, PTK 默认会设置 no-locale
支持的参数列表请查看 gs_initdb 工具[文档](https://docs.mogdb.io/zh/mogdb/v3.0/5-gs_initdb) + +**示例**: + +- gs_initdb options example + +```yaml +gs_initdb_opts: + - --locale=LOCALE + - -E=UTF-8 +``` + +**新增于**: v0.3 + +### cm_option + +**类型**: CMOption + +**描述**: （选填）MogDB 高可用组件 CM 配置信息，若不使用 CM 组件，可不填写该字段
仅在数据库版本 3.0 及以上生效 + +**新增于**: v0.4 + +--- + +## CMOption + +Appears in: + +- Global.cm_option + +### dir + +**类型**: string + +**描述**: CM 安装目录 + +**示例**: + +- db cm dir example + +```yaml +dir: /opt/mogdb/cm +``` + +**新增于**: v0.4 + +### cm_server_port + +**类型**: int + +**描述**: cm server 监听端口 + +**示例**: + +- cm server port + +```yaml +cm_server_port: 15300 +``` + +**新增于**: v0.4 + +### db_service_vip + +**类型**: string + +**描述**: 数据库提供服务的虚拟IP + +**新增于**: v0.4 + +### cm_server_conf + +**类型**: map[string]string + +**描述**: cm_server.conf 中支持的配置参数， PTK 不对参数的准确性和有效性做校验 + +**示例**: + +- cm server conf + +```yaml +cm_server_conf: + key: value +``` + +**新增于**: v0.4 + +### cm_agent_conf + +**类型**: map[string]string + +**描述**: cm_agent.conf 中支持的配置参数， PTK 不对参数的准确性和有效性做校验 + +**示例**: + +- cm agent conf + +```yaml +cm_agent_conf: + key: value +``` + +**新增于**: v0.4 + +--- + +## CMServer + +CMServer CM服务配置信息 + +Appears in: + +- Config.cm_servers + +**示例**: + +- cm server example + +```yaml +host: 10.1.1.101 # CM Server 服务器 IP (仅支持 IPv4) +port: 25300 # CM Server 监听端口 +role: "" +``` + +- cm servers example + +```yaml +- host: 10.1.1.100 # CM Server 服务器 IP (仅支持 IPv4) + port: 0 # CM Server 监听端口 + role: "" +- host: 10.1.1.101 # CM Server 服务器 IP (仅支持 IPv4) + port: 25300 # CM Server 监听端口 + role: "" +``` + +### host + +**类型**: string + +**描述**: CM Server 服务器 IP (仅支持 IPv4) + +**示例**: + +- cm host ip example + +```yaml +host: 10.1.1.100 +``` + +**新增于**: v0.5 + +### port + +**类型**: int + +**描述**: CM Server 监听端口
默认使用 global.cm_option.cm_server_port + +**示例**: + +- cms port example + +```yaml +port: 15300 +``` + +**新增于**: v0.5 + +### ssh_option + +**类型**: SSHOption + +**描述**: SSH 登录信息，登录用户需为 **root** 或者具有 sudo 权限的用户
不设置时为本地执行 + +**新增于**: v0.5 + +--- + +## 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 # 数据库端口 + # - name: db HA ip list example + ha_ips: + - 10.1.1.200 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: primary # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + az_name: BJ # Available Zone (可用区) 名称 + az_priority: 1 # 可用区使用的优先级，数值越小优先级越高 + # SSH 登录信息，登录用户需为 **root** 或者具有 sudo 权限的用户 + ssh_option: + port: 22 # SSH 登录用户 + user: root # SSH 登录用户密码 + password: pTk6LIBsPVplOpmxQToCPT9+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # SSH 登录密钥文件路径 + conn_timeout: 5m0s # SSH 执行单条命令时的超时时间 + exec_timeout: 5m0s # 跳板服务器登录信息，如果目标服务器无法直连时，支持通过中间跳板机方式连接 +- host: 10.1.1.101 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # - name: db HA ip list example + ha_ips: + - 10.1.1.201 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: standby # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + az_name: BJ # Available Zone (可用区) 名称 + az_priority: 1 # 可用区使用的优先级，数值越小优先级越高 + # SSH 登录信息，登录用户需为 **root** 或者具有 sudo 权限的用户 + ssh_option: + port: 22 # SSH 登录用户 + user: root # SSH 登录用户密码 + key_file: ~/.ssh/id_rsa # SSH 登录密钥文件口令 + conn_timeout: 5m0s # SSH 执行单条命令时的超时时间 + exec_timeout: 5m0s # 跳板服务器登录信息，如果目标服务器无法直连时，支持通过中间跳板机方式连接 +- host: 10.1.1.102 # 数据库实例服务器 IP (仅支持 IPv4) + db_port: 27000 # 数据库端口 + # - name: db HA ip list example + ha_ips: + - 10.1.1.202 + ha_port: 27001 # 数据库主备实例日志传输端口 + role: cascade_standby # 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + upstream_host: 10.1.1.101 # 当实例角色为 cascade_standby 时，该字段表示要跟随的上游备库 IP + az_name: SH # Available Zone (可用区) 名称 + az_priority: 2 # 可用区使用的优先级，数值越小优先级越高 +``` + +### host + +**类型**: string + +**描述**: 数据库实例服务器 IP (仅支持 IPv4) + +**示例**: + +- db host ip example + +```yaml +host: 10.1.1.100 +``` + +**新增于**: v0.1 + +### user + +**类型**: string + +**描述**: 运行数据库的操作系统用户名
如果想一套主备在同一个服务器上部署，该字段需设置为不同的用户
默认和 global.user 配置一致 + +**示例**: + +- os user example + +```yaml +user: omm +``` + +**新增于**: v0.5 + +### group + +**类型**: string + +**描述**: 运行数据库的操作系统用户组
默认和 global.group 配置一致 + +**示例**: + +- os user group example + +```yaml +group: omm +``` + +**新增于**: v0.5 + +### user_password + +**类型**: string + +**描述**: 运行数据库的操作系统用户密码
该字段不支持明文填写，需使用 ptk encrypt 加密
默认和 global.user_password 配置一致 + +**新增于**: v0.5 + +### db_port + +**类型**: int + +**描述**: 数据库端口
默认为空，复用全局的端口配置 26000 + +**示例**: + +- db port example + +```yaml +db_port: 26000 +``` + +**新增于**: v0.1 + +### base_dir + +**类型**: string + +**描述**: 数据库安装目录，默认使用 global.base_dir 的值
如果需要在单台机器上部署集群时，需在不同的实例上设置不同的安装目录，并且，实例级别仅提供设置安装目录，不支持自定义 app_dir, data_dir 等高级设置
默认值: "/opt/mogdb" + +**示例**: + +- db base dir example + +```yaml +base_dir: /opt/mogdb +``` + +**新增于**: v0.5 + +### ha_ips + +**类型**: []string + +**描述**: - name: db HA ip list example + +**新增于**: v0.1 + +### ha_port + +**类型**: int + +**描述**: 数据库主备实例日志传输端口
无特殊情况，值应为数据库端口加1 + +**新增于**: v0.1 + +### role + +**类型**: string + +**描述**: 数据库实例角色，若不填，PTK 会随机选择一个实例作为主库，其余自动为备库 + +**可选值**: + +- primary +- standby +- cascade_standby + +**示例**: + +- db role example + +```yaml +role: primary +``` + +**新增于**: v0.1 + +### upstream_host + +**类型**: string + +**描述**: 当实例角色为 cascade_standby 时，该字段表示要跟随的上游备库 IP + +**示例**: + +- cascade db upstream example + +```yaml +upstream_host: 10.1.1.101 +``` + +**新增于**: v0.1 + +### az_name + +**类型**: string + +**描述**: Available Zone (可用区) 名称
默认值："AZ1" + +**示例**: + +- db az example + +```yaml +az_name: AZ1 +``` + +**新增于**: v0.1 + +### az_priority + +**类型**: int + +**描述**: 可用区使用的优先级，数值越小优先级越高
默认值：1 + +**新增于**: v0.1 + +### xlog_dir + +**类型**: string + +**描述**: 数据库 Xlog 日志目录设置
默认为空，若需配置，值不能为数据目录的子目录 + +**新增于**: v0.1 + +### db_conf + +**类型**: map[string]string + +**描述**: 用户根据个性化需要配置数据库参数和值，该字段配置的内容将会在数据库启动前写入到 postgresql.conf 文件中 + +**示例**: + +- db config example + +```yaml +db_conf: + key: value +``` + +**新增于**: v0.1 + +### ssh_option + +**类型**: SSHOption + +**描述**: SSH 登录信息，登录用户需为 **root** 或者具有 sudo 权限的用户
不设置时为本地执行 + +**新增于**: v0.1 + +--- + +## SSHOption + +SSHOption SSH 登录认证信息，支持密码和密钥两种方式，二者需至少设置一种 + +Appears in: + +- Global.ssh_option +- CMServer.ssh_option +- DBServer.ssh_option +- SSHOption.proxy + +**示例**: + +```yaml +host: 10.1.1.100 +port: 22 +user: root +key_file: ~/.ssh/id_rsa +``` + +### host + +**类型**: string + +**描述**: 要连接的目标服务器 IP
当该机器为跳板机时必填；
当为数据库所在机器时可以留空，会继承 db_server 的 IP
默认为空 + +**新增于**: v0.1 + +### port + +**类型**: int + +**描述**: SSH 服务端口
默认值：22 + +**新增于**: v0.1 + +### user + +**类型**: string + +**描述**: SSH 登录用户
默认值：root + +**示例**: + +- ssh user example + +```yaml +user: root +``` + +**新增于**: v0.1 + +### password + +**类型**: string + +**描述**: SSH 登录用户密码
该字段不支持明文填写，需使用 ptk encrypt 加密后填写 + +**示例**: + +- ssh password example + +```yaml +password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= +``` + +**新增于**: v0.1 + +### key_file + +**类型**: string + +**描述**: SSH 登录密钥文件路径
默认为空 + +**示例**: + +- ssh key file example + +```yaml +key_file: ~/.ssh/id_rsa +``` + +**新增于**: v0.1 + +### passphrase + +**类型**: string + +**描述**: SSH 登录密钥文件口令
该字段不支持明文填写，需使用 ptk encrypt 加密后填写
默认为空 + +**新增于**: v0.1 + +### conn_timeout + +**类型**: Duration + +**描述**: SSH 登录连接超时时间，支持单位 m(分),s(秒)
默认值: "1m" + +**示例**: + +- ssh connect timeout example + +```yaml +conn_timeout: 1m +``` + +```yaml +conn_timeout: 30s +``` + +**新增于**: v0.1 + +### exec_timeout + +**类型**: Duration + +**描述**: SSH 执行单条命令时的超时时间
默认值: "10m" + +**示例**: + +- ssh execute timeout example + +```yaml +exec_timeout: 1m +``` + +```yaml +exec_timeout: 30s +``` + +**新增于**: v0.1 + +### proxy + +**类型**: SSHOption + +**描述**: 跳板服务器登录信息，如果目标服务器无法直连时，支持通过中间跳板机方式连接 + +**新增于**: v0.1 diff --git a/product/zh/docs-ptk/v0.6/debug.md b/product/zh/docs-ptk/v0.6/debug.md new file mode 100644 index 0000000000000000000000000000000000000000..33a89b325d0ece7e04f0b7bcbb5282b58f4ae261 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/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.6/faq.md b/product/zh/docs-ptk/v0.6/faq.md new file mode 100644 index 0000000000000000000000000000000000000000..419a5de5b5138a2fd69d6aa9e4507bca51b02a44 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/faq.md @@ -0,0 +1,97 @@ +--- +title: FAQ +summary: FAQ +author: Yao Qian +date: 2022-05-30 +--- + +## FAQ + +### 初始化数据库报错：undefined symbol: EVP_KDF_ctrl + +使用的安装包和机器的系统不匹配，此错误一般出现于在 glibc 版本较高的系统上使用 centos7 的安装包进行安装。 + +解决方法就是改用 openEuler 的安装包进行安装即可。 + +### 报错：can not combine with 'abrt-hook-ccpp' + +使用 abrt(automatic bug report too) 服务代理 coredump 文件，有可能导致 core 文件丢失或者数据库宕机的风险。 + +*[什么是abrt服务](https://abrt.readthedocs.io/en/latest/howitworks.html)* + +可通过修改 `kernel.core_pattern` 参数的值修复。 + +```shell +# 值根据需求可自定义 +sysctl -w kernel.core_pattern=/var/log/coredump/%e.%p.%u.%t.core +``` + +### 是否需要预装 Python3？ + +需要，且版本需为 python3.6 或者 python 3.7，因为 om 包中提供的预编译好的 psutil 动态库目前仅支持这两个版本。 + +> ptk 和 mogdb 本身不依赖 python3，gs_om、gs_guc 等工具依赖，所以建议预装好，保证环境使用顺利。 + +### 能否在 PTK 未支持的操作系统版本上使用 PTK 进行数据库安装？ + +可以。 + +PTK 本身提供完整通用的安装流程，默认情况下，PTK 会针对客户系统自动判断需要下载的数据库安装包类型，但对于超出 PTK 支持的操作系统或版本，PTK 无法为用户决定应该使用哪个安装包，此时，用户可以通过 ptk install 提供的 `-p` 参数来指定安装包安装，但由于未测试过，不一定能够正常启动，这是很正常的。 + +用户在决定自己的系统应该尝试使用哪个安装包时，可以参考如下规则： + +1. 优先判断 CPU 指令集架构 + + ```shell + uname -m + ``` + + `arm64/aarch64` 的情况考虑使用 openEuler arm64 安装包 + + `x86_64` 继续判断 + +2. 其次根据内核 glibc 版本判断 + + ```shell + getconf GNU_LIBC_VERSION + ``` + + 如果 glibc 版本小于等于 2.17，考虑使用 centos7 x86_64 的安装包，否则考虑使用 openEuler x86_64 的安装包 + +### PTK安装后，是否还支持 gs_om 操作？ + +支持。 + +PTK 安装的集群兼容 gs_om，会自动生成 gs_om 需要的静态文件。 + +> 注意：`gs_om` 的操作需要是节点之间的用户SSH互信，PTK 安装后会自动建立，若未创建需用户自行建立。 + +### 查询的状态报错 `FATAL: semctl(578486307, 7, SETVAL, 0) failed: Invalid argument` + +请检查服务器 /etc/systemd/logind.conf 中 **RemoveIPC** 的值是否为 `no`，修改后重启服务器 + +### PTK 如何查看目前可支持安装的mogdb版本？ + +执行 `ptk candidate db` 指令查看 + +### PTK 如何查看目前可支持安装的操作系统？ + +执行 `ptk candidate os` 指令查看 + +### 是否支持安装 CM 组件？ + +支持。 + +> 注意：CM 的使用目前强制要求 3 个实例及以上才可以启用。 + +ptk install 命令支持 `--install-cm` 参数，当指定了该参数时，当初始化完集群内所有节点时，会使用 cm_ctl 去启动集群（不安装 CM 时，使用 gs_ctl 工具）,使用 cm_ctl 启动的过程会涉及集群选主及主备构建的过程，所以一般耗时较长。 + +如果在 PTK 启动阶段指令超时。用户可登录到数据库服务器查看集群状态，因为在启动阶段，PTK的退出不中断 cm_ctl 后端的执行。 + +### PTK 必须和数据库在同一个服务器上吗？ + +不是的。 + +PTK 工具的设计时的定位是 “中控机” 的角色，因为 PTK 拥有管理多个数据库集群的能力，所以我们建议是 PTK 独立在一个管理服务器上安装，数据库在数据库专用的服务器集群内节点上安装。 + +当然，PTK 也是支持和数据库部署在同一个服务器上的，此时就是本地安装。 diff --git a/product/zh/docs-ptk/v0.6/install.md b/product/zh/docs-ptk/v0.6/install.md new file mode 100644 index 0000000000000000000000000000000000000000..1ece79569c05a88fea13ce0ce779d6cb6fd2085c --- /dev/null +++ b/product/zh/docs-ptk/v0.6/install.md @@ -0,0 +1,54 @@ +--- +title: 软件安装 +summary: 软件安装 +author: Yao Qian +date: 2022-05-30 +--- + +## 安装 PTK + +PTK 作为一个部署管理工具，并不需要和数据库实例安装到一起，我们推荐使用一个中控管理机器来安装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.6/overview.md b/product/zh/docs-ptk/v0.6/overview.md new file mode 100644 index 0000000000000000000000000000000000000000..52f461135648402bfe9aa5d9c4b09ccb0720b123 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/overview.md @@ -0,0 +1,70 @@ +--- +title: PTK 使用文档 +summary: PTK 使用文档 +author: Yao Qian +date: 2022-05-30 +--- + +## PTK 简介 + +PTK (Provisioning Toolkit)是一款针对 MogDB 数据库开发的软件安装和运维工具，旨在帮助用户更便捷地安装部署MogDB数据库。 + +如果用户想要运行 MogDB 或者 MogDB 的相关组件时，仅需要执行一行命令即可实现。 + +## 使用场景 + +- 开发人员快速启动多个本地MogDB环境 +- 用户通过PTK快速安装部署MogDB +- DBA日常运维使用 +- 第三方运维平台集成 + +## 推荐部署架构 + +PTK 的定位是一个多集群管理软件，作为一个中控机的角色，通过 SSH 的方式远程管理多个数据库集群，所以，我们推荐您将PTK部署在单独的一台控制服务器上，然后将数据库部署到数据库专属的服务器上，如下图。当然，PTK也支持本地部署，您可以根据您的机器情况自行安排安装位置。 + +``` + +-----------+ + | PTK | + +-----------+ + /---ssh-----/ | \---ssh----\ + / ssh \ + / | \ + +-----------+ +-----------+ +-----------+ + | MogDB | | MogDB | | MogDB | + +-----------+ +-----------+ +-----------+ +``` + +## 通过 PTK 支持安装 MogDB 的操作系统 + +> 最新列表请通过 `ptk candidate os` 查看 + +| id | os | tested version(s) +----------|-------------------------------------|---------------------------- +| 1007010 | CentOS Linux 7 (Core) (x86_64) | 7.6.1810 (Core) +| 1008010 | Centos 8 (x86_64) | 8.0.1905 (Core) +| 1008020 | Centos 8 (arm64) | 8.0.1905 (Core) +| 1120010 | openEuler 20 (x86_64) | 20.03 LTS +| 1120020 | openEuler 20 (arm64) | 20.03 LTS +| 1122010 | openEuler 22 (x86_64) | 22.03 LTS +| 1122020 | openEuler 22 (arm64) | 22.03 LTS +| 1210010 | Kylin V10 (x86_64) | V10 (Tercel) +| 1210020 | Kylin V10 (arm64) | V10 (Tercel) +| 1320010 | UOS 20 A (x86_64) | 1002a/1020a/1050a +| 1320020 | UOS 20 A (arm64) | 1050a (kongzi) +| 1420010 | UOS 20 D/E (x86_64) | 1040d (fou) +| 1420020 | UOS 20 D/E (arm64) | 1040d (fou) +| 1520010 | Ubuntu 20 (x86_64) | 20.04.3 LTS (Focal Fossa) +| 1522010 | Ubuntu 22 (x86_64) | 22.04 (Jammy Jellyfish) +| 1607010 | Red Hat Enterprise Linux 7 (x86_64) | 7.5 (Maipo) +| 1608010 | Red Hat Enterprise Linux 8 (x86_64) | 8.5 (Ootpa) +| 1702010 | EulerOS 2 (x86_64) | 2.0 (SP3) +| 1702020 | EulerOS 2 (arm64) | 2.0 (SP3) +| 1812010 | SLES 12SP5 (x86_64) | 12SP5 +| 1907010 | Oracle Linux 7 (x86_64) | 7.9 (Maipo) +| 1908010 | Oracle Linux 8 (x86_64) | 8.6 (Ootpa) +| 2008010 | Rocky Linux 8 (x86_64) | 8.5 (Green Obsidian) +| 2107010 | NeoKylin V7 (x86_64) | V7Update6 +| 2222010 | FusionOS 22 (x86_64) | 22.0.2 +| 2222020 | FusionOS 22 (arm64) | 22.0.2 + +*更多操作系统适配测试中...* diff --git a/product/zh/docs-ptk/v0.6/quick-start.md b/product/zh/docs-ptk/v0.6/quick-start.md new file mode 100644 index 0000000000000000000000000000000000000000..ff57e0d0b75259e0683172e985ef1c7330482a5f --- /dev/null +++ b/product/zh/docs-ptk/v0.6/quick-start.md @@ -0,0 +1,153 @@ +--- +title: 快速上手 +summary: 快速上手 +author: Yao Qian +date: 2022-06-02 +--- + +## 快速上手 + +本文介绍如何快速使用PTK安装 MogDB 数据库。 + +> PTK工具本身可以在多种操作系统中运行，支持Linux，macOS，Windows，但是由于 MogDB 目前仅支持 在Linux 系统中运行，因此需确保要运行MogDB数据库的服务器为 Linux 操作系统。MogDB支持的Linux操作系统种类和版本参看[通过 PTK 支持安装 MogDB 的操作系统](./overview.md#通过-ptk-支持安装-mogdb-的操作系统)。 + +## 安装演示 + +
+ +### 1. 下载并安装 PTK + +执行以下命令在线安装： + +```shell +curl --proto '=https' --tlsv1.2 -sSf https://cdn-mogdb.enmotech.com/ptk/install.sh | sh +``` + +安装完成后会提示如下信息（根据运行PTK的 SHELL 类型不同，信息会有所差异） + +``` +info: downloading ptk package +Detected shell: bash +Shell profile: /root/.bash_profile +ptk has been added to PATH in /root/.bash_profile +open a new terminal or source /root/.bash_profile to active it +Installed path: /root/.ptk/bin/ptk +``` + +可以通过提示的 source 指令或打开一个新的终端窗口来使 PTK PATH 环境变量生效。 + +假如输出的信息如上面的示例输出信息，ptk 已经自动在 /root/.bash_profile 文件中将自己的路径加入 PATH 环境变量。 + +> 请注意，并非所有系统都是 ~/.bash_profile，具体要激活哪个文件，请参考安装日志中的提示 + +以以上输出为例： + +```shell +source $HOME/.bash_profile +``` + +### 2. 通过PTK安装MogDB + +#### 2.1 准备拓扑配置文件 + +PTK 安装需用户提供一个 [YAML格式](./yaml-grammar.md) 的配置文件, 该配置文件可以通过 PTK 提供的 template 指令生成，如果是为本地安装，则可以执行： + +```shell +ptk template --local > config.yaml +``` + +配置文件的内容如下： + +```yaml +# config.yaml +global: + # # cluster name (required) + cluster_name: "cluster_etalatint" + # # system user for running db + user: "omm" + # # system user group, same as username if not given + group: "omm" + # # base directory for install MogDB server, + # # if any of app_dir，data_dir，log_dir and tool_dir not config， + # # PTK will create corresponding directory under base_dir + base_dir: "/opt/mogdb" + +db_servers: + - host: "127.0.0.1" + # # database port + db_port: 26000 +``` + +如果全部使用默认值，则PTK 执行以下行为： + +* 在本机安装数据库 +* 运行数据库的操作系统用户为omm ，用户组名称也是omm，该用户没有默认密码； +* 数据库安装在 /opt/mogdb目录下，在该目录下会创建4个目录：app, data, log, tool，分别用于存储数据库软件、数据文件、数据库日志和数据库相关工具； +* 数据库监听端口为26000； + +如果需要在其它服务器上安装MogDB，或者是安装主备架构的MogDB，则需要在config.yaml中[配置更多信息](./config.md)。详细信息可参考 [使用手册](./usage/usage-config.md)。 + +以下为安装一主一备环境的配置示例。 + +```yaml +# config.yaml +global: + cluster_name: mogdb_cluster1 + user: omm + group: omm + base_dir: /opt/mogdb +db_servers: + - host: 192.168.0.1 + db_port: 26000 + role: primary + ssh_option: + port: 22 + user: root + password: [此处填写SSH登录密码] + - host: 192.168.0.2 + db_port: 26000 + role: standby + ssh_option: + port: 22 + user: root + password: [此处填写SSH登录密码] +``` + +#### 2.2对本机进行系统检查 + +```shell +ptk checkos -f config.yaml +``` + +确保输出的检查结果均为 `OK` 或者 `Warning` 。 + +如果有 `Abnormal` 的检查项出现，PTK默认会自动生成一个 **root_fix_os** 前缀的 Shell 脚本，您可以通过执行该 Shell 脚本来尝试自动修复异常的检查项。 + +大部分情况下都是可以自动修复的，如果出现特殊情况，PTK 没有兼容到，需您根据日志提示手动修正。 + +#### 2.3 执行安装 + +```shell +ptk install -f config.yaml +``` + +默认会安装当前已经正式发布的 MogDB 最新版本，版本号可以在 MogDB 官网下载页面查询。安装过程中会提示用户输入数据库初始用户的密码，请用户自行记录并安全保存。PTK 自动完成所有安装操作后，会启动数据库实例。 + +PTK 也支持自定义安装包，可以通过手工下载安装包，指定安装。比如执行以下命令，将使用当前目录下的该安装包进行数据库安装。 + +```shell +ptk install -f config.yaml --pkg ./MogDB-3.0.0-openEuler-arm64.tar.gz +``` + +安装成功后，可以通过 `ptk ls` 来查看安装的实例信息。 + +### 3. 访问数据库 + +``` +su - omm +gsql -r +``` + +## 探索更多 + +以上示例中的拓扑配置文件以最简化模板提供，方便用户快速体验 MogDB, 若想要更全面的描述集群拓扑，请访问[拓扑文件配置](./config.md)章节了解更多参数细节。 diff --git a/product/zh/docs-ptk/v0.6/release.md b/product/zh/docs-ptk/v0.6/release.md new file mode 100644 index 0000000000000000000000000000000000000000..cc41df24dfc6e302249e766a39899c42d18726d6 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/release.md @@ -0,0 +1,106 @@ +--- +title: 发布记录 +summary: 发布记录 +author: Yao Qian +date: 2022-06-01 +--- + +## 最新版本下载 + +> 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) + +## 发布记录 + +### v0.5 + +#### 新功能 + +- 支持 MogDB-3.0.3，Uqbar-1.1.0 的安装 +- 支持单机多实例部署 +- 支持启用 CM 组件的集群在线扩缩容 +- 新增 exec 指令 +- 元数据新增日志记录功能 +- 内置 pssh 模块，解耦 om 依赖 + +#### 功能优化及Bug修复 + +- 优化扩缩容流程 +- 优化安装流程 +- 优化中断信号处理 +- 修复部分已知的bug + +### v0.4 + +#### 新功能 + +- cluster指令新增 failover/switchover 切换功能 +- cluster指令新增 show-hba/show-guc/show-config 指令，用户可方便地查看集群配置信息 +- cluster指令新增 MogHA 的安装功能 +- cluster指令新增 shell 指令，提供快速运行shell命令或脚本到集群服务器的能力 +- cluster指令新增 refesh 指令，便于用户更新集群配置，目前开放替换IP功能 +- 新增 register 指令，允许用户自己注册系统类型 +- candidate指令新增 cpu 指令，查看PTK支持的CPU架构列表 +- 集群扩容新增 copy 模式 +- 集群操作（启、停、查询）支持操作全部集群 +- 支持 MogDB 3.0.1 以上CM两节点安装 +- 支持飞腾CPU检测 +- 兼容 openGauss 安装 + +#### 功能优化及Bug修复 + +- 优化执行过程中断信号的检测和处理 +- 优化遇到信号量不足错误时的输出，给出修复建议 +- 修复az优先级配置错误导致CM启动失败的问题 +- 其他已知bug的修复 + +### v0.3 + +#### 新功能 + +- 支持扩缩容 +- 支持插件安装 +- 自动根据环境尝试修复动态库依赖 +- 集群列表结果新增版本信息 +- 新增安装包 md5 校验 +- 支持 download 指令 +- 新增集群备注功能 + +#### 功能优化及Bug修复 + +- 修复存在IB网卡时，网络检查的错误 +- 修复 suse 修复脚本指令错误 +- 其他已知问题修复及优化 + +### v0.2 + +#### 新功能 + +- 新增 candidate 指令 +- 新增 cm 安装支持 +- 系统检查自动生成修复脚本 +- 增加默认设置推荐数据库参数 + +#### Bug修复 + +- 优化安装流程 +- 修复checkos中多个检查项的问题 +- 兼容多种压缩包格式自动探测 +- 其他已知Bug修复 + +### v0.1 + +#### 新功能 + +- 实现系统检查 +- 实现数据库集群的安装和卸载 +- 实现集群管理功能：启动、停止、查询以及重启 +- 实现密码加密功能 +- 实现模板生成功能 +- 适配不同操作系统安装 +- 实现 ptk 自升级功能 diff --git a/product/zh/docs-ptk/v0.6/toc.md b/product/zh/docs-ptk/v0.6/toc.md new file mode 100644 index 0000000000000000000000000000000000000000..c9969d3c57dd1df406444e7b334bc3771c7ff3a7 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/toc.md @@ -0,0 +1,74 @@ + + +# 文档 + +## PTK 文档目录 + ++ [关于PTK](./overview.md) ++ [快速上手](./quick-start.md) ++ [软件安装](./install.md) ++ 使用手册 + + [系统检查](./usage/usage-chekos.md) + + [创建配置文件](./usage/usage-config.md) + + [安装数据库](./usage/usage-install.md) + + [操作数据库](./usage/usage-operation.md) + + [扩缩容](./usage/usage-scale.md) + + [安装插件](./usage/usage-install-plugin.md) + + [卸载数据库](./usage/usage-uninstall.md) + + [集群备注](./usage/usage-comment.md) + + [安装MogHA](./usage/usage-install-mogha.md) + + [升级PTK](./usage/usage-self-upgrade.md) + + [demo库](./usage/usage-demo.md) + + [meta操作](./usage/usage-meta.md) + + [查看帮助](./usage/usage-help.md) ++ [配置文件](./config.md) ++ [配置示例](./config-samples.md) ++ 命令介绍 + + [ptk](./command.md) + + [ptk candidate](./commands/ptk-candidate.md) + + [ptk candidate db](./commands/ptk-candidate-db.md) + + [ptk candidate os](./commands/ptk-candidate-os.md) + + [ptk candidate cpu](./commands/ptk-candidate-cpu.md) + + [ptk checkos](./commands/ptk-checkos.md) + + [ptk encrypt](./commands/ptk-encrypt.md) + + [ptk env](./commands/ptk-env.md) + + [ptk template](./commands/ptk-template.md) + + [ptk template create](./commands/ptk-template-create.md) + + [ptk template mogha](./commands/ptk-template-mogha.md) + + [ptk template scale-out](./commands/ptk-template-scale-out.md) + + [ptk install](./commands/ptk-install.md) + + [ptk ls](./commands/ptk-ls.md) + + [ptk cluster](./commands/ptk-cluster.md) + + [ptk cluster start](./commands/ptk-cluster-start.md) + + [ptk cluster stop](./commands/ptk-cluster-stop.md) + + [ptk cluster status](./commands/ptk-cluster-status.md) + + [ptk cluster restart](./commands/ptk-cluster-restart.md) + + [ptk cluster scale-out](./commands/ptk-cluster-scale-out.md) + + [ptk cluster scale-in](./commands/ptk-cluster-scale-in.md) + + [ptk cluster install-plugin](./commands/ptk-cluster-install-plugin.md) + + [ptk cluster install-mogha](./commands/ptk-cluster-install-mogha.md) + + [ptk cluster show-guc](./commands/ptk-cluster-show-guc.md) + + [ptk cluster show-hba](./commands/ptk-cluster-show-hba.md) + + [ptk cluster show-config](./commands/ptk-cluster-show-config.md) + + [ptk cluster modify-comment](./commands/ptk-cluster-modify-comment.md) + + [ptk cluster failover](./commands/ptk-cluster-failover.md) + + [ptk cluster switchover](./commands/ptk-cluster-switchover.md) + + [ptk cluster refresh](./commands/ptk-cluster-refresh.md) + + [ptk cluster shell](./commands/ptk-cluster-shell.md) + + [ptk cluster build](./commands/ptk-cluster-build.md) + + [ptk self](./commands/ptk-self.md) + + [ptk self upgrade](./commands/ptk-self-upgrade.md) + + [ptk uninstall](./commands/ptk-uninstall.md) + + [ptk exec](./commands/ptk-exec.md) + + [ptk gen-om-xml](./commands/ptk-gen-om-xml.md) + + [ptk version](./commands/ptk-version.md) + + [ptk completion](./commands/ptk-completion.md) + + [ptk meta](./commands/ptk-meta.md) + + [ptk meta home](./commands/ptk-meta-home.md) + + [ptk meta prune](./commands/ptk-meta-prune.md) + + [ptk demo](./commands/ptk-demo.md) ++ [故障排查](./debug.md) ++ [FAQ](./faq.md) ++ [发布记录](./release.md) ++ [社区](https://www.modb.pro/search?query=ptk) ++ [附录：YAML语法](./yaml-grammar.md) diff --git a/product/zh/docs-ptk/v0.6/usage/usage-chekos.md b/product/zh/docs-ptk/v0.6/usage/usage-chekos.md new file mode 100644 index 0000000000000000000000000000000000000000..376f0868406baf1c1fc89da705076fab1a662c6e --- /dev/null +++ b/product/zh/docs-ptk/v0.6/usage/usage-chekos.md @@ -0,0 +1,81 @@ +--- +title: CheckOS +summary: CheckOS +author: Yao Qian +date: 2022-07-30 +--- + +# 系统检查 + +在安装数据库之前，你需要先对要安装数据库的服务器进行一下系统参数以及软件依赖等检查，确保安装过程可以顺利执行。 + +> PTK 在检查过程中给出的系统参数值为**数据库在生产环境**中的建议值，不同系统版本或硬件配置存在参数差异，用户可根据自己的环境进行调优。 + +## 检查项列表 + +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 | 检查数据库系统安装依赖 | +| A16 | CPU指令集 | Check_CPU_Instruction_Set | 检查CPU指令集 | +| A17 | 端口状态 | Check_Port | 检查数据库端口是否被占用 | + +在使用 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 checkos --gen-warning-fix # 输出 root-fix 脚本的时候，将 warning 级别的检查项也生成修复指令 +``` + +## 检查结果分类 + +PTK 的检查结果分为四个等级： + +- **OK**：符合预期值，满足安装需求 +- **Warning**: 不符合预期值，但不影响安装（预期值主要针对生产环境进行的建议） +- **Abnormal**: 不满足安装要求，可能会导致安装过程失败，需根据 PTK 给出的修改建议脚本，人工执行修改 +- **ExecuteError**: 执行错误，该等级表示 PTK 在检查时执行命令失败，可能为用户环境工具缺失或内部BUG，需根据实际错误提示进行修正 + +在安装数据库之前，需确保所有的检查项都在 **OK** 或 **Warning** 级别，如果存在 **Abnormal** 的检查结果，在安装时会报错退出。 + +## 更多参数 + +更新参数的使用说明请通过 `ptk checkos -h` 查看 + +```shell +Usage: + ptk checkos [flags] + +Flags: + --detail 打印每个检查项的详细信息 + -f, --file string 指定集群配置文件 + --gen-warning-fix 输出 abnormal 和 warning 项目的修复语句，默认仅输出 abnormal 的项目修复语句 + -h, --help help for checkos + -i, --item string 指定检查项编号，多个编号间使用英文逗号分隔 (default "A") + --only-abnormal-detail 仅显示Abnormal级别的信息 + -o, --output string 指定结果输出文件路径 +``` diff --git a/product/zh/docs-ptk/v0.6/usage/usage-comment.md b/product/zh/docs-ptk/v0.6/usage/usage-comment.md new file mode 100644 index 0000000000000000000000000000000000000000..9d592641bf65a0042d31c917118726b85240a574 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/usage/usage-comment.md @@ -0,0 +1,20 @@ +--- +title: Cluster Comment +summary: Cluster Comment +author: Yao Qian +date: 2022-09-15 +--- + +# 集群备注 + +PTK 在安装数据库集群时，支持通过 `--comment` 参数来指定一段针对该集群的备注信息。 + +安装成功后，备注信息会在 ls 查看集群列表时显示。 + +## 修改备注信息 + +当需要修改某个集群的备注信息时，可通过如下执行进行修改： + +```shell +ptk cluster -n CLUSTER_NAME modify-comment --comment "new comment" +``` diff --git a/product/zh/docs-ptk/v0.6/usage/usage-config.md b/product/zh/docs-ptk/v0.6/usage/usage-config.md new file mode 100644 index 0000000000000000000000000000000000000000..72f09a996859ea23a762706fe0049a14f69601c4 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/usage/usage-config.md @@ -0,0 +1,242 @@ +--- +title: Config +summary: Config +author: Yao Qian +date: 2022-07-30 +--- + +# 创建配置文件 + +## 手动配置 + +在安装数据库之前，需通过 PTK 来创建一个配置文件，用于描述期望的数据库集群拓扑结构。 + +如果要安装单实例数据库，可以通过以下命令生成配置文件： + +```shell +ptk template -l > config.yaml +``` + +如果要安装多实例集群，则可以通过以下命令生成配置文件： + +```shell +ptk template > config.yaml +``` + +运行后会在当前文件夹内生成 config.yaml 文件，用户需修改文件内 db_server 相关的字段。 + +如果存在密码字段，用户需通过 [ptk encrypt](../commands/ptk-encrypt.md) 指令加密后写入配置文件。 + +> 注意： +> 如果您希望 PTK 使用非 root 用户来连接目标机器操作, 请确保该用户在目标机器上具有免密执行 sudo 的权限， +> 配置方式：可在目标机器上的 /etc/sudoers 文件中新增如下一行（USERNAME 替换为SSH连接用户名） ： +> `[USERNAME] ALL=(ALL) NOPASSWD:ALL` + +## 交互式创建 + +PTK 也支持通过交互式方式创建配置文件，只需执行如下命令: + +```shell +ptk template create +``` + +执行后，会进入交互式终端，用户只需根据提示的问题，逐个填写即可。 + +注意，在填写 db_server 时，SSH 的链接信息如果相同可重复使用。 + +当交互式终端退出后，会自动在当前文件夹下创建一个 config.yaml 的文件。 + +### 交互式创建示例 + +默认情况下，大部分字段可使用系统生成的默认值，回车即可，密码字段需用户手动输入。 + +下面是创建一主一备的配置文件的示例，假设主在本机，备机IP为 `192.168.1.100` + +```shell +$ ptk template create +请输入集群名称: (default: cluster_igiltry) +请输入系统用户名: (default: omm) +请输入用户组名: (default: omm) +请输入数据库初始密码(需8到16位) +请再次输入数据库密码确认: +请输入数据库监听端口，取值范围 [1024~65535]: (default: 26000) +请输入CM sever的监听端口, 取值范围[1024~65535]: (default: 15300) +请输入数据库要安装的目录(需确保为空): (default: /opt/mogdb) +接下来, 我们来添加一些数据库实例服务器 +================db server 1================ +请输入服务器IP(仅支持IPv4): 127.0.0.1 +请选择数据库角色: + 1: primary + 2: standby + 3: cascade_standby +请输入选项编号: 1 +请输出数据库的 available zone 名称: (default: AZ1) +================ end ================ +Do you want to add another db server?[Y|Yes](default=N) y +================db server 2================ +请输入服务器IP(仅支持IPv4): 192.168.1.100 +请选择数据库角色: + 1: primary + 2: standby + 3: cascade_standby +请输入选项编号: 2 +请输出数据库的 available zone 名称: (default: AZ1) +[SSH] 请输入 SSH 登录用户: (default: root) +[SSH] 请输入 SSH 端口: (default: 22) +[SSH] 请选择验证方式: + 1: Password + 2: KeyFile +请输入选项编号: 1 +[SSH] 请输入 SSH 登录密码: +================ end ================ +Do you want to add another db server?[Y|Yes](default=N) n +Generate /Users/vimiix/Home/enmotech/ptk/ptk_repo/config.yaml successfully +``` + +## 配置文件字段说明 + +我们以下面这个完整的配置文件为例说明： + +> yaml 中，如果是字符串类型默认无需加引号，如果字符串之中包含空格或特殊字符，需要放在引号之中 + +```yaml +global: + # # 集群名称，用户自定义 + cluster_name: c1 + # # 运行数据的系统用户 + user: omm + # # 系统用户组，默认和用户名同名 + group: omm + # # 系统用户密码，PTK在创建用户时设置，可不填。若填写需通过 ptk encrypt 加密 + # user_password: "" + # # 数据库密码，需通过 ptk encrypt 加密。若不填写，在安装时会通过交互式填写 + db_password: "" + # # 数据库端口 + db_port: 26000 + # # 数据库的安装目录 + # # PTK 会在该目录下分别创建应用目录，数据目录，工具目录，日志目录以及临时目录 + base_dir: /opt/mogdb + # # gs_initdb 工具支持参数列表，安装时会追加到指令中 + gs_initdb_opts: + - --encoding=UTF-8 + - --dbcompatibility=A + # # CM 组件的配置，该值在启用CM组件时生效 + cm_option: + # # CM 的安装目录，不填写默认会在 base_dir 目录下创建 cm 目录 + # dir: /opt/mogdb/cm + # # CM Server 端口 + cm_server_port: 15300 + # # 虚拟IP，该值需CM支持的版本才生效 + db_service_vip: "" + # # CM Server 配置，会更新到 cm_server.conf 中 + cm_server_conf: + # instance_heartbeat_timeout: 2 + # ... + # # CM Agent 配置，会更新到 cm_agent.conf 中 + cm_agent_conf: + # log_max_size: 10240 + # ... + +db_servers: + - host: 10.0.1.100 + # # 数据库端口 + db_port: 26000 + # # 数据库角色，支持的选项: primary, standby, cascade_standby + role: primary + # # 可用区名称，该值在启用CM组件时生效 + az_name: AZ1 + # # 可用区优先级，值越小优先级越高，最小 1，该值在启用CM组件时生效 + az_priority: 1 + # # 级联备的上游备库IP，仅级联备时必填 + upstream_host: + # # postgresql.conf 中支持的参数 + db_conf: + # replication_type: 1 + # # 连接服务器的SSH配置 + # ssh_option: + # port: 22 + # user: root + # password: +# cm 服务器列表，如果不在这里列出，在安装时会在每个 db_server 的机器上部署 +# 注意此处配置不意味着安装，需在安装时指定 --install-cm 参数才会生效 +cm_servers: + - host: 10.0.1.100 + # # CM Server 端口，默认为 global.cm_option.cm_server_port + port: 15300 + # # ssh 配置信息，如果 db_server 有相同机器配置过，则无需在此处配置 + ssh_option: +``` + +整个配置文件分为两个部分：`global` 和 `db_servers` + +- **global**: 定义集群内所有实例公用的信息及缺省值 +- **db_servers**: 实例列表，每个元素代表一个实例信息 + +### global 配置 + +字段名 | 解释 | 值类型 | 默认值 | 是否必填 | 备注 +------|-------|-----|------|------ | ------ +cluster_name | 集群名称 | 字符串 | `cluster_` 前缀，随机生成| 是 +user | 操作系统用户 | 字符串| omm | 否 +group | 操作系统用户组 | 字符串| omm | 否 +user_password | 操作系统用户密码 | 字符串 | 空 | 否 | 需通过 encrypt 指令加密后填写 +db_password | 数据库密码 | 字符串| 空 | 否 | 需通过 encrypt 指令加密后填写，若不填写，安装过程也可以填写 +db_port | 数据库监听端口 | 整型| 26000 | 否| +base_dir | 数据库安装的基础目录 | 字符串| /opt/mogdb | 否 | 若填写该字段，app_dir, log_dir, data_dir, tool_dir, cm_dir, tmp_dir 可不填写，自动放置到该字段指定的目录下 +app_dir | 数据库应用目录 | 字符串| /opt/mogdb/app | 否| +log_dir | 数据库日志存放目录 | 字符串 | /opt/mogdb/log | 否| +data_dir | 数据库数据存放目录 | 字符串 | /opt/mogdb/data | 否| +tool_dir | 数据库工具存放目录 | 字符串| /opt/mogdb/tool | 否| +tmp_dir | 数据库临时文件存放目录 | 字符串 | /opt/mogdb/tmp | 否| +core_file_dir | 系统 corefile 路径 | 字符串 | 空 | 否 | 若填写会修改系统 `kernel.core_pattern` 的值 +gs_initdb_opts | 初始化数据库时 gs_initdb 工具的参数 | 字符串列表 | 否 | 一个元素设置一个参数，如果未设置 `--locale` 参数，PTK 默认设置 `--no-locale` +ssh_option | SSH连接认证信息 | [ssh_option](#ssh_option) | 否 | 实例如果需要远程连接，但实例级别的 ssh_option 未配置时会使用 global 内的该字段 +cm_option | CM组件配置参数 | [cm_option](#cm_option) | 否 | 该字段在安装时指定 `--install-cm` 时生效 + +### db_servers 配置 + +字段名 | 解释 | 值类型 | 默认值 | 是否必填 | 备注 +------|-------|-----|------|------ | ------ +host | 实例IP | 字符串 | 空 | 是 | +db_port | 实例端口 | 整型 | 26000 | 否 | 若未填写，使用 global 内的配置 +ha_ips | 实例日志复制备用IP列表 | 字符串列表 | 空 | 否 | +ha_port | 日志复制备用端口 | 整型 | 26001 | 否 | +role | 数据库实例角色 | 字符串 | 空 | 否 | 可选值： `primary`, `standby`, `cascade_standby`, 若不填写，集群内随机选择一个实例设置主，其余为备库 +upstream_host | 级联备上游备库IP | 字符串 | 空 | 级联备时必填 | +az_name | 可用区名 | 字符串 | AZ1 | 否 | +az_priority | 可用区优先级 | 整型 | 1 | 数值越小优先级越高 +xlog_dir | xlog 日志目录 | 字符串 | 空 | 默认会放到 log_dir 的 pg_log 下，若配置该字段，不能为数据目录的子目录，否则启动报错 +db_conf | 数据库guc 参数配置 | 字典 | 空 | 字典键为 postgresql.conf 中的参数 +ssh_option | 连接实例时的ssh 连接认证信息 | [ssh_option](#ssh_option) | 否 | 若未设置使用 global 内的配置 + +### cm_servers 配置 + +字段名 | 解释 | 值类型 | 默认值 | 是否必填 | 备注 +------|-------|-----|------|------ | ------ +host | 实例IP | 字符串 | 空 | 是 | +port | CM Server端口 | 整型 | 15300 | 否 | 若未填写，使用 global.cm_option.cm_server_port 的值 +ssh_option | 连接实例时的ssh 连接认证信息 | [ssh_option](#ssh_option) | 否 | 若未设置使用 global 内的配置或db_servers 中相同IP的配置 + +### cm_option + +字段名 | 解释 | 值类型 | 默认值 | 是否必填 | 备注 +------|-------|-----|------|------ | ------ +dir | CM 安装目录 | 字符串 | $base_dir/cm | 是 | +cm_server_port | CM server 监听端口 | 整型 | 15300 | 否| +db_service_vip | 虚拟IP（需CM支持） | 字符串 | 空 | 否 | +cm_server_conf | CM sever 配置参数 | 字典| 空 | 否 | 该字段下字典的键支持任何 cm_server 的参数，PTK 会将值设置到 cm_server.conf 文件中 +cm_agent_conf | CM agent 配置参数 | 字典 | 空 | 否 | 该字段下字典的键支持任何 cm_agent 的参数，PTK 会将值设置到 cm_agent.conf 文件中 + +### ssh_option + +字段名 | 解释 | 值类型 | 默认值 | 是否必填 | 备注 +------|-------|-----|------|------ | ------ +host | 机器IP | 字符串 | 实例的IP | 否 | 如果配置为 proxy 跳板机时，该字段必填 +port | ssh 连接端口 | 整型 | 22 | 否 | +user | ssh 连接用户 | 字符串 | root | 否 | 如果连接的用户为非 root 时，需确保该用户具有免密执行 sudo 的权限 +password | ssh 连接密码 | 字符串 | 空 | 否 | 需通过 encrypt 指令加密后填写 +key_file | ssh 连接密钥文件 | 字符串 | 空 | 否 | +passphrase | ssh 连接密钥文件的口令 | 字符串 | 空 | 否 | +conn_timeout | ssh 连接超时时间 | Duration | 1m | 否 | +exec_timeout | 执行命令超时时间 | Duration | 10m | 否 | +proxy | 跳板机配置 | ssh_option | 空 | 否 | 仅支持跳一次连接 diff --git a/product/zh/docs-ptk/v0.6/usage/usage-demo.md b/product/zh/docs-ptk/v0.6/usage/usage-demo.md new file mode 100644 index 0000000000000000000000000000000000000000..e509f9b0afb186022316b5665a7f984f66f96efc --- /dev/null +++ b/product/zh/docs-ptk/v0.6/usage/usage-demo.md @@ -0,0 +1,38 @@ +--- +title: ptk demo +summary: ptk demo +author: Jerad.K +date: 2023-01-10 +--- + +# 安装demo +demo子命令是为了在当前服务器上快速安装一个demo库为用户提供使用，可选参数--port可自定义demo数据库的端口（默认26000） + +# 前提 +目前仅限linux操作系统使用 + +# 安装demo库会提供哪些模式？ +目前MogDB共支持4种模式，分别为： +- A表示同O数据库兼容 +- B表示同MY数据库兼容 +- C表示同TD数据库兼容 +- PG表示同POSTGRES数据库兼容 + +当执行ptk demo命令安装demo库后，默认的postgres数据库为PG模式，同时会创建另一个A模式的oracle_compatibility数据库 + +# 安装demo库会安装哪些插件？ +针对A模式的oracle_compatibility库，安装的插件列表如下： +- [whale](https://docs.mogdb.io/zh/mogdb/v3.0/whale) +- [orafce](https://docs.mogdb.io/zh/mogdb/v3.0/orafce-user-guide) +- [compat_tools](https://gitee.com/enmotech/compat-tools) +- [mogila](https://gitee.com/enmotech/mogila) + + +# 安装的demo库和通过配置文件安装的集群有什么区别？ +没有区别。 + +通过`ptk install`安装的集群，ptk能对其执行的操作均能对demo库进行操作，包含但不限于的操作有 +- 卸载 +- cluster下的一些操作 +- 扩缩容的操作 +... diff --git a/product/zh/docs-ptk/v0.6/usage/usage-help.md b/product/zh/docs-ptk/v0.6/usage/usage-help.md new file mode 100644 index 0000000000000000000000000000000000000000..26926cb7cf714f93cbf343939dee1f4c9b4f63ea --- /dev/null +++ b/product/zh/docs-ptk/v0.6/usage/usage-help.md @@ -0,0 +1,79 @@ +--- +title: 使用手册 +summary: 使用手册 +author: Yao Qian +date: 2022-05-30 +--- + +## 查看帮助 + +当安装成功 PTK 以后，可以在终端运行 `ptk -h` 来查看帮助信息，关于命令参数的含义说明，请参考[命令介绍}](../command.md) + +``` +PTK是一款部署和管理MogDB数据库集群的命令行工具 + +Usage: + ptk [flags] [args...] + ptk [command] + +Available Commands: + env 打印 PTK 加载的环境变量值 + gen-om-xml 生成 gs_om 的 XML 配置文件 + self 操作 PTK 自身安装包 + version 打印 PTK 版本 + help 打印PTK帮助信息 + completion Generate the autocompletion script for the specified shell + +Pre Install Commands: + candidate 打印 PTK 支持的软件版本列表 + download 在线下载 MogDB 安装包 + checkos 检查集群服务器系统依赖是否满足安装数据库需求 + encrypt 提供一个便捷的方式来加密您的文本或密码 + template 打印配置模板 + +Install Commands: + install 基于给定的拓扑配置部署MogDB数据库集群 + uninstall 卸载 MogDB 数据库集群 + +Post Install Commands: + ls 列出所有MogDB集群列表 + cluster 数据库集群管理的操作 + +Experimental Commands: + register 注册PTK内部类型满足特定需求 + +Flags: + -h, --help 打印PTK帮助信息 + --log-file string 指定运行日志文件路径 + --log-format string 指定运行日志的输出格式, 可选项: [text, json] (default "text") + --log-level string 指定运行日志级别, 可选项: [debug, info, warning, error, panic] (default "info") + -v, --version 打印 PTK 版本 + +Use "ptk [command] --help" for more information about a command. +``` + +## 查看版本 + +可以通过 `ptk -v` 来查看 PTK 版本信息，以下为示例： + +```shell +$ ptk -v +PTK Version: v0.4.0 +Go Version: go1.17.1 +Build Date: 2022-09-14T09:32:14Z +Git Hash: a9xa9e +``` + +从版本信息可以得知 PTK 的版本号，编译的 Golang 版本，构建时间以及构建时的哈希值。 + +## 更多 + +- [系统检查](./usage-chekos.md) +- [创建配置文件](./usage-config.md) +- [安装数据库](./usage-install.md) +- [操作数据库](./usage-operation.md) +- [扩缩容](./usage-scale.md) +- [安装插件](./usage-install-plugin.md) +- [卸载数据库](./usage-uninstall.md) +- [集群备注](./usage-comment.md) +- [升级PTK](./usage-self-upgrade.md) diff --git a/product/zh/docs-ptk/v0.6/usage/usage-install-mogha.md b/product/zh/docs-ptk/v0.6/usage/usage-install-mogha.md new file mode 100644 index 0000000000000000000000000000000000000000..028ea6213413d30a909f39e833ba54b4f69dc1b3 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/usage/usage-install-mogha.md @@ -0,0 +1,28 @@ +--- +title: Cluster Install MogHA +summary: Cluster Install MogHA +author: Yao Qian +date: 2022-09-15 +--- + +# MogHA 安装 + +PTK 支持基本的 MogHA 安装流程，需用户提供合法的 MogHA 配置文件。 + +> 当前版本中，PTK 不对 MogHA 的配置文件进行校验，直接将用户提交的文件部署到集群服务器，所以需用户确保其正确性。 + +MogHA 分为 lite 模式和非 lite 模式，lite 模式仅会在主库和同步备库部署，非 lite 模式会在集群内所有节点进行部署。 + +## 生成配置文件模板 + +PTK 提供了模板指令来帮助用户自动生成 MogHA 的配置文件： + +```shell +ptk template mogha -n CLUSTER_NAME [-o node.conf] [--port 8081] +``` + +## 安装方式 + +```shell +ptk cluster -n CLUSTER_NAME install-mogha -d INSTALL_DIR -c node.conf [-p MOGHA_PACKAGE] +``` diff --git a/product/zh/docs-ptk/v0.6/usage/usage-install-plugin.md b/product/zh/docs-ptk/v0.6/usage/usage-install-plugin.md new file mode 100644 index 0000000000000000000000000000000000000000..10b86e05742231b371939d1d8d2f1b3932b7ad39 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/usage/usage-install-plugin.md @@ -0,0 +1,95 @@ +--- +title: Install Plugin +summary: Install Plugin +author: Yao Qian +date: 2022-07-30 +--- + +# 插件安装 + +> MogDB 插件的使用请参考[相关文档](https://docs.mogdb.io/zh/mogdb/v3.0/dblink-user-guide) + +PTK 插件安装会自动通过判断当前集群的版本，下载对应的插件包进行安装。 + +安装成功后，PTK 不会在数据库中创建 extension，需用户根据需要手动在数据库中参考插件安装指导进行创建。 + +## 查看帮助文档 + +```shell +# ptk cluster install-plugin -h +安装MogDB插件 + +Usage: + ptk cluster install-plugin [flags] + +Flags: + -h, --help help for install-plugin + -H, --host strings 指定待安装的主机 IP，默认将安装到集群中的所有主机 + -n, --name string 集群名称 + --override 是否覆盖现有插件文件 + -p, --pkg string 指定插件包路径 + -P, --plugin strings 指定要安装的插件名称，默认会安装所有插件 +``` + +## 安装全部插件 + +默认 PTK 会下载对应版本的安装包后安装全部插件到数据库，若需指定插件安装，可通过 `-P` 或 `--plugin` 指定。 + +安装示例： + +``` +# ptk cluster -n cluster_slirist install-plugin +INFO[2022-08-02T16:15:11.786] downloading Plugins-3.0.0-CentOS-x86_64.tar.gz... +> Plugins-3.0.0-CentOS-x86_64...: 70.71 MiB / 70.71 MiB [-----------------------------------------------] 100.00% 14.33 MiB p/s 5.1s +INFO[2022-08-02T16:15:17.629] download successfully +INFO[2022-08-02T16:15:17.651] scp file from /tmp/2451478859/Plugins-3.0.0-CentOS-x86_64.tar.gz to 192.168.122.101:/opt/mogdb/tool/Plugins-3.0.0-CentOS-x86_64.tar.gz host=192.168.122.101 +INFO[2022-08-02T16:15:17.651] scp file from /tmp/2451478859/Plugins-3.0.0-CentOS-x86_64.tar.gz to 192.168.122.102:/opt/mogdb/tool/Plugins-3.0.0-CentOS-x86_64.tar.gz host=192.168.122.102 +INFO[2022-08-02T16:15:17.781] mkdir /opt/mogdb/tool/plugins host=192.168.122.101 +> upload Plugins-3.0.0-CentOS...: 70.71 MiB / 70.71 MiB [--------------------------------------------------------] 100.00% 124.92 MiB p/s 800ms +INFO[2022-08-02T16:15:18.437] mkdir /opt/mogdb/tool/plugins host=192.168.122.102 +INFO[2022-08-02T16:15:18.606] decompress Plugins-3.0.0-CentOS-x86_64.tar.gz to dir /opt/mogdb/tool/plugins host=192.168.122.102 +INFO[2022-08-02T16:15:19.816] change /opt/mogdb/tool/plugins owner to vmx host=192.168.122.101 +INFO[2022-08-02T16:15:20.542] change /opt/mogdb/tool/plugins owner to vmx host=192.168.122.102 +INFO[2022-08-02T16:15:20.562] installing plugin [dblink] ... host=192.168.122.101 +INFO[2022-08-02T16:15:20.562] installing plugin [dolphin] ... host=192.168.122.102 +INFO[2022-08-02T16:15:20.627] plugin [dblink] installed successfully host=192.168.122.101 +INFO[2022-08-02T16:15:20.627] installing plugin [wal2json] ... host=192.168.122.101 +INFO[2022-08-02T16:15:20.668] plugin [wal2json] installed successfully host=192.168.122.101 +INFO[2022-08-02T16:15:20.668] installing plugin [pg_bulkload] ... host=192.168.122.101 +INFO[2022-08-02T16:15:20.725] plugin [dolphin] installed successfully host=192.168.122.102 +INFO[2022-08-02T16:15:20.725] installing plugin [postgis] ... host=192.168.122.102 +INFO[2022-08-02T16:15:20.734] plugin [pg_bulkload] installed successfully host=192.168.122.101 +INFO[2022-08-02T16:15:20.734] installing plugin [pg_prewarm] ... host=192.168.122.101 +INFO[2022-08-02T16:15:20.771] plugin [pg_prewarm] installed successfully host=192.168.122.101 +INFO[2022-08-02T16:15:20.771] installing plugin [dolphin] ... host=192.168.122.101 +INFO[2022-08-02T16:15:20.881] plugin [dolphin] installed successfully host=192.168.122.101 +INFO[2022-08-02T16:15:20.881] installing plugin [postgis] ... host=192.168.122.101 +INFO[2022-08-02T16:15:20.985] plugin [postgis] installed successfully host=192.168.122.102 +INFO[2022-08-02T16:15:20.985] installing plugin [dblink] ... host=192.168.122.102 +INFO[2022-08-02T16:15:21.042] plugin [dblink] installed successfully host=192.168.122.102 +INFO[2022-08-02T16:15:21.042] installing plugin [wal2json] ... host=192.168.122.102 +INFO[2022-08-02T16:15:21.075] plugin [postgis] installed successfully host=192.168.122.101 +INFO[2022-08-02T16:15:21.075] installing plugin [pg_trgm] ... host=192.168.122.101 +INFO[2022-08-02T16:15:21.112] plugin [wal2json] installed successfully host=192.168.122.102 +INFO[2022-08-02T16:15:21.112] installing plugin [pg_bulkload] ... host=192.168.122.102 +INFO[2022-08-02T16:15:21.117] plugin [pg_trgm] installed successfully host=192.168.122.101 +INFO[2022-08-02T16:15:21.117] installing plugin [orafce] ... host=192.168.122.101 +INFO[2022-08-02T16:15:21.160] plugin [orafce] installed successfully host=192.168.122.101 +INFO[2022-08-02T16:15:21.160] installing plugin [pg_repack] ... host=192.168.122.101 +INFO[2022-08-02T16:15:21.200] plugin [pg_repack] installed successfully host=192.168.122.101 +INFO[2022-08-02T16:15:21.200] installing plugin [whale] ... host=192.168.122.101 +INFO[2022-08-02T16:15:21.208] plugin [pg_bulkload] installed successfully host=192.168.122.102 +INFO[2022-08-02T16:15:21.208] installing plugin [pg_prewarm] ... host=192.168.122.102 +INFO[2022-08-02T16:15:21.243] plugin [whale] installed successfully host=192.168.122.101 +INFO[2022-08-02T16:15:21.266] plugin [pg_prewarm] installed successfully host=192.168.122.102 +INFO[2022-08-02T16:15:21.266] installing plugin [pg_trgm] ... host=192.168.122.102 +INFO[2022-08-02T16:15:21.321] plugin [pg_trgm] installed successfully host=192.168.122.102 +INFO[2022-08-02T16:15:21.321] installing plugin [orafce] ... host=192.168.122.102 +INFO[2022-08-02T16:15:21.384] plugin [orafce] installed successfully host=192.168.122.102 +INFO[2022-08-02T16:15:21.384] installing plugin [pg_repack] ... host=192.168.122.102 +INFO[2022-08-02T16:15:21.444] plugin [pg_repack] installed successfully host=192.168.122.102 +INFO[2022-08-02T16:15:21.444] installing plugin [whale] ... host=192.168.122.102 +INFO[2022-08-02T16:15:21.510] plugin [whale] installed successfully host=192.168.122.102 +INFO[2022-08-02T16:15:26.949] All done +INFO[2022-08-02T16:15:26.949] Time elapsed: 15s +``` diff --git a/product/zh/docs-ptk/v0.6/usage/usage-install.md b/product/zh/docs-ptk/v0.6/usage/usage-install.md new file mode 100644 index 0000000000000000000000000000000000000000..984e1c5b078dedf59889bad9a1e1fb999a70b366 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/usage/usage-install.md @@ -0,0 +1,82 @@ +--- +title: Install +summary: Install +author: Yao Qian +date: 2022-07-30 +--- + +# 数据库安装 + +## 查看帮助文档 + +当有了配置文件，并且系统检查也都通过后，就可以开始数据库安装了。 + +在操作数据库安装之前，建议先熟悉安装的一些常用参数，可通过 `ptk install -h` 查看： + +```shell +基于给定的拓扑配置部署MogDB数据库集群 + +Usage: + ptk install [flags] + +Flags: + -y, --assumeyes 自动对所有提问回复Yes + --db-version string 指定数据库安装包的版本(仅限在线安装) + 可通过 'ptk candidate db' 查看支持的 MogDB Server 版本列表 (default "3.0.0") + --default-guc 不自动优化 GUC 参数，使用数据库默认参数 + -e, --env strings 环境变量将被添加到系统用户的配置文件中 + -h, --help help for install + --install-cm 安装CM组件 + --launch-db-timeout duration 启动数据库超时时间 (default 10m0s) + --no-cache 不使用本地缓存的安装包 + -p, --pkg string 指定数据库安装包的文件路径或URL + --post-run string 指定 Bash 脚本路径，将在部署成功后分发到每个服务器上运行 + --pre-run string 指定 Bash 脚本路径，将在执行部署数据库之前分发到每个服务器上运行 + --skip-check-distro 跳过系统发行版检查，直接安装 + --skip-check-os 跳过系统环境检查，直接安装 + --skip-create-user 跳过创建系统用户 + --skip-launch-db 跳过启动数据库 + --skip-rollback 安装失败时跳过回滚操作 +``` + +### 安装 + +使用 PTK 安装数据库集群很简单，安装仅需输入以下指令即可： + +```shell +$ ptk install -f config.yaml -y +``` + +`-f` 指定配置文件路径，`-y` 表示自动所有交互式问询回复 Yes。 + +> 注：当配置文件中没有配置数据库初始密码时，`-y` 无法跳过询问密码流程 + +默认 PTK 会自动从网络下载 MogDB 的最新版进行安装。 + +如果你想要指定安装不同的版本或者想要安装自己编译的安装包，PTK 也是支持的。 + +PTK 提供了 `--db-version` 参数，来允许用户指定要安装的 MogDB 版本， + +假如想要安装 MogDB 2.1.1 版本： + +```shell +ptk install -f config.yaml --db-version 2.1.1 -y +``` + +> 支持安装的数据库版本列表可通过 ptk candidate db 查看 + +如果你希望安装自己编译的安装包，需通过 `-p|--pkg` 参数指定本地安装包路径或者网络下载地址. + +更多选项： + +- `-e|--env` : 环境变量将被添加到安装后的数据库系统用户的环境变量中 +- `--launch-db-timeout`: 启动数据库超时时间，默认 5 分钟。 +- `--pre-run`: 支持添加安装前的一个钩子 shell 脚本路径，在集群安装前，自动在集群内所有机器上执行指定的脚本 +- `--post-run`: 支持添加安装后的一个钩子 shell 脚本路径，在集群安装成功后，自动在集群内所有机器上执行指定的脚本 +- `--skip-check-os`: 跳过系统检查 +- `--skip-check-distro` : 跳过系统发行版检查，直接安装 +- `--skip-create-user`: PTK 默认会自动创建用户，指定该参数可以跳过创建用户，当指定该参数时，服务器上用户必须已经存在 +- `--skip-launch-db`: 安装完成后不启动数据库 +- `--skip-rollback`: PTK 在安装过程中如果出现错误，默认会回滚之前的所有操作来清理环境，指定该参数可以禁止回滚操作。 +- `--install-cm`: 安装数据库的同时，安装CM组件（仅适用于MogDB版本大于3.0.0且集群内实例数量大于3个） +- `--no-cache`: 不使用本地缓存的安装包，强制从网络重新下载 \ No newline at end of file diff --git a/product/zh/docs-ptk/v0.6/usage/usage-meta.md b/product/zh/docs-ptk/v0.6/usage/usage-meta.md new file mode 100644 index 0000000000000000000000000000000000000000..4a94b0dc2c2c1645da6e442ff38c1f23ee3b7a10 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/usage/usage-meta.md @@ -0,0 +1,25 @@ +--- +title: ptk meta +summary: ptk meta +author: Jerad.K +date: 2023-01-10 +--- + +# prune +```shell +ptk meta prune -n ${CLUSTER_NAME} +``` +ptk为用户提供的用于清理元数据的一个子命令 + +## 可选参数 +- `--force`: 不会检查该集群的冗余数据（数据库的相应目录，用户等），直接清理指定集群的元数据 + +## 输出 +元数据清理成功或失败 + +# home +```shell +ptk meta home +``` +## 输出 +显示当前ptk元数据所在的目录 \ No newline at end of file diff --git a/product/zh/docs-ptk/v0.6/usage/usage-operation.md b/product/zh/docs-ptk/v0.6/usage/usage-operation.md new file mode 100644 index 0000000000000000000000000000000000000000..79cd594a2a41d8a847b3b70de6d4f5409e20d267 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/usage/usage-operation.md @@ -0,0 +1,236 @@ +--- +title: Operation +summary: Operation +author: Yao Qian +date: 2022-07-30 +--- + +# 数据库操作 + +## 查看集群列表 + +当数据库集群安装成功后，可以通过 `ptk ls` 来查看当前用户已经安装过的集群列表（由于 PTK 的元数据存储于 `$HOME/.ptk` 目录下，所以仅能查看当前用户安装的，无法查看其他用户安装的集群列表）。 + +示例： + +```shell +$ ptk ls +cluster_name| id | addr | user | data_dir | db_version | create_time | comment +------------------+------+-----------------------+------+-----------------------+------------------------------+---------------------+---------- + c1 | 6001 | 192.168.100.100:26000 | ptk1 | /home/ptk1/mogdb/data | MogDB 3.0.3 (build 23ba838d) | 2022-11-09 15:01:34 | +``` + +可以在输出表中查看如下信息： + +- cluster_name: 集群名称 +- id: 安装时给实例分配的ID +- addr: 实例地址列表 +- user: 运行的系统用户 +- data_dir: 实例的数据目录 +- db_version: 数据库版本信息 +- create_time: 集群创建时间 +- comment: 集群备注 + +集群安装成功后，在之后管理集群操作时，使用 `-n` 参数指定集群名称来管理集群。 + +## 查看集群状态 + +可以通过 `cluster status` 指令查看集群状态 + +```shell +# ptk cluster -n c1 status + +[ Cluster State ] +database_version : MogDB 3.0.3 (build 23ba838d) +cluster_name : c1 +cluster_state : Normal + +[ Datanode State ] +cluster_name | id | ip | port | user | instance | db_role | state +-------------+-------+-----------------+-------+------+----------+---------+--------- + c1 | 6001 | 192.168.122.101 | 26000 | ptk | dn_6001 | primary | Normal + | 6002 | 192.168.122.102 | 26000 | ptk | dn_6002 | standby | Normal +``` + +## 启动集群 + +> 下面的集群操作以集群 `c1` 为例 + +在安装完数据库集群后，PTK 默认会将数据库集群启动。 + +如果安装时指定了 `--skip-launch-db` 的话，数据库会处于停止状态。 + +此时可通过 `cluster start` 指令启动集群，需指定集群的集群名称。 + +示例： + +```shell +# ptk cluster -n c1 start +INFO[2022-08-02T11:40:48.728] Operating: Starting. +INFO[2022-08-02T11:40:48.728] ========================================= +INFO[2022-08-02T11:40:48.784] starting host 192.168.122.101 +INFO[2022-08-02T11:40:54.097] starting host (192.168.122.101,ptk) successfully +INFO[2022-08-02T11:40:54.097] starting host 192.168.122.102 +INFO[2022-08-02T11:40:56.329] starting host (192.168.122.102,ptk) successfully +INFO[2022-08-02T11:40:56.613] waiting for check cluster state... +INFO[2022-08-02T11:41:01.861] ========================================= +INFO[2022-08-02T11:41:01.861] Successfully started. +INFO[2022-08-02T11:41:01.861] Operation succeeded: Start. +``` + +同时，PTK 默认会启动集群内所有实例，PTK 也支持指定单个实例启动： + +```shell +# ptk cluster -n c1 start -H 192.168.122.101 +INFO[2022-08-02T11:50:04.442] Operating: Starting. +INFO[2022-08-02T11:50:04.442] ========================================= +INFO[2022-08-02T11:50:06.692] starting host (192.168.122.101,ptk) successfully +``` + +更多启动参数请查看帮助文档： + +```shell +# ptk cluster start -h +启动数据库实例或集群 + +Usage: + ptk cluster start [flags] + +Flags: + -h, --help help for start + -H, --host string 操作的实例IP + -n, --name string 集群名称 + --security-mode string 是否使用安全模式启动数据库 + 可选项: on/off + --time-out duration 启动超时时间 (default 10m0s) +``` + +## 停止集群 + +> 下面的集群操作以集群 `c1` 为例 + +如果想要停止数据库集群，可以通过 `cluster stop` 指令，默认会停止集群内所有实例： + +```shell +# ptk cluster -n c1 stop +INFO[2022-08-02T11:49:40.685] Operating: Stopping. +INFO[2022-08-02T11:49:40.685] ========================================= +INFO[2022-08-02T11:49:40.891] stopping host 192.168.122.102 +INFO[2022-08-02T11:49:41.946] stopping host (192.168.122.102,ptk) successfully +INFO[2022-08-02T11:49:41.946] stopping host 192.168.122.101 +INFO[2022-08-02T11:49:43.004] stopping host (192.168.122.101,ptk) successfully +INFO[2022-08-02T11:49:43.004] ========================================= +INFO[2022-08-02T11:49:43.004] Successfully stoped. +INFO[2022-08-02T11:49:43.004] Operation succeeded: Stop. +``` + +如果想要停止集群内某个实例，可通过 `-H` 指定实例的IP + +```shell +# ptk cluster -n c1 stop -H 192.168.122.101 +INFO[2022-08-02T11:56:32.880] Operating: Stopping. +INFO[2022-08-02T11:56:32.881] ========================================= +INFO[2022-08-02T11:56:34.154] stopping host (192.168.122.101,ptk) successfully +``` + +停止集群的更多参数，请查看帮助文档： + +```shell +# ptk cluster stop -h +停止数据库实例或集群 + +Usage: + ptk cluster stop [flags] + +Flags: + -h, --help help for stop + -H, --host string 操作的实例IP + -n, --name string 集群名称 + --time-out duration 停止超时时间 (default 10m0s) +``` + +## 重启集群 + +> 下面的集群操作以集群 `c1` 为例 + +重启集群的操作，本质上是先停止数据库，再启动数据库的组合操作。 + +可通过 `cluster restart` 指令来实现： + +```shell +# ptk cluster -n c1 restart +INFO[2022-08-02T11:59:31.037] Operating: Stopping. +INFO[2022-08-02T11:59:31.037] ========================================= +INFO[2022-08-02T11:59:31.217] stopping host 192.168.122.102 +INFO[2022-08-02T11:59:32.269] stopping host (192.168.122.102,ptk) successfully +INFO[2022-08-02T11:59:32.269] stopping host 192.168.122.101 +INFO[2022-08-02T11:59:33.309] stopping host (192.168.122.101,ptk) successfully +INFO[2022-08-02T11:59:33.309] ========================================= +INFO[2022-08-02T11:59:33.309] Successfully stoped. +INFO[2022-08-02T11:59:33.309] Operation succeeded: Stop. + +INFO[2022-08-02T11:59:33.310] Operating: Starting. +INFO[2022-08-02T11:59:33.310] ========================================= +INFO[2022-08-02T11:59:33.376] starting host 192.168.122.101 +INFO[2022-08-02T11:59:35.583] starting host (192.168.122.101,ptk) successfully +INFO[2022-08-02T11:59:35.583] starting host 192.168.122.102 +INFO[2022-08-02T11:59:36.787] starting host (192.168.122.102,ptk) successfully +INFO[2022-08-02T11:59:36.995] waiting for check cluster state... +INFO[2022-08-02T11:59:42.247] ========================================= +INFO[2022-08-02T11:59:42.247] Successfully started. +INFO[2022-08-02T11:59:42.247] Operation succeeded: Start. +``` + +重启集群的更多参数，请查看帮助文档： + +```shell +# ptk cluster restart -h +重启数据库实例或集群 + +Usage: + ptk cluster restart [flags] + +Flags: + -h, --help help for restart + -H, --host string 操作的实例IP + -n, --name string 集群名称 + --security-mode string 是否使用安全模式启动数据库 + 可选项: on/off + --time-out duration 启动超时时间 (default 10m0s) +``` + + + + + +## 构建节点 + +> 下面的集群操作以集群 `c1` 为例 + +构建节点的操作，本质上是调用gs_ctl build进行相应的构建。 + +可通过 `cluster build` 指令来实现： + +```shell +# ptk cluster -n c1 build +INFO[2023-01-10T11:46:22.035] operation: build +INFO[2023-01-10T11:46:22.035] ======================================== +INFO[2023-01-10T11:46:22.035] build 172.16.0.190, role standby +INFO[2023-01-10T11:46:32.816] build 172.16.0.183, role cascade_standby +INFO[2023-01-10T11:46:44.099] ======================================== +INFO[2023-01-10T11:46:44.099] build successfully +``` + +构建节点的更多参数，请查看帮助文档： + +```shell +# ptk cluster build -h +重启数据库实例或集群 + +Usage: + ptk cluster build [flags] + +Flags: + -h, --help help for build + -H, --host stringArray 待构建的IP列表 +``` diff --git a/product/zh/docs-ptk/v0.6/usage/usage-scale.md b/product/zh/docs-ptk/v0.6/usage/usage-scale.md new file mode 100644 index 0000000000000000000000000000000000000000..cf0a017e53238eaebe908292f261c538c342bae2 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/usage/usage-scale.md @@ -0,0 +1,197 @@ +--- +title: Scale +summary: Scale +author: Yao Qian +date: 2022-07-30 +--- + +# 数据库扩缩容 + +## 什么是扩缩容？ + +扩缩容是指在某个已存在的数据库集群上，对集群进行增加数据库节点或减少数据库节点的操作，以满足不同的业务需求场景 + +术语: + +- **扩容**：指通过一系列操作，在原有集群上，增加数据库节点。 +- **缩容**：指通过一系列操作，在原有集群上，减少数据库节点。 + +## 前提 + +本文假设你已有一个 MogDB 数据库集群，可以是单机或多节点。且集群名为 `CLUSTER_NAME` + +扩容时，请确保数据库版本，配置和系统环境一致，避免出现不兼容问题 + +> 数据库集群安装请参考: [安装数据库](/install.md) + +## 扩容 + +### 查看帮助文档 + +``` +# ptk cluster scale-out -h +对一个MogDB集群进行扩容 + +Usage: + ptk cluster scale-out [flags] + +Examples: +ptk cluster -n scale-out -c scale-out.yaml + +Flags: + -y, --assumeyes 自动对所有提问回复Yes + -c, --config string 扩缩容配置文件路径 + --cpu string 指定CPU型号名 + 可通过 'ptk candidate cpu' 来查看支持的CPU型号名列表 + --default-guc 不自动优化 GUC 参数，使用数据库默认参数 + -h, --help help for scale-out + --skip-check-distro 跳过检查系统发行版 + --skip-check-os 跳过系统检查 + --skip-create-user 跳过创建用户 + --skip-rollback 安装失败时跳过回滚操作 +``` + +#### 扩容原理 + +ptk 在扩容时，会在当前集群内随机选择一个节点，将节点上的应用目录和工具目录等静态文件进行打包，复制到目标机器上后，解压到对应目录下。 +然后使用内核工具初始化一个新的数据目录出来，最后将集群的配置按照新集群的拓扑整体刷新。 + +注意，扩容时采用的是逐个节点扩容的模式，当扩容至某个节点失败时，立即停止继续扩容，按照已完成的集群进行刷新配置。 + +### 创建扩容的配置文件 + +ptk 的 template 子命令中包含 scale-out 的子命令，可以生成一个基础的扩容模板配置文件 + +``` +ptk template scale-out > scale-out.yaml +``` + +此时已创建一个扩容的配置文件 scale-out.yaml，请按需修改该配置文件。 + +下面对扩容模板内容进行一下介绍: + +```yaml +# 新增的数据库服务器列表，支持的字段和安装时相同 +db_servers: + - host: "replace host ip here" + # 角色仅支持 "standby" (默认) 或者 "cascade_standby" + role: standby + ssh_option: + port: 22 + user: root + password: "encrypted ssh password by ptk" + +# CM 组件服务器列表 +# 如果扩容前的集群安装了CM组件，则需要指定扩容后的CM服务器列表， +# 一般情况下 CM 服务器的列表和数据库的相同即可 +# 但如果在新的服务器上仅扩容数据库或者仅扩容CM组件，两个列表内的机器列表可以不一致 +cm_servers: + - host: "replace host ip here" +``` + +### 扩容支持情况表 + +| 原集群情况 | 扩容条件 | 支持情况 | 解决方案 | +| ---- | ---- | ---- | ---- | +| db1,db2 | db3 | 支持 || +| db1,db2 | cm1,cm2 | 不支持 | 卸载集群指定 --install-cm 参数重新装 | +| db1+cm1,db2+cm2,db3+cm3 | db4+cm4 | 支持 || +| db1+cm1,db2+cm2,db3+cm3 | db4 | 支持 || +| db1+cm1,db2+cm2,db3+cm3 | cm4 | 支持 || +| db1+cm1,db2+cm2,db3 | cm3 | 不支持 | 缩容 db3, 扩容 db3+cm3 | +| db1+cm1,db2+cm2,cm3 | db3 | 不支持 | 缩容 cm3, 扩容 db3+cm3 | + +### 扩容指令 + +```shell +ptk cluster -n CLUSTER_NAME scale-out -c scale-out.yaml +``` + +## 缩容 + +### 查看帮助 + +``` +# ptk cluster scale-in -h + +对一个MogDB集群进行缩容 + +Usage: + ptk cluster scale-in [flags] + +Examples: +ptk cluster -n scale-in -H -H + +Flags: + -y, --assumeyes 自动对所有提问回复Yes + --force 如果无法通过ssh连接目标主机，强制从集群升级节点的配置中删除目标实例 + -h, --help help for scale-in + -H, --host stringArray 要删除的目标IP + --skip-clear-db 不清除目标数据库的目录 + --skip-clear-user 不删除目标数据库的系统用户 +``` + +### 缩容指令 + +```shell +ptk cluster -n CLUSTER_NAME scale-in -H IP1 -H IP2 +``` + +会将IP为 `IP1` 和 `IP2` 的数据库节点从集群中移除。 + +**缩容的部分说明**： + +- 关于一主多备多级联的缩容 + +假设集群拓扑结构为 + +``` + standby1 —— cascade_standby1 + / +primary + \ + standby2 —— cascade_standby2 +``` + +缩容删除standby1时，最终拓扑结构变为 + +``` + standby1 cascade_standby1 + / +primary / + \ / + standby2 —— cascade_standby2 +``` + +此时standby1不在集群中，而是独立出来，与原集群没有任何关联。 + +也就是说，如果被删除的是备库，且该备备库下有级联节点，且除了被删的备库之外，还有其他备库。会为其下的级联备库随机选一个未被删除的备库连接。 + +- 关于一主一备一级联的缩容 + +假设集群拓扑结构为 + +``` +primary —— standby1 —— cascade_standby1 +``` + +缩容删除standby1时，最终拓扑结构变为 + +``` +primary standby1 cascade_standby1 +``` + +此时3个节点直接没有任何关联，均独立。 + +### 缩容支持情况表 + +> 注意：缩容仅支持按照 IP 的节点级别整体摘除 + +| 原集群情况 | 缩容条件 | 支持情况 | 解决方案 | +| ------------ | ------------ | ------------ | ------------ | +| db1,db2,db3 | db3 | 支持 || +| db1+cm1,db2+cm2,db3+cm3 | db3+cm3(同一个IP) | 支持 || +| db1+cm1,db2+cm2,db3+cm3 | db3 | 不支持 | 缩容 db3+cm3，扩 cm3 | +| db1+cm1,db2+cm2,db3+cm3 | cm3 | 不支持 | 缩容 db3+cm3，扩 db3 | +| db1+cm1,db2+cm2,db3 | db3 | 支持 | | +| db1+cm1,db2+cm2,cm3 | cm3 | 支持 | | diff --git a/product/zh/docs-ptk/v0.6/usage/usage-self-upgrade.md b/product/zh/docs-ptk/v0.6/usage/usage-self-upgrade.md new file mode 100644 index 0000000000000000000000000000000000000000..9f9139506b88251f898710f18f77b193c1223966 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/usage/usage-self-upgrade.md @@ -0,0 +1,66 @@ +--- +title: Self upgrade +summary: Self upgrade +author: Yao Qian +date: 2022-07-30 +--- + +# 升级PTK + +## 查看帮助文档 + +``` +$ ptk self -h + +操作 PTK 自身安装包 + +Usage: + ptk self [command] + +Available Commands: + upgrade 下载并自动安装PTK + +Flags: + -h, --help help for self +``` + +### 在线升级 + +PTK 支持在有网络情况下，通过 `self upgrade` 指令将PTK升级到已经发布的最新版本，升级后通过 `ptk -v` 查看版本。 + +下面是升级示例： + +```shell +$ ptk self upgrade + +INFO[2022-07-30T10:26:36.197] downloading ptk_darwin_arm64.tar.gz... +> ptk_darwin_arm64.tar.gz: 4.86 MiB / 4.86 MiB [-------------------------------------------------------------------] 100.00% 7.48 MiB p/s 900ms +INFO[2022-07-30T10:26:37.701] download successfully +INFO[2022-07-30T10:26:37.831] upgrade ptk successfully +``` + +### 离线包升级 + +首选，根据系统类型下载离线包（下面的链接始终返回最新版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二进制目录后解压覆盖之前的二进制文件即可： + +```shell +# which ptk +/root/.ptk/bin/ptk + +# cd /root/.ptk/bin/ +tar -xvf ptk_[os]_[arch]_.tar.gz +``` + +如果 ptk 版本大于 0.3, 可以通过 `-p` 参数本地升级： + +``` +# ptk self upgrade -p /path/to/ptk_[os]_[arch]_.tar.gz +``` diff --git a/product/zh/docs-ptk/v0.6/usage/usage-uninstall.md b/product/zh/docs-ptk/v0.6/usage/usage-uninstall.md new file mode 100644 index 0000000000000000000000000000000000000000..3e4906b6eccae7ea7a4091752d1f85a4a5c51352 --- /dev/null +++ b/product/zh/docs-ptk/v0.6/usage/usage-uninstall.md @@ -0,0 +1,23 @@ +--- +title: Uninstall +summary: Uninstall +author: Yao Qian +date: 2022-07-30 +--- + +# 数据库集群卸载 + +卸载时，PTK会检测集群是否处于运行状态，运行中是不允许被卸载的，需先将集群停止后再进行卸载操作。 + +> 注意： +> 卸载是一个很严肃的行为，请操作卸载数据库集群之前，反复确认当前集群是否确实可以卸载！ + +数据库集群的卸载仅需在 PTK 所在的服务器上执行 `ptk uninstall -n CLUSTER_NAME` 指令。 + +执行卸载时需指定要卸载的集群名称，可以通过 `ptk ls` 来查看集群名称。 + +在卸载中，PTK 会和用户确认卸载的内容，以确认要删除的集群拓扑信息，确认是否要连带删除系统用户，以及确认是否要连带删除数据库数据。 + +**请在回答每一个问题时，确认你的回答，避免由于误操作导致不可恢复的数据丢失！** + +> 在 PTK 执行数据库卸载操作时，如果用户指定了删除数据目录，PTK 仅会删除数据目录，不会删除数据目录所在的父目录，**需用户手动清理父目录**。 diff --git a/product/zh/docs-ptk/v0.6/yaml-grammar.md b/product/zh/docs-ptk/v0.6/yaml-grammar.md new file mode 100644 index 0000000000000000000000000000000000000000..489d1e7dfc440b8a54542c343751d716f1b9d38b --- /dev/null +++ b/product/zh/docs-ptk/v0.6/yaml-grammar.md @@ -0,0 +1,231 @@ +--- +title: 附录：YAML语法 +summary: 详细描述了YAML规范以及如何应用于PTK +author: Yao Qian +date: 2022-09-16 +--- + +# 附录：YAML语法 + +PTK 采用 YAML 格式的配置文件，主要是因为语法简洁直观，数据结构方面的表达能力强，并且便于搭配注释进行描述。 + +> 注意：YAML 特点是使用空格来表达层次结构，所以在编写配置时需要注意缩进层次 + +本文就主要介绍 YAML 的语法，来帮助用户可以更好的理解 PTK 的配置文件格式。 + +## 标量和集合 + +根据 [YAML 规范](https://yaml.org/spec/1.2/spec.html)，有两种集合类型和很多标量类型。 + +两种集合类型是 map (字典)和 sequence (列表)： + +```yaml +map: + one: 1 + two: 2 + three: 3 + +sequence: + - one + - two + - three +``` + +标量值是单个值，（与集合相反） + +## YAML中的标量类型 + +如果整型或浮点型数字没有引号，通常被视为数字类型： + +```yaml +count: 1 +size: 2.34 +``` + +但是如果被引号引起来，会被当做字符串： + +```yaml +count: "1" # <-- string, not int +size: '2.34' # <-- string, not float +``` + +布尔函数也是如此： + +```yaml +isGood: true # bool +answer: "true" # string +``` + +空字符串是 `null` （不是 `nil`）。 + +注意 `port: "80"`是合法的YAML，可以通过模板引擎和YAML解释器传值，但是如果PTK希望`port`是整型，就会失败。 + +在一些场景中，可以使用YAML节点标签强制推断特定类型： + +```yaml +coffee: "yes, please" +age: !!str 21 +port: !!int "80" +``` + +如上所示，`!!str`告诉解释器`age`是一个字符串，即使它看起来像是整型。即使`port`被引号括起来，也会被视为int。 + +## YAML中的字符串 + +YAML中的大多数数据都是字符串。YAML有多种表示字符串的方法。本节解释这些方法并演示如何使用其中一些方法。 + +有三种单行方式声明一个字符串： + +```yaml +way1: bare words +way2: "double-quoted strings" +way3: 'single-quoted strings' +``` + +单行样式必须在一行： + +- 裸字没有引号，也没有转义，因此，必须小心使用字符。 +- 双引号字符串可以使用`\`转义指定字符。比如，`"\"Hello\", she said"`。可以使用`\n`转义换行。 +- 单引号字符串是字面意义的字符串，不用`\`转义，只有单引号`''`需要转义，转成单个`'`。 + +除了单行字符串，可以声明多行字符串： + +```yaml +coffee: | + Latte + Cappuccino + Espresso +``` + +上述会被当作`coffee`的字符串值，等同于`Latte\nCappuccino\nEspresso\n`。 + +注意在第一行`|`后面必须正确缩进。可以这样破坏上述示例： + +```yaml +coffee: | + Latte + Cappuccino + Espresso + +``` + +由于`Latte`没有正确缩进，会遇到这样的错误： + +```shell +Error parsing file: error converting YAML to JSON: yaml: line 7: did not find expected key +``` + +模板中，有时候为了避免上述错误，在多行文本中添加一个假的“第一行”会更加安全： + +```yaml +coffee: | + # Commented first line + Latte + Cappuccino + Espresso + +``` + +注意无论第一行是什么，都会保存在字符串的输出中。比如你要这样把文件内容注入到配置映射中，注释应该是读取该条目需要的类型。 + +### 控制多行字符串中的空格 + +在上述示例中，使用了 `|` 来表示多行字符串。但是注意字符串后面有一个尾随的`\n`。如果需要YAML处理器去掉末尾的换行符，在`|` +后面添加`-`： + +```yaml +coffee: |- + Latte + Cappuccino + Espresso +``` + +现在 `coffee`的值变成了： `Latte\nCappuccino\nEspresso` (没有末尾的`\n`)。 + +其他时候，可能希望保留尾随空格。可以使用 `|+`符号： + +```yaml +coffee: |+ + Latte + Cappuccino + Espresso + + +another: value +``` + +现在`coffee`的值是 `Latte\nCappuccino\nEspresso\n\n\n`。 + +文本块中的缩进会被保留，也会保留换行符： + +```yaml +coffee: |- + Latte + 12 oz + 16 oz + Cappuccino + Espresso +``` + +上述示例中，`coffee`会变成 `Latte\n 12 oz\n 16 oz\nCappuccino\nEspresso`。 + +### 折叠多行字符串 + +有时您想在 YAML 中用多行表示一个字符串，但希望在解释时将其视为一个长行。这被称为"折叠"。要声明一个折叠块，使用 `>` 代替 `|`： + +```yaml +coffee: > + Latte + Cappuccino + Espresso + + +``` + +上面`coffee`的值是： `Latte Cappuccino Espresso\n`。 注意，除了最后一个换行符之外，所有的换行符都将转换成空格。 +可以组合空格控制符和折叠字符标记 `>-` 来替换或取消所有的新行。 + +注意在折叠语法中，缩进文本将导致保留行。 + +```yaml +coffee: >- + Latte + 12 oz + 16 oz + Cappuccino + Espresso +``` + +上述结果为：`Latte\n 12 oz\n 16 oz\nCappuccino Espresso`。注意空格和换行都保存下来了。 + +## YAML是JSON的超集 + +由于YAML是一个JSON的超集，任何合法的JSON文档 _都应该_ 是合法的YAML。 + +```json +{ + "coffee": "yes, please", + "coffees": [ + "Latte", "Cappuccino", "Espresso" + ] +} +``` + +上述json的另一种表述方式是： + +```yaml +coffee: yes, please +coffees: +- Latte +- Cappuccino +- Espresso +``` + +而且两种可以混合（要小心）： + +```yaml +coffee: "yes, please" +coffees: [ "Latte", "Cappuccino", "Espresso"] +``` + +所有这三个都应该解析为相同的内部表示形式。