Ubuntu 22.04 安装 Citus 14.2 指南

目标：在 Ubuntu 22.04 服务器上从 0 到 1 安装 PostgreSQL 18 + Citus 14.2 分布式扩展，覆盖官方 apt 在线安装、手动配置软件源、离线 deb 包三种方案，并给出单机模式与多节点集群的节点准备清单、版本升级/多版本管理与卸载清理。全部命令与回显均在 3 台 Ubuntu 22.04.5 LTS 服务器实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（PRETTY_NAME="Ubuntu 22.04.5 LTS"）
系统架构：x86_64
PostgreSQL 版本：18.6（包 postgresql-18，版本 18.6-1.pgdg22.04+2，来自 PGDG 官方源）
Citus 版本：14.2（扩展包 postgresql-18-citus-14.2，包版本 14.2.0.citus-1，来自 Citus Data 官方源；扩展版本号 14.2-1）
实测拓扑：3 台服务器（1 台作为协调器 coordinator + 2 台作为工作节点 worker），主机名 citus-node1/2/3，内网网段 10.89.61.0/24，主机名互相可解析
数据目录：/var/lib/postgresql/18/main
主配置：/etc/postgresql/18/main/postgresql.conf，认证配置：/etc/postgresql/18/main/pg_hba.conf

💡 Citus 是 PostgreSQL 扩展而非独立数据库：安装分两层——先装 PostgreSQL 本体（PGDG 源），再装 Citus 扩展（Citus Data 官方源）。两个源的添加顺序与依赖关系见第四章。

二、前置条件

安装前确认以下条件，避免中途报错：

cat /etc/os-release | grep PRETTY_NAME && uname -m && hostname

执行结果：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
x86_64
citus-node1

网络：能访问 apt.postgresql.org（PGDG 源）与 repos.citusdata.com（Citus 源）；服务器间 5432 端口互通（多节点部署必需）。
系统更新与基础工具：

sudo apt-get update
sudo apt-get install -y curl ca-certificates gnupg

执行结果（输出节选）：

Fetched 49.0 MB in 29s (1684 kB/s)
Reading package lists...

主机名解析（多节点）：把各节点主机名与内网 IP 写入每台服务器的 /etc/hosts，或使用内网 DNS，保证 citus-node2、citus-node3 等主机名互相可解析。

三、版本选型说明

Citus 扩展包命名规则为 postgresql-<PG大版本>-citus-<Citus minor>，两个版本维度独立选择。查询当前可安装版本：

apt-cache madison postgresql-18-citus-14.2

执行结果：

postgresql-18-citus-14.2 | 14.2.0.citus-1 | https://repos.citusdata.com/community/ubuntu jammy/main amd64 Packages

Citus Data 官方源中同一 PG 大版本下多个 Citus minor 包并存（实测于 Ubuntu 22.04）：

apt-cache search ^postgresql-18-citus | head -5

执行结果：

postgresql-18-citus-14.0 - sharding and distributed joins for PostgreSQL
postgresql-18-citus-14.0-dbgsym - debug symbols for postgresql-18-citus-14.0
postgresql-18-citus-14.1 - sharding and distributed joins for PostgreSQL
postgresql-18-citus-14.1-dbgsym - debug symbols for postgresql-18-citus-14.1
postgresql-18-citus-14.2 - sharding and distributed joins for PostgreSQL

选型结论：新装直接选当前最新稳定线 Citus 14.2（扩展包 postgresql-18-citus-14.2，2026-10-20 查询候选版本 14.2.0.citus-1）+ PostgreSQL 18（Citus 14.0 起官方支持 PG 18）。历史系统若仍跑 PG 16/17，源内同样提供对应包（如实测 postgresql-16-citus-12.1、postgresql-16-citus-13.0、postgresql-16-citus-13.1、postgresql-16-citus-13.2 等多版本并存）。

四、方案 A：官方 apt 源在线安装（推荐）

本方案用两个官方源：PostgreSQL 本体来自 PGDG 官方源，Citus 扩展来自 Citus Data 官方源。先说明一个实测结论——PGDG 源本身不发布 Citus 包（见 4.2 前的验证），Citus 扩展必须从 Citus 官方源获取。

4.1 添加 PostgreSQL 官方 PGDG 源

PostgreSQL 18 需从 PGDG 官方源安装（Ubuntu 22.04 自带仓库只有旧版 PG）。导入官方签名密钥并写源文件：

sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc
echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt jammy-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list
sudo apt-get update

执行结果（输出节选）：

Get:6 https://apt.postgresql.org/pub/repos/apt jammy-pgdg/main amd64 Packages [1159 kB]
Fetched 1348 kB in 2s (629 kB/s)
Reading package lists...

