schema registry必须根据kafka集群模式选择对应元数据协调方式：kraft模式下配置kafkastore.bootstrap.servers并设schema.registry.group.id，禁用zookeeper.connect；zookeeper模式下配置kafkastore.connection.url，二者互斥，混用将导致启动失败且无明确错误提示。
Schema Registry 必须和 Kafka 集群对齐元数据协调方式：用 KRaft 就不能配 zookeeper.connect，用 ZooKeeper 就不能开 kafkastore.bootstrap.servers —— 混用直接启动失败，日志里只报 Failed to start SchemaRegistry，不提示具体原因。
确认 Kafka 集群模式再选 Schema Registry 启动方式
Schema Registry 本身不存状态，但依赖外部存储做 schema 元数据同步。它支持两种后端：
-
kafkastore.connection.url：指向 ZooKeeper 地址（仅限旧版 Kafka + ZK 模式） -
kafkastore.bootstrap.servers：指向 Kafka broker 列表（KRaft 模式或 Kafka 3.3+ 无 ZK 部署）
二者互斥。查你 Kafka 是怎么启的：
- 如果
server.properties里有zookeeper.connect=...→ 用 ZooKeeper 模式 - 如果
server.properties里有process.roles=broker,controller→ 必须用 Kafka 原生存储模式
配错会导致服务卡在 Waiting for master election，CPU 占用低但端口不监听。
修改 schema-registry.properties 的关键项
Confluent Schema Registry 默认配置是面向 ZooKeeper 的，KRaft 下必须显式切换。重点改这三处：
-
listeners=http://0.0.0.0:8081：监听地址，生产环境别留0.0.0.0，换成内网 IP -
kafkastore.bootstrap.servers=PLAINTEXT://192.168.1.42:9092,PLAINTEXT://192.168.1.41:9092：填 Kafka broker 的advertised.listeners地址，不是listeners -
schema.registry.group.id=schema-registry-group：KRaft 模式下必须设，用于内部消费者组协调；ZooKeeper 模式可不设
删掉或注释掉 kafkastore.connection.url，否则会优先走 ZK 路径并静默失败。
启动时常见报错和对应解法
启动命令始终用：./bin/schema-registry-start etc/schema-registry/schema-registry.properties
- 报
ERROR Failed to start SchemaRegistry (io.confluent.kafka.schemaregistry.rest.SchemaRegistryRestApplication)：大概率是kafkastore.bootstrap.servers地址不可达，用telnet 192.168.1.42 9092测通不通 - 报
org.apache.kafka.common.errors.TimeoutException: Call(callName=listNodes, deadlineMs=...)：Kafka broker 没开listener.security.protocol.map或没暴露 controller 端口（KRaft 模式需要 controller.quorum.listeners） - 启动成功但
curl http://localhost:8081/subjects返回空数组：正常，说明服务起来了，只是还没注册任何 schema
验证 Schema Registry 是否真正可用
光看进程和端口不够，要走一次完整写读链路：
- 用
curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" --data '{"schema": "{\"type\":\"string\"}"}' http://localhost:8081/subjects/test-value/versions注册一个简单 schema - 返回
{"id":1}才算成功；如果返回 500 或超时，说明底层 Kafka topic_schemas没自动创建（检查 Kafka 是否允许 auto.create.topics.enable=true，或手动建：./bin/kafka-topics.sh --create --topic _schemas --partitions 1 --replication-factor 1 --bootstrap-server localhost:9092） - 再
curl http://localhost:8081/subjects/test-value/versions/latest查 schema 内容，能拿到 JSON 就说明读通了
注意：_schemas topic 默认 1 分区、RF=1，生产环境务必调高分区数和副本数，否则成单点瓶颈——这点容易被忽略，等压测时才暴露。
