Ubuntu24.04 PostgreSQL 18 完整安装与配置教程

本教程基于一次在 Ubuntu 24.04.4 LTS (noble) 上的真实安装全过程整理，所有命令均经过实际验证。安装完成后 PostgreSQL 18.4 在线运行，并已开启远程访问、设置 postgres 超级用户密码、安装 pgvector 向量扩展。

安装方式：PGDG 官方源（非 Ubuntu 默认仓库，可获得最新稳定版与扩展）

一、环境前置条件

项	要求 / 说明
操作系统	Ubuntu 22.04 / 24.04（本文实测 24.04.4 LTS，codename `noble`）
权限	root 或具备 sudo 的用户
网络	能访问 `https://apt.postgresql.org`（PGDG 仓库）
端口	TCP 5432 默认端口未被占用
依赖	`apt`、`ca-certificates`、`postgresql-common`

检查环境：

bash 复制代码

# 确认系统版本与 codename
cat /etc/os-release | grep -E 'PRETTY_NAME|VERSION_CODENAME'
lsb_release -cs                       # 输出例如 noble

# 确认端口 5432 未被占用
ss -ltnp | grep ':5432' || echo "5432 free"

# 确认未安装旧的 postgres
dpkg -l | grep -iE '^ii.*postgres' || echo "no postgres packages"

二、安装 PostgreSQL 18（PGDG 源）

1. 安装前置包并加入 PGDG 源

bash 复制代码

# 1) 安装 postgresql-common 与 ca-certificates
apt install -y postgresql-common ca-certificates

# 2) 加入 apt.postgresql.org 官方仓库（脚本会自动写入 sources.list.d/pgdg.sources 与 GPG keyring）
/usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y

脚本执行成功后会在 /etc/apt/sources.list.d/ 下生成 pgdg.sources，并将 GPG 密钥写入 /usr/share/postgresql-common/pgdg/apt.postgresql.org.gpg。发行版代号会自动识别为 <codename>-pgdg（如 noble-pgdg）。

2. 安装核心包

bash 复制代码

apt update && apt -y dist-upgrade
apt install -y postgresql-18 postgresql-client-18 postgresql-18-pgvector

包名	作用
`postgresql-18`	服务端主程序（含 initdb 集群自动创建）
`postgresql-client-18`	`psql` 等客户端工具
`postgresql-18-pgvector`	pgvector 向量类型与索引扩展（AI/向量检索场景必备）

安装过程中会自动创建默认集群 18/main：数据目录 /var/lib/postgresql/18/main，日志 /var/log/postgresql/postgresql-18-main.log，端口 5432，并注册 systemd 服务 postgresql.service。

3. 确认安装结果

bash 复制代码

psql --version                          # psql (PostgreSQL) 18.4 (...)
pg_lsclusters                          # 18 main 5432 online ...
systemctl is-active postgresql         # active

三、设置 postgres 超级用户密码

Debian/Ubuntu 的 PostgreSQL 默认 postgres 用户无密码、仅允许本地 peer 登录。为支持远程密码认证，必须设置密码。

本例密码设为 lihaozhe。生产环境请使用高强度密码，本文仅为演示。

bash 复制代码

# 以 postgres 系统用户身份执行（peer 认证，免密）
sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'lihaozhe';"

验证密码已写入：

bash 复制代码

sudo -u postgres psql -c "SELECT rolname, rolpassword IS NOT NULL AS has_password FROM pg_authid WHERE rolname='postgres';"

测试 TCP 密码登录（默认 pg_hba.conf 中 127.0.0.1/::1 已是 scram-sha-256）：

bash 复制代码

PGPASSWORD='lihaozhe' psql -h 127.0.0.1 -p 5432 -U postgres -c "SELECT 'password-login-OK' AS result;"

四、开启远程访问

远程访问需要修改两处配置文件，再放行防火墙，最后重启服务。

1. 修改 `listen_addresses` ------ 让服务器监听所有网卡

编辑 /etc/postgresql/18/main/postgresql.conf：

bash 复制代码

# 将
#listen_addresses = 'localhost'
# 改为
listen_addresses = '*'

或一行命令完成：

bash 复制代码

sed -i "s/^#listen_addresses = 'localhost'/listen_addresses = '*'/" /etc/postgresql/18/main/postgresql.conf

说明：listen_addresses 控制监听哪些网卡 IP，'*' 表示全部。该参数需重启服务生效。

