SQL CockroachDB 的 zone 配置与数据 locality 优化模板

cockroachdb 通过 zone 配置与 data locality 协同实现多区域部署下的低延迟、高可用与合规性；zone 分系统级、数据库级、表级三层，支持副本数、约束规则、租约偏好等配置，并需结合节点 locality 属性验证生效。

在 CockroachDB 中，zone 配置是控制数据副本分布、故障域隔离和读写延迟的关键机制；而 data locality（数据本地性）则是通过 zone rules 与节点属性（如 region、zone、dc）协同实现的低延迟访问策略。二者结合使用，才能真正支撑多区域（multi-region）部署下的合规性、高可用与性能目标。

Zone 配置的核心层级与作用范围

CockroachDB 的 zone config 分三级：系统级（.default）、数据库级（database db_name）、表级（table table_name）。优先级从高到低，表级 > 数据库级 > 系统级。每个 zone 可定义：

• num_replicas：副本总数（默认 3），影响容灾能力
• constraints：硬性分布规则（如 +region=us-east 或 -zone=gcp-us-central1-a）
• lease_preferences：指定首选租约持有区域（影响读性能），格式为 [[+region=us-west], [+region=eu-west]]
• gc.ttlseconds：该数据的垃圾回收保留时间（影响备份/时间旅行查询窗口）

基于 Region 的 Multi-Region Locality 模板

适用于跨云/跨大区部署（如 US + EU + APAC），目标：读本地化、写跨区强一致、故障时自动降级。

示例：三区域集群（us-east-1、eu-west-1、ap-southeast-1），要求用户读取始终落在所在 region，写入由多数派共识保障一致性：

ALTER DATABASE appdb CONFIGURE ZONE USING   num_replicas = 3,   constraints = '[+region=us-east-1, +region=eu-west-1, +region=ap-southeast-1]',   lease_preferences = '[[+region=us-east-1], [+region=eu-west-1], [+region=ap-southeast-1]]';

说明：

• 三个 +region=... 约束确保每个 region 至少一个副本（避免单点失效）
• lease_preferences 列表顺序即读偏好优先级，CockroachDB 会将租约动态分配给匹配的节点，使读请求免于跨 region
• 若某 region 全部宕机，租约会自动漂移到次优 region，无需人工干预

按业务维度精细化分片：表级 locality 控制

对合规或性能敏感的表（如用户表按国家分区、日志表冷热分离），应在表粒度配置 zone：

CREATE TABLE users_eu (   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),   country STRING,   data JSONB ) LOCALITY REGIONAL BY ROW AS 'country' USING COUNTRIES 'DE', 'FR', 'NL'; <p>ALTER TABLE users_eu CONFIGURE ZONE USING num_replicas = 3, constraints = '[+region=eu-west-1]', lease_preferences = '[[+region=eu-west-1]]';

关键点：

• LOCALITY REGIONAL BY ROW 是声明式 locality，自动按列值（如 country）将行路由到对应 region
• 配合表级 zone，可强制该表所有副本仅存于指定 region，满足 GDPR 等数据驻留要求
• 注意：此模式下，跨 region 的 JOIN 或事务需显式评估延迟代价

验证与调优：确认 locality 是否生效

配置后务必验证实际副本分布与租约位置：

• SHOW RANGES FROM TABLE users_eu; 查看每 range 的 replica 分布（node_id + attributes）
• select * FROM [SHOW RANGE FROM TABLE users_eu WITH DETAILS]; 获取租约 holder、leader、replica count 等实时状态
• cockroach node status --insecure 确认各节点是否正确标注了 --locality（如 region=us-east-1,zone=us-east-1a）
• 用 EXPLAIN (DISTsql) SELECT ... 观察查询是否触发跨 region 扫描

常见疏漏：节点启动未带 --locality、zone constraints 写错 key 名（如用 region 却在节点设 dc）、lease_preferences 缺少嵌套方括号。