原始网页:https://www.cockroachlabs.com/docs/stable/start-a-node.html


本小节将使用cockroach start命令,展示如何为新集群启动节点和添加节点到现有集群。更加全面的集群部署和初始化方法,可以查看手动部署教程。

NOTE: cockroach start命令通过Flags来定义节点范围内的配置,且在停止或重新启动节点之前无法更新配置。相反,某些群集范围的设置可以通过SQL语句定义,并且可以在集群启动后随时更新。详见集群设置

概要

# Start a single-node cluster:
cockroach start <flags, excluding --join>

# Start a multi-node cluster:
cockroach start <flags, including --join> &
cockroach init <flags>

# Add a node to a cluster:
cockroach start <flags, including --join>

# View help:
cockroach start --help

Flags

(Changed in v2.0) cockroach start命令支持通用型和日志相关两种类型的Flags。 除了--join以外的所有Flags,在节点启动时不会进行持久化操作,即在每次节点启动的时候都需要重新设置。关于--join Flag,推荐每次启动时重复配置,以便于在数据文件丢失时也能加入集群并进行恢复。

TIPS: 使用--joinFlag能够将新的个节点添加到已有的集群。

通用

Flag 简介
--advertise-host 节点使用的IP地址或hostname,供其他节点通过该地址进行通信。如果是hostname,则要求地址能被正常解析;如果是IP地址,则需要保证地址能被访问到。

该Flag需要配合--hostFlag使用,详见Networking
--attrs 显示节点性能的字符串,包括特定设备配置情况、CPU核心数量等。配置之间用逗号隔开,例如:--attrs=ram:64gb

该Flag影响数据冗余副本的散布情况,详见配置复制空间
--background 设置后台运行。

Note:--background适用场景为短时间的服务运行和测试环境。目前由于无法从当前终端完全分离,不建议在长时间的服务运行中使用,此时推荐使用服务管理器或是类似于daemon(8)的工具。
--cache 内存当中的缓存总大小,多个物理存储设备共享使用。Flag值可以为准确的内存大小值(单位为bytes),或是带小数点的十进制数值(转换为百分比数值),或是百分比值,例如:--cache=.25
--cache=25%
--cache=1000000000 ----> 1000000000 bytes
--cache=1GB ----> 1000000000 bytes
--cache=1GiB ----> 1073741824 bytes

Note:如果使用带%的格式,注意转义%保证能够正常识别,例如在某些配置文件当中%可能被识别为注解符,因此推荐使用带小数点的十进制数值。

(Changed in v1.1)
Default:128MiB

默认值的设置是基于本地部署集群的场景考虑,在实际生产环境中,推荐25%甚至更高,详见生产清单
--certs-dir 证书目录的路径,用于对安全模式部署的集群进行访问验证。

Default:${HOME}/.cockroach-certs/
--external-io-dir (New in v2.0)
使用本地节点目录或NFS驱动器执行备份和恢复操作时,使用本地文件访问路径作为前缀的外部IO文件夹路径。如果设置为disabled,则备份和恢复使用本地节点目录,NFS驱动被禁止。

Default: 第一个store配置的extern子目录

用户可以对extern目录进行文件符号连接,以达到不用重启节点就能够变更--extern-io-dir的目的。
--host 节点使用的IP地址或hostname,供其他节点和客户端通过该地址进行通信。

该Flag需要配合--advertise-host使用,详见Networking

Default: 使用节点机器的所有IP地址,并将规范主机名告知其他节点供节点之间通信使用。
--http-host 对外开放的Admin界面的IP地址或hostname。

Default:--host一致
--http-port 对外开放的Admin界面的端口。

Default: 8080
--insecure 以非安全模式启动集群。否则集群以安全模式启动,此时需要--certs-dir指定证书文件鲁姆路径。

