managing-cluster-settings

管理集群设置

审核、审计和修改 CockroachDB 集群设置。在提供操作步骤前，此技能会收集上下文，以确定哪些设置可用，以及针对运营人员所在的层级推荐哪种修改方式。

何时使用此技能

• 审计集群配置，确认其是否满足生产环境要求
• 找出偏离默认值的设置
• 调整性能、复制或准入控制
• 在升级或事故后验证设置
• 了解所在层级支持修改哪些设置
• 管理企业许可证的安装和续订（Self-Hosted）

版本管理： 使用 upgrading-cluster-version — 升级期间请勿更改设置。 健康检查： 使用 reviewing-cluster-health。

---

第 1 步：收集上下文

必需的上下文

问题	选项	重要性
部署层级？	Self-Hosted、Advanced、BYOC、Standard、Basic	决定哪些设置可查看和修改
目标？	审计/审核、调整性能、解决特定问题、升级后验证	决定要使用哪些查询和操作步骤

其他上下文（按层级）

如果是 Self-Hosted：

问题	选项	重要性
SQL 访问级别？	admin、MODIFYCLUSTERSETTING、VIEWCLUSTERSETTING	决定可执行的操作
特定设置或领域？	例如，“timeout”“replication”“gc”	将搜索范围缩小到相关设置
当前是否正在升级？	是、否	滚动升级期间不得更改设置

如果是 Advanced 或 BYOC：

问题	选项	重要性
SQL 访问级别？	admin、limited	决定可执行的操作
特定设置或领域？	例如，“timeout”“rangefeed”	缩小搜索范围

如果是 Standard 或 Basic： 无需收集其他上下文 — 设置访问权限有限。会话变量是主要的调优机制。

根据上下文选择路径

层级	设置访问权限	转到
Self-Hosted	完全	Self-Hosted 设置
Advanced / BYOC	大多数（部分受限）	Advanced / BYOC 设置
Standard	有限	Standard 设置
Basic	最少	Basic 设置

---

审计查询（所有层级）

这些只读查询适用于 Self-Hosted 和 Advanced/BYOC。Standard 和 Basic 的可见性可能受限 — 请参阅下方按层级划分的部分。

非默认设置

SELECT variable, value, setting_type, description
FROM [SHOW ALL CLUSTER SETTINGS]
WHERE value != default_value ORDER BY variable;

生产环境关键设置

SELECT variable, value FROM [SHOW ALL CLUSTER SETTINGS]
WHERE variable IN (
  'kv.rangefeed.enabled', 'sql.stats.automatic_collection.enabled',
  'server.time_until_store_dead', 'admission.kv.enabled',
  'cluster.preserve_downgrade_option',
  'sql.defaults.idle_in_transaction_session_timeout'
) ORDER BY variable;

gc.ttlseconds 是区域配置参数，而非集群设置；请使用 SHOW ZONE CONFIGURATION FOR ...，针对相关表/数据库/范围进行检查。

按关键字搜索

SELECT variable, value, description FROM [SHOW ALL CLUSTER SETTINGS]
WHERE variable LIKE '%<keyword>%' OR description LIKE '%<keyword>%'
ORDER BY variable;

其他审计查询请参阅 sql-queries 参考。 生产环境推荐的设置请参阅 recommended-values 参考。

---

Self-Hosted 设置

适用条件： 层级 = Self-Hosted

可完全控制所有集群设置和节点级启动标志。

修改设置

SHOW CLUSTER SETTING <name>;          -- Document current value first
SET CLUSTER SETTING <name> = <value>; -- Apply
SHOW CLUSTER SETTING <name>;          -- Verify

重置为默认值

RESET CLUSTER SETTING <name>;

节点级设置（需要重启节点）

节点级设置是 cockroach start 标志，无法在运行时更改。如需更改：排空节点、停止进程、更新标志，然后重启。请参阅 performing-cluster-maintenance。

完整的启动标志列表请参阅 node-level-settings 参考。

许可证管理

CockroachDB Self-Hosted 的备份/恢复、变更流、静态加密和多区域功能等特性需要企业许可证。许可证以集群设置的形式存储。

查看当前许可证：

SHOW CLUSTER SETTING cluster.organization;
SHOW CLUSTER SETTING enterprise.license;

安装或续订许可证：

SET CLUSTER SETTING cluster.organization = '<organization-name>';
SET CLUSTER SETTING enterprise.license = '<license-key>';

验证许可证是否有效：

SELECT * FROM [SHOW CLUSTER SETTING enterprise.license];

**许可证到期：**许可证到期不会导致数据丢失或集群不可用。续订前，企业功能（备份、CDC、EAR）将停止工作。核心功能仍然可用。请主动监控许可证到期时间。

