PhxQueue：超详细部署与使用教程

PhxQueue 是腾讯开源的基于 Paxos 协议的高可用、高吞吐、高可靠分布式持久化队列，保证 At-Least-Once（至少一次）投递，已在微信支付、微信公众平台等核心业务大规模生产验证。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

PhxQueue 是腾讯自研并开源的分布式消息队列，核心存储层基于 Paxos 协议做多副本强一致复制，对外承诺 At-Least-Once Delivery（至少一次投递，配合严格的实时对账）。它最初服务于微信支付、微信公众平台等对「消息不丢、严格有序、可回放」要求极高的业务场景。作者为 Junjie Liang、Tao He、Haochuan Cui、Qing Huang、Jiatao Xu，联系邮箱 phxteam@tencent.com。与 PhxSQL 同属腾讯 Phx 系列基础组件，共享 PhxPaxos、PhxRPC、libco 等底层库。

1.2 核心功能

• 严格实时对账保证投递：通过对账机制确保消息至少被消费一次，解决「消息丢了」问题。
• 服务端批量入队：Producer 侧批量 enqueue，提升吞吐。
• 严格有序出队：同一队列内消息严格按序出队。
• 多消费组：一个 Topic 可被多个 Consumer Group 独立消费，互不干扰。
• 出队限速：支持 Consumer 侧出队速率限制。
• 出队回放（Replay）：支持按游标重新消费历史消息，适合对账、补数据场景。
• 消费者负载均衡：多 Consumer 节点间自动分摊队列分片。
• 全模块可扩展：Store / Consumer / Lock / Scheduler 均可独立水平扩容。
• 多区域部署：Store 或 Lock 节点支持多地域（异地灾备）部署。

1.3 技术架构

官方 Wiki 「事务消息使用简介」页给出了 PhxQueue 的整体架构图（下图为官方原图）：Producer（发布者）通过 Prepare/Commit/Rollback 与 Store 交互；Store 是基于 Paxos 多副本的队列存储；Consumer 从 Store 拉取并消费；Lock 是独立的分布式锁模块；Scheduler 汇聚 Consumer 全局负载信息做容灾与负载均衡。

各模块职责：

下图为官方 Wiki 中的事务消息两阶段提交流程（Prepare → Commit/Rollback）：

二、环境要求

主要端口与二进制（官方 etc/ 示例配置）：

配置文件位于 etc/：globalconfig.conf（全局）、topicconfig.conf（Topic）、storeconfig.conf（Store）、consumerconfig.conf（Consumer）、schedulerconfig.conf（Scheduler）、lockconfig.conf（Lock）。

三、部署方式

下面给出三条路径：① 一键编译 + 本机 Quickstart（最快验证）→ ② Docker 官方镜像上手 → ③ 分布式多机部署（生产）。

3.1 方式一：一键编译 + 本机 Quickstart（最快验证）

步骤 1：一键构建

git clone https://github.com/Tencent/phxqueue
cd phxqueue/
bash build.sh

build.sh 会自动拉取并编译全部依赖（protobuf、glog、leveldb、phxpaxos、phxrpc、libco），首次构建耗时较长。

步骤 2：提升文件句柄

ulimit -n 65535        # 必须 > 4000，否则运行报文件句柄错误

步骤 3：启动 3 个 Store 节点

bin/store_main -c etc/store_server.0.conf
bin/store_main -c etc/store_server.1.conf
bin/store_main -c etc/store_server.2.conf

查看进程与日志：

ps -ef | grep store_main
tail -f log/store.0/store_main.INFO
tail -f log/store.1/store_main.INFO
tail -f log/store.2/store_main.INFO

⚠️ 官方提示：至少要启动 2 个 Store 节点，否则日志会报： MASTERSTAT: ERR: Propose err. paxos_ret 404 ...

步骤 4：启动 3 个 Consumer 节点

bin/consumer_main -c etc/consumer_server.0.conf
bin/consumer_main -c etc/consumer_server.1.conf
bin/consumer_main -c etc/consumer_server.2.conf

tail -f log/consumer.0/consumer_main.INFO
tail -f log/consumer.1/consumer_main.INFO
tail -f log/consumer.2/consumer_main.INFO

