返回笔记首页
最后更新: 2026-06-05v-green

Mac环境 向量数据库 docker 完整环境搭建

主题配置

系统要求：macOS（Intel 或 Apple Silicon 均支持） 已有环境：Node.js、pnpm 需要安装：Docker Desktop

一、安装 Docker Desktop

Docker Desktop 是 macOS 上运行 Docker 容器的官方工具，本项目用它启动 PostgreSQL + pgvector 数据库，不需要在本机手动安装 PostgreSQL。

1.1 下载

访问 https://www.docker.com/products/docker-desktop/，点击"Download for Mac"。

页面会提示选择芯片类型：

  • Mac 搭载 M1 / M2 / M3 / M4 芯片 → 选 Apple Silicon
  • Mac 搭载 Intel 芯片 → 选 Intel Chip

不确定芯片类型：点击左上角苹果图标 → "关于本机"，处理器一栏写 Apple M 开头的是 Apple Silicon，写 Intel 的是 Intel。

1.2 安装

下载完成后双击 .dmg 文件，把 Docker 图标拖到 Applications 文件夹，打开 Docker Desktop，等待顶部菜单栏的鲸鱼图标停止动画，变成静止状态，表示 Docker 已经启动完成。

首次启动会弹出引导窗口，直接关闭即可，不需要登录账号。

1.3 验证安装

打开终端（Terminal）执行：

bash 
docker --version

输出类似 Docker version 27.x.x 表示安装成功。

bash 
docker ps

输出空表格（没有报错）表示 Docker 正在运行。

1.4 Docker 基本概念（结合本项目）

镜像（Image）：类似安装包，pgvector/pgvector:pg16 是一个包含 PostgreSQL 16 和 pgvector 扩展的镜像，第一次使用时会自动从网上下载。

容器（Container）：镜像运行起来后的实例，相当于一个独立运行的数据库服务。本项目创建的容器叫 pgvector-jisu。

端口映射（-p）：把容器内部的端口暴露给宿主机。-p 5432:5432 表示宿主机的 5432 端口对应容器内的 5432 端口，Node.js 通过 localhost:5432 就能连到容器里的 PostgreSQL。

环境变量（-e）：传给容器的配置，相当于设置数据库的用户名、密码、数据库名。

常用命令速查：

bash 
docker ps           # 查看正在运行的容器
docker ps -a        # 查看所有容器（含已停止的）
docker start 容器名  # 启动已有容器
docker stop  容器名  # 停止容器
docker logs  容器名  # 查看容器日志
docker rm    容器名  # 删除容器（数据会丢失）

二、启动 PostgreSQL + pgvector

2.1 创建并启动容器

打开终端，执行以下命令（只需执行一次，以后用 docker start 启动）：

bash 
docker run -d \
  --name pgvector-jisu \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres123 \
  -e POSTGRES_DB=jisu_ai \
  -p 5432:5432 \
  -v pgvector-jisu-data:/var/lib/postgresql/data \
  pgvector/pgvector:pg16

参数说明：

参数 含义
-d 后台运行，不占用终端
--name pgvector-jisu 容器命名，方便后续管理
-e POSTGRES_USER=postgres 数据库用户名
-e POSTGRES_PASSWORD=postgres123 数据库密码（和 .env 保持一致）
-e POSTGRES_DB=jisu_ai 数据库名（和 .env 保持一致）
-p 5432:5432 端口映射，本机 5432 → 容器 5432
-v pgvector-jisu-data:/var/lib/postgresql/data 数据持久化，容器删除后数据不丢失
pgvector/pgvector:pg16 镜像名，pg16 表示 PostgreSQL 16 版本

首次执行会下载镜像，大约 100MB，需要等待 1～2 分钟（取决于网速）。

2.2 验证容器运行状态

bash 
docker ps

看到 pgvector-jisu 行、状态列显示 Up 表示容器正在运行。

2.3 开启 vector 扩展

pgvector 扩展需要手动开启一次：

bash 
docker exec -it pgvector-jisu \
  psql -U postgres -d jisu_ai \
  -c "CREATE EXTENSION IF NOT EXISTS vector;"

输出 CREATE EXTENSION 表示成功。

2.4 验证扩展已开启（可选）

bash 
docker exec -it pgvector-jisu \
  psql -U postgres -d jisu_ai \
  -c "SELECT extname FROM pg_extension WHERE extname = 'vector';"

输出有 vector 行表示扩展已启用。

2.5 日常启停

电脑重启后 Docker Desktop 默认不会自动启动容器，每次需要使用时手动启动：

bash 
# 先确认 Docker Desktop 已启动（菜单栏有鲸鱼图标）

# 启动容器
docker start pgvector-jisu

