Docker 环境下 PostgreSQL 16 安装 pgvector 向量数据库插件详细教程（Bitnami 镜像）

前言：最近在项目中需要实现向量相似度搜索功能，选择了 pgvector 作为 PostgreSQL 的向量扩展插件。本文记录了在 Docker 容器中（Bitnami PostgreSQL 主从复制镜像）安装 pgvector 的完整过程，包括遇到的坑和解决方案。

---

一、环境说明

组件	版本
操作系统	CentOS 7 / Rocky Linux
Docker	20.x+
PostgreSQL 镜像	postgresql-pgrout-repmgr:16 (Bitnami)
pgvector	v0.8.0

架构说明：本环境使用 Bitnami 的 PostgreSQL + repmgr 实现主从复制架构。

---

二、问题背景

在使用数据库管理工具（如 Navicat、DBeaver）创建数据库时，遇到如下报错：

ERROR: cannot execute CREATE DATABASE in a read-only transaction

2.1 问题分析

这个错误通常意味着：

1. 连接的是 只读从库（replica/standby） 而不是主库
2. 或者会话被设置为只读模式

2.2 排查方法

# 进入容器检查是否为主库
docker exec -it postgresql-repmgr psql -U admin -d postgres -c "SELECT pg_is_in_recovery();"

返回结果说明：

• f (false) → 当前节点是 主库
• t (true) → 当前节点是 从库

也可以通过 repmgr 查看集群状态：

docker exec -it postgresql-repmgr repmgr cluster show

---

三、pgvector 安装步骤

3.1 进入容器

docker exec -it -u root postgresql-repmgr bash

⚠️ 注意：必须使用 -u root 以 root 用户进入，否则没有权限安装软件。

3.2 安装编译依赖

Bitnami 镜像默认没有 PostgreSQL 官方 APT 源，需要手动添加：

# 安装必要工具
apt-get update
apt-get install -y wget gnupg lsb-release

# 添加 PostgreSQL 官方源
echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -

# 更新并安装编译依赖
apt-get update
apt-get install -y git build-essential postgresql-server-dev-16

3.3 下载 pgvector 源码

方法一：容器内直接克隆（需要网络畅通）

cd /tmp
git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
cd pgvector

方法二：宿主机下载后复制进容器（推荐，解决网络问题）

如果容器内无法访问 GitHub，可以在宿主机下载：

# 退出容器
exit

# 在宿主机下载（使用国内镜像加速）
cd /tmp
wget https://ghproxy.cn/https://github.com/pgvector/pgvector/archive/refs/tags/v0.8.0.tar.gz

# 备选镜像（如果上面不可用）
# wget https://hub.gitmirror.com/https://github.com/pgvector/pgvector/archive/refs/tags/v0.8.0.tar.gz
# wget https://gh.api.99988866.xyz/https://github.com/pgvector/pgvector/archive/refs/tags/v0.8.0.tar.gz

# 复制到容器
docker cp /tmp/v0.8.0.tar.gz postgresql-repmgr:/tmp/

# 重新进入容器
docker exec -it -u root postgresql-repmgr bash

# 解压
cd /tmp
tar -xzf v0.8.0.tar.gz
cd pgvector-0.8.0

3.4 编译安装

make
make install

编译成功后会看到类似输出：

/usr/bin/install -c -m 755 vector.so '/opt/bitnami/postgresql/lib/vector.so'
/usr/bin/install -c -m 644 vector.control '/opt/bitnami/postgresql/share/extension/'
/usr/bin/install -c -m 644 sql/vector--*.sql '/opt/bitnami/postgresql/share/extension/'

3.5 退出容器

exit

---

四、启用 pgvector 扩展

💡 重要：安装完成后 不需要重启 PostgreSQL 容器，可以直接使用。

4.1 创建扩展

在需要使用向量功能的数据库中执行：

docker exec -it postgresql-repmgr psql -U admin -d your_database -c "CREATE EXTENSION IF NOT EXISTS vector;"

或者在 Navicat/DBeaver 中执行：

CREATE EXTENSION IF NOT EXISTS vector;

⚠️ 注意：CREATE EXTENSION 需要在 每个 需要使用向量功能的数据库中单独执行一次。

---

五、验证安装

5.1 检查扩展是否可用

-- 查看可用扩展列表中是否有 vector
SELECT * FROM pg_available_extensions WHERE name = 'vector';

-- 查看已安装的扩展
SELECT * FROM pg_extension WHERE extname = 'vector';

-- 查看 pgvector 版本
SELECT extversion FROM pg_extension WHERE extname = 'vector';

5.2 功能测试

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

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

-- 查询数据
SELECT * FROM test_vector;

-- 向量距离计算（L2距离）
SELECT embedding, embedding <-> '[1,1,1]' AS distance 
FROM test_vector 
ORDER BY distance;

-- 测试完成后删除测试表
DROP TABLE test_vector;

如果以上 SQL 都能正常执行，说明 pgvector 安装成功！🎉

---

六、常见问题

Q1: 报错 E: Unable to locate package postgresql-server-dev-16

原因：Bitnami 镜像没有 PostgreSQL 官方 APT 源

解决：按照 3.2 节添加 PostgreSQL 官方源后再安装

Q2: git clone 失败，提示 GnuTLS recv error

原因：容器内网络访问 GitHub 受限

解决：使用方法二，在宿主机通过国内镜像下载后复制进容器

Q3: 报错 cannot execute CREATE DATABASE in a read-only transaction

原因：

1. 连接的是从库而不是主库
2. 客户端连接配置问题

解决：

1. 使用 SELECT pg_is_in_recovery(); 确认连接的是主库
2. 检查连接串是否包含 target_session_attrs=read-only 等参数
3. 检查 SHOW default_transaction_read_only; 的值

Q4: 主从架构下需要在所有节点安装吗？

答：是的，pgvector 扩展文件需要在 所有节点（主库和从库）都安装。但 CREATE EXTENSION 命令只需要在主库执行，会自动同步到从库。

Q5: 容器重启后还需要重新安装吗？

答：

• 容器重启：不需要，扩展文件还在
• 容器删除重建：需要重新安装

建议将安装步骤写入自定义 Dockerfile 或使用 docker-compose 的 entrypoint 脚本。

---

七、pgvector 常用操作速查

7.1 支持的向量操作符

操作符	说明
<->	L2 距离（欧几里得距离）
<#>	负内积
<=>	余弦距离
<+>	L1 距离（曼哈顿距离）

7.2 创建向量索引

-- 创建 IVFFlat 索引（适合大数据量）
CREATE INDEX ON items USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

-- 创建 HNSW 索引（查询更快，但构建较慢）
CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops);

7.3 相似度搜索示例

-- 查找最相似的 5 个向量
SELECT * FROM items 
ORDER BY embedding <=> '[0.1, 0.2, 0.3, ...]' 
LIMIT 5;

---

八、总结

本文详细介绍了在 Docker 环境下的 Bitnami PostgreSQL 16 镜像中安装 pgvector 扩展的完整步骤：

1. ✅ 确认主从节点身份
2. ✅ 添加 PostgreSQL 官方 APT 源
3. ✅ 安装编译依赖
4. ✅ 下载并编译 pgvector
5. ✅ 启用扩展并验证

pgvector 为 PostgreSQL 提供了强大的向量存储和相似度搜索能力，非常适合用于 AI 应用中的 Embedding 存储、RAG（检索增强生成）、推荐系统等场景。

---

参考链接：

• pgvector GitHub
• PostgreSQL 官方文档
• Bitnami PostgreSQL 镜像

---

📝 作者：惊鸿Randy
📅 发布时间：2026年1月29日
🏷️ 标签：PostgreSQL pgvector Docker 向量数据库 AI

如果这篇文章对你有帮助，欢迎 点赞 👍 收藏 ⭐ 关注 🔔