06 · 安装 pgvector（Docker 与本地）

一句话：最快的方式是用官方 Docker 镜像 pgvector/pgvector，一条命令就有一个自带 pgvector 的 PostgreSQL。

1. 三种安装方式怎么选

方式	适合谁	难度
Docker 镜像（推荐）	想快速学习/开发	⭐ 最简单
包管理器安装	已有本地/服务器 PG	⭐⭐
源码编译	特殊系统、要最新版	⭐⭐⭐

初学强烈建议用 Docker，几分钟搞定，且不污染本机环境。

---

2. 方式一：Docker（推荐）

2.1 启动一个带 pgvector 的 PostgreSQL

官方镜像 pgvector/pgvector 已经把扩展装好了，标签里带 PG 版本，例如 pg17 表示 PostgreSQL 17。

docker run --name pgvector-demo `
  -e POSTGRES_PASSWORD=postgres `
  -e POSTGRES_DB=vectordb `
  -p 5432:5432 `
  -d pgvector/pgvector:pg17

上面是 PowerShell 写法（用反引号 换行）。如果你在 Linux/Mac 的 bash，把 换成 \ 即可。

参数说明：

• --name pgvector-demo：容器名，方便后续操作。
• -e POSTGRES_PASSWORD=postgres：数据库密码（必填）。
• -e POSTGRES_DB=vectordb：启动时自动建一个名为 vectordb 的库。
• -p 5432:5432：把容器 5432 端口映射到本机。
• -d：后台运行。

2.2 确认容器起来了

docker ps

看到 pgvector-demo 且状态是 Up 就成功了。

2.3 进入容器里的 psql 命令行

docker exec -it pgvector-demo psql -U postgres -d vectordb

进入后提示符会变成 vectordb=#，说明已连上数据库。

想退出 psql，输入 \q 回车。

2.4 数据持久化（可选但建议）

上面的容器删掉后数据就没了。想保留数据，挂一个数据卷：

docker run --name pgvector-demo `
  -e POSTGRES_PASSWORD=postgres `
  -e POSTGRES_DB=vectordb `
  -p 5432:5432 `
  -v pgvector_data:/var/lib/postgresql/data `
  -d pgvector/pgvector:pg17

-v pgvector_data:/var/lib/postgresql/data 会把数据存到名为 pgvector_data 的 Docker 卷里，容器重建也不丢。

2.5 用 docker-compose（更省心）

新建 docker-compose.yml：

services:
  db:
    image: pgvector/pgvector:pg17
    container_name: pgvector-demo
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: vectordb
    ports:
      - "5432:5432"
    volumes:
      - pgvector_data:/var/lib/postgresql/data

volumes:
  pgvector_data:

启动 / 停止：

docker compose up -d      # 启动
docker compose down       # 停止（数据卷保留）

---

3. 方式二：给已有的 PostgreSQL 装 pgvector

如果你已经有本地 PG，只需装扩展文件。

Debian / Ubuntu

sudo apt install postgresql-17-pgvector

17 换成你的 PG 大版本号。

macOS（Homebrew）

brew install pgvector

Windows

Windows 上原生装 pgvector 较麻烦，强烈建议直接用上面的 Docker 方式。

---

4. 方式三：源码编译（需要最新版时）

git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

前提：本机已安装 PG 的开发头文件（如 postgresql-server-dev-17）。

---

5. 常见问题

Q：docker run 报端口 5432 被占用？
本机已有 PG 占用了 5432。把映射改成别的端口，比如 -p 5433:5432，之后连接用 5433。

Q：忘了密码怎么连？
密码就是启动时 POSTGRES_PASSWORD 设的值（示例里是 postgres）。

Q：怎么用图形工具连（DBeaver / Navicat）？

• Host：localhost
• Port：5432
• Database：vectordb
• User：postgres
• Password：postgres

---

6. 一句话总结

学习首选 Docker：docker run ... pgvector/pgvector:pg17，几分钟得到一个自带向量能力的 PostgreSQL。

---

➡️ 下一章：07-CREATE-EXTENSION与验证.md，启用扩展并确认它真的能用。