2. 修改 `pg_hba.conf` ------ 允许远程客户端用密码连接

编辑 /etc/postgresql/18/main/pg_hba.conf，在文件末尾追加远程访问规则：

bash 复制代码

cat >> /etc/postgresql/18/main/pg_hba.conf <<'EOF'

# === Remote access (added for remote login) ===
host    all             all             0.0.0.0/0               scram-sha-256
host    all             all             ::/0                    scram-sha-256
EOF

字段	含义
`host`	TCP 连接（非本地 socket）
`all / all`	允许所有数据库与所有用户
`0.0.0.0/0` / `::/0`	允许任意 IPv4 / IPv6 来源
`scram-sha-256`	强制 SCRAM-SHA-256 密码认证（PG18 默认加密方式）

安全建议 ：生产环境不要用 0.0.0.0/0，应替换为受限网段，例如 192.168.1.0/24。如需仅允许特定用户/数据库，可拆分多行精确授权。

3. 放行防火墙 5432 端口

bash 复制代码

# 若使用 ufw
ufw allow 5432/tcp
ufw status

# 若使用 firewalld
# firewall-cmd --permanent --add-port=5432/tcp
# firewall-cmd --reload

# 云服务器还需在控制台安全组放行 5432

4. 重启服务使配置生效

bash 复制代码

systemctl restart postgresql
pg_lsclusters
ss -ltnp | grep ':5432'          # 应看到 0.0.0.0:5432 与 [::]:5432

五、远程连接验证

从另一台机器或本机使用公网/内网 IP 测试：

bash 复制代码

# 假设服务器 IP 为 10.2.0.3
PGPASSWORD='lihaozhe' psql -h 10.2.0.3 -p 5432 -U postgres -c "SELECT 'remote-login-OK' AS chk, inet_server_addr() AS server;"

预期输出包含 remote-login-OK 及服务器实际监听 IP，即远程访问成功。

Windows 客户端 可用 pgAdmin、DBeaver、Navicat 等，连接参数：

Host: 服务器 IP
Port: 5432
User: postgres
Password: lihaozhe
Database: postgres

六、全面功能验证清单

以下为安装后建议执行的功能自检（本教程实测全部通过）。

6.1 服务与监听

bash 复制代码

systemctl is-active postgresql          # active
pg_lsclusters                            # 18 main 5432 online
psql --version                           # 18.4
ss -ltn | awk '/:5432/{print $4}'        # 0.0.0.0:5432 / [::]:5432

6.2 多种认证方式

bash 复制代码

# 本地 socket（peer 认证）
sudo -u postgres psql -c "SELECT current_user;"

# TCP 密码登录（scram-sha-256）
PGPASSWORD='lihaozhe' psql -h 127.0.0.1 -U postgres -c "SELECT 1;"

# 错误密码必须失败
PGPASSWORD='wrong' psql -h 127.0.0.1 -U postgres -c "SELECT 1;"
# 预期：FATAL: password authentication failed

6.3 关键参数

bash 复制代码

PGPASSWORD='lihaozhe' psql -h 127.0.0.1 -U postgres -c \
  "SHOW max_connections; SHOW shared_buffers; SHOW server_encoding; \
   SHOW TimeZone; SHOW listen_addresses; SHOW port; SHOW password_encryption;"

6.4 DDL / DML / 事务 / 索引

bash 复制代码

export PGPASSWORD='lihaozhe'
PSQL="psql -h 127.0.0.1 -U postgres -v ON_ERROR_STOP=1"

# 建库建用户授权
$PSQL -c "CREATE DATABASE appdb;"
$PSQL -c "CREATE USER appuser WITH PASSWORD 'lihaozhe';"
$PSQL -c "GRANT ALL PRIVILEGES ON DATABASE appdb TO appuser;"

# 建表、增删改查
$PSQL -d appdb <<'SQL'
CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT NOT NULL, age INT, created_at TIMESTAMPTZ DEFAULT now());
INSERT INTO users (name, age) VALUES ('lihaozhe', 30), ('alice', 25), ('bob', 40);
SELECT * FROM users ORDER BY id;
UPDATE users SET age = 31 WHERE name = 'lihaozhe';
DELETE FROM users WHERE name = 'bob';
SELECT count(*) FROM users;
SQL

