Ubuntu 22.04 源码编译部署 Apache Pegasus 2.5.0 指南

Ubuntu 22.04 从 0 到 1 源码编译部署 Apache Pegasus 2.5.0：构建依赖与 run.sh build（--enable_rocksdb_portable 规避 AVX-512 SIGILL 崩溃）、onebox 单机集群启停（3 meta+3 replica+collector+ZooKeeper）、shell 连通验证与常见问题

Apache PegasusPegasusApache安装部署Ubuntu 22.04NoSQL2026/10/15

Ubuntu 22.04 源码编译部署 Apache Pegasus 2.5.0 指南

目标：在 Ubuntu 22.04 服务器上从零完成 Apache Pegasus 2.5.0 的源码编译，并以官方 onebox 模式在一台机器上拉起完整集群（3 个 MetaServer + 3 个 ReplicaServer + 1 个 Collector + 本地 ZooKeeper），完成建表与读写的连通验证。全流程已在 12 核 / 31GB 内存、Ubuntu 22.04 的环境中实测通过，全量编译耗时 18 分 29 秒；所有命令与回显均为实测记录。

一、环境信息

本文所有命令与回显均在以下环境实测采集，读者在其他环境操作时输出中的主机名、PID、时间等会有差异。

项目值
操作系统Ubuntu 22.04.3 LTS（x86_64）
CPU12 核，Intel(R) Core(TM) i7-14700KF（支持 AVX2，不支持 AVX-512）
内存31GB
目标版本Apache Pegasus 2.5.0（Apache 孵化中，incubating）
源码目录/pegasus-src（源码解压根目录，含 run.sh、src/、thirdparty/）
构建工具链gcc/g++ 11.4.0、make 4.3、cmake 3.27.9、OpenJDK 8u392、maven 3.6.3、Thrift 0.11.0
onebox 进程端口Meta 34601/34602/34603，Replica 34801/34802/34803，Collector 34101
本地 ZooKeeper3.7.0，端口 22181（start_onebox 自动安装到源码目录 .zk_install/）
指标端口（默认关闭）9092 起、按进程递增（run.sh 内 prometheus_port=$((9091+i))）

Pegasus 官方以源码包形式发行（2.5.0 无任何官方二进制发行包，GitHub release 页亦无二进制附件，实测核实），因此源码编译是官方唯一部署路线，本文即按此路线从 0 到 1 展开。

二、版本与前置说明

2.1 版本选型

官网《版本发布》页（https://pegasus.apache.org/zh/docs/downloads/，实测 HTTP 200）列出的最新版本为 2.5.0，列表前有 2.4.0、2.3.0；GitHub 仓库最新 tag 同为 v2.5.0，两者一致。官方源码包地址（downloads.apache.org，实测均可访问）：

对象URL实测大小
源码 ziphttps://downloads.apache.org/incubator/pegasus/2.5.0/apache-pegasus-2.5.0-incubating-src.zip4,377,166 字节
sha512 校验文件https://downloads.apache.org/incubator/pegasus/2.5.0/apache-pegasus-2.5.0-incubating-src.zip.sha512-
签名文件https://downloads.apache.org/incubator/pegasus/2.5.0/apache-pegasus-2.5.0-incubating-src.zip.asc-

历史版本归档：downloads.apache.org 的 incubator/pegasus 目录索引实测仅保留 2.4.0/、2.5.0/ 与 KEYS 文件，更早版本请到 GitHub releases（https://github.com/apache/incubator-pegasus/releases）按 tag（v2.4.0 / v2.3.0 / v2.2.0 …）获取源码。

2.2 ⚠️ CPU 指令集要求与 AVX-512 崩溃预警（务必先读）

