CockroachDB 系统部署和应用

Question

一、概述

cockroach (蟑螂) 是一个新兴的分布式 NewSQL 数据库系统。和传统关系性 Relation、非关系型 NoSQL、对象数据库和类似的竞争对手相比，它具备一些自己的特点：

• 几乎完全的点对点复制网络，理想的可扩展性和高可用性
• 更好的事务支持，更接近传统关系数据库
• SQL API 几乎可以直接支持传统 Postgres 客户端应用和数据操作方法
• 单一的可执行软件，全参数化配置，方便操作、移植，特别是对云计算环境的支持
• 使用 go 语言开发，性能和资源占用比较有优势
• 提供了基于 Web 的管理和监控程序和丰富的管理功能

cockroachdb 的官方网站在：https://www.cockroachlabs.com/

由于 cockroach 软件应用的系统性，在正式部署前，应当进行良好的准备和规划，能够更好的帮助后续的系统部署和运行。

这里先强调几点经验之谈：

• 要特别注意时间的同步性
• 要特别节点网络相互的连接
• 要特别注意某些节点的异常工作状态，及时排除和处理，因为它会影响到整个群集

二、系统规划和基础配置

规划和准备

系统规划的内容包括准备系统中所有节点计算机的 IP 地址，网络设置，主机名，DNS 和 NTP 服务配置，硬件配置和程序、文件、数据存放地址，账号设置等相关内容，为后续的运维管理提供方便。

建议的最佳实践

• 使用 NTP 服务来保证时间同步
• 使用 DNS 来管理主机名和 IP 地址，提高管理效率
• 使用独立的 cockroach 账号，单一工作目录，方便管理和移植，并和系统登录和管理的账户分离
• 编写好的启动脚本，而非临时的启动参数，保证一致性
• 在部署阶段，严密监控节点工作状态，及时处理异常情况

主管理服务器

下列配置中我们使用 192.168.9.30 这台主机作为主管理服务器，在此服务器上安装和配置 DNS 和 NTP 服务。并作为文件管理和中转服务，要求此计算机能够访问互联网。

时间服务

基于 Cockroach 程序角色协商的实现原理，时间同步在 Cockroach 中的作用极为重要，是首要需要考虑的因素。虽然 Cockroach 精心设计的协调机制，使系统不需要使用向原子钟和 GPS 授时服务这样的昂贵技术，但也需要使用 Linux 系统内置的 NTP 时间同步服务和机制，来使系统内的主机时间误差控制在 500ms 以内来保证系统的正常工作。一般情况下 NTP 可以提供的时间精度在 100ms 以下。

在实际的运行中，这一点非常重要，很多和节点加入群集、节点故障有关的问题，都和这一点相关。

本系统的建议方案如下：在网络内建立一个 NTP 服务器，此服务器和互联网公共 NTP 服务同步；其他主机使用此 NTP 服务器进行校时，从而保证所有主机的时间同步。

安装和配置 NTP 服务的过程如下（略)

在主机使用 NTP 服务的方式如下：

sudo crontab -e 
*/5 * * * * /usr/sbin/ntpdate 192.168.9.30

DNS 服务器

强烈建立系统准备一套 DNS 服务系统，作为整个系统的域名管理系统，这样只需要在 DNS 系统上进行域名配置，就为整个系统提供域名映射服务。在各节点机上只需要将 DNS 服务器只想这台服务器，就可以使用域名服务。
然后，就可以在所有节点配置信息中使用主机名而非 IP 地址来进行配置和管理，在节点数量较多时，提供了极大的方便性。

我们使用 Linux 内置的 bind9 软件实现 DNS 服务：

// 安装 bind 
sudo apt install bind9 

// 启动 DNS 服务和加载配置信息
sudo service bind start | reload

备份和恢复服务

作为一个为云计算设计的数据库系统，cockroach 的数据备份和恢复，以及导入导出，并不直接使用本地文件系统，而是使用如 S3 这种存储服务。如果本地部署的话，需要自己搭建类似的系统。cockroach http 网络文件系统基于 webdav 技术，所以可以使用 nginx 来进行实现，方法如下：

// 安装完全版本的 nginx
sudo apt install nginx-full

