SpringBoot系列之集成Pulsar教程

SpringBoot集成Apache Pulsar实战（Linux环境手动安装JDK+Pulsar）

本文全程基于Linux（CentOS 7为例） 环境，先通过手动方式安装OpenJDK 17.0.12，再完成Pulsar 2.11.1的下载安装，最终实现SpringBoot与Pulsar的消息生产/消费集成，所有步骤可直接复制执行，新手也能落地。

系列博客专栏：

SpringBoot与微服务实践系列博客

一、环境说明

组件	版本/配置	说明
Linux发行版	CentOS 7.x（适配Ubuntu）	主流服务器系统
JDK	OpenJDK 17.0.12（手动装）	Pulsar 2.11.1服务端依赖JDK 17+
Apache Pulsar	2.11.1（Linux单机部署）	稳定版，满足基础开发
SpringBoot	3.2.0	与Spring Pulsar 3.2.0兼容
网络要求	Linux服务器可联网	若无网络可离线传安装包

二、Linux手动安装OpenJDK 17.0.12（有效链接版）

2.1 卸载系统自带JDK（避免版本冲突）

先清理系统预装的OpenJDK，防止与手动安装的版本冲突：

bash 复制代码

# 1. 查看系统已安装的Java组件
rpm -qa | grep java

# 2. 卸载所有预装Java组件（无输出则跳过）
sudo rpm -e --nodeps $(rpm -qa | grep java) 2>/dev/null

# Ubuntu/Debian系统执行以下命令卸载：
# sudo apt remove -y openjdk* && sudo apt autoremove -y

2.2 手动下载OpenJDK 17.0.12（有效链接）

选用Adoptium官方归档的稳定版本，直接在Linux中下载（解决链接失效问题）：

bash 复制代码

# 1. 切换到临时目录（存放安装包）
cd /tmp

# 2. 下载OpenJDK 17.0.12（x64架构，有效链接）
sudo wget https://github.com/adoptium/temurin17-binaries/releases/download/jdk-17.0.12%2B7/OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz

# 【离线备用】若Linux无网络：
# 1. 本地下载上述链接的压缩包；
# 2. 通过scp上传到Linux的/tmp目录：
# scp 本地路径/OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz root@Linux服务器IP:/tmp/

2.3 解压并安装JDK到指定目录

Linux软件推荐安装到/usr/local/（统一管理），解压后重命名简化路径：

bash 复制代码

# 1. 解压压缩包到/usr/local/
sudo tar -zxvf OpenJDK17U-jdk_x64_linux_hotspot_17.0.12_7.tar.gz -C /usr/local/

# 2. 重命名目录（简化后续配置，必做）
sudo mv /usr/local/jdk-17.0.12+7 /usr/local/jdk17

2.4 配置全局环境变量（关键步骤）

修改系统配置文件，让所有用户/进程都能识别JDK 17.0.12：

bash 复制代码

# 1. 编辑全局配置文件
sudo vi /etc/profile

# 2. 在文件末尾粘贴以下内容（复制即可）
export JAVA_HOME=/usr/local/jdk17
export JRE_HOME=${JAVA_HOME}/jre
export CLASSPATH=.:${JAVA_HOME}/lib:${JRE_HOME}/lib
export PATH=${JAVA_HOME}/bin:${PATH}

# 3. 保存退出（按Esc → 输入:wq → 回车）

2.5 生效配置并验证JDK安装

bash 复制代码

# 1. 让环境变量立即生效（无需重启系统）
source /etc/profile

# 2. 验证JDK版本（核心验证）
java -version
javac -version

成功标志：输出如下内容（版本号为17.0.12即可）：

复制代码

openjdk version "17.0.12" 2024-07-16 LTS
OpenJDK Runtime Environment Temurin-17.0.12+7 (build 17.0.12+7-LTS)
OpenJDK 64-Bit Server VM Temurin-17.0.12+7 (build 17.0.12+7-LTS, mixed mode, sharing)

三、Linux安装Apache Pulsar 2.11.1（单机版）

3.1 下载并解压Pulsar安装包

bash 复制代码

# 1. 切换到/usr/local目录
cd /usr/local

# 2. 下载Pulsar 2.11.1（Apache镜像站，速度快）
sudo wget https://archive.apache.org/dist/pulsar/pulsar-2.11.1/apache-pulsar-2.11.1-bin.tar.gz

# 3. 解压安装包
sudo tar -zxvf apache-pulsar-2.11.1-bin.tar.gz

# 4. 创建软链接（简化后续命令）
sudo ln -s apache-pulsar-2.11.1 pulsar

3.2 启动Pulsar并验证

bash 复制代码

# 1. 后台启动Pulsar（输出日志到pulsar.log）
nohup  /usr/local/pulsar/bin/pulsar > /usr/local/pulsar/pulsar.log 2>&1 &

# 2. 检查Pulsar端口（6650=消息端口，8080=管理端口）
netstat -tlnp | grep -E "6650|8080"