Pegasus 的三方依赖（尤其 RocksDB）在部分预编译产物中以 native 模式编译，产物中会包含 AVX-512 指令。在不支持 AVX-512 指令集的 CPU 上，pegasus_server 进程会在 RocksDB 的全局静态初始化阶段收到非法指令（SIGILL）而无声崩溃——没有日志、没有 core 输出提示，7 个进程全部"启动即死"，极难与常规配置错误区分（完整排障过程见第九节常见问题 9.1）。

因此本文主线从编译第一步就固定 --enable_rocksdb_portable 参数（run.sh 官方选项，含义为 build a portable rocksdb binary），生成可移植的 RocksDB 二进制，规避该问题。部署前先检测本机指令集：

grep -m1 'model name' /proc/cpuinfo
grep -c avx512f /proc/cpuinfo
grep -c avx2 /proc/cpuinfo

实测输出（本文环境，Raptor Lake 架构消费级 CPU）：

model name	: Intel(R) Core(TM) i7-14700KF
avx512f count: 0
avx2 count: 12

判读：avx512f 计数为 0 表示不支持 AVX-512（本文环境即如此，必须用 portable 编译）；支持 AVX-512 的服务器虽然可以直接运行 native 产物，也建议统一加 --enable_rocksdb_portable，让编译产物具备跨机可移植性。

2.3 硬件与系统要求

  • 编译资源：全量编译含三方库（krb5、boost、rocksdb 等），内存开销集中在三方编译阶段。本文 12 核 / 31GB 以 -j 12 实测通过；内存较小的机器（如 8GB）请将 -j 降到 4~6，避免编译器进程被内核 OOM 杀掉。
  • 磁盘：源码 + 三方源码与构建产物 + 编译输出合计数 GB，建议预留 20GB 以上空闲磁盘。
  • 网络：编译期需从 GitHub、Maven Central 下载三方源码（krb5、boost、rocksdb 等），需可访问外网；下载缓慢可为编译会话配置 HTTP 代理（本文实测环境代理出口为 192.168.1.62:7897，用法见第五节）。
  • 运行形态：onebox 用于单机体验与实验（官方口径：让你在一台机器上就能体验 Pegasus 的集群式服务），不是生产形态；多机生产部署请参考官方《集群部署》文档（https://pegasus.apache.org/zh/administration/deployment）。

三、安装构建依赖

3.1 apt 依赖清单（官方构建环境口径）

以下清单与官方 v2.5.0 源码库中 Ubuntu 22.04 构建环境定义（pegasus-build-env/ubuntu2204/）完全一致，实测环境逐一核对过安装版本：

apt-get update -y
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
    build-essential software-properties-common \
    clang-14 libclang-14-dev llvm-14-dev \
    openjdk-8-jdk pkg-config python3-pip \
    libaio-dev libsnappy-dev libbz2-dev libzstd-dev liblz4-dev \
    zlib1g zlib1g-dev patch netcat wget ccache git curl zip unzip \
    gdb vim automake libtool libssl-dev bison maven flex

安装完成后用 dpkg 核对关键包版本（实测回显节选）：

dpkg -l | grep -E '^ii +(build-essential|clang-14|openjdk-8-jdk:amd64|libssl-dev|maven|gdb|ccache) '

实测输出：

ii  build-essential              12.9ubuntu3
ii  ccache                       4.5.1-1
ii  clang-14                     1:14.0.0-1ubuntu1.1
ii  gdb                          12.1-0ubuntu1~22.04
ii  maven                        3.6.3-5
ii  openjdk-8-jdk:amd64          8u392-ga-1~22.04
ii  libssl-dev:amd64             3.0.2-0ubuntu1.12

关键包用途与实测版本：

