Bitnami PostgreSQL 16 镜像安装 pgvector 完整排障与 Docker 实践

我最近在一个知识库项目里搭 PostgreSQL 16 环境，本来以为照着网上那套“docker run 一个 postgres:16，然后进容器 git clone pgvector、make install”就能收工，结果拉的是 Bitnami 镜像，一句话把我晾在那里：

bash复制ERROR:  could not open extension control file "/opt/bitnami/postgresql/share/extension/vector.control": No such file or directory

后面查了一圈才发现，不是我的编译命令不对，而是 Bitnami 镜像和官方 postgres 镜像的目录结构、运行用户、配置方式根本就是两套逻辑。网上 90% 的 pgvector 教程都默认基于官方镜像，直接套到 Bitnami 上自然四处碰壁。

这篇文章就相当于一份完整的排障记录加可复现教程：我会先讲清楚 Bitnami 镜像为什么特殊，然后给一个能直接用的 Dockerfile，再把 docker compose 编排、首次启动自动创建扩展、SQL 验证、以及我实际踩过的几个坑一次说透。如果你正在用 Bitnami 的 PostgreSQL 镜像跑 RAG、向量检索、或者准备把 pgvector 接到自己的应用里，这篇应该能帮你省下不少时间。

1. Bitnami 镜像与官方 postgres 镜像：先从目录结构差异说起

1.1 为什么我会选择 Bitnami 镜像

先说结论：Bitnami 镜像和官方 postgres 镜像都是“能用的 PostgreSQL”，但设计哲学完全不同。

官方 postgres 镜像走的是极简路线，默认基于 Debian，所有 PostgreSQL 相关文件都装在系统标准路径下，比如 /usr/lib/postgresql/16、/usr/share/postgresql/16/extension。它的优点是透明、直接、社区资料多；缺点是环境变量、初始化逻辑相对简单，在 Kubernetes 这类平台里要自己写不少胶水逻辑。

Bitnami 镜像则是“为容器编排而生”。它把 PostgreSQL 完整安装在自己的独立目录树里，提供了一整套更细粒度的环境变量体系，比如 POSTGRESQL_USERNAME、POSTGRESQL_PASSWORD、POSTGRESQL_DATABASE、POSTGRESQL_REPLICATION_MODE 等等；数据目录固定在 /bitnami/postgresql；默认以 uid 1001 运行而不是 root。这套机制让 Bitnami 镜像在 Helm Chart、Kubernetes、OpenShift 以及很多 PaaS 平台里非常流行，很多公司的内部中间件平台预置的就是 Bitnami 的 PostgreSQL Chart。

但这种“完整封装”的代价，就是你不能拿官方镜像的教程来直接套。用 Bitnami 镜像时，系统里可能根本没有 /usr/lib/postgresql/16/bin/pg_config，而是藏在 /opt/bitnami/postgresql/bin/pg_config。pgvector 的编译过程依赖 pg_config 去定位头文件和扩展安装目录，一旦路径不对，后续每一步都会显得莫名其妙。

1.2 先看懂 Bitnami 的文件布局：扩展安装到哪里

在动手之前，我强烈建议你先花两分钟进容器里看一眼实际文件布局，否则后面出了问题很难定位。

以 bitnami/postgresql:16 为例，关键目录和文件大致是这样：

• /opt/bitnami/postgresql/bin/：包含 psql、postgres、pg_config、pg_ctl 等所有可执行文件；
• /opt/bitnami/postgresql/share/：包含 PostgreSQL 的扩展控制文件、SQL 脚本等，比如后续会出现的 extension/vector.control；
• /opt/bitnami/postgresql/lib/：存放 PostgreSQL 的动态库，比如 pgvector 编译出来的 vector.so；
• /bitnami/postgresql/：数据卷挂载点，实际数据在 /bitnami/postgresql/data；
• /opt/bitnami/postgresql/conf/：配置文件模板目录，Bitnami 会在容器启动时把模板和用户覆盖配置合并到一起。

你可以用一条命令进容器验证：

bash复制docker run -it --rm --entrypoint bash bitnami/postgresql:16 \
  -c "ls /opt/bitnami/postgresql/bin/pg_config && /opt/bitnami/postgresql/bin/pg_config --sharedir"

