从零开始：在 macOS 上部署与调试 FastGPT 本地开发环境

Moomin245
15 阅读4分钟

从零开始：在 macOS 上部署与调试 FastGPT 本地开发环境(开源版）

摘要：本文详细介绍了如何在完全干净的 macOS 环境中，从安装基础依赖到拉取代码、配置数据库，最终实现 FastGPT 的本地开发调试。

1. 前言

FastGPT 是一个基于 LLM 大语言模型的知识库问答系统，提供开箱即用的数据处理、模型调用及可视化工作流编排能力。对于开发者而言，直接在源码层面进行二次开发和调试是深入理解其架构的最佳方式。

本文将带你一步步搭建本地开发环境。

2. 前置准备：基础环境安装

由于我们假设是一台“没有任何环境依赖”的 Mac，首先需要安装核心工具链。推荐使用 Homebrew 作为包管理器。

2.1 安装 Homebrew

打开终端（Terminal），运行以下命令安装 Homebrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，根据终端提示将 brew 加入 PATH（通常是将几行 export 命令添加到 ~/.zshrc）。

2.2 安装 Git

brew install git

2.3 安装 Node.js (关键步骤)

FastGPT 对 Node.js 版本有严格要求。官方推荐使用 v20.x 系列（如 v20.18.2+），版本过高或过低可能导致 isolate-vm 等依赖编译失败。

推荐使用 nvm (Node Version Manager) 来管理版本：

# 安装 nvm
brew install nvm

# 配置 nvm (将以下内容添加到 ~/.zshrc)
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"' >> ~/.zshrc

# 重新加载配置
source ~/.zshrc

# 安装并切换到 Node.js v20.14.0
nvm install 20.14.0
nvm use 20.14.0
nvm alias default 20.14.0

# 验证版本
node -v # 应显示 v20.14.0
npm -v

2.4 安装 pnpm

FastGPT 项目使用 pnpm 进行包管理，它比 npm 更快且节省磁盘空间。

corepack enable pnpm
# 或者使用 npm 安装
npm install -g pnpm

2.5 安装 Docker Desktop (仅用于数据库)

为了简化开发环境，我们不使用 Docker 运行 FastGPT 主程序（否则无法进行本地代码调试），而是使用 Docker 仅运行 MongoDB 和 PostgreSQL。

# 如果使用 Homebrew 安装 Orbstack
brew install --cask orbstack
# 启动 Orbstack/Docker Desktop 并确保其在后台运行

3. 开始本地开发

3.1 Fork FastGPT 存储库

访问 FastGPT GitHub 仓库，点击右上角的 Fork 按钮，将仓库 Fork 到您的个人 GitHub 账户下。

3.2 克隆存储库

在 FastGPT-local 目录中克隆您在 GitHub 上 Fork 的存储库：

cd FastGPT-local
git clone git@github.com:<your_github_username>/FastGPT.git

注意：克隆完成后，项目根目录为 FastGPT-local/FastGPT，后续所有操作请在此目录中进行。

3.3 通过 Docker 启动开发环境

重要：若您本地已经通过 Docker 启动了 FastGPT，则需要先关闭，否则会有端口冲突。

切换到 FastGPT/deploy/dev 目录，执行 docker compose up -d 运行 FastGPT 的各种依赖服务：

cd FastGPT/deploy/dev
docker compose up -d

如果无法获取镜像，可以选择国内镜像版本的 docker-compose.yml 文件：

docker compose -f docker-compose.cn.yml up -d

MongoDB 连接提示：本地连接 MongoDB 副本集时，需要在连接地址中增加 directConnection=true 参数才能正常连接。

3.4 初始配置

以下配置文件均在 projects/app 路径下进行操作。

3.4.1 确认当前目录
cd ../../projects/app
pwd
# 应当输出 /xxxx/xxxx/xxx/FastGPT-local/FastGPT/projects/app
3.4.2 环境变量配置

复制 .env.template 文件，在同级目录下生成一个 .env.local 文件：

cp .env.template .env.local

说明：.env.local 里的内容才是有效的变量。如果没有修改 docker-compose.yaml 中的变量，.env.template 中的默认值就可以，不需要进行修改，否则需要和 yml 中的变量一致。变量说明见 .env.template 文件。

3.4.3 config.json 配置文件

复制 data/config.json 文件，生成一个 data/config.local.json 配置文件：

cp data/config.json data/config.local.json

说明：这个文件大部分时候不需要修改。只需要关注 systemEnv 里的参数：

  • vectorMaxProcess: 向量生成最大进程，根据数据库和 key 的并发数来决定，通常单个 120 号，2c4g 服务器设置 10~15
  • qaMaxProcess: QA 生成最大进程
  • vlmMaxProcess: 图片理解模型最大进程
  • hnswEfSearch: 向量搜索参数，仅对 PG 和 OB 生效，越大搜索精度越高但是速度越慢

具体配置参数说明可参考 config 配置说明。

3.5 运行项目

回到代码根目录下执行，会安装根 package、projects 和 packages 内所有依赖：

cd ../../
pnpm i

然后再执行 pnpm i。如果是 Windows 系统，可以使用 Git Bash 给 postinstall 脚本添加执行权限并执行 sh 脚本。

安装完成后，进入 projects/app 目录启动开发服务器：

cd projects/app
pnpm dev

默认 Next.js 将运行在 3000 端口，访问：

http://localhost:3000

4. 本地开发流程总结

# 1. 根目录安装依赖
pnpm i

# 2. 复制配置文件
cp projects/app/.env.template projects/app/.env.local
cp projects/app/data/config.json projects/app/data/config.local.json

# 3. 进入项目目录
cd projects/app

# 4. 启动开发服务器
pnpm dev

5. 打包（可选）

建议直接使用 Docker 进行打包：

# 没有 Proxy
docker build -f ./projects/app/Dockerfile -t fastgpt . --build-arg name=app

# Taobao Proxy
docker build -f ./projects/app/Dockerfile -t fastgpt . --build-arg name=app --build-arg proxy=taobao

注意：如果不使用 Docker 打包，需要手动把 Dockerfile 里 run 阶段的内容全部手动执行一遍（非常不推荐）。

avatar
文章
阅读
粉丝