包用途实测版本
build-essentialgcc/g++/make/make 工具链基础12.9ubuntu3（gcc-11 11.4.0、make 4.3）
clang-14 / llvm-14-dev / libclang-14-dev部分三方库构建与代码检查14.0.0
openjdk-8-jdk编译期 Java 构建（krb5 等）与本地 ZooKeeper 运行8u392-ga-1~22.04
maven三方库编译期从 Maven Central 拉取构件3.6.3
libssl-devOpenSSL 开发头文件（三方库链接用）3.0.2-0ubuntu1.12
libaio-dev / libsnappy-dev / libbz2-dev / libzstd-dev / liblz4-dev / zlib1g-devRocksDB 及压缩算法依赖0.3.112 / 1.1.8 / 1.0.8 / 1.4.8 / 1.9.3 / 1.2.11
automake / autoconf / libtool / bison / flex / pkg-config三方库源码构建系统1.16.5 / 2.71 / 2.4.6 / 3.8.2 / 2.6.4 / 0.29.2
ccache编译缓存，重复编译提速4.5.1
gdb崩溃定位（第九节 SIGILL 排障必需）12.1
unzip / zip / wget / curl / netcat / patch下载、解压与运维工具6.0 / 3.0 / 1.21.2 / 7.81.0 / 1.218 / 2.7.6

3.2 安装 cmake

官方构建环境不用 apt 的 cmake，而是通过 pip3 安装（版本更新）。执行：

pip3 install cmake

验证：

cmake --version

实测输出：

cmake version 3.27.9

3.3 预编译 Thrift 0.11.0

官方构建环境在 apt 依赖之后预编译了 Thrift 0.11.0（禁用库输出，仅编译器工具）。建议一并执行，与官方环境保持一致：

cd /opt
wget --progress=dot:giga https://github.com/apache/thrift/archive/refs/tags/0.11.0.tar.gz -P /opt/thrift
cd /opt/thrift && tar xzf 0.11.0.tar.gz && cd thrift-0.11.0
./bootstrap.sh
./configure --enable-libs=no
make -j$(($(nproc)/2+1))
make install
cd - && rm -rf /opt/thrift/thrift-0.11.0 /opt/thrift/0.11.0.tar.gz

验证：

thrift --version

实测输出：

Thrift version 0.11.0

3.4 配置 Java 8 环境变量

编译脚本与本地 ZooKeeper 依赖 JAVA_HOME。写入 /root/.bashrc：

echo 'export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64' >> /root/.bashrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> /root/.bashrc
source /root/.bashrc

验证：

java -version

实测输出：

openjdk version "1.8.0_392"
OpenJDK Runtime Environment (build 1.8.0_392-8u392-ga-1~22.04-b08)
OpenJDK 64-Bit Server VM (build 25.392-b08, mixed mode)

3.5 工具链验证汇总

gcc --version | head -1
g++ --version | head -1
make --version | head -1
cmake --version | head -1
mvn -version | head -1

实测输出：

gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0
g++ (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0
GNU Make 4.3
cmake version 3.27.9
Apache Maven 3.6.3

四、下载源码并校验

4.1 下载官方源码包

cd /opt
wget https://downloads.apache.org/incubator/pegasus/2.5.0/apache-pegasus-2.5.0-incubating-src.zip

实测下载结果：apache-pegasus-2.5.0-incubating-src.zip，4,377,166 字节。若 downloads.apache.org 下载缓慢，可为本会话配置 HTTP 代理后重试（本文实测环境代理出口为 192.168.1.62:7897）：

export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897

4.2 sha512 校验

wget https://downloads.apache.org/incubator/pegasus/2.5.0/apache-pegasus-2.5.0-incubating-src.zip.sha512
cat apache-pegasus-2.5.0-incubating-src.zip.sha512
sha512sum apache-pegasus-2.5.0-incubating-src.zip

实测输出（官方值与本地计算值逐字符一致，校验通过）：

官方: 13b6f9aae89b126a15f3b8ddc87c5434508da0edfdb65af88dd1687a03b77123fcd1a8d3afee0572b090191bde7d89da5ac81f5d458d6806d6b70c0be2b79c87
实测: 13b6f9aae89b126a15f3b8ddc87c5434508da0edfdb65af88dd1687a03b77123fcd1a8d3afee0572b090191bde7d89da5ac81f5d458d6806d6b70c0be2b79c87  apache-pegasus-2.5.0-incubating-src.zip

4.3 解压到源码目录

unzip -q apache-pegasus-2.5.0-incubating-src.zip -d /pegasus-src

💡 说明：源码包解压后可能自带一层顶层目录；只要保证 /pegasus-src 下能直接看到 run.sh、src/、thirdparty/ 即可，若多了一层目录，用 mv 把内容上移一层。本文后续所有命令均在 /pegasus-src 下执行。备选下载源：GitHub tag 打包 https://github.com/apache/incubator-pegasus/archive/refs/tags/v2.5.0.tar.gz（实测 2,755,201 字节，内容与官方源码包同为 v2.5.0 源码）。

五、源码编译

5.1 执行全量编译

run.sh 是官方一键构建/运维脚本（编译、打包、onebox 启停、shell 等子命令都在其中）。执行全量编译，-j 为并行度（取 CPU 核数），--enable_rocksdb_portable 生成可移植 RocksDB（见 2.2 的 AVX-512 预警，此参数是本文主线的固定项）：

cd /pegasus-src
./run.sh build -j 12 --enable_rocksdb_portable

编译期脚本会自动从 GitHub、Maven Central 下载三方源码（krb5、boost、rocksdb 等）并逐一构建。若下载缓慢，先在当前会话配置代理再执行（本文实测编译命令即携带代理环境变量）：

export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897

实测结果：编译正常结束（退出码 0），输出尾行：

Build elapsed time: 18m 29s

时长构成：三方库约 12 分钟，主代码约 6 分钟（12 核机器实测）。

5.2 产物核验

编译产物位于 build/release/output/：

ls /pegasus-src/build/release/output/bin/pegasus_server/pegasus_server
ls /pegasus-src/build/release/output/bin/pegasus_shell/pegasus_shell

实测产物路径：

/pegasus-src/build/release/output/bin/pegasus_server/pegasus_server
/pegasus-src/build/release/output/bin/pegasus_shell/pegasus_shell

lib/ 目录下还有运行所需的动态库（libdsn_*.so 等）；通过 run.sh 启动/调用时会自动设置 LD_LIBRARY_PATH，无需手工指定。

5.3 （可选）打包 server 发行目录

如需把编译产物整理成可分发目录（含二进制、配置模板与依赖 so），执行：

cd /pegasus-src && ./run.sh pack_server 2>&1 | tail -8

实测输出（节选）：

'/lib/x86_64-linux-gnu/libsnappy.so.1' -> 'pegasus-server-2.5.0-non-git-glibc2.35-release/bin/libsnappy.so.1'
'/lib/x86_64-linux-gnu/libcrypto.so.3' -> 'pegasus-server-2.5.0-non-git-glibc2.35-release/bin/libcrypto.so.3'
'/lib/x86_64-linux-gnu/libssl.so.3' -> 'pegasus-server-2.5.0-non-git-glibc2.35-release/bin/libssl.so.3'
'/lib/x86_64-linux-gnu/libzstd.so.1' -> 'pegasus-server-2.5.0-non-git-glibc2.35-release/bin/libzstd.so.1'
'/lib/x86_64-linux-gnu/liblz4.so.1' -> 'pegasus-server-2.5.0-non-git-glibc2.35-release/bin/liblz4.so.1'
Couldn't find env  or no valid keytab file was specified,
          hadoop-related files were not packed.
Done

说明：末尾的 hadoop 提示在未配置 HADOOP_HOME/keytab 的机器上是正常现象，仅表示 hdfs 相关文件不打入包内，不影响使用。打包产物为 pegasus-server-2.5.0-non-git-glibc2.35-release/ 目录及同名 .tar.gz。

六、部署 onebox 单机集群

6.1 onebox 是什么

onebox 是官方提供的单机集群体验形态：启动时自动把 ZooKeeper 3.7.0 安装到源码目录的隐藏目录 .zk_install/ 并启动本地 ZooKeeper（端口 22181），随后启动 3 个 MetaServer（端口 34601/34602/34603）与 3 个 ReplicaServer（端口 34801/34802/34803），集群就绪后默认创建一个 temp 表；-c 参数还会启动 1 个 Collector（端口 34101）。onebox 适合体验、开发与实验，官方明确其性能不代表生产水平。

6.2 清场（重复启动前必做）

onebox 的 ZooKeeper 启动脚本没有幂等保护：若 22181 上已有 ZooKeeper 在运行，重复执行 start_onebox 会卡死在对 ZooKeeper 的 ruok 探测上。因此每次启动前先执行清场（首次全新环境执行它会提示 nothing，无副作用；⚠️ 它会清理 onebox 数据目录，已有数据时勿随意执行）：

cd /pegasus-src
./run.sh clear_onebox

实测输出：

Stopping zookeeper ... STOPPED
Clearing zookeeper ... CLEARED

6.3 启动集群

⚠️ 启动脚本不要挂在临时会话里用裸 & 运行后立即退出该会话：启动过程中的 pegasus_server 子进程会随会话回收被连带终止（实测曾复现 7 个进程全部消失、仅 ZooKeeper 存活的现象）。用 nohup 加日志重定向启动，可避免会话断开牵连集群。

cd /pegasus-src
nohup ./run.sh start_onebox -m 3 -r 3 -c > /tmp/start_onebox.log 2>&1 &

稍候查看启动日志：

tail -20 /tmp/start_onebox.log

实测输出：

TARGET_PATH zookeeper-bin has existed, thus do not try to download apache-zookeeper-3.7.0-bin
ZooKeeper JMX enabled by default
Using config: /pegasus-src/.zk_install/zookeeper-bin/bin/../conf/zoo.cfg
Starting zookeeper ... STARTED
Zookeeper started at port 22181
starting server
root 127818 ... /pegasus-src/onebox/meta1/pegasus_server config.ini -app_list meta
root 127825 ... /pegasus-src/onebox/meta2/pegasus_server config.ini -app_list meta
root 127832 ... /pegasus-src/onebox/meta3/pegasus_server config.ini -app_list meta
root 127876 ... /pegasus-src/onebox/replica1/pegasus_server config.ini -app_list replica
root 127922 ... /pegasus-src/onebox/replica2/pegasus_server config.ini -app_list replica
root 127971 ... /pegasus-src/onebox/replica3/pegasus_server config.ini -app_list replica
root 128032 ... /pegasus-src/onebox/collector/pegasus_server config.ini -app_list collector

看到 3 meta + 3 replica + 1 collector 共 7 个 pegasus_server 进程即为启动成功（官方 onebox 文档口径："如果你能看到 3 个 MetaServer 和 3 个 ReplicaServer 进程，那么恭喜你，启动成功了"）。

start_onebox 常用参数（run.sh 内置语义）：

参数含义默认值
-m / --meta_countMetaServer 个数（端口 34601 起）3
-r / --replica_countReplicaServer 个数（端口 34801 起）3
-c同时启动 1 个 Collector（端口 34101）不启动
-w等待集群完全 healthy 后脚本才返回不等待
-a初始表名temp
-p初始表分区数8

6.4 验证进程与端口

逐一验证 7 个进程存活：

ps -ef | grep pegasus_server | grep -v grep

实测输出（7 行，-app_list 与角色对应）：

root 127818 ... /pegasus-src/onebox/meta1/pegasus_server config.ini -app_list meta
root 127825 ... /pegasus-src/onebox/meta2/pegasus_server config.ini -app_list meta
root 127832 ... /pegasus-src/onebox/meta3/pegasus_server config.ini -app_list meta
root 127876 ... /pegasus-src/onebox/replica1/pegasus_server config.ini -app_list replica
root 127922 ... /pegasus-src/onebox/replica2/pegasus_server config.ini -app_list replica
root 127971 ... /pegasus-src/onebox/replica3/pegasus_server config.ini -app_list replica
root 128032 ... /pegasus-src/onebox/collector/pegasus_server config.ini -app_list collector

验证端口监听（34601-34603 / 34801-34803 / 34101 / 22181 共 8 个端口应全部处于 LISTEN）：

ss -tlnp | grep -E '3460[123]|3480[123]|34101|22181'

在未安装 ss 的最小化系统上，可用 /proc/net/tcp 判读（state 0A 即 LISTEN）。本文实测结果：

port 34601 state 0A(LISTEN)   port 34602 state 0A   port 34603 state 0A
port 34801 state 0A           port 34802 state 0A   port 34803 state 0A
port 34101 state 0A
（另有大量组件间 ESTABLISHED 连接；zookeeper 监听在 tcp6）

再验证本地 ZooKeeper 存活（four-letter word 探测，onebox 的 zoo.cfg 固定放行 ruok）：

printf 'ruok' | nc 127.0.0.1 22181

实测输出：

imok

6.5 目录与配置生成说明

start_onebox 会生成以下内容（本节为运行期目录速览，详细配置键值见《Apache Pegasus 2.5.0 Shell 命令与运维详解》）：

  • onebox/meta1~meta3/、onebox/replica1~replica3/、onebox/collector/：每个进程一个目录，内含 config.ini（该进程最终配置）、result（标准错误输出）、data/（数据与日志）。
  • config-server.ini：由模板 src/server/config.min.ini 生成到源码根目录的集群级配置。
  • .zk_install/zookeeper-bin/：本地 ZooKeeper 3.7.0 安装目录（clientPort=22181）。

💡 说明：onebox 的进程配置由 src/server/config.min.ini 经两级 sed 替换生成——先替换 @LOCAL_HOSTNAME@/@APP_NAME@/@PARTITION_COUNT@ 得到 config-server.ini，再为每个进程替换 @META_PORT@/@REPLICA_PORT@/@PROMETHEUS_PORT@ 生成各自 config.ini。要改默认端口或指标上报，改模板后重新 clear + start 即可。

七、Shell 连通验证

7.1 进入 shell

cd /pegasus-src
./run.sh shell

实测输出（进入交互界面）：

Pegasus Shell 2.5.0
Type "help" for more information.
Type "Ctrl-D" or "Ctrl-C" to exit the shell.
The config file is: /pegasus-src/config-shell.ini.130891
The cluster name is: onebox
The cluster meta list is: 127.0.0.1:34601,127.0.0.1:34602,127.0.0.1:34603

7.2 建表

创建 3 副本表 t1（不指定 -p 时默认 4 个分区）：

> create t1 -r 3

实测输出（建表脚本轮询等待副本就绪，共 8 行 (0/4)，约 16 秒）：

create app t1 succeed, waiting for app ready
t1 not ready yet, still waiting... (0/4)
t1 not ready yet, still waiting... (0/4)
t1 is ready now: (4/4)
t1 is ready now!
create app "t1" succeed

7.3 读写一条链

先 use 切换当前表（Pegasus 的数据命令不携带表名），再完成 set/get/exist/count 闭环：

> use t1
OK
> set hkey sortkey value
OK
app_id          : 3
partition_index : 2
decree          : 5
server          : 127.0.0.1:34801

> get hkey sortkey
app_id          : 3
partition_index : 2
decree          : 5
server          : 127.0.0.1:34801
"value"

> exist hkey sortkey
app_id          : 3
partition_index : 2
server          : 127.0.0.1:34801
True

> count hkey
app_id          : 3
partition_index : 2
server          : 127.0.0.1:34801
1

写入的 hash_key 落到 app_id=3（t1）的 2 号分区、主副本在 127.0.0.1:34801，get 返回 "value"，读写链路连通。

7.4 节点健康复核

> nodes

实测输出：

[details]
address          status
127.0.0.1:34801  ALIVE
127.0.0.1:34802  ALIVE
127.0.0.1:34803  ALIVE

[summary]
total_node_count    : 3
alive_node_count    : 3
unalive_node_count  : 0

至此部署与连通验证全部完成。退出 shell 输入 exit 或按 Ctrl-D（实测退出时统一输出 dsn exit with code 0）。

八、启停管理

8.1 停止集群

cd /pegasus-src
./run.sh stop_onebox

语义：kill 全部 pegasus_server 进程。停止之后可以再用 ./run.sh start_onebox -m 3 -r 3 -c 重启集群（ZooKeeper 数据保留）。⚠️ 重启前若不确定 ZooKeeper 状态，先执行 6.2 的 clear_onebox 清场，避免卡在 ruok 探测。

8.2 清理集群（含数据）

cd /pegasus-src
./run.sh clear_onebox

语义：stop_onebox 之外，还会清理 ZooKeeper 与数据目录（rm -rf onebox *.log *.data config-*.ini）。⚠️ 数据会被彻底清除，仅在需要重置环境时使用。

8.3 单进程粒度管理

官方 onebox 文档提供单实例启停/重启命令，各自带 -h 查看参数：

./run.sh start_onebox_instance -h
./run.sh stop_onebox_instance -h
./run.sh restart_onebox_instance -h

适用于个别进程异常时的定点处理（如只重启 replica2）。

8.4 其他辅助命令

  • ./run.sh list_onebox：查看 onebox 进程列表（官方文档推荐的启动后检查命令）。
  • ./run.sh bench：官方 onebox 文档提及的读写压测工具入口（onebox 性能仅作体验参考）。
  • ./run.sh shell：进入管理 shell（详见《Apache Pegasus 2.5.0 Shell 命令与运维详解》）。

九、常见问题（FAQ）

9.1 进程"启动即死"且无任何日志（AVX-512 SIGILL，本文最大坑）

现象：编译成功后 start_onebox 能打印 7 个进程行，但随即全部消失：onebox/meta1/result 为 0 字节、没有日志目录、无任何 stderr。直接前台运行二进制，先报动态库缺失：

./pegasus_server: error while loading shared libraries: libdsn_replica_server.so:
cannot open shared object file: No such file or directory

补上库路径（run.sh 内部会自动带上等价环境变量）后，进程变成无声 core dump（timeout 报 "dumped core"），日志一个字都不输出。

定位：用 gdb 直接前台运行抓崩溃栈（gdb 是本问题的唯一直路）：

cd /pegasus-src/onebox/meta1
gdb --args ./pegasus_server config.ini -app_list meta

程序崩溃后执行 bt，实测栈回显：

Program received signal SIGILL, Illegal instruction.
0x00005da41cf98edc in rocksdb::LRUHandleTable::Resize() ()
#0 rocksdb::LRUHandleTable::Resize()
#1 rocksdb::LRUCache::LRUCache(...)
#2 rocksdb::NewLRUCache(rocksdb::LRUCacheOptions const&)
#3 rocksdb::BlockBasedTableFactory::BlockBasedTableFactory(...)
#4 rocksdb::ColumnFamilyOptions::ColumnFamilyOptions()
#5 __static_initialization_and_destruction_0(...)   ← 静态初始化阶段即崩

对崩溃点反汇编可见 AVX-512 指令：

=> vcvtusi2sdl 0xc(%rdi),%xmm2,%xmm1     ← AVX-512 指令

根因：所用的三方库预编译产物在支持 AVX-512 的编译机上以 native 模式构建了 RocksDB，二进制内含 AVX-512 指令；本文环境 CPU（i7-14700KF，Raptor Lake）有 AVX2、无 AVX-512，进程在 RocksDB 全局静态初始化阶段即触发 SIGILL。注意两个反直觉点：崩溃不在业务代码而在静态初始化；且进程无任何输出就退（日志都来不及建），极易被误判为配置或环境问题。

解决：弃用预编译三方产物，清空三方构建目录后全量重建并固定 portable 参数：

cd /pegasus-src
rm -rf thirdparty/build thirdparty/output
./run.sh build -j 12 --enable_rocksdb_portable

实测重建 18 分 29 秒完成，之后 onebox 7 进程稳定运行。

经验：凡使用任何预编译三方库产物自建 Pegasus，必须先核对目标机 CPU 指令集（grep -c avx512f /proc/cpuinfo），或在编译参数固定 --enable_rocksdb_portable。

9.2 启动失败的一般排查路径

官方 onebox 文档给出的排查位置：某个进程不在了（如 replica1），到 onebox/replica1/ 下找 core 文件（前提是 ulimit 允许产生 core）、到 onebox/replica1/data/log/ 找日志、到 onebox/replica1/result 查看标准错误输出。注意 2.5.0 的日志配置为 [tools.simple_logger] stderr_start_level = LOG_LEVEL_ERROR：崩溃发生在更早阶段时 result 文件可能为空，此时需要依赖 gdb（见 9.1）或 dmesg（内核记录的 traps/illegal instruction）定位。

9.3 编译慢或内存吃紧

  • 全量编译实测 18m29s（三方约 12 分钟 + 主代码约 6 分钟，12 核）；重复编译可利用依赖清单中的 ccache 缓存提速。
  • 若三方编译阶段报内存不足或机器卡死，把 -j 从 12 降到 4~6。
  • 若只是主代码改动后的重建，且三方库已编译完成，可用 ./run.sh build --skip_thirdparty -j 12 跳过三方编译，实测该路径耗时：
Build finish time: Wed Oct 14 17:07:24 Asia 2026
Build elapsed time: 6m 11s

⚠️ --skip_thirdparty 只应在你确认三方库产物可移植（编译时带过 --enable_rocksdb_portable）或目标 CPU 支持 AVX-512 时使用；混用预编译三方产物正是 9.1 崩溃的来源。

9.4 重复执行 start_onebox 卡住不动

onebox 的 ZooKeeper 启动无幂等保护：22181 已被占用时，start_onebox 会卡在对 ZooKeeper 的 ruok 探测上。先 ./run.sh clear_onebox 清场再启动（见 6.2）。

9.5 pack_server 提示 hadoop 相关文件未打包

Couldn't find env or no valid keytab file was specified, hadoop-related files were not packed. 在未配置 HADOOP_HOME 的机器上是正常现象，不影响 onebox 与常规使用（实测复现，见 5.3）。

9.6 官网部分文档路径 404

Pegasus 官网迁移后部分旧路径实测 404（如 /downloads、/zh/docs/deployment/onebox/、/zh/docs/deployment/single-machine/、/zh/administration/single-machine、/zh/tools/shell/）。实测有效的入口：版本发布 https://pegasus.apache.org/zh/docs/downloads/、集群部署 https://pegasus.apache.org/zh/administration/deployment、Shell 工具 https://pegasus.apache.org/zh/docs/tools/shell/（该页官方注明基于 2.5.0 版本）。本文参考链接均采用实测有效地址。

十、卸载与清理

完整清理部署痕迹，按数据危险性从高到低执行：

# 1. 停止并清空 onebox 集群（清数据，先确认无需保留）
cd /pegasus-src
./run.sh clear_onebox

# 2. 删除源码与编译产物目录（含 .zk_install 本地 ZooKeeper 与 onebox 运行目录）
cd /
rm -rf /pegasus-src

# 3. 清理启动日志
rm -f /tmp/start_onebox.log

如需回退系统依赖（可选，通常保留无害）：

apt-get purge -y clang-14 libclang-14-dev llvm-14-dev openjdk-8-jdk maven cmake
apt-get autoremove -y

十一、参考链接