成功标志：端口6650/8080被Java进程占用（Pulsar基于JDK 17.0.12运行），示例输出：

复制代码

tcp6       0      0 :::6650                 :::*                    LISTEN      12345/java
tcp6       0      0 :::8080                 :::*                    LISTEN      12345/java

3.3 开放端口（远程连接必做）

若SpringBoot项目不在同一台Linux服务器，需开放端口：

bash 复制代码

# CentOS 7开放端口
sudo firewall-cmd --add-port=6650/tcp --permanent
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reload

# Ubuntu/Debian开放端口
# sudo ufw allow 6650/tcp
# sudo ufw allow 8080/tcp
# sudo ufw reload

3.4 命令行测试Pulsar 2.11.1功能

验证Pulsar服务正常，避免后续集成踩坑：

bash 复制代码

# 1. 生产一条测试消息
/usr/local/pulsar/bin/pulsar-client produce test-topic --messages 'Hello Pulsar 2.11.1!'

# 2. 消费消息（输出包含Hello Pulsar 2.11.1!即成功）
/usr/local/pulsar/bin/pulsar-client consume test-topic --subscription-name test-sub --num-messages 1

成功输出示例：

复制代码

Hello Pulsar 2.11.1!

四、SpringBoot集成Pulsar 2.11.1（完整代码）

4.1 创建Maven项目（pom.xml）

确保依赖版本与Pulsar 2.11.1、JDK 17.0.12兼容，核心引入spring-pulsar-starter：

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>springboot-pulsar</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-pulsar</name>
    <description>Demo project for Spring Boot integrate Pulsar 2.11.1</description>
    <properties>
        <java.version>17</java.version>
        <!-- 明确指定Pulsar版本，与安装的2.11.1保持一致 -->
        <pulsar.version>2.11.1</pulsar.version>
    </properties>

    <repositories>
        <!-- 1. 优先配置Spring官方仓库（拉取pulsar依赖） -->
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
            <releases><enabled>true</enabled></releases>
            <snapshots><enabled>false</enabled></snapshots>
        </repository>

        <!-- 2. 保留阿里云仓库（拉取其他依赖） -->
        <repository>
            <id>aliyunmaven</id>
            <name>Aliyun Maven Repository</name>
            <url>https://maven.aliyun.com/repository/public</url>
            <releases><enabled>true</enabled></releases>
            <snapshots><enabled>false</enabled></snapshots>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- SpringBoot集成Pulsar核心依赖，适配2.11.1版本 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-pulsar</artifactId>
            <exclusions>
                <!-- 排除默认依赖，强制使用指定的2.11.1版本 -->
                <exclusion>
                    <groupId>org.apache.pulsar</groupId>
                    <artifactId>pulsar-client</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <!-- 显式引入Pulsar 2.11.1客户端，匹配服务端版本 -->
        <dependency>
            <groupId>org.apache.pulsar</groupId>
            <artifactId>pulsar-client</artifactId>
            <version>${pulsar.version}</version>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
            <scope>provided</scope>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>17</source>
                    <target>17</target>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

4.2 配置Pulsar连接（application.yml）

关键：service-url填写Linux服务器的实际IP（而非localhost），否则远程连接失败：

yaml 复制代码

spring:
  application:
    name: springboot-pulsar
  pulsar:
    client:
      service-url: pulsar://127.0.0.1:6650
      tenant: public
      namespace: default
    producer:
      send-timeout: 5000
    consumer:
      ack-mode: AUTO
      #service-url: pulsar+ssl://127.0.0.1:6651 # 开启 SSL 安全通信的连接配置方式
      #auth-plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationToken # 示例使用 JWT Token 认证插件
      #authentication:
      #  token: YOUR_PULSAR_TOKEN # token 信息

    defaults:
      type-mappings:
        - message-type: com.example.pulsar.model.Message
          schema-info:
            schema-type: JSON

    listener:
      concurrency: 2

4.3 消息实体类（Message.java）

java 复制代码

package com.example.pulsar.model;

import lombok.Data;

@Data
public class Message {
    private String content; // 消息内容
    private String sender;  // 发送者
    private Long sendTime;  // 发送时间戳
}

4.4 实现消息生产者

java 复制代码

package com.example.pulsar.service;

import com.example.pulsar.model.Message;
import org.apache.pulsar.client.api.PulsarClientException;
import org.springframework.pulsar.core.PulsarTemplate;
import org.springframework.stereotype.Service;

@Service
public class PulsarProducerService {

    private final PulsarTemplate<Message> pulsarTemplate;

    public PulsarProducerService(PulsarTemplate<Message> pulsarTemplate) {
        this.pulsarTemplate = pulsarTemplate;
    }

    public void send(Message msg) throws PulsarClientException {
        pulsarTemplate.send("example-topic", msg);
    }

}

4.5 实现消息消费者