正常情况下输出会是 /opt/bitnami/postgresql/share。这里的 sharedir 就是 PostgreSQL 安装扩展控制文件的位置。pgvector 编译后要做的就是两件事：把 vector.so 放到 lib 目录，把 vector.control 和 vector--0.7.4.sql 这类文件放到 share/extension 目录。只要 pg_config 路径对了，这两个位置就不用你手动关心，make install 会自动完成。

1.3 一张表对比：官方镜像和 Bitnami 镜像的关键差异

我整理了一个对比表，方便你在排查问题的时候快速对照：

看出问题了吗？如果你拿官方镜像的 make install 教程来跑，系统默认会去找 /usr/lib/postgresql/16/bin/pg_config，在 Bitnami 镜像里根本没有这个文件。就算你把源码下载好、编译器装好，最后也会失败在“找不到 PostgreSQL 头文件”或“找不到 sharedir”上。所以这类教程的第一步不是让你改什么参数，而是让你接受一个事实：你得先适配 Bitnami 自己的文件布局。

2. 编译前的环境确认：先匹配版本，再谈安装

2.1 PostgreSQL 16 和 pgvector 版本怎么选

pgvector 对 PostgreSQL 版本是有要求的。虽然大部分常用版本支持得不错，但我不建议你在生产环境里无脑拉最新代码编译。最好的方式是明确固定两个版本：PostgreSQL 主版本 16，pgvector 使用某个已经验证过的稳定 tag。

我这次使用的是 bitnami/postgresql:16 对应的 PostgreSQL 16.x，以及 pgvector 的 v0.7.4 tag。写 Dockerfile 的时候，我建议把 pgvector 版本做成一个可替换的变量，比如后续出了 v0.8.0，你只需要改一行，而不需要重写整个构建逻辑。

版本匹配的大致要求如下：

还有个容易被忽略的点：pgvector 的 make install 本质上编译的是“针对某个 PostgreSQL 主版本的二进制扩展”，所以一旦 PostgreSQL 从 16 升到 17，扩展也必须重新编译。这也是为什么我强烈不推荐“把插件直接装在容器层里，然后随手升级镜像 tag”的做法，版本漂移会让你踩到 ABL 兼容的坑。

2.2 拉取镜像后先做三件事

正式写 Dockerfile 之前，分三步确认一下环境：

第一，拉取镜像：

bash复制docker pull bitnami/postgresql:16

第二，确认镜像内部的 PostgreSQL 版本：

bash复制docker run -it --rm --entrypoint bash bitnami/postgresql:16 \
  -c "/opt/bitnami/postgresql/bin/postgres --version"

第三，确认 pg_config 路径存在：

bash复制docker run -it --rm --entrypoint bash bitnami/postgresql:16 \
  -c "ls -l /opt/bitnami/postgresql/bin/pg_config"

这三步看起来简单，但能帮你省掉许多“编译成功但装不上”的谜之问题。尤其第三步，如果 pg_config 不在预期位置，你后面做的所有编译都白搭。

2.3 准备项目结构

建议专门建一个目录，把构建相关文件放一起，方便以后用 docker compose 一把梭：

bash复制mkdir -p pgvector-pg16-demo/init
cd pgvector-pg16-demo

目录结构大概是这样的：

• Dockerfile：基于 bitnami 镜像、编译 pgvector；
• docker-compose.yml：编排容器、端口、环境变量和数据卷；
• init/001-create-extensions.sql：第一次启动时自动建扩展。

把基础设施作为代码管理起来，比“先进容器手动装一版、再 commit 成镜像”要可靠得多。后面我会讲为什么。

3. 用 Dockerfile 定制镜像：把 pgvector 编译进 PostgreSQL

3.1 可以直接复制的 Dockerfile

这是我在实际项目里验证过的 Dockerfile，核心思路就是“继承 Bitnami 基础镜像，安装编译依赖，编译 pgvector，最后清理临时文件并切回非 root 用户”：

dockerfile复制FROM bitnami/postgresql:16

USER root

