diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/Vector/cluster_centers.md b/docs/MatrixOne/Reference/Functions-and-Operators/Vector/cluster_centers.md index 7e7cb1afc9..1b45adff0b 100644 --- a/docs/MatrixOne/Reference/Functions-and-Operators/Vector/cluster_centers.md +++ b/docs/MatrixOne/Reference/Functions-and-Operators/Vector/cluster_centers.md @@ -17,7 +17,7 @@ SELECT cluster_centers(col kmeans 'k, op_type, init_type, normalize') FROM tbl; | col | 必需的。要确定聚类中心的向量列。| | k | 必需的。要将数据集分成的簇的数量，大于 0，小于等于总行数。| | op_type| 必需的。在聚类计算过程中使用的距离函数。目前支持 vector_l2_ops。| -| init_type | 必需的。要使用的初始化聚类中心算法。目前我们支持 random 和 kmeanspluspus(K-means++)。| +| init_type | 必需的。要使用的初始化聚类中心算法。目前我们支持 random 和 kmeansplusplus(K-means++)。| | normalize | 必需的。布尔值，要使用的聚类算法，true 代表 Spherical Kmeans，false 代表 Regular Kmeans。| ## 示例 diff --git a/docs/MatrixOne/Reference/mo-tools/mo_ctl.md b/docs/MatrixOne/Reference/mo-tools/mo_ctl.md index 2bee10373b..4b37ac46d0 100644 --- a/docs/MatrixOne/Reference/mo-tools/mo_ctl.md +++ b/docs/MatrixOne/Reference/mo-tools/mo_ctl.md @@ -1,366 +1,308 @@ -# mo_ctl 工具指南 +# mo_ctl 分布式版工具指南 -`mo_ctl` 是一款帮助你对单机版 MatrixOne 进行部署安装、启停控制以及数据库连接等操作的命令行工具。 +`mo_ctl` 分布式版是一款面向企业用户，协助用户部署 MatrixOne 分布式集群、安装相关组件并最终向用户提供 MatrixOne 服务的命令行工具 -## 功能概览 - -`mo_ctl` 目前已适配过的操作系统如下表所示： - -| 操作系统 | 版本 | -| -------- | -------------------- | -| Debian | 11 及以上 | -| Ubuntu | 20.04 及以上 | -| macOS | Monterey 12.3 及以上 | - -`mo_ctl` 目前的功能列表如下表所示。 - -| 命令 | 功能 | -| -------------------- | ------------------------------------------------------------------------------------------------------ | -| `mo_ctl help` | 查看`mo_ctl`工具本身的语句和功能列表 | -| `mo_ctl precheck` | 检查 MatrixOne 源码安装所需要的依赖项，分别为 golang, gcc, git,MySQL Client | -| `mo_ctl deploy` | 下载并安装及编译 MatrixOne 相应版本，默认为安装最新稳定版本 | -| `mo_ctl start` | 启动 MatrixOne 服务 | -| `mo_ctl status` | 检查 MatrixOne 服务是否正在运行中 | -| `mo_ctl stop` | 停止所有 MatrixOne 服务进程 | -| `mo_ctl restart` | 重启 MatrixOne 服务 | -| `mo_ctl connect` | 调用 MySQL Client 连接 MatrixOne 服务 | -| `mo_ctl upgrade` | 将 MatrixOne 从当前版本升级/降级到某个发布版本或者 commit id 版本 | -| `mo_ctl set_conf` | 设置各类使用参数 | -| `mo_ctl get_conf` | 查看当前使用参数 | -| `mo_ctl uninstall` | 从 MO_PATH 路径下卸载 MatrixOne | -| `mo_ctl watchdog` | 设置一个定时任务保证 MatrixOne 服务可用性，每分钟检查 MatrixOne 的状态，如果发现服务中止则自动拉起服务 | -| `mo_ctl sql` | 直接通过命令执行 SQL 或者 SQL 构成的文本文件 | -| `mo_ctl ddl_convert` | 将 MySQL 的 DDL 语句转换成 MatrixOne 语句的工具 | -| `mo_ctl get_cid` | 查看当前使用 MatrixOne 下载仓库的源码版本 | -| `mo_ctl get_branch` | 查看当前使用 MatrixOne 下载仓库的分支版本 | -| `mo_ctl pprof` | 用于收集 MatrixOne 的性能分析数据 | - -## 安装 mo_ctl - -根据您是否有互联网访问权限，可以选择在线或离线安装 `mo_ctl` 工具，你需要注意始终以 root 或具有 sudo 权限执行命令（并在每个命令前添加 sudo）。同时，`install.sh` 将使用 `unzip` 命令来解压 `mo_ctl` 软件包，请确保已安装 `unzip` 命令。 - -### 在线安装 - -``` -wget https://raw.githubusercontent.com/matrixorigin/mo_ctl_standalone/main/install.sh && sudo bash +x ./install.sh - -# 备用地址 -wget https://ghproxy.com/https://github.com/matrixorigin/mo_ctl_standalone/blob/main/install.sh && sudo bash +x install.sh -``` - -对于在 macOS 环境中运行此命令的用户，如果您是非 root 用户，请以以下语句运行 `install.sh`: - -``` -sudo -u $(whoami) bash +x ./install.sh -``` - -### 离线安装 - -``` -# 1. 先将安装脚本下载到本地计算机，再上传到安装机器上 -wget https://raw.githubusercontent.com/matrixorigin/mo_ctl_standalone/main/install.sh -wget https://github.com/matrixorigin/mo_ctl_standalone/archive/refs/heads/main.zip -O mo_ctl.zip +!!! note + mo_ctl 分布式版是一款专为企业级用户设计的高效数据库集群管理工具。如需获取该工具的下载路径，请与您的 MatrixOne 客户经理取得联系。 -# 如 github 原地址下载过慢，您可尝试从以下镜像地址下载： -wget https://githubfast.com/matrixorigin/mo_ctl_standalone/blob/main/install.sh -wget https://githubfast.com/matrixorigin/mo_ctl_standalone/archive/refs/heads/main.zip -O mo_ctl.zip +## 功能概览 -# 2. 从离线包安装 -bash +x ./install.sh mo_ctl.zip -``` +`mo_ctl` 目前已经适配过操作系统如下表所示： + +| 操作系统 | 版本 | +| ------------- | ----------| +| Debian | 11 及以上 | +| Ubuntu | 20.04 及以上 | +| UOS | 20.0.0 | +| Open EulerOS | 20.3.0 | + +`mo_ctl` 目前的功能列表如下表所示： + +| 命令 | 功能 | +| --------------- | ------------------------------------------------------ | +| `mo_ctl help` | 查看`mo_ctl`工具本身的语句和功能列表。 | +| `mo_ctl precheck` | 检查安装集群所需要的依赖项，例如：CPU，内存等。 | +| `mo_ctl install` | 创建集群，安装相应插件，并按照配置文件初始化 matrixone 集群。 | +| `mo_ctl registry` | 操作集群中创建的高可用镜像仓库，例如：增删改查镜像。 | +| `mo_ctl node` | 对集群中的节点进行管理，增加节点，删除节点等。 | +| `mo_ctl matrixone` | 对集群中 matrixone 集群进行管理，可创建，启动，停止，删除等操作。 | +| `mo_ctl s3` | 对集群中分布式 minio 进行管理，查看状态，扩展容量等操作。 | +| `mo_ctl backup` | 对集群中 matrixone cluster 进行备份，恢复等操作。 | +| `mo_ctl destroy` | 销毁 matrixone 服务并抹除集群。 | ## 快速上手 -可以通过以下步骤快速安装部署单机版 MatrixOne，详细指南可以查看[单机部署 MatrixOne](../Get-Started/install-standalone-matrixone.md). - 1. 使用命令 `mo_ctl help` 查看工具指南。 2. 使用命令 `mo_ctl precheck` 查看前置依赖条件是否满足。 -3. 使用命令 `mo_ctl get_conf` 设置相关参数，可能用到的参数配置如下所示： - ``` - mo_ctl set_conf MO_PATH="/data/mo/matrixone" #设置自定义的 MatrixOne 下载路径 - mo_ctl set_conf MO_GIT_URL="https://githubfast.com/matrixorigin/matrixone.git" #针对 github 原地址下载过慢问题，设置镜像下载地址 + mo_ctl precheck --config xxx.yaml ``` -4. 使用命令 `mo_ctl deploy` 安装部署 MatrixOne 最新稳定版本。 - -5. 使用命令 `mo_ctl start` 启动 MatrixOne 服务。 - -6. 使用命令 `mo_ctl connect` 连接 MatrixOne 服务。 +3. 使用命令 `mo_ctl install` 部署 MatrixOne 集群： -## 参考命令指南 + ``` + mo_ctl install --config xxx.yaml + ``` -### help - 打印参考指南 +4. 使用命令 `mo_ctl matrixone list` 检查 MatrixOne 的状态。 -``` -mo_ctl help -Usage : mo_ctl [option_1] [option_2] - - [option_1] : available: connect | ddl_connect | deploy | get_branch | get_cid | get_conf | help | pprof | precheck | query | restart | set_conf | sql | start | status | stop | uninstall | upgrade | watchdog - 1) connect : connect to mo via mysql client using connection info configured - 2) ddl_convert : convert ddl file to mo format from other types of database - 3) deploy : deploy mo onto the path configured - 4) get_branch : upgrade or downgrade mo from current version to a target commit id or stable version - 5) get_cid : print mo git commit id from the path configured - 6) get_conf : get configurations - 7) help : print help information - 8) pprof : collect pprof information - 9) precheck : check pre-requisites for mo_ctl - 10) restart : a combination operation of stop and start - 11) set_conf : set configurations - 12) sql : execute sql from string, or a file or a path containg multiple files - 13) start : start mo-service from the path configured - 14) status : check if there's any mo process running on this machine - 15) stop : stop all mo-service processes found on this machine - 16) uninstall : uninstall mo from path MO_PATH=/data/mo/20230712_1228//matrixone - 17) upgrade : upgrade or downgrade mo from current version to a target commit id or stable version - 18) watchdog : setup a watchdog crontab task for mo-service to keep it alive - e.g. : mo_ctl status - - [option_2] : Use " mo_ctl [option_1] help " to get more info - e.g. : mo_ctl deploy help -``` + ``` + mo_ctl matrixone list --type cluster + ``` -使用 `mo_ctl [option_1] help` 来获取下一级 `mo_ctl [option_1]` 功能的使用指南。 +## 参考命令指南 -### precheck - 检查前置依赖条件 +### help -源码安装 MatrixOne 前使用 `mo_ctl precheck` 检查前置依赖条件，目前前置依赖于 `go`/`gcc`/`git`/`mysql(client)`。 +使用 `mo_ctl help` 打印参考指南。 ``` -mo_ctl precheck help -Usage : mo_ctl precheck # check pre-requisites for mo_ctl - Check list : go gcc git mysql -``` - -### deploy - 安装 MatrixOne +./mo_ctl help +Install, destroy, and operation matrixone cluster -使用 `mo_ctl deploy [mo_version] [force]` 安装部署稳定版本 MatrixOne, 或某个指定版本，通过 `force` 选项可以将同一目录下已经存在的 MatrixOne 版本删除，强制重新安装新版本。 +Usage: + mo_ctl [command] -``` -mo_ctl deploy help -Usage : mo_ctl deploy [mo_version] [force] # deploy mo onto the path configured - [mo_version]: optional, specify an mo version to deploy - [force] : optional, if specified will delete all content under MO_PATH and deploy from beginning - e.g. : mo_ctl deploy # default, same as mo_ctl deploy 1.2.1 - : mo_ctl deploy main # deploy development latest version - : mo_ctl deploy d29764a # deploy development version d29764a - : mo_ctl deploy 1.2.1 # deploy stable verson 1.2.1 - : mo_ctl deploy force # delete all under MO_PATH and deploy verson 1.2.1 - : mo_ctl deploy 1.2.1 force # delete all under MO_PATH and deploy stable verson 1.2.1 from beginning -``` +Available Commands: + backup backup matrixone cluster + completion Generate the autocompletion script for the specified shell + destroy destroy k8s cluster and apps on it + help Help about any command + install Install k8s, matrixone, minio, and other apps + matrixone matrixone operation cmd + precheck precheck cluster machine environment before install + registry registry operations -### start - 启动 MatrixOne 服务 +Flags: + --config string Specify the mo_ctl config file + -d, --debug turn on debug mode + -h, --help help for mo_ctl + --kubeconfig string Path to the kubeconfig file to use (default "/root/.kube/config") + --logfile string Specify the log file -使用 `mo_ctl start` 启动 MatrixOne 服务，启动文件路径位于 `MO_PATH` 下。 - -``` -mo_ctl start help -Usage : mo_ctl start # start mo-service from the path configured +Use "mo_ctl [command] --help" for more information about a command. ``` -### stop - 停止 MatrixOne 服务 +### precheck -使用 `mo_ctl stop [force]` 停止本机器上所有 MatrixOne 服务，如果有多个 MatrixOne 服务在运行，也会全部停止。 +使用 `mo_ctl precheck` 预检查硬件和软件的环境是否适合安装 MatrixOne。 ``` - mo_ctl stop help -Usage : mo_ctl stop [force] # stop all mo-service processes found on this machine - [force] : optional, if specified, will try to kill mo-services with -9 option, so be very carefully - e.g. : mo_ctl stop # default, stop all mo-service processes found on this machine - : mo_ctl stop force # stop all mo-services with kill -9 command -``` - -### restart - 重启 MatrixOne 服务 +./mo_ctl precheck --help +precheck cluster machine environment before install -使用 `mo_ctl restart [force]` 停止所有本机器上 MatrixOne 服务，并重启位于 `MO_PATH` 路径下的 MatrixOne 服务。 +Usage: + mo_ctl precheck [flags] -``` -mo_ctl restart help -Usage : mo_ctl restart [force] # a combination operation of stop and start - [force] : optional, if specified, will try to kill mo-services with -9 option, so be very carefully - e.g. : mo_ctl restart # default, stop all mo-service processes found on this machine and start mo-serivce under path of conf MO_PATH - : mo_ctl restart force # stop all mo-services with kill -9 command and start mo-serivce under path of conf MO_PATH +Flags: + -h, --help help for precheck ``` -### connect - 通过 mysql-client 连接 MatrixOne 服务 +### install -使用 `mo_ctl connect` 连接到 MatrixOne 服务，连接参数均由 `mo_ctl` 工具中设置。 +使用 `mo_ctl install` 在计算机（机器或虚拟机）上安装 k8s、matrixone、minio 和其他应用程序，执行此命令前需要联系您的客户经理获取镜像包的下载路径。 -``` -mo_ctl connect help -Usage : mo_ctl connect # connect to mo via mysql client using connection info configured -``` - -### status - 检查 MatrixOne 的状态 - -使用 `mo_ctl status` 来检查 MatrixOne 的运行状态，是否在运行中。 +- clusterimage.tar：面向需要使用 `mo_ctl` 创建集群并安装相关组件，其中包含基础 k8s 组件以及 matrixone 相应的 app 组件 +- moappdistro.tar：面向已有 k8s 集群，需要使用 `mo_ctl` 进行组件管理，其中包含 matrixone 以及相应的组件 ``` -mo_ctl status help -Usage : mo_ctl status # check if there's any mo process running on this machine -``` - -### get_cid - 打印 MatrixOne 代码提交 id +./mo_ctl install --help +Install k8s, matrixone, minio, and other apps -使用 `mo_ctl get_cid` 打印当前 `MO_PATH` 路径下的 MatrixOne 代码库提交 id。 +Usage: + mo_ctl install [flags] -``` -mo_ctl get_cid help -Usage : mo_ctl get_cid # print mo commit id from the path configured +Flags: + --app only install k8s app + --dry-run dry run + -h, --help help for install ``` -### get_branch - 打印 MatrixOne 代码提交 id +### destory -使用 `mo_ctl get_branch` 打印当前 `MO_PATH` 路径下的 MatrixOne 代码库分支。 +使用 `mo_ctl destroy` 销毁 k8s 集群及其上的应用程序。 ``` -mo_ctl get_branch help -Usage : mo_ctl get_branch # print which git branch mo is currently on -``` +./mo_ctl destroy --help +destroy k8s cluster and apps on it -### pprof - 收集性能信息 +Usage: + mo_ctl destroy [flags] -使用 `mo_ctl pprof [item] [duration]` 收集 MatrixOne 的相关性能信息，主要为开发人员进行调试使用。 - -``` -mo_ctl pprof help -Usage : mo_ctl pprof [item] [duration] # collect pprof information - [item] : optional, specify what pprof to collect, available: profile | heap | allocs - 1) profile : default, collect profile pprof for 30 seconds - 2) heap : collect heap pprof at current moment - 3) allocs : collect allocs pprof at current moment - [duration] : optional, only valid when [item]=profile, specifiy duration to collect profile - e.g. : mo_ctl pprof - : mo_ctl pprof profile # collect duration will use conf value PPROF_PROFILE_DURATION from conf file or 30 if it's not set - : mo_ctl pprof profile 30 - : mo_ctl pprof heap +Flags: + --configmap get clusterfile from k8s configmap + --dry-run dry run + --force force destroy, no notice + -h, --help help for destroy ``` -### set_conf - 配置参数 +### register -使用 `mo_ctl set_conf [conf_list]` 配置 1 个或多个使用参数。 +使用 `mo_ctl register` 操作集群中创建的高可用镜像仓库，例如：增删改查镜像。 ``` -mo_ctl set_conf help -Usage : mo_ctl setconf [conf_list] # set configurations - [conf_list] : configuration list in key=value format, seperated by comma - e.g. : mo_ctl setconf MO_PATH=/data/mo/matrixone,MO_PW=M@trix0riginR0cks,MO_PORT=6101 # set multiple configurations - : mo_ctl setconf MO_PATH=/data/mo/matrixone # set single configuration -``` - -!!! note - 当 set_conf 的设置的路径中包含变量如 `${MO_PATH}` 时，需要在 `$` 前加上 `\`，例如： - ```bash - mo_ctl set_conf MO_CONF_FILE="\${MO_PATH}/matrixone/etc/launch/launch.toml" + mo_ctl registry --help +Usage: + mo_ctl registry [flags] + mo_ctl registry [command] - ``` +Aliases: + registry, reg -### get_conf - 获取参数列表 - -使用 `mo_ctl get_conf [conf_list]` 获取一个或多个当前配置项。 - -``` -mo_ctl get_conf help -Usage : mo_ctl getconf [conf_list] # get configurations - [conf_list] : optional, configuration list in key, seperated by comma. - : use 'all' or leave it as blank to print all configurations - e.g. : mo_ctl getconf MO_PATH,MO_PW,MO_PORT # get multiple configurations - : mo_ctl getconf MO_PATH # get single configuration - : mo_ctl getconf all # get all configurations - : mo_ctl getconf # get all configurations -``` - -#### mo_ctl get_conf - 详细参数列表 - -使用 `mo_ctl get_conf` 将打印当前工具使用的所有参数列表，它们的释义与取值范围如下表所示。 - -| 参数名称 | 功能 | 取值规范 | -| ---------------------- | ------------------------------------------------------ | ----------------------------------------------------- | -| MO_PATH | MatrixOne 的代码库及可执行文件存放位置 | 文件夹路径 | -| MO_LOG_PATH | MatrixOne 的日志存放位置 | 文件夹路径，默认为${MO_PATH}/matrixone/logs | -| MO_HOST | 连接 MatrixOne 服务的 IP 地址 | IP 地址，默认为 127.0.0.1 | -| MO_PORT | 连接 MatrixOne 服务的端口号 | 端口号，默认为 6001 | -| MO_USER | 连接 MatrixOne 服务使用的用户名 | 用户名，默认为 root | -| MO_PW | 连接 MatrixOne 服务使用的密码 | 密码，默认为 111 | -| CHECK_LIST | precheck 需要的检查依赖项 | 默认为 ("go" "gcc" "git" "mysql") | -| GCC_VERSION | precheck 检查的 gcc 版本 | 默认为 8.5.0 | -| GO_VERSION | precheck 检查的 go 版本 | 默认为 1.22.3 | -| MO_GIT_URL | MatrixOne 的源码拉取地址 | 默认为 | -| MO_DEFAULT_VERSION | 默认拉取的 MatrixOne 的版本 | 默认为 1.2.1 | -| GOPROXY | GOPROXY 的地址，一般为国内加速拉取 golang 依赖包而使用 | 默认为,direct | -| STOP_INTERVAL | 停止间隔，停止服务后检测服务状态等待时间 | 默认为 5 秒 | -| START_INTERVAL | 启动间隔，启动服务后检测服务状态等待时间 | 默认为 2 秒 | -| MO_DEBUG_PORT | MatrixOne 的 debug 端口，一般为开发人员使用 | 默认为 9876 | -| MO_CONF_FILE | MatrixOne 的启动配置文件 | 默认为${MO_PATH}/matrixone/etc/launch/launch.toml | -| RESTART_INTERVAL | 重启间隔，重启服务后检测服务状态等待时间 | 默认为 2 秒 | -| PPROF_OUT_PATH | golang 的性能收集数据输出路径 | 默认为/tmp/pprof-test/ | -| PPROF_PROFILE_DURATION | golang 的性能收集时间 | 默认为 30 秒 | - -### ddl_convert - DDL 格式转换 - -使用 `mo_ctl ddl_convert [options] [src_file] [tgt_file]` 将一个 DDL 文件从其他数据库语法格式转换成 MatrixOne 的 DDL 格式，目前仅有 `mysql_to_mo` 模式支持。 - -``` -mo_ctl ddl_convert help -Usage : mo_ctl ddl_convert [options] [src_file] [tgt_file] # convert a ddl file to mo format from other types of database - [options] : available: mysql_to_mo - [src_file] : source file to be converted, will use env DDL_SRC_FILE from conf file by default - [tgt_file] : target file of converted output, will use env DDL_TGT_FILE from conf file by default - e.g. : mo_ctl ddl_convert mysql_to_mo /tmp/mysql.sql /tmp/mo.sql -``` - -### sql - 执行 SQL - -使用 `mo_ctl sql [sql]` 来执行 SQL 文本或者 SQL 文件。 +Available Commands: + delete delete (image) + list list (image | chart) + push push (image | chart) -``` -mo_ctl sql help -Usage : mo_ctl sql [sql] # execute sql from string, or a file or a path containg multiple files - [sql] : a string quote by "", or a file, or a path - e.g. : mo_ctl sql "use test;select 1;" # execute sql "use test;select 1" - : mo_ctl sql /data/q1.sql # execute sql in file /data/q1.sql - : mo_ctl sql /data/ # execute all sql files with .sql postfix in /data/ +Flags: + -h, --help help for registry + --type string registry type (image | chart) (default "image") ``` -### uninstall - 卸载 MatrixOne +### backup -使用 `mo_ctl uninstall` 来从 MO_PATH 上卸载 MatrixOne。 + 使用 `mo_ctl backup` 对集群中 matrixone cluster 进行备份，恢复等操作 ``` -mo_ctl uninstall help -Usage : mo_ctl uninstall # uninstall mo from path MO_PATH=/data/mo//matrixone - # note: you will need to input 'Yes/No' to confirm before uninstalling -``` + ./mo_ctl backup --help +backup matrixone cluster -### upgrade - 升级/降级 MatrixOne 版本 +Usage: + mo_ctl backup [flags] + mo_ctl backup [command] -MatrixOne 0.8 及更高版本可使用 `mo_ctl upgrade version` 或者 `mo_ctl upgrade commitid` 来将 MatrixOne 从当前版本升级或降级到某个稳定版本或者某个 commit id 版本。 +Available Commands: + list list matrixone cluster backup revison + restore restore backup matrixone cluster + start start backup matrixone cluster +Flags: + -h, --help help for backup ``` -mo_ctl upgrade help -Usage : mo_ctl upgrade [version_commitid] # upgrade or downgrade mo from current version to a target commit id or stable version - [commitid] : a commit id such as '38888f7', or a stable version such as '1.2.1' - : use 'latest' to upgrade to latest commit on main branch if you don't know the id - e.g. : mo_ctl upgrade 38888f7 # upgrade/downgrade to commit id 38888f7 on main branch - : mo_ctl upgrade latest # upgrade/downgrade to latest commit on main branch - : mo_ctl upgrade 1.2.1 # upgrade/downgrade to stable version 1.2.1 -``` - -### watchdog - 保活 MatrixOne -使用 `mo_ctl watchdog [options]` 设置一个定时任务保证 MatrixOne 服务可用性，每分钟检查 MatrixOne 的状态，如果发现服务中止则自动拉起服务。 +- **start** + + 1. 首先需要准备描述 backup job 的 yaml 文件，此处预设生成的 yaml 名称为 backup.yaml。 + ``` + apiVersion: core.matrixorigin.io/v1alpha1 + kind: BackupJob + metadata: + # 此处指定 job 的名称 + name: backupjob + # 此处指定 job 所属的 namespace + # 注意：此处要与需要备份的 mo 集群处于同一个 namespace + namespace: mocluster1 + spec: + source: + # mo 集群的名称，可通过 mo_ctl matrixone list 命令获取 + clusterRef: mocluster-mocluster1 + # 配置备份存储位置，可选择对象存储或者本地路径存储。具体的可参考 https://github.com/matrixorigin/matrixone-operator/blob/main/docs/reference/api-reference.md#backupjob + target: + s3: + type: minio + endpoint: http://minio.s3-minio-tenant-test1 + path: mo-test/backup-01 + secretRef: + name: minio + ``` + + 2. 通过以下命令创建一个 backup job 来进行备份操作 + + ``` + # 退出码为 0 则证明备份 job 创建成功 + sudo ./mo_ctl backup start --values backup.yaml + ``` + + 3. 创建成功后可通过以下命令等待备份完成 + + ``` + # 此处的 backupjob 即为在步骤一中定义的 name + sudo kubectl wait --for=condition=ended backupjob --all -A --timeout=5m + ``` + +- **restore** + + 1. 获取 backup job 的名称 (ID)，可通过以下命令获取 + + ``` + sudo ./mo_ctl backup list + ``` + + 2. 首先需要准备描述 restore job 的 yaml 文件，此处预设生成的 yaml 名称为 restore.yaml。 + + ``` + # 除了 restoreFrom，其他字段可参考 https://github.com/matrixorigin/matrixone-operator/blob/main/docs/reference/api-reference.md#matrixonecluster + apiVersion: core.matrixorigin.io/v1alpha1 + kind: MatrixOneCluster + metadata: + name: morestore + namespace: mocluster1 + spec: + # 此处需要填写步骤一中获取的 backup job 的 name + restoreFrom: #BackupName + # 此处需要填写实际的镜像仓库信息 + imageRepository: sea.hub:5000/matrixorigin/matrixone + version: 1.1.0 + logService: + replicas: 1 + sharedStorage: + # 此处需要填写实际的对象存储信息 + s3: + type: minio + path: mo-test/backup-01 + endpoint: http://minio.s3-minio-tenant-test1 + secretRef: + name: minio + volume: + size: 10Gi + tn: + replicas: 1 + cacheVolume: + size: 10Gi + cnGroups: + - name: tp + replicas: 1 + cacheVolume: + size: 10Gi + ``` + + 3. 执行备份恢复命令 + + ``` + sudo ./mo_ctl backup restore --values restore.yaml + ``` + +### matrixone + +使用 `mo_ctl matrixone` 对集群中 matrixone 集群进行管理，可创建，启动，停止，删除等操作 + +``` +./mo_ctl matrixone --help +Used for matrixone operation cmd + +Usage: + mo_ctl matrixone [flags] + mo_ctl matrixone [command] + +Aliases: + matrixone, mo + +Available Commands: + history history all matrixone (cluster | operator) + list list matrixone (cluster | operator) + remove remove matrixone (cluster) + rollback rollback depoly of matrixone (cluster | operator) + setup setup matrixone (cluster) + start start matrixone (cluster) + stop stop matrixone (cluster) + upgrade upgrade matrixone (cluster | operator) + +Flags: + --dry-run dry run + -h, --help help for matrixone + --name string Specify matrixorigin cluster name + --type string Specify a type (cluster | operator) (default "cluster") ``` -mo_ctl watchdog help -Usage : mo_ctl watchdog [options] # setup a watchdog crontab task for mo-service to keep it alive - [options] : available: enable | disable | status - e.g. : mo_ctl watchdog enable # enable watchdog service for mo, by default it will check if mo-servie is alive and pull it up if it's dead every one minute - : mo_ctl watchdog disable # disable watchdog - : mo_ctl watchdog status # check if watchdog is enabled or disabled - : mo_ctl watchdog # same as mo_ctl watchdog status -``` - - diff --git a/docs/MatrixOne/Reference/mo-tools/mo_ctl_standalone.md b/docs/MatrixOne/Reference/mo-tools/mo_ctl_standalone.md new file mode 100644 index 0000000000..d67ea5b576 --- /dev/null +++ b/docs/MatrixOne/Reference/mo-tools/mo_ctl_standalone.md @@ -0,0 +1,372 @@ +# mo_ctl 单机版工具指南 + +`mo_ctl` 单机版是一款帮助你对单机版 MatrixOne 进行部署安装、启停控制以及数据库连接等操作的命令行工具。 + +## 功能概览 + +`mo_ctl` 目前已适配过的操作系统如下表所示： + +| 操作系统 | 版本 | +| -------- | -------------------- | +| Debian | 11 及以上 | +| Ubuntu | 20.04 及以上 | +| macOS | Monterey 12.3 及以上 | +|OpenCloudOS| v8.0 / v9.0 | +|Open EulerOS | 20.03 | +|TencentOS Server | v2.4 / v3.1 | +|统信 | V20 | +|银河麒麟 | V10 | +|麒麟信安 | v3.0 | + +`mo_ctl` 目前的功能列表如下表所示。 + +| 命令 | 功能 | +| -------------------- | ------------------------------------------------------------------------------------------------------ | +| `mo_ctl help` | 查看`mo_ctl`工具本身的语句和功能列表 | +| `mo_ctl precheck` | 检查 MatrixOne 源码安装所需要的依赖项，分别为 golang, gcc, git,MySQL Client | +| `mo_ctl deploy` | 下载并安装及编译 MatrixOne 相应版本，默认为安装最新稳定版本 | +| `mo_ctl start` | 启动 MatrixOne 服务 | +| `mo_ctl status` | 检查 MatrixOne 服务是否正在运行中 | +| `mo_ctl stop` | 停止所有 MatrixOne 服务进程 | +| `mo_ctl restart` | 重启 MatrixOne 服务 | +| `mo_ctl connect` | 调用 MySQL Client 连接 MatrixOne 服务 | +| `mo_ctl upgrade` | 将 MatrixOne 从当前版本升级/降级到某个发布版本或者 commit id 版本 | +| `mo_ctl set_conf` | 设置各类使用参数 | +| `mo_ctl get_conf` | 查看当前使用参数 | +| `mo_ctl uninstall` | 从 MO_PATH 路径下卸载 MatrixOne | +| `mo_ctl watchdog` | 设置一个定时任务保证 MatrixOne 服务可用性，每分钟检查 MatrixOne 的状态，如果发现服务中止则自动拉起服务 | +| `mo_ctl sql` | 直接通过命令执行 SQL 或者 SQL 构成的文本文件 | +| `mo_ctl ddl_convert` | 将 MySQL 的 DDL 语句转换成 MatrixOne 语句的工具 | +| `mo_ctl get_cid` | 查看当前使用 MatrixOne 下载仓库的源码版本 | +| `mo_ctl get_branch` | 查看当前使用 MatrixOne 下载仓库的分支版本 | +| `mo_ctl pprof` | 用于收集 MatrixOne 的性能分析数据 | + +## 安装 mo_ctl + +根据您是否有互联网访问权限，可以选择在线或离线安装 `mo_ctl` 工具，你需要注意始终以 root 或具有 sudo 权限执行命令（并在每个命令前添加 sudo）。同时，`install.sh` 将使用 `unzip` 命令来解压 `mo_ctl` 软件包，请确保已安装 `unzip` 命令。 + +### 在线安装 + +``` +wget https://raw.githubusercontent.com/matrixorigin/mo_ctl_standalone/main/install.sh && sudo bash +x ./install.sh + +# 备用地址 +wget https://ghproxy.com/https://github.com/matrixorigin/mo_ctl_standalone/blob/main/install.sh && sudo bash +x install.sh +``` + +对于在 macOS 环境中运行此命令的用户，如果您是非 root 用户，请以以下语句运行 `install.sh`: + +``` +sudo -u $(whoami) bash +x ./install.sh +``` + +### 离线安装 + +``` +# 1. 先将安装脚本下载到本地计算机，再上传到安装机器上 +wget https://raw.githubusercontent.com/matrixorigin/mo_ctl_standalone/main/install.sh +wget https://github.com/matrixorigin/mo_ctl_standalone/archive/refs/heads/main.zip -O mo_ctl.zip + +# 如 github 原地址下载过慢，您可尝试从以下镜像地址下载： +wget https://githubfast.com/matrixorigin/mo_ctl_standalone/blob/main/install.sh +wget https://githubfast.com/matrixorigin/mo_ctl_standalone/archive/refs/heads/main.zip -O mo_ctl.zip + +# 2. 从离线包安装 +bash +x ./install.sh mo_ctl.zip +``` + +## 快速上手 + +可以通过以下步骤快速安装部署单机版 MatrixOne，详细指南可以查看[单机部署 MatrixOne](../Get-Started/install-standalone-matrixone.md). + +1. 使用命令 `mo_ctl help` 查看工具指南。 + +2. 使用命令 `mo_ctl precheck` 查看前置依赖条件是否满足。 + +3. 使用命令 `mo_ctl get_conf` 设置相关参数，可能用到的参数配置如下所示： + + ``` + mo_ctl set_conf MO_PATH="/data/mo/matrixone" #设置自定义的 MatrixOne 下载路径 + mo_ctl set_conf MO_GIT_URL="https://githubfast.com/matrixorigin/matrixone.git" #针对 github 原地址下载过慢问题，设置镜像下载地址 + ``` + +4. 使用命令 `mo_ctl deploy` 安装部署 MatrixOne 最新稳定版本。 + +5. 使用命令 `mo_ctl start` 启动 MatrixOne 服务。 + +6. 使用命令 `mo_ctl connect` 连接 MatrixOne 服务。 + +## 参考命令指南 + +### help - 打印参考指南 + +``` +mo_ctl help +Usage : mo_ctl [option_1] [option_2] + + [option_1] : available: connect | ddl_connect | deploy | get_branch | get_cid | get_conf | help | pprof | precheck | query | restart | set_conf | sql | start | status | stop | uninstall | upgrade | watchdog + 1) connect : connect to mo via mysql client using connection info configured + 2) ddl_convert : convert ddl file to mo format from other types of database + 3) deploy : deploy mo onto the path configured + 4) get_branch : upgrade or downgrade mo from current version to a target commit id or stable version + 5) get_cid : print mo git commit id from the path configured + 6) get_conf : get configurations + 7) help : print help information + 8) pprof : collect pprof information + 9) precheck : check pre-requisites for mo_ctl + 10) restart : a combination operation of stop and start + 11) set_conf : set configurations + 12) sql : execute sql from string, or a file or a path containg multiple files + 13) start : start mo-service from the path configured + 14) status : check if there's any mo process running on this machine + 15) stop : stop all mo-service processes found on this machine + 16) uninstall : uninstall mo from path MO_PATH=/data/mo/20230712_1228//matrixone + 17) upgrade : upgrade or downgrade mo from current version to a target commit id or stable version + 18) watchdog : setup a watchdog crontab task for mo-service to keep it alive + e.g. : mo_ctl status + + [option_2] : Use " mo_ctl [option_1] help " to get more info + e.g. : mo_ctl deploy help +``` + +使用 `mo_ctl [option_1] help` 来获取下一级 `mo_ctl [option_1]` 功能的使用指南。 + +### precheck - 检查前置依赖条件 + +源码安装 MatrixOne 前使用 `mo_ctl precheck` 检查前置依赖条件，目前前置依赖于 `go`/`gcc`/`git`/`mysql(client)`。 + +``` +mo_ctl precheck help +Usage : mo_ctl precheck # check pre-requisites for mo_ctl + Check list : go gcc git mysql +``` + +### deploy - 安装 MatrixOne + +使用 `mo_ctl deploy [mo_version] [force]` 安装部署稳定版本 MatrixOne, 或某个指定版本，通过 `force` 选项可以将同一目录下已经存在的 MatrixOne 版本删除，强制重新安装新版本。 + +``` +mo_ctl deploy help +Usage : mo_ctl deploy [mo_version] [force] # deploy mo onto the path configured + [mo_version]: optional, specify an mo version to deploy + [force] : optional, if specified will delete all content under MO_PATH and deploy from beginning + e.g. : mo_ctl deploy # default, same as mo_ctl deploy 1.2.1 + : mo_ctl deploy main # deploy development latest version + : mo_ctl deploy d29764a # deploy development version d29764a + : mo_ctl deploy 1.2.1 # deploy stable verson 1.2.1 + : mo_ctl deploy force # delete all under MO_PATH and deploy verson 1.2.1 + : mo_ctl deploy 1.2.1 force # delete all under MO_PATH and deploy stable verson 1.2.1 from beginning +``` + +### start - 启动 MatrixOne 服务 + +使用 `mo_ctl start` 启动 MatrixOne 服务，启动文件路径位于 `MO_PATH` 下。 + +``` +mo_ctl start help +Usage : mo_ctl start # start mo-service from the path configured +``` + +### stop - 停止 MatrixOne 服务 + +使用 `mo_ctl stop [force]` 停止本机器上所有 MatrixOne 服务，如果有多个 MatrixOne 服务在运行，也会全部停止。 + +``` + mo_ctl stop help +Usage : mo_ctl stop [force] # stop all mo-service processes found on this machine + [force] : optional, if specified, will try to kill mo-services with -9 option, so be very carefully + e.g. : mo_ctl stop # default, stop all mo-service processes found on this machine + : mo_ctl stop force # stop all mo-services with kill -9 command +``` + +### restart - 重启 MatrixOne 服务 + +使用 `mo_ctl restart [force]` 停止所有本机器上 MatrixOne 服务，并重启位于 `MO_PATH` 路径下的 MatrixOne 服务。 + +``` +mo_ctl restart help +Usage : mo_ctl restart [force] # a combination operation of stop and start + [force] : optional, if specified, will try to kill mo-services with -9 option, so be very carefully + e.g. : mo_ctl restart # default, stop all mo-service processes found on this machine and start mo-serivce under path of conf MO_PATH + : mo_ctl restart force # stop all mo-services with kill -9 command and start mo-serivce under path of conf MO_PATH +``` + +### connect - 通过 mysql-client 连接 MatrixOne 服务 + +使用 `mo_ctl connect` 连接到 MatrixOne 服务，连接参数均由 `mo_ctl` 工具中设置。 + +``` +mo_ctl connect help +Usage : mo_ctl connect # connect to mo via mysql client using connection info configured +``` + +### status - 检查 MatrixOne 的状态 + +使用 `mo_ctl status` 来检查 MatrixOne 的运行状态，是否在运行中。 + +``` +mo_ctl status help +Usage : mo_ctl status # check if there's any mo process running on this machine +``` + +### get_cid - 打印 MatrixOne 代码提交 id + +使用 `mo_ctl get_cid` 打印当前 `MO_PATH` 路径下的 MatrixOne 代码库提交 id。 + +``` +mo_ctl get_cid help +Usage : mo_ctl get_cid # print mo commit id from the path configured +``` + +### get_branch - 打印 MatrixOne 代码提交 id + +使用 `mo_ctl get_branch` 打印当前 `MO_PATH` 路径下的 MatrixOne 代码库分支。 + +``` +mo_ctl get_branch help +Usage : mo_ctl get_branch # print which git branch mo is currently on +``` + +### pprof - 收集性能信息 + +使用 `mo_ctl pprof [item] [duration]` 收集 MatrixOne 的相关性能信息，主要为开发人员进行调试使用。 + +``` +mo_ctl pprof help +Usage : mo_ctl pprof [item] [duration] # collect pprof information + [item] : optional, specify what pprof to collect, available: profile | heap | allocs + 1) profile : default, collect profile pprof for 30 seconds + 2) heap : collect heap pprof at current moment + 3) allocs : collect allocs pprof at current moment + [duration] : optional, only valid when [item]=profile, specifiy duration to collect profile + e.g. : mo_ctl pprof + : mo_ctl pprof profile # collect duration will use conf value PPROF_PROFILE_DURATION from conf file or 30 if it's not set + : mo_ctl pprof profile 30 + : mo_ctl pprof heap +``` + +### set_conf - 配置参数 + +使用 `mo_ctl set_conf [conf_list]` 配置 1 个或多个使用参数。 + +``` +mo_ctl set_conf help +Usage : mo_ctl setconf [conf_list] # set configurations + [conf_list] : configuration list in key=value format, seperated by comma + e.g. : mo_ctl setconf MO_PATH=/data/mo/matrixone,MO_PW=M@trix0riginR0cks,MO_PORT=6101 # set multiple configurations + : mo_ctl setconf MO_PATH=/data/mo/matrixone # set single configuration +``` + +!!! note + 当 set_conf 的设置的路径中包含变量如 `${MO_PATH}` 时，需要在 `$` 前加上 `\`，例如： + ```bash + mo_ctl set_conf MO_CONF_FILE="\${MO_PATH}/matrixone/etc/launch/launch.toml" + + ``` + +### get_conf - 获取参数列表 + +使用 `mo_ctl get_conf [conf_list]` 获取一个或多个当前配置项。 + +``` +mo_ctl get_conf help +Usage : mo_ctl getconf [conf_list] # get configurations + [conf_list] : optional, configuration list in key, seperated by comma. + : use 'all' or leave it as blank to print all configurations + e.g. : mo_ctl getconf MO_PATH,MO_PW,MO_PORT # get multiple configurations + : mo_ctl getconf MO_PATH # get single configuration + : mo_ctl getconf all # get all configurations + : mo_ctl getconf # get all configurations +``` + +#### mo_ctl get_conf - 详细参数列表 + +使用 `mo_ctl get_conf` 将打印当前工具使用的所有参数列表，它们的释义与取值范围如下表所示。 + +| 参数名称 | 功能 | 取值规范 | +| ---------------------- | ------------------------------------------------------ | ----------------------------------------------------- | +| MO_PATH | MatrixOne 的代码库及可执行文件存放位置 | 文件夹路径 | +| MO_LOG_PATH | MatrixOne 的日志存放位置 | 文件夹路径，默认为${MO_PATH}/matrixone/logs | +| MO_HOST | 连接 MatrixOne 服务的 IP 地址 | IP 地址，默认为 127.0.0.1 | +| MO_PORT | 连接 MatrixOne 服务的端口号 | 端口号，默认为 6001 | +| MO_USER | 连接 MatrixOne 服务使用的用户名 | 用户名，默认为 root | +| MO_PW | 连接 MatrixOne 服务使用的密码 | 密码，默认为 111 | +| CHECK_LIST | precheck 需要的检查依赖项 | 默认为 ("go" "gcc" "git" "mysql") | +| GCC_VERSION | precheck 检查的 gcc 版本 | 默认为 8.5.0 | +| GO_VERSION | precheck 检查的 go 版本 | 默认为 1.22.3 | +| MO_GIT_URL | MatrixOne 的源码拉取地址 | 默认为 | +| MO_DEFAULT_VERSION | 默认拉取的 MatrixOne 的版本 | 默认为 1.2.1 | +| GOPROXY | GOPROXY 的地址，一般为国内加速拉取 golang 依赖包而使用 | 默认为,direct | +| STOP_INTERVAL | 停止间隔，停止服务后检测服务状态等待时间 | 默认为 5 秒 | +| START_INTERVAL | 启动间隔，启动服务后检测服务状态等待时间 | 默认为 2 秒 | +| MO_DEBUG_PORT | MatrixOne 的 debug 端口，一般为开发人员使用 | 默认为 9876 | +| MO_CONF_FILE | MatrixOne 的启动配置文件 | 默认为${MO_PATH}/matrixone/etc/launch/launch.toml | +| RESTART_INTERVAL | 重启间隔，重启服务后检测服务状态等待时间 | 默认为 2 秒 | +| PPROF_OUT_PATH | golang 的性能收集数据输出路径 | 默认为/tmp/pprof-test/ | +| PPROF_PROFILE_DURATION | golang 的性能收集时间 | 默认为 30 秒 | + +### ddl_convert - DDL 格式转换 + +使用 `mo_ctl ddl_convert [options] [src_file] [tgt_file]` 将一个 DDL 文件从其他数据库语法格式转换成 MatrixOne 的 DDL 格式，目前仅有 `mysql_to_mo` 模式支持。 + +``` +mo_ctl ddl_convert help +Usage : mo_ctl ddl_convert [options] [src_file] [tgt_file] # convert a ddl file to mo format from other types of database + [options] : available: mysql_to_mo + [src_file] : source file to be converted, will use env DDL_SRC_FILE from conf file by default + [tgt_file] : target file of converted output, will use env DDL_TGT_FILE from conf file by default + e.g. : mo_ctl ddl_convert mysql_to_mo /tmp/mysql.sql /tmp/mo.sql +``` + +### sql - 执行 SQL + +使用 `mo_ctl sql [sql]` 来执行 SQL 文本或者 SQL 文件。 + +``` +mo_ctl sql help +Usage : mo_ctl sql [sql] # execute sql from string, or a file or a path containg multiple files + [sql] : a string quote by "", or a file, or a path + e.g. : mo_ctl sql "use test;select 1;" # execute sql "use test;select 1" + : mo_ctl sql /data/q1.sql # execute sql in file /data/q1.sql + : mo_ctl sql /data/ # execute all sql files with .sql postfix in /data/ +``` + +### uninstall - 卸载 MatrixOne + +使用 `mo_ctl uninstall` 来从 MO_PATH 上卸载 MatrixOne。 + +``` +mo_ctl uninstall help +Usage : mo_ctl uninstall # uninstall mo from path MO_PATH=/data/mo//matrixone + # note: you will need to input 'Yes/No' to confirm before uninstalling +``` + +### upgrade - 升级/降级 MatrixOne 版本 + +MatrixOne 0.8 及更高版本可使用 `mo_ctl upgrade version` 或者 `mo_ctl upgrade commitid` 来将 MatrixOne 从当前版本升级或降级到某个稳定版本或者某个 commit id 版本。 + +``` +mo_ctl upgrade help +Usage : mo_ctl upgrade [version_commitid] # upgrade or downgrade mo from current version to a target commit id or stable version + [commitid] : a commit id such as '38888f7', or a stable version such as '1.2.1' + : use 'latest' to upgrade to latest commit on main branch if you don't know the id + e.g. : mo_ctl upgrade 38888f7 # upgrade/downgrade to commit id 38888f7 on main branch + : mo_ctl upgrade latest # upgrade/downgrade to latest commit on main branch + : mo_ctl upgrade 1.2.1 # upgrade/downgrade to stable version 1.2.1 +``` + +### watchdog - 保活 MatrixOne + +使用 `mo_ctl watchdog [options]` 设置一个定时任务保证 MatrixOne 服务可用性，每分钟检查 MatrixOne 的状态，如果发现服务中止则自动拉起服务。 + +``` +mo_ctl watchdog help +Usage : mo_ctl watchdog [options] # setup a watchdog crontab task for mo-service to keep it alive + [options] : available: enable | disable | status + e.g. : mo_ctl watchdog enable # enable watchdog service for mo, by default it will check if mo-servie is alive and pull it up if it's dead every one minute + : mo_ctl watchdog disable # disable watchdog + : mo_ctl watchdog status # check if watchdog is enabled or disabled + : mo_ctl watchdog # same as mo_ctl watchdog status +``` + + diff --git a/mkdocs.yml b/mkdocs.yml index bc4467006b..9c9af3b26c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -636,7 +636,8 @@ nav: - MatrixOne 的 JDBC 功能支持列表: MatrixOne/Reference/Limitations/mo-jdbc-feature-list.md - MatrixOne 文件目录结构: MatrixOne/Maintain/mo-directory-structure.md - MatrixOne 工具: - - mo_ctl 工具: MatrixOne/Reference/mo-tools/mo_ctl.md + - mo_ctl 单机工具: MatrixOne/Reference/mo-tools/mo_ctl_standalone.md + - mo_ctl 分布式工具: MatrixOne/Reference/mo-tools/mo_ctl.md - mo_datax_writer 工具: MatrixOne/Reference/mo-tools/mo_datax_writer.md - mo_ssb_open 工具: MatrixOne/Reference/mo-tools/mo_ssb_open.md - mo_tpch_open 工具: MatrixOne/Reference/mo-tools/mo_tpch_open.md