FastGPT Docker部署教程｜附源码

随着大语言模型应用的快速发展，越来越多企业和开发者希望搭建一套属于自己的知识库问答系统、AI客服系统、企业内部智能助手或私有化AI应用平台。FastGPT 正是一个非常适合入门和落地的开源项目。它基于大语言模型能力，提供了可视化工作流、知识库、AI应用编排、插件调用等功能，能够帮助开发者快速构建各种智能应用。

本文将围绕 FastGPT 的 Docker 部署方式 展开，详细介绍从环境准备、配置文件编写、服务启动、常见问题排查，到源码结构说明和二次开发建议。无论你是想在本地测试，还是准备在服务器上私有化部署，都可以参考本文完成部署。

一、FastGPT简介

FastGPT 是一个开源的 AI 知识库问答和应用编排平台，通常用于以下场景：

• 企业内部知识库问答
• AI客服机器人
• 文档智能检索
• 私有化大模型应用平台
• 工作流自动化智能助手
• 基于知识库的RAG应用开发
• 多模型、多应用统一管理

FastGPT 的核心能力包括：

1. 知识库管理
   支持上传文档、网页内容、Markdown、PDF等资料，并进行向量化处理。

2. RAG检索增强生成
   用户提问时，系统会先从知识库中检索相关内容，再结合大模型生成回答。

3. 可视化工作流编排
   可通过拖拽方式配置复杂AI应用逻辑，例如条件判断、HTTP请求、插件调用等。

4. 多模型接入
   可对接 OpenAI、Azure OpenAI、ChatGLM、通义千问、DeepSeek、Moonshot、智谱等模型服务。

5. 私有化部署
   可以通过 Docker 快速部署到自己的服务器，适合企业内部使用。

二、部署前准备

在开始部署 FastGPT 之前，需要准备一台 Linux 服务器。推荐使用 Ubuntu 20.04 或 Ubuntu 22.04。

1. 服务器配置建议

如果只是测试环境，推荐配置如下：

如果是生产环境，建议配置：

FastGPT 本身并不一定需要 GPU，因为大多数情况下它只是调用远程大模型 API。如果你需要本地部署大模型，则需要额外准备 GPU 服务器。

三、安装Docker和Docker Compose

FastGPT 推荐使用 Docker 部署，因为它依赖的组件较多，例如 MongoDB、PostgreSQL、向量数据库等，通过 Docker Compose 可以一次性启动多个服务。

1. 更新系统软件包

sudo apt update
sudo apt upgrade -y

2. 安装基础工具

sudo apt install -y curl wget git vim ca-certificates gnupg lsb-release

3. 安装Docker

可以使用官方脚本快速安装：

curl -fsSL https://get.docker.com | bash

安装完成后，查看 Docker 版本：

docker -v

如果能看到类似输出，说明安装成功：

Docker version 26.1.0, build xxxxxxx

4. 设置Docker开机自启

sudo systemctl enable docker
sudo systemctl start docker

5. 安装Docker Compose

较新版本 Docker 已经内置了 Compose 插件，可以通过以下命令查看：

docker compose version

如果输出类似：

Docker Compose version v2.x.x

说明可以直接使用 docker compose 命令。

四、获取FastGPT源码

FastGPT 是开源项目，可以从 GitHub 获取源码。

git clone https://github.com/labring/FastGPT.git
cd FastGPT

如果服务器访问 GitHub 较慢，也可以使用代理或镜像源拉取。

查看项目目录：

ls

常见目录结构如下：

FastGPT
├── projects
│   ├── app
│   └── sandbox
├── packages
├── files
├── docker
├── scripts
├── package.json
└── README.md

其中：

五、Docker Compose部署思路

FastGPT 的 Docker 部署通常包含以下几个核心服务：

1. FastGPT Web服务
   提供前端页面和后端接口。

2. MongoDB
   用于存储用户、应用、知识库、对话记录等业务数据。

3. PostgreSQL / Vector数据库
   用于向量存储和知识库检索。

4. Sandbox服务
   用于执行代码块、插件或工作流中的部分逻辑。

5. 外部模型API
   例如 OpenAI、DeepSeek、通义千问等。

需要注意的是，FastGPT 的不同版本可能对数据库和配置项略有差异，因此实际部署时建议以官方仓库中的最新 docker-compose.yml 文件为准。本文给出的是一个可参考、易理解的部署示例。

