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

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 是向量维度必须和实际模型输出维度一致。三、前置准备开始前确认已安装 Docker Desktop 或 Docker Engine。Docker 服务已经启动。当前用户可以执行 docker 命令。主机的 5432 端口没有被其他 PostgreSQL 服务占用。如果机器上已有 PostgreSQL 容器或重要数据库先备份不要直接复用下面的容器名和数据卷名。检查 Dockerdocker version docker info如果 docker info 无法连接 daemon先启动 Docker Desktop。四、拉取镜像docker pull pgvector/pgvector:pg14pg14 表示 PostgreSQL 14 系列。镜像的 pgvector 小版本会随项目更新变化实际版本使用 SQL 查询不要把某次拉取得到的版本当成永久固定值。检查镜像docker image inspect pgvector/pgvector:pg14五、创建持久化数据卷docker volume create pgvector_pg14_data docker volume inspect pgvector_pg14_dataDocker Desktop 下不建议手动猜测或修改卷在宿主机上的实际目录。使用卷名挂载到 /var/lib/postgresql/data由 Docker 管理存储位置。六、创建 PostgreSQL 容器运行前务必把示例密码替换成自己的强密码docker run -d --name pgvector-pg14 -p 5432:5432 -e POSTGRES_USERappuser -e POSTGRES_PASSWORDChangeMe_123456 -e POSTGRES_DBappdb -v pgvector_pg14_data:/var/lib/postgresql/data --restart unless-stopped pgvector/pgvector:pg14参数说明参数作用-d后台运行容器--name pgvector-pg14设置容器名称-p 5432:5432主机 5432 映射到容器 5432POSTGRES_USER首次初始化时创建的数据库用户POSTGRES_PASSWORD首次初始化时设置的用户密码POSTGRES_DB首次初始化时创建的数据库-v把数据库数据保存到命名卷--restart unless-stoppedDocker 启动后自动恢复手动停止后不强制拉起ChangeMe_123456 只是示例值不能直接用于生产环境。POSTGRES_PASSWORD 只在数据目录第一次初始化时生效卷已经初始化后修改环境变量不会自动修改现有密码。如果 5432 已被占用可改用主机端口 15432docker run -d --name pgvector-pg14 -p 15432:5432 -e POSTGRES_USERappuser -e POSTGRES_PASSWORDChangeMe_123456 -e POSTGRES_DBappdb -v pgvector_pg14_data:/var/lib/postgresql/data --restart unless-stopped pgvector/pgvector:pg14客户端此时连接 15432容器内端口仍是 5432。七、确认 PostgreSQL 已经就绪docker ps --filter namepgvector-pg14 docker exec pgvector-pg14 pg_isready -U appuser -d appdbpg_isready 返回 accepting connections 后才表示数据库已经可以连接。失败时查看日志docker logs --tail 100 pgvector-pg14八、启用并验证扩展进入 appdbdocker 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 中不会自动更新业务更新时应显式维护或另行创建触发器。十、索引建议数据量小、查询次数少时全表扫描可能已经足够。当查询延迟或数据量确实需要优化时再根据距离类型建立索引。余弦距离对应 HNSWCREATE 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-pg143. 修改密码没有生效已有数据卷应进入数据库执行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 文档总结本教程完成了镜像拉取、命名卷持久化、容器启动、数据库就绪检查、扩展启用、向量查询、重启验证和逻辑备份。命令链路已经使用临时容器验证过镜像小版本、扩展版本、端口和密码仍应以读者实际环境为准。