Ubuntu 22.04 安装 Apache Cloudberry 指南

在 Ubuntu 22.04 服务器上以官方 DEB 包安装 Apache Cloudberry 2.1.0（Incubating）MPP 数据库并初始化单机多 Segment 集群，含下载校验、gpinitsystem 初始化与验证回显

Apache CloudberryApache Cloudberry2026/10/14

Ubuntu 22.04 安装 Apache Cloudberry 指南

目标：在 Ubuntu 22.04 服务器上以官方 DEB 包安装 Apache Cloudberry 2.1.0（Incubating），初始化 1 个 Coordinator + 2 个 Primary Segment + 2 个 Mirror Segment 的单机 MPP 集群，并完成建库建表与数据分布验证。本指南已在 Ubuntu 22.04 实测通过。

一、环境信息

本节列出本指南实测所用的服务器环境，后续所有命令与回显均来自该环境，读者可据此对照复现。

  • 操作系统：Ubuntu 22.04.5 LTS（Linux x86_64）
  • 内核版本：Linux 5.15（实测 uname -r 输出与发行版一致）
  • 数据库版本：Apache Cloudberry 2.1.0-incubating（PostgreSQL 14.4 内核）
  • 主机名：cdw（Coordinator 节点，本环境为单机部署，Segment 与 Mirror 同机）
  • 安装方式：官方 DEB 包（apache-cloudberry-db-incubating_2.1.0-1-ubuntu22.04_amd64.deb，约 20.4 MB）
  • 安装目录：/usr/cloudberry-db（软链接 /usr/local/cloudberry-db 指向该目录）
  • 管理用户：gpadmin（UID/GID 520）
  • 数据目录：Coordinator /data/coordinator、Primary /data/primary、Mirror /data/mirror
  • 端口规划：Coordinator 5432，Primary Segment 6000/6001，Mirror Segment 7000/7001
  • 环境变量文件：/usr/local/cloudberry-db/cloudberry-env.sh

💡 说明：Cloudberry 2.1 起官方提供 RPM/DEB 安装包，且环境变量文件名由旧版 Greenplum 时代的 greenplum_path.sh 更名为 cloudberry-env.sh（官方文档已确认此变更）。

二、版本选型说明

2.1 版本背景

Apache Cloudberry（Incubating）是 Apache 软件基金会孵化项目下的 MPP（Massively Parallel Processing，大规模并行处理）数据库，源自 Greenplum，内核为 PostgreSQL 14.4，Coordinator/Segment 架构天然适合数据仓库与大规模分析负载。

本节先说明为什么选择 2.1.0-incubating：该版本是撰写本指南时官方渠道可下载的最新正式发布版本（2026-04-15 发布），且是首个官方提供 RPM/DEB 二进制包的版本系列。版本核对方法如下（实测）：

curl -s https://archive.apache.org/dist/incubator/cloudberry/ | grep -oE 'href="[^"]+/"' | head -10

输出节选（实测首尾）：

href="2.0.0-incubating/"
href="2.1.0-incubating/"
href="KEYS"

💡 说明：Apache 基金会将孵化项目发布件归档在 archive.apache.org/dist/incubator/ 下，KEYS 文件用于校验发布签名，2.1.0-incubating/ 即为当前最新版本目录。

2.2 版本对照表

以下为 Cloudberry 近几个正式版本的对照（版本、内核、发布方式均来自官方渠道实测核对）：

版本PostgreSQL 内核官方二进制包发布时间
1.6.0PG 14无（仅源码）2024-09
2.0.0-incubatingPG 14.4无（仅源码）2025-09
2.1.0-incubatingPG 14.4RPM（el8/el9）+ DEB（Ubuntu 22.04）2026-04

关键差异解读：1.6/2.0 时代只能下载源码自行编译，部署成本高；2.1.0-incubating 起官方直接发布 RPM/DEB 二进制包，安装流程大幅简化，因此本指南选定 2.1.0-incubating。

2.3 同类 MPP 数据库横向对比

