配置 GreptimeDB

配置 GreptimeDB

GreptimeDB 提供了层次化的配置能力，按照下列优先顺序来生效配置：

命令行参数
配置文件
环境变量
默认值

本文介绍了配置 GreptimeDB server 的方法，用户可以在 TOML 文件中进行设置。

在配置文件中，对于缺失的参数，系统会赋予其一个默认值。

所有样本配置文件都放在项目的 config 文件夹中。

命令行选项

请阅读命令行工具学习如何使用 greptime 命令行工具。

全局选项

-h/--help: 打印命令行帮助信息
-V/--version: 打印 GreptimeDB 版本信息
--log-dir <LOG_DIR>: 指定日志路径
--log-level <LOG_LEVEL>: 指定日志级别，如 info、debug 等。

datanode 子命令选项

通过执行下列命令来获取 datanode 子命令的帮助菜单：

greptime datanode start --help

-c/--config-file: 指定 datanode 启动的配置文件
--data-home: 数据库存储 home 目录
--env-prefix <ENV_PREFIX>: 配置的环境变量前缀，默认为 GREPTIMEDB_DATANODE;
--http-addr <HTTP_ADDR>: HTTP 服务地址
--http-timeout <HTTP_TIMEOUT>: HTTP 超时设置，单位秒
--metasrv-addr <METASRV_ADDR>: Metasrv 服务器列表，用逗号隔开
--node-id <NODE_ID>: 节点 ID
--rpc-addr <RPC_ADDR>: gRPC 服务地址
--rpc-hostname <RPC_HOSTNAME>: 节点 hostname
--wal-dir <WAL_DIR>: WAL 日志目录;

所有的地址类选项都是 ip:port 形式的字符串。

metasrv 子命令选项

通过执行下列命令来获取 metasrv 子命令的帮助菜单：

greptime metasrv start --help

-c/--config-file: 指定 metasrv 启动配置文件
--enable-region-failover: 是否启动 region 自动容灾，默认为 false 不启用。
--env-prefix <ENV_PREFIX>: 配置的环境变量前缀，默认为GREPTIMEDB_METASRV;
--bind-addr <BIND_ADDR>:服务监听地址，默认为 127.0.0.1:3002.
--http-addr <HTTP_ADDR>: HTTP 服务器地址
--http-timeout <HTTP_TIMEOUT>: HTTP 超时设置，单位秒
--selector <SELECTOR>: 参考 selector 类型;
--server-addr <SERVER_ADDR>: 提供给 frontend 和 datanode 的外部通讯服务器地址
--store-addr <STORE_ADDR>: 存储元数据的 etcd 地址列表，用逗号隔开
--use-memory-store: 是否使用内存存储替代 etcd，仅用于测试

frontend 子命令选项

通过执行下列命令来获取 frontend 子命令的帮助菜单：

greptime frontend start --help

-c/--config-file: 指定 frontend 启动配置文件
--disable-dashboard: 是否禁用 dashboard，默认为 false。
--env-prefix <ENV_PREFIX>: 配置的环境变量前缀，默认为GREPTIMEDB_FRONTEND;
--rpc-addr <RPC_ADDR>: gRPC 服务地址
--http-addr <HTTP_ADDR>: HTTP 服务器地址
--http-timeout <HTTP_TIMEOUT>: HTTP 超时设置，单位秒
--influxdb-enable: 是否启用 influxdb HTTP 接口，默认为 true。
--metasrv-addr <METASRV_ADDR>: Metasrv 地址列表，用逗号隔开
--mysql-addr <MYSQL_ADDR>: MySQL 服务地址
--opentsdb-addr <OPENTSDB_ADDR>: OpenTSDB 服务地址
--postgres-addr <POSTGRES_ADDR>: Postgres 服务地址
--tls-cert-path <TLS_CERT_PATH>: TLS 公钥文件地址
--tls-key-path <TLS_KEY_PATH>: TLS 私钥文件地址
--tls-mode <TLS_MODE>: TLS 模式
--user-provider <USER_PROVIDER>: 参考鉴权;

standalone 子命令选项

通过执行下列命令来获取 standalone 子命令的帮助菜单：

greptime standalone start --help

-c/--config-file: 指定 standalone 启动配置文件
--env-prefix <ENV_PREFIX>: 配置的环境变量前缀，默认为GREPTIMEDB_STANDALONE;
--http-addr <HTTP_ADDR>: HTTP 服务器地址
--influxdb-enable: 是否启用 influxdb HTTP 接口，默认为 true。
--mysql-addr <MYSQL_ADDR>: MySQL 服务地址
--opentsdb-addr <OPENTSDB_ADDR>: OpenTSDB 服务地址
--postgres-addr <POSTGRES_ADDR>: Postgres 服务地址
--rpc-addr <RPC_ADDR>: gRPC 服务地址