**CockroachDB Core（免费）：**如果运行时没有企业许可证，则无需管理许可证。核心功能始终可用。

---

高级 / BYOC 设置

**适用条件：**层级 = Advanced 或 BYOC

大多数 SQL 级集群设置都可以修改。基础设施级设置由 Cockroach Labs 管理。

可修改（常见示例）

SET CLUSTER SETTING sql.defaults.idle_in_transaction_session_timeout = '300s';
SET CLUSTER SETTING sql.defaults.statement_timeout = '30s';
SET CLUSTER SETTING kv.rangefeed.enabled = true;
-- gc.ttlseconds is a zone configuration parameter, not a cluster setting
ALTER RANGE default CONFIGURE ZONE USING gc.ttlseconds = 86400;

受限（由 CRL 管理）

以下设置由 Cockroach Labs 管理，无法修改：

• server.time_until_store_dead
• kv.snapshot_rebalance.max_rate
• cluster.preserve_downgrade_option（升级时请使用 Cloud Console）
• 节点级标志（--cache、--max-sql-memory）——由 CRL 管理

如果修改被拒绝，错误信息会指出该设置由 CockroachDB Cloud 管理。请使用 Cloud Console 或联系支持团队。

**许可证：**在 Advanced/BYOC 上，企业许可证由 Cockroach Labs 自动管理。客户无需采取任何操作。

完整列表请参阅 cloud-restricted-settings 参考文档。

---

Standard 设置

**适用条件：**层级 = Standard

Standard 是一项多租户托管服务。大多数集群设置都无法修改，因为更改可能会影响其他租户。请将会话变量作为主要调优方式。

会话变量（推荐方式）

-- Per-session
SET statement_timeout = '30s';

-- Default for all sessions (preferred over sql.defaults.*)
ALTER ROLE ALL SET statement_timeout = '30s';
ALTER ROLE ALL SET idle_in_transaction_session_timeout = '300s';

可配置内容

• 通过 SET 和 ALTER ROLE 设置会话级超时和默认值
• 通过会话变量控制 SQL 级行为

由 CRL 管理的内容

• 所有基础设施设置（复制、准入控制、存储）
• 计算和网络——通过 Cloud Console 配置

**注意：**在 Standard 上，SHOW ALL CLUSTER SETTINGS 可能只会返回有限的设置。

---

Basic 设置

**适用条件：**层级 = Basic

Basic 是一项可访问设置极少的无服务器服务。基础设施完全由系统管理，并会自动扩缩。请使用会话变量进行 SQL 级调优。

会话变量

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

Cloud Console 配置

• 支出限额
• IP 允许列表
• 区域选择

所有其他配置均由 Cockroach Labs 管理。如果需要对设置进行更多控制，可考虑升级到 Standard 或 Advanced。

---

安全注意事项

只读查询在所有层级上都安全。

修改任何设置前：

1. 记录当前值（以便回滚）
2. 确认当前不在升级过程中
3. 了解影响（查看 description 字段）
4. 一次只更改一个设置
5. 监控 15-30 分钟后，再进行其他更改

风险级别：

• 低：sql.defaults.statement_timeout、diagnostics.reporting.enabled
• 中：kv.snapshot_rebalance.max_rate、gc.ttlseconds（区域配置参数——风险级别相同）
• 高：cluster.preserve_downgrade_option、admission.kv.enabled

重要：切勿在滚动升级期间更改设置。集群设置会影响集群上的所有工作负载——尽可能优先使用会话变量，以缩小影响范围。

有关各项设置的详细风险评估，请参阅 safety-guide 参考文档。

故障排除

问题	层级	解决方法
SET 时出现“permission denied”	SH/ADV/BYOC	授予 MODIFYCLUSTERSETTING 权限或使用管理员角色
出现“managed by Cloud”错误	ADV/BYOC	此层级限制了该设置；请使用 Cloud Console 或联系支持团队
设置不可见	STD/BAS	符合预期——多租户／无服务器层级的设置可见性有限
未见效果	SH/ADV/BYOC	检查是否有会话变量覆盖；使用 SHOW 验证
升级后设置被还原	SH	重新应用；在运维手册中记录
企业功能停止工作	SH	许可证已过期；使用 SET CLUSTER SETTING enterprise.license 续订
出现“enterprise license required”错误	SH	安装许可证或使用仅包含核心功能的替代方案

参考资料

技能参考：

• SQL 审计查询
• 推荐的生产环境值
• 节点级设置（启动标志）
• 云端限制的设置
• 安全指南

相关技能：

• reviewing-cluster-health
• upgrading-cluster-version

CockroachDB 官方文档：

• 集群设置
• SET CLUSTER SETTING
• 生产环境检查清单