Note the following risks: 集群对客户端是开放的,通过IP地址可以访问集群任意节点;任何非root用户能够不需要密码访问集群;包括root用户在内的所有用户能够读写集群当中的所有数据;集群节点间任何网络通讯都是非加密的,不需要任何验证。

Default:false
--join
-j
节点连接集群的地址。

(Changed in v1.1)
初始化时需要指定集群3-5个节点的地址和端口,然后执行cockroach init命令完成集群启动过程。

不指定该标签时,则启动的是一个单节点集群,此时不需要执行cockroach init命令。

当需要向已有集群添加新节点的时候,使用该flag指定集群3-5个节点的地址和端口。
--listening-url-file 节点成功启动的时候对于节点的SQL connection URL除了输出到标准输出以外,还将输出到指定的文件当中。适用于--port=0,即自动分配未使用的端口,此时方便识别节点的端口。
--locality 自定义的键值对序列,描述节点的位置信息,可以包括国家、地区、数据中心、机架等等。详见Locality
--max-disk-temp-storage (New in v1.1)
允许超过--max-sql-memory指定内存限制的查询额外使用的临时存储空间的最大硬盘空间大小,允许JOINS、排序和其他内存密集型SQL操作缓存中间结果。该Flag的值可以是百分数或是准确的值(以byte为单位),例如.2525%500GB1TB1TiB

Note: 如果使用带%的格式,注意转义%保证能够正常识别,例如在某些配置文件当中%可能被识别为注解符,因此推荐使用带小数点的十进制数值。此外,在使用%的情况下, 默认使用第一个配置的store。CockroachDB不会检查硬盘是否剩有该Flag值对应的空间大小,因此务必保证硬盘空间充足。

(New in v2.0)
这些临时文件将存储在--temp-dir对应文件夹当中。

Default:32GiB
--max-offset 一个集群允许的最大时间偏移值,若观测到的时间偏移超过该阈值,服务器将崩溃,以减少读取到不一致数据的可能性。而增加该值将增加故障恢复的时间以及基于不确定性读的重启的频率。

值得注意的是该值集群中的所有节点必须保持一致,且在rolling update时不允许改变。更新该值需要停止集群中的所有节点,并在重启集群时统一指定新值。

Default: 500ms
--max-sql-memory SQL查询需要缓存的临时数据所能使用的最大内存空间。包括准备好的查询和在查询执行期间中间数据行。该Flag的值可以是百分数或是准确的值(以byte为单位),例如:
--max-sql-memory=.25
--max-sql-memory=25%
--max-sql-memory=10000000000 ----> 1000000000 bytes
--max-sql-memory=1GB ----> 1000000000 bytes
--max-sql-memory=1GiB ----> 1073741824 bytes

(New in v2.0)
这些临时文件将存储在--temp-dir对应文件夹当中。

Note: 如果使用带%的格式,注意转义%保证能够正常识别,例如在某些配置文件当中%可能被识别为注解符,因此推荐使用带小数点的十进制数值。

(Changed in v1.1)
Default: 128MiB
--pid-file 节点启动时将进程ID输出到指定的文件当中,若不指定该Flag,则不输出进程ID内容。
--port
-p
节点通信或是客户端通信所使用的端口。若--port=0,则使用系统自动配置的端口。

Env Variable: COCKROACH_PORT
Default: 26257
--store
-s
存储数据库数据的存储设备路径,同时可以指定设备属性和空间大小。若使用多设备存储,则使用方式如下:
--store=/mnt/ssd01 --store=/mnt/ssd02

详见Store
--temp-dir (New in v2.0) 节点临时数据存储位置,用户可以在节点启动信息有相关内容输出。

Default: 第一个配置的store的子目录。

Locality

--locality值为用户自定义的键值对序列,描述节点的位置信息,可以包括国家、地区、数据中心、机架等。键值对序列里键值顺序需要由大范围到小范围,重要程度递减,且集群中所有节点范围层级结构是一致的。推荐用户使用更多的层级结构。

示例

