FastGPT极速上手指南：Docker容器化部署实战

• 使用 Docker Compose 快速部署 FastGPT 4.9.7 版本

一、前置知识

1. 基础的网络知识：端口，防火墙……
2. Docker 和 Docker Compose 基础知识
3. 大模型相关接口和参数
4. RAG 相关知识：向量模型，向量数据库，向量检索

二、部署架构图

• MongoDB：用于存储除了向量外的各类数据
• PostgreSQL/Milvus：存储向量数据
• OneAPI: 聚合各类 AI API，支持多模型调用 （任何模型问题，先自行通过 OneAPI 测试校验）

三、向量库选择

1. PgVector版本

• 非常轻量，适合知识库索引量在 5000 万以下。

2. Milvus版本

• 对于亿级以上向量性能更优秀。点击查看 Milvus 官方推荐配置

3. zilliz cloud版本

• Zilliz Cloud 由 Milvus 原厂打造，是全托管的 SaaS 向量数据库服务，性能优于 Milvus 并提供 SLA，点击使用 Zilliz Cloud。由于向量库使用了 Cloud，无需占用本地资源，无需太关注。

四、前置工作

1. 确保网络环境

• 如果使用OpenAI等国外模型接口，请确保可以正常访问，否则会报错：Connection error 等。 方案可以参考：代理方案

2. 准备 Docker 环境

2.1 Linux环境

# 安装 Docker
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun
systemctl enable --now docker
# 安装 docker-compose
curl -L https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
# 验证安装
docker -v
docker-compose -v
# 如失效，自行百度~

2.2 Windows环境

• 可以选择直接使用 WSL 2 后端在 Windows 中安装 Docker Desktop。
• 也可以直接在 WSL 2 中安装命令行版本的 Docker。
• 建议将源代码和其他数据绑定到 Linux 容器中时，将其存储在 Linux 文件系统中，而不是 Windows 文件系统中。

五、FastGPT部署

1. 下载 docker-compose.yml

• 下载配置文件 config.json 和对应版本的docker-compose.yml
• 本地开发使用推荐docker-compose-pgvector版本，并且自行拉取并运行sandbox和fastgpt
• 本文部署使用 docker-compose-milvus.yml 版本
• config.json
• docker-compose.yml (注意，不同向量库版本的文件不一样)
• Linux 快速脚本

mkdir fastgpt
cd fastgpt
curl -O https://raw.githubusercontent.com/labring/FastGPT/main/projects/app/data/config.json
# pgvector 版本(测试推荐，简单快捷)
#curl -o docker-compose.yml https://raw.githubusercontent.com/labring/FastGPT/main/deploy/docker/docker-compose-pgvector.yml
# oceanbase 版本（需要将init.sql和docker-compose.yml放在同一个文件夹，方便挂载）
# curl -o docker-compose.yml https://raw.githubusercontent.com/labring/FastGPT/main/deploy/docker/docker-compose-oceanbase/docker-compose.yml
# curl -o init.sql https://raw.githubusercontent.com/labring/FastGPT/main/deploy/docker/docker-compose-oceanbase/init.sql
# milvus 版本
curl -o docker-compose.yml https://raw.githubusercontent.com/labring/FastGPT/main/deploy/docker/docker-compose-milvus.yml
# zilliz 版本
# curl -o docker-compose.yml https://raw.githubusercontent.com/labring/FastGPT/main/deploy/docker/docker-compose-zilliz.yml

2. 修改 docker-compose.yml 文件

• 更换镜像地址

# minio
swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/minio/minio:RELEASE.2023-03-20T20-16-18Z
# milvusStandalone
swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/milvusdb/milvus:v2.4.3
# mongo
registry.cn-hangzhou.aliyuncs.com/fastgpt/mongo:5.0.18
# redis
swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/redis:7.2-alpine
# sandbox
registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sandbox:v4.9.7-fix2
# fastgpt-mcp-server
registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-mcp_server:v4.9.7-fix2
# fastgpt
registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt:v4.9.7-fix2
# aiproxy
registry.cn-hangzhou.aliyuncs.com/labring/aiproxy:v0.1.7
# aiproxy_pg
registry.cn-hangzhou.aliyuncs.com/fastgpt/pgvector:v0.8.0-pg15

3. 修改 config.json 配置文件

• 修改config.json文件中的mcpServerProxyEndpoint值，设置成mcp server的公网可访问地址，yml 文件中默认给出了映射到 3005 端口，如通过 IP 访问，则可能是：120.172.2.10:3005。

4. 启动容器

• 在 docker-compose.yml 同级目录下执行。请确保docker-compose版本最好在2.17以上，否则可能无法执行自动化命令。

# 启动容器
docker-compose up -d

• FastGPT服务涉及所有容器均已启动，如下：
  

5. 访问 FastGPT

• 目前可以通过 ip:3000 直接访问(注意开放防火墙)。登录用户名为 root，密码为docker-compose.yml环境变量里设置的 DEFAULT_ROOT_PSW。
• 如果需要域名访问，请自行安装并配置 Nginx。
• 首次运行，会自动初始化 root 用户，密码为 1234（与环境变量中的DEFAULT_ROOT_PSW一致）。

