企业官网建设流程全解析

pgvector 向量搜索 Docker 部署避坑指南

【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvector

docker pull pgvector/pgvector:latest回车，终端甩回一句manifest for pgvector/pgvector:latest not found。这不是网络抽风，也不是仓库改名——pgvector 官方镜像根本没有 latest 标签，解法就一条：按你正在用的 Postgres 主版本号，拉pg{版本号}形式的镜像标签。

报错现场：manifest unknown 到底怪谁

那行 CI 日志经常被原样贴到群里：流水线跑到拉镜像阶段就挂，错误永远是manifest unknown这一句。第一反应去查网络、换镜像源的人基本都会白折腾——标签列表里就是没有latest这一项。从官方 postgres 镜像切过来的同事基本都会在这里卡一下：postgres 镜像有 latest，pgvector 这个没有。翻一眼 README 里列出的可用标签，清一色是pg16、pg15、pg14这种带版本号的写法。

定位：标签为什么绑死 Postgres 主版本

pgvector 是编译进数据库的 C 扩展，镜像里的 Dockerfile 直接以postgres:$PG_MAJOR为底、现场编译安装，所以镜像里的扩展文件天然绑死那个版本 Postgres 的内部 API。因为不同主版本的扩展接口对不上，所以跨版本混用镜像，扩展直接加载失败；也因为"latest"对这种绑版本的扩展来说本身就是歧义的——哪个 pg 的 latest？——所以项目干脆不设浮动标签，让你显式选主版本。

标签大致三类写法：主版本标签（pg16）、主版本加基础系统（pg16-bookworm、pg16-trixie）、连扩展版本一起锁死的（0.8.6-pg16），支持的主版本从 pg13 到 pg18。

动手：先确认版本，再拉标签，然后起容器

先确认 Postgres 主版本：本地装好的实例跑psql --version，跑着的库就在库里执行SELECT version();，看一眼大版本号。

再拉镜像，标签后缀就是版本号：

psql --version docker pull pgvector/pgvector:pg16

需要同时锁住扩展版本（生产环境建议）就用0.8.6-pg16这种带扩展版本前缀的标签，数据库和扩展两层版本一次钉死。

然后起容器并挂上数据卷，不然容器一重建数据就没了：

services: postgres: image: pgvector/pgvector:pg16 # 主版本号跟着你的 pg 走 volumes: - pgdata:/var/lib/postgresql/data # 其余字段省略

验证：如果你遇到 X，检查 Y

起来之后跑两条命令：

docker run -d --name pgv -e POSTGRES_PASSWORD=123 pgvector/pgvector:pg16 docker exec pgv psql -U postgres -c "CREATE EXTENSION vector;"

不报错就再试一句SELECT '[1,2,3]'::vector;，能吐出向量值说明整条链路通了。

⚠️ 路上的常见坑，都按条件句排查：

• 如果你拉取时又看到manifest unknown→ 检查标签是不是以pg+ 主版本开头，裸latest不存在。
• 如果你报extension "vector" is not available→ 扩展是库级生效的，在默认库建过不代表业务库可用，每个要用的库都得执行一次CREATE EXTENSION vector;。
• 如果你建 HNSW 索引时并行构建报共享内存错误 → 检查--shm-size是否不小于maintenance_work_mem。
• 如果你不确定扩展有没有装好 → 查pg_extension的extversion，当前镜像内置的是 0.8.6。

回到那行报错

下次再看到那句manifest unknown，不用再翻网络配置：把 Postgres 主版本号补到标签上，镜像就出来了。向量搜索扩展没有浮动标签不是缺陷——生产上要的是可复现的"镜像 + 数据库版本"组合，不是最新。

【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvector