2. Confluent Cloud与Confluent Platform环境搭建

事件驱动系统的开发从一条可靠的消息通道开始。Confluent 提供两种形态：Confluent Cloud 是全托管的 SaaS 服务，集群、Broker、Schema Registry、Connector 都由平台运维，开发者只关心 Topic 与 ACL；Confluent Platform 是自托管发行版，包含 Kafka Broker、Schema Registry、Kafka Connect、ksqlDB、Control Center 等组件，需要自行部署与运维。本节的目标是让两种环境都达到“可连接、可认证、可读写”的状态，并给出可复现的验证方法。

一、Confluent Cloud：账号、环境与集群

注册 Confluent Cloud 后，资源按三层组织：Organization（组织） 是最外层计费与成员边界；Environment（环境） 用于隔离 dev / staging / prod，每个环境有独立的 RBAC 与网络配置；Cluster（集群） 是实际承载 Topic 的 Kafka 集群。创建集群时需选择云厂商（AWS / GCP / Azure）、区域（Region）和集群类型：Basic 适合开发验证，Standard 提供更高可用性与弹性，Dedicated 提供专属容量与私有网络。教学示例中可选择 AWS / us-west-2 / Basic，成本最低且创建通常在数分钟内完成。

集群创建完成后，控制台会给出 Bootstrap Server（引导服务器） 地址，形如 pkc-xxxxx.us-west-2.aws.confluent.cloud:9092。这是所有客户端连接的入口，务必记录。随后在 API Keys 页面创建 API Key 与 Secret，它同时用于认证与鉴权。注意：Secret 只在创建时显示一次，需立即保存到密码管理器或本地环境变量文件。

二、Confluent Platform：本地与自托管部署

本地开发常用两种方式：Confluent CLI 一键启动单机版，或使用 Docker Compose 启动多组件栈。Confluent CLI 的 confluent local services start 会在本地拉起 Kafka、Schema Registry、Connect、ksqlDB、Control Center，适合快速验证；Docker Compose 更适合模拟多 Broker 与多组件协作。自托管场景下，Bootstrap Server 通常是 localhost:9092 或 broker:29092（容器内网）。

无论哪种形态，客户端工具链是统一的：Confluent CLI 用于管理资源，kafka-topics / kafka-console-producer / kafka-console-consumer 用于命令行读写，kcat 是轻量替代品，各语言客户端（Java、Python、Go 等）用于应用集成。安装后应确认版本与 PATH 生效。

# 安装 Confluent CLI（macOS 示例）
brew install confluentinc/tap/cli

# 登录 Confluent Cloud
confluent login --save

# 查看环境与集群
confluent environment list
confluent kafka cluster list

# 本地启动 Confluent Platform
confluent local services start
confluent local services status

三、访问控制：认证与授权

Confluent Cloud 的访问控制分两层：认证（Authentication） 确认“你是谁”，通过 API Key/Secret 或 SASL/OAUTHBEARER 完成；授权（Authorization） 确认“你能做什么”，通过 RBAC 角色或 ACL 控制。RBAC 角色包括 OrganizationAdmin、EnvironmentAdmin、CloudClusterAdmin、DeveloperRead、DeveloperWrite 等，粒度到环境或集群。若使用 ACL，则需为具体 Principal 授予 Topic 的 READ / WRITE / DESCRIBE 等权限。

Confluent Platform 默认使用 PLAINTEXT，生产环境应启用 SASL_SSL 或 mTLS。Schema Registry 也需单独配置认证，通常复用同一套 API Key 或独立凭据。一个常见误区是只配置了 Broker 认证却忘记 Schema Registry，导致序列化阶段报 401。

四、网络连通性验证

连通性验证应分层进行：先验证 DNS 与 TCP 端口可达，再验证 TLS 握手，最后验证认证与读写。Cloud 集群的 9092 端口通常对公网开放，但若启用了 PrivateLink 或 VPC Peering，则需从对应 VPC 内访问。自托管环境需确认防火墙、安全组与 advertised.listeners 配置一致。

# 1. DNS 解析
nslookup pkc-xxxxx.us-west-2.aws.confluent.cloud

# 2. TCP 端口连通
nc -vz pkc-xxxxx.us-west-2.aws.confluent.cloud 9092

# 3. 列出 Topic（验证认证与授权）
confluent kafka topic list --cluster lkc-xxxxx

# 4. 创建并读写测试 Topic
confluent kafka topic create demo-topic --partitions 3
echo "hello-confluent" | confluent kafka topic produce demo-topic
confluent kafka topic consume demo-topic --from-beginning

若第 3 步返回 401，说明 API Key 无效或权限不足；若返回超时，说明网络不通；若第 4 步能生产但消费为空，检查消费组偏移与 Topic 分区。建议把上述命令整理为一份环境自检脚本，每次切换环境后执行一次。

五、常见问题与排查要点

环境搭建阶段最常遇到三类问题。第一类是认证失败：API Key 与 Secret 不匹配、Key 被禁用、或 Schema Registry 未配置独立凭据，表现为 401 Unauthorized。第二类是网络不通：DNS 解析失败、安全组未放行 9092、或 PrivateLink 场景下从公网访问，表现为连接超时。第三类是授权不足：Key 有效但缺少 Topic 的 WRITE 权限，表现为 403 Forbidden 或 TopicAuthorizationException。

排查时建议按“先网络后认证、先认证后授权”的顺序推进，避免在权限问题上反复怀疑网络。对于自托管环境，还需检查 advertised.listeners 是否与客户端实际访问的地址一致——这是容器化部署中最隐蔽的坑：Broker 返回的元数据地址若为容器内网名，宿主机客户端将无法连接。

六、环境自检清单（可直接使用）