provisioning-cluster-for-production

用于生产环境的集群预配

介绍 CockroachDB 集群的创建和生产环境部署配置。在提供操作步骤之前，此技能会先收集上下文，以便提供适合相应层级的预配步骤和生产环境加固指南。

何时使用此技能

• 创建新的 CockroachDB 集群
• 准备将开发／预发布集群投入生产环境
• 验证硬件和配置是否满足生产环境要求
• 选择合适的部署层级和规模

部署后的健康检查： 使用 reviewing-cluster-health。 持续管理设置： 使用 managing-cluster-settings。 部署后的容量变更： 使用 managing-cluster-capacity。

---

第 1 步：收集上下文

必需的上下文

问题	选项	重要性
部署层级？	Self-Hosted、Advanced、BYOC、Standard、Basic	预配流程完全不同
环境？	生产、预发布、开发	决定硬件规模和配置要求

补充上下文（按层级）

如果是 Self-Hosted：

问题	选项	重要性
平台？	裸机、VM（AWS/GCP/Azure）、Kubernetes	会影响安装和启动命令
如果是 Kubernetes？	Operator（推荐）、Helm、手动 StatefulSet	决定部署方式
节点数？	3（最少）、5、9+	影响拓扑和复制
多区域？	是（几个区域）、否	需要 locality 标志和拓扑规划
预期工作负载？	OLTP、混合 OLTP／分析、写入密集型	影响硬件规模
安全要求？	要求 TLS、静态加密、CMEK	决定证书和加密设置

如果是 Advanced 或 BYOC：

问题	选项	重要性
预配方式？	Cloud Console、Cloud API、Terraform	决定操作流程
云服务提供商？	AWS、GCP、Azure	影响区域选择和网络配置
节点数和规格？	例如，3 个节点 x 8 vCPUs	决定初始容量

如果是 Standard： 收集预期工作负载规模（vCPUs）和存储估算值。

如果是 Basic： 收集预期使用模式和月度预算。

根据上下文选择流程

层级	前往
Self-Hosted	Self-Hosted 预配
Advanced	Advanced 预配
BYOC	BYOC 预配
Standard	Standard 预配
Basic	Basic 预配

---

Self-Hosted 预配

适用条件： 层级 = Self-Hosted

硬件规模

组件	最低要求	生产环境推荐
节点	3	3+（每个故障域使用奇数个节点）
CPU	4 vCPUs（不可突增）	8+ vCPUs
RAM	16 GB	32+ GB
存储	150 GB SSD	500+ GB NVMe SSD
网络	1 Gbps	10 Gbps

内存公式： --cache + --max-sql-memory <= 75% of total RAM 推荐：--cache=.25 --max-sql-memory=.25

切勿使用： 可突增型实例、HDD、网络连接的 HDD、共享 CPU。

有关云实例建议，请参阅硬件与基础设施参考。

在 VM／裸机上部署

步骤 1：在每个节点上安装 CockroachDB

curl https://binaries.cockroachdb.com/cockroach-v<version>.linux-amd64.tgz | tar -xz
cp cockroach-v<version>.linux-amd64/cockroach /usr/local/bin/

步骤 2：生成证书

cockroach cert create-ca --certs-dir=certs --ca-key=my-safe-directory/ca.key
cockroach cert create-node <node-hostname> <node-ip> localhost 127.0.0.1 \
  --certs-dir=certs --ca-key=my-safe-directory/ca.key
cockroach cert create-client root --certs-dir=certs --ca-key=my-safe-directory/ca.key

步骤 3：启动节点（在每个节点上重复）

cockroach start \
  --certs-dir=certs \
  --store=path=<store-path> \
  --listen-addr=<node-address>:26257 \
  --http-addr=<node-address>:8080 \
  --join=<node1-address>,<node2-address>,<node3-address> \
  --locality=region=<region>,zone=<zone> \
  --cache=.25 \
  --max-sql-memory=.25 \
  --background

步骤 4：初始化集群（从任意节点执行一次）

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

步骤 5：验证

cockroach node status --certs-dir=certs --host=<any-node-address>

步骤 3 中启动的每个节点都应显示 is_live = true 和预期的 locality。

在 Kubernetes 上部署

Operator（推荐）：

kubectl apply -f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/master/install/crds.yaml
kubectl apply -f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/master/install/operator.yaml
# Apply CrdbCluster manifest with node count, resources, and storage

Helm：

helm repo add cockroachdb https://charts.cockroachdb.com/
helm install cockroachdb cockroachdb/cockroachdb \
  --set statefulset.replicas=3 \
  --set storage.persistentVolume.size=100Gi

生产环境配置（可自托管）

集群运行后，应用生产环境设置：

-- Enable critical features
SET CLUSTER SETTING kv.rangefeed.enabled = true;
SET CLUSTER SETTING sql.stats.automatic_collection.enabled = true;
SET CLUSTER SETTING admission.kv.enabled = true;

-- Set timeouts
SET CLUSTER SETTING sql.defaults.idle_in_transaction_session_timeout = '300s';
SET CLUSTER SETTING sql.defaults.statement_timeout = '30s';