# 事务回滚
$PSQL -d appdb <<'SQL'
BEGIN;
INSERT INTO users (name, age) VALUES ('temp', 99);
SELECT count(*) AS during_txn FROM users;
ROLLBACK;
SELECT count(*) AS after_rollback FROM users;
SQL

# 索引与执行计划
$PSQL -d appdb -c "CREATE INDEX idx_users_name ON users(name);"
$PSQL -d appdb -c "EXPLAIN (COSTS OFF) SELECT * FROM users WHERE name = 'alice';"

6.5 pgvector 向量扩展

bash 复制代码

export PGPASSWORD='lihaozhe'
PSQL="psql -h 127.0.0.1 -U postgres -v ON_ERROR_STOP=1"

# 检查扩展可用
$PSQL -c "SELECT name, default_version FROM pg_available_extensions WHERE name='vector';"

# 启用并使用
$PSQL -d appdb <<'SQL'
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE items (id SERIAL PRIMARY KEY, embedding vector(3));
INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]'), ('[7,8,9]');

-- L2 距离（越小越相似）
SELECT id, embedding <-> '[1,2,3]' AS l2_dist FROM items ORDER BY embedding <-> '[1,2,3]';

-- 内积
SELECT id, embedding <#> '[1,2,3]' AS inner_prod FROM items ORDER BY embedding <#> '[1,2,3]';

-- 余弦距离
SELECT id, embedding <=> '[1,2,3]' AS cosine FROM items ORDER BY embedding <=> '[1,2,3]';

-- HNSW 索引（近似最近邻 ANN 检索）
CREATE INDEX ON items USING hnsw (embedding vector_l2_ops);
SQL

# 验证 ANN 走索引
$PSQL -d appdb -c "SET enable_seqscan = off; EXPLAIN (COSTS OFF) SELECT id FROM items ORDER BY embedding <-> '[1,2,3]' LIMIT 1;"

预期 EXPLAIN 输出 Index Scan using items_embedding_idx。

6.6 逻辑备份与恢复

bash 复制代码

export PGPASSWORD='lihaozhe'

# 备份（自定义压缩格式）
pg_dump -h 127.0.0.1 -U postgres -d appdb -Fc -f /tmp/appdb.dump

# 恢复到新库
psql -h 127.0.0.1 -U postgres -c "CREATE DATABASE appdb_restore_test;"
pg_restore -h 127.0.0.1 -U postgres -d appdb_restore_test /tmp/appdb.dump
psql -h 127.0.0.1 -U postgres -d appdb_restore_test -c "SELECT count(*) FROM users; SELECT count(*) FROM items;"

# 清理
psql -h 127.0.0.1 -U postgres -c "DROP DATABASE appdb_restore_test;"
rm -f /tmp/appdb.dump

6.7 并发连接

bash 复制代码

export PGPASSWORD='lihaozhe'
seq 1 10 | xargs -P10 -I{} sh -c \
  "psql -h 127.0.0.1 -U postgres -d appdb -c 'SELECT pg_sleep(0.1);' >/dev/null 2>&1"
echo "10 concurrent connections OK"

验证结果汇总表

#	验证项	状态
1	服务在线（systemd + pg_lsclusters）	✅
2	版本 18.4 + 监听 0.0.0.0:5432 / $::$ :5432	✅
3	本地 socket 登录（peer）	✅
4	TCP 密码登录（scram-sha-256）	✅
5	错误密码拒绝	✅
6	远程 IP 登录	✅
7	建库 / 建用户 / 授权	✅
8	建表 / 插入 / 查询 / 更新 / 删除	✅
9	事务回滚	✅
10	索引 + EXPLAIN	✅
11	pgvector 扩展可用（0.8.5）	✅
12	L2 / 内积 / 余弦距离 + HNSW 索引	✅
13	HNSW 近似 ANN 搜索	✅
14	关键参数（max_conn / shared_buffers / 编码 / 时区 / listen_addresses）	✅
15	日志无错误	✅
16	pg_dump / pg_restore 逻辑备份恢复	✅
17	10 并发连接	✅

七、运维常用操作

7.1 服务管理

bash 复制代码

systemctl start    postgresql
systemctl stop     postgresql
systemctl restart  postgresql
systemctl status   postgresql
systemctl enable   postgresql          # 开机自启

7.2 集群管理

bash 复制代码