RUN install_packages build-essential git make gcc \
    && git clone --branch v0.7.4 --depth 1 \
       https://github.com/pgvector/pgvector.git /tmp/pgvector \
    && cd /tmp/pgvector \
    && make PG_CONFIG=/opt/bitnami/postgresql/bin/pg_config \
    && make install PG_CONFIG=/opt/bitnami/postgresql/bin/pg_config \
    && rm -rf /tmp/pgvector

USER 1001

如果你的基础镜像 tag 已经指定为 bitnami/postgresql:16.4.0-debian-12-r7 这种带小版本的标签，那我建议你在 FROM 里写完整 tag，避免未来某天 16 指向新的小版本后，构建产物和运行产物产生偏差。

构建和验证命令：

bash复制docker build -t pgvector-pg16-demo .

构建完成后，可以快速看一下镜像里是否已经出现扩展文件：

bash复制docker run -it --rm --entrypoint bash pgvector-pg16-demo \
  -c "ls -l /opt/bitnami/postgresql/share/extension/vector.control"

如果能看到 vector.control，说明扩展已经成功编译并安装到了正确位置。

3.2 每一行命令在做什么

我逐段解释一下这个 Dockerfile，因为很多人看到 make install 就照抄，却不清楚每一步解决了什么问题：

首先是 USER root。Bitnami 镜像默认是以 uid 1001 运行，但安装系统级编译依赖、往 /opt/bitnami/postgresql/lib 写文件都需要 root 权限，所以要先切到 root。如果你跳过这一步直接编译，很容易碰到 Permission denied。

然后是 install_packages build-essential git make gcc。Bitnami 镜像提供了一个叫 install_packages 的包管理包装脚本，它会根据底层操作系统自动调用 apt、yum 或 dnf。这里不直接用 apt-get 是因为 Bitnami 官方镜像有的版本基于 Debian，有的基于 UBI，写死 apt-get 会降低复用性。

接下来是核心编译：

bash复制git clone --branch v0.7.4 --depth 1 \
  https://github.com/pgvector/pgvector.git /tmp/pgvector
cd /tmp/pgvector
make PG_CONFIG=/opt/bitnami/postgresql/bin/pg_config
make install PG_CONFIG=/opt/bitnami/postgresql/bin/pg_config

重点在 PG_CONFIG 参数。默认情况下 make 会去系统 PATH 里找 pg_config，但 Bitnami 镜像的 PATH 里并没有 /opt/bitnami/postgresql/bin。所以必须通过 PG_CONFIG 明确告诉编译系统：PostgreSQL 的头文件和扩展安装目录在哪里。这一步是我踩过最多次的坑，也是最容易让新手怀疑人生的地方。

最后是 rm -rf /tmp/pgvector，清理 git clone 出来的源码目录。这能明显减少镜像体积，也避免把源码带到运行时镜像里。

最后一行 USER 1001 同样重要。Bitnami 的入口脚本和编排平台都默认容器以非 root 运行，切回 1001 既能保持安全，也能避免某些 Kubernetes 安全策略拒绝以 root 启动的容器。

3.3 编译失败的高频原因

我见过的编译失败，九成都是下面这几类问题：

第一类是“找不到 pg_config”。报错一般长这样：

bash复制/bin/sh: pg_config: command not found

这说明 make 没有在 PATH 中找到 pg_config。解决办法就是加上 PG_CONFIG=/opt/bitnami/postgresql/bin/pg_config，不要依赖镜像默认 PATH。

第二类是“找不到 postgres.h”。出现这个说明 pg_config 虽然存在，但指向了一个错误的 PostgreSQL 安装，或者版本不匹配。你可以在进入容器后执行：

bash复制/opt/bitnami/postgresql/bin/pg_config --includedir-server

确认返回的目录里确实存在 postgres.h。如果这个命令指向了系统自带的另一个 PostgreSQL，那你需要重新确认是否真的用了 Bitnami 的 pg_config。

第三类是“权限不足”。通常发生在进入容器手动编译时，因为没有切到 root，make install 无法写入 /opt/bitnami/postgresql/lib。解决方式有两种，要么在 Dockerfile 里用 USER root 构建，要么进入容器后执行 docker exec -u root 再操作。

4. 用 docker compose 把 PG16 + pgvector 跑起来

4.1 compose 文件怎么设计

