setting-up-local-cluster

设置本地 CockroachDB 集群

指导你下载、安装并启动本地 CockroachDB 集群用于开发。使用官方二进制文件，无需 Docker 或外部运行时依赖。

何时使用此技能

• 开发者要求“设置 CockroachDB”或“启动本地数据库”
• 无法连接到 CockroachDB 集群
• 开发者想从头开始使用 CockroachDB 构建应用
• 设置新的开发环境

前提条件

• macOS（Intel 或 Apple Silicon）、Linux（Intel 或 ARM）或 Windows（Intel）
• 可用于下载二进制文件的 curl 或 wget
• 每个节点约需 500 MB 磁盘空间
• 3 节点集群需要端口 26257-26259（SQL）、26357-26359（RPC）和 8080-8082（DB Console）可用

步骤 1：检测平台并下载

检测操作系统和架构，然后下载相应的二进制文件。

下载 URL

基础 URL：https://binaries.cockroachdb.com/

操作系统	架构	文件名格式
Linux	Intel（amd64）	cockroach-v{VERSION}.linux-amd64.tgz
Linux	ARM（arm64）	cockroach-v{VERSION}.linux-arm64.tgz
macOS	Intel（amd64）	cockroach-v{VERSION}.darwin-10.9-amd64.tgz
macOS	Apple Silicon（arm64）	cockroach-v{VERSION}.darwin-11.0-arm64.tgz
Windows	Intel（amd64）	cockroach-v{VERSION}.windows-6.2-amd64.zip

将 {VERSION} 替换为所需版本（例如 25.4.9）。查看 CockroachDB 发布版本获取最新 GA 版本。

安装

# Example: macOS Apple Silicon, v25.4.9
curl -fsSL https://binaries.cockroachdb.com/cockroach-v25.4.9.darwin-11.0-arm64.tgz | tar xz
mkdir -p ~/.cockroachdb/bin
cp cockroach-v25.4.9.darwin-11.0-arm64/cockroach ~/.cockroachdb/bin/
export PATH="$HOME/.cockroachdb/bin:$PATH"

如果 cockroach 已在 PATH 中，则跳过下载。

步骤 2：启动集群

建议开发时使用 3 节点集群，因为它可以演示复制、范围分布、租约持有者均衡和存活目标——这些是 CockroachDB 的核心功能，单节点无法展现。

3 节点集群（推荐）

# Start 3 nodes with separate SQL, RPC, and HTTP ports.
# Use $HOME instead of ~ in --store / --log-dir / --pid-file: tilde does not
# expand inside --flag=~/... in bash or zsh.
cockroach start --insecure --listen-addr=localhost:26357 --sql-addr=localhost:26257 \
  --http-addr=localhost:8080 --store=$HOME/.cockroachdb/data/node1 \
  --log-dir=$HOME/.cockroachdb/logs/node1 \
  --pid-file=$HOME/.cockroachdb/data/node1/cockroach.pid \
  --join=localhost:26357,localhost:26358,localhost:26359 --background

cockroach start --insecure --listen-addr=localhost:26358 --sql-addr=localhost:26258 \
  --http-addr=localhost:8081 --store=$HOME/.cockroachdb/data/node2 \
  --log-dir=$HOME/.cockroachdb/logs/node2 \
  --pid-file=$HOME/.cockroachdb/data/node2/cockroach.pid \
  --join=localhost:26357,localhost:26358,localhost:26359 --background

cockroach start --insecure --listen-addr=localhost:26359 --sql-addr=localhost:26259 \
  --http-addr=localhost:8082 --store=$HOME/.cockroachdb/data/node3 \
  --log-dir=$HOME/.cockroachdb/logs/node3 \
  --pid-file=$HOME/.cockroachdb/data/node3/cockroach.pid \
  --join=localhost:26357,localhost:26358,localhost:26359 --background

# Initialize the cluster (only needed on first start)
cockroach init --insecure --host=localhost:26357

单节点（轻量）

如果不需要完整的集群功能，可使用资源占用最低的配置：

cockroach start-single-node --insecure --listen-addr=localhost:26257 \
  --http-addr=localhost:8080 --store=$HOME/.cockroachdb/data/node1 \
  --log-dir=$HOME/.cockroachdb/logs/node1 \
  --pid-file=$HOME/.cockroachdb/data/node1/cockroach.pid --background

步骤 3：验证集群

# Check SQL connectivity
cockroach sql --insecure --host=localhost:26257 -e "SELECT version();"

# Verify all nodes joined (3-node cluster)
cockroach node status --insecure --host=localhost:26257

# Check replication factor (should show num_replicas = 3)
cockroach sql --insecure --host=localhost:26257 \
  -e "SHOW ZONE CONFIGURATION FOR RANGE default;"

连接详情

属性	值
SQL URL	postgresql://root@localhost:26257/defaultdb?sslmode=disable
DB Console	http://localhost:8080
用户	root（不安全模式下无密码）
数据库	defaultdb

MCP Toolbox 的环境变量

export COCKROACHDB_HOST=localhost
export COCKROACHDB_PORT=26257
export COCKROACHDB_USER=root
export COCKROACHDB_PASSWORD=
export COCKROACHDB_DATABASE=defaultdb
export COCKROACHDB_SSLMODE=disable

停止集群

# Graceful shutdown via PID files
kill $(cat $HOME/.cockroachdb/data/node1/cockroach.pid) 2>/dev/null
kill $(cat $HOME/.cockroachdb/data/node2/cockroach.pid) 2>/dev/null
kill $(cat $HOME/.cockroachdb/data/node3/cockroach.pid) 2>/dev/null

销毁所有数据

rm -rf $HOME/.cockroachdb/data $HOME/.cockroachdb/logs

隔离网络／受限环境

对于无法访问互联网的环境：

1. 在获准的计算机上预先下载二进制文件
2. 通过批准的渠道将文件传输到目标计算机
3. 将文件放置在 ~/.cockroachdb/bin/cockroach 或 PATH 中的任意位置

3 节点集群的功能

功能	单节点	3 节点
SQL 执行	是	是
复制（num_replicas=3）	否	是
范围分布	否	是
租约持有者均衡	否	是
模拟节点故障	否	是
具有实际分布的 SHOW RANGES	否	是
存活目标（SURVIVE ZONE FAILURE）	否	是
节点间争用	否	是

安全注意事项

• 集群以不安全模式运行（无 TLS、无身份验证）——仅适用于本地开发。
• 重启后，数据会保留在 $HOME/.cockroachdb/data 中。
• 二进制文件和数据位于用户本地目录（~/.cockroachdb/）——无需 sudo，也不会修改系统。
• 3 节点集群总计约使用 750 MB 内存。

参考资料

• 安装 CockroachDB
• 启动本地集群
• CockroachDB 发布版本
• cockroach start
• cockroach init