一、引言：为什么选择Docker部署Pulsar单机版？

Apache Pulsar作为云原生消息流平台，其分布式架构设计天然支持高可用与横向扩展。但在开发测试或轻量级生产场景中，单机部署能以更低的资源成本快速验证功能，而Docker容器化技术则进一步简化了环境配置与依赖管理。通过Docker部署Pulsar单机版，开发者可避免直接操作主机环境，实现“一键启动”的便捷体验，同时保持与集群部署一致的核心功能。

二、环境准备：前置条件与工具安装

1. 硬件与系统要求

资源最低配置：4核CPU、8GB内存、50GB磁盘空间（生产环境建议翻倍）
操作系统：Linux（推荐Ubuntu 20.04+/CentOS 7+）或macOS（需Docker Desktop）
网络要求：确保主机可访问互联网（用于拉取镜像）

2. Docker与Docker Compose安装

Linux系统安装示例

# 卸载旧版本（如有）
sudo apt-get remove docker docker-engine docker.io containerd runc
# 安装依赖
sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release
# 添加Docker官方GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# 添加稳定版仓库
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 安装Docker引擎
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
# 验证安装
sudo docker run hello-world

Docker Compose安装（v2.0+）

sudo curl -L "https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

三、Pulsar单机Docker部署步骤

1. 直接使用官方镜像启动

Apache Pulsar官方提供了预构建的Docker镜像，可通过单容器模式快速启动。

# 拉取最新稳定版镜像
docker pull apachepulsar/pulsar:2.12.0
# 启动单机版Pulsar（包含Broker、BookKeeper、ZooKeeper）
docker run -it \
  --name pulsar-standalone \
  -p 6650:6650 \
  -p 8080:8080 \
  --mount source=pulsar-data,target=/pulsar/data \
  --mount source=pulsar-conf,target=/pulsar/conf \
  apachepulsar/pulsar:2.12.0 \
  /bin/bash -c "bin/pulsar standalone"

参数说明：

-p 6650:6650：暴露Pulsar协议端口（生产者/消费者连接）
-p 8080:8080：暴露REST API端口（管理接口）
--mount：使用Docker卷持久化数据（避免容器删除后数据丢失）

2. 使用Docker Compose管理（推荐）

创建docker-compose.yml文件，实现更灵活的配置：

version: '3.8'
services:
  pulsar:
    image: apachepulsar/pulsar:2.12.0
    container_name: pulsar-standalone
    ports:
      - "6650:6650"
      - "8080:8080"
    volumes:
      - pulsar-data:/pulsar/data
      - pulsar-conf:/pulsar/conf
    command: >
      sh -c "bin/apply-config-from-env.py conf/standalone.conf &&
             bin/pulsar standalone"
    environment:
      # 可选：覆盖默认配置
      # PULSAR_MEM: "-Xms512m -Xmx512m"
      # clusterName: "standalone"
volumes:
  pulsar-data:
  pulsar-conf:

启动服务：

docker-compose up -d

四、验证部署与基础操作

1. 检查服务状态

docker logs pulsar-standalone | grep "Started"
# 应输出类似：Started Apache Pulsar Broker service

2. 使用Pulsar CLI工具

进入容器交互模式：

docker exec -it pulsar-standalone /bin/bash

创建测试Topic并生产/消费消息：

# 创建Topic
bin/pulsar-admin topics create-partitioned-topic \
  persistent://public/default/test-topic -p 1
# 生产消息
bin/pulsar-client produce persistent://public/default/test-topic \
  -n 10 -m "Hello Pulsar"
# 消费消息
bin/pulsar-client consume persistent://public/default/test-topic \
  -s "test-subscriber" -n 0

3. 访问Web管理界面

浏览器访问 http://localhost:8080，登录后（默认无密码）可查看：

Topic列表与统计信息
集群健康状态
函数工作流（如启用Function Worker）

五、常见问题与优化建议

1. 内存不足错误

现象：容器频繁重启，日志中出现OutOfMemoryError。
解决方案：

调整JVM内存参数（通过PULSAR_MEM环境变量）
示例：-e PULSAR_MEM="-Xms1g -Xmx1g"

2. 数据持久化配置

问题：容器删除后数据丢失。
改进方案：

使用Docker卷或绑定主机目录：

volumes:
  - /host/path/data:/pulsar/data
  - /host/path/conf:/pulsar/conf

3. 性能调优参数

参数	说明	推荐值（单机）
`bookkeeper.journal.dir`	BookKeeper日志目录	`/pulsar/data/bookkeeper/journals`
`managedLedgerDefaultEnsembleSize`	副本数	`1`（单机模式）
`managedLedgerDefaultWriteQuorum`	写入副本数	`1`

六、扩展场景：启用Function Worker

若需运行Pulsar Functions，需在启动命令中添加参数：

command: >
  sh -c "bin/apply-config-from-env.py conf/standalone.conf &&
         bin/pulsar standalone --functions-worker-enabled true"

验证Function运行：

# 创建示例Function
bin/pulsar-admin functions create \
  --tenant public \
  --namespace default \
  --name exclamation-function \
  --inputs persistent://public/default/test-topic \
  --output persistent://public/default/exclamation-topic \
  --jar examples/api-examples.jar \
  --classname org.apache.pulsar.functions.api.examples.ExclamationFunction

七、总结与最佳实践

资源隔离：为Pulsar容器分配专用资源，避免与其他服务竞争。
备份策略：定期备份/pulsar/data目录，尤其是生产环境。
版本管理：固定Docker镜像标签（如2.12.0），避免自动升级导致兼容性问题。
监控集成：通过Prometheus+Grafana监控关键指标（如消息堆积、延迟）。

通过Docker部署Pulsar单机版，开发者可在10分钟内完成从环境准备到功能验证的全流程，为后续集群部署或功能开发奠定坚实基础。

Pulsar单机Docker部署指南：快速搭建消息流平台