构建好镜像之后，不建议直接用一长串 docker run 命令去启动，环境变量和挂载点一多容易乱。我用 docker compose 管理，文件如下：

yaml复制services:
  pg:
    build:
      context: .
      dockerfile: Dockerfile
    image: pgvector-pg16-demo:latest
    container_name: pgvector-pg16
    environment:
      POSTGRESQL_USERNAME: appuser
      POSTGRESQL_PASSWORD: apppass
      POSTGRESQL_DATABASE: appdb
      POSTGRESQL_POSTGRES_PASSWORD: postgrespass
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/bitnami/postgresql
      - ./init:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD", "/opt/bitnami/postgresql/bin/pg_isready", "-U", "appuser", "-q"]
      interval: 5s
      timeout: 5s
      retries: 20

volumes:
  pgdata:

这里有几个 Bitnami 特有的点要特别提醒。

数据卷挂载路径必须是 /bitnami/postgresql，不是官方镜像的 /var/lib/postgresql/data。如果你把宿主目录挂到 /var/lib/postgresql/data，Bitnami 的初始化脚本根本不会往那里写数据，最后容器可能反复重启，或者你连上了数据库却发现数据不在预期位置。

环境变量建议用 POSTGRESQL_ 前缀。Bitnami 兼容部分 POSTGRES_ 前缀，但为了减少混乱，我统一用 POSTGRESQL_。POSTGRESQL_USERNAME 和 POSTGRESQL_PASSWORD 用来创建一个普通业务用户；POSTGRESQL_DATABASE 指定默认数据库；POSTGRESQL_POSTGRES_PASSWORD 设置超级用户 postgres 的密码。如果不设置超级用户密码，Bitnami 可能会随机生成或者只允许本地连接，外部工具连不上时会很困惑。

4.2 初始化脚本：第一次启动自动建扩展

在 init/001-create-extensions.sql 里写入：

sql复制CREATE EXTENSION IF NOT EXISTS vector;

这个目录的作用和官方镜像类似：当数据卷为空、数据库首次初始化时，容器会按文件名顺序执行目录下的 .sql、.sh 脚本。因此第一次 docker compose up 后，pgvector 扩展会自动创建，不需要你事后手动连进数据库再敲一次 CREATE EXTENSION。

不过要格外注意：如果数据卷已经初始化过，这个 SQL 脚本不会再次执行。也就是说你如果先启动了一个没有挂载 init 脚本的数据库，创建好了数据，再补上 init 脚本重启容器，扩展不会自动出现，因为数据库已经被初始化过了。解决办法是删掉旧卷重建，或者手动执行 CREATE EXTENSION。

重置环境时可以执行：

bash复制docker compose down -v

这会连命名卷一起删除，下次启动会重新初始化数据库。

4.3 启动验证和 psql 连接注意点

启动命令：

bash复制docker compose up -d --build

等待健康检查通过后，可以这样验证版本并尝试连接：

bash复制docker compose exec pg \
  /opt/bitnami/postgresql/bin/psql \
  -U appuser -d appdb \
  -c "SELECT version();"

Bitnami 镜像默认不以 root 运行，容器里通常也没有 psql 在系统 PATH 下，所以要用全路径 /opt/bitnami/postgresql/bin/psql。如果你已经通过 docker compose exec 进入容器，也可以直接在 bash 里执行全路径命令。

还有一个很实用的小技巧：如果你发现 psql -U appuser 报“无法创建锁文件”或 socket 权限错误，不要和它硬刚，直接加 -h 127.0.0.1 走 TCP 连接，能绕开一大部分容器内 Unix socket 目录的权限问题：

bash复制docker compose exec pg \
  /opt/bitnami/postgresql/bin/psql \
  -h 127.0.0.1 -U appuser -d appdb

5. 开工后的验证：vector 扩展到底能不能用

5.1 三步确认扩展已注册

启动完成后，第一步确认 pgvector 是否已注册到当前数据库中：

sql复制SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE name = 'vector';

如果 installed_version 是空的，说明扩展还没创建，执行：

sql复制CREATE EXTENSION IF NOT EXISTS vector;

创建后再看一眼版本：

sql复制SELECT extversion FROM pg_extension WHERE extname = 'vector';