💡 技术拓展：MPP 数据库不止 Cloudberry 一家，常见可选方案对比——

方案架构原理适用场景
Apache Cloudberry源自 Greenplum，Coordinator 分发 + Segment 并行计算，PostgreSQL 协议兼容数据仓库、大规模分析、开源可控
Greenplum商业版 MPP（PostgreSQL 内核），功能类似商用数仓，需商业授权
Citus（PG 扩展）基于单机 PostgreSQL 的分片扩展，协调节点 + 工作节点多租户、实时分析、横向扩容
单机 PostgreSQL单进程多线程模型，无分布式执行中小规模 OLTP/OLAP 混合

本文按 Apache 孵化项目官方路线选用 Apache Cloudberry，理由：开源可自主可控、提供官方 DEB/RPM 包、PostgreSQL 生态兼容。

三、在线安装方案（A：官方 DEB 包，推荐）

本章为官方推荐安装路线：下载 DEB 包 → 校验 → 安装 → 创建管理用户 → 初始化集群 → 验证。所有命令均在本指南环境实测。

3.1 方案说明

在线安装方案从 Apache 官方发布渠道下载 DEB 包，用 apt（含 --fix-broken 自动补依赖）完成安装。该方案联网即可，依赖自动解析，是官方文档首推方式。

3.2 前置条件与系统参数

安装前需要确认系统满足 MPP 集群的基础参数要求（共享内存、信号量、端口范围等）。以下为本环境实测的系统参数：

sysctl -n kernel.shmmax kernel.shmall kernel.sem vm.overcommit_memory vm.max_map_count net.ipv4.ip_local_port_range

实测回显：

810810728448
197951838
250     2048000 200     8192
2
65530
10000   65535

逐项说明：

  • kernel.shmmax：单块共享内存段上限，Cloudberry 各实例共享内存以该值衡量，810810728448 字节约为 755 GB，足够承载 Coordinator + 多 Segment。
  • kernel.shmall：系统共享内存页总数，197951838 页（页大小 4KB）。
  • kernel.sem：SEMMSL SEMMNS SEMOPM SEMMNI 四项，即每组信号量数 250、系统信号量总数 2048000、每次操作数 200、信号量组数 8192；Segment 并发进程多，需要较大信号量配额。
  • vm.overcommit_memory=2：禁止内核过量分配内存，避免大查询导致 OOM。
  • vm.max_map_count=65530：单进程可映射的内存区域数量上限，Segment 进程依赖该值。
  • net.ipv4.ip_local_port_range：本地临时端口范围 10000 65535，Segment 端口（6000/7000 段）应避开该范围（本环境实测满足）。

3.3 创建管理用户 gpadmin

Cloudberry 集群所有实例（Coordinator/Segment/Mirror）都以统一管理用户 gpadmin 运行，安装前必须先创建该用户：

groupadd -g 520 gpadmin
useradd -g 520 -u 520 -m -d /home/gpadmin -s /bin/bash gpadmin
echo "gpadmin ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/gpadmin
chmod 440 /etc/sudoers.d/gpadmin
id gpadmin

实测回显：

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

要点：UID/GID 统一固定为 520 是为了多节点部署时各主机用户 ID 一致，避免跨节点权限错乱；/etc/sudoers.d/gpadmin 授予免密 sudo，供初始化与日常运维使用。

3.4 下载软件包并校验完整性

从官方发布渠道下载 DEB 包及其 SHA512 校验文件（下载地址：https://github.com/apache/cloudberry/releases/download/2.1.0-incubating/apache-cloudberry-db-incubating_2.1.0-1-ubuntu22.04_amd64.deb）：

cd /tmp
curl -L -o cloudberry.deb \
  "https://github.com/apache/cloudberry/releases/download/2.1.0-incubating/apache-cloudberry-db-incubating_2.1.0-1-ubuntu22.04_amd64.deb"
