『MaxKB系列（一）』在Windows下搭建MaxKB开发环境

📣读完这篇文章里你能收获到

1. 📁 了解MaxKB项目的结构，清晰划分前后端代码、配置文件和依赖项，便于快速上手开发。
2. 🐍 安装Python和Poetry，为后端开发搭建稳定环境，确保项目顺利运行。
3. 🌐 配置PostgreSQL数据库，为MaxKB项目提供强大的数据存储支持。
4. 🖥️ 启动前端和后端服务，通过详细步骤和命令，快速启动MaxKB项目并进行调试。

前言

本文将详细介绍如何在Windows系统中完成MaxKB开发环境的搭建，包括前端、后端以及数据库的配置，确保开发者能够顺利启动项目。

一、项目结构概览

MaxKB的项目结构清晰地划分了前后端代码、配置文件和依赖项，便于开发者快速定位和管理。以下是其项目结构的简要说明：

.
├── LICENSE                 # License声明
├── README.md
├── apps                    # 后端项目根目录
│ ├── application           # 应用代码
│ ├── common                # 项目公共资源目录
│ ├── dataset               # 知识库
│ ├── embedding             # 向量化模块
│ ├── function_lib          # 函数库
│ ├── ops                   # 操作相关代码
│ ├── setting               # 设置文件
│ ├── smartdoc              # 项目主目录
│ ├── users                 # 用户相关代码
│ └── manage.py             # Django项目入口
├── installer               # 安装相关脚本
├── pyproject.toml          # 后端依赖配置文件
└── ui                      # 前端项目根目录├── config_example.yml  # 项目配置示例├── main.py             # 项目入口文件

这种结构设计不仅有助于代码的模块化管理，也方便团队协作和后续的维护工作。

二、环境准备

1. 前端环境

1.1 Node.js安装

1. 访问 Node.js 官方网站，下载并安装推荐的LTS版本（v16及以上）。
2. 安装完成后，打开命令提示符（CMD）或PowerShell，运行以下命令验证安装：

node -v
npm -v

如果显示Node.js和npm的版本号，则表示安装成功。

---

2. 后端环境

后端开发基于Python，推荐使用Python版本v3.11.x。

2.1 Python安装

1. 访问 Python 官方网站，下载并安装Python v3.11.x。
2. 在安装过程中，确保勾选“Add Python to PATH”选项，以便在命令行中直接使用Python。
3. 安装完成后，打开命令提示符（CMD）或PowerShell，运行以下命令验证安装：

python --version

如果显示Python的版本号，则表示安装成功。

2.2 Poetry安装

Poetry是一个现代的Python包管理工具，用于依赖管理和项目构建。

1. <font style="color:rgb(6, 6, 7);">打开命令提示符（CMD）或PowerShell，运行以下命令安装Poetry：</font>

pip install poetry

2. <font style="color:rgb(6, 6, 7);">验证Poetry安装是否成功：</font>

poetry --version

---

3. 数据库环境

需要额外安装PGVector向量插件，由于我是在Linux安装的数据库，Windows安装的自行搜索安装

3.1 PostgreSQL安装（推荐版本为v15.x）

1. <font style="color:rgb(6, 6, 7);">访问 </font>[PostgreSQL 官方网站](https://www.postgresql.org/download/)<font style="color:rgb(6, 6, 7);">，下载适用于Windows的安装程序。</font>
2. <font style="color:rgb(6, 6, 7);">运行安装程序，按照提示完成安装。在安装过程中，建议使用默认设置。</font>
3. <font style="color:rgb(6, 6, 7);">安装完成后，启动PostgreSQL服务。可以通过以下命令在命令提示符中运行：</font>

pg_ctl -D "C:\Program Files\PostgreSQL\<版本号>\data" start

• 创建数据库
  1. 打开命令提示符（CMD）或PowerShell，运行以下命令登录PostgreSQL：

psql -U postgres

2. <font style="color:rgb(6, 6, 7);">在PostgreSQL命令行中，运行以下SQL语句创建</font>`maxkb`<font style="color:rgb(6, 6, 7);">数据库并启用</font>`vector`<font style="color:rgb(6, 6, 7);">扩展：</font>

CREATE DATABASE maxkb;
\c maxkb;
CREATE EXTENSION vector;

三、本地配置

1. 配置文件

MaxKB的配置文件config_example.yml提供了项目的运行参数，包括数据库连接信息和模型路径等。需要将该文件复制到指定目录，并根据实际环境进行修改。

1. 打开文件资源管理器，导航到MaxKB项目的根目录。
2. 找到config_example.yml文件，将其复制到C:\opt\maxkb\conf目录（如果该目录不存在，请手动创建，项目代码在哪个盘就在哪个盘创建）。
3. 使用文本编辑器（如Notepad++或VS Code）打开C:\opt\maxkb\conf\config_example.yml文件，并根据实际环境修改以下内容：

# 数据库配置（将以下信息替换为实际环境信息）
DB_NAME: maxkb
DB_HOST: localhost
DB_PORT: 5432
DB_USER: postgres
DB_PASSWORD: <你的数据库密码>
DB_ENGINE: django.db.backends.postgresql_psycopg2# 模型相关配置
EMBEDDING_MODEL_PATH: C:\opt\maxkb\model\
EMBEDDING_MODEL_NAME: C:\opt\maxkb\model\shibing624_text2vec-base-chinese

四、开发调试

1. 启动前端

1. 打开命令提示符（CMD）或PowerShell，导航到ui目录：

cd C:\path\to\maxkb\ui

2. 安装前端依赖：

npm install

3. 启动前端项目：

npm run dev

如果一切正常，你将看到类似以下的输出，表示前端服务已启动：Local: http://localhost:3000

---

2. 启动后端

1. 打开命令提示符（CMD）或PowerShell，导航到MaxKB项目的根目录：

cd C:\path\to\maxkb

2. 安装后端依赖：

poetry install

3. 启动Web服务：

python main.py start

4. 启动本地模型服务：

python main.py dev local_model

5. 启动异步任务服务：

python main.py dev celery

五、访问项目

当前后端服务都成功启动后，你可以通过浏览器访问前端路由地址（通常是http://localhost:3000）来查看项目运行情况。

六、常见问题及解决方法

1. PostgreSQL服务无法启动

• 确保PostgreSQL服务已正确安装并配置。
• 检查服务是否已添加到Windows服务中，可以通过“服务”管理器启动PostgreSQL服务。

2. Python依赖安装失败

• 如果poetry install失败，可能是某些依赖项无法正确下载。尝试切换网络或使用国内镜像源。
• 在命令提示符中运行以下命令配置Python镜像源：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

• 如果问题仍然存在，可以尝试删除poetry.lock文件后重新安装。

3. 前端依赖安装失败

• 如果npm install失败，可能是网络问题导致某些依赖无法下载。可以尝试切换npm镜像源：

npm config set registry https://registry.npmmirror.com

• 如果问题仍然存在，可以尝试删除node_modules目录和package-lock.json文件后重新安装。

七、总结

本文详细介绍了在Windows环境下搭建MaxKB开发环境的步骤，包括前端、后端和数据库的配置。通过遵循上述指南，开发者可以快速搭建一个稳定、高效的开发环境，从而专注于项目的开发工作。如果在搭建过程中遇到问题，可以参考MaxKB的官方文档或社区支持获取帮助。