SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场managing-tls-certificates

managing-tls-certificates

安全与审计

查看项目

更新于 10-15 16:58

技能介绍

该技能围绕 CockroachDB 集群的 TLS 证书生命周期管理展开，适用于 CockroachDB Cloud 与自托管两种部署模式，并覆盖证书配置、轮换与故障排查等任务。

一、用途与适用场景

  • 排查应用客户端（DBeaver、TypeORM、psql、Go、Python、Java）出现的 SSL/TLS 连接错误。
  • 在 CockroachDB Cloud 上设置客户端证书认证。
  • 向 Cloud 集群上传自定义 Client CA。
  • 轮换或续期证书（Cloud 或自托管）。
  • 为 CDC changefeed 到 Kafka 配置 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

自托管 — 检查现有证书

cockroach cert list --certs-dir=<certs-directory>

三、配置决策 需先确定部署模型：CockroachDB Cloud 的 TLS 始终开启，集群 CA 由 Cockroach Labs 管理，按第 1 部分处理 CA 下载、客户端证书认证与 Cloud 证书轮换；自托管需完整手动管理证书生命周期（CA、节点、客户端证书），按第 2 部分处理创建、轮换与管理。第 3 部分（排错）与第 4 部分（CDC mTLS）对两种模式均适用。

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

  1. 下载 CA 证书：

通过 ccloud CLI 下载

ccloud cluster cert <cluster-id>

或从 Cloud Console 下载：

Cluster > Connect > Download CA Cert

CA 证书也可从 https://cockroachlabs.cloud/clusters/<cluster-id>/cert 获取。常见下载后位置：macOS 为 ~/.postgresql/root.crt；Linux 为 ~/.postgresql/root.crt 或 /etc/cockroach-certs/ca.crt；Windows 为 %APPDATA%\postgresql\root.crt。 2. 配置客户端证书认证（mTLS）： 步骤 1：上传 Client CA 到集群（Client CA 用于签发客户端证书，与集群 CA 相互独立）：

通过 ccloud CLI 上传 Client CA 证书

ccloud cluster cert set-client-ca <cluster-id> --cert-file <client-ca.crt>

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

生成客户端密钥与证书签名请求

openssl genrsa -out client.<username>.key 2048 openssl req -new -key client.<username>.key
-out client.<username>.csr
-subj "/CN=<username>"

使用 Client CA 签署 CSR

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. Cloud 证书轮换：客户端证书应在过期前轮换；集群 CA 证书由 Cockroach Labs 管理并自动轮换。客户端证书轮换流程为：生成由同一 Client CA（或新 Client CA）签发的新的客户端证书；将新证书部署到应用客户端；验证新证书可正常连接；从应用客户端移除旧证书。Client CA 轮换流程为：生成新的 Client CA；将新 Client CA 上传到集群（过渡期支持多个 CA）；签发由新 CA 签名的新客户端证书；将新客户端证书部署到所有应用；所有客户端迁移完成后移除旧的 Client CA。

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

  1. 初始化证书颁发机构： cockroach cert create-ca
    --certs-dir=certs
    --ca-key=my-safe-directory/ca.key
  2. 创建节点证书（为每个节点创建）： cockroach cert create-node
    <node-hostname>
    <node-ip>
    localhost
    127.0.0.1
    --certs-dir=certs
    --ca-key=my-safe-directory/ca.key
  3. 创建客户端证书：

为 root 用户创建客户端证书

cockroach cert create-client root
--certs-dir=certs
--ca-key=my-safe-directory/ca.key

为应用用户创建客户端证书

cockroach cert create-client <username>
--certs-dir=certs
--ca-key=my-safe-directory/ca.key 4. 自托管证书轮换：

检查证书过期时间

cockroach cert list --certs-dir=certs

或使用 OpenSSL

openssl x509 -in certs/node.crt -noout -enddate

轮换流程：使用现有 CA 生成新证书（或先轮换 CA）；将新证书复制到每个节点；重载证书（SIGHUP，无需停机）： kill -SIGHUP $(pgrep cockroach) 验证节点是否已使用新证书。

六、SSL/TLS 错误排查 常见错误与快速修复："x509: certificate signed by unknown authority" 表示客户端不信任集群的 CA 证书，修复方法是下载正确的 CA 证书并在连接字符串中设置 sslrootcert；"SSL SYSCALL error: EOF detected" 表示 TLS 握手期间连接意外终止，修复方法是检查网络连通性、防火墙规则以及是否使用正确端口（26257）；"tls: bad certificate" 表示客户端证书被服务器拒绝，修复方法是确认客户端证书由集群信任的 CA 签名（必须已上传 Client CA）；"certificate has expired" 表示客户端或服务器证书已过期，修复方法是轮换过期证书。 诊断命令：

检查证书

openssl x509 -in cert.crt -text -noout

验证证书链

openssl verify -CAfile ca.crt client.crt

测试到集群的 TLS 连接

openssl s_client -connect <host>:26257 -CAfile ca.crt

检查证书过期日期

openssl x509 -in cert.crt -noout -enddate

七、CDC Changefeed 到 Kafka 的 mTLS CockroachDB CDC changefeed 可使用 mTLS 向 Kafka broker 认证。 -- 创建使用 mTLS 认证到 Kafka 的 changefeed 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;

为 changefeed URI 准备证书：

为 changefeed URI 使用 base64 编码证书

cat ca.crt | base64 -w 0 # Linux cat ca.crt | base64 # macOS

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

八、安全注意事项 影响类型与严重度：Client CA 上传为低，不影响现有连接，仅新增信任根；Client CA 移除为高，会使该 CA 签发的所有客户端证书失效；证书过期为高，应监控过期日期并在过期前轮换；错误的 CA 证书为中，客户端将无法连接，可通过更新 CA 证书修正。 不要：删除 CA 私钥（签署新证书所必需）；上传已过期的 CA 证书；在客户端仍依赖某 Client CA 时将其移除；在生产集群上禁用 TLS（CockroachDB Cloud 不允许）。 回滚：Cloud 的 Client CA 问题可上传正确的 CA，若客户端证书被拒绝可临时回退到密码认证，若集群 CA 需要干预请联系 CockroachDB 支持；自托管的证书问题可从备份恢复先前的证书、重载证书（kill -SIGHUP $(pgrep cockroach)），若已轮换 CA 需确保所有节点与客户端都拥有新 CA。