managing-tls-certificates

管理 TLS 证书

管理 CockroachDB 集群的 TLS 证书，包括 CA 证书下载、客户端证书身份验证设置、证书轮换，以及常见 SSL/TLS 连接错误的排查。涵盖 CockroachDB Cloud（始终启用 TLS）和自托管证书生命周期管理。

适用场景

• 排查应用客户端（DBeaver、TypeORM、psql、Go、Python、Java）的 SSL/TLS 连接错误
• 在 CockroachDB Cloud 上设置客户端证书身份验证
• 向 Cloud 集群上传自定义 Client CA
• 轮换或续订证书（Cloud 或自托管）
• 为连接 Kafka 的 CDC changefeed 配置 mTLS
• 下载或查找 Cloud 集群的 CA 证书

前提条件

CockroachDB Cloud：

• 已通过身份验证的 ccloud CLI（ccloud auth login）
• 可访问 Cloud Console，以下载 CA 证书
• 具有 Cluster Admin 角色，以配置客户端 CA

自托管：

• 可使用 cockroach cert CLI
• 具有对集群节点的 管理员访问权限
• 使用 OpenSSL 检查和生成证书

验证访问权限：

# Cloud
ccloud auth whoami
ccloud cluster list

# Self-hosted — check existing certificates
cockroach cert list --certs-dir=<certs-directory>

配置决策

继续之前，先确定用户的部署模式。询问适用哪种选项，然后仅按照以下相关部分操作。

决策 1 — 部署模式：

• CockroachDB Cloud： TLS 始终启用，集群 CA 由 Cockroach Labs 管理。按照第 1 部分下载 CA、设置客户端证书身份验证，以及轮换 Cloud 证书。
• 自托管： 完全手动管理证书生命周期（CA、节点和客户端证书）。按照第 2 部分创建、轮换和管理证书。

第 3 部分（故障排查）和第 4 部分（CDC 的 mTLS）适用于两种部署模式。

步骤

第 1 部分：CockroachDB Cloud TLS

如果用户在决策 1 中选择了 CockroachDB Cloud，请按照本部分操作。

CockroachDB Cloud 对所有连接强制启用 TLS。集群 CA 证书由 Cockroach Labs 管理。

1.1 下载 CA 证书

客户端需要 CA 证书来验证集群身份。

# Download via ccloud CLI
ccloud cluster cert <cluster-id>

# Or download from the Cloud Console:
# Cluster > Connect > Download CA Cert

也可通过以下地址获取 CA 证书：https://cockroachlabs.cloud/clusters/<cluster-id>/cert

下载后的常见 CA 证书位置：

• macOS：~/.postgresql/root.crt
• Linux：~/.postgresql/root.crt 或 /etc/cockroach-certs/ca.crt
• Windows：%APPDATA%\postgresql\root.crt

1.2 配置客户端证书身份验证

客户端证书身份验证使用相互 TLS（mTLS）——客户端通过证书而非密码来证明自己的身份。

步骤 1：向集群上传 Client CA

Client CA 用于签署客户端证书，与集群的 CA 不同。

# Upload a Client CA certificate via ccloud CLI
ccloud cluster cert set-client-ca <cluster-id> --cert-file <client-ca.crt>

步骤 2：创建由 Client CA 签署的客户端证书

# Generate a client key and certificate signing request
openssl genrsa -out client.<username>.key 2048
openssl req -new -key client.<username>.key \
  -out client.<username>.csr \
  -subj "/CN=<username>"

# Sign the CSR with your Client CA
openssl x509 -req -in client.<username>.csr \
  -CA client-ca.crt -CAkey client-ca.key \
  -CAcreateserial \
  -out client.<username>.crt \
  -days 365

步骤 3：使用客户端证书连接

cockroach sql \
  --url "postgresql://<username>@<cluster-host>:26257/defaultdb?sslmode=verify-full&sslrootcert=<ca.crt>&sslcert=client.<username>.crt&sslkey=client.<username>.key"

针对特定客户端的连接字符串，请参阅连接示例参考。

1.3 证书轮换（Cloud）

客户端证书应在到期前轮换。集群 CA 证书由 Cockroach Labs 管理，并会自动轮换。

客户端证书轮换：

1. 生成由同一个 Client CA（或新的 Client CA）签署的新客户端证书
2. 将新证书部署到应用客户端
3. 验证使用新证书的连接是否正常
4. 从应用客户端移除旧证书

Client CA 轮换：

1. 生成新的 Client CA
2. 向集群上传新的 Client CA（过渡期间支持多个 CA）
3. 签发由新 CA 签署的新客户端证书
4. 将新客户端证书部署到所有应用
5. 所有客户端迁移完成后，移除旧的 Client CA