# Locality flag for nodes in US East datacenter:
--locality=region=us,datacenter=us-east

# Locality flag for nodes in US Central datacenter:
--locality=region=us,datacenter=us-central

# Locality flag for nodes in US West datacenter:
--locality=region=us,datacenter=us-west

Store

--store支持以下配置项,配置项之间通过逗号分隔,因此用户需要在配置项的值当中避免逗号的使用。

NOTE: 在生产部署环境当中不推荐使用内存存储。

配置项 简介
type 若是内存存储,则值为mempath配置项值为空。其他情况该值应为空。
path 存储设备路径,例如:--store=path=/mnt/ssd01,size=20GB

若用户不需要设置attrsize,则path=可以省略,即:
--store=path=/mmt/ssd01省略为--store=/mnt/ssd01

Default:cockroach-data
attrs 用户自定义字符串,指定硬盘类型或空间大小,逗号分隔。该配置影响数据冗余的位置选择,详见配置复制空间

在大多数情况下,节点级--locality--attrs配置优于存储级配置,但此字段还可用于匹配存储设备的能力与单个数据库(或表)的需求。例如,OLTP数据库倾向于在固态设备上为其表分配空间,而时间序列数据倾向于成本更便宜的磁盘设备。该配置项值包括设备是闪存(ssd)还是磁盘(hdd),以及磁盘转速和其他规格参数等,例如:
--store=path=/mnt/hda1,attrs=hdd:7200rpm
size 存储设备允许节点使用的最大空间大小。达到此阈值时,CockroachDB尝试将数据重新散布到具有可用容量的其他节点。当其他节点都使用完可用容量时,该节点将无视该限制地继续使用更多空间。一旦集群有其他新的可用空间,则该节点超出阈值的数据将转移到新的可用空间上。

该Flag的值可以是基于硬盘大小的百分数或是准确的值(以byte为单位),例如:
--store=path=/mnt/ssd01,size=10000000000 ----> 10000000000 bytes
--store=path=/mnt/ssd01,size=20GB ----> 20000000000 bytes
--store=path=/mnt/ssd01,size=20GiB ----> 21474836480 bytes
--store=path=/mnt/ssd01,size=0.02TiB ----> 21474836480 bytes
--store=path=/mnt/ssd01,size=20% ----> 20% of available space
--store=path=/mnt/ssd01,size=0.2 ----> 20% of available space
--store=path=/mnt/ssd01,size=.2 ----> 20% of available space

Default: 100%

若是内存存储,则该值是基于内存大小的百分数或是准确的值(以byte为单位),例如:
--store=type=mem,size=20GB
--store=type=mem,size=90%

Note: 如果使用带%的格式,注意转义%保证能够正常识别,例如在某些配置文件当中%可能被识别为注解符,因此推荐使用带小数点的十进制数值。

日志

默认情况下,cockroach start将所有信息打印到日志文件当中,不向stderr输出任何内容。

Flag 简介
--log-dir 启动日志功能,并在指定的目录下记录日志。--log-dir配置为空字符串(--log-dir="")时,则关闭日志功能。
--log-dir-max-size 所有日志文件大小达到一定阈值以后,CockroachDB将删除最老的日志。

Default:100MiB
--log-file-max-size 单个日志文件大小达到一定阈值以后,CockroachDB将开启新的日志文件并输出日志到新文件当中。

Default:10MiB
--log-file-verbosity 只有指定严重级别及以上的日志才输出到日志文件当中。

Default:INFO
--logtostderr 将指定严重级别及以上的日志输出到stderr,例如--logtostderr=ERROR

若使用该Flag时不指定配置值(cockroach start --logtostderr),则CockroachDB将所有严重级别的日志输出到stderr

若配置为--logtostderr=NONE,则禁止日志输出到stderr
--no-color 是否对stderr着色,值为truefalse
值为false时,输出到stderr将基于自身严重级别进行着色。

