CentOS 8 安装 Apache Cloudberry 指南

在 CentOS 8 上用官方 RPM 包从零安装 Apache Cloudberry 2.1.0，配置 gpadmin 与内核参数，用 gpinitsystem 初始化单机集群并验证。

Apache CloudberryApache Cloudberry2026/10/14

CentOS 8 安装 Apache Cloudberry 指南

目标：在 CentOS 8 服务器上从零安装 Apache Cloudberry 2.1.0，用 gpinitsystem 初始化「1 Coordinator + 2 Primary Segment + 2 Mirror Segment」的单机 MPP 集群，并通过 gpstate、psql 与数据分布查询验证集群可用。本文全部命令与回显已在 CentOS Linux 8（x86_64）实测通过。

一、环境信息

项目实测值 / 说明
操作系统CentOS Linux 8（x86_64）
安装包apache-cloudberry-db-incubating-2.1.0-1.el8.x86_64.rpm（官方 RPM 包，约 22.3 MB）
数据库版本Apache Cloudberry 2.1.0-incubating，内核 PostgreSQL 14.4
安装路径/usr/local/cloudberry-db（软链接，指向 /usr/local/cloudberry-db-2.1.0）
集群规模单机集群：1 Coordinator + 2 Primary Segment + 2 Mirror Segment
端口规划Coordinator 5432；Primary 6000/6001；Mirror 7000/7001
数据目录/data/coordinator/gpseg-1、`/data/primary/gpseg0
运行用户gpadmin（UID/GID 520），免密 SSH 到本机主机名 cdw
主机名cdw（同时写入 /etc/hosts 解析）
SELinux实测环境未启用（若 getenforce 返回 Enforcing 需按 2.5 节关闭）

说明：CentOS 8 官方包只提供 RPM；它与 Ubuntu 的 DEB 包内容一致，区别仅在安装方式与安装目录（RPM 装在 /usr/local/cloudberry-db-<版本> 下并软链接到 /usr/local/cloudberry-db）。

二、前置条件

本节完成安装前需要的操作系统准备：管理员账户、依赖包、语言环境、内核参数、安全模块与免密 SSH。单机集群在本机执行一次即可。

2.1 安装基础依赖与创建 gpadmin 用户

sudo dnf install -y openssh-server openssh-clients sudo shadow-utils \
  bash procps-ng ca-certificates python3 rsync which
sudo groupadd -g 520 gpadmin
sudo useradd -g 520 -u 520 -m -d /home/gpadmin -s /bin/bash gpadmin
sudo passwd gpadmin
sudo usermod -aG wheel gpadmin
echo "gpadmin ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/gpadmin
sudo chmod 440 /etc/sudoers.d/gpadmin
id gpadmin

实测回显：

uid=520(gpadmin) gid=520(gpadmin) groups=520(gpadmin)

解读：固定 UID/GID 520 保证后续多机部署一致；usermod -aG wheel 把 gpadmin 加入管理员组。

2.2 设置主机名与 hosts 解析

sudo hostnamectl set-hostname cdw
echo "127.0.1.1 cdw" | sudo tee -a /etc/hosts
hostname

实测回显：

cdw

解读：hostname 输出必须与 gpinitsystem_config 中的 COORDINATOR_HOSTNAME 完全一致。

2.3 生成 en_US.UTF-8 语言环境

CentOS 8 最小化安装默认未生成 en_US.UTF-8，而 initdb 要求有效的 locale，否则初始化会失败（见第 10.1 节）。因此先安装语言包。

sudo dnf install -y glibc-langpack-en
locale -a | grep -E "en_US.utf8|POSIX"

实测回显：

en_US
en_US.iso885915
en_US.utf8
POSIX

解读：出现 en_US.utf8 即可；初始化时再通过 LANG/LC_ALL 显式指定。

2.4 配置内核参数与资源限制

sudo tee -a /etc/sysctl.conf > /dev/null <<'EOF'
kernel.shmall = 197951838
kernel.shmmax = 810810728448
kernel.shmmni = 4096
vm.overcommit_memory = 2
vm.overcommit_ratio = 95
net.ipv4.ip_local_port_range = 10000 65535
kernel.sem = 250 2048000 200 8192
kernel.sysrq = 1
vm.swappiness = 10
EOF
sudo sysctl -p

实测回显：

kernel.shmall = 197951838
kernel.shmmax = 810810728448
kernel.shmmni = 4096
vm.overcommit_memory = 2
vm.overcommit_ratio = 95
net.ipv4.ip_local_port_range = 10000 65535
kernel.sem = 250 2048000 200 8192
kernel.sysrq = 1
vm.swappiness = 10

逐项解读：shmall/shmmax 是共享内存段上限（按物理内存重算，方法见下）；vm.overcommit_memory=2 + overcommit_ratio=95 允许 MPP 大量后端进程按比例超量申请内存；kernel.sem 放大信号量供并行锁使用。

sudo tee -a /etc/security/limits.conf > /dev/null <<'EOF'
* soft nofile 524288
* hard nofile 524288
* soft nproc 131072
* hard nproc 131072
EOF

按物理内存重算共享内存参数：

echo "kernel.shmall = $(( $(getconf _PHYS_PAGES) / 2 ))"
echo "kernel.shmmax = $(( $(getconf _PHYS_PAGES) / 2 * $(getconf PAGE_SIZE) ))"

💡 说明：文档中的 shmall=197951838、shmmax=810810728448 是官方示例值，对应约 1583 GB 内存的机器，请用上面的算式按实际内存生成后再写入。

2.5 关闭 SELinux 与防火墙

getenforce
sudo sed -i 's/^SELINUX=.*/SELINUX=disabled/' /etc/selinux/config
sudo systemctl stop firewalld
sudo systemctl disable firewalld

实测回显：

bash: getenforce: command not found

解读：本机未安装 SELinux 策略（最小化系统常见），输出 command not found 表示无需关闭；若 getenforce 返回 Enforcing，则须执行 sed 改 /etc/selinux/config 为 disabled 并重启。firewalld 无论是否运行，关闭后再做初始化最稳妥。

2.6 打通 gpadmin 免密 SSH

sudo systemctl start sshd
sudo -iu gpadmin
ssh-keygen -t rsa -b 4096 -N "" -f ~/.ssh/id_rsa -q
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
ssh -o StrictHostKeyChecking=no cdw hostname

实测回显：

Warning: Permanently added 'cdw,172.17.0.5' (ECDSA) to the list of known hosts.
cdw

解读：最后输出 cdw 表示免密 SSH 生效。

三、版本选型说明

版本发布时间RPM 形态说明
2.1.0-incubating2026-04el8 / el9目前最新，本文采用
2.0.0-incubating2025-09el8 / el9上一版
1.6.02024-09el8 / el9更早版本，包名为 cloudberry-db-*

解读：CentOS 8 属于 el8，选 apache-cloudberry-db-incubating-2.1.0-1.el8.x86_64.rpm；若目标是 Rocky/RHEL 9 则选 el9 包。

💡 技术拓展：同类「MPP / 分布式分析型数据库」横向对比——

名称内核/来源特点适用场景
Apache CloudberryPostgreSQL 14.4，源自 Greenplum完全开源、无企业版限制，Coordinator+Segment+Mirror开源数仓、GP 替代
Greenplum 7PostgreSQL 12，VMware官方仅 RHEL 系 RPM既有 GP 存量环境
Postgres-XLPostgreSQL 扩展基于 PG 的 MPP，社区较小轻量分布式 PG
PostgreSQL 单机原生 PG无 MPP 并行中小规模事务库

本文因目标系统为 CentOS 8（RHEL 系）且需要开源 MPP 数仓，采用 Apache Cloudberry 2.1.0 官方 el8 RPM 包。

四、安装方案 A：官方 RPM 包安装（推荐）

本节使用官方 RPM 包完成安装。

4.1 下载并校验 RPM 包

cd ~
curl -fsSL -O https://github.com/apache/cloudberry/releases/download/2.1.0-incubating/apache-cloudberry-db-incubating-2.1.0-1.el8.x86_64.rpm
curl -fsSL -O https://github.com/apache/cloudberry/releases/download/2.1.0-incubating/apache-cloudberry-db-incubating-2.1.0-1.el8.x86_64.rpm.sha512
ls -l apache-cloudberry-db-incubating-2.1.0-1.el8.x86_64.rpm
sha512sum -c apache-cloudberry-db-incubating-2.1.0-1.el8.x86_64.rpm.sha512

实测回显：

-rw-r--r-- 1 root root 23337068 Oct 13 18:43 apache-cloudberry-db-incubating-2.1.0-1.el8.x86_64.rpm
apache-cloudberry-db-incubating-2.1.0-1.el8.x86_64.rpm: OK

解读：sha512sum -c 校验通过时输出 <rpm 文件名>: OK，说明文件与官方校验值一致；curl 必须带 -L，否则 GitHub 的 302 跳转会得到 0 字节空文件。

4.2 安装 RPM 包

sudo dnf install -y ./apache-cloudberry-db-incubating-2.1.0-1.el8.x86_64.rpm

实测回显（输出节选（实测首尾））：

  rsync-3.1.3-12.el8.x86_64
  which-2.21-16.el8.x86_64
  zip-3.0-23.el8.x86_64
Complete!

解读：dnf 自动补齐依赖（rsync、which、perl-* 等），末行 Complete! 表示安装完成。

4.3 校验安装路径与版本

ls -ld /usr/local/cloudberry-db
ls -ld /usr/local/cloudberry-db-2.1.0
/usr/local/cloudberry-db/bin/postgres --version
/usr/local/cloudberry-db/bin/psql --version

实测回显：

lrwxrwxrwx  1 root root   30 Apr 27 03:26 /usr/local/cloudberry-db -> /usr/local/cloudberry-db-2.1.0
drwxr-xr-x 11 root root 4096 Oct 13 18:43 /usr/local/cloudberry-db-2.1.0
postgres (Apache Cloudberry) 14.4
psql (Apache Cloudberry) 14.4

解读：RPM 把实际文件安装在带版本号的 /usr/local/cloudberry-db-2.1.0，并创建 /usr/local/cloudberry-db 软链接；版本输出为内核 PostgreSQL 14.4。

4.4 设置属主并创建数据目录

sudo chown -R gpadmin:gpadmin /usr/local/cloudberry*
sudo mkdir -p /data/coordinator /data/primary /data/mirror
sudo chown -R gpadmin:gpadmin /data
ls -ld /data/*

实测回显：

drwxr-xr-x 2 gpadmin gpadmin 4096 Oct 13 18:43 /data/coordinator
drwxr-xr-x 2 gpadmin gpadmin 4096 Oct 13 18:43 /data/mirror
drwxr-xr-x 2 gpadmin gpadmin 4096 Oct 13 18:43 /data/primary

五、安装方案 B：源码编译安装（可选）

当无法使用官方 RPM（如需自定路径、改内核）时，可从源码编译。

5.1 安装编译依赖

sudo dnf install -y gcc gcc-c++ cmake re2c flex bison pkgconfig \
  libxml2-devel libyaml-devel libzstd-devel readline-devel openssl-devel \
  krb5-devel libicu-devel libevent-devel python3-devel

5.2 下载源码并编译

git clone https://github.com/apache/cloudberry.git
cd cloudberry
git checkout 2.1.0-incubating
./configure --prefix=/usr/local/cloudberry-db --with-python --with-libxml --with-openssl --with-zstd
make -j"$(nproc)"
sudo make install

解读：编译完成后同样需要执行第 2 章的 gpadmin、语言环境、内核参数与 SSH 准备，以及第 4.4 节的属主设置，再进入初始化。

💡 说明：源码编译不生成版本号目录与软链接，需自行管理；生产环境建议直接用官方 RPM 包。

六、初始化单机集群（gpinitsystem）

本节用 gpinitsystem 按配置文件一次性初始化 Coordinator 与所有 Segment。

6.1 编写初始化配置文件

sudo -iu gpadmin
mkdir -p /home/gpadmin/gpconfigs
cat > /home/gpadmin/gpconfigs/hostfile_gpinitsystem <<'EOF'
cdw
EOF
cat > /home/gpadmin/gpconfigs/gpinitsystem_config <<'EOF'
SEG_PREFIX=gpseg
PORT_BASE=6000
declare -a DATA_DIRECTORY=(/data/primary /data/primary)
COORDINATOR_HOSTNAME=cdw
COORDINATOR_DIRECTORY=/data/coordinator
COORDINATOR_PORT=5432
TRUSTED_SHELL=ssh
ENCODING=UNICODE
MIRROR_PORT_BASE=7000
declare -a MIRROR_DATA_DIRECTORY=(/data/mirror /data/mirror)
MACHINE_LIST_FILE=/home/gpadmin/gpconfigs/hostfile_gpinitsystem
EOF

逐项解读：DATA_DIRECTORY/MIRROR_DATA_DIRECTORY 的元素个数决定每台主机的 Primary/Mirror 数量（这里各 2 个）；PORT_BASE=6000、MIRROR_PORT_BASE=7000 决定端口基数；COORDINATOR_HOSTNAME=cdw 必须与主机名一致；主机文件只列 Segment 主机名。

6.2 执行初始化

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
source /usr/local/cloudberry-db/cloudberry-env.sh
gpinitsystem -c /home/gpadmin/gpconfigs/gpinitsystem_config -a

实测回显（输出节选（实测首尾））：

20261013:18:44:01:000426 gpinitsystem:cdw:gpadmin-[INFO]:-Coordinator IP address array = 172.17.0.5
20261013:18:44:01:000426 gpinitsystem:cdw:gpadmin-[INFO]:-Building the Coordinator instance database, please wait...
20261013:18:44:48:002229 gpinitsystem:cdw:gpadmin-[INFO]:-Apache Cloudberry instance successfully created
20261013:18:44:48:002229 gpinitsystem:cdw:gpadmin-[INFO]:-1. Ensure that the cloudberry-env.sh file is sourced
20261013:18:44:48:002229 gpinitsystem:cdw:gpadmin-[INFO]:-2. Add "export COORDINATOR_DATA_DIRECTORY=/data/coordinator/gpseg-1"

⚠️ 注意：若跳过 2.3 节的语言环境安装，Building the Coordinator instance database 阶段会以 FATAL 退出，报 initdb: error: invalid locale settings。排障见第 10.1 节。

解读：与 Ubuntu 一致，初始化结束时也可能出现 WARN: Failed to start Cloudberry instance（Mirror 注册告警），按第 10.2 节重启即可修复。

七、集群验证

7.1 查看集群状态（gpstate）

source /usr/local/cloudberry-db/cloudberry-env.sh
export COORDINATOR_DATA_DIRECTORY=/data/coordinator/gpseg-1
gpstate -b

实测回显（输出节选（实测首尾））：

20261013:18:45:03:009378 gpstate:cdw:gpadmin-[INFO]:-local Cloudberry Version: 'postgres (Apache Cloudberry) 2.1.0-incubating build bdf90c5518f'
20261013:18:45:03:009378 gpstate:cdw:gpadmin-[INFO]:-   Coordinator instance                                      = Active
20261013:18:45:03:009378 gpstate:cdw:gpadmin-[INFO]:-   Total segment instance count from metadata                = 4

解读：Coordinator instance = Active、Segment 元数据计数为 4（2 Primary + 2 Mirror），说明集群已就绪。

7.2 查看 Segment 配置表

psql -d postgres -c "SELECT dbid,content,role,port,status,mode FROM gp_segment_configuration ORDER BY dbid;"

实测回显（修复 Mirror 后的健康状态）：

 dbid | content | role | port | status | mode
------+---------+------+------+--------+------
    1 |      -1 | p    | 5432 | u      | n
    2 |       0 | p    | 6000 | u      | s
    3 |       1 | p    | 6001 | u      | s
    4 |       0 | m    | 7000 | u      | s
    5 |       1 | m    | 7001 | u      | s
(5 rows)

逐列解读：content=-1 为 Coordinator；role=p/m 为 Primary/Mirror；status=u 表示 Up；mode=s 表示与 Mirror 数据同步。健康集群应全部为 u/s。

7.3 建库建表并观察数据分布

psql -d postgres <<'SQL'
CREATE DATABASE cbdbtest;
\c cbdbtest
CREATE TABLE t_user (user_id int, user_name text, login_count int) DISTRIBUTED BY (user_id);
INSERT INTO t_user VALUES (1, 'alice', 10), (2, 'bob', 5), (3, 'carol', 7);
SELECT gp_segment_id, count(*) AS cnt FROM t_user GROUP BY gp_segment_id ORDER BY gp_segment_id;
SQL

实测回显：

CREATE DATABASE
You are now connected to database "cbdbtest" as user "gpadmin".
CREATE TABLE
INSERT 0 3
 gp_segment_id | cnt
---------------+-----
             0 |   2
             1 |   1
(2 rows)

解读：3 行数据按 user_id hash 分布到 content=0（2 行）和 content=1（1 行），证明 MPP 分布生效。

八、配置说明

8.1 配置 gpadmin 登录环境

sudo -iu gpadmin
cat >> ~/.bashrc <<'EOF'
source /usr/local/cloudberry-db/cloudberry-env.sh
export COORDINATOR_DATA_DIRECTORY=/data/coordinator/gpseg-1
EOF
source ~/.bashrc
echo "$GPHOME"

实测回显：

/usr/local/cloudberry-db

8.2 查看与修改集群参数

gpconfig -s max_connections

实测回显：

Values on all segments are consistent
GUC              : max_connections
Coordinator value: 250
Segment     value: 750

解读：gpconfig -s 查看参数在所有实例上的取值；该命令可读取 Coordinator 与 Segment 的不同值，修改时用 gpconfig -c <参数> -v <值>（详见《Apache Cloudberry 配置参数详解》）。

九、方案对比与选择建议

维度方案 A：官方 RPM 包方案 B：源码编译
是否需联网仅首次下载包需拉取源码 + 大量依赖
安装耗时约 1~2 分钟数十分钟
依赖处理dnf 自动补齐需手动装全开发库
目录形态版本号目录 + 软链接单一 --prefix 目录
适用场景生产/测试首选改内核、自定路径

解读：CentOS 8 属 RHEL 系，官方 RPM 支持完善，默认选方案 A。

十、常见问题

Q1：gpinitsystem 报 initdb: error: invalid locale settings; check LANG and LC_* environment variables 并 FATAL 退出，如何解决？

现象：初始化在 Building the Coordinator instance database 阶段以 [FATAL] 退出，日志关键行为 initdb: error: invalid locale settings。定位：CentOS 8 最小化安装未生成 en_US.UTF-8，initdb 无法设置默认 locale。解法：安装语言包并在执行前指定 locale，然后清理上次残留的实例目录重跑。

sudo dnf install -y glibc-langpack-en
sudo rm -rf /data/coordinator/gpseg-1 /data/primary/gpseg0 /data/primary/gpseg1 /data/mirror/gpseg0 /data/mirror/gpseg1
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
source /usr/local/cloudberry-db/cloudberry-env.sh
gpinitsystem -c /home/gpadmin/gpconfigs/gpinitsystem_config -a

实测回显：

20261013:18:44:48:002229 gpinitsystem:cdw:gpadmin-[INFO]:-Apache Cloudberry instance successfully created

Q2：初始化后 Mirror 段 status=d/mode=n（WARN: Failed to start Cloudberry instance），如何修复？

现象：日志出现 WARN: Failed to start Cloudberry instance，gp_segment_configuration 中两条 role=m 记录为 d。定位：日志显示 Complete failed to register mirror for contentid=0/1，Mirror 实例创建成功但注册超时。解法：整体重启集群，让 gpstart 重新拉起并注册全部实例。

source /usr/local/cloudberry-db/cloudberry-env.sh
export COORDINATOR_DATA_DIRECTORY=/data/coordinator/gpseg-1
gpstop -a
gpstart -a

实测回显（gpstart 关键行）：

20261013:18:45:03:009378 gpstart:cdw:gpadmin-[INFO]:-   Successful segment starts                                            = 4
20261013:18:45:03:009378 gpstart:cdw:gpadmin-[INFO]:-   Failed segment starts                                                = 0
20261013:18:45:03:009378 gpstart:cdw:gpadmin-[INFO]:-Successfully started 4 of 4 segment instances

Q3：curl 下载 RPM 得到 0 字节文件，为什么？

现象：执行 curl -fsSL -O 后文件大小为 0。定位：GitHub Releases 的下载链接返回 302 跳转到 blob 存储，若不带 -L 则不跟随跳转。解法：始终加 -L：

curl -fsSLO https://github.com/apache/cloudberry/releases/download/2.1.0-incubating/apache-cloudberry-db-incubating-2.1.0-1.el8.x86_64.rpm
ls -l apache-cloudberry-db-incubating-2.1.0-1.el8.x86_64.rpm

实测回显：

-rw-r--r-- 1 root root 23337068 Oct 13 18:43 apache-cloudberry-db-incubating-2.1.0-1.el8.x86_64.rpm

十一、卸载与清理

11.1 删除集群实例

source /usr/local/cloudberry-db/cloudberry-env.sh
export COORDINATOR_DATA_DIRECTORY=/data/coordinator/gpseg-1
gpdeletesystem -d /data/coordinator/gpseg-1 -f

11.2 卸载软件包

sudo dnf remove -y apache-cloudberry-db-incubating
sudo rm -rf /usr/local/cloudberry-db-2.1.0 /usr/local/cloudberry-db
sudo rm -rf /data/coordinator /data/primary /data/mirror
rpm -qa | grep cloudberry

解读：最后一条命令无输出表示 RPM 已卸载干净。

十二、参考链接