最后更新: 2026-06-05v-green

Windows 完整环境搭建与运行指南

主题配置

排版主题

代码高亮

系统要求：Windows 10（版本 2004 及以上）或 Windows 11 已有环境：无，从零开始

一、安装 Node.js

1.1 下载

访问 https://nodejs.org，点击左侧"LTS"版本下载（长期支持版，更稳定），下载 .msi 安装包。

1.2 安装

双击安装包，全程点击"Next"，保持默认选项不变，最后点"Install"。安装时会自动把 Node.js 和 npm 加入系统 PATH。

1.3 验证

安装完成后打开命令提示符（Win + R，输入 cmd，回车）：

plain

node --version
npm --version

两行都输出版本号表示安装成功。

二、安装 pnpm

pnpm 是本课程统一使用的包管理器，比 npm 更快，磁盘占用更少。

在命令提示符中执行：

plain

npm install -g pnpm

验证：

plain

pnpm --version

输出版本号表示安装成功。

三、安装 Docker Desktop

Docker Desktop 用于在 Windows 上运行 PostgreSQL + pgvector 数据库容器，不需要手动安装 PostgreSQL。

3.1 开启 WSL 2（前置条件）

Docker Desktop on Windows 依赖 WSL 2（Windows Subsystem for Linux）。以管理员身份打开 PowerShell（右键"开始"菜单 → Windows PowerShell（管理员）），执行：

powershell

wsl --install

这条命令会自动开启所需 Windows 功能并安装 Ubuntu。执行完成后重启电脑。

重启后如果弹出 Ubuntu 终端，按提示设置一个用户名和密码（这是 Linux 子系统的账号，和 Windows 账号无关，随意设置即可）。设置完关闭即可。

验证 WSL 2 已启用：

powershell

wsl --list --verbose

看到 Ubuntu 行、VERSION 列显示 2 表示正常。

3.2 下载 Docker Desktop

访问 https://www.docker.com/products/docker-desktop/，点击"Download for Windows"，下载 Docker Desktop Installer.exe。

3.3 安装

双击安装包，保持默认选项（确保"Use WSL 2 instead of Hyper-V"已勾选），点击"OK"开始安装，完成后重启电脑。

3.4 启动与验证

重启后 Docker Desktop 会自动启动，任务栏右下角出现鲸鱼图标。等鲸鱼图标停止动画变为静止，表示 Docker 已就绪。

打开命令提示符验证：

plain

docker --version
docker ps

两条命令都正常输出（无报错）表示 Docker 安装成功。

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

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

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

端口映射（-p）：-p 5432:5432 把容器内部的 5432 端口映射到本机 5432 端口，Node.js 通过 localhost:5432 连接数据库。

数据卷（-v）：把数据库文件存在宿主机上，容器删除后数据不会丢失。

常用命令速查：

plain

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

四、启动 PostgreSQL + pgvector

4.1 创建并启动容器

打开命令提示符，执行（只需执行一次）：

plain

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