Default: false
--sql-audit-dir (New in v2.0)
该Flag的值非空时,在指定文件夹中记录SQL审计日志。默认情况下,SQL审计日志与其他日志一样输出到同一个文件夹中。详见SQL审计日志

NOTE: 默认情况下,cockroach start命令日志相关配置为--log-dir=<first store dir>/logs --logtostderr=NONE,此时CockroachDB将所有日志信息输出到日志文件当中,不输出任何内容到stderr

标准输出

运行cockroach start,启动CockroahDB后将输出如下内容:

CockroachDB node starting at 2018-08-13 15:10:52.34274101 +0000 UTC
build:               CCL v2.0.5 @ 2018/08/13 14:48:26 (go1.10)
admin:               http://ROACHs-MBP:8080
sql:                 postgresql://root@ROACHs-MBP:26257?sslmode=disable
logs:                node1/logs
temp dir:            /node1/cockroach-temp430873933
external I/O path:   /node1/extern
attrs:               ram:64gb
locality:            datacenter=us-east1
store[0]:            path=node1,attrs=ssd
status:              initialized new cluster
clusterID:           7b9329d0-580d-4035-8319-53ba8b74b213
nodeID:              1

TIP: 以上内容也将以INFO等级输出到/log日志文件夹中。

以下是上述每一行内容的介绍:

内容项 简介
build 正在运行的CockroachDB版本
admin Admin界面的URL地址
sql 客户端SQL connection URL
logs 包含Debug日志数据的文件夹
temp dir 节点临时存储空间路径
external I/O path 使用本地节点目录或NFS驱动器执行备份恢复操作时,使用本地文件访问路径作为前缀的外部IO文件夹路径。
attrs 输出节点启动时若指定的--attrsFlag的内容,以便配置复制空间
locality 输出节点启动时若指定的--localityFlag的内容,以便配置复制空间
store[n] 按顺序输出节点启动时指定的--storeFlag内多个存储设备的信息。
status 可能值:
initialized new cluster集群中第一次创建节点;
initialized new node, joined pre-existing cluster节点第一次添加到已有集群;
restarted pre-existing node节点重新添加到已有集群;
clusterID 集群的ID

启动节点时若该ID与已有集群ID不一致,则创建新的集群。该问题可能由节点数据文件的数据异常导致,详见troubleshooting
nodeID 节点的ID

示例

启动单节点集群

指定cockroach start命令,设置--join为集群的3-5个节点。

非安全模式

cockroach start \
--insecure \
--host=<node1 address> \
--cache=.25 \
--max-sql-memory=.25

安全模式

cockroach start \
--certs-dir=certs \
--host=<node1 address> \
--cache=.25 \
--max-sql-memory=.25

启动多节点集群

非安全模式

指定cockroach start命令,设置--join为集群的3-5个节点。

cockroach start \
--insecure \
--host=<node1 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

cockroach start \
--insecure \
--host=<node2 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

cockroach start \
--insecure \
--host=<node3 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

随后在任意节点上执行cockroach init命令初始化集群。

cockroach init \
--insecure \
--host=<address of any node>

安全模式

指定cockroach start命令,设置--join为集群的3-5个节点。

cockroach start \
--certs-dir=certs \
--host=<node1 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

cockroach start \
--certs-dir=certs \
--host=<node2 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

cockroach start \
--certs-dir=certs \
--host=<node3 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

随后在任意节点上执行cockroach init命令初始化集群。

cockroach init \
--certs-dir=certs \
--host=<address of any node>

添加新节点到现有集群

指定cockroach start命令,设置--join为集群的3-5个节点。

非安全模式

cockroach start \
--insecure \
--host=<node4 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25

安全模式

cockroach start \
--certs-dir=certs \
--host=<node4 address> \
--join=<node1 address>:26257,<node2 address>:26257,<node3 address>:26257 \
--cache=.25 \
--max-sql-memory=.25