curl -L -o cloudberry.deb.sha512 \
  "https://github.com/apache/cloudberry/releases/download/2.1.0-incubating/apache-cloudberry-db-incubating_2.1.0-1-ubuntu22.04_amd64.deb.sha512"
ls -l cloudberry.deb
sha512sum cloudberry.deb

实测回显（节选）：

-rw-r--r-- 1 root root 20383680 10月 13 18:56 cloudberry.deb
8235e89791209474bb5fb5fb7b15b7c63653368bd37e8e6d489cc0deeffcd101d3c8f923fbb9ff6da8abc29b335e3cedb3870ab328ccb1b63776868700fbebf6  cloudberry.deb

官方 SHA512 校验文件内容（实测）：

8235e89791209474bb5fb5fb7b15b7c63653368bd37e8e6d489cc0deeffcd101d3c8f923fbb9ff6da8abc29b335e3cedb3870ab328ccb1b63776868700fbebf6  apache-cloudberry-db-incubating_2.1.0-1-ubuntu22.04_amd64.deb

校验结论：两者逐字符一致，包完整、来源可信。安装前务必执行此步，防止下载损坏或中间人替换。

💡 说明：网络受限的内网环境可改用离线方案（见第四章），或通过支持 GitHub 下载的加速通道获取同一文件后继续以下步骤。

3.5 安装 DEB 包

使用 apt 安装，--fix-broken 让 apt 自动补齐 DEB 声明的依赖（libapr1、libevent、openssh-server、python3 等）：

apt-get update
apt-get install -y --fix-broken /tmp/cloudberry.deb

实测回显（节选首尾）：

Reading package lists... Done
Building dependency tree... Done
...
Preparing to unpack /tmp/cloudberry.deb ...
Unpacking apache-cloudberry-db-incubating (2.1.0-1-ubuntu22.04) ...
Setting up apache-cloudberry-db-incubating (2.1.0-1-ubuntu22.04) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

确认安装结果：

dpkg -l | grep -i cloudberry
ls -ld /usr/local/cloudberry-db
ls /usr/local/cloudberry-db/bin/psql

实测回显：

ii  apache-cloudberry-db-incubating 2.1.0-1-ubuntu22.04  amd64  Apache Cloudberry (incubating) is an advanced, open-source, massively...
lrwxrwxrwx 1 root root 18 10月 13 18:39 /usr/local/cloudberry-db -> /usr/cloudberry-db
/usr/local/cloudberry-db/bin/psql

逐项说明：dpkg -l 显示包处于 ii（已安装）状态；/usr/local/cloudberry-db 是指向 /usr/cloudberry-db 的软链接，版本升级时链接自动切换；psql 客户端程序位于安装目录 bin/ 下。

3.6 配置环境变量

每次登录 gpadmin 用户后需加载环境变量文件，并把 Coordinator 数据目录导出为 COORDINATOR_DATA_DIRECTORY（所有 gp* 管理工具都依赖该变量）：

cat >> /home/gpadmin/.bashrc <<'EOF'
source /usr/local/cloudberry-db/cloudberry-env.sh
export COORDINATOR_DATA_DIRECTORY=/data/coordinator/gpseg-1
export PGPORT=5432
EOF

验证环境变量生效（实测）：

su - gpadmin -c "source /usr/local/cloudberry-db/cloudberry-env.sh && echo \$GPHOME && echo \$COORDINATOR_DATA_DIRECTORY"

实测回显：

/usr/local/cloudberry-db
/data/coordinator/gpseg-1

⚠️ 注意：COORDINATOR_DATA_DIRECTORY 必须指向 Coordinator 实例数据目录 /data/coordinator/gpseg-1（含 SEG_PREFIX 后缀 gpseg-1），而不是 gpinitsystem_config 中的 COORDINATOR_DIRECTORY=/data/coordinator。若未导出该变量，gpstate、gpstop 等工具会直接报错（见常见问题 Q2）。

3.7 准备数据目录与免密 SSH

MPP 集群初始化需要各角色实例的数据目录，且 gpadmin 必须能免密 SSH 到集群内每台主机（单机部署即本机 cdw）：

mkdir -p /data/coordinator /data/primary /data/mirror
chown -R gpadmin:gpadmin /data

su - gpadmin -c "
mkdir -p ~/.ssh
[ -f ~/.ssh/id_rsa ] || 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' (ED25519) to the list of known hosts.
cdw

ssh cdw hostname 输出 cdw 即代表免密链路打通。若集群含多台主机，用 gpssh-exkeys -f hostfile_exkeys 可将 1-N 免密扩展为 N-N 免密（见《Apache Cloudberry 常用 CLI 命令与工具详解》篇）。

3.8 编写 gpinitsystem 配置并初始化集群

gpinitsystem 是 Cloudberry 的初始化工具，它按配置文件在 Coordinator 和各 Segment 上并行执行 initdb 并启动实例。首先准备配置文件：

mkdir -p /home/gpadmin/gpconfigs
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
echo "cdw" > /home/gpadmin/gpconfigs/hostfile_gpinitsystem
chown -R gpadmin:gpadmin /home/gpadmin/gpconfigs

配置项逐项说明：

  • SEG_PREFIX=gpseg：Segment 数据目录前缀，实例目录形如 gpseg0、gpseg1，Coordinator 目录则为 gpseg-1。
  • PORT_BASE=6000：Primary Segment 起始端口，第二个 Segment 依次递增（6001）。
  • DATA_DIRECTORY=(/data/primary /data/primary)：每段一个数据目录位置，数组元素个数即 Segment 数量，此处定义 2 个 Primary Segment。
  • COORDINATOR_HOSTNAME=cdw：Coordinator 主机名，必须能被本机解析。
  • COORDINATOR_DIRECTORY=/data/coordinator：Coordinator 数据目录基目录（实际实例目录为 /data/coordinator/gpseg-1）。
  • COORDINATOR_PORT=5432：Coordinator 监听端口，即 psql 连接端口。
  • TRUSTED_SHELL=ssh：实例间通信用 SSH。
  • ENCODING=UNICODE：数据库默认编码 UTF-8。
  • MIRROR_PORT_BASE=7000 与 MIRROR_DATA_DIRECTORY：启用 Mirror（备段）时使用，备段端口 7000/7001、目录 /data/mirror。
  • MACHINE_LIST_FILE：指向 Segment 主机清单文件 hostfile_gpinitsystem，内容为各 Segment 主机名，每行一个。

执行初始化（-a 表示跳过确认提示自动继续，-c 指定配置文件，-h 指定主机清单）：

su - gpadmin -c "
source /usr/local/cloudberry-db/cloudberry-env.sh
export COORDINATOR_DATA_DIRECTORY=/data/coordinator/gpseg-1
export PGPORT=5432
gpinitsystem -c /home/gpadmin/gpconfigs/gpinitsystem_config -h /home/gpadmin/gpconfigs/hostfile_gpinitsystem -a
"

实测回显（节选首尾）：

20261013:19:00:03:015182 gpinitsystem:cdw:gpadmin-[INFO]:-Checking configuration parameters, please wait...
20261013:19:00:03:015182 gpinitsystem:cdw:gpadmin-[INFO]:-Coordinator connections    = 250
20261013:19:00:03:015182 gpinitsystem:cdw:gpadmin-[INFO]:-Segment connections        = 750
20261013:19:00:03:015182 gpinitsystem:cdw:gpadmin-[INFO]:-Segment buffers            = 128000kB
...
20261013:19:00:03:015182 gpinitsystem:cdw:gpadmin-[INFO]:-Number of primary segments = 2
20261013:19:00:03:015182 gpinitsystem:cdw:gpadmin-[INFO]:-Number of mirror segments  = 2
20261013:19:00:03:015182 gpinitsystem:cdw:gpadmin-[INFO]:-cdw   6000    cdw     /data/primary/gpseg0    2
20261013:19:00:03:015182 gpinitsystem:cdw:gpadmin-[INFO]:-cdw   6001    cdw     /data/primary/gpseg1    3
...
20261013:19:03:02:020038 gpinitsystem:cdw:gpadmin-[INFO]:-Apache Cloudberry instance successfully created
20261013:19:03:02:020038 gpinitsystem:cdw:gpadmin-[INFO]:-To complete the environment configuration, please
20261013:19:03:02:020038 gpinitsystem:cdw:gpadmin-[INFO]:-update gpadmin .bashrc file with the following
20261013:19:03:02:020038 gpinitsystem:cdw:gpadmin-[INFO]:-1. Ensure that the cloudberry-env.sh file is sourced
20261013:19:03:02:020038 gpinitsystem:cdw:gpadmin-[INFO]:-2. Add "export COORDINATOR_DATA_DIRECTORY=/data/coordinator/gpseg-1"
...
20261013:19:03:02:020038 gpinitsystem:cdw:gpadmin-[INFO]:-Script log file = /home/gpadmin/gpAdminLogs/gpinitsystem_20261013.log