6. 配置模型

• 首次登录FastGPT后，系统会提示未配置语言模型和索引模型，并自动跳转模型配置页面。系统必须至少有这两类模型才能正常使用。
• 如果系统未正常跳转，可以在账号-模型提供商页面，进行模型配置。
• 目前已知可能问题：首次进入系统后，整个浏览器 tab 无法响应。此时需要删除该tab，重新打开一次即可。
• FastGPT模型详细配置说明：FastGPT 模型配置说明 | FastGPT

6.1 对接模型提供商

• AI Proxy：从 4.8.23 版本开始， FastGPT 支持在页面上配置模型提供商，即使用 AI Proxy 接入来进行模型聚合，从而可以对接更多模型提供商。
• One API：使用 OneAPI 接入，你需要先在各服务商申请好 API 接入 OneAPI 后，才能在 FastGPT 中使用这些模型。
• 除了各模型官方的服务外，还有一些第三方服务商提供模型接入服务，当然你也可以用 Ollama 等来部署本地模型，最终都需要接入 OneAPI，下面是一些第三方服务商：
• SiliconCloud(硅基流动): 提供开源模型调用的平台。
• Sealos AIProxy: 提供国内各家模型代理，无需逐一申请 api。
• 在 OneAPI 配置好模型后，你就可以打开 FastGPT 页面，启用对应模型了。

6.2 支持模型类型

1. 语言模型 - 进行文本对话，多模态模型支持图片识别。
2. 索引模型 - 对文本块进行索引，用于相关文本检索。
3. 重排模型 - 对检索结果进行重排，用于优化检索排名。
4. 语音合成 - 将文本转换为语音。
5. 语音识别 - 将语音转换为文本。

六、常见问题解决

1. Mongo 副本集自动初始化失败

• 最新的 docker-compose 示例优化 Mongo 副本集初始化，实现了全自动。目前在 unbuntu20,22 centos7, wsl2, mac, window 均通过测试。
• 如果是由于，无法自动初始化副本集合，可以手动初始化副本集：

1. 终端中执行下面命令，创建mongo密钥：

openssl rand -base64 756 > ./mongodb.key
chmod 600 ./mongodb.key
# 修改密钥权限，部分系统是admin，部分是root
chown 999:root ./mongodb.key

2. 修改 docker-compose.yml，挂载密钥

mongo:#  image: mongo:5.0.18# image: registry.cn-hangzhou.aliyuncs.com/fastgpt/mongo:5.0.18 # 阿里云container_name: mongoports:- 27017:27017networks:- fastgptcommand: mongod --keyFile /data/mongodb.key --replSet rs0environment:# 默认的用户名和密码，只有首次允许有效- MONGO_INITDB_ROOT_USERNAME=myusername- MONGO_INITDB_ROOT_PASSWORD=mypasswordvolumes:- ./mongo/data:/data/db- ./mongodb.key:/data/mongodb.key

3. 重启服务

docker-compose down
docker-compose up -d

4. 进入容器执行副本集合初始化

# 查看 mongo 容器是否正常运行
docker ps 
# 进入容器
docker exec -it mongo bash# 连接数据库（这里要填Mongo的用户名和密码）
mongo -u myusername -p mypassword --authenticationDatabase admin# 初始化副本集。如果需要外网访问，mongo:27017 。如果需要外网访问，需要增加Mongo连接参数：directConnection=true
rs.initiate({_id: "rs0",members: [{ _id: 0, host: "mongo:27017" }]
})
# 检查状态。如果提示 rs0 状态，则代表运行成功
rs.status()

2. 如何自定义配置文件？

修改config.json文件，并执行docker-compose down再执行docker-compose up -d重起容器。具体配置，参考配置详解。

3. 如何检查自定义配置文件是否挂载

1. docker logs fastgpt 可以查看日志，在启动容器后，第一次请求网页，会进行配置文件读取，可以看看有没有读取成功以及有无错误日志。
2. docker exec -it fastgpt sh 进入 FastGPT 容器，可以通过ls data查看目录下是否成功挂载config.json文件。可通过cat data/config.json查看配置文件。

• 可能不生效的原因

1. 挂载目录不正确
2. 配置文件不正确，日志中会提示invalid json，配置文件需要是标准的 JSON 文件。
3. 修改后，没有docker-compose down再docker-compose up -d，restart是不会重新挂载文件的。

4. 如何检查环境变量是否正常加载

1. docker exec -it fastgpt sh 进入 FastGPT 容器。
2. 直接输入env命令查看所有环境变量。

5. 连接本地模型镜像

• docker-compose.yml中使用了桥接的模式建立了fastgpt网络，如想通过0.0.0.0或镜像名访问其它镜像，需将其它镜像也加入到网络中。

6. 首次部署，root用户提示未注册

• 日志会有错误提示。大概率是没有启动 Mongo 副本集模式。

7. 登录提示 Network Error

• 由于服务初始化错误，系统重启导致。
  • 90%是由于配置文件写不对，导致 JSON 解析报错
  • 剩下的基本是因为向量数据库连不上

8. 如何修改密码

• 修改docker-compose.yml文件中DEFAULT_ROOT_PSW并重启即可，密码会自动更新。