如果能看到类似 0.7.4 的输出，说明扩展已经能用。

这里有个关于 shared_preload_libraries 的常见误区需要说一下。pgvector 不像 pg_stat_statements 那样必须预加载到 shared_preload_libraries。它只是一个普通扩展，创建扩展后会加载对应的 vector.so，所以不用去修改 PostgreSQL 的共享库预加载配置。很多人以为所有插件都要改 shared_preload_libraries，结果在 Bitnami 镜像里找半天配置文件，其实完全不需要。

5.2 用真实 SQL 测一遍余弦相似度

确认扩展存在以后，我建议用一个小案例跑一遍相似度检索，确保函数和操作符都正常工作。

先建一张测试表：

sql复制CREATE TABLE documents (
    id bigserial PRIMARY KEY,
    content text NOT NULL,
    embedding vector(3)
);

插入几条示例数据，这里的 vector(3) 表示每个文本对应一个 3 维向量。实际 RAG 应用里，向量维度可能是 768、1536 甚至更高，但原理一样：

sql复制INSERT INTO documents (content, embedding) VALUES
('苹果是一种水果', '[1,1,1]'),
('数据库用来存数据', '[2,0,1]'),
('向量检索适合做相似度搜索', '[1,0,1]');

然后模拟一个查询向量，比如查询和“水果”最相近的文本：

sql复制SELECT id, content,
       embedding <=> '[1,1,1]' AS cosine_distance
FROM documents
ORDER BY cosine_distance ASC;

这里 <=> 是余弦距离操作符，距离越小表示越相似。输出会先显示“苹果是一种水果”，距离为 0；其他记录的 distance 会大于 0，这就说明 pgvector 的运算链路已经通了。

实际应用中常见操作符还有：

• <-> 表示 L2 欧氏距离；
• <#> 表示负内积；
• <=> 表示余弦距离。

选哪个取决于你的 embedding 模型和检索需求。如果是 OpenAI 的 text-embedding-ada-002 这类已经归一化的向量，用余弦距离或内积结果差不多；如果是自定义 embedding，最好先做归一化，再统一距离口径。

5.3 加 HNSW 索引时我的建议

小数据量下顺序扫描没问题，但一旦向量数据量到了十万、百万级别，不加索引的查询会慢到让人崩溃。pgvector 提供了两类索引：IVFFlat 和 HNSW。

我目前比较推荐 HNSW，因为它不需要像 IVFFlat 那样先准备足够的数据来训练中心点，召回率也更稳定。建索引的 SQL 如下：

sql复制CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

如果你主要用 L2 距离，可以改成：

sql复制CREATE INDEX ON documents USING hnsw (embedding vector_l2_ops);

这里 vector_cosine_ops 和 vector_l2_ops 是操作符类，必须和查询时使用的距离函数匹配，否则索引不会生效。

我个人的习惯是：先把应用逻辑跑通，确认查询结果正确，再回过头来建索引。因为索引构建会消耗内存和 CPU，也会稍微拖慢插入速度。在开发环境里先验证业务，再把性能优化加上，思路会更清晰。

6. Bitnami 下的踩坑记录与应对

6.1 容器内直接 make install，一重建就丢

这是 Bitnami 镜像下最容易踩的坑，也是最值得拿出来单独讲的。

很多人看到网上的教程会说：“你先 docker run 一个容器，然后 docker exec 进去，apt-get install 依赖，git clone pgvector，make install，create extension”。这个方法在官方镜像下能用，在 Bitnami 镜像下也能“临时”成功。但问题在于：你做的这些修改都在容器可写层里，而不是镜像层里。

一旦你执行了：

bash复制docker compose down
docker compose up -d

或者更干脆地删除容器重建，新建容器会从原始镜像启动，你在容器里装的 pgvector 文件全部丢失。数据库数据可能还在，因为数据卷是独立的，但扩展文件不在了，于是你又会看到熟悉的 could not open extension control file。

要避免这个坑，唯一正确的做法就是像第 3 节那样，把编译过程写进 Dockerfile，构建成自定义镜像。容器实例可以随意删除重建，但镜像里的 pgvector 不会丢。

