Gemix使用指南

openGemini大约 10 分钟约 3021 字

本文主要介绍Gemix如何使用，欢迎大家试用和反馈。

仓库地址：https://github.com/openGemini/gemixopen in new window

问题反馈：https://github.com/openGemini/gemix/issuesopen in new window

Gemix 概览

在各种系统软件和应用软件的安装管理中，包管理器有着广泛的应用，包管理工具的出现大大简化了软件的安装和升级维护工作。例如，几乎所有使用 RPM 的 Linux 都会使用 yum 来进行包管理，而 Anaconda 则可以非常方便地管理 Python 的环境和相关软件包。

在早期的 openGemini 生态中，没有专门的包管理工具，使用者只能通过相应的配置文件和文件夹命名来手动管理，由于openGemini组件多，配置参数多，配置问题是社区收到反馈最多的问题，为此我们希望开发一款工具，帮助大家更容易安装和运维openGemini。

在业界，我们看到Tiup工具做的非常好，参考之下，社区开发了Gemix，它是一款openGemini 运维工具，第一阶段主要完成了openGemini集群安装、集群启停、集群卸载、集群监控（自带Grafana的监控模板）等功能，您只需规划好集群的各组件分布，无需再配置繁杂的集群配置文件，就可以实现一键安装部署。

安装 Gemix

执行如下命令安装 gemix 工具

> go install github.com/openGemini/gemix@latest

安装成功后，gemix二进制保存在$GOPATH/bin目录。如果是国内用户，安装失败，建议配置GOPROXY

> export GOPROXY=https://goproxy.cn

使用Gemix部署openGemini集群

安装好gemix后，就可以使用gemix部署openGemini集群了

1. 初始化集群拓扑文件

执行如下命令，生成集群初始化配置文件：

> gemix cluster template > topology.yaml

2. 配置集群拓扑文件

打开配置文件

> vim topology.yaml

配置文件topology.yaml分为如下7个部分，主要是为了告诉gemix工具，在哪些机器部署哪些组件，每个组件需要安装到目标机器什么位置，各组件的数据和日志存放到机器什么位置，是否需要部署集群监控和监控面板等。

global:
	...
monitored:
	...
ts_meta_servers:
	...
ts_sql_servers:
	...
ts_store_servers:
	...
grafana_servers:
	...
server_configs:
	...

global

global主要配置项如下

  ### The user who runs the openGemini cluster.
  user: "root"
  ### group is used to specify the group name the user belong to if it's not the same as user.
  # group: "root"
  ### Storage directory for cluster deployment files, startup scripts, and configuration files.
  deploy_dir: "/var/lib/openGemini/deploy"
  ### openGemini Cluster log file storage directory.
  log_dir: "/var/lib/openGemini/logs"
  ### openGemini Cluster data storage directory
  data_dir: "/gemini-data/meta"
  # operating system, linux/darwin.
  os: "linux"
  # Supported values: "amd64", "arm64" (default: "amd64").
  arch: "amd64"

user 和 group 指定部署openGemini的机器的用户名和用户组，如果不存在该用户，gemix会自动创建该用户，并加入用户组。默认为root

deploy_dir指定openGemini组件，如ts-sql，ts-store等二进制的安装目录。这里配置了，后面可不再配置

log_dir指定openGemini各组件对应日志文件的存放目录。这里配置了，后面可不再配置

data_dir 指定openGemini组件（ts-store、ts-meta）的数据存放目录。这里配置了，后面可不再配置，但一般来说，ts-store会存储业务数据、WAL数据等，ts-meta会存储集群元数据、快照数据等，建议后面单独配置，使用不同目录进行区分，比如ts-store的数据目录为 /gemini-data/data, ts-meta的数据目录为/gemini-data/meta

os和arch分别指定部署机器的操作系统类型和对应CPU架构，用于下载对应的版本。目前暂不支持Windows。

monitored

monitored是配置是否需要为openGemini部署集群监控（参考集群监控），其主要配置项如下

  ### Enable ts-monitor instance for all the machines
  ts_monitor_enabled: true
  ### Storage directory for deployment files, startup scripts, and configuration files of monitoring components.
  # deploy_dir: "/var/lib/openGemini/deploy"
  ### Log storage directory of the ts-monitor component.
  # log_dir: "/var/lib/openGemini/logs"

ts_monitor_enabled为true表示需要为openGemini部署集群监控，false则不会安装

deploy_dir和log_dir表示采集集群监控指标的组件被部署的目录和产生的日志存储目录。在前面的global中若有配置deploy_dir，则这里可不用配置。

ts_meta_servers

