FastGPT Docker 部署教程｜零基础可学

前言

FastGPT 是一个基于大语言模型的知识库问答与 AI 应用编排平台，适合用来搭建企业内部知识库、客服机器人、文档问答系统、AI 助手以及各种基于工作流的智能应用。对于零基础用户来说，最容易上手的部署方式通常不是源码编译，而是使用 Docker。

Docker 的好处是：环境隔离、安装简单、迁移方便、版本可控。你不需要手动安装 Node.js、MongoDB、PostgreSQL、向量数据库等复杂依赖，只需要准备好服务器、安装 Docker 和 Docker Compose，然后按照配置文件启动即可。

本文将以“零基础可学”为目标，从服务器准备、Docker 安装、FastGPT 配置、启动服务、访问后台、常见问题排查等方面，完整讲解 FastGPT 的 Docker 部署流程。即使你之前没有接触过 Linux 和 Docker，也可以按照步骤一步一步完成部署。

一、部署前需要准备什么

在开始之前，我们先明确需要准备的内容。

1. 一台服务器

建议使用 Linux 服务器，例如：

• Ubuntu 20.04 / 22.04
• Debian 11 / 12
• CentOS 7 / Rocky Linux / AlmaLinux
• 其他主流 Linux 发行版

如果你只是测试学习，最低配置可以参考：

如果用于正式生产环境，建议：

FastGPT 本身并不是特别吃硬件，但如果你的知识库文档较多、并发用户较多，或者需要本地部署大模型，就需要更高配置。一般来说，如果模型调用使用 OpenAI、Azure、智谱、通义千问、DeepSeek 等外部 API，服务器压力会小很多。

2. 一个域名，可选但推荐

如果你只是本地测试，可以直接使用服务器 IP 访问。

如果你准备长期使用，建议准备一个域名，例如：

fastgpt.example.com

然后将域名解析到服务器公网 IP。后续如果配置 HTTPS，也会更方便。

3. 一个可用的大模型 API Key

FastGPT 本身是应用平台，需要连接大语言模型才能完成对话、知识库问答等能力。你可以准备以下任意一种模型服务：

• OpenAI API
• Azure OpenAI
• DeepSeek API
• 智谱 AI
• 通义千问
• Moonshot / Kimi
• 火山方舟
• 本地部署的 OpenAI 兼容接口

不同模型平台的配置方式略有差异，但核心都是在 FastGPT 的配置文件中填写接口地址、模型名称和 API Key。

二、连接服务器

如果你使用的是云服务器，通常可以通过 SSH 登录。

在本地电脑打开终端，输入：

ssh root@你的服务器IP

例如：

ssh root@123.123.123.123

如果你的服务器不是 root 用户，也可以使用普通用户登录：

ssh ubuntu@你的服务器IP

登录成功后，建议先更新系统软件包。

Ubuntu / Debian 系统执行：

sudo apt update
sudo apt upgrade -y

CentOS / Rocky Linux 系统执行：

sudo yum update -y

为了让教程更容易统一，下面主要以 Ubuntu 22.04 为例进行说明。

三、安装 Docker

Docker 是本次部署的核心工具。我们先安装 Docker。

1. 卸载旧版本 Docker

如果服务器之前安装过旧版本 Docker，可以先执行：

sudo apt remove docker docker-engine docker.io containerd runc -y

如果提示某些包不存在，不用担心，继续下一步即可。

2. 安装基础依赖

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

3. 添加 Docker 官方 GPG 密钥

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

4. 添加 Docker 软件源

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

5. 安装 Docker Engine

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

6. 验证 Docker 是否安装成功

docker version

如果能看到 Docker Client 和 Docker Server 的版本信息，说明安装成功。

再执行：

docker compose version

如果能看到 Docker Compose 版本号，也说明 Compose 插件安装成功。

四、创建 FastGPT 部署目录

我们建议将 FastGPT 的部署文件统一放到 /opt/fastgpt 目录中。

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

如果你当前不是 root 用户，后续操作可能需要加 sudo。为了方便，也可以将当前用户加入 docker 用户组：

sudo usermod -aG docker $USER