步骤 5：发送测试请求

# 用官方回显 Producer 发消息
bin/test_producer_echo_main
# 预期输出：produce echo succeeded!

# 观察任一 Consumer 日志（3 个节点之一）
tail -f log/consumer.0/consumer_main.INFO
# 预期输出：consume echo succeeed! ...

步骤 6：跑压测

bin/producer_benchmark_main 10 5 5 10
# 观察 Consumer 日志，预期形如：
# INFO: Dequeue ret 0 topic 1000 consumer_group_id 1 store_id 1 queue_id 44
#       size 1 prev_cursor_id 9106 next_cursor_id 9109

3.2 方式二：Docker 官方镜像上手

官方 Wiki「Quickstart with Docker」提供镜像 phxqueue/phxqueue：

# 1) 拉取镜像
docker pull phxqueue/phxqueue
docker images | grep phxqueue

# 2) 启动一个容器
docker run --name=phxqueue_1 phxqueue/phxqueue
docker ps -a | grep phxqueue

# 3) 另开终端进入容器操作
docker exec -it phxqueue_1 bash
# 容器内即可执行方式一中的 store_main / consumer_main / test_producer_echo_main

Docker 方式适合单机快速体验；真实生产按方式三多机部署。

3.3 方式三：分布式多机部署（生产）

