PostgreSQL 16 + pgvector 安装（CentOS 8）

注意：CentOS 8 已于 2021-12-31 停止官方维护，软件源需切换至 vault 镜像。本教程包含修复步骤。

---

环境要求

项目	要求
操作系统	CentOS 8 (x86_64)
内存	≥ 2 GB
磁盘	≥ 10 GB 可用空间
权限	root 或 sudo

---

一、修复 CentOS 8 软件源（EOL 处理）

CentOS 8 官方源已下线，必须先切换至 vault 镜像，否则后续 dnf 命令将报错。

# 备份原有 repo 文件
mkdir -p /etc/yum.repos.d/backup
mv /etc/yum.repos.d/*.repo /etc/yum.repos.d/backup/

# 写入 vault 镜像源
cat > /etc/yum.repos.d/CentOS-Vault.repo << 'EOF'
[BaseOS]
name=CentOS-8 - Base - vault.centos.org
baseurl=https://vault.centos.org/8.5.2111/BaseOS/x86_64/os/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial
enabled=1

[AppStream]
name=CentOS-8 - AppStream - vault.centos.org
baseurl=https://vault.centos.org/8.5.2111/AppStream/x86_64/os/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial
enabled=1

[extras]
name=CentOS-8 - Extras - vault.centos.org
baseurl=https://vault.centos.org/8.5.2111/extras/x86_64/os/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial
enabled=1
EOF

# 清理缓存并验证
dnf clean all
dnf makecache

---

二、安装基础依赖

dnf install -y epel-release
dnf install -y gcc gcc-c++ make git wget curl \
    readline-devel zlib-devel openssl-devel \
    libxml2-devel libxslt-devel

---

三、安装 PostgreSQL 16

3.1 添加 PGDG 官方源

dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm

3.2 禁用系统内置 PostgreSQL 模块（避免冲突）

dnf -qy module disable postgresql

3.3 安装 PostgreSQL 16

dnf install -y postgresql16-server postgresql16 postgresql16-devel postgresql16-contrib

若报错：无法为该任务安装最佳候选，提示缺少 clang-devel >= 19.0、llvm-devel >= 19.0 或 perl(IPC::Run)，原因是 postgresql16-devel-16.13 依赖了 CentOS 8 仓库中不存在的高版本 LLVM。按以下步骤处理：

方案一：rpm —nodeps 强制安装（推荐）

--skip-broken 会整包跳过，因为 PGDG 仓库仅有一个版本且携带这些依赖。 缺失的 clang/llvm/perl 是 PostgreSQL JIT 编译特性的依赖，与 pgvector 编译无关，可安全跳过。

# 下载 RPM 到本地
dnf download postgresql16-devel

# 强制安装，绕过依赖检查
rpm -ivh --nodeps postgresql16-devel-16.13-1PGDG.rhel8.10.x86_64.rpm

# 验证头文件安装成功（看到 server/ 目录即可）
ls /usr/pgsql-16/include/

方案二：修复 EPEL vault 源后安装 perl 依赖（若方案一仍失败）

# CentOS 8 EOL 导致 EPEL 源也失效，添加归档源
cat > /etc/yum.repos.d/epel-vault.repo << 'EOF'
[epel]
name=EPEL 8 - Vault
baseurl=https://dl.fedoraproject.org/pub/archive/epel/8/Everything/x86_64/
enabled=1
gpgcheck=0
EOF

dnf install -y perl-IPC-Run
dnf install -y --nobest postgresql16-devel

3.4 初始化数据库

/usr/pgsql-16/bin/postgresql-16-setup initdb

3.5 启动并设置开机自启

systemctl enable postgresql-16
systemctl start postgresql-16
systemctl status postgresql-16

输出中看到 active (running) 即表示启动成功。

---

四、安装 pgvector

4.1 方式一：PGDG 源安装（推荐）

  dnf install -y pgvector_16

若提示找不到包，使用方式二从源码编译。

4.2 方式二：源码编译安装

# 克隆源码
cd /tmp
git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
cd pgvector

# 编译并安装（指定 pg_config 路径）
make PG_CONFIG=/usr/pgsql-16/bin/pg_config
make install PG_CONFIG=/usr/pgsql-16/bin/pg_config

---

五、配置 PostgreSQL

5.1 确认认证方式（pg_hba.conf）

PostgreSQL 16 初始化后默认已使用 scram-sha-256（比 md5 更安全），本地连接无需修改：

# Unix socket（系统用户 postgres 免密登录）
local   all             all                                     peer
# 本机 TCP 连接（需要密码）
host    all             all             127.0.0.1/32            scram-sha-256
host    all             all             ::1/128                 scram-sha-256

若需允许远程连接，在文件末尾追加一行：

echo "host    all             all             0.0.0.0/0               scram-sha-256" >> /var/lib/pgsql/16/data/pg_hba.conf

5.2 配置监听地址（postgresql.conf，仅远程访问需要）

sed -i "s/#listen_addresses = 'localhost'/listen_addresses = '*'/" /var/lib/pgsql/16/data/postgresql.conf

或手动编辑：

vi /var/lib/pgsql/16/data/postgresql.conf

找到并修改：

listen_addresses = '*'    # 默认为 localhost
port = 5432

5.3 重启服务使配置生效

systemctl restart postgresql-16

5.4 开放防火墙端口（如需远程访问）

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

---

六、初始化数据库用户与扩展

6.1 设置 postgres 用户密码

sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'your_password';"

6.2 创建业务用户与数据库

sudo -u postgres psql << 'EOF'
CREATE USER authine WITH PASSWORD 'Authine@123456';

CREATE DATABASE cloudpivot_launcher OWNER authine;
CREATE DATABASE cloudpivot_user     OWNER authine;
CREATE DATABASE cloudpivot_report   OWNER authine;
CREATE DATABASE cloudpivot_ai       OWNER authine;
CREATE DATABASE cloudpivot_tenant   OWNER authine;

GRANT ALL PRIVILEGES ON DATABASE cloudpivot_launcher TO authine;
GRANT ALL PRIVILEGES ON DATABASE cloudpivot_user     TO authine;
GRANT ALL PRIVILEGES ON DATABASE cloudpivot_report   TO authine;
GRANT ALL PRIVILEGES ON DATABASE cloudpivot_ai       TO authine;
GRANT ALL PRIVILEGES ON DATABASE cloudpivot_tenant   TO authine;
EOF

6.3 启用 pgvector 扩展

仅 cloudpivot_ai 库需要向量能力：

sudo -u postgres psql -d cloudpivot_ai -c "CREATE EXTENSION IF NOT EXISTS vector;"

---

七、验证安装

7.1 验证 PostgreSQL 版本

sudo -u postgres psql -c "SELECT version();"

期望输出包含：PostgreSQL 16.x

7.2 验证 pgvector

sudo -u postgres psql -d appdb << 'EOF'
-- 查看扩展版本
SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';

-- 创建测试表
CREATE TABLE test_vector (id SERIAL PRIMARY KEY, embedding vector(3));

-- 插入测试数据
INSERT INTO test_vector (embedding) VALUES ('[1,2,3]'), ('[4,5,6]'), ('[1,1,1]');

-- 余弦相似度查询（最近邻）
SELECT id, embedding, embedding <=> '[1,2,3]' AS distance
FROM test_vector
ORDER BY distance
LIMIT 3;

-- 清理测试表
DROP TABLE test_vector;
EOF

期望输出：查询返回按距离排序的结果，且 [1,2,3] 自身距离为 0。

7.3 创建向量索引（可选，生产环境推荐）

sudo -u postgres psql -d appdb << 'EOF'
CREATE TABLE documents (
    id     SERIAL PRIMARY KEY,
    content TEXT,
    embedding vector(1536)
);

-- IVFFlat 索引（适合大数据量近似搜索）
CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

-- HNSW 索引（更高精度，pgvector >= 0.5.0）
-- CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);
EOF

---

八、常用管理命令

# 启动 / 停止 / 重启 / 状态
systemctl start postgresql-16
systemctl stop postgresql-16
systemctl restart postgresql-16
systemctl status postgresql-16

# 进入 psql 交互终端
sudo -u postgres psql
sudo -u postgres psql -d appdb

# 查看数据目录
/usr/pgsql-16/bin/pg_config --pgdata

# 查看日志
journalctl -u postgresql-16 -f
tail -f /var/lib/pgsql/16/data/log/postgresql-*.log

---

九、常见问题排查

问题	原因	解决方法
dnf 报 404 错误	CentOS 8 EOL，源已下线	执行第一节修复软件源
initdb 失败	数据目录已存在	rm -rf /var/lib/pgsql/16/data/* 后重试
无法远程连接	监听或防火墙未配置	检查 listen_addresses 和 pg_hba.conf
CREATE EXTENSION vector 失败	pgvector 未安装或路径错误	重新执行第四节，确认 pg_config 路径正确
编译 pgvector 报找不到头文件	缺少 postgresql16-devel	dnf install -y postgresql16-devel
postgresql16-devel 报缺少 clang/llvm >= 19.0	CentOS 8 仓库版本过低	见 3.3 节方案一/方案二