回显解读：初始化日志显示 Coordinator 连接数 250、Segment 连接数 750、Segment 缓冲 128000kB（125MB）、Primary/Mirror 各 2 个，最终输出 Apache Cloudberry instance successfully created 表示集群创建成功；初始化详细日志保存在 ~/gpAdminLogs/gpinitsystem_*.log，排障时重点查看。

💡 说明：gpinitsystem -a 与交互确认等同义（交互模式会输出 Continue with Cloudberry creation Yy|Nn (default=N): 并等待输入 y），脚本化部署用 -a 更稳妥。

3.9 验证集群运行状态

初始化成功后用 gpstate -s 查看集群全量状态（实测）：

su - gpadmin -c "
source /usr/local/cloudberry-db/cloudberry-env.sh
export COORDINATOR_DATA_DIRECTORY=/data/coordinator/gpseg-1
export PGPORT=5432
gpstate -s
"

实测回显（节选首尾）：

20261013:18:58:48:012663 gpstate:cdw:gpadmin-[INFO]:-Coordinator host                  = cdw
20261013:18:58:48:012663 gpstate:cdw:gpadmin-[INFO]:-Coordinator postgres process ID   = 10975
20261013:18:58:48:012663 gpstate:cdw:gpadmin-[INFO]:-Coordinator data directory        = /data/coordinator/gpseg-1
20261013:18:58:48:012663 gpstate:cdw:gpadmin-[INFO]:-Coordinator port                  = 5432
20261013:18:58:48:012663 gpstate:cdw:gpadmin-[INFO]:-Cloudberry current version        = PostgreSQL 14.4 (Apache Cloudberry 2.1.0-incubating build bdf90c5518f)...
...
20261013:18:58:48:012663 gpstate:cdw:gpadmin-[INFO]:-   Segment Info
20261013:18:58:48:012663 gpstate:cdw:gpadmin-[INFO]:-      Datadir                               = /data/primary/gpseg0
20261013:18:58:48:012663 gpstate:cdw:gpadmin-[INFO]:-      Port                                  = 6000
...
20261013:18:58:48:012663 gpstate:cdw:gpadmin-[INFO]:-      Configuration reports status as       = Up
20261013:18:58:48:012663 gpstate:cdw:gpadmin-[INFO]:-      Database status                       = Up

解读：gpstate -s 分别列出 Coordinator 配置与每个 Segment（Primary 与 Mirror）的状态；全部 status = Up、Mirror 状态 Synchronized（已同步）即为健康集群。

3.10 建库建表与数据分布验证

通过 psql 连接 Coordinator 验证 MPP 数据分布（本指南核心验证，实测）：

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

实测回显：

psql (Apache Cloudberry) 14.4
CREATE DATABASE
CREATE TABLE
INSERT 0 3
 gp_segment_id | cnt
---------------+-----
             0 |   2
             1 |   1
(2 rows)