pg_lsclusters                          # 查看所有集群
pg_ctlcluster 18 main start|stop|restart|status
pg_dropcluster 18 main --stop          # 删除集群（慎用）
pg_createcluster 18 main --start       # 新建集群

7.3 关键文件路径

文件	路径
postgresql.conf	`/etc/postgresql/18/main/postgresql.conf`
pg_hba.conf	`/etc/postgresql/18/main/pg_hba.conf`
数据目录	`/var/lib/postgresql/18/main`
日志	`/var/log/postgresql/postgresql-18-main.log`
PGDG 源	`/etc/apt/sources.list.d/pgdg.sources`

7.4 性能参数调优（可选）

编辑 postgresql.conf，按内存调整后重启：

conf 复制代码

# 示例（4GB 内存机器）
shared_buffers = 1GB
work_mem = 16MB
maintenance_work_mem = 256MB
effective_cache_size = 3GB
max_connections = 100

7.5 备份策略

bash 复制代码

# 逻辑备份（全库）
pg_dump -h 127.0.0.1 -U postgres -Fc -f /backup/all.dump postgres

# 备份单个库
pg_dump -h 127.0.0.1 -U postgres -Fc -f /backup/appdb.dump appdb

# 备份纯 SQL 文本
pg_dump -h 127.0.0.1 -U postgres -Fp -f /backup/appdb.sql appdb

# 物理备份（需 archive_mode + WAL 归档）
# 配合 pg_basebackup 实现 PITR，适合生产

八、安全加固建议（生产环境）

改用强密码 ：ALTER USER postgres PASSWORD '<强密码>';
限制来源 IP ：pg_hba.conf 中将 0.0.0.0/0 替换为业务网段，如 192.168.1.0/24
最小权限 ：业务用独立用户，仅授予所需库的权限，不要用 postgres 跑应用

按库/用户精细授权 ：

bash 复制代码

host appdb appuser 192.168.1.0/24 scram-sha-256

SSL 加密传输 ：在 postgresql.conf 启用 ssl = on 并配置证书
关闭非必要远程 ：若无需远程，listen_addresses = 'localhost' 并删除 pg_hba.conf 远程行
防火墙 + 安全组：仅放行可信 IP 到 5432
定期备份 + WAL 归档，并演练恢复
更新补丁 ：apt update && apt upgrade postgresql-18 保持小版本最新

九、卸载方法

bash 复制代码

# 停止服务
systemctl stop postgresql

# 卸载包（保留数据）
apt remove -y postgresql-18 postgresql-client-18 postgresql-18-pgvector postgresql-common

# 彻底清除（含数据目录，谨慎！）
apt purge -y postgresql-18 postgresql-client-18 postgresql-18-pgvector
pg_dropcluster --stop 18 main
rm -rf /var/lib/postgresql/18 /etc/postgresql/18

十、故障排查

现象	排查
`psql: could not connect to server`	`systemctl status postgresql`；查看日志 `/var/log/postgresql/postgresql-18-main.log`
远程连不上	检查 `listen_addresses='*'`、`pg_hba.conf` 远程行、`ufw/安全组`、云服务器安全组
`password authentication failed`	确认密码已 `ALTER USER` 设置；确认 `pg_hba.conf` 用 `scram-sha-256`
`FATAL: no pg_hba.conf entry`	`pg_hba.conf` 未放行该来源 IP/用户/库组合
修改 `listen_addresses` 不生效	该参数需 `systemctl restart postgresql`，reload 无效
改完配置未生效	`pg_hba.conf` 改完可 `pg_ctlcluster 18 main reload`；`postgresql.conf` 部分参数需 restart
端口被占用	`ss -ltnp

查看实时日志：

bash 复制代码

tail -f /var/log/postgresql/postgresql-18-main.log

附录：本次实测环境摘要

复制代码

OS          : Ubuntu 24.04.4 LTS (noble)
PostgreSQL  : 18.4 (18.4-1.pgdg24.04+1)
pgvector    : 0.8.5
监听        : 0.0.0.0:5432 / [::]:5432
listen_addresses : '*'
password_encryption : scram-sha-256
server_encoding    : UTF8
TimeZone           : Asia/Shanghai
max_connections    : 100
shared_buffers    : 128MB
集群       : 18 main (online)
数据目录   : /var/lib/postgresql/18/main

文档生成于 2026-07-26，所有步骤均经实际安装验证通过。

Ubuntu24.04 PostgreSQL 18 完整安装与配置教程