CockroachDB 是一款开源的分布式 SQL 数据库，目标是把”像 PostgreSQL 一样好用”的关系型能力，扩展到跨机房、跨地域的高可用架构上。当单机 PostgreSQL 遇到容量上限、备库延迟或机房级故障风险时，CockroachDB 通过自动分片、Raft 多副本与存算分离，让一份数据在多个节点间自愈、可水平扩展，且对应用几乎透明——这正是它在云原生时代被大量采用的核心理由。
CockroachDB 是什么：把单机 PostgreSQL 升级为分布式
传统 PostgreSQL 的高可用通常靠主从复制（流复制 + 哨兵），但主库仍是容量与写入的单点，扩容往往要停机或做繁重的分库分表。CockroachDB 从设计上就假设”节点会宕机、机房会断电”，它以分布式 SQL 的方式对外提供标准 SQL 接口，对内把数据切成小块自动调度，让整个集群像一台永远在线的大数据库。
高度兼容 PostgreSQL 线协议
CockroachDB 实现了 PostgreSQL 的线协议（wire protocol），大部分应用可以沿用既有的 libpq、JDBC、ORM 驱动直接连。它支持常见数据类型、事务（ACID）、窗口函数与 CTE，也兼容 psql 风格的诊断命令。当然它并非 100% 兼容 PL/pgSQL 存储过程等高级特性，迁移前仍需做语法清单核对——这与我们此前在 PostgreSQL vs SQL Server 迁移避坑 中强调的”先盘语法差异”思路一致。
存算分离与自动分片
每个 CockroachDB 节点既承担 SQL 计算，也持有数据副本。数据按主键范围被切成默认 64MiB 左右的 Range 分片，集群根据节点负载与容量自动把 Range 在节点间搬移，实现在线扩缩容而无需人工分表。
核心架构：Range、Raft 与多副本
理解 CockroachDB 的可靠性，关键在它的两层机制：数据如何切、以及切完之后如何保持一致。
数据如何分片（Range）
表按主键有序切分为 Range，每个 Range 默认持有 3 个副本，分布在不同节点（生产环境应跨可用区）。当某个 Range 过大或节点失衡时，系统自动分裂或迁移，整个过程对业务无感。
Raft 保证强一致
每个 Range 的多个副本组成一个 Raft 组，写请求需多数派（quorum）确认才算提交，从而保证即使个别节点掉线，数据也不丢、不错。读请求默认走 Leaseholder 副本，兼顾一致性与延迟。
快速上手：Docker 一键拉起三节点
本地体验最稳妥的方式是用 Docker Compose 跑一个三节点 insecure 集群（仅用于学习，生产务必启用证书）。下面的编排让三个节点互相 join，组成一个最小可玩的高可用集群：
version: "3.8"
services:
roach1:
image: cockroachdb/cockroach:v24.1.2
command: start --insecure --join=roach1:26257,roach2:26257,roach3:26257
ports: ["26257:26257", "8080:8080"]
roach2:
image: cockroachdb/cockroach:v24.1.2
command: start --insecure --join=roach1:26257,roach2:26257,roach3:26257
ports: ["26258:26257", "8081:8080"]
roach3:
image: cockroachdb/cockroach:v24.1.2
command: start --insecure --join=roach1:26257,roach2:26257,roach3:26257
ports: ["26259:26257", "8082:8080"]
用 docker compose up -d 启动后，访问任一节点的 8080 端口即可打开内置 Admin UI，实时看到节点状态、Range 分布与 QPS。容器编排的完整思路可参考我们整理的 Docker Compose 一键编排 一文。
连接与建表：像用 PostgreSQL 一样
CockroachDB 自带 cockroach sql 客户端，也兼容 psql。下面演示建库、建表、插入与查询——语法与 PostgreSQL 高度一致：
-- 连接（insecure 学习环境）
cockroach sql --insecure --host=localhost:26257
-- 建库建表
CREATE DATABASE shop;
USE shop;
CREATE TABLE orders (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id INT NOT NULL,
amount DECIMAL(12,2) NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- 插入与查询
INSERT INTO orders (user_id, amount) VALUES (1001, 199.00), (1002, 49.50);
SELECT user_id, sum(amount) FROM orders GROUP BY user_id;
注意：CockroachDB 强烈建议每个表都有显式主键，因为主键决定了数据在 Range 间的切分方式；缺少主键的表会被隐式补一个 rowid，可能成为热点，这一点在高频写入场景尤其要规避。
数据再平衡与在线扩缩容
新增节点后，集群会自动把部分 Range 迁移过去，无需停机。你可以直接观察数据分布：
-- 查看某张表的分片（Range）分布
SELECT start_key, end_key, replica_localities
FROM [SHOW RANGES FROM TABLE shop.orders];
-- 查看集群节点与状态
cockroach node status --insecure --host=localhost:26257
当集群从 3 节点扩到 5 节点，Range 会在后台平滑漂移，业务连接不中断。这种”加机器就能加容量”的特性，正是它相较传统主从架构的最大优势。
高可用与容灾设计
副本因子与容忍度
默认 num_replicas = 3 可容忍 1 个节点失效。跨可用区部署时，可通过 locality 让副本分散到不同机房，并设置 5 副本容忍 2 个机房级故障：
-- 把默认副本数提升到 5（跨区容灾）
ALTER RANGE default CONFIGURE ZONE USING num_replicas = 5;
节点级故障演练
在生产上线前，建议做一次真实故障演练：直接停掉其中一个节点容器，确认集群仍可读写、Admin UI 标记该节点为 Suspected/dead，并在其余副本上继续服务。演练能验证你的 locality 与副本策略是否真的”抗揍”。
与同类分布式数据库的对比
分布式 SQL 赛道并不只有 CockroachDB，选型时要结合团队栈与部署形态。下面是一张横向对照，帮助快速定位：
| 方案 | 兼容协议 | 部署形态 | 典型适用 |
|---|---|---|---|
| CockroachDB | PostgreSQL | 自托管 / 云托管 | 全球化部署、强一致 OLTP |
| OceanBase | MySQL / Oracle | 自托管 / 阿里云 | 金融级高并发交易 |
| PolarDB | MySQL / PostgreSQL | 云原生托管 | 云上平滑迁移、弹性扩缩 |
| 传统 PG 主从 | PostgreSQL | 自建 | 中小规模、运维简单优先 |
如果业务以 MySQL 生态为主、且追求金融级稳定性，可以看看我们写过的 OceanBase 部署与调优 与 PolarDB 云原生架构与迁移；若需要的是实时分析而非事务，StarRocks 极速 OLAP 会更对路。
生产落地检查清单
| 检查项 | 建议做法 |
|---|---|
| 安全 | 生产启用 --certs-dir 证书，禁止 insecure |
| 副本与 locality | 跨可用区打 locality，副本数匹配容忍目标 |
| 容量规划 | 单 Range 64MiB，预留 30% 磁盘水位 |
| 主键设计 | 避免单调自增主键造成写入热点 |
| 备份 | 定期 BACKUP 到对象存储并演练 RESTORE |
| 监控 | 接入 Prometheus，关注节点存活与 Range 均衡 |
备份、监控与生态衔接
CockroachDB 内置 BACKUP / RESTORE，支持全量、增量与时间点恢复（revision history）。最简的本地备份示例：
-- 全量备份到节点本地（生产应改为云存储路径）
BACKUP DATABASE shop INTO 'nodelocal://1/backups/2026-09' WITH revision_history;
-- 从备份恢复
RESTORE DATABASE shop FROM 'nodelocal://1/backups/2026-09';
监控方面，CockroachDB 暴露 Prometheus 指标端点，可直接对接我们在 GitHub Actions 之外也会用到的可观测体系，把节点存活、QPS、Range 再平衡时延纳入统一告警。把数据库变更纳入 CI/CD 同样是好习惯——用迁移工具在流水线里自动执行 schema 变更，能显著降低人为误操作。
小结
CockroachDB 用”分布式 SQL + Raft 多副本 + 自动分片”的组合，把高可用与水平扩展做成了数据库的默认能力，而非靠 DBA 手工拼装的架构。对于需要跨地域一致、又不愿放弃 SQL 生态的团队，它是 PostgreSQL 主从之外一个值得认真评估的方向。落地时牢记三件事：开证书、设计好主键、做真实故障演练——剩下的交给集群自愈。
