FastGPT 部署完整教程｜2026最新版

前言

FastGPT 是一款面向企业和个人开发者的 AI 知识库问答与智能体编排平台，支持知识库导入、向量检索、工作流编排、多模型接入、API 调用以及企业级权限管理等能力。随着大模型应用在客服、运营、研发、售前、知识管理等场景中的普及，越来越多团队希望搭建一套属于自己的 AI 应用平台，而 FastGPT 正是一个非常适合私有化部署和二次开发的开源方案。

本文将以 2026 最新部署思路 为基础，系统介绍 FastGPT 的部署方式、服务器准备、Docker 环境安装、配置文件说明、模型接入、常见问题排查以及上线后的优化建议。无论你是第一次接触 FastGPT，还是希望将其部署到生产环境，本文都可以作为完整参考。

一、FastGPT 是什么？

FastGPT 可以理解为一个“AI 应用构建平台”。它并不只是简单地调用大模型接口，而是将知识库、向量数据库、模型服务、应用编排、插件工具和 API 能力整合到一起，让用户可以快速构建企业级 AI 应用。

常见应用场景包括：

• 企业内部知识库问答
• AI 智能客服
• 产品文档助手
• 销售话术辅助
• 研发代码知识库
• 多轮对话机器人
• 私有数据问答系统
• 工作流自动化智能体

相比单独调用 ChatGPT、Claude、通义千问、DeepSeek 等模型，FastGPT 的优势在于它提供了一整套完整的应用层能力，尤其适合需要将 AI 能力接入实际业务系统的团队。

二、部署 FastGPT 前的准备工作

在正式部署之前，建议先准备好服务器、域名、模型 API Key 以及基础运行环境。

1. 服务器配置建议

如果只是个人测试或小团队使用，可以选择较低配置的云服务器；如果用于生产环境，则建议预留更高的 CPU、内存和磁盘空间。

FastGPT 本身并不一定需要 GPU，因为它通常通过 API 调用外部大模型。如果你需要本地部署大模型，例如 Qwen、DeepSeek、Llama、Baichuan 等，则需要额外准备 GPU 服务器。

2. 操作系统建议

推荐使用主流 Linux 发行版：

• Ubuntu 22.04 LTS
• Ubuntu 24.04 LTS
• Debian 12
• CentOS Stream 9
• Rocky Linux 9

如果你是新手，推荐优先选择 Ubuntu 22.04 LTS，因为社区资料多，Docker 兼容性好，命令也相对统一。

3. 域名与 HTTPS

生产环境强烈建议准备一个域名，例如：

fastgpt.example.com

并通过 Nginx、Caddy、Traefik 或云厂商负载均衡配置 HTTPS。虽然 FastGPT 可以通过 IP 加端口访问，但如果后续要接入企业微信、飞书、钉钉、浏览器插件或外部 API，使用 HTTPS 会更加稳定和安全。

三、安装 Docker 与 Docker Compose

FastGPT 官方推荐使用 Docker Compose 部署，因为它依赖多个服务，例如 MongoDB、PostgreSQL、向量数据库、FastGPT 主服务等。使用 Docker Compose 可以大幅降低部署复杂度。

1. 更新系统软件包

以 Ubuntu 为例：

sudo apt update
sudo apt upgrade -y

2. 安装基础依赖

sudo apt install -y ca-certificates curl gnupg lsb-release

3. 安装 Docker

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

安装完成后，检查版本：

docker -v

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

Docker version 26.x.x

4. 安装 Docker Compose

新版 Docker 通常已经内置 Compose 插件，可以使用：

docker compose version

如果命令正常返回版本号，说明可以直接使用。如果没有安装，可以根据系统环境单独安装 Docker Compose 插件。

5. 配置 Docker 开机自启

sudo systemctl enable docker
sudo systemctl start docker

四、获取 FastGPT 部署文件

推荐从 FastGPT 官方 GitHub 仓库获取最新部署文件。实际部署时，请以官方仓库最新文档为准。

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

通常部署相关文件会放在 projects/app/data/config.json、docker-compose.yml 或官方提供的部署目录中。不同版本目录结构可能略有变化，建议先阅读仓库中的 README.md 和部署文档。

如果你只是希望快速启动，可以使用官方提供的 Docker Compose 示例文件，并根据自己的模型服务、数据库密码、域名等进行修改。