验证结论：3 行数据按分布键 user_id 哈希后落在 2 个 Segment 上（Segment 0 两行、Segment 1 一行），证明 MPP 数据分布生效。gp_segment_id 是 Cloudberry 在每个 Segment 上自动附加的系统列，用于标识行所在的分片。

再通过 gp_segment_configuration 系统表核对集群拓扑（实测）：

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

实测回显：

 dbid | content | role | preferred_role | mode | status | port | hostname |          datadir
------+---------+------+----------------+------+--------+------+----------+---------------------------
    1 |      -1 | p    | p              | n    | u      | 5432 | cdw      | /data/coordinator/gpseg-1
    2 |       0 | p    | p              | s    | u      | 6000 | cdw      | /data/primary/gpseg0
    4 |       0 | m    | m              | s    | u      | 7000 | cdw      | /data/mirror/gpseg0
    3 |       1 | p    | p              | s    | u      | 6001 | cdw      | /data/primary/gpseg1
    5 |       1 | m    | m              | s    | u      | 7001 | cdw      | /data/mirror/gpseg1
(5 rows)

解读：content=-1 为 Coordinator；content=0/1 为两个数据分片；每分片一对 Primary（role=p）与 Mirror（role=m）；status=u 全部 Up、mode=s 主备已同步，集群拓扑健康。

四、离线安装方案（B：dpkg 直接安装，断网环境）

4.1 方案说明

若服务器无法访问软件源，可先在其他机器下载 DEB 包（含全部依赖需预先离线备齐），再用 dpkg -i 直接安装。该方案是官方文档提供的备用路线（dpkg -i <DEB> && apt-get install -f）。

4.2 dpkg 直接安装

将 DEB 包拷贝到目标机器后执行：

cd /tmp
dpkg -i cloudberry.deb

实测回显：

(Reading database ... 18404 files and directories currently installed.)
Preparing to unpack cloudberry.deb ...
Unpacking apache-cloudberry-db-incubating (2.1.0-1-ubuntu22.04) over (2.1.0-1-ubuntu22.04) ...
Setting up apache-cloudberry-db-incubating (2.1.0-1-ubuntu22.04) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

4.3 依赖缺失时的修复

dpkg -i 不做依赖解析，若系统缺少依赖会报 dependency problems 错误。此时执行：

apt-get install -f

-f（fix-broken）会自动补装 DEB 声明的缺失依赖并完成配置。依赖全部满足时输出 0 upgraded, 0 newly installed（实测），随后按第三章 3.6 起的步骤继续初始化即可。

五、方案对比与选择建议

方案是否联网依赖处理适合场景
A：apt 在线安装是自动解析补装可访问软件源的常规环境（推荐）
B：dpkg 离线安装否需手动/apt-get install -f 补齐内网隔离、离线交付环境

解读：两方案安装产物完全一致（同一 DEB 包），区别仅在依赖获取方式。日常部署首选方案 A；离线环境用方案 B 并在源机器上把依赖包一并打包携带。

六、配置说明

6.1 常用配置文件位置

Cloudberry 各实例的配置以 PostgreSQL 惯例分布在各实例数据目录下：

文件路径（本环境实测）作用
主配置文件/data/coordinator/gpseg-1/postgresql.confCoordinator 参数配置
客户端认证/data/coordinator/gpseg-1/pg_hba.conf连接认证规则
Segment 主配置/data/primary/gpseg0/postgresql.conf各 Segment 参数配置
环境变量/usr/local/cloudberry-db/cloudberry-env.shGPHOME/PATH/LD_LIBRARY_PATH

解读：MPP 参数分两类管理——跨实例统一参数用 gpconfig 工具批量修改（见《Apache Cloudberry 配置参数详解》篇），仅 Coordinator 或仅 Segment 的差异参数直接编辑对应实例的 postgresql.conf。