// add to nginx.conf server 段
server {
      listen 8070;
      location / {
      dav_methods  PUT DELETE;
      root /opt/cockroach/backup;
      sendfile           on;
      sendfile_max_chunk 1m;

      client_max_body_size 0;
      }
}

// 使用导出命令   
export into csv 'http://192.168.9.30:8070/' from table uldata.pt_student;

账号和主工作目录

建议为 cockroach 服务专门建立一个账号 cockroach 来运行程序，而不使用 root 和其他 sudo 账号。此账号应设置为不能远程登录，也没有密码，使用 sudo 来进行切换。

为方便管理，可以为系统维护再创建一个管理员账号，此处 culsc。

建议使用独立的 cockroach 文件夹作为工作文件夹，典型的配置和内容如下。

// 创建账号
sudo useradd cockroach

// 修改账号主目录和 shell
sudo nano /etc/passwd

// 主工作文件夹
sudo mkdir /opt/cockroach
// 证书文件夹
sudo mkdir /opt/cockroach/certs 

// 数据文件夹
sudo mkdir /opt/cockroach/certs 

// 在程序文件，证书文件都准备好的情况下，统一修改文件属主
sudo chown cockroach:cockroach /opt/cockroach -R 

// 切换到 screen 可以保留当前会话状态
screen -S cock 
// control a+d 可以临时退出 screen -r 恢复会话
screen -r cock

// 切换到 cockroach 账号（不需要 cockroach 密码)
sudo su - cockroach

典型的 cockroach 工作文件夹的内容如下

• cockroach 主程序文件，约 210m
• lib 程序 so 库，来自解压文件
• start.sh 启动脚本
• datan 数据文件夹
• certsn 证书文件夹

本文件夹和子文件夹的属主均为 cockroach.

节点主机

主机名的命名按照 n+ip 的规则，子域名为 ckdb.ulsc.local，主机名按照 IP 地址分别命名为 n.ckdb.ulsc.local。 这些主机名需要在 DNS 服务器中进行配置。
这样配置可以使用 cockroach 创建的通配符证书，简化部署和管理。

主机的 IP 可以动态的设置，并可以设置多个：

// 设置 IP 地址
ip addr add 192.168.9.32/24 dev eth0

// 设置 DNS
sudo nano /etc/resolve.conf
nameserver 192.168.9.30

还有一种方式，可以保护 DHCP 来修改 DNS 配置，方式是使用 chattr 命令，修改属性保护 resovled.conf 文件，-i 去除属性设置。

  chattr +i /etc/resolv.conf

如果节点主机使用了 DHCP 来配置其他的 IP 地址，则其 DHCP 的 DNS 会覆盖 resolve.conf 中的内容，这种情况下需要修改 dhcpclient

sudo nano /etc/dhcp/dhcpclient.conf

// 增加以下预制内容
prepend domain-name-servers 192.168.9.30,61.139.2.69;
prepend domain-name ulsc.local
prepend domain-search ulsc.local

// 在 request 段中找到并删除以上项目

所使用的 Linux 发行版本不限, 但尽可能一致，推荐使用 debian9 和 centos7 版本，有些版本的 linux 不能直接运行 go 编译程序（如 alpine)。

操作系统设置修改

cockroachdb 的运行，对操作系统的设置有一定要求，特别是文件句柄数量的限制，可能需要修改，详见部署文件。

三、系统部署

建议在管理服务器上进行软件包的下载和证书准备，并分发到各个节点主机之上。

程序文件

从 cockroach 的官方网站可以下载最新稳定版本的程序的压缩包文件，最新版本为 20.2.4。下载地址为：

wget -qO-   https://binaries.cockroachdb.com/cockroach-v20.2.4.linux-amd64.tgz   | tar xvz

软件包有 90M。解压后可以得到一个 200M 的可执行文件和一个 lib 目录。单一的可执行文件是 cockroachdb 的特点，它再不需要额外的依赖，直接通过命令行和参数就可以执行，非常方便部署和管理。软件包中的 lib 其实并不是必须的，它是一个地理空间功能的扩展，如果不需要相关的功能，完全可以不要 。

证书管理

我们使用安全方式创建群集，需要先进行相关证书的创建和管理。

所有证书管理操作，都在管理主机上完成。证书文件包括群集证书、节点证书和客户证书

• 群集证书
  如果是完全的新建群集，需要先创建群集证书。

