FastGPT

首页 > 帮助 > 使用技巧 > 入门 > FastGPT 社区版 > 快速开始本地开发

快速开始本地开发

对 FastGPT 进行开发调试

本文档介绍了如何设置开发环境以构建和测试 FastGPT。

前置开发环境

您需要在计算机上安装和配置以下依赖项才能构建 FastGPT：

  • Git

  • Docker

  • Node.js v20.14.0（版本尽量一样，可以使用 nvm 管理 node 版本）

  • pnpm 推荐版本 9.4.0 (目前官方的开发环境)

建议在 *nix 环境进行开发 (Linux, MacOS, Windows WSL)

开始本地开发

1. Fork FastGPT 存储库

您需要 Fork FastGPT 存储库。

2. 克隆存储库<

克隆您在 GitHub 上 Fork 的存储库：


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

3. 通过 docker 启动开发环境

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

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


cd FastGPT/deploy/devdocker compose up -d

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

  2. Mongo 数据库需要注意，需要注意在连接地址中增加 directConnection=true 参数，才能连接上副本集的数据库。

4. 初始配置

以下文件均在 projects/app 路径下。


# 确保你现在在 projects/app 下pwd# 应当输出 /xxxx/xxxx/xxx/FastGPT/projects/app

1. 环境变量

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


cp .env.template .env.local

2. config.json 配置文件

复制 data/config.json 文件，生成一个 data/config.local.json 配置文件，具体配置参数说明，可参考 config 配置说明


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

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

  • vectorMaxProcess: 向量生成最大进程，根据数据库和 key 的并发数来决定，通常单个 120 号，2c4g 服务器设置 10~15。

  • qaMaxProcess: QA 生成最大进程

  • vlmMaxProcess: 图片理解模型最大进程

  • hnswEfSearch: 向量搜索参数，仅对 PG 和 OB 生效，越大搜索精度越高但是速度越慢。

5. 运行

可参考项目根目录下的 dev.md，第一次编译运行可能会有点慢，需要点耐心哦


# 代码根目录下执行，会安装根 package、projects 和 packages 内所有依赖# 如果提示 isolate-vm 安装失败，可以参考：https://github.com/laverdet/isolated-vm?tab=readme-ov-file#requirementspwd # 应该在代码的根目录pnpm icd projects/apppnpm dev

默认 next 将运行在 3000 端口，访问 http://localhost:3000

6. 打包

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


# 没有 Proxydocker build -f ./projects/app/Dockerfile -t fastgpt . --build-arg name=app# Taobao Proxydocker build -f ./projects/app/Dockerfile -t fastgpt. --build-arg name=app --build-arg proxy=taobao

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

提交代码至开源仓库

  1. 确保你的代码是 Fork FastGPT 仓库

  2. 尽可能少量的提交代码，每次提交仅解决一个问题。

  3. 向 FastGPT 的 main 分支提交一个 PR，提交请求后，FastGPT 团队/社区的其他人将与您一起审查它。

如果遇到问题，比如合并冲突或不知道如何打开拉取请求，请查看 GitHub 的拉取请求教程，了解如何解决合并冲突和其他问题。一旦您的 PR 被合并，您将自豪地被列为贡献者表中的一员。

QA

获取系统时间异常

如果用户默认的时区为 Asia/Shanghai, 非 linux 环境时，获取系统时间会异常，本地开发时，可以将用户的时区调整成 UTC（+0）。

本地数据库无法连接

  1. 如果你是连接远程的数据库，先检查对应的端口是否开放。

  2. 如果是本地运行的数据库，可尝试host改成localhost或127.0.0.1

  3. 本地连接远程的 Mongo，需要增加 directConnection=true 参数，才能连接上副本集的数据库。

  4. mongo使用mongocompass客户端进行连接测试和可视化管理。

  5. pg使用navicat进行连接和管理。

sh ./scripts/postinstall.sh 没权限

FastGPT 在pnpm i后会执行postinstall脚本，用于自动生成ChakraUI的Type。如果没有权限，可以先执行chmod -R +x ./scripts/，再执行pnpm i。

仍不可行的话，可以手动执行./scripts/postinstall.sh里的内容。 如果是Windows下的话，可以使用git bash给postinstall脚本添加执行权限并执行sh脚本

TypeError: Cannot read properties of null (reading 'useMemo' )

删除所有的node_modules，用 Node18 重新 install 试试，可能最新的 Node 有问题。 本地开发流程：

  1. 根目录: pnpm i

  2. 复制 config.json -> config.local.json

  3. 复制 .env.template -> .env.local

  4. cd projects/app

  5. pnpm dev

Error response from daemon: error while creating mount source path 'XXX': mkdir XXX: file exists

这个错误可能是之前停止容器时有文件残留导致的，首先需要确认相关镜像都全部关闭，然后手动删除相关文件或者重启docker即可

代码结构说明

nextjs

FastGPT 使用了 nextjs 的 page route 作为框架。为了区分好前后端代码，在目录分配上会分成 global, service, web 3个自目录，分别对应着 前后端共用、后端专用、前端专用的代码。

monorepo

FastGPT 采用 pnpm workspace 方式构建 monorepo 项目，主要分为两个部分：

  • projects/app - FastGPT 主项目

  • packages/ - 子模块

    • global - 共用代码，通常是放一些前后端都能执行的函数、类型声明、常量。

    • service - 服务端代码

    • web - 前端代码

    • plugin - 工作流自定义插件的代码

领域驱动模式（DDD）

FastGPT 在代码模块划分时，按DDD的思想进行划分，主要分为以下几个领域：

  • core - 核心功能（知识库，工作流，应用，对话）

  • support - 支撑功能（用户体系，计费，鉴权等）

  • common - 基础功能（日志管理，文件读写等）


上一篇 Sealos 一键部署
下一篇 Docker Compose 快速部署
放大预览