6.2 版本升级与多版本管理

  • 升级：新版本发布后下载新版 DEB，apt-get install -y --fix-broken <新包> 覆盖安装；安装目录按版本独立（如 /usr/cloudberry-db-<version>），/usr/local/cloudberry-db 软链接自动指向新版。
  • 多版本并存：不同版本目录各自独立，通过切换 cloudberry-env.sh 来源实现版本共存验证；跨大版本升级需按官方发布说明执行数据迁移。
  • 回退：保留旧版目录即可切换回旧版本（先停库再切换环境变量后重启）。

6.3 停止与启动

日常启停用 gpstop/gpstart（实测回显见《Apache Cloudberry 常用 CLI 命令与工具详解》篇），例如：

gpstop -a        # 停止整个集群
gpstart -a       # 启动整个集群

七、常见问题（FAQ）

Q1：安装或初始化时报 initdb: error: invalid locale settings; check LANG and LC_* environment variables，如何处理？ A：系统缺少 UTF-8 locale 时 initdb 会失败。Ubuntu 下执行 locale-gen en_US.UTF-8（或安装 locales 后 dpkg-reconfigure locales），并在执行 gpinitsystem 前导出 LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8。实测确认该环境变量后初始化即通过。

Q2：执行 gpstate 报 Environment Variable COORDINATOR_DATA_DIRECTORY not set! 或 No such file or directory: '/data/coordinator/postgresql.conf'？ A：前者是未导出 COORDINATOR_DATA_DIRECTORY；后者是变量指向了基目录而非实例目录。正确值应为 /data/coordinator/gpseg-1（见 3.6），写入 gpadmin 的 .bashrc 后重新登录生效。

Q3：gpinitsystem 提示端口被占用？ A：PORT_BASE=6000/MIRROR_PORT_BASE=7000 与系统已有进程端口冲突时，检查 ss -tlnp | grep -E "6000|7000" 释放端口，或调整配置中的端口基值；同时确认 net.ipv4.ip_local_port_range 起点低于端口基值（官方建议）。

Q4：初始化完成后部分 Segment（Mirror）状态为 Down？ A：偶发情况下初始化收尾未完成 Mirror 数据同步。实测解法：gpstop -a 后 gpstart -a 完整重启一次，gpstate -s 确认全部 Up、Mirror Synchronized 即恢复。

Q5：如何确认安装的版本与官方一致？ A：psql --version 输出 psql (Apache Cloudberry) 14.4，SELECT version(); 输出含 Apache Cloudberry 2.1.0-incubating build bdf90c5518f；同时比对 DEB 的 SHA512 与官方发布文件（见 3.4）。

八、卸载与清理

8.1 停止数据库

su - gpadmin -c "
source /usr/local/cloudberry-db/cloudberry-env.sh
export COORDINATOR_DATA_DIRECTORY=/data/coordinator/gpseg-1
export PGPORT=5432
gpstop -a
"

实测回显（节选）：

20261013:19:01:05:010196 gpstop:cdw:gpadmin-[INFO]:-Segments stopped successfully      = 4
20261013:19:01:05:010196 gpstop:cdw:gpadmin-[INFO]:-Segments with errors during stop   = 0
20261013:19:01:05:010196 gpstop:cdw:gpadmin-[INFO]:-Database successfully shutdown with no errors reported

8.2 卸载软件包

dpkg -r apache-cloudberry-db-incubating

实测回显（节选）：

(Reading database ... 18404 files and directories currently installed.)
Removing apache-cloudberry-db-incubating (2.1.0-1-ubuntu22.04) ...

8.3 清理数据与用户

rm -rf /data/coordinator /data/primary /data/mirror
userdel -r gpadmin

⚠️ 注意：userdel -r 会删除 gpadmin 家目录，卸载前请确认无需保留该用户下的日志（~/gpAdminLogs）与配置（~/gpconfigs）。

九、参考链接

  • Apache Cloudberry 官方文档（部署与安装）：https://cloudberry.apache.org/docs/next/deployment/install_cloudberry/
  • 官方发布下载：https://github.com/apache/cloudberry/releases
  • Apache 归档（含源码与 KEYS）：https://archive.apache.org/dist/incubator/cloudberry/
  • 项目主页：https://cloudberry.apache.org/