五、理解 FastGPT 的核心组件

在部署前，理解每个组件的作用非常重要，这样遇到问题时更容易排查。

1. FastGPT 主服务

这是平台的核心服务，负责用户界面、应用管理、知识库管理、对话逻辑、权限控制、API 调用等功能。

2. MongoDB

FastGPT 通常使用 MongoDB 存储应用配置、用户信息、知识库元数据、对话记录等结构化数据。

3. PostgreSQL / 向量数据库

FastGPT 的知识库检索需要向量能力。部分部署方案会使用 PostgreSQL 搭配向量扩展，也可能使用独立向量数据库。向量数据库负责存储文档切片后的 embedding 数据，并在用户提问时进行相似度检索。

4. 模型服务

FastGPT 本身不是大模型，它需要接入模型服务，包括：

• OpenAI
• Azure OpenAI
• DeepSeek
• 通义千问
• 智谱 GLM
• Moonshot Kimi
• 百度千帆
• 火山方舟
• 本地 Ollama
• OneAPI / New API / LiteLLM 等中转服务

其中，OneAPI、New API、LiteLLM 这类模型网关非常常见，可以统一管理多个模型渠道，并向 FastGPT 提供兼容 OpenAI 格式的接口。

六、配置 Docker Compose

下面给出一个通用部署思路。由于不同版本 FastGPT 的 Compose 文件可能有所差异，实际字段请以官方文件为准。

常见服务包括：

services:
  fastgpt:
    image: ghcr.io/labring/fastgpt:latest
    container_name: fastgpt
    restart: always
    ports:
      - "3000:3000"
    environment:
      - MONGODB_URI=mongodb://mongo:27017/fastgpt
      - TOKEN_KEY=your-token-key
      - ROOT_KEY=your-root-key
    depends_on:
      - mongo

  mongo:
    image: mongo:5.0
    container_name: fastgpt-mongo
    restart: always
    volumes:
      - ./mongo/data:/data/db

这里需要重点关注几个配置项。

1. TOKEN_KEY

TOKEN_KEY 用于系统内部 token 加密，生产环境必须设置为随机复杂字符串。不要使用示例中的默认值。

示例：

TOKEN_KEY=FastGPT_2026_random_token_key_xxxxx

2. ROOT_KEY

ROOT_KEY 通常用于初始化管理员或系统级访问。生产环境同样需要设置强密码。

示例：

ROOT_KEY=FastGPT_2026_root_key_xxxxx

3. 数据卷挂载

数据库数据必须持久化，否则容器重建后数据可能丢失。建议将 MongoDB、PostgreSQL、向量库等服务的数据目录挂载到宿主机。

例如：

volumes:
  - ./mongo/data:/data/db

生产环境还应定期备份这些目录。

七、配置模型接口

FastGPT 部署完成后，最关键的一步就是配置模型。模型配置决定了系统是否能正常对话、生成 embedding、处理知识库检索。

1. 对话模型

对话模型用于回答用户问题，例如：

• gpt-4o
• gpt-4.1
• deepseek-chat
• qwen-plus
• qwen-max
• moonshot-v1-8k
• glm-4
• doubao-pro

如果使用兼容 OpenAI 协议的模型网关，通常需要配置：

Base URL: https://your-api-domain.com/v1
API Key: sk-xxxxxxxx
Model: deepseek-chat

2. Embedding 模型

Embedding 模型用于将文档和问题转换成向量，是知识库问答的核心。常见模型包括：

• text-embedding-3-small
• text-embedding-3-large
• bge-large-zh
• bge-m3
• qwen-text-embedding
• text-embedding-v1

如果知识库主要是中文内容，建议选择中文效果较好的 embedding 模型，例如 BGE 系列或通义 embedding 模型。

3. Rerank 模型

Rerank 用于对初步召回的文档片段进行重排序，可以提升知识库问答准确率。常见模型包括：

• bge-reranker-large
• bge-reranker-v2-m3
• 部分云厂商提供的 rerank 服务

如果你对回答准确率要求较高，建议开启 rerank。

八、启动 FastGPT

配置完成后，在 Compose 文件所在目录执行：

docker compose up -d

查看容器状态：

docker compose ps

如果所有服务都是 running 或 healthy 状态，说明启动成功。

查看日志：