cd /opt/cockroach 
./cockroach cert create-ca \
--certs-dir=certs \
--ca-key=certs/ca.key

此处为了方便管理，将 cert 和 key 文件放在同一个文件夹中。理论上，需要将 cert 分配给所有节点主机。

其实不建议使用 cockroach 建立主证书和密钥，而可以使用 openssl 来创建带有证书颁发机构信息的主证书和密钥，这样搭建的 Admin UI 才可以使用没有警告信息的 HTTPS 连接。

• 节点证书
  节点证书是各个节点之间通讯安全的保证，所有节点证书都基于群集证书创建。

基于群集证书和各节点主机名称，可以创建各节点的证书和 key。节点证书的创建支持通配符，结合 DNS 的子域名和主机名，可以简化节点证书的管理。

./cockroach cert create-node \
*.ckdb.ulsc.local \
--certs-dir=certs \
--ca-key=certs/ca.key

mv certs/node.* certs/.

命令执行后，会在 certs 文件夹中，生成 node.crt 和 node.key 文件,所有子域名为 ckdb.ulsc.local 的节点主机都可以使用。

配置完成后，所有节点实例的 certs 文件夹中，一般有三个文件，包括 ca.crt，node.crt 和 node.key 文件。

• 客户端证书
  客户端证书，用于客户端软件和应用连接群集使用。

cockroach cert create-client \
root \
--certs-dir=certs \
--ca-key=certs/ca.key

生成的客户端证书的形式为 client-name.key 和 client-name.crt。

部署在个节点程序证书文件夹中的证书 key，需要将其设置为属主只读权限，否则节点启动或连接时，会提示权限错误。