执行后需要重新登录 SSH，用户组权限才会生效。

五、准备 Docker Compose 配置

FastGPT 通常需要依赖以下组件：

• FastGPT 主服务
• MongoDB 数据库
• PostgreSQL 数据库
• 向量检索相关服务，例如 pgvector
• Sandbox 或执行器服务，可选
• OneAPI / New API 等模型转发服务，可选

实际部署方式会随着 FastGPT 官方版本变化而变化。因此，最推荐的方法是使用官方提供的 docker-compose.yml 示例文件，然后根据自己的模型服务进行修改。

你可以从 FastGPT 官方仓库获取最新配置。一般流程如下：

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

如果服务器没有安装 Git，可以先安装：

sudo apt install -y git

进入项目目录后，查找 Docker 部署相关文件：

cd FastGPT
ls

通常官方会提供类似 docker-compose.yml、config.json、.env 或 projects/app/data/config.json 一类配置文件。由于不同版本目录可能变化，建议以官方仓库当前说明为准。

如果你不想克隆完整仓库，也可以在本地浏览官方文档，复制对应版本的 Docker Compose 配置到服务器。

六、理解核心配置项

在正式启动之前，建议先理解几个关键配置。很多部署失败问题都来自配置项填写错误。

1. 数据库配置

FastGPT 会使用数据库保存用户、应用、知识库、对话记录等数据。Docker Compose 通常会自动启动数据库容器，并通过容器网络连接。

常见配置类似：

MONGODB_URI: mongodb://username:password@mongo:27017/fastgpt
PG_URL: postgresql://username:password@postgres:5432/fastgpt

这里需要注意：

• mongo 和 postgres 通常是 Docker Compose 里的服务名，不是服务器公网 IP。
• 用户名和密码要与数据库容器中的环境变量保持一致。
• 不建议在生产环境使用过于简单的密码，例如 123456。

2. 模型配置

FastGPT 需要调用大模型接口。很多平台现在都兼容 OpenAI API 格式，因此可以使用类似配置：

{
  "model": "gpt-4o-mini",
  "name": "GPT-4o Mini",
  "avatar": "/imgs/model/openai.svg",
  "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": {}
}

如果你使用 DeepSeek，模型名可能是：

deepseek-chat

如果你使用通义千问，模型名可能是：

qwen-plus

如果你使用本地模型平台，只要它提供 OpenAI 兼容接口，通常也可以接入。

3. API 地址

常见的 OpenAI 兼容接口格式是：

https://api.openai.com/v1

DeepSeek 示例：

https://api.deepseek.com/v1

本地模型服务示例：

http://你的服务器IP:8000/v1

需要注意：如果 FastGPT 容器内部访问宿主机服务，不能总是直接使用 127.0.0.1，因为容器里的 127.0.0.1 指的是容器自己，不是宿主机。可以考虑使用：

host.docker.internal

或者将模型服务也放到同一个 Docker Compose 网络中。

4. API Key

API Key 是模型服务的访问凭证，例如：

sk-xxxxxxxxxxxxxxxx

一定不要将真实 API Key 公开到 GitHub、博客、截图或公共文档中。

七、启动 FastGPT

当配置文件准备完成后，在 docker-compose.yml 所在目录执行：

docker compose up -d

这个命令的意思是：在后台启动所有服务。

第一次启动时，Docker 会自动拉取镜像。根据服务器网络情况，可能需要几分钟到十几分钟。如果拉取镜像较慢，可以配置 Docker 镜像加速器，或者更换网络环境。

启动完成后，查看容器状态：

docker compose ps

如果所有服务都显示 running 或 healthy，说明启动基本正常。

查看日志：

docker compose logs -f

如果只想查看 FastGPT 主服务日志，可以执行：

docker compose logs -f fastgpt

具体服务名以你的 docker-compose.yml 为准。

八、访问 FastGPT 页面

假设 FastGPT 映射到了服务器的 3000 端口，你可以在浏览器访问：

http://你的服务器IP:3000

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

https://fastgpt.example.com

首次访问时，通常需要注册管理员账号或使用默认初始化账号。不同版本的 FastGPT 初始化方式可能略有差异，请以官方文档为准。