第 2 部分：自托管证书管理

如果用户在决策 1 中选择了 自托管，请按照本部分操作。

自托管 CockroachDB 需要手动管理 CA、节点和客户端证书的生命周期。

2.1 初始化证书颁发机构

# Create the CA certificate and key
cockroach cert create-ca \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

2.2 创建节点证书

# Create a node certificate for each node
cockroach cert create-node \
  <node-hostname> \
  <node-ip> \
  localhost \
  127.0.0.1 \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

2.3 创建客户端证书

# Create a client certificate for root user
cockroach cert create-client root \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

# Create a client certificate for an application user
cockroach cert create-client <username> \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

2.4 证书轮换（可自托管）

# Check certificate expiry
cockroach cert list --certs-dir=certs

# Or with OpenSSL
openssl x509 -in certs/node.crt -noout -enddate

轮换流程：

1. 使用现有 CA 生成新证书（或先轮换 CA）
2. 将新证书复制到每个节点
3. 重新加载证书（SIGHUP — 无需停机）：

   kill -SIGHUP $(pgrep cockroach)
   

4. 确认节点正在提供新证书

第 3 部分：排查 SSL/TLS 错误

请参阅故障排除参考，了解全面的错误指南。

常见错误和快速修复方法

“x509: certificate signed by unknown authority”

• 客户端不信任集群的 CA 证书
• 修复方法：下载正确的 CA 证书，并在连接字符串中设置 sslrootcert

“SSL SYSCALL error: EOF detected”

• TLS 握手期间连接意外终止
• 修复方法：检查网络连接、防火墙规则，并确认使用了正确的端口（26257）

“tls: bad certificate”

• 服务器拒绝了客户端证书
• 修复方法：确认客户端证书由集群信任的 CA 签名（必须上传客户端 CA）

“certificate has expired”

• 客户端或服务器证书已过期
• 修复方法：轮换过期证书（请参见上面的轮换步骤）

诊断命令

# Inspect a certificate
openssl x509 -in cert.crt -text -noout

# Verify certificate chain
openssl verify -CAfile ca.crt client.crt

# Test TLS connection to cluster
openssl s_client -connect <host>:26257 -CAfile ca.crt

# Check certificate expiry date
openssl x509 -in cert.crt -noout -enddate

第 4 部分：用于向 Kafka 发送 CDC 变更流的 mTLS

CockroachDB CDC 变更流可使用 mTLS 向 Kafka Broker 进行身份验证。

-- Create a changefeed with mTLS authentication to Kafka
CREATE CHANGEFEED FOR TABLE orders
  INTO 'kafka://<kafka-broker>:9093?tls_enabled=true&ca_cert=<base64-ca>&client_cert=<base64-cert>&client_key=<base64-key>'
  WITH updated, resolved;

为变更流 URI 准备证书：

# Base64 encode certificates for use in changefeed URI
cat ca.crt | base64 -w 0    # Linux
cat ca.crt | base64          # macOS

cat client.crt | base64 -w 0
cat client.key | base64 -w 0

安全注意事项

影响类型	严重程度	建议
上传客户端 CA	低	不会影响现有连接；只会添加一个新的信任根
移除客户端 CA	高	会使由该 CA 签名的所有客户端证书失效
证书过期	高	监控到期日期；在过期前轮换
CA 证书错误	中	客户端将无法连接；可通过更新 CA 证书修复

请勿：

• 删除 CA 私钥 — 它是签署新证书所必需的
• 上传过期的 CA 证书
• 在客户端仍依赖某个客户端 CA 时将其移除
• 在生产集群上禁用 TLS（CockroachDB Cloud 不允许这样做）

回滚

云端 — 客户端 CA 问题：

1. 如果新上传的客户端 CA 有误，请上传正确的 CA
2. 如果客户端证书被拒绝，请暂时恢复使用密码身份验证
3. 如果需要处理集群 CA，请联系 CockroachDB 支持团队

自托管 — 证书问题：

1. 从备份中恢复之前的证书
2. 重新加载证书：kill -SIGHUP $(pgrep cockroach)
3. 如果已轮换 CA，请确保所有节点和客户端都已获取新的 CA

参考资料

技能参考：

• 客户端连接示例 — 常见客户端的连接字符串
• TLS 故障排查指南 — 常见 SSL/TLS 错误及其修复方法

相关技能：

• 审计云集群安全性 — 执行全面的安全态势审计
• 配置 SSO 和 SCIM — 将 SSO 用作基于证书的身份验证的替代方案

CockroachDB 官方文档：

• 传输层安全协议（TLS）
• 身份验证
• 客户端连接参数
• cockroach cert 命令
• 轮换安全证书
• 云证书管理
• CDC Kafka Sink