sudo chmod 400 /opt/cockroach/certs/*.key 

启动第一个节点

逻辑上而言，cockroach 的所有节点的地位都是相同的，但基于方便，我们会将 node1 作为初始配置节点，因为基于这个节点，有一些额外的工作，如初始化群集和证书管理等等。

为了方便使用，我们在/opt/cockroach 目录下，创建 start1.sh 文件作为节点 1 的启动文件，内容如下：

nano /opt/cockroach/start.sh

#!/bin/bash
./cockroach start \
--cache=0.3 
--pid-file =ckdb1.pid
--certs-dir=certs1 \
--store=data1 \
--listen-addr=n1.ckdb.ulsc.local:5434 \
--http-addr=n1.ckdb.ulsc.local:8080 \
--join=n1.ckdb.ulsc.local:5434,n5.ckdb.ulsc.local:5434 \
--background

chmod +x start.sh

这些参数项目的含义分别如下：

• cache 缓存比例，默认为 0.25，如果是独立的 cockroach 服务器，可以适当增加，提升查询性能
• pid-file pid 文件，默认在当前文件夹下，可以使用 kill cat cddb1.pid 来中止服务程序
• certs_dir 证书文件夹，启动节点通常需要包括 ca.crt,node.crt 和 node.key 三个文件，node 文件和侦听地址匹配，但可以支持通配符
• store 数据文件夹
• listen-addr 节点间数据传输和数据服务侦听地址和端口，默认为 localhost:26257
• http-addr 节点 adminui 服务地址和端口，默认为 localhost:8080
• join 需要加入的群集某些节点的地址和端口
• background 可以作为服务在后台执行，通常如果基于调试的需求可以去除此项目在控制台执行

启动节点前，最好先同步一下时间，然后切换到 cockroach 执行启动脚本

sudo ntpdata 192.168.9.30 
screen -S cockroach
sudo su - cockroach
cd /opt/cockroach
/start.sh

此命令可以指定证书文件夹（文件夹中必须包含 ca.crt, 本节点或通配域名的 node.cert 和 node.key 文件)、数据文件夹、侦听 IP 和端口、http 服务端口、群集入口（可以设置多个) 和是否后端运行等。

全新创建群集时，运行以上命令，虽然节点可以启动，但其实群集并没有初始化，需要使用以下命令进行初始化：

./cockroach init --certs-dir=certs --host=n1.ckdb.ulsc.local:5434

如果一切正常，会看到群集已经初始化的信息。

启动时，经常可以遇到证书的错误，除了正确的证书文件位置外，还需要将所有的.key 文件的权限修改为 0400(属主只读)，并确认相关文件的属主均为 cockroach。

连接群集和创建管理账号

群集初始化之后，就可以连接群集进行相关的管理工作了。

在 node1 上，可以直接使用 root 账号证书连接群集:

./cockroach sql --certs-dir=certs --host=cknode1.ulsc.local:26257

连接群集后，可以考虑创建一个额外的管理员账号和工作数据库，并进行赋权：

CREATE USER dbadmin WITH PASSWORD 'admin123';
GRANT admin TO dbadmin WITH ADMIN OPTION;
SHOW GRANTS FOR dbadmin;
CREATE database uldata;
GRANT ALL ON DATABASE uldata TO dbadmin;

初始化群集后，创建管理账号后，可以使用浏览器访问管理界面，并使用管理员账号进行登录。

https://n1.ckdb.ulsc.local:8080  

启动其他节点

确认群集已经创建，并且能够正常的访问和管理，就可以考虑启动其他节点并加入群集了。

启动其他节点，同样可以创建节点启动脚本，修改为对应的参数就可以了。特别要注意区分数据文件夹、证书文件夹、侦听地址和端口。

启动前的标准检查项目包括:

• 节点的 IP 地址和域名是否配置正确
• 是否能连接其他节点主机
• start.sh 的内容，是否匹配本节点设置
• 程序文件、data 目录和 certs 目录是否设置正确和完备
• 证书文件是否就绪，当前节点 IP 和域名是否配置正确
• 节点防火墙端口是否打开（5434 和 8080）

如果配置得当，就可以执行 start.sh 脚本启动了。程序启动后，节点会基于--join 中的设置，连接到群集，并加入群集了。可以在 DBConsole 中看到新加入的节点和状态。

启动后的检查项目包括：

• netstat -lpnt 查看是否正确监听
• ps aux | grep cock 查看程序进程是否存在和正常运行
• Admin UI 节点加入信息和状态
• 查看 cockroach 运行日志，方式为 tail /opt/cockroach/data/logs/cockroach.log -f

可以在一个主机上，运行多个实例，使用不同的 IP、端口、证书和 Data 文件夹进行区分。

常见故障

• 服务启动时，提示证书权限错误，修改 key 文件为属主只读权限

   chmod 400 *.key
  

• 节点不能启动，而且没有明确的错误信息，可能是由于服务器时间不同步造成
  启动后，可以使用 ps 或者 netstat 查看程序运行状态，可能会看到程序没有正常启动的状态。
• 服务可以启动，但数据不能同步，可能是节点双向通讯故障造成，如果使用主机名成作为节点名称，要保证 dns 或者 hosts 解析正常

停止节点

cockroach 没有明确的停止节点的方式，可以使用 ps aux | grep cock 找到正在运行的进程编号 pid，并使用 kill pid 命令发送进程终止信号，后续程序会进行清理和停止操作。如果操作正常，会提示正常停止的信息。

停止节点后，可以再次使用 ps 和 netstat 命令检查进程和监听正确停止。

退役节点

cockroach 没有删除节点的操作，而使用“退役 decommission”的说法。
如果要退役一个活动节点，需要先正常停止节点；对于已经失效的节点，可以直接退役。退役节点使用 cockroach node decommission 命令：

// 查看节点状态并获取需要退役节点的 ID
./cockroach node status --all --host n30.ckdb.ulsc.local:5434 --certs-dir certs30

// 使节点退役
./cockroach node decommission 27 --host n30.ckdb.ulsc.local:5434 --certs-dir certs30

节点退役命令正常执行，可以看到处理的结果，节点状态为 decommissioning 或者 decommissioned；在 AdminUI 中也会出现在退役节点列表中。有时候也会出现一些异常的信息记录，导致退役命令没有处理结果，需要过一段时间，重新检查退役状态。

四、系统管理和使用

负载均衡

cockroachlib 建议使用 haproxy 作为负载均衡的标准 NLB 方案。虽然提供了相关命令用于生成 haproxy 配置，但不建议使用，可以参考下面的内容和配置：

sudo nano /etc/haproxy/haproxy.cfg

maxconn 4096

defaults
mode  tcp     # Timeout values should be configured for your specific use.
# See:   https://cbonte.github.io/haproxy-dconv/1.8/configuration.html#4-timeout%20connect  
timeout connect     10s
timeout client      1m
timeout server      1m     # TCP keep-alive on client side. Server already enables them.     option              clitcpka

listen stats    #定义监控页面
bind  192.168.9.30:1080       #绑定端口 1080
mode  http
stats refresh 30s             #每 30 秒更新监控数据
stats uri /stats              #访问监控页面的 uri
stats realm HAProxy\ Stats    #监控页面的认证提示
stats auth admin:ulsc2020    #监控页面的用户名和密码

listen psql
bind 192.168.9.30:5432
mode tcp
balance roundrobin

option httpchk GET /health?ready=1

server ck23  n23.ckdb.ulsc.local:5434 check port 8000
server ck39  n39.ckdb.ulsc.local:5434 check port 8000
...

类似的，也可以建立 AdminUI 和 HTTP API 的负载均衡设置。可能包括的项目和建议的设置为：

• sql 端口为 5432 (原始为 5434)
• haproxy 状态 1080
• AdminUI 8010(原始为 8080)
• API 8000(原始为 8001)

数据库连接

原生的 cockroach 应用程序包含了连接数据库的模块（cockroach sql），可以使用作为原生的客户端应用。该命令如下：

./cockroach sql \
--certs-dir=certs30 \
--host=n30.ckdb.ulsc.local:5434 \
--user dulsc \
--database uldata

连接时可以直接指定连接的用户和数据库，如果没有设置，将会使用 root 和 defaultdb。

逻辑上而言，cockroach 提供了 postgres 兼容性，所有兼容 PG 的客户端软件和工具都可以连接 crdb。我们通常使用 dbeaver 软件来作为标准的 CRDB 管理工具。连接方式和 PG 无异，要主要在选择数据库时，可以有 cockroachdb 的数据库连接选项。另外需要可能会有证书方面的错误提示，需要手动设置 TLS 版本。详见故障排查章节。

在程序中，提供了相对比较丰富的客户端连接库，包括 JAVA 平台的 jdbc，和 node 平台的 PG。在 node 中使用 crdb 连接稍微麻烦一点，因为它默认需要使用证书进行连接，需要准备和配置证书，详见相关开发章节。

现在可以使用两种

cockroach 程序命令

使用 cockroach 程序，可以对群集和节点进行相关的管理，常规的指令包括:

// 查看群集节点和状态
./cockroach node status --certs-dir=certs30 --host=n30.ckdb.ulsc.local:5434

// 节点退役
./cockroach node decommission 19 --certs-dir=certs30 --host=n30.ckdb.ulsc.local:5434  

数据备份

cockroach 在 sql 环境中提供了数据备份的指令 backup，可以将系统、数据库和表备份到 S3 或者类似的存储系统中。需要注意的是 backup 不支撑本地原生文件系统的直接备份，如果在本地群集，需要部署支持 HTTP WebDev 协议的网络文件服务系统，可以使用 nginx 实现。

系统备份的命令如下：

//已经备好 webdev 服务
backup pt_guardian to 'http://n30.ckdb.ulsc.local:8070/bk_guardian/'

应用开发

使用 Cockroach 进行应用开发，和使用 postgres 进行应用开发的区别不大，这里以 nodejs 为例，阐述 cockroach 应用开发的过程和要点。

// 安装 pg
npm install pg;


// pg database 2
require("./lib/db_pg4_b")({
// secret: process.env.PDB_SECRET,
connectionString: "postgres://user:passwd@ckdb.ulsc.local:5434/uldata" ,
ssl: {
      ca   : fs.readFileSync(__dirname + '/certs/ca.crt').toString(),
      key  : fs.readFileSync(__dirname + '/certs/client.dulsc.key').toString(),
      cert : fs.readFileSync(__dirname + '/certs/client.dulsc.crt').toString()
}
});

// 执行查询
qr = db.query('select name from student where stuid = $1',[param.stuid]);

已知和 PG 的差异

• PG 可以使用 _ 转义符， CK 不行

在 sy_ids 表中，pg 中使用_112304 这种形式的 uid，来表示该 iid 未被使用，可以用 where uid like '\_%' (用了转义符) 进行查询，但这个查询在 CK 中失效。

解决方式，使用~作为占位符，就可以使用 like '~%' 来查询可用的 id

• 数组类型的字段
  在 CK 中，不能直接使用数组索引来给数组元素进行赋值， 如 update set scount[1] = 2 ；

解决方式，重新构造数组，给整个数组赋值， 如 update set scount = array[2,scount[2]];

• 中文字符串截取
  在 CRDB 中，对于中文字符串，不能像 PG 中一样直接截取中文的子字符串。思路是 CRDB 可能使用 UTF8 编码中文字符串，每个中文字符占用三个字节，可以使用 3 的倍数长度来处理中文字符。

例如：

// 查询中文单姓人数最多的姓和人数
select substr(xm,1,3), count(*) from pt_student group by 1 order by 2 desc limit 20 ;

注意，这个情况的发生视情况和场景而定，并不一定普遍适合。可能要区分从数据库中取值和从变量中取值的情况。

• 修改表定义
  CRDB 可以像 PG 一样修改表定义，但可能由于底层实现方式的不同，在一个很大的表中，修改列定义，需要花比 PG 更多的时间。 比如有时在一个 2000 万条记录的表中，增加一个字段，可能需要 3 个小时的时间。但也可能很快，只需要几秒钟，尚不清楚造成这一差异的原因。所以，对于 CRDB 的数据设计预先应该有很好的规划，尽量减少数据定义的调整。

CRDB 中，修改表定义，最好一个一个执行，具体会体现在任务当中，其执行进度和状态可以在 AdminUI 中看到。

CRDB 中修改表的命令，基本和 PG 相同：

ALTER TABLE pt_guardian ADD utime INT4[]  default '{0,0}';

中文字符串截取

五、故障排查和可能和存在的问题

标准检查条目－命令行

由于 AdminUI 有可能无法正常工作，所以执行标准检查时，首先使用命令行程序来进行系统检查，通常的检查项目和操作如下：

• 操作系统常规检查

// 当前时间
date

// 当前网络
ip addr
netstat -lpnt

// 当前内存使用
top
free -m

// 当前磁盘使用
df -h 
sudo du -h -d 1 /opt/cockroach/data30 

// 当前相关进程
ps aux | grep cock

• 网络和 DNS 配置

连接任意节点 SSH，使用 IP 地址和域名进行 ping 操作

ping 192.168.9.30
ping n30.ckdb.ulsc.local

• 节点状态

// 登录任意节点 ssh console，可以使用 cockroach node 命令检查所有节点状态

sudo su - cockroach
./cockroach node status  --certs-dir=certs30 --host=n30.ckdb.ulsc.local:5434

确认所有节点的配置信息是正常的，并且确认可用性和存活性。

• 如果怀疑某个节点有故障，可以登录对应的节点主机检查程序运行状态

// 程序是否运行
sudo su - cockroach
ps aux | grep cock

// 网络侦听是否正常
netstat -lpnt

• 日志项目检查
  cockroachdb 的日志，位于 data／logs 下，可以使用以下命令来检查当前节点和 store 实例的运行状态和问题。默认的 cockroach.log 为当前日志项目的软连接，历史记录可以查看对应的历史日志文件项目

// 查看日志
cat data30/logs/cockroach.log | more

// 实时监控
tail data30/logs/cockroach.log -f

• SQL 连接和执行正常

// 使用 cockroach sql 命令连接数据库和节点
./cockroach sql --certs-dir=certs30 --host=n30.ckdb.ulsc.local:5434 --user dulsc --database uldata

// 执行查询
show tables;

// 查询一些系统状态
show transactions;
show sessions;
SELECT * FROM crdb_internal.cluster_transactions;

标准检查项目-AdminUI

如果能够正常使用 AdminUI，建议遵循以下检查次序和项目

• 概览－确认容量的使用在合理范围，节点状态均为存活，无正常复制特别是不可用的范围
• 概览－在节点列表中，确认所有都可用并存活，容量和内存使用在合理范围内，副本分布比较均匀
• 数据库－能正常显示数据表和，相关参数正常合理
• 事务－事务列表中的操作正常合理，无挂起或者特别慢操作的语句
• 语句－查看当前无异常执行的语句
• 网络－确认所有节点间通信的网络延迟在正常合理范围
• 高级－问题区域，确认没有问题区域、无问题 Raft、所有问题项目数量为 0
• 高级－数据分布，确认所有节点和数据分布比较合理，没有异常

可能遇到的常见问题包括：

节点不能加入群集

节点不能正常加入群集，可能的原因和处理方式包括：

• 检查 cockroach 日志
• 网络连接要保证节点机和群集之间能正常访问，包括端口开启
• 时间同步 要保证各节点时间一致，误差在 500ms 以内

节点能够加入，但工作不正常

一般体现为可以看到节点，但节点的副本数量为 0.

可能的原因是由于其它节点不能正常访问本机节点进行操作，需要检查网络连接和防火墙，或者需要等待一段时间。

加入新节点影响 AdminUI

如果新节点加入了群集，但由于各种原因不能正常工作时，可能会影响到 AdminUI 的使用。 具体的表现可能包括：

• admin ui 不能登录，提示用户账号错误或者超时
• admin ui 可以登录，但不能正常显示节点列表
• 前端浏览器错误可能包括 404 401 504 500 等等

这种情况非常麻烦，通常是由于有问题或配置错误的节点加入到群集导致。

处理方式可能包括逐一检查所有活动节点，查看日志中是否有尝试连接失效节点的信息，尝试关闭和重新启动节点。重启节点最好按照较好的流程，等待关闭确认信息，然后等待几分钟，区域复制完成后，再启动节点。关闭和重启节点，一次只能操作一个节点，避免数据复制紊乱。

无法清除无效的节点

由于各种原因，节点失效后，尝试清除节点，但无法看到正常的处理结果。

cockroach 没有删除节点的说法，一般的做法是让节点退役。一般使用如下命令：

./cockroach node decommission 13 --certs-dir=certs30 --host=n30.ckdb.ulsc.local:5434

后来发现，经过较长时间后，虽然命令没有结束，但取消后，重新使用 node status 检查，已经清除了 decommission 项目。

滚动升级

cockroach 声称能够进行滚动升级，但经过实验和测试的情况不理想，很容易造成节点和群集故障，所以要非常小心。

滚动升级的步骤如下：

• 检查所有节点均正常工作，无正在复制的副本
• 在每个 locality 使用新版本，增加一个新节点，等待系统状态稳定
• 尝试关闭 locality 的一个旧版本节点，等待正常关闭，并副本平衡
• 在关闭的旧节点替换为新程序文件，数据目录不改变，检查参数无误后，启动节点，等待平衡
• 依次关闭和升级 locality 所有旧节点
• 重复上述次序，依次处理所有 locality 的所有节点

要点在于，在同一时间，只进行一个节点的升级，同时避免其它可能干扰这一过程的操作。

DNS 配置失效

如果使用了 DHCP，当 IP 地址重新获取和分配时，DNS 网络设置会被重置，这会影响到正常的节点间通信。除了/etc/resolve.conf 内容之外，可以考虑修改/etc/dhcp/dhcpclient.conf 中的内容，预设 dns-servers 内容，这一操作前面节点主机内容章节已有所阐述。

如何检查和排除锁定的查询

使用 show queries 和 show sessions 命令，可以查看当前正在执行的查询，和当前的会话。

使用 cancel query id 和 cancel session id 命令，可以中止当前执行的查询和会话。

No Raft Leader

在 AdminUI-Advanced Debug- Problem Rangers 页面，有 No Raft Leader 项目。不知道是否影响系统正常运行。

除 root 账号外，其他的数据库用户账号无法连接

可以使用 cockroach sql 的 root 账号连接，但无法使用标准数据库客户端和普通用户账号连接。错误信息为：

ERROR: internal error while retrieving user account。

无法使用 Dbeaver 软件连接

默认情况下，使用 dbeaver 软件无法连接到 cockroachdb，提示证书和 SSL 相关的错误信息，这是由于默认的 TLS 版本配置方面的错误引起的。修正的方式为修改

dbeaver.ini 文件，增加一下以下内容：

-Djdk.tls.client.protocols=TLSv1.2

可以创建表，但不能查询和插入数据

不知道什么原因，crdb 可以创建表和表结构，但不能插入数据，表现为插入操作挂起（很长时间也没有处理），同样的，在这个表上任何形式的查询操作也不能执行。但好像部分别的表的操作不受影响。

可以查询数据，但附带错误

在可以貌似可以正常工作的表上，可以查询数据，结果看起来也是正常的，但后续会提示以下错误：

error encountered after some results were delivered

检查正在执行的群集事务

SELECT * FROM crdb_internal.cluster_transactions;