java 复制代码

package com.example.pulsar.service;

import com.example.pulsar.model.Message;
import org.apache.pulsar.client.api.SubscriptionType;
import org.springframework.pulsar.annotation.PulsarListener;
import org.springframework.pulsar.listener.AckMode;
import org.springframework.pulsar.listener.Acknowledgement;
import org.springframework.stereotype.Service;

@Service
public class PulsarConsumerService {

    @PulsarListener(
            subscriptionName = "example-subscription",
            topics = "example-topic",
            subscriptionType = SubscriptionType.Shared,
            ackMode = AckMode.MANUAL // 手动模式
    )
    public void consume(Message message, Acknowledgement ack) {
        try {
            System.out.println("Received message: " + message.getContent());
            ack.acknowledge();
        } catch (Exception e) {
            ack.nack();
        }
    }
}

4.6 编写测试接口（PulsarController.java）

java 复制代码

package com.example.pulsar.controller;

import com.example.pulsar.model.Message;
import com.example.pulsar.service.PulsarProducerService;
import org.apache.pulsar.client.api.PulsarClientException;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/pulsar")
public class PulsarController {

    private final PulsarProducerService producerService;

    public PulsarController(PulsarProducerService producerService) {
        this.producerService = producerService;
    }

    @PostMapping("/send")
    public String sendMessage(@RequestBody Message message) throws PulsarClientException {
        producerService.send(message);
        return "Message sent to Pulsar successfully!";
    }
}

4.7 编写启动类

java 复制代码

package com.example.pulsar;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringbootPulsarApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringbootPulsarApplication.class, args);
    }
}

五、Linux环境运行SpringBoot项目

5.1 打包项目

在本地开发机执行打包命令（或在Linux中安装Maven 3.8+后打包）：

bash 复制代码

mvn clean package -DskipTests

打包完成后，target目录会生成springboot-pulsar-0.0.1-SNAPSHOT.jar。

5.2 上传并运行

bash 复制代码

# 1. 上传jar包到Linux的/opt目录（替换为你的服务器IP）
scp target/springboot-pulsar-0.0.1-SNAPSHOT.jar root@192.168.1.100:/opt/

# 2. 登录Linux，进入/opt目录
cd /opt

# 3. 后台运行项目（指定JDK 17.0.12，输出日志到app.log）
nohup /usr/local/jdk17/bin/java -jar springboot-pulsar-0.0.1-SNAPSHOT.jar > app.log 2>&1 &

# 4. 查看日志（验证生产/消费）
tail -f app.log

5.3 测试消息发送

通过curl调用接口发送消息，验证集成效果：

bash 复制代码

# 在Linux服务器执行curl命令
curl -X POST \
  http://127.0.0.1:8080/api/pulsar/send \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello Pulsar 2.11.1 + JDK 17.0.12",
    "sender": "SpringBoot"
  }'

成功响应 ：Message sent to Pulsar 2.11.1 successfully!

日志验证 ：查看app.log可看到消费者输出：

复制代码

[1728456789000] Received message: Hello Pulsar 2.11.1 + JDK 17.0.12, sender: SpringBoot

六、常见问题与解决方案

问题1：JDK 17.0.12环境变量配置后不生效

原因：未执行source /etc/profile，或JAVA_HOME路径与解压目录不一致；
解决：重新执行source /etc/profile，检查/usr/local/jdk17目录是否存在（需与解压后的重命名一致）。

问题2：SpringBoot连接Pulsar 2.11.1超时

原因：Linux防火墙未开放6650端口，或service-url填了localhost/127.0.0.1（仅本机可访问）；
解决：开放6650端口，确保service-url是Linux服务器的公网/内网实际IP。

问题3：Pulsar 2.11.1启动失败

原因：JDK版本低于17（需17.0.12），或6650/8080端口被占用；
解决：验证java -version为17.0.12，执行lsof -i:6650找到占用进程，kill -9 进程ID后重启Pulsar。

问题4：Pulsar客户端与服务端版本不兼容

原因：SpringBoot依赖的Pulsar客户端版本与服务端2.11.1不一致；
解决：在pom.xml中显式指定pulsar.version=2.11.1，并排除默认依赖（参考4.1节pom.xml）。

总结

核心步骤：Linux手动安装OpenJDK 17.0.12（有效链接）→ 安装并启动Pulsar 2.11.1 → SpringBoot配置Pulsar连接（填服务器实际IP）→ 实现生产/消费 → 打包运行；
关键配置 ：JDK环境变量需全局生效，Pulsar的service-url必须填Linux服务器IP，客户端版本需与服务端2.11.1一致；
验证标准：JDK 17.0.12版本验证通过、Pulsar 2.11.1端口监听正常、SpringBoot日志输出生产/消费成功，即为集成完成。

此教程适配Linux生产环境的基础部署，如需Pulsar集群、消息持久化、SSL认证等进阶功能，可基于此扩展。