ts_meta_servers主要配置部署openGemini的ts-meta组件的机器信息。主要配置项如下

	### The ip address of the ts-meta Server.
  - host: 10.0.1.11
    ### SSH port of the server.
    # ssh_port: 22
    ### Access the ts-meta cluster port. (for devops)
    client_port: 8091
    ### communication port among ts-meta Server nodes.
    # peer_port: 8092
    ### communication raft port among ts-meta Server nodes.
    # raft_port: 8088
    ### communication gossip port among ts-meta and ts-store Server nodes.
    # gossip_port: 8010
    ### ts-meta Server deployment file, startup script, configuration file storage directory.
    deploy_dir: "/var/lib/openGemini/deploy"
    ### ts-meta Server logs storage directory.
    log_dir: "/var/lib/openGemini/logs"
    ### ts-meta Server meta data storage directory.
    data_dir: "/var/lib/openGemini/meta"

部署ts-meta组件，openGemini要求ts-meta要部署三个节点，以确保元数据的可靠性。一般建议部署在三台不同的虚拟机或物理机上，ts-meta可以与ts-store，ts-sql合部在一台机器上。如果希望两个及以上ts-meta要部署在同一台机器上，需要参考openGemini端口矩阵对ts-meta的相关端口进行调整，避免出现端口冲突。

这里以ts-meta部署在三台不同虚拟机为例

host指定部署ts-meta的其中第一台机器IP地址

client_port, peer_port, raft_port, gossip_port等保持默认。除非要修改对应端口号，参考openGemini端口矩阵

deploy_dir指定ts-meta二进制的存放目录，在前面的global中若有配置deploy_dir，则这里可不用配置。

log_dir指定ts-meta的日志存放目录，在前面的global中若有配置log_dir，则这里可不用配置。

data_dir指定ts-meta存放数据的目录，建议配置

上述为一个节点的配置，其余两个节点的配置可参考上述配置。总结起来，绝大多数情况下，只需配置host和data_dir即可。

ts_sql_servers

ts_sql_servers主要配置部署openGemini的ts-sql组件的机器信息。主要配置项如下

	### The ip address of the ts-sql Server.
  - host: 10.0.1.14
    ### Access the openGemini cluster port.
    # port: 8086
    ### ts-sql Server deployment file, startup script, configuration file storage directory.
    deploy_dir: "/var/lib/openGemini/deploy"
    ### ts-sql Server logs storage directory.
    log_dir: "/var/lib/openGemini/logs"

host指定部署ts-sql的机器IP地址

port可以保持默认。除非要修改对应端口号，参考openGemini端口矩阵

deploy_dir指定ts-sql二进制的存放目录，在前面的global中若有配置deploy_dir，则这里可不用配置。

log_dir指定ts-sql的日志存放目录，在前面的global中若有配置log_dir，则这里可不用配置。

若需要部署多个ts-sql，可参考上述配置多台机器信息。

ts_store_servers

ts_sql_servers主要配置部署openGemini的ts-store组件的机器信息。主要配置项如下

	### The ip address of the ts-store Server.
	- host: 10.0.1.14
    ### ingest data port
    # ingest_port: 8400
    ### select data port
    # select_port: 8401
    ### communication gossip port among ts-meta and ts-store Server nodes.
    # gossip_port: 8011
    ### ts-store Server deployment file, startup script, configuration file storage directory.
    deploy_dir: "/var/lib/openGemini/deploy"
    ### ts-store Server logs storage directory.
    log_dir: "/var/lib/openGemini/logs"
    ### ts-store Server meta data storage directory.
    data_dir: "/var/lib/openGemini/data"

host指定部署ts-store的机器IP地址

ingest_port, select_port, gossip_port可以保持默认。除非要修改对应端口号，参考openGemini端口矩阵

deploy_dir指定ts-store二进制的存放目录，在前面的global中若有配置deploy_dir，则这里可不用配置。

log_dir指定ts-store的日志存放目录，在前面的global中若有配置log_dir，则这里可不用配置。

data_dir指定ts-store存放数据的目录，建议配置

若需要部署多个ts-store，可参考上述配置多台机器信息。

grafana_servers

grafana_servers主要配置部署Grafana的机器信息。主要配置项如下

	### The ip address of the Grafana Server.
  - host: 10.0.1.17
    ### Grafana Web monitoring service client (browser) access port
    # port: 3000
    ### Grafana deployment file, startup script, configuration file storage directory.
    # deploy_dir: /var/lib/openGemini/deploy/grafana-3000
    ### grafana dashboard dir on gemix machine
    # dashboard_dir: /home/gemini/dashboards

host指定部署Grafana的机器IP地址

port可以保持默认。除非要修改Grafana服务的监听端口

deploy_dir指定Grafana的安装目录，在前面的global中若有配置deploy_dir，则这里可不用配置。

dashboard_dir指定存放openGemini监控面板模板的目录，建议配置。

server_configs

server_configs 用于配置具体的openGemini内核组件，生成各组件的配置文件，主要配置项如下：

  # server_configs:
  # ts-meta:
  # ts-sql:
  # ts-store:
  # ts-monitor:

