单机模式oom需调低jvm堆内存并禁用内置zookeeper；集群元数据初始化失败主因是zk地址不一致或残留节点；broker注册失败多因advertisedaddress配置错误；client连接拒绝须检查防火墙、安全组及docker/k8s端口映射。
单机模式启动失败：pulsar standalone 报 java.lang.OutOfMemoryError
小内存服务器（比如 2G RAM）跑 pulsar standalone 极大概率直接 OOM，因为默认 JVM 参数对 Broker + BookKeeper + ZooKeeper 三合一进程过于激进。
解决办法不是换机器，而是调低堆内存并禁用非必要组件：
- 编辑
conf/standalone.conf，把brokerHeapSizeMB改成512，bookieHeapSizeMB改成384 - 在
bin/pulsar启动脚本顶部追加：export PULSAR_MEM="-Xms256m -Xmx512m" - 如果只是测试生产/消费逻辑，可跳过 ZooKeeper 内嵌——改用外部 ZooKeeper（哪怕单节点），再执行
bin/pulsar standalone --no-zk-run
注意：--no-zk-run 不代表不用 ZooKeeper，它只是不拉起内置实例；你必须提前运行好 ZooKeeper 并在 conf/standalone.conf 中配好 zookeeperServers。
集群部署时 pulsar initialize-cluster-metadata 命令反复失败
这个命令失败通常不是权限或网络问题，而是元数据已存在却未清理干净，或者 --configuration-store 和 --zookeeper 指向了不同 ZK 实例。
关键检查点：
- 确认
--zookeeper和--configuration-store的地址完全一致（端口、IP、域名都不能差一点） - 用
echo stat | nc zk-host 2181验证 ZK 是否可连且处于 leader 状态 - 如果之前执行过但失败，先手动清空 ZK 路径：
./bin/pulsar-admin namespaces list若报错“namespace not found”，大概率是 /ledgers 或 /config 节点残留；此时需用zkCli.sh连上去删掉/ledgers、/config、/pulsar（谨慎操作）
别依赖“重试”——Pulsar 对元数据一致性极其严格，一次写入失败后残留半成品比没写更麻烦。
Broker 启动后无法注册到 ZooKeeper，log 里反复出现 Failed to register broker
这问题表面是网络不通，实际常因 advertisedAddress 配置错误。Broker 会把自己这个地址告诉 ZooKeeper，消费者和 Producer 也靠它来连接；如果填的是 localhost 或内网 IP，外部客户端必然连不上。
正确做法：
- 在
conf/broker.conf中，advertisedAddress必须填**客户端能直连的 IP 或域名**（例如公网 IP、K8s Service 名、宿主机可解析的 hostname） -
bindAddresses可设为0.0.0.0，表示监听所有接口；但advertisedAddress绝不能是0.0.0.0 - 验证方式：启动后查 ZK 中的 broker 注册路径：
ls /brokers，然后get /brokers/xxx，看返回 JSON 里的address字段是否是你期望的地址
很多团队卡在这一步数小时，就因为 advertisedAddress 沿用了默认值或抄了文档里的 localhost 示例。
Java Client 连不上 pulsar://host:6650，抛 Connection refused
Broker 默认只监听 0.0.0.0:6650，但 Linux 防火墙或云厂商安全组往往默认拦截该端口。这不是 Pulsar 配置问题，而是基础设施层漏掉了。
快速定位步骤：
- 在 Broker 服务器上执行：
ss -tlnp | grep :6650，确认进程确实在监听 - 在同一台机器上执行：
telnet localhost 6650，通则说明服务正常，问题出在网络层 - 从客户端机器执行：
telnet broker-host 6650；不通就立刻检查防火墙：sudo firewall-cmd --list-ports（CentOS）或sudo ufw status（Ubuntu），开放 6650 - 云服务器务必检查安全组规则——6650 TCP 入方向必须放行，且源 IP 设置合理（不要只写 0.0.0.0/0）
最容易被忽略的是：Docker 部署时没加 -p 6650:6650，或 Kubernetes Service 没暴露该端口。连不上时，先别翻 Pulsar 日志，先做端口连通性验证。
