# Postgresql数据库安装参考手册

# 组件合规性说明

PostgreSQL采用类BSD许可协议(又称 PostgreSQL License (opens new window)),在合规性活动范围内可以免费使用:

  • 允许任何目的使用、修改、分发代码(包括闭源商业产品),无需开源衍生作品。
  • 仅需保留原始版权声明和许可文本。
  • 基于PostgreSQL开发的商业产品无需公开源代码。

# Postgresql官网和维护策略

Postgresql官网访问地址:https://www.postgresql.org/

Postgresql每年都有新的发行版本,每个发行版本有维护生命周期,官网的版本控制策略说明地址: https://www.postgresql.org/support/versioning/

建议选择次新稳定维护版本,如最新版本如果是V18,则优先选择次新的V17版本。

注意关注大版本的Final Release(截止维护日期),确保数据库尽量在维护日期内,以获得持续的安全、问题处理。

1765332117924.png

# 部署方案

本手册提供多种部署方案供项目参考:

方案 适用系统 部署方案 推荐指数
方案一 Linux、信创系统 基于Docker免编译安装 ★★★★★
方案二 Linux、信创系统 联网安装(限定系统) ★★★
方案三 Linux、信创系统 源码编译安装 ★★★★
方案四 Windows Server Windows安装 ★★

# Linux免编译安装

如项目允许在Docker容器中运行数据库,可以采用此方案,当前方案部署效率高。

# Linux免编译部署步骤

1、下载免编译安装包,下载地址 https://pan.baidu.com/s/1BSkVbPckeqzR1NkxwUgu8g?pwd=2026

找到合适的版本(如本例选择postgres17),然后根据服务器实际情况选择在合适的架构包(x86服务器选择amd64、arm服务器选择arm64、龙芯对应loong64):

1792647470460.png

2、上传安装包到服务器:自行将安装包上传至服务器,建议放到 /data 目录(后续示例)。

3、解压安装包

cd /data
# 包上传到 /data 目录 再解压
tar -xf multi-deploy-postgres-17.10-amd64.tgz --one-top-level
cd multi-deploy-postgres-17.10-amd64/
ls

解压后的典型目录结构如下(以包内实际为准,部署配置只需要关注 multi-deploy-postgres.sh 和 cfg/docker/postgres.hosts 两个文件):

multi-deploy-postgres-17.10-amd64/
├── multi-deploy-postgres.sh   # 部署脚本 + 参数配置(需编辑)
├── cfg/
│   └── docker/
│       └── postgres.hosts     # SSH 连接配置(需编辑)
├── image/                     # PostgreSQL 离线镜像
├── doc/                       # 文档
└── logs/                      # 运行日志

4、配置部署参数

# 部署前先确认无历史安装(两条都应无输出,有输出先卸载/清理)
docker ps -a --format '{{.Names}}' | grep v8-postgres
ls /data/postgres/docker-compose.yaml

# 编辑部署脚本参数
vi multi-deploy-postgres.sh

修改以下参数:

dbPort="5432"        # 数据库访问端口,按需修改
dbPass="Seeyon123."  # postgres 用户密码,改为实际密码,密码要求:不少于 8 位,不能包含空格 双引号 反引号 及其它特殊字符 $  \ : #
enableAdminer=""     # 包内默认是 "1",可改为空-不部署 Adminer 管理界面
enableTLS=""         # TLS 加密,保持为空(不开启)
autoTuneSystem=""    # 系统参数自动调优,默认空(不开启),开启后自动做系统参数调优,如PG数据库独立部署建议开启调优

5、配置 SSH 连接信息

multi-deploy-postgres 离线部署包的运行原理是安装包服务器 → SSH 连接到 PostgreSQL 服务器远程安装。如果您将安装包已经放置在 PostgreSQL 服务器,也需要将当前服务器的 SSH 信息进行配置才能安装。

# 获取本机 IP示例
ip addr | awk '/inet .*global/ {split($2,a,"/"); print a[1]; exit}'

# 编辑 hosts 配置文件
vi cfg/docker/postgres.hosts

修改为真实 IP 和 SSH 连接信息,修改后保存,如下是一个环境配置示例,请自行给参考调整:

postgres-local host=192.168.58.132 port=22 user=root password=Seeyon123.

6、执行安装

在解压目录中执行部署脚本,出现确认提示时输入 y:

bash multi-deploy-postgres.sh i

安装过程会自动完成:Docker 检测与离线安装(缺失时)→ 导入内置镜像 → 生成 /data/postgres/docker-compose.yaml → 创建并启动容器 v8-postgres → 注册 systemd 服务 postgres(开机自启)。

验证安装结果:

# 服务状态
systemctl status postgres
# 预期: active (running)

# 数据库就绪(首次启动初始化约需 10~30 秒)
docker exec v8-postgres pg_isready -U postgres
# 预期输出: accepting connections

# 数据库端口
ss -tlnp | grep :5432

# 部署摘要(如存在)
cat doc/apps-deployment-summary.txt

# Linux免编译日常运维

  1. 启停服务
systemctl start postgres
systemctl stop postgres
systemctl restart postgres
  1. 查看状态
systemctl status postgres
docker ps --filter "name=postgres"
  1. 查看板本
docker exec v8-postgres psql -U postgres -c "select version();"
  1. 查看日志
journalctl -u postgres
docker logs -f --tail 100 v8-postgres
  1. 连接数据库
# 本机进入命令行
docker exec -it v8-postgres psql -U postgres

# 远程连接(替换为服务器 IP)
psql -h <服务器IP> -p 5432 -U postgres -d postgres
  1. 备份数据
# 方式一:逻辑备份(理论可不停机)
docker exec v8-postgres pg_dumpall -U postgres > /data/pg_backup_$(date +%Y%m%d).sql

# 方式二:物理备份(需先停止服务,拷贝整个数据目录 /data/postgres/data)

# Linux免编译卸载步骤

# 停止并注销服务
systemctl disable --now postgres

# 停止并删除容器(保留数据目录)
docker compose -f /data/postgres/docker-compose.yaml down

# 删除服务文件
rm -f /etc/systemd/system/postgres.service && systemctl daemon-reload

# 确认不再需要后,再删除程序和数据(谨慎!不可恢复)
rm -rf /data/postgres

# Linux免编译升级步骤(小版本升级)

  1. 先备份:参考【日常运维 - 备份数据】
  2. 下载新版本总包并上传解压(参考【部署步骤 - 第 1~3 步】)
  3. 导入新版镜像:docker load -i image/postgres-<新版本>-<架构>.tgz(路径以包内实际为准,可 find . -name 'postgres-*.tgz' 定位)
  4. 修改 /data/postgres/docker-compose.yaml 中 image: 为新版本号
  5. 重启生效:systemctl restart postgres
  6. 验证:参考【部署步骤 - 第 6 步】

⚠️ 跨大版本升级(如 16 → 17)数据目录不兼容,必须用 pg_dumpall 导出后,重新部署新版本再导入数据。

# Linux联网安装方案

# Linux联网安装前提要求

Postgresql官网提供了不同的Linux发行版在线安装方法,要求当前Linux系统具备如下条件:

  • 1)操作系统处于联网状态,并且能访问 https://www.postgresql.org
  • 2)安装过程使用root管理员账号
  • 3)在官方标注的Linux发行版型号范围内,后续步骤有查看支持清单的方法(官网未列举的操作系统型号,无法使用本方案,比如国产Anolis龙蜥操作系统)

# Linux联网安装操作步骤

1、访问Postgresql Download地址:https://www.postgresql.org/download/

在官网下载页面,点击Linux面板,会列出Linux不同生态发行版,选择与自己Linux相匹配的生态发行版进入:

注:如果当前Linux操作系统不在支持范围内,则只能用另一种“源码编译”安装部署!

1765335383405.png

2、以Linux下的Red Hat/Rocky/AlmaLinux发行生态为例,进入下载面板后,通过“Select platform”、“Select architecture”、“Select version”下拉选择具体的Linux型号版本、架构和Postgresql的版本,会自动带出在线安装部署命令:

1765335185542.png

1765335292920.png

3、以AlmaLinux 9 + X86 + Postgresql17为例,PG官网会自动生成下载命令,只需要按照命令逐个执行即可完成包安装、初始化、自启动:

# AlmaLinux 9 + X86 + Postgresql17 安装命令

# Install the repository RPM:
# 安装PG仓库源
sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm

# Install PostgreSQL:
# 安装Postgresql
sudo dnf install -y postgresql17-server

# Optionally initialize the database and enable automatic start:
# 初始化数据库和设置数据库自启动
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

注:下载手册最后也提供了下载离线PG仓库源的方法,供这些无法访问外网的Linux环境使用:

1765336984585.png

4、登录PG修改密码:你可以通过 psql 命令行工具访问PostgreSQL。

在前面初始化时,会给系统预置一个postgres的用户用于管理数据库,我们可以切换到 postgres 用户并进入 psql:

sudo -i -u postgres
psql

# postgres默认没有密码,在psql模式下,通过如下命令设置密码:
\password postgres

5、(按需)创建用户和数据库:在 psql 中,你可以创建用户和数据库。

例如,创建一个名为 seeyondb 的用户(密码通用户名)和一个名为 seeyondatabase 的数据库:

-- 在psql模式下创建帐号和库
CREATE USER seeyondb WITH PASSWORD 'seeyondb';
-- 在psql模式下新建一个数据库,管理权限交给seeyondb
CREATE DATABASE seeyondatabase OWNER seeyondb;

6、退出psql:完成后,可以输入 \q 退出 psql。

7、调优PostgreSQL:编辑/var/lib/pgsql/data/postgresql.conf,调整数据库的最大连接和缓存数量:

-- max_connections最大连接数的值,生产环境建议配置500,后续根据实际情况做调整:
max_connections=500

-- shared_buffers的值:缓存模块,可以加速SQL响应效率,建议此值设置为2G以上,生产环境一般推荐占用当前系统内存的15%~20%,配置如下:
shared_buffers=2048M

-- listen_addresses设置监听的网卡IP,默认localhost,设置*表示当前服务器所有网卡
listen_addresses = '*'

参数修改后,通过sudo systemctl restart postgresql设置生效。

8、配置PostgreSQL:编辑/var/lib/pgsql/data/pg_hba.conf文件来设置身份验证方法:

# 第一种:增加一行host配置,192.168.xx.xx这个网段的设备可以通过用户名密码访问
host    all             all             192.168.0.0/24               md5
# 第二种:也可以把IP设置为0.0.0.0/0,表示任意外部IP访问,这种方式仅适合开发环境,生产环境不要随意暴露连接
host    all             all             0.0.0.0/0               md5

参数修改后,通过sudo systemctl restart postgresql设置生效。

9、配置防火墙,允许PG数据库端口可被外部访问:

sudo firewall-cmd --add-port=5432/tcp --permanent
sudo firewall-cmd --reload

10、以上完成后,我们可以通过客户端远程连接PG数据库了:

1730636881532.png

如果客户端通过数据库工具连接不通(比如Navicat),可根据工具提示将必要的IP加入到pg_hba中,如下图所示表示192.168.188.1需要加入配置中:

1730636803619.png

# Linux源码编译安装

# Linux源码编译适用场景

Linux源码编译理论适用全部Linux操作系统,官方主要建议为:如果客户的操作系统产品和版本不在downloads列表范围内(Other Linux),则推荐统一使用build from source(源码编译)形式部署PG。源码包可以提前下载,对无法连接外网的Linux系统也能使用。

1765347178870.png

# Linux源码编译部署步骤

1、 源码下载地址:https://www.postgresql.org/ftp/source/

从官网源码下载地址下载对应版本的源码包, 推荐按照 Postgresql版本维护策略和选型 章节选择在维护期的PG版本安装, 如果Linux系统内核版本较低,建议选择早期的PG版本,避免编译安装报错。

这里以Postgresql V17.5为例,提供部署方法:

mkdir -p /data
cd /data

# Linux在线下载后缀名为.tar.gz的源码包(也可以提前下载并上传到Linux)
wget https://ftp.postgresql.org/pub/source/v17.5/postgresql-17.5.tar.gz
# Linux在线下载后缀名为.tar.gz.md5的源码包md5值文件(也可以提前下载并上传到Linux)
wget https://ftp.postgresql.org/pub/source/v17.5/postgresql-17.5.tar.gz.md5

# 对比源码包md5值是否与postgresql-17.5.tar.gz.md5记录的一致
# 查看源码包md5值
md5sum postgresql-17.5.tar.gz
# 查看文件记录值
cat postgresql-17.5.tar.gz.md5

2、安装编译工具及依赖,不同体系操作系统使用不同命令

Ubuntu、Debian

apt update
apt install -y build-essential
apt install -y libreadline-dev zlib1g-dev libssl-dev libicu-dev pkg-config bison flex m4

CentOS、RHEL

yum install -y gcc gcc-c++ make
yum install -y readline-devel zlib-devel openssl-devel libicu-devel pkgconfig bison flex m4

Fedora

dnf install -y gcc gcc-c++ make
dnf install -y readline-devel zlib-devel openssl-devel libicu-devel pkgconfig bison flex m4

3、编译&安装

# 解压
tar -zvxf postgresql-17.5.tar.gz

# 配置编译环境
cd postgresql-17.5
# /usr/local/postgresql-17.5表示PG编译后最终程序存放位置
./configure --prefix=/usr/local/postgresql-17.5

# 编译源码
make

# 安装
make install

# 创建软链接
ln -s /usr/local/postgresql-17.5 /usr/local/postgresql

4、初始化

# 创建PG数据库维护用户
useradd -m postgres