六、创建部署目录

为了便于管理，可以单独创建部署目录：

mkdir -p /opt/fastgpt
cd /opt/fastgpt

如果你已经通过 Git 克隆了源码，也可以直接在源码目录中进行部署。

七、编写docker-compose.yml源码

下面是一份示例 docker-compose.yml 文件，适合大多数测试和中小型部署场景。你可以根据实际情况调整镜像版本、端口、数据库密码等。

version: "3.8"

services:
  fastgpt:
    image: ghcr.io/labring/fastgpt:latest
    container_name: fastgpt
    restart: always
    ports:
      - "3000:3000"
    depends_on:
      - mongo
      - pg
      - sandbox
    environment:
      # FastGPT访问地址
      - FE_DOMAIN=http://localhost:3000

      # 登录密钥，可自定义修改
      - DEFAULT_ROOT_PSW=123456

      # MongoDB连接地址
      - MONGODB_URI=mongodb://username:password@mongo:27017/fastgpt?authSource=admin

      # PostgreSQL连接地址
      - PG_URL=postgresql://postgres:postgres@pg:5432/postgres

      # Sandbox地址
      - SANDBOX_URL=http://sandbox:3000

      # AI模型配置文件路径
      - AI_PROVIDER=openai

      # OpenAI兼容接口配置
      - OPENAI_BASE_URL=https://api.openai.com/v1
      - CHAT_API_KEY=sk-xxxxxxx

    volumes:
      - ./config.json:/app/data/config.json
    networks:
      - fastgpt

  mongo:
    image: mongo:5.0
    container_name: fastgpt-mongo
    restart: always
    command: mongod --keyFile /data/mongodb.key --replSet rs0
    environment:
      - MONGO_INITDB_ROOT_USERNAME=username
      - MONGO_INITDB_ROOT_PASSWORD=password
    volumes:
      - ./mongo/data:/data/db
      - ./mongo/mongodb.key:/data/mongodb.key
    networks:
      - fastgpt

  pg:
    image: ankane/pgvector:v0.5.1
    container_name: fastgpt-pg
    restart: always
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=postgres
    volumes:
      - ./pg/data:/var/lib/postgresql/data
    networks:
      - fastgpt

  sandbox:
    image: ghcr.io/labring/fastgpt-sandbox:latest
    container_name: fastgpt-sandbox
    restart: always
    networks:
      - fastgpt

networks:
  fastgpt:
    driver: bridge

注意：以上配置是示例模板。实际部署时，建议结合 FastGPT 官方最新文档和仓库中的配置文件进行调整。

八、创建MongoDB keyFile

MongoDB 如果开启副本集，通常需要 keyFile。先创建目录：

mkdir -p mongo/data
mkdir -p pg/data

生成 key 文件：

openssl rand -base64 756 > mongo/mongodb.key
chmod 400 mongo/mongodb.key

由于 MongoDB 容器内运行用户可能对权限较敏感，如果启动失败，可以尝试修改文件归属：

sudo chown 999:999 mongo/mongodb.key

九、编写FastGPT配置文件config.json源码

FastGPT 通常需要通过配置文件定义模型、向量模型、重排模型等。下面给出一份 OpenAI 兼容接口示例。

创建 config.json：

vim config.json

写入以下内容：

{
  "systemEnv": {
    "openapiPrefix": "fastgpt",
    "vectorMaxProcess": 15,
    "qaMaxProcess": 15,
    "tokenWorkers": 30,
    "pgHNSWEfSearch": 100
  },
  "llmModels": [
    {
      "model": "gpt-4o-mini",
      "name": "GPT-4o Mini",
      "maxContext": 125000,
      "maxResponse": 16000,
      "quoteMaxToken": 120000,
      "maxTemperature": 1.2,
      "charsPointsPrice": 0,
      "censor": false,
      "vision": true,
      "datasetProcess": true,
      "usedInClassify": true,
      "usedInExtractFields": true,
      "usedInToolCall": true,
      "usedInQueryExtension": true,
      "toolChoice": true,
      "functionCall": true,
      "customCQPrompt": "",
      "customExtractPrompt": "",
      "defaultSystemChatPrompt": "",
      "defaultConfig": {}
    }
  ],
  "vectorModels": [
    {
      "model": "text-embedding-3-small",
      "name": "Embedding-3-Small",
      "price": 0,
      "defaultToken": 700,
      "maxToken": 8192
    }
  ],
  "reRankModels": [],
  "audioSpeechModels": [],
  "whisperModel": {
    "model": "whisper-1",
    "name": "Whisper",
    "charsPointsPrice": 0
  }
}