配置文件

指定配置文件

用户可以通过使用命令行参数 -c [file_path] 指定配置文件，比如：

greptime [standalone | frontend | datanode | metasrv]  start -c config/standalone.example.toml

常见配置

在 frontend 和 standalone 子命令中常见的协议配置有：

toml

[http]
addr = "127.0.0.1:4000"
timeout = "30s"
body_limit = "64MB"
[grpc]
addr = "127.0.0.1:4001"
runtime_size = 8
[mysql]
enable = true
addr = "127.0.0.1:4002"
runtime_size = 2
[mysql.tls]
mode = "disable"
cert_path = ""
key_path = ""
[postgres]
enable = true
addr = "127.0.0.1:4003"
runtime_size = 2
[postgres.tls]
mode = "disable"
cert_path = ""
key_path = ""
[opentsdb]
enable = true
addr = "127.0.0.1:4242"
runtime_size = 2
[influxdb]
enable = true
[prom_store]
enable = true

除了 HTTP 和 gRPC 以外，其他协议都是可选的，上面列出了其默认值。如果想禁用某些协议，比如 OpenTSDB 协议，可以将 enable 的值设为 false。

协议选项

选项	键	类型	描述
http			HTTP 服务器选项
	addr	字符串	服务器地址，默认为 “127.0.0.1:4000”
	timeout	字符串	HTTP 请求超时时间，默认为 “30s”
	body_limit	字符串	HTTP 最大体积大小，默认为 “64MB”
grpc			gRPC 服务器选项
	addr	字符串	服务器地址，默认为 “127.0.0.1:4001”
	runtime_size	整数	服务器工作线程数量，默认为 8
mysql			MySQL 服务器选项
	enable	布尔值	是否启用 MySQL 协议，默认为 true
	add	字符串	服务器地址，默认为 “127.0.0.1:4002”
	runtime_size	整数	服务器工作线程数量，默认为 2
influxdb			InfluxDB 协议选项
	enable	布尔值	是否在 HTTP API 中启用 InfluxDB 协议，默认为 true
opentsdb			OpenTSDB 协议选项
	enable	布尔值	是否启用 OpenTSDB 协议，默认为 true
	addr	字符串	OpenTSDB telnet API 服务器地址，默认为 “127.0.0.1:4242”
	runtime_size	整数	服务器工作线程数量，默认为 2
prom_store			Prometheus 远程存储选项
	enable	布尔值	是否在 HTTP API 中启用 Prometheus 远程读写，默认为 true
postgres			PostgresSQL 服务器选项
	enable	布尔值	是否启用 PostgresSQL 协议，默认为 true
	addr	字符串	服务器地址，默认为 “127.0.0.1:4003”
	runtime_size	整数	服务器工作线程数量，默认为 2

节点选项

一些共同的节点选项：

Option	Key	Type	Description
	mode	字符串	节点运行模式，可以是 `“standalone”` 或者 `“distributed”`

存储选项

存储选项在 datanode 和 standalone 模式下有效，它指定了数据库数据目录和其他存储相关的选项。

GreptimeDB 支持将数据保存在本地文件系统， AWS S3 以及其兼容服务（比如 MinIO、digitalocean space、腾讯 COS、百度对象存储（BOS）等），Azure Blob Storage 和阿里云 OSS。

选项	键	类型	描述
storage			存储选项
	type	字符串	存储类型，支持 “File”，”S3” 和 “Oss” 等.
File			本地文件存储选项，当 type=”File” 时有效
	data_home	字符串	数据库存储根目录，默认为 “/tmp/greptimedb”
S3			AWS S3 存储选项，当 type=”S3” 时有效
	bucket	字符串	S3 桶名称
	root	字符串	S3 桶中的根路径
	endpoint	字符串	S3 的 API 端点
	region	字符串	S3 区域
	access_key_id	字符串	S3 访问密钥 id
	secret_access_key	字符串	S3 秘密访问密钥
Oss			阿里云 OSS 存储选项，当 type=”Oss” 时有效
	bucket	字符串	OSS 桶名称
	root	字符串	OSS 桶中的根路径
	endpoint	字符串	OSS 的 API 端点
	access_key_id	字符串	OSS 访问密钥 id
	secret_access_key	字符串	OSS 秘密访问密钥