如果你只是临时测试，不想写 Dockerfile，也可以手动执行安装后立刻用 docker commit 把容器保存成镜像。但我不推荐这种做法，因为它没办法让团队成员复现，也没办法纳入版本管理，只能算“一次性补救”。

6.2 psql 连接时报 lock 文件权限不够

还有一个出现频率很高的报错：

bash复制psql: error: could not create lock file "/var/run/postgresql/.s.pgsql.5432.lock": Permission denied

这个和 PostgreSQL 本身通常没有关系，而是 psql 在尝试创建 Unix socket 锁文件时，发现目标目录不可写。Bitnami 容器内默认运行用户是 1001，而 /var/run/postgresql 这个目录要么不存在，要么不属于当前用户，psql 自然写不进去。

解决办法有三种，按推荐程度排序：

第一种，连接时指定 TCP 地址，走 127.0.0.1，不在本地走 Unix socket：

bash复制/opt/bitnami/postgresql/bin/psql -h 127.0.0.1 -U appuser -d appdb

第二种，查看 PostgreSQL 当前实际的 Unix socket 目录，很多 Bitnami 配置会把它放在 /opt/bitnami/postgresql/tmp 或者 /bitnami/postgresql/tmp：

sql复制SHOW unix_socket_directories;

然后用 -h 指向该目录：

bash复制/opt/bitnami/postgresql/bin/psql -h /opt/bitnami/postgresql/tmp -U appuser -d appdb

第三种，如果非要修改默认 socket 目录，可以在 Bitnami 的环境变量里增加额外配置，但我觉得没必要，直接用 TCP 或者指定路径更省事。

6.3 镜像拉取慢和容器无法启动的两个周边问题

说两个和 Bitnami 镜像搭配使用时几乎绕不开的周边问题。

第一，镜像拉取很慢。如果你在拉取 bitnami/postgresql:16 时速度很不理想，可以在 Docker daemon 的配置里加上 registry mirror。以 Docker Desktop 为例，在 Settings -> Docker Engine 中编辑 JSON，增加 registry-mirrors 数组，然后重启 Docker daemon。注意不要照抄网上不可靠的地址，要根据你所在网络环境选择可用的镜像加速服务。改了之后再用 docker pull bitnami/postgresql:16 测试，通常会有明显改善。

第二，Windows 上 Docker Desktop 启动失败，报 “virtualization support wasn’t detected” 之类的问题。这通常是因为 BIOS 里的虚拟化功能没开启，或者 WSL 2 没有正确启用。你需要去 BIOS 打开 Intel VT-x 或 AMD-V，然后再安装或更新 WSL 2。Docker Desktop 在 Windows 下严重依赖 Hyper-V/WSL2 这部分底座，底座不工作，镜像拉不下来、容器启动失败都属于连锁反应。

这些问题的详细解法每种都能写一整篇，但在 pgvector 安装这个主线上，它们只属于“环境劫”。你只需要尽早确认 Docker 本身能正常创建容器，再开始编译 pgvector，否则容器都没起来谈安装插件没有意义。

最后再分享一条我自己的经验

如果你正在搭建知识库项目，必然要频繁调整数据库环境。我的建议是把构建 pgvector 镜像这件事完全代码化：一个 Dockerfile、一个 docker-compose.yml、一个 init SQL 脚本，放进 Git 仓库。以后不管换电脑、换服务器、还是同事要复现，只需要 docker compose up -d --build，十分钟内就能获得一个带 pgvector 的 PostgreSQL 16 环境。

我自己吃过多少次“容器里手动装好了，数据库也跑通了，一删容器全没了”的亏，所以现在凡是涉及扩展类组件，一律先在镜像阶段解决。pgvector 这种“编译型扩展”尤其如此，它不像纯 SQL 扩展那样可以在线安装，它要编译、要拷动态库、要管理版本，一旦脱离镜像层，就很容易变成“薛定谔的插件”：当前容器里有，换个容器就没有了。

希望这篇基于 Bitnami 镜像的实战记录能帮到你。如果你在实操中遇到其他奇怪报错，先别急着怀疑 pgvector，回去看一眼 pg_config 路径、数据卷挂载点和运行用户，大概率问题就出在这三件事里。