如果你使用的是其他 OpenAI 兼容服务，例如 DeepSeek、通义千问、Moonshot、硅基流动等，需要修改 OPENAI_BASE_URL、CHAT_API_KEY 以及模型名称。

例如 DeepSeek 配置可以参考：

- OPENAI_BASE_URL=https://api.deepseek.com/v1
- CHAT_API_KEY=sk-你的DeepSeekKey

模型配置示例：

{
  "llmModels": [
    {
      "model": "deepseek-chat",
      "name": "DeepSeek Chat",
      "maxContext": 64000,
      "maxResponse": 8000,
      "quoteMaxToken": 30000,
      "maxTemperature": 1.2,
      "charsPointsPrice": 0,
      "censor": false,
      "vision": false,
      "datasetProcess": true,
      "usedInClassify": true,
      "usedInExtractFields": true,
      "usedInToolCall": true,
      "usedInQueryExtension": true,
      "toolChoice": true,
      "functionCall": true,
      "defaultConfig": {}
    }
  ],
  "vectorModels": [
    {
      "model": "text-embedding-3-small",
      "name": "Embedding",
      "price": 0,
      "defaultToken": 700,
      "maxToken": 8192
    }
  ]
}

十、初始化MongoDB副本集

启动服务前，可以先启动 MongoDB：

docker compose up -d mongo

查看容器是否运行：

docker ps

进入 MongoDB 容器：

docker exec -it fastgpt-mongo mongosh -u username -p password --authenticationDatabase admin

执行副本集初始化命令：

rs.initiate({
  _id: "rs0",
  members: [
    {
      _id: 0,
      host: "mongo:27017"
    }
  ]
})

查看状态：

rs.status()

如果看到 PRIMARY 状态，说明初始化成功。

退出：

exit

十一、启动FastGPT

在 /opt/fastgpt 目录下执行：

docker compose up -d

查看所有容器：

docker ps

正常情况下，你应该能看到类似容器：

fastgpt
fastgpt-mongo
fastgpt-pg
fastgpt-sandbox

查看 FastGPT 日志：

docker logs -f fastgpt

如果没有明显报错，说明服务已经启动成功。

十二、访问FastGPT后台

浏览器访问：

http://服务器IP:3000

如果你在本地部署，则访问：

http://localhost:3000

默认管理员密码取决于配置中的：

DEFAULT_ROOT_PSW=123456

首次进入后，建议立即修改管理员密码，并配置模型密钥、知识库参数等信息。

十三、配置Nginx反向代理

生产环境中不建议直接暴露 3000 端口，可以使用 Nginx 反向代理，并配置 HTTPS。

安装 Nginx：

sudo apt install -y nginx

创建配置文件：

sudo vim /etc/nginx/conf.d/fastgpt.conf

写入：

