Docker 安装带 pgvector 的 PostgreSQL 14 新手教程

摘要

本文使用 pgvector 项目提供的 Docker 镜像，在 Docker Desktop 或 Docker Engine 中运行 PostgreSQL 14，并完成数据持久化、扩展启用、向量查询和重启验证。内容优先采用 pgvector 官方仓库、Docker Hub 和 Docker 官方文档中的做法，适合第一次接触 PostgreSQL 向量检索的读者。

一、先说结论

本教程使用的镜像是：

pgvector/pgvector:pg14

它是 pgvector 项目提供的 PostgreSQL 14 镜像标签。镜像中已经包含 vector 扩展文件，但扩展仍然需要在具体数据库中执行：

CREATE EXTENSION IF NOT EXISTS vector;

数据使用 Docker 命名卷挂载到容器内的 PostgreSQL 数据目录：

/var/lib/postgresql/data

命名卷可以让数据独立于容器保存，但它不是备份。重要数据仍然需要使用 pg_dump 等方式备份。

二、pgvector 是什么

pgvector 是 PostgreSQL 的向量相似度搜索扩展，可以保存向量，并使用欧氏距离、余弦距离或内积进行相似度查询。它适合语义搜索、RAG 知识库和推荐等功能，但不会自动生成向量，embedding 仍然需要由外部模型生成。

需要区分两个概念：

• 镜像中包含扩展文件，不等于每个数据库都已经启用扩展。
• vector(3) 中的 3 是向量维度，必须和实际模型输出维度一致。

三、前置准备

开始前确认：

1. 已安装 Docker Desktop 或 Docker Engine。
2. Docker 服务已经启动。
3. 当前用户可以执行 docker 命令。
4. 主机的 5432 端口没有被其他 PostgreSQL 服务占用。
5. 如果机器上已有 PostgreSQL 容器或重要数据库，先备份，不要直接复用下面的容器名和数据卷名。

检查 Docker：

docker version
docker info

如果 docker info 无法连接 daemon，先启动 Docker Desktop。

四、拉取镜像

docker pull pgvector/pgvector:pg14

pg14 表示 PostgreSQL 14 系列。镜像的 pgvector 小版本会随项目更新变化，实际版本使用 SQL 查询，不要把某次拉取得到的版本当成永久固定值。

检查镜像：

docker image inspect pgvector/pgvector:pg14

五、创建持久化数据卷

docker volume create pgvector_pg14_data
docker volume inspect pgvector_pg14_data

Docker Desktop 下不建议手动猜测或修改卷在宿主机上的实际目录。使用卷名挂载到 /var/lib/postgresql/data，由 Docker 管理存储位置。

六、创建 PostgreSQL 容器

运行前务必把示例密码替换成自己的强密码：

docker run -d --name pgvector-pg14 -p 5432:5432 -e POSTGRES_USER=appuser -e POSTGRES_PASSWORD=ChangeMe_123456 -e POSTGRES_DB=appdb -v pgvector_pg14_data:/var/lib/postgresql/data --restart unless-stopped pgvector/pgvector:pg14

参数说明：

参数	作用
-d	后台运行容器
--name pgvector-pg14	设置容器名称
-p 5432:5432	主机 5432 映射到容器 5432
POSTGRES_USER	首次初始化时创建的数据库用户
POSTGRES_PASSWORD	首次初始化时设置的用户密码
POSTGRES_DB	首次初始化时创建的数据库
-v	把数据库数据保存到命名卷
--restart unless-stopped	Docker 启动后自动恢复，手动停止后不强制拉起

ChangeMe_123456 只是示例值，不能直接用于生产环境。POSTGRES_PASSWORD 只在数据目录第一次初始化时生效；卷已经初始化后，修改环境变量不会自动修改现有密码。

如果 5432 已被占用，可改用主机端口 15432：

docker run -d --name pgvector-pg14 -p 15432:5432 -e POSTGRES_USER=appuser -e POSTGRES_PASSWORD=ChangeMe_123456 -e POSTGRES_DB=appdb -v pgvector_pg14_data:/var/lib/postgresql/data --restart unless-stopped pgvector/pgvector:pg14

客户端此时连接 15432，容器内端口仍是 5432。

七、确认 PostgreSQL 已经就绪

docker ps --filter "name=pgvector-pg14"
docker exec pgvector-pg14 pg_isready -U appuser -d appdb

pg_isready 返回 accepting connections 后，才表示数据库已经可以连接。失败时查看日志：

docker logs --tail 100 pgvector-pg14

八、启用并验证扩展

进入 appdb：

docker exec -it pgvector-pg14 psql -U appuser -d appdb

在 psql 中执行：

CREATE EXTENSION IF NOT EXISTS vector;

SELECT extname, extversion
FROM pg_extension
WHERE extname = 'vector';

返回 vector 和实际版本号，说明扩展已经在当前数据库启用。扩展是按数据库启用的，新建其他数据库后需要再次执行 CREATE EXTENSION。

退出：

\q

九、创建向量表并查询

下面用 3 维向量验证功能，真实项目应根据 embedding 模型输出维度设计字段。

CREATE TABLE vector_items (
    id BIGSERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    embedding VECTOR(3) NOT NULL,
    remark VARCHAR(500),
    delete_status SMALLINT NOT NULL DEFAULT 0 CHECK (delete_status IN (0, 1)),
    create_user_no BIGINT,
    modified_user_no BIGINT,
    create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    modified_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO vector_items (name, embedding)
VALUES
    ('apple', '[1,2,3]'),
    ('banana', '[4,5,6]'),
    ('grape', '[2,3,4]');

SELECT id, name, embedding <-> '[1,2,4]' AS distance
FROM vector_items
WHERE delete_status = 0
ORDER BY embedding <-> '[1,2,4]'
LIMIT 3;

<-> 表示欧氏距离，距离越小通常表示越接近。余弦距离查询：

SELECT id, name, embedding <=> '[1,2,4]' AS cosine_distance
FROM vector_items
WHERE delete_status = 0
ORDER BY embedding <=> '[1,2,4]'
LIMIT 3;

modified_time 在 PostgreSQL 中不会自动更新，业务更新时应显式维护，或另行创建触发器。

十、索引建议

数据量小、查询次数少时，全表扫描可能已经足够。当查询延迟或数据量确实需要优化时，再根据距离类型建立索引。

余弦距离对应 HNSW：

CREATE INDEX vector_items_embedding_hnsw_idx
ON vector_items
USING hnsw (embedding vector_cosine_ops);

欧氏距离使用 vector_l2_ops。IVFFlat 的 lists 需要结合数据量、召回率和延迟调优，不要无条件复制固定值。建立索引后使用 EXPLAIN (ANALYZE, BUFFERS) 评估效果。

十一、客户端连接

默认端口连接信息：

项目	值
主机	127.0.0.1
端口	5432
用户名	appuser
密码	启动容器时设置的密码
数据库	appdb

如果映射的是 15432:5432，客户端端口填写 15432。连接失败时先检查 docker ps、pg_isready 和容器日志，不要先删除数据卷。

十二、重启验证和备份

docker exec pgvector-pg14 psql -U appuser -d appdb -c "SELECT count(*) FROM vector_items;"
docker restart pgvector-pg14
docker exec pgvector-pg14 psql -U appuser -d appdb -c "SELECT count(*) FROM vector_items;"

两次结果一致，说明当前命名卷完成了容器重启场景下的持久化验证。卷不是备份，继续执行逻辑备份：

docker exec pgvector-pg14 pg_dump -U appuser -d appdb > .\pgvector-appdb.sql

恢复：

Get-Content .\pgvector-appdb.sql | docker exec -i pgvector-pg14 psql -U appuser -d appdb

十三、常见问题

1. 端口 5432 已被占用

docker ps --format "table {{.Names}}\t{{.Ports}}"

停止冲突服务，或者改用 15432:5432。

2. CREATE EXTENSION vector 报不存在

确认镜像是 pgvector/pgvector:pg14，而不是普通 postgres:14，然后检查镜像和日志：

docker image inspect pgvector/pgvector:pg14
docker logs --tail 100 pgvector-pg14

3. 修改密码没有生效

已有数据卷应进入数据库执行：

ALTER ROLE appuser WITH PASSWORD '替换成新的强密码';

4. 删除容器后数据是否还在

只要没有删除 pgvector_pg14_data，命名卷通常仍然存在：

docker volume inspect pgvector_pg14_data

仍然建议使用 pg_dump 做独立备份。

十四、卸载方式

确认不再需要容器和数据后再执行：

docker rm -f pgvector-pg14
docker volume rm pgvector_pg14_data
docker image rm pgvector/pgvector:pg14

删除命名卷会永久删除数据库数据。只想删除容器而保留数据时，不要删除命名卷。

十五、官方资料

• pgvector 官方 GitHub 仓库
• pgvector Docker Hub 镜像标签
• Docker 官方 Volumes 文档
• PostgreSQL 14 CREATE EXTENSION 文档

总结

本教程完成了镜像拉取、命名卷持久化、容器启动、数据库就绪检查、扩展启用、向量查询、重启验证和逻辑备份。命令链路已经使用临时容器验证过；镜像小版本、扩展版本、端口和密码仍应以读者实际环境为准。