-- Install enterprise license (if applicable)
SET CLUSTER SETTING cluster.organization = '<org-name>';
SET CLUSTER SETTING enterprise.license = '<license-key>';

在每个节点上创建压舱文件：

cockroach debug ballast <store-path>/auxiliary/EMERGENCY_BALLAST --size=1GiB

**配置负载均衡器：**指向所有节点，并在 /health?ready=1 上执行健康检查。

完整的上线检查清单请参阅 production-deployment-checklist reference。

---

高级预配

**适用条件：**Tier = Advanced

通过 Cloud Console

1. cockroachlabs.cloud → 创建集群
2. 选择 Advanced 计划
3. 选择云提供商（AWS、GCP、Azure）
4. 选择区域
5. 配置节点数（至少 3 个）和机器规格（每个节点的 vCPU 数量）
6. 配置存储
7. 检查并创建

通过 Cloud API

curl -X POST -H "Authorization: Bearer $COCKROACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<cluster-name>",
    "provider": "AWS",
    "spec": {
      "dedicated": {
        "region_nodes": {"us-east-1": 3},
        "machine_type": "m6i.xlarge",
        "storage_gib": 150
      }
    }
  }' \
  "https://cockroachlabs.cloud/api/v1/clusters"

通过 Terraform

resource "cockroach_cluster" "production" {
  name           = "production"
  cloud_provider = "AWS"

  dedicated {
    num_virtual_cpus = 8
    storage_gib      = 150
    num_nodes        = 3
  }

  regions = [{
    name = "us-east-1"
  }]
}

预配后

• 配置 IP 允许列表或 VPC Peering/PrivateLink
• 创建 SQL 用户和数据库
• 设置维护窗口（参阅 performing-cluster-maintenance）
• 如有需要，配置将指标导出到 Datadog/Prometheus

---

BYOC 预配

**适用条件：**Tier = BYOC

按照高级预配步骤操作——BYOC 使用相同的 Cloud Console、API 和 Terraform 接口。

BYOC 额外步骤：

• 确保您的云账户满足 CRL 前提条件（服务账户、VPC、IAM 角色）
• 配置 PrivateLink/PSC 以实现私有连接
• 验证 CRL 服务账户权限

---

标准预配

**适用条件：**Tier = Standard

1. cockroachlabs.cloud → 创建集群
2. 选择 Standard 计划
3. 选择云提供商和区域
4. 根据预期工作负载设置预配的计算资源（vCPU）
5. 创建

预配后：

• 创建 SQL 用户和数据库
• 配置 IP 允许列表
• 设置会话级默认值：

  ALTER ROLE ALL SET statement_timeout = '30s';
  ALTER ROLE ALL SET idle_in_transaction_session_timeout = '300s';
  

---

基础预配

**适用条件：**Tier = Basic

1. cockroachlabs.cloud → 创建集群
2. 选择 Basic 计划
3. 选择云提供商和区域
4. 创建（自动扩缩，无需设置规格）

预配后：

• 设置支出限额（Cloud Console → 集群 → 设置）
• 创建 SQL 用户和数据库
• 配置 IP 允许列表

---

安全注意事项

操作	Tier	风险
cockroach init	SH	安全——仅运行一次；后续调用不会执行任何操作
证书生成	SH	安全存储 CA 密钥——丢失后将无法生成新证书
创建云集群	ADV/BYOC/STD/BAS	安全——配置错误时可以删除
更改生产环境设置	SH	参阅 managing-cluster-settings

关键注意事项（可自托管）：

• 生产环境中切勿使用 --insecure——始终使用 TLS
• 生产工作负载切勿使用可突增型实例
• 多节点集群始终设置 --locality 标志
• 始终配置 --cache 和 --max-sql-memory（默认值过低）
• 投入生产环境前始终创建压舱文件

故障排除

问题	Tier	修复方法
cockroach init 失败	SH	检查所有节点是否已启动，并且可通过端口 26257 访问
节点无法加入集群	SH	验证 --join 地址；检查端口 26257、8080 的防火墙规则
“clock offset”错误	SH	使用 NTP 同步时钟；检查 --max-offset 设置
TLS 握手失败	SH	验证证书是否匹配；检查所有节点的 CA 是否相同
云集群卡在“Creating”状态	ADV/BYOC	等待 15 分钟；如果没有进展，请联系支持团队
创建后无法连接	ALL	检查 IP 允许列表；验证连接字符串；尝试使用 root 用户连接

参考资料

技能参考：

• 硬件和基础设施
• 生产环境部署检查清单

相关技能：

• reviewing-cluster-health — 部署后健康检查
• managing-cluster-settings — 生产环境设置
• managing-certificates-and-encryption — TLS 设置
• managing-cluster-capacity — 部署后扩容

CockroachDB 官方文档：

• 安装 CockroachDB
• 启动集群
• 在 Kubernetes 上部署
• 生产环境检查清单
• 创建高级集群
• Cloud API