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

前置依赖项

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

• Git
• Docker（构建镜像）
• Node.js v20.14.0（版本尽量一样，可以使用nvm管理node版本）
• pnpm 推荐版本 9.4.0 (目前官方的开发环境)
• make命令: 根据不同平台，百度安装 (官方是GNU Make 4.3)

开始本地开发

1. 用户默认的时区为 Asia/Shanghai,非 linux 环境时候，获取系统时间会异常，本地开发时候，可以将用户的时区调整成 UTC（+0）。
2. 建议先服务器装好数据库，再进行本地开发。

1. Fork 存储库

您需要 Fork 存储库。

2. 克隆存储库

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

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

目录简要说明

1. projects 目录下为 FastGPT 应用代码。其中 app 为 FastGPT 核心应用。（后续可能会引入其他应用）
2. NextJS 框架前后端放在一起，API 服务位于 src/pages/api 目录内。
3. packages 目录为共用代码，通过 workspace 被注入到 projects 中，已配置 monorepo 自动注入，无需额外打包。

3. 安装数据库

第一次开发，需要先部署数据库，建议本地开发可以随便找一台 2C2G 的轻量小数据库实践，或者新建文件夹并配置相关文件用以运行docker。数据库部署教程：Docker 快速部署。部署完了，可以本地访问其数据库。

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

4. 初始配置

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

1. 环境变量

复制.env.template文件，在同级目录下生成一个.env.local 文件，修改.env.local 里内容才是有效的变量。变量说明见 .env.template，主要需要修改API_KEY和数据库的地址与端口以及数据库账号的用户名和密码，具体配置需要和docker配置文件相同，其中用户名和密码如需修改需要修改docker配置文件、数据库和.env.local文件，不能只改一处。

2. config 配置文件

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

注意：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#requirementspnpm i# 非 Make 运行cd projects/apppnpm dev# Make 运行make dev name=app

6. 部署打包

# Docker cmd: Build image, not proxydocker build -f ./projects/app/Dockerfile -t registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt:v4.8.1 . --build-arg name=app# Make cmd: Build image, not proxymake build name=app image=registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt:v4.8.1# Docker cmd: Build image with proxydocker build -f ./projects/app/Dockerfile -t registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt:v4.8.1 . --build-arg name=app --build-arg proxy=taobao# Make cmd: Build image with proxymake build name=app image=registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt:v4.8.1 proxy=taobao

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

提交代码至开源仓库

1. 确保你的代码是 Fork FastGPT 仓库
2. 尽可能少量的提交代码，每次提交仅解决一个问题。
3. 向 FastGPT 的 main 分支提交一个 PR，提交请求后，FastGPT 团队/社区的其他人将与您一起审查它。

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

QA

本地数据库无法连接

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即可

《CDA数据分析师技能树系列图书》系统整合数据分析核心知识，从基础工具（如Python、SQL、Excel、Tableau、SPSS等）到机器学习、深度学习算法，再到行业实战（金融、零售等场景）形成完整体系。书中结合案例讲解数据清洗、建模、可视化等技能，兼顾理论深度与实操性，帮助读者构建系统化知识框架。同时，内容紧跟行业趋势，涵盖大数据分析、商业智能、ChatGPT与DeepSeek等前沿领域，还配套练习与项目实战，助力读者将知识转化为职场竞争力，是数据分析师从入门到进阶的实用参考资料。