docker compose logs -f fastgpt

如果日志中没有明显报错，就可以通过浏览器访问：

http://服务器IP:3000

如果配置了域名和反向代理，则访问：

https://fastgpt.example.com

九、首次登录与初始化

首次访问 FastGPT 后，通常需要创建管理员账号或使用初始化密钥完成系统初始化。初始化完成后，可以进入控制台进行以下配置：

1. 创建团队或空间
2. 配置模型渠道
3. 创建知识库
4. 上传文档
5. 创建应用
6. 进行对话测试
7. 发布 API 或分享链接

建议先用少量文档测试完整流程，确认模型、embedding、向量检索和回答效果正常后，再导入大量正式文档。

十、创建知识库并测试问答

FastGPT 的知识库流程一般包括以下步骤：

1. 新建知识库

进入知识库管理页面，点击新建知识库，选择合适的知识库类型。一般文档问答场景选择普通知识库即可。

2. 上传文档

支持上传的文件类型通常包括：

• PDF
• Word
• Markdown
• TXT
• Excel
• CSV
• HTML

为了获得更好的问答效果，建议优先使用结构清晰的 Markdown、TXT 或经过整理的 Word 文档。PDF 如果排版复杂，可能会影响解析质量。

3. 设置切片规则

文档切片会影响召回效果。切片太短容易丢失上下文，切片太长又可能导致召回不精准。常见建议：

• 普通文档：每片 500 到 1000 字
• FAQ 文档：按问答对切片
• 产品手册：按标题层级切片
• 表格数据：按行或业务对象切片

4. 等待向量化完成

上传文档后，系统会调用 embedding 模型生成向量。此过程取决于文档数量、模型速度和 API 限流情况。如果任务长时间卡住，可以查看日志或检查 embedding 模型配置。

5. 测试召回效果

可以先提问一些文档中明确存在的问题，观察返回内容是否引用了正确片段。如果召回不准确，可以调整切片大小、embedding 模型、rerank 配置或文档结构。

十一、配置反向代理与 HTTPS

生产环境不建议直接暴露 3000 端口，推荐使用 Nginx 或 Caddy 反向代理。

1. Nginx 示例

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

    location / {
        proxy_pass http://127.0.0.1:3000;
        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;
    }
}

配置完成后，可以使用 Certbot 申请 HTTPS 证书：

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

2. Caddy 示例

如果你希望更简单地配置 HTTPS，可以使用 Caddy：

fastgpt.example.com {
    reverse_proxy 127.0.0.1:3000
}

Caddy 会自动申请和续期 HTTPS 证书，非常适合中小型部署。

十二、数据备份与恢复

FastGPT 一旦进入生产使用，数据备份非常重要。至少需要备份以下内容：

• MongoDB 数据
• PostgreSQL 或向量数据库数据
• 上传文件目录
• Docker Compose 配置文件
• FastGPT 配置文件
• 模型渠道配置
• 环境变量文件

1. MongoDB 备份

如果 MongoDB 运行在容器中，可以使用：

docker exec fastgpt-mongo mongodump --out /backup

也可以将备份目录挂载到宿主机，定时同步到对象存储或备份服务器。

2. 文件级备份

如果使用本地数据卷，可以直接备份部署目录：

tar -zcvf fastgpt-backup.tar.gz ./fastgpt-deploy

生产环境建议每天增量备份，每周完整备份，并定期测试恢复流程。

十三、性能优化建议

FastGPT 的性能主要受以下因素影响：

1. 模型接口响应速度
2. Embedding 模型吞吐量
3. 向量数据库检索性能
4. 文档切片数量
5. 并发用户数量
6. 服务器 CPU 和内存
7. 网络延迟

1. 使用稳定的模型网关

如果你接入多个模型供应商，建议使用 OneAPI、New API 或 LiteLLM 统一管理模型渠道。这样可以方便地做 Key 管理、用量统计、失败重试和模型切换。

2. 合理设置知识库参数

不要盲目把召回数量设置得过高。召回片段越多，模型上下文越长，响应速度越慢，费用也越高。一般可以从 5 到 10 个片段开始测试。

3. 开启 Rerank

对于企业知识库，Rerank 往往能明显提升准确率。尤其是文档数量较多、内容相似度较高时，Rerank 可以帮助模型优先读取更相关的片段。

4. 优化文档结构

