Couchbase从4.5版本开始逐步强化了安全体系，节点之间的集群通信、客户端到服务端的数据传输、控制台访问以及XDCR跨集群复制，都可以通过TLS加密来保护。而TLS加密的核心就是证书，一旦证书过期没有及时轮换，轻则客户端报证书校验失败，重则节点之间无法通信导致集群脑裂。所谓certificate rotation证书轮换，指的就是在不中断服务或者尽量少中断服务的前提下，把旧的证书替换成新证书。这篇文章从原理、操作步骤、客户端配合以及常见问题四个层面，把Couchbase证书轮换这件事讲透。
Couchbase的证书体系与轮换原理
Couchbase的TLS体系主要分两块：一块是集群内部证书（cluster certificate），用于节点之间的加密通信和GSI（global secondary index）等内部流量；另一块是服务端节点证书，用于客户端连接11207、11210等端口时的身份验证。默认安装时，Couchbase会自动生成一套自签名证书，存放在/opt/couchbase/var/lib/couchbase/config目录下，其中pki子目录保存着CA根证书和各个节点的证书链。
轮换的基本思路有两种。第一种是保留原有CA根证书，只重新签发节点证书，这种方式客户端不需要更换信任的CA，操作最平滑。第二种是整个证书链全部更换，包括根CA在内，这种方式安全性最高（适合私钥疑似泄露的场景），但客户端必须同步更新信任配置，否则会立刻出现证书校验失败。生产环境绝大多数情况下建议采用第一种，除非有明确的合规要求或者密钥泄露风险。
理解一个关键点很重要：Couchbase集群内部证书的轮换是自动的。节点之间通信用的证书由集群自己管理，到期前会自动续期，运维不需要手动干预。真正需要人工轮换的是你在集群初始化之后手动上传的自定义节点证书，也就是客户端用来做服务端身份验证的那部分。很多事故的根源就是混淆了这两者，以为集群内部证书自动续期就万事大吉，结果自定义的节点证书悄悄过期了。
服务端节点证书的轮换操作
假设我们采用保留CA、只换节点证书的方案。首先用openssl签发新证书，这里给一个完整流程。先确认现有证书的CA与域名配置：
# 查看当前节点证书的subject与SAN openssl x509 -in current-node.pem -noout -subject -ext subjectAltName # 用原有CA签发新证书，有效期两年 openssl genrsa -out node-new.key 2048 openssl req -new -key node-new.key -out node-new.csr \ -subj "/CN=cb-node-1.ipipp.com" openssl x509 -req -in node-new.csr \ -CA ca.pem -CAkey ca.key -CAcreateserial \ -out node-new.pem -days 730 \ -extfile <(printf "subjectAltName=DNS:cb-node-1.ipipp.com,IP:10.0.1.11")
证书签好之后，通过couchbase-cli上传到集群。setting-x509-cert命令有两组参数：一组是cluster-ca-file，用于更换CA证书链；另一组是node-cert-file，只更换节点证书而不动CA。我们要做的是后者：
# 仅替换节点证书，保留原有CA couchbase-cli setting-x509-cert -c http://10.0.1.11:8091 \ --username Administrator \ --password 'your-password' \ --node-cert-file ./node-new.pem # 验证证书是否生效 couchbase-cli ssl-manage -c http://10.0.1.11:8091 \ --username Administrator \ --password 'your-password' \ --retrieve-cert ./cluster-ca-new.pem
这个命令的作用范围是整个集群，执行一次所有节点都会更新节点证书，不需要逐台机器操作，这一点和很多中间件不一样。上传完成后，可以用openssl直接探测11207端口验证新证书是否已经对外生效：
openssl s_client -connect 10.0.1.11:11207 \ -CAfile ./ca.pem < /dev/null 2>/dev/null | grep -E "Verify return code|notAfter"
看到Verify return code: 0 (ok)并且notAfter日期是新的，说明轮换成功。这里有个细节需要注意：如果新证书的SAN里漏掉了客户端实际连接用的IP地址或域名，客户端SDK会报hostname mismatch错误，签发前务必核对旧证书的完整SAN列表。
客户端信任证书的平滑更新策略
服务端证书换了，客户端这边的处理方式取决于连接配置。如果客户端信任的是CA根证书，而CA没换，那么客户端什么都不用改，这就是前面推荐保留CA方案的原因。但如果这次连CA一起换了，就必须让客户端先同时信任新旧两个CA，等服务端切换完成后再移除旧CA，也就是所谓的双信任窗口期。
以Java客户端为例，信任库的更新操作如下：
# 先备份原truststore cp truststore.jks truststore.jks.bak # 导入新CA到truststore（旧CA暂不删除） keytool -importcert -alias new-ca \ -file new-ca.pem \ -keystore truststore.jks \ -storepass changeit \ -noprompt # 确认两个CA都在 keytool -list -keystore truststore.jks -storepass changeit
其他SDK的处理方式类似：Go客户端把新CA追加到tls.RootCAs对应的证书池；Python客户端在ClusterOptions的TLS配置中加载包含新旧两份CA的pem文件。整个流程的顺序必须是客户端先加新CA、再换服务端证书、最后客户端移除旧CA，顺序颠倒任何一个环节都会造成连接中断。窗口期内新旧CA同时信任是安全的，多信任一个即将废弃的CA带来的风险窗口非常短，可以接受。
常见问题与回滚方案
轮换过程中最典型的报错有三类。第一类是certificate signed by unknown authority，说明客户端还没信任新CA就切了服务端，解决办法是把新CA加进信任库。第二类是certificate has expired or is not yet valid，除了真的过期，还可能是服务器时间不同步导致证书被判定为未生效，先检查NTP再排查证书。第三类是hostname mismatch，前面提过，是SAN配置不全。排查时优先用openssl s_client直连端口，把问题定位在服务端还是客户端SDK层面。
回滚方面，如果新证书有问题，直接用备份的旧证书重新执行一遍setting-x509-cert --node-cert-file即可，服务端切换本身是秒级生效的。所以轮换前务必备份当前生效的节点证书和CA私钥，建议连同openssl的配置文件一起打包存档。如果是CA全换的场景，回滚还需要把客户端的truststore恢复到备份版本，这也是为什么truststore要先做备份。
最后提两点运维规范。第一，把证书到期检查纳入监控，可以用openssl x509 -checkend 2592000判断证书是否在30天内到期，配合定时任务提前告警，别等客户端报错才发现。第二，轮换操作尽量安排在业务低峰期，虽然标准流程可以做到不中断，但如果配置有遗漏，低峰期的故障影响面会小很多。证书轮换本身不复杂，复杂的永远是那些没被文档记录清楚的现有配置，动手前多做核对，比事后救火划算得多。
Couchbase证书轮换certificate rotation修改时间：2026-09-16 02:16:36