CockroachDB 分布式数据库部署教程

CockroachDB 是一款开源的分布式 SQL 数据库，兼容 PostgreSQL 协议，提供强一致性事务、自动分片和多活跨区域部署能力。与 TiDB 兼容 MySQL 不同，CockroachDB 兼容 PostgreSQL，适合 PG 生态的应用直接迁移。本文将在搬瓦工 VPS 上部署 CockroachDB 并演示基本使用。

一、安装 CockroachDB

1.1 二进制安装

curl https://binaries.cockroachdb.com/cockroach-v23.2.5.linux-amd64.tgz | tar -xz
cp cockroach-v23.2.5.linux-amd64/cockroach /usr/local/bin/
mkdir -p /usr/local/lib/cockroach
cp -r cockroach-v23.2.5.linux-amd64/lib/* /usr/local/lib/cockroach/
cockroach version

1.2 Docker 安装

docker run -d --name cockroachdb \
  -p 26257:26257 -p 8080:8080 \
  -v crdb_data:/cockroach/cockroach-data \
  --restart unless-stopped \
  cockroachdb/cockroach:v23.2.5 start-single-node --insecure

二、单节点启动

# 创建数据目录
mkdir -p /data/cockroach

# 启动单节点（开发/测试用）
cockroach start-single-node --insecure --store=/data/cockroach \
  --listen-addr=0.0.0.0:26257 --http-addr=0.0.0.0:8080 --background

# 安全模式启动（生产用）
cockroach cert create-ca --certs-dir=/data/certs --ca-key=/data/certs/ca.key
cockroach cert create-node localhost $(hostname) --certs-dir=/data/certs --ca-key=/data/certs/ca.key
cockroach cert create-client root --certs-dir=/data/certs --ca-key=/data/certs/ca.key

cockroach start-single-node --certs-dir=/data/certs --store=/data/cockroach \
  --listen-addr=0.0.0.0:26257 --http-addr=0.0.0.0:8080 --background

Web 管理界面：http://your-server-ip:8080

三、集群部署

# 节点 1（引导节点）
cockroach start --insecure --store=/data/cockroach \
  --listen-addr=192.168.1.10:26257 --http-addr=0.0.0.0:8080 \
  --join=192.168.1.10:26257,192.168.1.20:26257,192.168.1.30:26257 --background

# 节点 2
cockroach start --insecure --store=/data/cockroach \
  --listen-addr=192.168.1.20:26257 --http-addr=0.0.0.0:8080 \
  --join=192.168.1.10:26257,192.168.1.20:26257,192.168.1.30:26257 --background

# 节点 3
cockroach start --insecure --store=/data/cockroach \
  --listen-addr=192.168.1.30:26257 --http-addr=0.0.0.0:8080 \
  --join=192.168.1.10:26257,192.168.1.20:26257,192.168.1.30:26257 --background

# 初始化集群（只需执行一次）
cockroach init --insecure --host=192.168.1.10:26257

四、数据库使用

# 连接数据库（使用内置 SQL shell）
cockroach sql --insecure --host=localhost:26257

# 或使用 PostgreSQL 客户端
psql -h localhost -p 26257 -U root

# 创建数据库和表
CREATE DATABASE myapp;
USE myapp;

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    username STRING UNIQUE NOT NULL,
    email STRING,
    created_at TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    amount DECIMAL(10, 2),
    status STRING DEFAULT 'pending',
    created_at TIMESTAMPTZ DEFAULT now(),
    INDEX idx_user_id (user_id),
    INDEX idx_created_at (created_at)
);

INSERT INTO users (username, email) VALUES ('zhangwei', 'zhang@example.com');
INSERT INTO orders (user_id, amount)
VALUES ((SELECT id FROM users WHERE username='zhangwei'), 199.99);

五、CockroachDB 特有功能

# 查看 Range 分布
SHOW RANGES FROM TABLE orders;

# 行级 TTL（自动过期删除）
CREATE TABLE sessions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID,
    token STRING,
    created_at TIMESTAMPTZ DEFAULT now()
) WITH (ttl_expiration_expression = 'created_at + INTERVAL ''24 hours''',
        ttl_job_cron = '*/5 * * * *');

# 变更数据捕获（CDC）
CREATE CHANGEFEED FOR TABLE orders INTO 'kafka://localhost:9092' WITH format = json;

六、备份与恢复

# 全库备份到本地
BACKUP DATABASE myapp TO 'nodelocal://1/backup/myapp';

# 恢复
RESTORE DATABASE myapp FROM 'nodelocal://1/backup/myapp';

# 定时备份
CREATE SCHEDULE daily_backup
FOR BACKUP DATABASE myapp INTO 'nodelocal://1/backups'
RECURRING '@daily'
WITH SCHEDULE OPTIONS first_run = 'now';

七、监控与运维

# 查看节点状态
cockroach node status --insecure --host=localhost:26257

# 查看集群设置
SHOW CLUSTER SETTING ALL;

# 内存配置（搬瓦工低配方案）
SET CLUSTER SETTING sql.mem.max = '256MiB';

# 查看慢查询
SELECT query, elapsed, rows_read
FROM crdb_internal.node_queries
WHERE elapsed > interval '1s';

创建 systemd 服务文件 /etc/systemd/system/cockroachdb.service：

[Unit]
Description=CockroachDB
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/cockroach start-single-node --insecure --store=/data/cockroach --listen-addr=0.0.0.0:26257 --http-addr=0.0.0.0:8080 --cache=256MiB --max-sql-memory=256MiB
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable cockroachdb
systemctl start cockroachdb

八、与 PostgreSQL 的差异

• 不支持存储过程和自定义类型（部分 PG 扩展不可用）。
• 触发器支持有限。
• 序列（Sequence）在分布式环境下不保证连续。
• 外键约束完全支持（这一点优于 TiDB）。
• 原生支持 JSONB 数据类型。

九、常见问题

• 内存不足：CockroachDB 默认使用较多内存。通过 --cache 和 --max-sql-memory 参数限制。搬瓦工 2GB 方案建议各设为 256MiB。
• 节点下线：使用 cockroach node decommission 安全下线，确保数据迁移完成后再停止。
• 时钟同步：CockroachDB 依赖时钟同步。确保安装了 NTP 或 chrony 服务。

# 安装时间同步
apt install chrony -y
systemctl enable chrony

总结

CockroachDB 是 PostgreSQL 兼容的分布式数据库方案，适合需要强一致性和水平扩展的应用。在搬瓦工 VPS 上可以从单节点开始，随着业务增长扩展到多节点集群。更多数据库教程可参考 TiDB 和 PostgreSQL 流复制。选购搬瓦工 VPS 请查看 全部方案，使用优惠码 NODESEEK2026 享受 6.77% 折扣，通过 bwh81.net 进入官网。