Azblob			Azure Blob 存储选项，当 type=”Azblob” 时有效
	container	字符串	容器名称
	root	字符串	容器中的根路径
	endpoint	字符串	Azure Blob 存储的 API 端点
	account_name	字符串	Azure Blob 存储的账户名
	account_key	字符串	访问密钥
	sas_token	字符串	共享访问签名
Gsc			Google Cloud Storage 存储选项，当 type=”Gsc” 时有效
	root	字符串	Gsc 桶中的根路径
	bucket	字符串	Gsc 桶名称
	scope	字符串	Gsc 权限
	credential_path	字符串	Gsc 访问证书
	endpoint	字符串	GSC 的 API 端点

文件存储配置范例：

toml

[storage]
type = "File"
data_home = "/tmp/greptimedb/"

s3 配置范例：

toml

[storage]
type = "S3"
bucket = "test_greptimedb"
root = "/greptimedb"
access_key_id = "<access key id>"
secret_access_key = "<secret access key>"

自定义多存储引擎

[[storage.providers]] 用来设置存储引擎的提供商列表。基于这个配置，你可以为每张表指定不同的存储引擎，具体请参考 create table:

toml

# Allows using multiple storages
[[storage.providers]]
type = "S3"
bucket = "test_greptimedb"
root = "/greptimedb"
access_key_id = "<access key id>"
secret_access_key = "<secret access key>"
[[storage.providers]]
type = "Gcs"
bucket = "test_greptimedb"
root = "/greptimedb"
credential_path = "<gcs credential path>"

所有配置的这些存储引擎提供商都可以在创建表时用作 storage 选项。

对象存储缓存

当使用 S3、阿里云 OSS 等对象存储的时候，最好开启缓存来加速查询：

toml

[storage]
type = "S3"
bucket = "test_greptimedb"
root = "/greptimedb"
access_key_id = "<access key id>"
secret_access_key = "<secret access key>"
## 开启对象存储缓存
cache_path = "/var/data/s3_local_cache"
cache_capacity = "256MiB"

cache_path 指定本地的缓存目录， cache_capacity 指定缓存的最大大小（字节）。

WAL 选项

datanode 和 standalone 在 [wal] 部分可以配置 Write-Ahead-Log 的对应参数：

toml

[wal]
file_size = "256MB"
purge_threshold = "4GB"
purge_interval = "10m"
read_batch_size = 128
sync_write = false

dir: WAL 的日志目录，当使用文件 File 存储的时候, 默认值为{data_home}/wal 。当使用对象存储的时候，必须明确指定。
file_size: 单个日志文件的最大大小，默认为 256MB。
purge_threshold 和 purge_interval: 控制清除任务的触发阈值和间隔
sync_write: 是否在写入每条日志的时候调用 l fsync 刷盘。

存储引擎选项

datanode 和 standalone 在 [region_engine] 部分可以配置不同存储引擎的对应参数。目前只有一种存储引擎 mito。

toml

[[region_engine]]
[region_engine.mito]
num_workers = 1
manifest_checkpoint_distance = 10
max_background_jobs = 4
global_write_buffer_size = "1GB"
global_write_buffer_reject_size = "2GB"

num_workers: 写入线程数量
manifest_checkpoint_distance: 每写入 manifest_checkpoint_distance 个 manifest 文件创建一次 checkpoint
max_background_jobs: 后台线程数量
global_write_buffer_size: 写入缓冲区大小，默认 1GB
global_write_buffer_reject_size: 写入缓冲区内数据的大小超过 global_write_buffer_reject_size 后拒绝写入请求，需要比 global_write_buffer_size 大，默认 2GB

单机模式

当用户在单机模式（standalone）下使用 GreptimeDB 时，可以参考 standalone.example.toml 配置文件。

类似下面这样的命令启动：

greptime standalone start -c standalone.example.toml

分布式模式下的 `Frontend`

在分布式模式下配置 Frontend：

toml

mode = "distributed"
[meta_client]
metasrv_addrs = ["127.0.0.1:3002"]
timeout = "3s"
connect_timeout = "1s"
ddl_timeout = "10s"
tcp_nodelay = true

指定运行模式为 "distributed"。

通过 meta_client 配置 metasrv 客户端，包括：

metasrv_addrs， Metasrv 地址列表，对应 Metasrv 启动配置的 server address。
timeout，操作超时时长，默认为 3 秒。
connect_timeout，连接服务器超时时长，默认为 1 秒。
ddl_timeout， DDL 执行的超时时间，默认 10 秒。
tcp_nodelay，接受连接时的 TCP_NODELAY 选项，默认为 true。

这里可以找到配置 frontend 分布式模式运行的样例配置文件 frontend.example.toml.

分布式模式下的 `Datanode`