# 创建数据目录 注:如果此步报错“没有那个文件或目录”,则可能是前面ln -s创建软链接操作失败:软链接源目录不存在导致,需要解除软链接重新绑定
mkdir /usr/local/postgresql/data

# 修改PG用户目录权限
chown -R postgres:postgres /usr/local/postgresql/

# 初始化数据库 -D 后面对应数据目录
sudo -u postgres /usr/local/postgresql/bin/initdb -D /usr/local/postgresql/data

5、配置调整

# 修改监听地址(默认监听127.0.0.1,修改为服务器所有网卡的所有 IPv4/IPv6 监听,以便PG能被外部连接)
vim /usr/local/postgresql/data/postgresql.conf
listen_addresses = '*'

# 允许外部客户端通过tcp端口连接
vim /usr/local/postgresql/data/pg_hba.conf

# 第一种:增加一行host配置,192.168.xx.xx这个网段的设备可以通过用户名密码访问
host    all             all             192.168.0.0/24               scram-sha-256
# 第二种:也可以把IP设置为0.0.0.0/0,表示任意外部IP访问,这种方式仅适合开发环境,生产环境不要随意暴露连接
host    all             all             0.0.0.0/0               scram-sha-256

1766107319568.png

6、启停

# 启动数据库
sudo -u postgres /usr/local/postgresql/bin/pg_ctl -D /usr/local/postgresql/data -l /usr/local/postgresql/pg-server.log start

# 停止数据库
sudo -u postgres /usr/local/postgresql/bin/pg_ctl -D /usr/local/postgresql/data -l /usr/local/postgresql/pg-server.log stop

7、设置postgres的密码

# 在PG服务器执行命令进入数据库psql下
sudo -u postgres /usr/local/postgresql/bin/psql

# postgres默认没有密码,在psql模式下,通过如下命令设置密码
\password postgres

8、退出psql模式,配置防火墙,允许PG数据库端口可被外部访问:

sudo firewall-cmd --add-port=5432/tcp --permanent
sudo firewall-cmd --reload

客户端输入修改的密码进行测试连接:

1766107305059.png

9、参数优化

vim /usr/local/postgresql/data/postgresql.conf

# 内存相关设置
shared_buffers: 设置为服务器内存的 25% 左右,生产环境至少2G,如2048MB,用于缓存数据块以减少磁盘 I/O。
work_mem: 配置为每个连接的需求,通常设置为 16-64MB,适用于排序和哈希操作。
maintenance_work_mem: 在执行数据库维护任务(如 VACUUM、CREATE INDEX)时使用,可以更高。
effective_cache_size: 合理设置这个值,反映数据库使用的操作系统缓存大小。

# 并发相关设置
max_connections: 根据用户访问量合理设置,生产环境推荐500,避免过多并发连接导致性能下降。
wal_writer_delay: 在需要提升写性能时,可以减少 WAL 写的延迟。

# I/O和日志相关设置
wal_level: 基于系统复制需要进行选择,minimal 可以提供更快的写入性能。
checkpoint_segments 和 checkpoint_completion_target: 增加这些参数以减少 checkpoint 加载对系统的影响。

10、使用systemctl命令进行pg启停管理(命令仅供参考,如有问题需要自行研究调整)

# 如pg已经手动启动,使用命令主动停止
sudo -u postgres /usr/local/postgresql/bin/pg_ctl -D /usr/local/postgresql/data -l /usr/local/postgresql/pg-server.log stop

# 增加postgresql.service配置
vim /etc/systemd/system/postgresql.service
# postgresql.service配置内容如下
[Unit]
Description=PostgreSQL Database Server
After=network.target

[Service]
Type=forking
User=postgres
Group=postgres
ExecStart=/usr/local/postgresql/bin/pg_ctl -D /usr/local/postgresql/data -l /usr/local/postgresql/pg-server.log start
ExecStop=/usr/local/postgresql/bin/pg_ctl -D /usr/local/postgresql/data -l /usr/local/postgresql/pg-server.log stop
ExecReload=/usr/local/postgresql/bin/pg_ctl -D /usr/local/postgresql/data reload
Restart=on-failure
RestartSec=3s

[Install]
WantedBy=multi-user.target
# postgresql.service配置完成后,重新加载systemctl
systemctl daemon-reload
# 启动pg
systemctl start postgresql.service
# 查看pg状态
systemctl status postgresql.service
# 设置开机自启
systemctl enable postgresql.service

# Windows 环境安装部署方案

第一种:访问官方下载地址,下载安装PG: https://www.postgresql.org/download/

1750916037227.png

1750916044355.png

1750916050053.png

第二种:二进制包下载地址,下载免安装PG:https://www.enterprisedb.com/download-postgresql-binaries

1750916134144.png

1750916164664.png

编撰人:admin