香港服务器部署PostgreSQL 18前,如何核对系统与扩展兼容性?

发布人:A5数据发布时间:2026-10-13 09:21阅读量:139

很多人把“服务器能安装 PostgreSQL 18”或“psql 可以连接数据库”当成兼容性通过。实际上,这只能证明基础进程或客户端能够工作,不能说明操作系统、C 运行库、扩展二进制、应用驱动和升级工具已经形成完整兼容链。

在香港服务器上部署 PostgreSQL 18,真正需要核对的是:服务器架构和发行版是否有可用的软件包;数据库扩展是否提供针对 PostgreSQL 18 的版本;扩展依赖的 glibc、OpenSSL、ICU 或其他动态库是否匹配;应用使用的运行时和驱动是否能正确处理认证、TLS、数据类型与连接池;如果是从旧版本升级,备份、复制和升级工具是否支持目标版本。

先划清兼容性的概念边界

“能启动”不代表“可用于生产”

兼容性至少可以分成四个层次:

  1. 系统层兼容:CPU 架构、Linux 发行版、内核、文件系统、权限机制和系统库能够支撑 PostgreSQL 18。
  2. 数据库层兼容:PostgreSQL 服务端能够初始化、启动、读写数据,并正确使用目标数据目录。
  3. 扩展层兼容:PostGIS、pgvector、pg_stat_statements、FDW 或自研 C 扩展能够在 PostgreSQL 18 上安装和加载。
  4. 应用层兼容:应用运行时、数据库驱动、迁移工具和连接池能够使用目标数据库的认证方式、协议、数据类型及 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 18pg_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 包”,而是确认:

  1. 目标架构有对应软件包;
  2. PostgreSQL 18 服务端、开发文件和扩展包可以从同一版本体系获取;
  3. 包管理器没有把 PostgreSQL 17 或发行版默认版本作为候选;
  4. 扩展供应商明确支持当前发行版和架构。

第三步:检查扩展清单和目标版本

数据库中可以查询当前已安装扩展,以及软件目录中可用的扩展:

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;

如果测试的是需要预加载的扩展,还要分两步:

  1. 在测试环境配置 shared_preload_libraries;
  2. 安排测试实例重启,确认服务能够启动并执行扩展功能。

只有在重启后仍能正常启动、扩展函数可调用、日志中没有动态库或符号错误,才算完成了预加载层验证。若扩展加载失败,回滚方式应是恢复原配置并重启测试实例;生产环境则需要在变更前准备维护窗口、备份和明确的配置回退方案。

第六步:从应用侧验证,而不是只从服务器本机验证

应用测试应尽量使用与生产相同的:

  • 运行时版本;
  • 驱动和 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。至少要测试:

  1. 全量备份是否成功;
  2. 备份文件是否包含扩展相关对象;
  3. 新环境能否恢复角色、权限、表、索引和函数;
  4. 恢复后扩展是否处于可用状态;
  5. 应用是否可以使用恢复后的数据库;
  6. 恢复耗时和存储空间是否满足维护窗口。

特别是使用 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

相关推荐