进入后台后，可以重点检查以下内容：

1. 是否能正常登录；
2. 是否能创建应用；
3. 是否能配置模型；
4. 是否能创建知识库；
5. 是否能上传文档；
6. 是否能正常发起对话；
7. 知识库问答是否能返回引用内容。

如果这些流程都正常，说明 FastGPT 已经部署成功。

九、配置 Nginx 反向代理

如果你希望通过域名访问，并启用 HTTPS，建议使用 Nginx 反向代理。

1. 安装 Nginx

sudo apt install -y nginx

2. 创建站点配置

新建配置文件：

sudo nano /etc/nginx/sites-available/fastgpt

写入以下示例：

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;

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

将 fastgpt.example.com 替换成你的真实域名。

启用站点：

sudo ln -s /etc/nginx/sites-available/fastgpt /etc/nginx/sites-enabled/

检查配置：

sudo nginx -t

重载 Nginx：

sudo systemctl reload nginx

现在你可以通过域名访问：

http://fastgpt.example.com

十、配置 HTTPS 证书

推荐使用 Certbot 免费申请 Let’s Encrypt 证书。

1. 安装 Certbot

sudo apt install -y certbot python3-certbot-nginx

2. 申请证书

sudo certbot --nginx -d fastgpt.example.com

按照提示输入邮箱、同意协议，并选择是否自动跳转 HTTPS。

完成后访问：

https://fastgpt.example.com

如果可以正常打开，说明 HTTPS 配置成功。

3. 检查证书自动续期

sudo certbot renew --dry-run

如果没有报错，证书会自动续期。

十一、FastGPT 基础使用流程

部署完成后，我们简单了解一下 FastGPT 的基本使用方式。

1. 创建模型配置

进入管理后台后，首先确认模型是否可用。你需要配置：

• 模型名称
• API 地址
• API Key
• 上下文长度
• 回复长度
• 是否支持工具调用
• 是否支持视觉能力
• 是否用于知识库处理

如果模型配置错误，最常见的问题是对话时报错，或者知识库索引失败。

2. 创建知识库

知识库是 FastGPT 的核心能力之一。你可以上传：

• PDF 文档
• Word 文档
• Markdown 文件
• TXT 文本
• Excel 表格
• 网页内容
• FAQ 问答数据

上传后，系统会对文档进行分段、向量化和索引。用户提问时，FastGPT 会先从知识库中检索相关内容，再交给大模型生成回答。

3. 创建 AI 应用

FastGPT 支持创建多种 AI 应用，例如：

• 简单聊天机器人
• 知识库问答助手
• 客服机器人
• 工作流应用
• 数据提取工具
• 多轮表单助手

对于新手，建议先创建一个“知识库问答”应用，把刚刚创建的知识库关联进去，然后测试提问效果。

4. 调试问答效果

如果回答质量不理想，可以从以下方面优化：

• 文档内容是否清晰；
• 文档分段是否合理；
• 向量模型是否可用；
• 检索数量是否合适；
• 提示词是否明确；
• 模型能力是否足够；
• 问题是否与知识库内容相关。

知识库问答不是简单地“上传文档就完美回答”，实际效果往往需要持续调优。

十二、常见问题与解决方法

1. Docker 镜像拉取失败

可能原因：

• 服务器网络无法访问镜像仓库；
• Docker Hub 访问慢；
• 镜像名称或版本写错。

解决方法：

docker compose pull

如果仍然失败，可以配置镜像加速器，或检查官方镜像地址是否变化。

2. 容器启动后马上退出

查看日志：

docker compose logs -f

重点检查：

• 环境变量是否缺失；
• 数据库连接是否失败；
• 端口是否被占用；
• 配置文件 JSON 格式是否错误；
• 镜像版本是否不匹配。

3. 页面打不开

先检查容器是否运行：

docker compose ps

再检查端口是否监听：

sudo ss -tulnp | grep 3000

如果使用云服务器，还要检查安全组是否放行端口。例如你使用 3000 端口访问，就需要在云厂商控制台放行 TCP 3000。

如果使用 Nginx 反向代理，还需要检查：