⚠️ 实测验证：仅添加 PGDG 源时，apt-cache policy postgresql-18-citus-14.2 输出为空、apt-cache search citus 无结果——PGDG 源不含任何 Citus 包。Citus 扩展必须另行添加官方源（4.2）。

4.2 添加 Citus Data 官方源（一键脚本）

Citus 官方提供一键脚本，自动检测已配置的 PG 大版本、写源文件并导入签名密钥：

curl -fsSL https://install.citusdata.com/community/deb.sh | sudo bash

执行结果（逐行实测）：

Checking for postgresql-18...
Detected postgresql-18...
Installing apt-transport-https... done.
Installing /etc/apt/sources.list.d/citusdata_community.list... done.
Importing Citus Data Community gpg key... done.
Running apt-get update... done.

The repository is set up! You can now install packages.

确认候选版本（此时 Citus 源与 PGDG 源同时可见）：

apt-cache policy postgresql-18-citus-14.2 postgresql-18

执行结果（逐行实测）：

postgresql-18-citus-14.2:
  Installed: (none)
  Candidate: 14.2.0.citus-1
  Version table:
     14.2.0.citus-1 500
        500 https://repos.citusdata.com/community/ubuntu jammy/main amd64 Packages
postgresql-18:
  Installed: (none)
  Candidate: 18.6-1.pgdg22.04+2
  Version table:
     18.6-1.pgdg22.04+2 500
        500 https://apt.postgresql.org/pub/repos/apt jammy-pgdg/main amd64 Packages
     18.4-1.pgdg22.04+1 500
        500 https://apt.postgresql.org/pub/repos/apt jammy-pgdg/main amd64 Packages
     18.3-1.pgdg22.04+1 500
        500 https://apt.postgresql.org/pub/repos/apt jammy-pgdg/main amd64 Packages

脚本生成的两个源文件内容（实测 cat 回显），排查源问题时可直接比对：

cat /etc/apt/sources.list.d/citusdata_community.list

执行结果：

# this file was generated by packagecloud.io for
# the repository at https://repos.citusdata.com/community

deb [signed-by=/etc/apt/keyrings/citusdata_community-archive-keyring.gpg] https://repos.citusdata.com/community/ubuntu/ jammy main
deb-src [signed-by=/etc/apt/keyrings/citusdata_community-archive-keyring.gpg] https://repos.citusdata.com/community/ubuntu/ jammy main

4.3 安装 PostgreSQL 18 与 Citus 14.2

sudo apt-get install -y postgresql-18 postgresql-18-citus-14.2

执行结果（输出节选，实测首尾）：