AI 知识库效果并不只取决于模型，还取决于文档质量。建议将文档整理为标题清晰、层级合理、段落完整的格式。对于 FAQ 类型内容，应尽量使用“问题 + 答案”的结构。

十四、常见问题排查

1. 页面无法访问

可以依次检查：

docker compose ps
docker compose logs -f fastgpt
sudo ufw status

确认容器是否启动、端口是否开放、防火墙是否阻止访问。

2. 模型调用失败

常见原因包括：

• API Key 错误
• Base URL 配置错误
• 模型名称填写错误
• 账户余额不足
• 模型供应商限流
• 服务器无法访问外部网络

建议先使用 curl 测试模型接口是否可用，再回到 FastGPT 中配置。

3. 知识库一直向量化失败

重点检查 embedding 模型配置。很多用户会把对话模型和 embedding 模型混用，导致向量化失败。Embedding 必须使用专门的 embedding 模型。

4. 回答不准确

可以从以下方向优化：

• 更换更好的 embedding 模型
• 调整文档切片大小
• 开启 rerank
• 优化提示词
• 清理低质量文档
• 减少重复内容
• 增加标准 FAQ 数据

5. 容器重启后数据丢失

这通常是因为没有正确配置数据卷。生产环境必须将数据库和文件目录挂载到宿主机或独立存储。

十五、生产环境安全建议

FastGPT 涉及企业知识库和用户数据，生产部署时必须重视安全。

建议做到：

• 使用 HTTPS
• 设置强密码
• 不使用默认 TOKEN_KEY 和 ROOT_KEY
• 限制数据库端口外部访问
• 定期备份数据
• 定期更新镜像
• 控制管理员权限
• 配置服务器防火墙
• 不在公开仓库泄露 API Key
• 对外 API 设置访问鉴权和限流

如果是企业内部使用，还可以将 FastGPT 部署在内网环境，仅通过 VPN 或堡垒机访问。

十六、升级 FastGPT

升级前一定要先备份数据。推荐流程如下：

docker compose down
docker compose pull
docker compose up -d

升级完成后查看日志：

docker compose logs -f fastgpt

如果版本跨度较大，建议先在测试环境验证兼容性，确认知识库、应用、模型配置和用户权限都正常后，再升级生产环境。

十七、部署方案选择建议

不同用户可以根据实际情况选择不同方案。

个人用户

推荐使用单机 Docker Compose 部署，接入 DeepSeek、通义千问或 OpenAI 兼容接口即可。成本低，维护简单。

小型团队

建议使用云服务器 + Docker Compose + 域名 HTTPS + 定时备份。可以接入模型网关，统一管理多个模型供应商。

企业用户

建议使用独立数据库、对象存储、反向代理、日志监控和权限管控。对知识库准确率要求高的场景，应配置高质量 embedding 模型和 rerank 模型。

大规模场景

可以考虑 Kubernetes 部署、独立向量数据库、分布式存储、监控告警、灰度升级和多模型负载均衡。

十八、总结

FastGPT 是一个非常适合私有化部署的 AI 应用平台，它将知识库、模型调用、向量检索、应用编排和 API 发布整合到一起，能够帮助个人和企业快速搭建自己的 AI 助手系统。

部署 FastGPT 的核心流程可以概括为：

1. 准备服务器和域名
2. 安装 Docker 与 Docker Compose
3. 获取官方部署文件
4. 修改环境变量和配置文件
5. 配置 MongoDB、向量库和数据卷
6. 接入对话模型、embedding 模型和 rerank 模型
7. 启动服务并完成初始化
8. 创建知识库并测试问答效果
9. 配置 HTTPS、备份和安全策略
10. 根据业务需求持续优化性能和准确率

对于初学者来说，最容易出问题的地方通常是模型配置、embedding 配置、数据卷挂载和反向代理。只要按照本文步骤逐项检查，大多数问题都可以快速定位并解决。

如果你只是想体验 FastGPT，可以先用单机 Docker Compose 快速跑起来；如果你计划用于正式业务，则应重点关注安全、备份、监控、模型稳定性和知识库质量。随着企业 AI 应用逐渐成为标配，FastGPT 这类平台的价值会越来越明显。通过合理部署和持续优化，它完全可以成为企业内部知识管理、智能客服和业务自动化的重要基础设施。