在分布式模式下配置 datanode：

toml

node_id = 42
mode = "distributed"
rpc_hostname = "127.0.0.1"
rpc_addr = "127.0.0.1:3001"
rpc_runtime_size = 8
[meta_client]
metasrv_addrs = ["127.0.0.1:3002"]
timeout = "3s"
connect_timeout = "1s"
tcp_nodelay = false

分布式模式下的 datanode 应该在不同的节点上设置不同的 node_id。

这里可以找到配置 datanode 分布式模式运行的样例配置文件 datanode.example.toml.

Metasrv 配置

一份配置样例文件 metasrv.example.toml：

toml

# The working home directory.
data_home = "/tmp/metasrv/"
# The bind address of metasrv, "127.0.0.1:3002" by default.
bind_addr = "127.0.0.1:3002"
# The communication server address for frontend and datanode to connect to metasrv,  "127.0.0.1:3002" by default for localhost.
server_addr = "127.0.0.1:3002"
# Etcd server addresses, "127.0.0.1:2379" by default.
store_addr = "127.0.0.1:2379"
# Datanode selector type.
# - "lease_based" (default value).
# - "load_based"
# For details, please see "https://docs.greptime.com/contributor-guide/meta/selector".
selector = "lease_based"
# Store data in memory, false by default.
use_memory_store = false

键	类型	描述
data_home	字符串	Metasrv 的工作目录，默认为 `“/tmp/metasrv/“`
bind_addr	字符串	Metasrv 的绑定地址，默认为 `“127.0.0.1:3002”`。
server_addr	字符串	前端和数据节点连接到 Metasrv 的通信服务器地址，默认为 `“127.0.0.1:3002”`（适用于本地主机）
store_addr	字符串	etcd 服务器地址，默认为 `“127.0.0.1:2379”`，服务器地址由逗号分隔，格式为 `“ip1:port1,ip2:port2,…”`。
selector	字符串	创建新表时选择数据节点的负载均衡策略，参见选择器
use_memory_store	布尔值	仅在测试时使用，当你没有 etcd 集群时，将数据存储在内存中，默认为 `false`

Logging 选项

frontend、metasrv、datanode 和 standalone 都可以在 [logging] 部分配置 log、tracing 相关参数：

toml

[logging]
dir = "/tmp/greptimedb/logs"
level = "info"
enable_otlp_tracing = false
otlp_endpoint = "localhost:4317"
tracing_sample_ratio = 1.0
append_stdout = true

dir: log 输出目录。
level: log 输出的日志等级，日志等级有 info, debug, error, warn，默认等级为 info。
enable_otlp_tracing：是否打开分布式追踪，默认不开启。
otlp_endpoint：使用基于 gRPC 的 OTLP 协议导出 tracing 的目标端点，默认值为 localhost:4317。
tracing_sample_ratio：采样 tracing 的百分比，取值范围 [0,1]，默认值为 1，代表采样所有的 tracing。
append_stdout：是否将日志打印到stdout。默认是true。

如何使用分布式追踪，请参考 Tracing

环境变量配置

配置文件中的每一项都可以映射到环境变量。例如，如果我们想通过环境变量设置 datanode 的配置项 data_home：

toml

# ...
[storage]
data_home = "/data/greptimedb"
# ...

你可以使用以下的 shell 命令来设置环境变量，格式如下：

export GREPTIMEDB_DATANODE__STORAGE__DATA_HOME=/data/greptimedb

环境变量规则

每个环境变量应该有组件前缀，例如：
- GREPTIMEDB_FRONTEND
- GREPTIMEDB_METASRV
- GREPTIMEDB_DATANODE
- GREPTIMEDB_STANDALONE
我们使用双下划线 __ 作为分隔符。例如，上述的数据结构 storage.data_home 将被转换为 STORAGE__DATA_HOME。

环境变量也接受用逗号 , 分隔的列表，例如：

GREPTIMEDB_METASRV__META_CLIENT__METASRV_ADDRS=127.0.0.1:3001,127.0.0.1:3002,127.0.0.1:3003

配置 GreptimeDB

配置 GreptimeDB

命令行选项

全局选项

datanode 子命令选项

metasrv 子命令选项

frontend 子命令选项

standalone 子命令选项

配置文件

指定配置文件

常见配置

协议选项

节点选项

存储选项

自定义多存储引擎

对象存储缓存

WAL 选项

存储引擎选项

单机模式

分布式模式下的 Frontend

分布式模式下的 Datanode

Metasrv 配置

Logging 选项

环境变量配置

环境变量规则

分布式模式下的 `Frontend`

分布式模式下的 `Datanode`