内外网映射情况下的Kafka 部署指南⚠ 文档说明本文档中的 IP 地址和路径均为示例值部署时请根据实际环境替换PUBLIC_IP公网入口地址如123.xx.xx.xxINTERNAL_IP服务器内网地址如20.xx.xx.xx/path/to/your/kafka/baseKafka 安装基础目录/home/your_username个人用户主目录本文档针对DataChecker 数据校验工具提供完整的 Kafka 部署方案面向个人用户在内网服务器上使用 KRaft 模式无需 ZooKeeper。部署背景环境限制限制项说明用户权限个人账号xjt_ai无 root 权限网络环境Kafka 部署在内网服务器Windows 开发机在公网需通过 NAT/端口映射访问存储限制/usr1分区为只读模式数据和日志需存放在/home目录端口限制公网入口端口由运维统一分配如10073内网端口可自行选择核心挑战内外网隔离公网客户端无法直接访问内网 IP需通过 NAT 转发Kafka 地址告知机制Broker 会向客户端返回advertised.listeners地址需确保不同网络的客户端拿到正确地址只读分区安装包可放在/usr1但数据和日志必须放在/home无 root 权限无法配置 systemd 服务需使用setsid后台启动一、网络拓扑说明1.1 部署架构┌──────────────────────────────────────────────────────────────────────────┐ │ 网络拓扑 │ ├──────────────────────────────────────────────────────────────────────────┤ │ │ │ Windows 开发机 (公网) 内网 Kafka 服务器 │ │ ┌─────────────┐ ┌──────────────────┐ ┌───────────────┐ │ │ │ DataChecker │ ──→ PUBLIC_IP:10073 ──→ ... ──→ │ INTERNAL_IP │ │ │ │ 代码运行 │ (公网入口/NAT) (网络转换) │ :2111 (公网) │ │ │ └─────────────┘ └──────────────────┘ │ :2112 (本地) │ │ │ └───────────────┘ │ │ │ │ 本地操作: kafka-topics.sh --bootstrap-server INTERNAL_IP:2112 │ │ 远程连接: bootstrap-servers: PUBLIC_IP:10073 │ │ │ └──────────────────────────────────────────────────────────────────────────┘1.2 地址与端口汇总角色地址说明公网入口PUBLIC_IP:10073Windows 开发机连接地址替换为实际公网 IPKafka 服务器内网 IPINTERNAL_IP服务器实际地址替换为实际内网 IPPLAINTEXT 监听端口2111公网访问入口NAT 转发目标端口LOCAL 监听端口2112内网/本地操作入口CONTROLLER 端口9093KRaft 控制器通信1.3 双端口设计原理Kafka 的网络模型有一个关键特性客户端初次连接后Broker 会把advertised.listeners中的地址告诉客户端后续所有通信都使用这个地址。核心矛盾advertised.listeners只能返回客户端能访问的地址。如果只配公网地址公网客户端正常但内网客户端也要走 NAT效率低且可能不可用如果只配内网地址内网客户端正常但公网客户端收到内网地址无法连接解决方案使用两个不同的 listener让不同来源的客户端拿到不同的地址Listener监听端口广播地址用途PLAINTEXT2111PUBLIC_IP:10073Windows 开发机远程连接LOCAL2112INTERNAL_IP:2112内网服务器本地操作二、项目 Kafka 需求梳理需求项说明Kafka 版本4.3.1KRaft 模式无需 ZooKeeperBootstrap Server公网PUBLIC_IP:10073/ 本地INTERNAL_IP:2112安全协议PLAINTEXT无 SASL/SSL 认证消费者组checkgroup数据校验消费组消息序列化StringSerializer/StringDeserializer单条消息上限最大 64MBfetch-max-bytes: 67108864Topic 管理由应用自动创建/删除KafkaAdminServiceTopic 数量动态生成单次任务通常 2 ~ 20 个 Topic分区数默认 16num.partitions16运行模式KRaft 模式单节点brokercontroller三、环境准备3.1 硬件要求最低资源推荐CPU2 核内存4GBKafka 堆内存分配 1~2GB磁盘20GB 可用空间需在/home目录下OSLinuxCentOS 7/8, Ubuntu 18.04/20.04/22.043.2 软件依赖Java 17Kafka 4.x 要求 Java 11# 检查 Java 版本java-version3.3 安装目录约定路径说明JAVA_HOME/path/to/your/kafka/base/javaKAFKA_HOME/path/to/your/kafka/base/kafka/kafka_2.13-4.3.1数据目录/home/your_username/kafka-logs/kafka-data运行日志/home/your_username/kafka-logs/kafka-run-logs/kafka.out配置文件/path/to/your/kafka/base/kafka/kafka_2.13-4.3.1/config/server.properties注意由于/usr1等分区可能为只读模式数据和日志目录应放在个人主目录/home/your_username下。四、安装步骤4.1 安装 JDK 17# 解压 JDK 到指定目录安装包已提前下载mkdir-p/path/to/your/kafka/base/javatar-xzf/path/to/your/kafka/base/bisheng-jdk-17.0.18-b13-linux-aarch64.tar.gz-C/path/to/your/kafka/base/java --strip-components1# 配置环境变量个人账号级别cat~/.bashrcEOF export JAVA_HOME/path/to/your/kafka/base/java export PATH$JAVA_HOME/bin:$PATH EOF# 立即生效source~/.bashrc# 验证java-version4.2 解压 Kafka# 创建目录并解压安装包已提前下载mkdir-p/path/to/your/kafka/base/kafkacd/path/to/your/kafka/base/kafkatar-xzf/path/to/your/kafka/base/kafka_2.13-4.3.1.tgz# 创建数据和日志目录放在 /home确保可写mkdir-p/home/your_username/kafka-logs/kafka-data /home/your_username/kafka-logs/kafka-run-logs五、配置 KafkaKRaft 模式5.1 生成集群 IDKAFKA_HOME/path/to/your/kafka/base/kafka/kafka_2.13-4.3.1${KAFKA_HOME}/bin/kafka-storage.sh random-uuid# 输出示例: psciFaaJRcG55QP3lpcd5Q5.2 修改配置文件编辑${KAFKA_HOME}/config/server.properties# 基本配置 # 每个 Broker 的唯一 ID单机部署保持为 1 node.id1 # 控制器角色单机部署两者都选 process.rolesbroker,controller # 控制器仲裁地址单机只用本地 controller.quorum.bootstrap.serverslocalhost:9093 # 监听器配置 # 监听所有网卡提供公网和本地两个入口 listenersPLAINTEXT://0.0.0.0:2111,CONTROLLER://0.0.0.0:9093,LOCAL://0.0.0.0:2112 # 对外广播地址公网客户端看到公网地址本地客户端看到内网地址 # 注意PUBLIC_IP 和 INTERNAL_IP 需替换为实际地址 advertised.listenersPLAINTEXT://PUBLIC_IP:10073,LOCAL://INTERNAL_IP:2112 # 监听器协议映射 listener.security.protocol.mapCONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,LOCAL:PLAINTEXT,SSL:SSL,SASL_PLAINTEXT:SASL_PLAINTEXT,SASL_SSL:SASL_SSL inter.broker.listener.namePLAINTEXT controller.listener.namesCONTROLLER # 日志存储 # 数据目录放在 /home/usr1 等分区可能为只读 log.dirs/home/your_username/kafka-logs/kafka-data # Topic 默认配置 # 默认分区数需 ≥ 项目最大分区数 16 num.partitions16 # 默认副本数单机必须为 1 default.replication.factor1 min.insync.replicas1 offsets.topic.replication.factor1 transaction.state.log.replication.factor1 transaction.state.log.min.isr1 # 允许自动创建 Topic项目依赖 KafkaAdminService 管理 Topic auto.create.topics.enabletrue # 消息大小 # 单条消息最大 64MB与项目 fetch-max-bytes / buffer-memory 匹配 message.max.bytes67108864 replica.fetch.max.bytes67108864 max.request.size67108864 # 网络与IO # Socket 缓冲区与消息大小匹配 socket.send.buffer.bytes67108864 socket.receive.buffer.bytes67108864 socket.request.max.bytes67108864 # 日志保留策略 # 日志保留 72 小时纯校验场景数据生命周期短可按需调整 log.retention.hours72 # 日志分段大小 512MB log.segment.bytes536870912 # 性能优化 num.network.threads3 num.io.threads4 background.threads45.3 格式化存储目录# 使用第 5.1 步生成的 UUID注意添加 --standalone 参数${KAFKA_HOME}/bin/kafka-storage.shformat\-t上面生成的UUID\-c${KAFKA_HOME}/config/server.properties\--standalone输出Formatting /home/your_username/kafka-logs/kafka-data with metadata.version 4.3-IV0表示成功。六、启动与验证6.1 启动 Kafka后台启动无 root 权限使用 setsidexportJAVA_HOME/path/to/your/kafka/base/javaexportPATH$JAVA_HOME/bin:$PATHexportLOG_DIR/home/your_username/kafka-logs/kafka-run-logscd/path/to/your/kafka/base/kafka/kafka_2.13-4.3.1 setsid bin/kafka-server-start.sh config/server.properties$LOG_DIR/kafka.out21停止服务${KAFKA_HOME}/bin/kafka-server-stop.sh6.2 验证运行状态# 检查进程psaux|grepkafka|grep-vgrep# 检查端口监听ss-tlnp|grep2111ss-tlnp|grep2112# 查看日志tail-100f/home/your_username/kafka-logs/kafka-run-logs/kafka.out6.3 功能验证本地操作使用 LOCAL 端口 2112KAFKA_HOME/path/to/your/kafka/base/kafka/kafka_2.13-4.3.1BS_LOCALINTERNAL_IP:2112# 创建测试 Topic${KAFKA_HOME}/bin/kafka-topics.sh --bootstrap-server${BS_LOCAL}--create--topictest-topic--partitions1--replication-factor1# 查看 Topic 列表${KAFKA_HOME}/bin/kafka-topics.sh --bootstrap-server${BS_LOCAL}--list# 测试生产消息echohello datachecker|${KAFKA_HOME}/bin/kafka-console-producer.sh --bootstrap-server${BS_LOCAL}--topictest-topic# 测试消费消息${KAFKA_HOME}/bin/kafka-console-consumer.sh --bootstrap-server${BS_LOCAL}--topictest-topic --from-beginning --max-messages1# 删除测试 Topic${KAFKA_HOME}/bin/kafka-topics.sh --bootstrap-server${BS_LOCAL}--delete--topictest-topic七、项目配置对接7.1 修改项目 Kafka 连接地址将项目配置文件中的bootstrap-servers改为公网入口地址。开发环境datachecker-extract/src/main/resources/application.yml和datachecker-check/src/main/resources/application.ymlspring:kafka:bootstrap-servers:PUBLIC_IP:10073生产环境config/application.ymlspring:kafka:bootstrap-servers:PUBLIC_IP:100737.2 验证公网连通性从 Windows 开发机验证能否通过公网地址访问 Kafka# Windows PowerShell替换 PUBLIC_IP 为实际地址Test-NetConnection-ComputerName PUBLIC_IP-Port 10073# 或者用 telnettelnet PUBLIC_IP 10073启动 DataChecker 项目后查看日志是否有以下类似输出KafkaAdminService - Connected to kafka, topic list: [...]八、常用运维命令KAFKA_HOME/path/to/your/kafka/base/kafka/kafka_2.13-4.3.1BS_LOCALINTERNAL_IP:2112# 查看所有 Topic${KAFKA_HOME}/bin/kafka-topics.sh --bootstrap-server${BS_LOCAL}--list# 查看某个 Topic 详情分区、副本等${KAFKA_HOME}/bin/kafka-topics.sh --bootstrap-server${BS_LOCAL}--describe--topicCHECK_xxx# 查看消费者组列表${KAFKA_HOME}/bin/kafka-consumer-groups.sh --bootstrap-server${BS_LOCAL}--list# 查看消费者组消费进度${KAFKA_HOME}/bin/kafka-consumer-groups.sh --bootstrap-server${BS_LOCAL}--groupcheckgroup--describe# 删除 Topic${KAFKA_HOME}/bin/kafka-topics.sh --bootstrap-server${BS_LOCAL}--delete--topictopic-name# 查看磁盘使用du-sh/home/your_username/kafka-logs/kafka-data/# 查看 Kafka 运行日志tail-100f/home/your_username/kafka-logs/kafka-run-logs/kafka.out# 查看 GC 日志tail-100f/home/your_username/kafka-logs/kafka-run-logs/kafkaServer-gc.log九、常见问题Q1: 提示InconsistentClusterIdException格式化存储目录时使用的 UUID 与当前数据目录不匹配。# 清除旧数据后重新格式化rm-rf/home/your_username/kafka-logs/kafka-data/*${KAFKA_HOME}/bin/kafka-storage.shformat-tUUID-c${KAFKA_HOME}/config/server.properties--standaloneQ2: 消息发送失败提示消息过大检查 Kafka 端的message.max.bytes和replica.fetch.max.bytes是否设置为 64MB67108864。Q3: Topic 自动删除不生效确认auto.create.topics.enabletrue且项目配置中auto-delete-topic不为 0。Q4: 客户端连接超时或无法连接确认内网 Kafka 已正常启动ss -tlnp | grep 2111确认advertised.listeners配置为公网地址PUBLIC_IP:10073确认公网转发PUBLIC_IP:10073 → INTERNAL_IP:2111的 NAT/端口映射已配置且生效确认中间防火墙没有拦截Q5: 本地操作连接失败本地操作必须使用INTERNAL_IP:2112LOCAL 端口不要使用INTERNAL_IP:2111PLAINTEXT 端口会返回公网地址。Q6: 单机部署性能不够增加KAFKA_HEAP_OPTS堆内存如-Xmx4g -Xms2g将log.dirs指向 SSD适当增加num.io.threadsQ7: 是否需要 ZooKeeper不需要。本文档使用 Kafka 4.x 的 KRaft 模式不依赖 ZooKeeper更简单、更轻量。十、总结步骤关键命令/操作1. 安装 JDK 17解压到/path/to/your/kafka/base/java配置环境变量2. 解压 Kafkatar -xzf kafka_2.13-4.3.1.tgz3. 创建目录/home/your_username/kafka-logs/kafka-data和/home/your_username/kafka-logs/kafka-run-logs4. 生成集群 IDkafka-storage.sh random-uuid5. 配置 server.properties双端口监听 公网/本地广播地址替换 PUBLIC_IP 和 INTERNAL_IP6. 格式化存储kafka-storage.sh format -t UUID -c server.properties --standalone7. 启动服务setsid bin/kafka-server-start.sh config/server.properties ...无 root 权限8. 本地操作使用--bootstrap-server INTERNAL_IP:21129. 项目连接bootstrap-servers: PUBLIC_IP:10073核心原则单节点 KRaft 模式 双端口监听PLAINTEXT LOCAL PLAINTEXT 协议 自动创建 Topic。网络要点利用advertised.listeners的地址告知机制让公网客户端拿到公网地址内网客户端拿到内网地址。部署要点个人账号部署无 root 权限数据目录放在/home使用setsid后台启动。