Windows 命令提示符里换行用 ^，PowerShell 里换行用 ```（反引号）。也可以直接写成一行：

plain

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

首次执行会下载镜像，需要等待 1～2 分钟。

参数说明：

参数	含义
`-d`	后台运行
`--name pgvector-jisu`	容器名称
`-e POSTGRES_PASSWORD=postgres123`	数据库密码（与 .env 保持一致）
`-e POSTGRES_DB=jisu_ai`	数据库名（与 .env 保持一致）
`-p 5432:5432`	端口映射
`-v pgvector-jisu-data:...`	数据持久化

4.2 验证容器运行

plain

docker ps

看到 pgvector-jisu、状态显示 Up 表示正常运行。

4.3 开启 vector 扩展

plain

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

输出 CREATE EXTENSION 表示成功。

4.4 日常启停

电脑重启后需要手动启动容器（需先确认 Docker Desktop 已运行）：

plain

docker start pgvector-jisu

不需要时停止：

plain

docker stop pgvector-jisu

也可以在 Docker Desktop 界面的 Containers 列表里直接点击播放/停止按钮操作。

五、配置 API Key

5.1 获取 DeepSeek API Key

访问 https://platform.deepseek.com
注册并登录
左侧菜单点击"API keys" → "创建 API key"
复制 Key（sk- 开头的长字符串）

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

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

5.3 创建 .env 文件

解压项目后，进入 jisu-ai-customer\server 目录，找到 .env.example 文件。

在命令提示符里执行：

plain

cd jisu-ai-customer\server
copy .env.example .env

用记事本或 VS Code 打开 .env 文件，填入 Key：

plain

# ─── 对话模型（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 必须和第四节创建容器时填的一致

用记事本打开 .env 的方法：在文件资源管理器里右键 .env → "打开方式" → 记事本。如果看不到 .env 文件，在资源管理器顶部"查看"里勾选"隐藏的项目"。

六、安装项目依赖

打开命令提示符，进入解压后的项目目录：

6.1 后端依赖

plain

cd jisu-ai-customer\server
pnpm install

6.2 前端依赖

plain

cd ..\client
pnpm install

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

RAG 功能需要先把知识库文档向量化存入数据库，只需执行一次。

确认 pgvector 容器已运行后，在 server 目录执行：

plain

cd jisu-ai-customer\server
pnpm ingest

正常输出：

plain

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

八、启动项目

需要同时打开两个命令提示符窗口。

窗口 1：启动后端

plain

cd jisu-ai-customer\server
pnpm dev

看到以下输出表示后端启动成功：

plain

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

窗口 2：启动前端

plain

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 发货了吗？     → 自动路由到订单查询
退款需要多少天？             → 自动路由到知识库
你好                        → 自动路由到通用对话

十、常见问题

WSL 安装失败或报"请启用虚拟机平台"

以管理员身份打开 PowerShell，执行：

powershell

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

重启后再执行 wsl --install。如果仍然失败，进入 BIOS 确认 Intel VT-x 或 AMD-V 虚拟化功能已开启（不同品牌电脑进 BIOS 方式不同，开机时按 F2 / F12 / Delete 键）。

docker: command not found 或 'docker' 不是内部或外部命令

Docker Desktop 没有启动。任务栏右下角找到鲸鱼图标，如果没有则打开 Docker Desktop 应用，等待其完全启动。

Error: connect ECONNREFUSED 127.0.0.1:5432

PostgreSQL 容器没有运行，执行：

plain

docker start pgvector-jisu

Error: password authentication failed for user "postgres"

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

看不到 .env 文件

Windows 默认隐藏无扩展名文件。打开文件资源管理器，顶部"查看"选项卡，勾选"隐藏的项目"，或者在命令提示符里用 type .env 查看内容。

pnpm install 报 EACCES 权限错误

以管理员身份运行命令提示符（右键"开始" → "命令提示符（管理员）"），再执行 pnpm install。

ingest 执行报 Embedding API 错误

检查 server\.env 里的 ZHIPU_API_KEY 是否填写正确，确认智谱 AI 账号的 Key 状态正常（登录 https://open.bigmodel.cn 查看）。

切换到阿里云百炼 Embedding

打开 server\src\models\embedding.js，注释掉方式一，取消注释方式二
在 server\.env 里填写 DASHSCOPE_API_KEY
清空旧数据并重新入库：

plain

docker exec -it pgvector-jisu psql -U postgres -d jisu_ai -c "TRUNCATE knowledge_embeddings;"
pnpm ingest

端口 5432 被占用

本机已有 PostgreSQL 服务在运行，和 Docker 容器冲突。停掉本机的 PostgreSQL 服务：打开"服务"（Win + R → services.msc），找到 postgresql 相关服务，右键停止。或者在 docker run 时改用其他端口，比如 -p 5433:5432，同时把 .env 里的 PG_PORT 改为 5433。

十一、快速启动清单

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

plain

REM 1. 确认 Docker Desktop 已启动（任务栏有鲸鱼图标）

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

REM 3. 窗口1：启动后端
cd jisu-ai-customer\server
pnpm dev

REM 4. 窗口2：启动前端
cd jisu-ai-customer\client
pnpm dev

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

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

plain

cd jisu-ai-customer\server
pnpm ingest