正式部署时每个节点应落在独立机器，并为每台机器配置对应 etc/*.conf。把 etc/ 下 6 个配置文件（globalconfig / topicconfig / storeconfig / consumerconfig / schedulerconfig / lockconfig）分发到所有目标机器并按本机 IP 调整后启动。

部署 Store 节点（3 台机器，-d 后台运行）

bin/store_main -c etc/store_server.0.conf -d
bin/store_main -c etc/store_server.1.conf -d
bin/store_main -c etc/store_server.2.conf -d

部署 Consumer 节点（3 台机器）

bin/consumer_main -c etc/consumer_server.0.conf -d
bin/consumer_main -c etc/consumer_server.1.conf -d
bin/consumer_main -c etc/consumer_server.2.conf -d

可选：部署 Lock 节点（3 台机器）

Lock 是独立的分布式锁模块，可对外提供通用分布式锁服务。若不需要事务消息等依赖 Lock 的能力，可在 topicconfig.conf 中设置 skip_lock = 1 关闭：

bin/lock_main -c etc/lock_server.0.conf -d
bin/lock_main -c etc/lock_server.1.conf -d
bin/lock_main -c etc/lock_server.2.conf -d

可选：部署 Scheduler 节点（3 台机器）

Scheduler 汇聚 Consumer 全局负载信息用于容灾与负载均衡；必须先部署 Lock 才能部署 Scheduler。不部署时 Consumer 按配置权重静态分配。关闭方式为 topicconfig.conf 中 use_dynamic_scale = 0：

bin/scheduler_main -c etc/scheduler_server.0.conf -d
bin/scheduler_main -c etc/scheduler_server.1.conf -d
bin/scheduler_main -c etc/scheduler_server.2.conf -d

源码手动编译（不使用 build.sh 时）

# 1) 准备依赖目录
export DEP_PREFIX=/your/directory/for/dependency

# 2) 编译 protobuf 与 glog（必须 -fPIC + --prefix）
cd protobuf && ./configure CXXFLAGS=-fPIC --prefix=$DEP_PREFIX && make && make install
cd glog && ./configure CXXFLAGS=-fPIC --prefix=$DEP_PREFIX && make && make install
# 建立软链
rm -r $PHXQUEUE_DIR/third_party/protobuf/
rm -r $PHXQUEUE_DIR/third_party/glog/
ln -s $DEP_PREFIX $PHXQUEUE_DIR/third_party/protobuf
ln -s $DEP_PREFIX $PHXQUEUE_DIR/third_party/glog

# 3) 编译 LevelDB 到 third_party/leveldb，并 ln -s out-static lib

# 4) 在 third_party/phxpaxos、third_party/phxrpc 下分别编译；
#    git clone libco 到 third_party/colib/

# 5) 编译 PhxQueue
cd $PHXQUEUE_DIR/
make
# 产物：二进制在 bin/，库在 lib/，示例配置在 etc/

3.4 验证部署成功（通用）

1. 3 个 Store 节点日志 store_main.INFO 无 paxos_ret 404 报错，Paxos 选主成功；
2. bin/test_producer_echo_main 输出 produce echo succeeded!；
3. 任一 Consumer 日志出现 consume echo succeeed!；
4. 压测 bin/producer_benchmark_main 10 5 5 10 后 Consumer 日志出现形如 Dequeue ret 0 topic 1000 ... next_cursor_id 9109 的正常出队记录。

3.5 清理测试数据（危险操作）

# 清理日志（可重复执行）
bash log/clear_log.sh
# 清理数据（不可逆，仅在确认无重要数据时执行）
bash data/clear_data.sh

官方警告：data/clear_data.sh 会永久删除数据，生产环境严禁在存有重要数据的集群上执行。

四、使用方法

4.1 基础用法：Producer / Consumer 最小闭环

PhxQueue 官方提供 Echo 演示程序作为最小用法：

# 启动 Store + Consumer 后，直接运行内置回显 Producer
bin/test_producer_echo_main
# 预期：produce echo succeeded!

业务接入时按官方 Wiki 的 MQTT / RPC 客户端方式集成（见下文进阶）。

4.2 常用命令与压测

# 压测（参数含义以 etc/ 配置与官方 README 为准）
bin/producer_benchmark_main 10 5 5 10

# 查看某节点日志
tail -f log/store.0/store_main.INFO
tail -f log/consumer.0/consumer_main.INFO

# 查看进程
ps -ef | grep -E "store_main|consumer_main|lock_main|scheduler_main"

Consumer 日志中关键字段：

4.3 进阶功能

• 事务消息（两阶段提交）：Producer 先 Prepare 提交预消息，本地事务执行成功后 Commit、失败 Rollback；官方 Wiki「事务消息使用简介」给出了完整时序图（即本文 1.3 节图）。
• MQTT 接入：官方 Wiki 提供「使用 MQTT 客户端连接 PhxQueue」与「PhxQueue 部署 MQTT 支持」专页，可用 MQTT 协议直接收发消息。
• 多消费组：同一 Topic 下多个 consumer_group 独立消费，互不影响。
• 出队回放：基于 prev_cursor_id 重新消费历史消息，用于对账与补数据。
• 出队限速：在 Consumer 配置中按消费组/队列设置速率上限。
• 消费者负载均衡：多 Consumer 节点自动分摊 queue_id；部署 Scheduler 后按全局负载动态调整。
• 多区域部署：Store 或 Lock 节点可跨地域部署，做异地灾备。
• 配置调优：所有行为开关集中在 etc/*.conf，如 skip_lock = 1（关 Lock）、use_dynamic_scale = 0（关 Scheduler）。

4.4 适用场景

• 支付、账务等要求「消息绝不丢失、严格有序、可对账回放」的交易链路；
• 微信公众平台类大规模消息推送，要求高吞吐 + 多消费组；
• 需要多副本强一致（Paxos）而非最终一致的队列场景；
• 需要独立分布式锁服务（Lock 模块）与动态负载均衡（Scheduler）的配套基础设施；
• 希望用 MQTT 协议接入现有 IoT/移动推送链路的团队。

五、常见问题排查（FAQ）

Q1：Store 日志报 MASTERSTAT: ERR: Propose err. paxos_ret 404 - 原因：Paxos 多数派未形成——只启动了 1 个 Store 节点。 - 解决：至少启动 2 个、推荐 3 个 Store 节点（store_main -c etc/store_server.0/1/2.conf），确认节点间网络互通。

Q2：启动即报 too many open files / 文件句柄错误 - 原因：PhxQueue 同时打开大量文件，默认 ulimit 不足。 - 解决：ulimit -n 65535（官方要求 > 4000），并写入 /etc/security/limits.conf 永久生效；systemd 启动时在 unit 中配 LimitNOFILE。

Q3：Consumer 日志一直没有 consume 记录 - 原因：Store 未就绪、Producer 未真正写入，或 Consumer 配置的 topic/queue 与 Producer 不一致。 - 解决：先确认 bin/test_producer_echo_main 返回 produce echo succeeded!；再核对 etc/consumer_server.*.conf 中 topic 配置与 Store 一致；检查 log/store.0/store_main.INFO 是否有写入。

Q4：编译报 protobuf/glog 链接错误（-fPIC） - 原因：glog、protobuf 编译时未加 -fPIC。 - 解决：按官方手动编译步骤，./configure CXXFLAGS=-fPIC --prefix=$DEP_PREFIX 重新编译，再软链到 third_party/。

Q5：Lock 不部署，Producer 发消息失败 - 原因：某些能力（如事务消息）依赖 Lock 模块。 - 解决：要么部署 3 个 Lock 节点（lock_main -c etc/lock_server.*.conf -d），要么在 topicconfig.conf 中明确设置 skip_lock = 1 关闭相关能力。

Q6：部署了 Scheduler 但负载均衡不生效 - 原因：Scheduler 依赖 Lock，Lock 未部署会导致 Scheduler 异常。 - 解决：先起 Lock 再起 Scheduler；或在 topicconfig.conf 中设 use_dynamic_scale = 0 退回按权重静态分配。

Q7：测试后想清理数据但误删了生产数据 - 原因：data/clear_data.sh 不可逆。 - 解决：官方明确警告该命令永久删除数据，仅可在测试集群执行；生产环境提前做好数据目录备份，严禁在生产跑该脚本。

Q8：Docker 容器内进程看不到 - 原因：容器前台进程退出或镜像内启动参数不对。 - 解决：docker ps -a 看状态；docker exec -it phxqueue_1 bash 进入后手动按顺序启动 store_main / consumer_main；确认容器内 ulimit 已足够。

六、部署注意事项与最佳实践

1. Store 至少 3 节点且跨机：Paxos 需要多数派，3 节点是最小可用规模；生产跨机甚至跨机架部署，避免单点故障。
2. ulimit 前置：所有节点（含 systemd / Docker 启动）务必把文件句柄提到 65535+，这是官方明确强调的硬性要求。
3. 按需启停可选模块：Lock、Scheduler 都是可选的；用 skip_lock = 1 / use_dynamic_scale = 0 精简架构，避免不必要的依赖。
4. Scheduler 依赖 Lock：要动态负载均衡必须先部署 Lock，不要反过来。
5. 配置文件逐机分发：etc/*.conf 要按每台机器的实际 IP / 数据目录调整后再分发，不要直接拷同一份。
6. 数据目录与磁盘：Store 持久化队列堆积，按业务峰值堆积量规划磁盘；建议 SSD，定期清理已消费但未回放的历史数据。
7. 时钟同步：Paxos 选主与实时对账依赖节点时钟，所有节点配 NTP。
8. 至少一次语义：PhxQueue 保证 At-Least-Once，业务 Consumer 需做幂等（消息可能重复投递），不要假设 Exactly-Once。
9. 回放能力善用：基于 cursor_id 回放是对账利器，但回放前确认不会重复触发副作用（下游幂等）。
10. BSD 许可友好：PhxQueue 采用 BSD 3-Clause，商用与二次开发限制较小，但仍需保留版权声明。

七、参考资料

• GitHub 仓库：https://github.com/Tencent/phxqueue
• 官方 Wiki 首页：https://github.com/Tencent/phxqueue/wiki
• Docker 快速上手：https://github.com/Tencent/phxqueue/wiki/Quickstart-with-Docker
• 事务消息使用简介：https://github.com/Tencent/phxqueue/wiki/事务消息使用简介
• PhxQueue 配置说明：https://github.com/Tencent/phxqueue/wiki/PhxQueue配置
• 使用 MQTT 客户端连接 PhxQueue：https://github.com/Tencent/phxqueue/wiki/使用MQTT客户端连接PhxQueue
• PhxQueue 部署 MQTT 支持：https://github.com/Tencent/phxqueue/wiki/PhxQueue部署MQTT支持
• 依赖组件 PhxPaxos：https://github.com/Tencent/phxpaxos
• 依赖组件 PhxRPC：https://github.com/Tencent/phxrpc
• 依赖组件 libco：https://github.com/Tencent/libco
• 联系邮箱：phxteam@tencent.com