FastGPT在Ubuntu服务器上从下载安装到运行的完整安装指南以及性能优化参数

时间：2026-07-18 06:30

FastGPT适合在Ubuntu服务器上以容器方式部署，安装前需准备Docker、配置文件和模型接口。部署后应重点优化内存、连接数、上传限制、向量检索参数与访问安全。

部署前先明确适用场景

FastGPT 是面向知识库问答、智能客服、企业内部助手和工作流编排的 AI 应用平台。它通常需要与大模型接口、向量数据库、文档解析服务等组件配合使用。对于中小团队，使用 Ubuntu 服务器加 Docker Compose 部署是维护成本较低的方式；对于访问量较高的生产环境，则建议把数据库、对象存储、模型接口服务拆分到独立实例，避免所有压力集中在一台机器上。

FastGPT 从下载安装到运行：Ubuntu 服务器安装教程，附性能优化参数

推荐服务器配置为 2 核 4GB 起步，仅用于测试和少量知识库体验；生产环境建议 4 核 8GB 以上，并预留足够磁盘空间用于文档、索引和日志。系统建议选择 Ubuntu 22.04 LTS 或 24.04 LTS，保持软件源可用、时间同步正常，并准备一个具有 sudo 权限的普通用户，避免长期使用 root 直接操作。

第一步：更新系统并安装基础组件

登录服务器后，先更新软件索引并安装常用依赖。可执行：sudo apt update && sudo apt upgrade -y，随后安装证书、下载工具和解压工具：sudo apt install -y ca-certificates curl gnupg lsb-release git unzip。如果服务器此前安装过旧版 Docker，建议先清理旧包，避免版本冲突。

安装 Docker 推荐使用官方仓库方式。添加密钥与源后，执行：sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin。安装完成后用 docker version 和 docker compose version 检查版本。为了让普通用户直接执行 Docker 命令，可运行 sudo usermod -aG docker $USER，然后重新登录终端。

第二步：获取 FastGPT 部署文件

进入计划存放服务的目录，例如：mkdir -p /opt/fastgpt && cd /opt/fastgpt。从官方项目仓库获取部署文件，建议优先查看对应版本的 release 说明，不要随意混用不同版本的 compose 文件和环境变量。常见目录中会包含 docker-compose.yml、config.json、环境变量示例文件以及数据库初始化相关配置。

如果是生产用途，不建议直接使用示例密码。需要在启动前修改数据库账号、服务访问密钥、管理后台初始信息、模型接口地址等配置。配置文件中凡是涉及 token、secret、password 的字段，都应使用随机强密码，并保存到团队内部安全文档中。不要把含有密钥的配置文件提交到公开代码仓库。

第三步：配置模型接口与基础参数

FastGPT 本身不是大模型，它需要连接可用的模型服务。配置时重点关注三个位置：聊天模型、向量模型和重排模型。聊天模型用于生成回答，向量模型用于知识库切片后的语义索引，重排模型用于提高检索结果排序质量。测试环境可以先只配置聊天模型和向量模型，待流程跑通后再加入重排能力。

在配置文件中，应确认 API 地址、模型名称、密钥、最大上下文长度和超时时间是否与实际服务一致。若模型接口响应较慢，可适当提高请求超时，例如设置为 120 秒；若并发不高，不要盲目把并发数调得过大，否则容易造成请求堆积。知识库文档较多时，还要关注文件上传大小限制、切片长度和向量批处理数量。

第四步：启动服务并检查状态

在部署目录执行：docker compose pull 拉取镜像，再执行：docker compose up -d 启动服务。启动后使用 docker compose ps 查看各容器状态，使用 docker compose logs -f 观察日志。如果发现数据库连接失败，多数是账号、密码、服务名或端口配置不一致；如果页面打不开，需要检查容器端口映射、服务器安全组和本机防火墙规则。

首次访问时，通过浏览器打开服务器 IP 加映射端口，完成初始化配置。建议先创建一个测试知识库，上传少量 PDF、Word 或文本文件，观察解析、切片、索引和问答是否正常。不要一开始就导入大量业务资料，否则排查问题会变得困难。

第五步：性能优化参数建议

FastGPT 的性能瓶颈通常出现在四个环节：文档解析、向量入库、模型接口响应和数据库查询。单机部署时，建议给 Docker 设置合理资源上限，避免某个容器占满内存导致整机不可用。例如数据库容器优先保证内存，应用容器根据访问量分配 CPU。若服务器内存只有 4GB，应开启 swap 作为兜底，但不能把它当作性能手段。

知识库参数方面，切片长度可从 500 到 800 字左右开始测试，重叠长度控制在 80 到 150 字之间。切片太短会增加向量数量和检索成本，切片太长会降低命中精度。topK 可从 5 到 8 开始，重排后保留 3 到 5 段进入模型上下文。若回答经常遗漏信息，可适当提高 topK；若回答变慢或内容发散，则应减少召回数量并优化文档结构。

应用参数方面，可把接口超时设置在 60 到 180 秒之间，具体取决于模型服务速度。上传大文件时，需同步调整反向袋里、应用配置和解析服务的大小限制。数据库方面，应定期清理无用知识库、历史测试文件和过期日志。高并发场景下，不建议单机硬撑，应把数据库、对象存储和应用服务分离，并为应用层增加多个副本。

常见问题与排查思路

页面能打开但问答失败，优先检查模型接口地址、密钥和模型名称是否正确，再查看应用日志中的返回码。文档上传成功但无法检索，多数与向量模型配置、切片任务失败或数据库扩展异常有关。容器反复重启时，可执行 docker compose logs 服务名 定位错误，常见原因包括端口占用、配置格式错误、磁盘空间不足和数据库未完成初始化。

升级时不要直接覆盖旧目录。稳妥做法是先备份 compose 文件、配置文件、数据库数据卷和上传目录，再阅读新版本变更说明。升级命令通常是 docker compose pull && docker compose up -d，但如果涉及数据库结构变化，应按官方迁移步骤执行。回滚时恢复旧镜像版本和备份数据，避免新旧版本混用造成数据不可读。