CKafka 支持为开启 SASL_SSL 接入方式的实例配置自定义 SSL 证书。配置后，客户端与 CKafka Broker 之间的数据传输将通过指定证书进行 TLS 加密；如选择双向认证，客户端还需提供由指定 CA 签发的客户端证书，以提升接入安全性。
本文介绍如何在 CKafka 控制台设置、更换和解绑自定义 SSL 证书。
前置要求
在配置自定义 SSL 证书前，请检查实例是否满足以下要求：
检查项 | 要求说明 |
实例版本 | Serverful 专业版 2.4 及 2.8 版本实例和 Serverless 实例支持使用 SASL_SSL 接入点并配置自定义 SSL 证书。 |
实例状态 | 实例需处于正常运行中，实例状态健康，且未在执行扩容、缩容、升配、降配、可用区变更、版本升级等变配任务。 |
证书状态 | 证书需已在腾讯云 SSL 证书服务中完成签发或托管，且证书状态正常。 |
权限要求 | 当前账号需具备 SSL 证书服务的读取权限。首次操作时，需根据页面提示完成 CKafka 访问 SSL 证书服务的角色授权。 |
接入方式 | 实例需创建或计划创建 SASL_SSL 类型的 VPC 接入点或公网接入点。 |
客户端准备 | 客户端需支持 TLS/SASL_SSL 配置。如使用双向认证，需提前准备客户端证书、私钥和信任链配置。 |
域名校验 | CKafka 自定义证书暂不支持按接入域名进行证书域名校验，客户端需关闭 hostname/domain 校验。 |
注意：
对于在旧版本新购时已配置过 SSL 证书的实例，其证书配置仍为旧版配置。首次设置或更换自定义证书时，系统会触发 Broker 滚动重启。滚动重启完成后，实例将自动升级为新版证书配置。建议在业务低峰期执行相关操作，并确保客户端具备自动重连能力。
若实例已满足自定义 SSL 证书的使用条件，但控制台未展示 SSL 证书配置入口，可能是实例底层配置未完成升级。您可以先执行一次涉及数据迁移的升配操作，升配完成后再查看 SSL 证书配置入口是否开启。
对于新购实例，如需使用自定义证书，建议在实例创建完成后尽快完成证书替换，再接入正式业务流量，以减少证书变更对业务连接的影响。
风险提示
设置、更换或解绑自定义 SSL 证书属于实例配置变更操作，操作前请关注以下风险：
连接闪断风险
设置、更换或解绑证书可能触发 Broker 滚动重启。滚动重启期间，客户端连接可能出现短暂闪断。建议在业务低峰期执行证书变更，并提前确认客户端配置以下能力：
生产者和消费者开启自动重连。
合理配置 retries、retry.backoff.ms、request.timeout.ms、session.timeout.ms 等参数。
消费端业务逻辑具备幂等或重复消费处理能力。
生产端根据业务要求配置 acks 和重试策略。
证书兼容性风险
客户端需要信任服务端证书链，双向认证场景下，服务端还会校验客户端证书。如果客户端使用了固定证书、固定 CA、证书指纹校验或证书钉扎策略，证书更换后可能导致连接失败。
更换证书前，请确认：
客户端信任库已包含新证书的根 CA 或中间 CA。如使用双向认证，请确保客户端证书由服务端配置的 CA 签发，且客户端证书、私钥和密码配置正确。
Java 客户端已更新 truststore。
客户端已关闭域名校验或 hostname 校验。
认证方式说明
认证方式 | 说明 | 适用场景 | 客户端要求 |
单向认证 | 使用自定义服务端证书进行 TLS 加密，客户端校验服务端证书，服务端不校验客户端证书。 | 适用于需要使用企业自有证书或指定证书链的场景。 | 配置 security.protocol=SASL_SSL，并在客户端信任库中配置服务端证书对应的 CA 或完整证书链。 |
双向认证 | 使用自定义服务端证书，并配置客户端 CA 证书。客户端校验服务端证书，服务端校验客户端证书。 | 适用于金融、政企、跨组织数据交换等对终端身份认证要求较高的场景。 | 配置 security.protocol=SASL_SSL，在客户端信任库中配置服务端证书链，并配置客户端证书和私钥。 |
默认证书 | 使用 CKafka 默认 SSL 证书进行 TLS 加密传输，无需绑定自定义证书。 | 适用于仅需加密传输、不要求使用企业自有证书的场景。 注意： 使用默认证书可能无法满足更高等级的安全合规要求。为提升实例访问安全性，建议您尽快更换为自有证书。 | 配置 security.protocol=SASL_SSL，并信任 CKafka 默认 SSL 证书链。 |
变更前安全检查
设置、更换或解绑自定义 SSL 证书属于实例配置变更操作。提交变更前，CKafka 会对实例进行安全检查，避免在高风险状态下重启导致数据丢失，造成不必要的损失。常见检查项包括但不限于：
检查项 | 说明 |
单副本检查 | 若实例中存在单副本 Topic 或分区，Broker 重启期间会影响数据可用性，引起部分数据丢失，系统将阻断本次变更。 |
未同步副本检查 | 若实例中存在未同步副本，说明副本数据尚未完成同步。此时执行证书设置、更换或解绑操作，可能增加分区不可用、消息同步延迟或数据一致性风险，系统可能阻断本次变更。 |
实例负载检查 | 若实例当前 CPU、内存、磁盘、网络、连接数或请求量负载较高，变更期间可能出现连接抖动，系统可能阻断本次变更。 |
Broker 健康检查 | 若存在 Broker 异常、分区未完成同步、ISR 不健康等情况，系统可能阻断变更。 |
任务冲突检查 | 若实例正在执行扩缩容、迁移、升级、路由变更等任务，需等待当前任务完成后再操作。 |
如安全检查未通过，建议根据控制台提示先完成风险治理，例如补齐副本、降低业务流量、等待任务完成或修复实例健康状态后再重试。
注意：
使用 API 方式配置证书时，部分接口可能提供 force_restart 参数，用于控制是否强制提交变更。当安全检查存在风险时，不建议直接开启强制执行。仅在明确理解风险、已完成业务侧容灾和客户端重连准备的情况下，才可以使用强制参数。
设置自定义证书
1. 登录 CKafka 控制台。
2. 在左侧导航栏选择实例列表，选择好地域后，单击目标实例的“ID”，进入实例基本信息页面。
3. 在左侧导航栏中，选择SSL 管理。
4. 首次进入 SSL 管理页面时，需勾选授权 CKafka 下载应用 SSL 证书。该授权用于允许 CKafka 从 SSL 证书服务读取并加载证书内容。
5. 初始实例绑定的都是默认证书，单击设置自定义证书按钮，进入配置弹窗。CKafka 支持切换不同认证方式，切换认证方式将触发 Broker 滚动重启，重启期间可能出现连接闪断，建议在业务低峰期操作，并确保客户端具备自动重连能力。
6. 在集群变更前置安全检查通过的情况下，根据业务需要完成相关配置。
注意：
如您选择双向认证，请确保服务端证书与 CA 证书相匹配，且客户端证书由该 CA 签发，否则客户端可能无法通过 TLS 握手，导致连接失败。
7. 确认配置无误后，单击提交。
8. 提交后，实例将会进入变配中状态，可以在实例详情页观察实例状态，等待任务完成，期间不可进行变配等相关操作。
9. 证书绑定成功后，可以刷新页面更新证书状态，绑定状态将会变为已绑定。
10. 完成自定义 SSL 证书设置后，根据客户端配置指南更新生产者和消费者的 SASL_SSL 配置。并观察实例连接数、生产消费流量、错误日志和客户端 SSL 握手日志，使用生产者和消费者客户端验证消息收发是否正常，确认业务恢复正常。
解绑证书
如不再使用自定义 SSL 证书，可在 SSL 管理页面解绑当前证书。解绑自定义证书后，实例将退回使用 CKafka 默认 SSL 证书的状态。解绑操作同样会触发证书配置变更，部分版本或旧版证书配置模板的实例可能触发 Broker 滚动重启。
1. 登录 CKafka 控制台。
2. 在左侧导航栏选择实例列表，选择好地域后，单击目标实例的“ID”，进入实例基本信息页面。
3. 在左侧导航栏中，选择SSL 管理。
4. 在证书列表中，找到当前已绑定的证书。在操作列单击解绑。
5. 阅读风险提示后，确认解绑。双向认证解绑任意证书会同时解绑 CA 证书和服务端证书。如果客户端只信任原自定义证书或其 CA 链，解绑后可能无法连接实例。生产环境不建议在业务高峰期执行解绑操作。
6. 确认配置无误后，单击提交，等待解绑任务完成。
操作建议
为降低证书变更对业务的影响，建议按以下流程操作：
1. 确认证书已在 SSL 证书服务中完成签发或托管，且证书状态正常。更换证书前，将新证书对应的 CA 链加入客户端信任库，确保客户端兼容新旧证书。
2. 在业务低峰期执行设置、更换或解绑证书操作，降低连接闪断对业务的影响。并确认生产者和消费者已配置自动重连、重试、超时和消费容错逻辑。
3. 如控制台提示单副本、负载高或实例不健康等风险，请先完成治理后再执行变更。
4. 建议在证书到期前预留充足时间完成证书更换和客户端验证，避免证书过期导致连接失败。
