# 【超详细】Docker 部署 PostgreSQL + PGVector 向量数据库

> 适合人群：
>
> * 第一次用 Docker
> * 第一次接触 PostgreSQL
> * 想做 AI 向量检索 / RAG / embedding 存储
> * 国内无法直连 Docker Hub

---

## 一、我们要做什么？

目标只有三件事：

1. 用 **Docker** 跑一个 PostgreSQL
2. 给 PostgreSQL 安装 **PGVector 向量扩展**
3. 能 **存 1536 维向量并做相似度搜索**

最终你会得到一个：

* ✅ 数据不会丢
* ✅ 支持向量检索
* ✅ 可直接接 AI embedding
* ✅ 可生产使用的 PostgreSQL

---

## 二、基础概念（小白必看）

### 1️⃣ 什么是 Docker？

Docker ≈ 一个「软件集装箱」

* 不污染系统
* 不用手动装 PostgreSQL
* 删了容器不影响系统

---

### 2️⃣ 什么是 PGVector？

PGVector 是 PostgreSQL 的一个扩展：

* 提供 `vector` 数据类型
* 支持 **欧氏距离 / 余弦相似度**
* 非常适合 AI embedding

例如：

embedding vector(1536)

---

## 三、准备工作

### 1️⃣ 确认 Docker 已安装

docker version

能看到版本信息即可。

---

### 2️⃣ 创建数据目录（非常重要）

> **不做这一步 = 删容器数据全没**

mkdir -p /home/mrrobot/postgres_data

---

## 四、方案说明（推荐）

我们采用 **自定义镜像** 的方式：

* 基础镜像：PostgreSQL 16
* 在镜像内 **编译安装 PGVector**
* 一次构建，永久可用

---

## 五、完整 Dockerfile（核心）

> **新建文件：`Dockerfile`**

FROM postgres:16

# 安装编译依赖
RUN apt-get update && apt-get install -y \
    git \
    build-essential \
    postgresql-server-dev-16 \
    && rm -rf /var/lib/apt/lists/*

# 编译安装 pgvector
RUN git clone https://github.com/pgvector/pgvector.git /pgvector && \
    cd /pgvector && \
    make && \
    make install && \
    rm -rf /pgvector

---

## 六、构建 PGVector 镜像

docker build -t postgres:16-pgvector .

成功后查看：

docker images | grep pgvector

---

## 七、启动 PostgreSQL（数据持久化）

docker run -d \
  --name postgres-pgvector \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=mypassword \
  -p 5432:5432 \
  -v /home/mrrobot/postgres_data:/var/lib/postgresql/data \
  postgres:16-pgvector

解释（小白版）：

| 参数 | 含义 |
| ------------------- | ----- |
| `-d` | 后台运行 |
| `-p 5432:5432` | 映射端口 |
| `-v` | 数据不丢 |
| `POSTGRES_PASSWORD` | 数据库密码 |

---

## 八、进入 PostgreSQL

docker exec -it postgres-pgvector psql -U postgres

看到：

postgres=#

说明你已经进数据库了 🎉

---

## 九、启用 PGVector 扩展（关键步骤）

⚠️ **很多人卡在这一步**

CREATE EXTENSION IF NOT EXISTS vector;

检查是否成功：

\dx

你应该能看到：

vector | 1.x.x | ...

---

## 十、创建向量表（1536 维）

CREATE TABLE items (
    id serial PRIMARY KEY,
    embedding vector(1536)
);

---

## 十一、SQL 测试脚本（直接可用）

### ✅ 插入随机 1536 维向量（强烈推荐）

INSERT INTO items (embedding)
VALUES (
  ARRAY(
    SELECT random()
    FROM generate_series(1,1536)
  )::vector
);

插入 10 条：

INSERT INTO items (embedding)
SELECT ARRAY(
  SELECT random()
  FROM generate_series(1,1536)
)::vector
FROM generate_series(1,10);

---

### ✅ 查询数据

SELECT id FROM items;

---

## 十二、向量相似度搜索（重点）

### 1️⃣ 欧氏距离（L2）

SELECT id,
       embedding <-> (
         ARRAY(
           SELECT random()
           FROM generate_series(1,1536)
         )::vector
       ) AS distance
FROM items
ORDER BY distance
LIMIT 5;

### 2️⃣ 余弦相似度（推荐）

SELECT id,
       embedding <#> (
         ARRAY(
           SELECT random()
           FROM generate_series(1,1536)
         )::vector
       ) AS score
FROM items
ORDER BY score
LIMIT 5;

---

## 十三、常见错误汇总（必看）

### ❌ 错误 1：`type "vector" does not exist`

原因：
➡️ 忘了执行

CREATE EXTENSION vector;

---

### ❌ 错误 2：`expected 1536 dimensions`

原因：
➡️ 向量长度不匹配

解决：

* 表是 `vector(1536)`
* 插入必须 **1536 个数**

---

### ❌ 错误 3：端口 5432 被占用

sudo lsof -i :5432

解决方案：

* 停掉本机 PostgreSQL
* 或换端口：`-p 15432:5432`

---

## 十四、适合哪些场景？

* ✅ AI 向量检索（RAG）
* ✅ 文本 / 图片 embedding
* ✅ 推荐系统
* ✅ 私有化部署
* ✅ 不想上 Milvus / FAISS

---

## 十五、总结一句话

> **PGVector + PostgreSQL = 最简单、最稳定的向量数据库方案**

* Docker 保证环境干净
* PGVector 性能够用
* SQL 学习成本极低
* 生产可用

---

如果你愿意，下一步我可以帮你写：

* 🔥 **Python + psycopg 连接 PGVector**
* 🔥 **和 OpenAI / DeepSeek embedding 对接**
* 🔥 **RAG 架构实战**

你只要说一句：**「继续」**