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

部署前先明确适用场景

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

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

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

登录服务器后，先更新软件索引并安装常用依赖。可执行：

，随后安装证书、下载工具和解压工具：。如果服务器此前安装过旧版 Docker，建议先清理旧包，避免版本冲突。

安装 Docker 推荐使用官方仓库方式。添加密钥与源后，执行：

。安装完成后用 和 检查版本。为了让普通用户直接执行 Docker 命令，可运行 ，然后重新登录终端。

第二步：获取 FastGPT 部署文件

进入计划存放服务的目录，例如：

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

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

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

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

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

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

在部署目录执行：

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

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

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

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

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

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

常见问题与排查思路

页面能打开但问答失败，优先检查模型接口地址、密钥和模型名称是否正确，再查看应用日志中的返回码。文档上传成功但无法检索，多数与向量模型配置、切片任务失败或数据库扩展异常有关。容器反复重启时，可执行

定位错误，常见原因包括端口占用、配置格式错误、磁盘空间不足和数据库未完成初始化。

升级时不要直接覆盖旧目录。稳妥做法是先备份 compose 文件、配置文件、数据库数据卷和上传目录，再阅读新版本变更说明。升级命令通常是

，但如果涉及数据库结构变化，应按官方迁移步骤执行。回滚时恢复旧镜像版本和备份数据，避免新旧版本混用造成数据不可读。

安全边界与运维建议

生产环境不要把数据库端口直接暴露到公网，只开放必要的 Web 访问端口。后台入口应设置强密码，并限制管理员数量。模型接口密钥属于敏感凭据，不能写在前端页面、公开文档或截图中。涉及客户资料、合同、研发文档等内容时，应先确认数据使用范围和保留周期，必要时做脱敏处理。

日常运维建议每周检查一次磁盘、容器状态和错误日志；每次大批量导入文档前先做小样本测试；每次升级前先在测试环境验证。FastGPT 部署并不复杂，真正影响体验的是模型质量、知识库整理方式和检索参数。先跑通最小可用流程，再逐步优化配置，通常比一次性堆满功能更稳定。