# 不用了可以停止（节省内存）
docker stop pgvector-jisu

也可以在 Docker Desktop 的 Containers 界面里点击播放按钮启动。

三、配置 API Key

3.1 获取 DeepSeek API Key

  1. 访问 https://platform.deepseek.com
  2. 注册并登录
  3. 左侧菜单点击"API keys"→"创建 API key"
  4. 复制 Key，格式为 sk- 开头的长字符串

3.2 获取智谱 AI API Key（Embedding 用）

  1. 访问 https://open.bigmodel.cn
  2. 注册并登录
  3. 右上角点击头像→"API keys"→"添加新的 API key"
  4. 复制生成的 Key

3.3 写入 .env 文件

进入项目的 server 目录，复制模板并填写：

bash 
cd jisu-ai-customer/server
cp .env.example .env

用任意编辑器打开 server/.env，把两个 Key 填进去：

bash 
# ─── 对话模型（DeepSeek，所有功能必填）────────────────────────────
DEEPSEEK_API_KEY=sk-你的DeepSeekKey
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
MODEL_NAME=deepseek-chat
PORT=3000

# ─── Embedding 模型（RAG 功能必填，二选一）───────────────────────
# 方式一：智谱 AI（推荐）https://open.bigmodel.cn
ZHIPU_API_KEY=你的智谱AIKey

# 方式二：阿里云百炼  https://bailian.console.aliyun.com
# DASHSCOPE_API_KEY=你的百炼APIKey

# ─── PostgreSQL（RAG 功能必填）───────────────────────────────────
PG_HOST=localhost
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=postgres123
PG_DATABASE=jisu_ai

注意事项：

  • Key 前后不能有空格
  • .env 文件不要提交到 Git，已在 .gitignore 中排除
  • PG_PASSWORD 和 PG_DATABASE 必须与第二节创建容器时用的一致

四、安装项目依赖

4.1 后端依赖

bash 
cd jisu-ai-customer/server
pnpm install

安装完成后 node_modules/ 目录出现，共安装约 20 个依赖包。

4.2 前端依赖

bash 
cd jisu-ai-customer/client
pnpm install

五、知识库入库（只需执行一次）

RAG 功能需要提前把知识库文档向量化并存入数据库。这一步只需要执行一次，知识库内容有更新时重新执行。

确认 pgvector 容器已在运行后执行：

bash 
cd jisu-ai-customer/server
pnpm ingest

等价于 node src/scripts/ingest.js。

正常输出：

plain 
开始处理文档...
切分完成，共 12 个片段
入库完成

如果报错，检查：

  • docker ps 确认 pgvector-jisu 容器在运行
  • .env 里 PG_* 配置是否正确
  • .env 里 ZHIPU_API_KEY 是否填写

六、启动项目

需要同时开两个终端窗口。

终端 1：启动后端

bash 
cd jisu-ai-customer/server
pnpm dev

正常输出：

plain 
极速购 AI 客服服务已启动：http://localhost:3000

nodemon 会监听文件变化，修改代码后自动重启，不需要手动重启。

终端 2：启动前端

bash 
cd jisu-ai-customer/client
pnpm dev

正常输出：

plain 
VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5173/

打开浏览器

访问 http://localhost:5173，顶部导航栏有四个入口：

入口 地址 功能
基础对话 http://localhost:5173/ 第一章，流式客服对话
订单查询 http://localhost:5173/agent 第二章，Agent 查询订单和物流
知识库 http://localhost:5173/rag 第三章，RAG 商品和售后问答
智能中枢 http://localhost:5173/graph 第四章，多 Agent 自动路由

七、功能测试用例

基础对话（/）

plain 
你好
如何申请退款？
快递迟迟不到怎么办？

订单查询（/agent）

plain 
帮我查一下订单 ORD-001 的状态
订单 ORD-001 快递到哪里了？
我的用户 ID 是 U-100，有哪些订单？

内置测试数据：

  • ORD-001（已发货，顺丰 SF1234567890，用户 U-100）
  • ORD-002（待付款，用户 U-100）
  • ORD-003（已完成，京东物流，用户 U-101）

知识库问答（/rag）

plain 
蓝牙耳机 X1 Pro 续航多少小时？
商品可以退货吗？退款流程是什么？
机械键盘 K200 有哪些轴体可选？
买了东西有质量问题怎么处理？

智能中枢（/graph）

plain 
订单 ORD-001 发货了吗？       → 自动路由到订单查询
退款需要多少天？               → 自动路由到知识库
蓝牙耳机多少钱？               → 自动路由到知识库
你好，我想了解一下             → 自动路由到通用对话

前端会显示工作流执行路径：意图识别 → 具体模块 → 整理回答。

