mirror of
https://github.com/labring/FastGPT.git
synced 2025-10-17 08:37:59 +00:00
32a3b9216b
* docs: https://localhost => http://localhost * chore: docker compose; deploy/dev docs * chore: quick-start page * chore: add comment & remove leading space of vector config * chore: remove redundant install.sh scripts * chore: adjust milvus and ob, image dyanmic config; readme.md * chore: update pnpm-lock.yaml
226 lines
8.6 KiB
Plaintext
226 lines
8.6 KiB
Plaintext
---
|
||
title: 快速开始本地开发
|
||
description: 对 FastGPT 进行开发调试
|
||
---
|
||
|
||
import { Alert } from '@/components/docs/Alert';
|
||
import FastGPTLink from '@/components/docs/linkFastGPT';
|
||
|
||
本文档介绍了如何设置开发环境以构建和测试 <FastGPTLink>FastGPT</FastGPTLink>。
|
||
|
||
## 前置开发环境
|
||
|
||
您需要在计算机上安装和配置以下依赖项才能构建 <FastGPTLink>FastGPT</FastGPTLink>：
|
||
|
||
- [Git](https://git-scm.com/)
|
||
- [Docker](https://www.docker.com/)
|
||
- [Node.js v20.14.0](https://nodejs.org)（版本尽量一样，可以使用 [nvm](https://github.com/nvm-sh/nvm) 管理 node 版本）
|
||
- [pnpm](https://pnpm.io/) 推荐版本 9.4.0 (目前官方的开发环境)
|
||
|
||
建议在 *nix 环境进行开发 (Linux, MacOS, Windows WSL)
|
||
|
||
## 开始本地开发
|
||
|
||
### 1. Fork FastGPT 存储库
|
||
|
||
您需要 Fork [FastGPT 存储库](https://github.com/labring/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 的各种依赖。
|
||
|
||
```bash
|
||
cd FastGPT/deploy/dev
|
||
docker compose up -d
|
||
```
|
||
|
||
<Alert context="warning">
|
||
1. 如果无法获取镜像，可以选择国内镜像版本的 docker-compose.yml 文件：`docker compose -f docker-compose.cn.yml up -d`
|
||
2. Mongo 数据库需要注意，需要注意在连接地址中增加 `directConnection=true`
|
||
参数，才能连接上副本集的数据库。
|
||
</Alert>
|
||
|
||
### 4. 初始配置
|
||
|
||
以下文件均在 `projects/app` 路径下。
|
||
|
||
```bash
|
||
# 确保你现在在 projects/app 下
|
||
pwd
|
||
# 应当输出 /xxxx/xxxx/xxx/FastGPT/projects/app
|
||
```
|
||
|
||
**1. 环境变量**
|
||
|
||
复制 `.env.template` 文件，在同级目录下生成一个`.env.local` 文件，修改`.env.local` 里内容才是有效的变量。
|
||
变量说明见 `.env.template`
|
||
如果没有修改 docker-compose.yaml 中的变量，`.env.template` 中的默认值就可以，不需要进行修改，否则需要和 `yml` 中的变量一致。
|
||
|
||
```bash
|
||
cp .env.template .env.local
|
||
```
|
||
|
||
**2. config.json 配置文件**
|
||
|
||
复制 `data/config.json` 文件，生成一个 `data/config.local.json` 配置文件，具体配置参数说明，可参考 [config 配置说明](/docs/introduction/development/configuration)
|
||
|
||
```bash
|
||
cp data/config.json data/config.local.json
|
||
```
|
||
|
||
这个文件大部分时候不需要修改。只需要关注 `systemEnv` 里的参数：
|
||
|
||
- `vectorMaxProcess`: 向量生成最大进程，根据数据库和 key 的并发数来决定，通常单个 120 号，2c4g 服务器设置 10~15。
|
||
- `qaMaxProcess`: QA 生成最大进程
|
||
- `vlmMaxProcess`: 图片理解模型最大进程
|
||
- `hnswEfSearch`: 向量搜索参数，仅对 PG 和 OB 生效，越大搜索精度越高但是速度越慢。
|
||
|
||
### 5. 运行
|
||
|
||
可参考项目根目录下的 `dev.md`，第一次编译运行可能会有点慢，需要点耐心哦
|
||
|
||
```bash
|
||
# 代码根目录下执行，会安装根 package、projects 和 packages 内所有依赖
|
||
# 如果提示 isolate-vm 安装失败，可以参考：https://github.com/laverdet/isolated-vm?tab=readme-ov-file#requirements
|
||
pwd # 应该在代码的根目录
|
||
pnpm i
|
||
cd projects/app
|
||
pnpm dev
|
||
```
|
||
|
||
默认 next 将运行在 3000 端口，访问 http://localhost:3000
|
||
|
||
### 6. 打包
|
||
|
||
建议直接使用 Docker 进行打包。
|
||
```bash
|
||
# 没有 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 阶段的内容全部手动执行一遍（非常不推荐）。
|
||
|
||
## 提交代码至开源仓库
|
||
|
||
1. 确保你的代码是 Fork [FastGPT](https://github.com/labring/FastGPT) 仓库
|
||
2. 尽可能少量的提交代码，每次提交仅解决一个问题。
|
||
3. 向 FastGPT 的 main 分支提交一个 PR，提交请求后，FastGPT 团队/社区的其他人将与您一起审查它。
|
||
|
||
如果遇到问题，比如合并冲突或不知道如何打开拉取请求，请查看 GitHub 的[拉取请求教程](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests)，了解如何解决合并冲突和其他问题。一旦您的 PR 被合并，您将自豪地被列为[贡献者表](https://github.com/labring/FastGPT/graphs/contributors)中的一员。
|
||
|
||
## 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即可
|
||
|
||
## 加入社区
|
||
|
||
遇到困难了吗？有任何问题吗? 加入飞书群与开发者和用户保持沟通。
|
||
|
||
<img
|
||
width="400px"
|
||
src="https://oss.laf.run/otnvvf-imgs/fastgpt-feishu1.png"
|
||
className="medium-zoom-image"
|
||
/>
|
||
|
||
## 代码结构说明
|
||
|
||
### 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 - 基础功能（日志管理，文件读写等）
|
||
|
||
<details>
|
||
<summary>代码结构说明</summary>
|
||
|
||
```
|
||
.
|
||
├── .github // github 相关配置
|
||
├── .husky // 格式化配置
|
||
├── document // 文档
|
||
├── files // 一些外部文件，例如 docker-compose, helm
|
||
├── packages // 子包
|
||
│ ├── global // 前后端通用子包
|
||
│ ├── plugins // 工作流插件（需要自定义包时候使用到）
|
||
│ ├── service // 后端子包
|
||
│ └── web // 前端子包
|
||
├── projects
|
||
│ └── app // FastGPT 主项目
|
||
├── python // 存放一些模型代码，和 FastGPT 本身无关
|
||
└── scripts // 一些自动化脚本
|
||
├── icon // icon预览脚本，可以在顶层 pnpm initIcon(把svg写入到代码中), pnpm previewIcon（预览icon）
|
||
└── postinstall.sh // chakraUI自定义theme初始化 ts 类型
|
||
├── package.json // 顶层monorepo
|
||
├── pnpm-lock.yaml
|
||
├── pnpm-workspace.yaml // monorepo 声明
|
||
├── Dockerfile
|
||
├── LICENSE
|
||
├── README.md
|
||
├── README_en.md
|
||
├── README_ja.md
|
||
├── dev.md
|
||
```
|
||
|
||
</details>
|