香港服务器部署PostgreSQL 18前,如何核对系统与扩展兼容性?
很多人把“服务器能安装 PostgreSQL 18”或“psql 可以连接数据库”当成兼容性通过。实际上,这只能证明基础进程或客户端能够工作,不能说明操作系统、C 运行库、扩展二进制、应用驱动和升级工具已经形成完整兼容链。
在香港服务器上部署 PostgreSQL 18,真正需要核对的是:服务器架构和发行版是否有可用的软件包;数据库扩展是否提供针对 PostgreSQL 18 的版本;扩展依赖的 glibc、OpenSSL、ICU 或其他动态库是否匹配;应用使用的运行时和驱动是否能正确处理认证、TLS、数据类型与连接池;如果是从旧版本升级,备份、复制和升级工具是否支持目标版本。
先划清兼容性的概念边界
“能启动”不代表“可用于生产”
兼容性至少可以分成四个层次:
- 系统层兼容:CPU 架构、Linux 发行版、内核、文件系统、权限机制和系统库能够支撑 PostgreSQL 18。
- 数据库层兼容:PostgreSQL 服务端能够初始化、启动、读写数据,并正确使用目标数据目录。
- 扩展层兼容:PostGIS、pgvector、
pg_stat_statements、FDW 或自研 C 扩展能够在 PostgreSQL 18 上安装和加载。 - 应用层兼容:应用运行时、数据库驱动、迁移工具和连接池能够使用目标数据库的认证方式、协议、数据类型及 SQL 行为。
例如,服务器可以正常执行以下命令:
psql --version
但这个命令只显示客户端版本。即使客户端能够连接到 PostgreSQL 18,也无法证明:
- 应用使用的 JDBC、Python、Go 或 Node.js 驱动兼容;
- 数据库需要的扩展已经安装;
- C 扩展没有链接到旧版 PostgreSQL 的库;
shared_preload_libraries中的模块能够在重启后加载;- 备份恢复或主版本升级可以顺利完成。
因此,兼容性核对不能只看一个版本号,而要看对象之间的对应关系。
| 核对对象 | 需要匹配的内容 | 不能替代的判断 |
|---|---|---|
| PostgreSQL 服务端与操作系统 | CPU 架构、发行版、系统库、文件系统 | 不能仅以 SSH 或包管理器可用判断 |
| PostgreSQL 服务端与客户端 | 协议、认证方式、工具功能 | psql 能连接不代表应用驱动兼容 |
| PostgreSQL 服务端与扩展 | 扩展构建目标、SQL 脚本、动态库、版本矩阵 | pg_available_extensions 有记录不代表功能全部可用 |
| 应用运行时与驱动 | 驱动版本、TLS、数据类型、连接池、预处理语句 | 服务端启动成功不代表应用可用 |
| 旧版本与 PostgreSQL 18 | pg_upgrade、逻辑迁移、备份工具、扩展升级脚本 | 直接替换服务端软件包通常不是升级方案 |
主版本、次版本和扩展版本不是一回事
PostgreSQL 18 属于主版本。主版本之间可能存在系统目录、服务器内部接口和行为变化,不能把 PostgreSQL 17 的服务端文件、扩展动态库或数据目录直接当作 PostgreSQL 18 的组成部分。
扩展自己的版本号又是另一套体系。例如,某个扩展可能使用 1.x、3.x 或日期版本号,它的版本号不等于 PostgreSQL 的主版本号。判断扩展是否兼容时,应同时确认:
- 扩展维护者是否列出 PostgreSQL 18;
- 发行版或供应商是否提供针对 PostgreSQL 18 的软件包;
- 扩展安装目录和动态库是否来自目标 PostgreSQL 18 环境;
- 当前已安装扩展版本是否有适用于目标版本的升级脚本;
- 扩展依赖的外部库是否存在且 ABI 兼容。
PostgreSQL 18兼容性为什么是链条问题
软件包、编译环境与运行环境相互绑定
通过发行版软件源安装时,PostgreSQL 主程序通常已经按照某个发行版的编译器、C 运行库、OpenSSL 和目录布局构建。自行编译时,则会进一步受到以下因素影响:
./configure使用的库路径;- 编译器和链接器版本;
- 是否启用 ICU、SSL、LLVM、GSSAPI 等可选功能;
pg_config指向的是 PostgreSQL 18 还是其他主版本;- 安装路径和服务启动脚本是否与扩展预期一致。
尤其是扩展编译,不能只看服务器上是否存在一个名为 pg_config 的命令。以下命令显示的版本,才是扩展构建时应关注的目标:
command -v pg_config
pg_config --version
pg_config --bindir
pg_config --includedir-server
pg_config --pkglibdir
pg_config --sharedir
如果系统同时装有 PostgreSQL 16、17 和 18,PATH 中排在前面的 pg_config 可能仍然指向旧版本。此时扩展即使编译成功,也可能被放入错误的库目录,或者使用旧版服务器头文件构建。
扩展兼容性分为 SQL 层和二进制层
扩展不能简单按“能否安装”判断。可以把它们分为三类。
第一类是以 SQL 脚本为主的扩展。 这类扩展主要创建函数、操作符、类型或索引支持对象,通常不包含复杂的服务器内部调用。但它仍可能依赖 PostgreSQL 18 的系统目录、SQL 语法或行为变化,仍需在测试数据库执行创建和基本调用。
第二类是包含 C 或 C++ 动态库的扩展。 这类扩展需要使用目标 PostgreSQL 18 的服务器头文件和 pg_config 构建。即便扩展名称相同,针对 PostgreSQL 17 编译的 .so 文件也不能视为 PostgreSQL 18 的可用文件。主版本升级后,通常需要重新安装或重新编译。
第三类是需要预加载的扩展。 某些监控、审计、性能分析或连接管理扩展需要加入 shared_preload_libraries。这类扩展的风险不只是在执行 CREATE EXTENSION 时暴露,数据库重启时也可能因动态库不存在、依赖缺失或初始化失败而无法正常启动。
修改 shared_preload_libraries 会影响启动过程,应在测试环境先验证,并准备好配置回滚、数据库备份或云硬盘快照。不要为了“试一下”直接覆盖生产环境配置;如果启动失败,回滚原配置后仍需要安排维护窗口重新启动服务。
应用运行时不等于数据库服务端运行时
PostgreSQL 服务端本身主要由本地编译程序组成,并不要求服务器必须安装 Java、Python、Node.js 或 Go 运行时。应用使用什么运行时,是另一条兼容链:

应用代码
↓
语言运行时与数据库驱动
↓
libpq 或驱动自身的协议实现
↓
TLS、认证和网络连接
↓
PostgreSQL 18 服务端
因此,服务器上安装 psql 并不能验证应用驱动。需要单独核对:
- 应用使用的驱动版本是否声明支持 PostgreSQL 18;
- 驱动运行时是否支持 SCRAM、TLS 校验证书和目标加密套件;
timestamp、时区、数组、JSONB、枚举、自定义类型是否能正确映射;- 预处理语句、批量写入、
COPY、大字段和事务行为是否正常; - 连接池是否能处理服务端重启、连接失效和超时;
- ORM 或迁移工具是否理解 PostgreSQL 18 的系统目录和 SQL 行为。
客户端工具和服务端主版本不一定必须完全相同。较新的客户端通常可以连接较旧服务端,但这不代表旧客户端能够使用新服务端的全部特性。对于生产部署、备份恢复和迁移操作,使用与目标服务端匹配的 PostgreSQL 18 工具更容易减少版本差异。
香港服务器上需要重点核对的影响因素
服务器区域不是兼容性的决定因素
香港机房位置本身不会改变 PostgreSQL 18 的二进制兼容规则。真正可能产生差异的是服务器供应商提供的:
- 操作系统镜像版本;
- CPU 架构和虚拟化类型;
- 默认内核与安全策略;
- 软件源和镜像同步情况;
- 云硬盘或本地盘的文件系统;
- IPv4、IPv6、DNS 和时间同步配置。
例如,两台都标注为香港 Linux 服务器,一台可能是 x86_64 的 Debian,另一台可能是 ARM64 的 Ubuntu。PostgreSQL 主程序都可能有可用包,但某个商业扩展、自研扩展或闭源监控模块可能只提供 x86_64 构建版本。此时问题不是香港区域,而是架构与扩展供应范围不一致。

