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 容器或重要数据库，先备份，不要直接复用下面的容器名和数据卷名。
检查 Docker：
docker 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_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 appdbpg_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-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 文档
总结
本教程完成了镜像拉取、命名卷持久化、容器启动、数据库就绪检查、扩展启用、向量查询、重启验证和逻辑备份。命令链路已经使用临时容器验证过；镜像小版本、扩展版本、端口和密码仍应以读者实际环境为准。