server {
    listen 80;
    server_name fastgpt.example.com;

    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

检查配置：

sudo nginx -t

重载 Nginx：

sudo systemctl reload nginx

如果要配置 HTTPS，可以使用 Certbot：

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d fastgpt.example.com

然后将 FE_DOMAIN 修改为你的域名：

- FE_DOMAIN=https://fastgpt.example.com

修改后重启：

docker compose down
docker compose up -d

十四、常用运维命令

1. 查看服务状态

docker compose ps

2. 查看日志

docker compose logs -f

只查看 FastGPT：

docker logs -f fastgpt

3. 重启服务

docker compose restart

4. 停止服务

docker compose down

5. 更新镜像

docker compose pull
docker compose up -d

6. 备份数据

FastGPT 主要需要备份 MongoDB 和 PostgreSQL 数据目录：

tar -czvf fastgpt-backup.tar.gz mongo pg config.json docker-compose.yml

如果是生产环境，建议使用数据库自带的备份命令，例如：

mongodump
pg_dump

十五、知识库使用流程

部署完成后，可以按照以下流程创建知识库应用：

1. 登录 FastGPT 控制台；
2. 创建知识库；
3. 上传文档，例如 PDF、Markdown、Word、TXT；
4. 等待系统完成文档解析与向量化；
5. 创建 AI 应用；
6. 在应用中绑定知识库；
7. 配置提示词；
8. 测试问答效果；
9. 发布应用或接入API。

知识库问答效果与以下因素密切相关：

• 文档质量
• 切分方式
• 向量模型质量
• 检索数量
• Prompt设计
• 大模型能力
• 是否开启重排模型
• 是否进行人工标注和数据清洗

如果发现回答不准确，不一定是部署问题，更多时候需要优化知识库内容和检索策略。

十六、常见问题排查

1. FastGPT容器启动失败

查看日志：

docker logs -f fastgpt

常见原因包括：

• MongoDB连接地址错误
• PostgreSQL连接地址错误
• config.json 格式错误
• API Key 未配置
• 端口被占用

可以使用以下命令检查端口：

sudo lsof -i:3000

2. MongoDB副本集报错

如果出现副本集相关错误，确认是否执行了：

rs.initiate()

并确保 host 使用 Docker Compose 内部服务名：

host: "mongo:27017"

而不是服务器公网 IP。

3. 上传文档后一直处理中

可能原因：

• 向量模型不可用
• API Key错误
• Embedding模型名称不匹配
• 文档过大
• 网络访问模型服务失败

建议查看 FastGPT 日志，同时尝试使用较小的 TXT 文件测试。

4. 页面无法访问

检查容器是否运行：

docker ps

检查服务器安全组是否开放端口：

3000
80
443

如果使用云服务器，还需要在云厂商控制台开放对应端口。

5. 调用模型失败

检查以下配置：

OPENAI_BASE_URL
CHAT_API_KEY

以及 config.json 中的模型名称是否与服务商支持的模型名称一致。

十七、源码部署和二次开发说明

如果你不仅想运行 FastGPT，还想进行二次开发，可以使用源码方式启动。

1. 安装Node.js

推荐使用 Node.js 18 或 20。

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

查看版本：

node -v
npm -v

2. 安装pnpm

npm install -g pnpm

3. 安装依赖

进入源码目录：

cd FastGPT
pnpm install

4. 配置环境变量

通常需要复制示例环境变量文件：

cp .env.template .env.local

然后修改其中数据库、模型接口、域名等配置。

5. 启动开发服务

pnpm dev

如果项目使用 monorepo 结构，可能需要进入具体应用目录执行命令，具体以官方 README 为准。

十八、FastGPT源码结构简析

FastGPT 的源码通常采用前后端一体化或 Monorepo 方式组织。常见结构如下：

projects/
  app/
    src/
      pages/
      components/
      service/
      web/
      global/
  sandbox/
packages/
  global/
  service/
  common/

1. 前端页面

前端页面主要包括：

• 登录页面
• 应用管理页面
• 知识库管理页面
• 工作流编辑器
• 对话测试页面
• 系统配置页面

如果你需要修改界面样式、增加菜单、调整交互逻辑，通常会在 projects/app 下完成。

2. 后端接口

后端主要负责：

• 用户认证
• 应用配置
• 知识库处理
• 文件上传
• 向量检索
• 模型调用
• API发布
• 工作流执行

如果你需要接入自己的业务系统，例如企业微信、钉钉、飞书、CRM、ERP，可以重点关注接口层和工作流插件部分。

3. 公共模块

packages 中通常存放公共类型、工具函数、数据库模型、服务封装等代码。二次开发时，不建议随意修改公共模块，除非你明确知道影响范围。

十九、生产环境部署建议

如果你准备将 FastGPT 用于生产环境，建议注意以下几点。

1. 修改默认密码

不要使用示例中的：

123456

建议设置复杂密码，并定期更换。

2. 数据库独立部署

对于正式业务，建议将 MongoDB 和 PostgreSQL 单独部署，或者使用云数据库服务。这样有利于备份、扩容、监控和故障恢复。

3. 开启HTTPS

如果系统中包含企业文档、用户对话记录或内部知识库，一定要使用 HTTPS，避免数据在网络传输中泄露。

4. 做好数据备份

至少备份以下内容：

• MongoDB数据
• PostgreSQL数据
• 配置文件
• 上传文件
• docker-compose.yml

可以使用定时任务：

crontab -e

示例：

0 3 * * * tar -czf /backup/fastgpt-$(date +\%F).tar.gz /opt/fastgpt

5. 限制后台访问

如果 FastGPT 仅供公司内部使用，可以通过以下方式增强安全性：

• 使用 VPN
• Nginx IP白名单
• 防火墙限制访问
• 开启统一身份认证
• 禁止暴露数据库端口

6. 监控资源占用

可以使用：

docker stats

查看容器资源使用情况。

二十、完整部署源码汇总

为了便于复制使用，下面汇总核心文件。

1. docker-compose.yml

version: "3.8"

services:
  fastgpt:
    image: ghcr.io/labring/fastgpt:latest
    container_name: fastgpt
    restart: always
    ports:
      - "3000:3000"
    depends_on:
      - mongo
      - pg
      - sandbox
    environment:
      - FE_DOMAIN=http://localhost:3000
      - DEFAULT_ROOT_PSW=123456
      - MONGODB_URI=mongodb://username:password@mongo:27017/fastgpt?authSource=admin
      - PG_URL=postgresql://postgres:postgres@pg:5432/postgres
      - SANDBOX_URL=http://sandbox:3000
      - OPENAI_BASE_URL=https://api.openai.com/v1
      - CHAT_API_KEY=sk-xxxxxxx
    volumes:
      - ./config.json:/app/data/config.json
    networks:
      - fastgpt

  mongo:
    image: mongo:5.0
    container_name: fastgpt-mongo
    restart: always
    command: mongod --keyFile /data/mongodb.key --replSet rs0
    environment:
      - MONGO_INITDB_ROOT_USERNAME=username
      - MONGO_INITDB_ROOT_PASSWORD=password
    volumes:
      - ./mongo/data:/data/db
      - ./mongo/mongodb.key:/data/mongodb.key
    networks:
      - fastgpt

  pg:
    image: ankane/pgvector:v0.5.1
    container_name: fastgpt-pg
    restart: always
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=postgres
    volumes:
      - ./pg/data:/var/lib/postgresql/data
    networks:
      - fastgpt

  sandbox:
    image: ghcr.io/labring/fastgpt-sandbox:latest
    container_name: fastgpt-sandbox
    restart: always
    networks:
      - fastgpt

networks:
  fastgpt:
    driver: bridge

2. config.json

{
  "systemEnv": {
    "openapiPrefix": "fastgpt",
    "vectorMaxProcess": 15,
    "qaMaxProcess": 15,
    "tokenWorkers": 30,
    "pgHNSWEfSearch": 100
  },
  "llmModels": [
    {
      "model": "gpt-4o-mini",
      "name": "GPT-4o Mini",
      "maxContext": 125000,
      "maxResponse": 16000,
      "quoteMaxToken": 120000,
      "maxTemperature": 1.2,
      "charsPointsPrice": 0,
      "censor": false,
      "vision": true,
      "datasetProcess": true,
      "usedInClassify": true,
      "usedInExtractFields": true,
      "usedInToolCall": true,
      "usedInQueryExtension": true,
      "toolChoice": true,
      "functionCall": true,
      "defaultConfig": {}
    }
  ],
  "vectorModels": [
    {
      "model": "text-embedding-3-small",
      "name": "Embedding-3-Small",
      "price": 0,
      "defaultToken": 700,
      "maxToken": 8192
    }
  ],
  "reRankModels": [],
  "audioSpeechModels": [],
  "whisperModel": {
    "model": "whisper-1",
    "name": "Whisper",
    "charsPointsPrice": 0
  }
}

二十一、总结

本文完整介绍了 FastGPT 的 Docker 部署流程，包括环境准备、Docker 安装、源码获取、docker-compose.yml 编写、config.json 配置、MongoDB 副本集初始化、服务启动、Nginx 反向代理、常见问题排查以及源码二次开发说明。

对于个人开发者来说，FastGPT 是学习 RAG、知识库问答、AI应用编排的优秀项目；对于企业来说，它也具备较强的私有化部署价值。通过 Docker Compose，你可以在较短时间内搭建一套完整的 AI 知识库平台，并基于自身业务继续扩展。

最后建议：正式上线前一定要修改默认密码、配置 HTTPS、做好数据库备份，并根据实际模型服务商调整模型配置。FastGPT 的部署并不复杂，真正影响使用效果的关键往往在于知识库整理、Prompt设计、检索参数调优以及模型选择。