FastGPT 商业版本地开发环境部署指南

Moomin245
4 阅读5分钟

FastGPT 商业版本地开发环境部署指南

本文档将带你完整部署 FastGPT 商业版本的本地开发环境，包括环境配置、代码克隆、Git 远程仓库设置以及环境变量配置等所有必要步骤。

📋 目录

  1. 环境准备
  2. Fork 代码仓库
  3. 克隆代码到本地
  4. 配置 Git Remote
  5. 环境变量配置
  6. 安装依赖与启动
  7. VSCode 插件推荐
  8. 代码提交规范

1. 环境准备

在开始之前，请确保你的开发环境已安装以下依赖：

1.1 Node.js 和 pnpm

# 推荐版本
Node: v20.14.0
pnpm: 9.4.0

# 使用 nvm 安装 Node.js（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20.14.0
nvm use 20.14.0

# 安装 pnpm
npm install -g pnpm@9.4.0

# 验证安装
node -v
pnpm -v

2. Fork 代码仓库

FastGPT 商业版采用 Monorepo 架构，需要 Fork 两个仓库：

仓库类型仓库地址说明
商业版github.com/labring/fas…需要联系管理员获取访问权限
开源版github.com/labring/Fas…公开仓库，直接 Fork

操作步骤

  1. 登录 GitHub 账号
  2. 访问上述两个仓库地址
  3. 点击右上角的 Fork 按钮
  4. 商业版仓库需要发送你的 GitHub 账号给管理员获取访问权限

3. 克隆代码到本地

3.1 Clone 商业版仓库

# 克隆你 fork 后的 pro 仓库
git clone git@github.com:<your-username>/fastgpt-pro.git
cd fastgpt-pro

3.2 初始化子模块

商业版仓库通过 Git Submodules 引用主项目代码：

# 初始化并更新子模块
git submodule update --init --recursive

⚠️ 此命令会拉取 FastGPT 开源仓库的代码到本地，可能需要一些时间

4. 配置 Git Remote

子模块初始化后，需要配置正确的 Git Remote 以便后续开发提交。

4.1 配置 fastgpt-pro（商业版）

cd fastgpt-pro

# 添加 upstream 指向官方商业版仓库
git remote add upstream https://github.com/labring/fastgpt-pro.git

# 验证配置
git remote -v

预期输出：

origin    git@github.com:<your-username>/fastgpt-pro.git (fetch)
origin    git@github.com:<your-username>/fastgpt-pro.git (push)
upstream  https://github.com/labring/fastgpt-pro.git (fetch)
upstream  https://github.com/labring/fastgpt-pro.git (push)

4.2 配置 FastGPT（开源版子模块）

# 进入 FastGPT 子模块目录
cd FastGPT

# 移除原有的 origin（指向 labring/FastGPT）
git remote remove origin

# 添加新的 origin（指向你 fork 的仓库）
git remote add origin git@github.com:<your-username>/FastGPT.git

# 添加 upstream 指向官方开源仓库
git remote add upstream https://github.com/labring/FastGPT.git

# 验证配置
git remote -v

预期输出：

origin    git@github.com:<your-username>/FastGPT.git (fetch)
origin    git@github.com:<your-username>/FastGPT.git (push)
upstream  https://github.com/labring/FastGPT.git (fetch)
upstream  https://github.com/labring/FastGPT.git (push)

💡 提示： 请将 <your-username> 替换为你实际的 GitHub 用户名

5. 环境变量配置

项目包含两个部分，都需要配置环境变量文件。

5.1 FastGPT（开源版部分）

# 进入 FastGPT 项目目录
cd FastGPT/projects/app

# 复制环境变量模板
cp .env.template .env.local

# 编辑 .env.local，添加 PRO_URL 环境变量（直接通过代码编辑器手动修改也可以）
echo "PRO_URL=http://localhost:3001" >> .env.local

5.2 fastgpt-pro（商业版部分）

# 进入 fastgpt-pro 项目目录
cd fastgpt-pro/projects/app

# 复制环境变量模板
cp .env.template .env.local

5.3 环境变量说明

变量名说明示例值
PRO_URL商业版服务地址http://localhost:3001
MONGODB_URIMongoDB 连接地址mongodb://localhost:27017/fastgpt
REDIS_URLRedis 连接地址redis://localhost:6379

📌 环境变量请根据最新的 .env.template 文件进行配置，开发服务器连接地址已在模板中提供

6. 安装依赖与启动

6.1 通过 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

6.2 安装依赖

# 返回项目根目录
cd fastgpt-pro

# 使用 pnpm 安装依赖
pnpm install

6.2 启动开发服务器

# 启动商业版管理后台
make dev name=app

# 启动前台
cd FastGPT
make dev name=app

服务端口：

7. VSCode 插件推荐

为了更好的开发体验，建议安装以下 VSCode 插件：

插件名称用途
i18n Ally国际化翻译支持
ESLint代码规范检查
Prettier代码格式化
React Developer ToolsReact 开发调试

8. 代码提交规范

由于项目采用 Monorepo 架构，代码提交需要注意以下规则：

8.1 仓库结构说明

fastgpt-pro/
├── packages/          # 复用代码（属于主项目）
├── projects/app/      # 商业版应用代码
└── FastGPT/           # 子模块（开源版主项目）
    ├── packages/      # 主项目复用代码
    └── projects/app/  # 开源版应用代码

8.2 提交规则

修改范围提交目标说明
FastGPT/projects主项目 PR只需向 FastGPT 仓库提交
fastgpt-pro/projects商业版 PR只需向 fastgpt-pro 仓库提交
FastGPT/packages双仓库 PR需要同时向两个仓库提交

8.3 提交示例

# 提交主项目代码
cd FastGPT
git add .
git commit -m "feat: 添加新功能"
git push origin main

# 提交商业版代码
cd fastgpt-pro
git add .
git commit -m "feat: 商业版功能更新"
git push origin main

🔧 常见问题

Q1: 子模块拉取失败

# 尝试重新初始化子模块
git submodule sync --recursive
git submodule update --init --recursive

Q2: Git Remote 配置错误

# 查看当前 remote 配置
git remote -v

# 删除错误的 remote
git remote remove <name>

# 重新添加正确的 remote
git remote add <name> <url>

Q3: 端口被占用

# 查看占用端口的进程
lsof -i :3000
lsof -i :3001

# 杀死占用端口的进程
kill -9 <PID>

📚 参考文档

✅ 部署检查清单

  • Node.js v20.14.0+ 已安装
  • pnpm 9.4.0+ 已安装
  • Docker 及 Docker Compose 已安装
  • 两个 GitHub 仓库已 Fork
  • 代码已克隆到本地
  • Git Submodule 已初始化
  • Git Remote 已正确配置
  • .env.local 文件已创建并配置
  • 依赖已安装
  • 开发服务器可正常启动

🎉 恭喜你完成 FastGPT 商业版本地开发环境的部署！如有问题，请参考官方文档或联系项目维护者。

avatar
文章
阅读
粉丝