八、常见问题

docker: command not found

Docker Desktop 没有启动，或者安装不完整。打开 Docker Desktop 应用，等待鲸鱼图标稳定后重试。

Error: connect ECONNREFUSED 127.0.0.1:5432

PostgreSQL 容器没有运行。执行 docker start pgvector-jisu 启动容器。

Error: password authentication failed for user "postgres"

.env 里的 PG_PASSWORD 和创建容器时用的 -e POSTGRES_PASSWORD 不一致。确认两处都是 postgres123。

Error: 401 Unauthorized

DeepSeek API Key 填写有误，或 Key 已过期。检查 server/.env 里的 DEEPSEEK_API_KEY，确认没有多余空格，且 Key 未失效。

知识库问答回答内容不准或说"没有相关信息"

先确认入库成功：

bash 
docker exec -it pgvector-jisu \
  psql -U postgres -d jisu_ai \
  -c "SELECT count(*) FROM knowledge_embeddings;"

输出 count > 0 表示数据已入库。如果为 0，重新执行 pnpm ingest。

ingest 执行报 Embedding API 错误

检查 server/.env 里的 ZHIPU_API_KEY 是否正确填写，以及 server/src/models/embedding.js 里的 baseURL 和 modelName 是否和智谱 AI 匹配。

切换到阿里云百炼 Embedding
  1. 打开 server/src/models/embedding.js，注释掉方式一，取消注释方式二
  2. 在 server/.env 里填写 DASHSCOPE_API_KEY
  3. 清空旧的向量数据并重新入库：
bash 
docker exec -it pgvector-jisu \
  psql -U postgres -d jisu_ai \
  -c "TRUNCATE knowledge_embeddings;"

pnpm ingest

九、项目目录结构

markdown 
jisu-ai-customer/
├── server/                          # Node.js + Express 后端
│   ├── .env.example                 # 环境变量模板（复制为 .env 并填写）
│   ├── .gitignore
│   ├── package.json
│   └── src/
│       ├── index.js                 # 服务入口，注册所有路由
│       ├── models/
│       │   ├── deepseek.js          # DeepSeek 对话模型封装
│       │   └── embedding.js         # Embedding 模型封装（智谱/百炼）
│       ├── prompts/
│       │   └── customer-service.js  # 客服 Prompt 模板
│       ├── chains/
│       │   ├── basic-chat.js        # 基础对话 Chain（第一章）
│       │   └── rag-chain.js         # RAG Chain（第三章）
│       ├── tools/
│       │   └── order-tools.js       # 订单查询工具（第二章）
│       ├── agents/
│       │   └── customer-agent.js    # 订单 Agent（第二章）
│       ├── graphs/                  # LangGraph 工作流（第四章）
│       │   ├── state.js
│       │   ├── customer-graph.js
│       │   └── nodes/
│       │       ├── intent-router.js
│       │       ├── order-agent.js
│       │       ├── rag-node.js
│       │       ├── general-chat.js
│       │       └── answer-synthesizer.js
│       ├── data/
│       │   ├── mock.js              # 模拟订单数据
│       │   └── knowledge/           # 知识库文档
│       │       ├── products.md
│       │       └── policies.md
│       ├── db/
│       │   └── postgres.js          # pg 连接池
│       ├── scripts/
│       │   └── ingest.js            # 知识库入库脚本
│       └── routes/
│           ├── chat.js              # POST /api/chat/stream
│           ├── agent.js             # POST /api/agent/stream
│           ├── rag.js               # POST /api/rag/query
│           └── graph.js             # POST /api/graph/stream
│
└── client/                          # Vue3 前端
    ├── index.html
    ├── vite.config.js
    ├── package.json
    └── src/
        ├── main.js
        ├── App.vue                  # 全局导航栏
        ├── router/
        │   └── index.js             # 四个页面路由
        ├── composables/
        │   ├── useChat.js
        │   ├── useAgent.js
        │   ├── useRag.js
        │   └── useGraph.js
        └── views/
            ├── ChatView.vue
            ├── AgentView.vue
            ├── RagView.vue
            └── GraphView.vue

十、快速启动清单

每次开发时，按以下顺序操作：

bash 
# 1. 启动 Docker Desktop（打开应用，等鲸鱼图标稳定）

# 2. 启动数据库容器
docker start pgvector-jisu

# 3. 终端 1：启动后端
cd jisu-ai-customer/server
pnpm dev

# 4. 终端 2：启动前端
cd jisu-ai-customer/client
pnpm dev

# 5. 浏览器访问
open http://localhost:5173

知识库入库只需要首次运行时执行一次：

bash 
cd jisu-ai-customer/server
pnpm ingest