syncing data to disk ... ok
invoke-rc.d: could not determine current runlevel
invoke-rc.d: policy-rc.d denied execution of start.
Setting up postgresql-18-jit (18.6-1.pgdg22.04+2) ...
Setting up postgresql-18-citus-14.2 (14.2.0.citus-1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

💡 postgresql-18-citus-14.2 会把扩展装入 /usr/lib/postgresql/18/lib/citus.so 与 /usr/share/postgresql/18/extension/（含 citus.control、citus_columnar.control 列存扩展等）。安装过程会尝试自动启动 PG 集群：标准 systemd 服务器上集群会随安装直接运行；若环境禁止开机自启（如出现上面 policy-rc.d denied execution of start 提示），执行 4.5 的手动启动即可。

4.4 基础配置

Citus 要求预加载扩展并监听外网口（多节点时）。编辑 /etc/postgresql/18/main/postgresql.conf：

sudo sed -i "s/^#listen_addresses.*/listen_addresses = '*'/" /etc/postgresql/18/main/postgresql.conf
sudo sed -i "s/^#shared_preload_libraries.*/shared_preload_libraries = 'citus'/" /etc/postgresql/18/main/postgresql.conf
grep -E "^(listen_addresses|shared_preload_libraries)" /etc/postgresql/18/main/postgresql.conf

执行结果：

listen_addresses = '*'
shared_preload_libraries = 'citus'

认证放行（/etc/postgresql/18/main/pg_hba.conf）。内网网段与回环的信任规则，其中回环的 replication 规则必须为 trust（Citus 在线搬分片基于逻辑复制，会从本机回环发起 replication 连接，默认的 scram 认证会导致迁移报 fe_sendauth: no password supplied，详见第十章 FAQ）：

sudo tee -a /etc/postgresql/18/main/pg_hba.conf <<'EOF'
# Citus cluster
host all all 10.89.61.0/24 trust
host all all 127.0.0.1/32 trust
host replication all 127.0.0.1/32 trust
host all all ::1/128 trust
host replication all ::1/128 trust
EOF

再追加两个多节点部署建议项（在线分片迁移依赖逻辑复制与 citus 逻辑解码插件，缺一会在迁移时报错，详见第十章 FAQ）：

echo "wal_level = logical" | sudo tee -a /etc/postgresql/18/main/postgresql.conf
echo "output_plugin_libraries = 'citus'" | sudo tee -a /etc/postgresql/18/main/postgresql.conf

💡 wal_level = logical：单机模式可不加，但规划做集群/分片迁移就必须设（默认 replica 不支持逻辑复制搬迁）。output_plugin_libraries = 'citus'：PostgreSQL 18 的新安全机制，显式声明允许作为逻辑解码输出插件的库；Citus 14.x on PG 18 做在线分片迁移时必须放行，否则报 library "citus" may not be used as an output plugin。

4.5 启动并创建扩展

sudo pg_ctlcluster 18 main start
pg_lsclusters

执行结果：

Ver Cluster Port Status Owner    Data directory               Log file
18  main    5432 online postgres /var/lib/postgresql/18/main /var/log/postgresql/postgresql-18-main.log

在目标数据库创建扩展（默认 postgres 库；业务库同理，每个要用分片特性的库都要创建）：

sudo -u postgres psql -c "CREATE EXTENSION citus;"
sudo -u postgres psql -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'citus';"

执行结果：

CREATE EXTENSION

 extname | extversion
---------+------------
 citus   | 14.2-1
(1 row)

4.6 安装验证

三项验证：预加载是否生效、Citus 版本信息、PG 服务端版本。

sudo -u postgres psql -tAc "SHOW shared_preload_libraries;"
sudo -u postgres psql -c "SELECT citus_version();"
sudo -u postgres psql -tAc "SELECT version();"

执行结果（逐行实测）：

 citus

                                                                                     citus_version
----------------------------------------------------------------------------------------------------------------------------------------------------------------------
 Citus 14.2.0 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0, 64-bit
(1 row)

PostgreSQL 18.6 (Ubuntu 18.6-1.pgdg22.04+2) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0, 64-bit

psql 扩展登记信息（\dx citus 实测）：

                        List of installed extensions
 Name  | Version | Default version |   Schema   |        Description
-------+---------+-----------------+------------+----------------------------
 citus | 14.2-1  | 14.2-1          | pg_catalog | Citus distributed database
(1 row)

三项全部符合预期（预加载 citus、Citus 14.2.0、PG 18.6），安装完成。

五、方案 B：手动配置官方源（不跑脚本）

一键脚本适合交互环境；托管/审计场景常要求「不执行远程脚本」，此时手动导入密钥与源文件，效果等价（实测在 node1 上删除脚本产物后手工重建）。

# 1. 导入 Citus Data Community 签名密钥为 keyring 文件
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://packagecloud.io/citusdata/community/gpgkey | sudo gpg --dearmor --yes -o /etc/apt/keyrings/citusdata_community-archive-keyring.gpg

# 2. 手写源文件（与脚本生成内容一致）
echo "deb [signed-by=/etc/apt/keyrings/citusdata_community-archive-keyring.gpg] https://repos.citusdata.com/community/ubuntu/ jammy main" | sudo tee /etc/apt/sources.list.d/citusdata_community.list

# 3. 刷新并确认
sudo apt-get update
apt-cache policy postgresql-18-citus-14.2

执行结果（实测关键行）：

KEYRING-OK
deb [signed-by=/etc/apt/keyrings/citusdata_community-archive-keyring.gpg] https://repos.citusdata.com/community/ubuntu/ jammy main
Get:4 https://repos.citusdata.com/community/ubuntu jammy InRelease [29.2 kB]
Get:6 https://repos.citusdata.com/community/ubuntu jammy/main amd64 Packages [101 kB]

postgresql-18-citus-14.2:
  Installed: 14.2.0.citus-1
  Candidate: 14.2.0.citus-1
  Version table:

apt-get update 出现 repos.citusdata.com ... InRelease 命中即说明手动源生效，后续安装步骤与 4.3 起完全相同。

六、方案 C：离线 deb 包安装（断网内网）

内网服务器无法访问官方源时，在任一可联网的同版本机器上用 apt-get download 拉取 deb 包，拷贝到目标机后 dpkg -i 安装。目标机需已具备全部依赖（PostgreSQL 18 等），或一并下载依赖包。

在联网机上下载（实测）：

apt-get download postgresql-18-citus-14.2
ls -la postgresql-18-citus-14.2_*.deb

执行结果：

W: Download is performed unsandboxed as root as file '/root/postgresql-18-citus-14.2_14.2.0.citus-1_amd64.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)
-rw-r--r-- 1 root root 3006300 Aug  6 11:09 postgresql-18-citus-14.2_14.2.0.citus-1_amd64.deb

⚠️ 下载约 3 MB 的 deb 包（实测 3,006,300 字节）；root 用户在 root 家目录执行时出现的 _apt 权限警告不影响结果，包文件正常生成。建议在普通用户目录或临时目录执行避免该警告。

把 deb 包拷贝到离线机后安装（实测：先卸载再从本地包重装，模拟离线机首次安装）：

sudo dpkg -i postgresql-18-citus-14.2_14.2.0.citus-1_amd64.deb
dpkg -l postgresql-18-citus-14.2 | tail -1

执行结果（输出节选，实测）：

Building PostgreSQL dictionaries from installed myspell/hunspell packages...
Removing obsolete dictionary files:
ii  postgresql-18-citus-14.2 14.2.0.citus-1 amd64        sharding and distributed joins for PostgreSQL

dpkg -i 报依赖缺失时（离线机未装 postgresql-18），把依赖包一并下载拷贝后按依赖顺序 dpkg -i *.deb，或改用 apt-get install /path/to/*.deb 让 apt 自动解算。安装后的配置与验证同 4.4–4.6。

七、多方案对比与选择建议

维度	方案 A：一键脚本在线源	方案 B：手动配置源	方案 C：离线 deb 包
是否需联网	需要访问 install.citusdata.com/repos.citusdata.com	同左	仅中转机需联网
密钥管理	脚本自动导入	手动导入（可审计）	无需（随包安装）
版本控制	跟随源更新	跟随源更新	锁定具体 deb 版本
适用场景	常规联网服务器（推荐）	托管/审计环境，禁止执行远程脚本	断网内网、批量分发
优点	最快、不易出错	全程可审计、密钥位置明确	完全离线、版本固定
缺点	执行了远程脚本	步骤略多	需自行处理依赖闭环

选择建议：能联网选方案 A（或审计要求改 B）；内网环境用方案 C，把 postgresql-18 全套依赖包一并打包。

八、coordinator/worker 节点准备

8.1 单机模式（coordinator-only）

单机安装（完成第四章）后 CREATE EXTENSION citus; 即刻可用：不注册任何 Worker 时，create_distributed_table() 创建的分布表数据保留在本机（coordinator 本地分片），可先用 Citus 的监控/元数据能力，后续再平滑扩为多节点。验证当前角色（未注册元数据前为假）：

sudo -u postgres psql -tAc "SELECT citus_is_coordinator();"

执行结果（注册 Worker 之前实测）：

8.2 多节点集群的节点预配清单

多节点部署时每个节点（协调器与全部 Worker）都要完成以下相同准备，缺一不可：

第四章的完整安装（两台 Worker 同样安装 postgresql-18-citus-14.2，实测三台扩展版本均为 14.2-1）；
shared_preload_libraries = 'citus' 与 listen_addresses = '*'；
wal_level = logical、output_plugin_libraries = 'citus'（在线分片迁移/重平衡依赖，见 FAQ）；
pg_hba.conf 放行集群内网网段与回环 replication 信任（4.4 的规则块原样套用，网段按实际内网修改）；
每个节点的目标数据库执行 CREATE EXTENSION citus;（扩展只在库级别生效，跨库不继承）；
主机名互相解析、系统时钟同步（NTP）。

⚠️ Worker 节点不需要、也不应该自己执行 citus_add_node——节点注册只由协调器完成（多节点组建过程见本专栏集群部署篇）。示例账号一律使用 postgres 超管在 postgres 库操作。

九、升级、降级与多版本管理

查看已装与可用版本：

apt list -a postgresql-18-citus-14.2 2>/dev/null | head -3

执行结果：

Listing...
postgresql-18-citus-14.2/jammy,now 14.2.0.citus-1 amd64 [installed]

小版本升级（14.2.x 内）：常规 sudo apt-get update && sudo apt-get install --only-upgrade postgresql-18-citus-14.2，随后在目标库执行 ALTER EXTENSION citus UPDATE;（扩展内部版本升级需要），并重启 PostgreSQL 重新加载 citus.so。

跨 minor 版本（如 14.1 → 14.2）：两套包可并存（见第三章），安装新包 sudo apt-get install -y postgresql-18-citus-14.2 后，把 shared_preload_libraries 与各库扩展切换到新版本，再逐库 ALTER EXTENSION citus UPDATE;。跨大版本（PG 16 → PG 18）需按官方升级文档使用 pg_upgrade 并执行 citus_prepare_pg_upgrade()/citus_finish_pg_upgrade() 配套 UDF。

降级：Citus 扩展与元数据格式向前不兼容，降级前必须先备份并按官方降级路径导出重灌；一般做法是 sudo apt-get install postgresql-18-citus-14.1 覆盖安装后重建集群元数据，生产环境强烈建议先演练。多版本并存要点：同一台服务器可同时安装 postgresql-18-citus-14.0/14.1/14.2 三套扩展文件（互不覆盖），同一时刻每个数据库只能启用其中一个版本。

十、常见问题（FAQ）

Q1：PGDG 源里怎么找不到 citus 包？ 实测结论：PGDG（apt.postgresql.org）jammy-pgdg main 不发布 Citus 包——apt-cache policy postgresql-18-citus-14.2 在仅有 PGDG 源时输出为空。必须添加 Citus Data 官方源（4.2/第五章）。

Q2：CREATE EXTENSION citus; 报 citus extension is not found？ 说明扩展包未安装或已被卸载（实测 purge 后复现）：

ERROR:  citus extension is not found

解决：确认 dpkg -l postgresql-18-citus-14.2 存在；不存在则按第四章重装，再执行 CREATE EXTENSION citus;。

Q3：改了 shared_preload_libraries 却不生效？ 该参数必须重启 PostgreSQL 才生效（reload 无效）。用 sudo -u postgres psql -tAc "SHOW shared_preload_libraries;" 确认值为 citus；未预加载时创建分布表会直接报错。

Q4：在线迁移/重平衡分片报 fe_sendauth: no password supplied（目标 localhost）？ 根因是 pg_hba.conf 的默认回环规则：Citus 搬分片基于逻辑复制，会从本机回环发起 replication 协议连接，而默认规则对 127.0.0.1/32 与 ::1/128 的 replication 连接要求 scram 认证。按 4.4 放行 host replication all 127.0.0.1/32 trust（及 ::1/128）后 reload 即可。注意 pg_hba 是顺序匹配，新规则必须位于同名默认规则之前。

Q5：分片迁移报 logical decoding requires "wal_level" >= "logical"？ Worker 的 wal_level 还是默认 replica。所有节点设置 wal_level = logical 并重启 PostgreSQL 后重试（该参数需重启，reload 不生效）。

Q6：PG 18 上分片迁移报 library "citus" may not be used as an output plugin？ PostgreSQL 18 收紧了逻辑解码输出插件白名单。所有节点在 postgresql.conf 增加 output_plugin_libraries = 'citus' 并重启后恢复（实测三节点统一加配置后迁移成功）。

Q7：安装日志出现 invoke-rc.d: policy-rc.d denied execution of start. 是否异常？ 这是环境禁用了「安装后自动启动服务」（常见于受限环境）；包安装本身成功，手动 sudo pg_ctlcluster 18 main start 启动即可。标准 systemd 服务器上不会出现该提示，集群随安装自动启动。

十一、卸载与清理

只卸载 Citus 扩展（保留 PostgreSQL）：

sudo apt-get purge -y postgresql-18-citus-14.2

执行结果（输出节选，实测）：

Processing triggers for postgresql-common (293.pgdg22.04+1) ...
Building PostgreSQL dictionaries from installed myspell/hunspell packages...
Removing obsolete dictionary files:

验证扩展文件已移除（实测回显）：

sudo -u postgres psql -d postgres -c "CREATE EXTENSION citus;"

执行结果：

ERROR:  citus extension is not found

连同 PostgreSQL 一起清理时再执行 sudo apt-get purge -y postgresql-18 postgresql-18-citus-14.2 && sudo rm -rf /var/lib/postgresql/18 /etc/postgresql/18（数据目录与配置一并删除，先确认备份）。注意：卸载前若集群元数据中已注册分片，先用 undistribute_table() 还原各分布表或按官方路径导出数据，避免留下不可用的分布式元数据。

十二、参考链接

Citus 官方多节点安装文档（Debian/Ubuntu）：https://docs.citusdata.com/en/stable/installation/multi_node_debian.html
Citus 官方单节点安装文档：https://docs.citusdata.com/en/stable/installation/single_node_debian.html
Citus GitHub 仓库：https://github.com/citusdata/citus
Citus 14.2.0 Release：https://github.com/citusdata/citus/releases/tag/v14.2.0
PGDG 官方 apt 源说明：https://www.postgresql.org/download/linux/ubuntu/
本平台同专栏实测篇：《Citus 14.2 集群部署指南》（多节点组建、分片与重平衡实测）