ts-sql：ts-sql 服务的相关配置，完整配置请参考 ts-sql配置文件描述

ts-store：ts-store 服务的相关配置，完整配置请参考 ts-store 配置文件描述

ts-meta：ts-meta 服务的相关配置，完整配置请参考 ts-meta 配置文件描述

ts-monitor：ts-monitor 服务的相关配置，完整配置请参考 ts-monitor 配置文件描述

3. 部署集群

上述配置文件准备好之后，就可以执行如下命令开始部署openGemini集群

> gemix cluster install gemini_test v1.1.1 ./topology.yaml --user root -p --skip-create-user

这条命令会部署一个名为gemini_test的openGemini集群，部署的openGemini版本为v1.1.1，集群部署的拓扑文件是topology.yaml，部署时访问机器的方式是用户名+密码，用户名为root，--skip-create-user跳过对root用户的创建。

国内用户如果访问github存在网络问题，可以执行如下命令进行安装

> GEMIX_MIRRORS_REPO=gitee.com gemix cluster install gemini_test v1.1.1 ./topology.yaml --user root -p

GEMIX_MIRRORS_REPO=gitee.com环境变量将指定从国内Gitee上下载openGemini的二进制版本。

提示

⚠️ 值得注意的是，选择从Gitee下载版本，只能安装v1.1.1及以上版本。

如果使用密钥方式

> gemix cluster install gemini_test v1.1.1 ./topology.yaml --user root -k /home/root/.ssh/id_rsa

如果配置了免密登录

> gemix cluster install gemini_test v1.1.1 ./topology.yaml --user root

提示

一般情况下 gemix 会在目标机器上创建 topology.yaml 中约定的用户和组，以下情况例外：

  • topology.yaml 中设置的用户名在目标机器上已存在。
  • 在命令行上使用了参数 --skip-create-user 明确指定跳过创建用户的步骤。

4. 集群启动

使用以下命令会将所有实例节点的相关进程启动。

> gemix cluster start gemini_test

预期结果输出 Started cluster gemini-test successfully，表示启动成功。

5.集群下线

使用以下命令会将所有实例节点的相关进程退出。

> gemix cluster stop gemini_test

预期结果输出 Stop cluster gemini_test successfully，表示下线成功。

提示

集群部署好之后，如果重新修改了ts-sql或者ts-store的配置文件，则需要将集群重启，具体操作方式为先将集群下线，再重新启动。

若是修改了topology.yaml，则需要重新安装

6.集群卸载

当业务下线之后，如果想将集群占有的机器释放出来让给其他业务使用，执行如下命令将销毁集群

> gemix cluster uninstall

执行该命令需要谨慎：

  • 停止集群
  • 对于每个服务，删除其日志目录，部署目录，数据目录
  • 如果各个服务的数据目录/部署目录的父目录是由 gemix-cluster 创建的，也一并删除

配置示例

以三台虚拟机部署openGemini集群为例, 额外一台机器作为运行gemix的执行机器，再一台机器用于部署Grafana，拓扑配置文件示例如下：

global:
  user: "root"
  deploy_dir: "/usr/local/openGemini"
  log_dir: "/var/openGemini/logs"
  os: "linux"
  arch: "amd64"
monitored:
	ts_monitor_enabled: true
ts_meta_servers:
	- host: 10.0.1.11
		data_dir: "/var/openGemini/data/meta"
	- host: 10.0.1.12
		data_dir: "/var/openGemini/data/meta"
	- host: 10.0.1.13
		data_dir: "/var/openGemini/data/meta"
ts_sql_servers:
	- host: 10.0.1.11
	- host: 10.0.1.12
ts_store_servers:
	- host: 10.0.1.11
		data_dir: "/var/openGemini/data/data"
	- host: 10.0.1.12
		data_dir: "/var/openGemini/data/data"
	- host: 10.0.1.13
		data_dir: "/var/openGemini/data/data"
grafana_servers:
	- host: 10.0.1.14
server_configs:
	ts-sql:
	  # 修改鉴权配置
		http.auth-enabled: false
	ts-store:
	  # 修改ts-store的wal文件目录
		data.store-wal-dir: "/var/openGemini/data/wal"
	ts-monitor:
	  # 修改存储监控数据的库名，默认为集群名
		report.database: "_internal"
    # 监控数据默认被写入当前集群的目标数据库中，如果需要将监控数据写入单独节点上的openGemini，可修改地址
    report.address: "11.0.1.14:8086"

修改ts-sql、ts-store等其他组件启动的配置文件，可以参考示例中的server_configs的文件格式进行配置。

警告

deploy_dir, data_dir, log_dir 不支持使用共享目录，否则会出现不可预料的问题。

openGemini is a Cloud Native Computing Foundation sandbox project.

The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page. 2024 © openGemini Project Authors. All rights reserved.