sudo nginx -t
sudo systemctl status nginx

4. 对话时报模型错误

常见原因：

• API Key 填错；
• API 地址填错；
• 模型名不存在；
• 模型账户余额不足；
• 模型服务不支持当前参数；
• 网络无法访问模型服务。

可以在服务器中使用 curl 测试模型接口。例如 OpenAI 兼容接口通常可以这样测试：

curl https://api.example.com/v1/models \
  -H "Authorization: Bearer 你的APIKey"

如果这个请求都失败，FastGPT 里大概率也无法正常调用。

5. 上传知识库后无法索引

可能原因：

• 向量模型没有配置；
• 文档解析服务异常；
• 文件过大；
• 数据库连接异常；
• 模型接口超时；
• 后台任务队列异常。

建议查看 FastGPT 服务日志，并先用小文档测试，例如上传一个简单的 TXT 文件，确认基础流程正常后再上传大型 PDF。

十三、数据备份建议

部署成功后，不要忽视备份。FastGPT 的核心数据通常包括：

• MongoDB 数据
• PostgreSQL 数据
• 上传文件
• 配置文件
• Docker Compose 文件
• 环境变量文件

建议定期备份 /opt/fastgpt 目录以及数据库数据卷。可以先查看当前 Docker 数据卷：

docker volume ls

如果数据存放在本地目录，例如：

/opt/fastgpt/data

可以直接打包备份：

tar -czvf fastgpt-backup.tar.gz /opt/fastgpt

生产环境建议结合云盘快照、对象存储或自动备份脚本，避免服务器故障导致知识库和应用配置丢失。

十四、升级 FastGPT

升级前一定要先备份数据。

一般升级流程是：

cd /opt/fastgpt
docker compose pull
docker compose down
docker compose up -d

如果官方版本更新涉及配置文件变化，需要先阅读官方升级说明，不要盲目直接替换。尤其是数据库结构、环境变量、模型配置发生变化时，直接升级可能导致服务无法启动。

更稳妥的做法是：

1. 备份现有数据；
2. 阅读官方 Release Note；
3. 对比新的配置文件；
4. 在测试环境先升级；
5. 确认无误后再升级生产环境。

十五、安全建议

FastGPT 部署完成后，建议做一些基础安全加固。

1. 不要暴露数据库端口

MongoDB、PostgreSQL 等数据库端口不要直接暴露到公网。Docker Compose 内部服务通信即可，不需要让外部访问数据库。

2. 使用强密码

数据库密码、后台管理员密码、API Key 都要足够复杂。不要使用：

admin
123456
password
fastgpt

3. 开启 HTTPS

如果通过公网访问，建议一定配置 HTTPS，避免账号密码和会话信息明文传输。

4. 限制后台访问

如果是企业内部系统，可以考虑：

• 使用 VPN；
• 配置 IP 白名单；
• 使用云防火墙；
• 接入统一身份认证；
• 配置 Nginx Basic Auth。

5. 妥善保管 API Key

模型 API Key 一旦泄露，可能造成费用损失。建议定期检查模型平台账单，并设置合理的消费限额。

十六、总结

通过 Docker 部署 FastGPT，整体流程可以概括为：

1. 准备 Linux 服务器；
2. 安装 Docker 和 Docker Compose；
3. 获取 FastGPT 官方部署文件；
4. 修改数据库、模型和环境变量配置；
5. 使用 docker compose up -d 启动服务；
6. 通过浏览器访问 FastGPT；
7. 配置模型、知识库和 AI 应用；
8. 根据需要配置 Nginx、HTTPS、备份和安全策略。

对于零基础用户来说，FastGPT 的难点通常不在“启动容器”，而在“配置模型”和“排查日志”。只要你掌握了 Docker Compose 的基本命令，能够查看容器状态和日志，就已经具备了独立部署和维护 FastGPT 的基础能力。

最后建议：第一次部署时不要急于追求复杂架构，可以先用最小配置跑通流程。等你熟悉 FastGPT 的模型配置、知识库上传、应用创建和日志排查之后，再逐步加入域名、HTTPS、备份、监控和安全加固。这样部署过程会更稳，也更适合长期维护。