操作系统与系统库
需要记录以下信息,而不是只记录“Ubuntu”或“Linux”:
- 发行版名称与版本;
- CPU 架构;
- 内核版本;
glibc或其他 C 运行库版本;- OpenSSL 版本;
- ICU 版本和是否启用;
- SELinux、AppArmor 等安全策略;
- 数据目录所在文件系统和挂载选项。
可在不修改系统的情况下采集基础信息:
#!/usr/bin/env bash
set -u
echo "== OS =="
if [ -r /etc/os-release ]; then
. /etc/os-release
printf 'ID=%s\nVERSION_ID=%s\nPRETTY_NAME=%s\n' \
"${ID:-unknown}" "${VERSION_ID:-unknown}" "${PRETTY_NAME:-unknown}"
fi
echo
echo "== CPU and kernel =="
uname -a
uname -m
if command -v lscpu >/dev/null 2>&1; then
lscpu | grep -E 'Architecture|CPU\(s\)|Byte Order|Virtualization' || true
fi
echo
echo "== Runtime libraries =="
getconf GNU_LIBC_VERSION 2>/dev/null || true
if command -v openssl >/dev/null 2>&1; then
openssl version
fi
echo
echo "== PostgreSQL tools =="
for tool in psql pg_config pg_dump pg_restore; do
if command -v "$tool" >/dev/null 2>&1; then
printf '%s: ' "$tool"
"$tool" --version
command -v "$tool"
else
printf '%s: not found\n' "$tool"
fi
done
echo
echo "== Locale and time =="
locale 2>/dev/null || true
if command -v timedatectl >/dev/null 2>&1; then
timedatectl status || true
fi
这段信息主要用于发现“表面相同、底层不同”的环境。例如:
- 服务器是 ARM64,但目标扩展没有 ARM64 包;
pg_config属于 PostgreSQL 17,而运行中的服务端是 PostgreSQL 18;- 应用容器内的
glibc与宿主机不同; - OpenSSL 或安全策略阻止某个扩展加载;
- 默认 locale 与测试环境不同。
如果 PostgreSQL 运行在容器内,还要同时检查容器镜像中的用户空间库和宿主机内核。宿主机是 Ubuntu,并不代表容器内的 Debian 或其他基础镜像使用相同的 glibc、OpenSSL 和 CA 证书。
Locale、ICU与时区
数据库初始化时,编码、排序规则和字符分类环境会影响数据库行为。需要重点关注:
server_encoding;lc_collate;lc_ctype;- 是否使用 ICU;
- 操作系统 locale 是否在升级后发生变化;
- 应用和数据库对时区的约定是否一致。
香港服务器并不要求必须使用 Asia/Hong_Kong。更重要的是明确约定:数据库存储是否使用 UTC,应用展示是否转换为香港时间,定时任务由哪个时区解释。
如果在旧系统上初始化数据库,之后更换发行版、升级 ICU 或改变 locale,字符串排序规则可能发生变化。数据库虽然能够启动,索引排序、唯一性判断和排序结果却可能受到影响。涉及生产迁移时,应在数据副本上检查排序规则版本,并按照 PostgreSQL 和操作系统文档安排索引重建或相关维护,不能只以服务启动成功作为判断。
文件系统、存储与安全策略
PostgreSQL 数据目录需要稳定的文件锁、写入顺序和持久化语义。兼容性核对不等于只看磁盘容量,还应确认:
- 数据目录使用的文件系统;
- 挂载参数是否改变了同步写入行为;
- 云硬盘是否提供持久化保证;
- 备份目录是否位于独立存储;
- SELinux 或 AppArmor 是否允许数据库进程读取扩展动态库;
- 数据目录和扩展目录的属主、权限是否正确。
未经验证的网络文件系统不适合作为 PostgreSQL 数据目录。即使基本读写测试通过,也不代表锁、fsync、断电恢复和并发写入语义满足要求。可以把网络存储用于备份仓库,但仍需单独验证备份工具对该存储的可靠性。
围绕PostgreSQL 18部署所需的计算、内存与存储资源,A5数据提供香港Xeon Gold及AMD EPYC物理服务器,搭配SSD或NVMe存储,为数据库缓存、数据读写及应用与数据库分机部署提供硬件基础。香港产品中的CN2与国际带宽方案可承接不同访问方向的业务连接需求,另有大容量企业级硬盘存储系列,可用于数据库备份文件与历史数据归档。
PostgreSQL 18扩展的逐层验证方法
第一步:确认运行中的服务端,而不是只看客户端
先通过实际连接检查数据库主版本:
psql -X -v ON_ERROR_STOP=1 -c "
SELECT
current_setting('server_version') AS server_version,
current_setting('server_version_num') AS server_version_num,
current_setting('server_encoding') AS server_encoding;
SHOW lc_collate;
SHOW lc_ctype;
SHOW data_directory;
SHOW config_file;
SHOW shared_preload_libraries;
"
如果 server_version_num 的主版本部分不是 18,说明当前连接的并不是目标 PostgreSQL 18 实例。常见原因包括:
psql连接到了另一台服务器;- 本机同时运行多个 PostgreSQL 实例;
- DNS 或端口仍指向旧环境;
- 服务端已安装 18,但实际启动的还是旧主版本;
- 容器端口映射与预期不一致。
可以进一步核对服务单元,但不要假定所有发行版的服务名都相同:
systemctl list-unit-files --type=service 2>/dev/null | \
grep -Ei 'postgres|pgsql' || true
systemctl --type=service --state=running 2>/dev/null | \
grep -Ei 'postgres|pgsql' || true
Debian、Ubuntu、RHEL 系列以及供应商镜像的服务名称和数据目录可能不同,应以系统实际输出为准。
第二步:确认软件源与软件包来自同一条版本链
PostgreSQL 主程序、开发头文件、contrib 模块和扩展包最好来自同一发行版仓库、同一供应商仓库或同一套源码构建流程。不要随意混用:
- 系统自带的旧版 PostgreSQL 包;
- 第三方仓库的 PostgreSQL 18 主程序;
- 另一个仓库提供的旧版
contrib; - 手工复制的
.so文件; - 面向 PostgreSQL 17 编译的开发头文件。
Debian 或 Ubuntu 系列可以先查看候选版本,而不执行安装:
apt-cache policy postgresql-18 postgresql-server-dev-18 postgresql-contrib-18
RHEL 系列则可以查看已启用仓库中的候选包;具体包名会因仓库命名方式不同而变化:
dnf repolist
dnf list --available '*postgresql*' 2>/dev/null | head -n 80
这里的目标不是看到“有一个 PostgreSQL 包”,而是确认:
- 目标架构有对应软件包;
- PostgreSQL 18 服务端、开发文件和扩展包可以从同一版本体系获取;
- 包管理器没有把 PostgreSQL 17 或发行版默认版本作为候选;
- 扩展供应商明确支持当前发行版和架构。
第三步:检查扩展清单和目标版本
数据库中可以查询当前已安装扩展,以及软件目录中可用的扩展:
SELECT extname, extversion
FROM pg_extension
ORDER BY extname;
SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE name IN (
'btree_gin',
'pg_stat_statements',
'postgis',
'vector'
)
ORDER BY name;
查询结果的含义需要区分:
pg_extension表示当前数据库已经安装的扩展;pg_available_extensions表示服务器可以找到扩展控制文件;default_version表示控制文件声明的默认版本;installed_version为空,可能表示扩展文件存在但尚未安装到当前数据库;- 有记录不代表所有动态库依赖都能加载;
- 也不代表扩展的业务功能已经通过测试。
对于 PostGIS、pgvector 或商业扩展,还应执行维护者提供的版本检查函数或诊断命令。例如,PostGIS 环境可以在测试数据库中调用其版本信息函数,向量扩展则应确认类型、索引方法和基本运算都能正常使用。具体检查函数以扩展维护者文档为准,不要仅凭包名推断兼容性。
第四步:检查扩展动态库及其依赖
对于包含动态库的扩展,需要确认文件来自 PostgreSQL 18 的库目录。先获取目标目录:
pg_config --version
pg_config --pkglibdir
pg_config --sharedir
扩展控制文件通常位于类似以下目录,实际路径以 pg_config 输出为准:
find "$(pg_config --sharedir)/extension" \
-maxdepth 1 -type f \
\( -name 'vector.control' -o -name 'postgis*.control' \) \
-print
动态库依赖可以使用 ldd 检查。下面以 vector 为例,文件名和路径必须根据实际扩展调整:
EXT_DIR="$(pg_config --pkglibdir)"
EXT_SO="$(find "$EXT_DIR" -maxdepth 1 -type f -name 'vector*.so' -print -quit)"
if [ -n "$EXT_SO" ]; then
echo "Checking: $EXT_SO"
ldd "$EXT_SO"
else
echo "The target extension shared library was not found."
fi
如果结果出现 not found,通常说明系统缺少运行库、库路径没有配置,或者扩展包与当前系统不匹配。不要直接从另一台服务器复制一个 .so 文件到生产环境,这样可能引入:
- PostgreSQL 主版本 ABI 不匹配;
glibc或 C++ ABI 不匹配;- OpenSSL 主版本不匹配;
- 安全策略拒绝加载;
- 依赖库升级后产生隐蔽崩溃。
更稳妥的处理方式是安装目标发行版和目标 PostgreSQL 18 对应的软件包,或者在目标环境中使用 PostgreSQL 18 的开发文件重新编译。
第五步:在隔离数据库中执行创建和基本功能测试
CREATE EXTENSION 会修改数据库系统目录,不能把生产数据库当作试验场。应使用生产库的脱敏副本、临时实例或可销毁的测试数据库,并提前保留备份或快照。
下面是一个只适合测试数据库的示例:
CREATE EXTENSION IF NOT EXISTS btree_gin;
SELECT extname, extversion
FROM pg_extension
WHERE extname = 'btree_gin';
CREATE TABLE IF NOT EXISTS extension_probe (
id integer,
tags text[]
);
CREATE INDEX extension_probe_tags_idx
ON extension_probe
USING gin (tags);
DROP TABLE extension_probe;
如果测试的是需要预加载的扩展,还要分两步:
- 在测试环境配置
shared_preload_libraries; - 安排测试实例重启,确认服务能够启动并执行扩展功能。
只有在重启后仍能正常启动、扩展函数可调用、日志中没有动态库或符号错误,才算完成了预加载层验证。若扩展加载失败,回滚方式应是恢复原配置并重启测试实例;生产环境则需要在变更前准备维护窗口、备份和明确的配置回退方案。
第六步:从应用侧验证,而不是只从服务器本机验证
应用测试应尽量使用与生产相同的:
- 运行时版本;
- 驱动和 ORM 版本;
- 数据库连接地址;
- TLS 模式和证书校验方式;
- 用户权限;
- 连接池参数;
- DNS、IPv4 或 IPv6 路径。
至少应覆盖以下场景:
| 测试项 | 核对内容 |
|---|---|
| 建立连接 | 用户认证、数据库名、端口、连接超时 |
| TLS | 证书链、主机名校验、加密协议 |
| 事务 | 提交、回滚、并发连接和连接复用 |
| 预处理语句 | 参数绑定、类型推断、重复执行 |
| 数据类型 | JSONB、数组、枚举、时间戳、数值精度 |
| 批量操作 | COPY、批量插入、大字段和错误恢复 |
| 时区 | 应用时区、数据库时区和夏令时规则 |
| 连接池 | 服务重启、连接断开、连接回收和重连 |
| 迁移工具 | 建表、索引、约束、函数和扩展处理 |
“服务器本机使用 psql 成功”只证明本机客户端到本机服务端的链路正常。应用从其他主机连接时,还可能受到证书主机名、DNS、IPv6、访问控制和连接池行为影响。
升级、复制与备份工具的兼容性
主版本升级不能只替换安装包
从 PostgreSQL 17 或更早版本升级到 PostgreSQL 18,通常需要选择经过验证的升级路径,例如:
pg_upgrade;- 逻辑复制;
pg_dump与pg_restore;- 供应商提供的迁移工具。
pg_upgrade 要求旧版本和新版本的二进制、数据目录、扩展文件以及操作系统环境满足相应条件。扩展必须在新版本环境中提前准备好,且新旧版本之间存在可用的升级脚本或兼容迁移方案。
可以在生产副本或快照上执行检查模式:
/path/to/postgresql-18/bin/pg_upgrade --check \
--old-bindir=/path/to/postgresql-17/bin \
--new-bindir=/path/to/postgresql-18/bin \
--old-datadir=/path/to/old/data \
--new-datadir=/path/to/new/data
示例中的路径必须替换为实际路径。--check 主要用于发现升级前置问题,但不等于完整业务验收,也不能代替备份恢复演练。正式升级前仍需确认:
- 备份可以在独立环境恢复;
- 所有扩展在新实例中可用;
- 应用迁移脚本能够执行;
- 统计信息、索引和权限处理符合预期;
- 失败时有保留旧实例或恢复快照的方案。
物理流复制通常要求主库和备库处于相同主版本体系。逻辑复制可以用于跨主版本迁移,但它不会自动解决扩展对象、序列、DDL、用户权限、自定义类型和业务写入切换问题。复制工具和高可用组件也应查看其针对 PostgreSQL 18 的兼容矩阵。
备份工具也要单独验证
备份工具能否连接数据库,不等于备份一定可以恢复到 PostgreSQL 18。至少要测试:
- 全量备份是否成功;
- 备份文件是否包含扩展相关对象;
- 新环境能否恢复角色、权限、表、索引和函数;
- 恢复后扩展是否处于可用状态;
- 应用是否可以使用恢复后的数据库;
- 恢复耗时和存储空间是否满足维护窗口。
特别是使用 pg_dump、pg_restore 或第三方备份工具时,应使用支持目标主版本的客户端工具。不要用一条成功的备份命令替代完整恢复验证。
适用边界:什么结果可以通过,什么结果应暂停
可以将核对结果分成三档。
| 结果 | 判断条件 | 处理建议 |
|---|---|---|
| 可进入业务测试 | 系统架构和发行版有支持包,服务端确认是 18,目标扩展可安装并通过基本功能测试,应用连接和关键数据类型正常 | 继续进行压力、备份恢复和发布演练 |
| 条件通过 | PostgreSQL 18 本身可用,但某个扩展或驱动只有维护者的预览支持,或需要重新编译 | 先在隔离环境固定版本并获得供应商支持,不直接用于关键生产库 |
| 不应上线 | 扩展没有 PostgreSQL 18 构建版本、动态库依赖缺失、应用驱动无法处理关键类型,或升级工具不支持目标版本 | 保留旧版本,等待兼容包或更换经过验证的组件 |
以下情况尤其不能用“服务已经启动”来掩盖:
- 目标扩展只有 PostgreSQL 17 的二进制文件;
pg_available_extensions有记录,但CREATE EXTENSION或函数调用失败;pg_config和运行中的服务端属于不同主版本;- 应用能够建立连接,但时间戳、数组、JSONB 或数值精度测试不通过;
shared_preload_libraries修改后尚未完成重启验证;- 只在服务器本机测试过,未从应用实际网络路径验证;
- 备份已生成,但没有在独立 PostgreSQL 18 实例中恢复;
- 操作系统或 ICU 升级后,排序规则变化未经检查;
- 供应商没有明确支持当前 CPU 架构或发行版版本。
核对依据应分层使用:操作系统与 PostgreSQL 18 的支持平台、安装要求和升级说明,以 PostgreSQL 官方文档为准;扩展是否支持 PostgreSQL 18,以扩展维护者或软件供应商发布的版本矩阵为准;应用驱动和 ORM,则以其自身发行说明及实际业务测试为准。
因此,香港服务器部署 PostgreSQL 18 的最小可接受判断不是“能不能安装”,而是完成一条可复核链路:确认操作系统和架构,确认运行中的服务端主版本,确认 pg_config 与扩展构建目标一致,检查动态库依赖,在隔离数据库中创建并调用扩展,再从真实应用运行时验证连接、数据类型、TLS、连接池和迁移流程。只要其中一个关键环节没有得到验证,就应把结果标记为条件兼容,而不是直接视为生产兼容。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3437.html



