本部分针对在为 Managed Service for Apache Kafka 配置和使用 mTLS 时遇到的常见问题提供了问题排查指南。
更新集群时出错
运行 gcloud managed-kafka clusters update 或 gcloud managed-kafka clusters create 命令时，您可能会遇到以下错误。
SSL 主体映射规则无效
您会收到类似于以下内容的错误消息：
INVALID_ARGUMENT: The request was invalid: invalid SSL principal mapping
rule: \"RULE:INVALID-RULE\". The rule must be of the format DEFAULT or
RULE:pattern/replacement/[LU]
INVALID_ARGUMENT: The request was invalid: invalid SSL principal mapping
rules: \"RULE:\\nRULE:,DEFAULT\" contains a newline
出现这些出错提示是因为为 ssl-principal-mapping-rules 标志提供的值格式不正确或包含无效字符。
更正规则以符合所需格式，并验证规则字符串是否不包含任何换行符。如需详细了解 ssl-principal-mapping-rules 标志，请参阅主体映射。
CA 池配置无效
您会收到类似于以下内容的错误消息：
INVALID_ARGUMENT: The request was invalid:
ca_pool: project/managed-kafka-test/locations/us-central1/test-ca-pool
doesn't match the expected format: projects/{project}/locations/{location}/caPools/{caPool}
INVALID_ARGUMENT: The request was invalid: maximum of 10 CA pools can be specified
INVALID_ARGUMENT: The request was invalid: duplicate CA pool:
projects/managed-kafka-test/locations/us-central1/caPools/test-ca-pool.
All CA pools must be unique
出现这些出错提示的原因是，为 mtls-ca-pools 标志提供的 CA 池列表无效。检查 CA 池列表，并验证以下内容：
所有 CA 池名称均采用完整资源格式：
projects/PROJECT_ID/locations/LOCATION/caPools/CA_POOL_ID。列表中没有重复的 CA 池。
CA 池的总数不超过 10 个。
集群不支持 mTLS
您收到类似于以下内容的错误消息：
FAILED_PRECONDITION: Invalid resource state for \"tls_config\": mTLS is not
supported for this cluster because it was created before the mTLS feature
was added. Please create a new cluster to use mTLS.
出现此出错提示是因为您尝试在功能推出之前创建的集群上启用 mTLS。如出错提示所示，您必须创建新集群才能使用 mTLS。您无法在 2025 年 6 月 24 日之前创建的现有不符合条件的集群上启用 mTLS。
客户端连接失败
如果客户端应用无法连接到集群的 mTLS 端点，请检查是否存在以下常见配置问题：
引导地址不正确：请验证您使用的引导地址是否正确。 您必须使用以
9192而不是9092结尾的 mTLS 引导地址。客户端证书无效或不正确：验证客户端证书是否有效、是否已过期，以及是否由集群上配置的某个 CA 池中的 CA 签发。
客户端密钥库配置不正确：确认客户端应用的配置正确指向其密钥库和信任库文件，并且密码正确无误。
Kafka ACL 不正确：验证您是否已为经过身份验证的主账号创建必要的 Kafka ACL。请注意，主体是证书的主题名称（或映射的别名），并以
User:为前缀。例如，如果主体名称为test-user，则相应的主账号为User:test-user。
Cloud Logging 中的错误
集群的日志（可在 Logging 中查看）中可能会显示以下错误。如需详细了解日志记录，请参阅使用 Logs Explorer 查看日志。
受信任证书存储区大小超过上限
您会看到类似如下内容的日志条目：
Trust store size X bytes exceeds the maximum allowed size of 1000 KiB
and cannot be updated.
出现此出错提示是因为配置的 CA 池中所有 CA 证书的总大小超过了 1000 KiB 的限制。
检查 CA 池中的证书，以减小总大小。 这可能涉及移除大型或不必要的证书，或优化 CA 链。
未能从 CA 池中提取证书
您会看到类似如下内容的日志条目：
Managed Service for Apache Kafka failed to fetch certificates from
CA pool <ca-pool-name>. Error: <error>.
如果 Managed Service for Apache Kafka 服务代理无法从指定的 CA 池检索证书，则会显示此出错提示。消息的错误部分提供了更多详细信息。此失败的常见原因是缺少 IAM 权限。
验证 Managed Service for Apache Kafka 服务代理是否对包含 CA 池的项目具有 CA Pool Reader (roles/privateca.poolReader) 角色。这在跨项目设置中尤为重要。
如需详细了解配置 mTLS 所需的权限，请参阅所需的角色和权限。