Cecil Fast - 自研全平台加速器服务 | 高速稳定全球网络访问返回首页

FastGPT本地部署教程:Docker快速安装、模型配置与故障排查

更新于 2026-11-09 · cecil.buzz

简答:FastGPT本地部署,新手优先选择Docker Compose,不要一开始走源码开发。准备Docker、Compose和可用的模型服务后,获取官方compose配置,启动容器并访问localhost:3000;如果使用4.17.0及以上版本,还要核对AI Proxy配置。本文给出快速体验路线、源码开发路线、配置要点和常见故障处理顺序。

定义:FastGPT本地部署,是把FastGPT及其数据库、向量库、模型代理等组件运行在自己的电脑或服务器上,通常分为Docker Compose部署和源码本地开发两种方式。

先选路线:Docker部署还是源码开发?

如果目标是先把FastGPT跑起来并使用知识库,优先选择Docker Compose;如果目标是修改源码、调试页面或开发功能,再选择源码本地开发。两条路线的依赖和操作不要混用。

路线适合场景主要准备起步方式成功判据
Docker Compose个人体验、测试、部署到服务器Docker、Docker Compose、模型服务、磁盘空间获取官方compose文件或运行安装脚本容器正常运行,可访问http://localhost:3000并完成登录
源码本地开发修改FastGPT代码、开发插件、调试功能Git、Docker、Node.js 20或更高版本、pnpm 10.xFork并克隆代码,再启动开发依赖依赖安装完成,执行pnpm dev后页面可访问

官方本地开发文档建议在Linux、macOS或Windows WSL环境中进行,并列出Git、Docker、Node.js 20及以上版本和pnpm 10.x等依赖。查看FastGPT本地开发文档

先做一个停止判断:如果你只是想使用FastGPT,不需要修改源码,就不要先安装Node.js和pnpm,直接进入Docker Compose路线。

Docker Compose本地部署步骤

1. 准备系统环境

官方Docker文档当前将Linux、macOS和Windows WSL列为可执行环境。Windows用户建议使用WSL 2后端,并尽量把项目和数据放在Linux文件系统中,避免文件挂载带来的权限或性能问题。查看Docker Compose部署要求

先确认Docker命令可用:

docker -v
docker compose version

如果任一命令无法执行,先修复Docker环境,不要继续下载FastGPT配置。

2. 选择向量数据库

新手体验通常可以先选择PgVector方案。官方文档说明,PgVector适合向量规模在5000万以下的知识库;Milvus更适合更大规模场景,但其版本和资源要求需要单独核对。查看向量数据库与配置说明

3. 获取配置并生成密码

在Linux、macOS或Windows WSL中,可以使用官方交互式脚本生成配置:

FASTGPT_DEPLOY_BASE_URL=https://doc.fastgpt.cn bash <(curl -fsSL https://doc.fastgpt.cn/deploy/install.sh)

脚本会引导选择部署环境和向量库,并生成docker-compose.yml、root登录密码、服务Token及其他组件凭证。命令执行完成后,立即把终端输出的root密码和生成的compose文件保存到安全位置。

如果需要固定使用某个配置文件,也可以采用手动方式:

curl -fsSL https://doc.fastgpt.cn/deploy/docker/main/cn/docker-compose.pg.yml -o docker-compose.source.yml
curl -fsSL https://doc.fastgpt.cn/deploy/install.sh -o install.sh
FASTGPT_LOCAL_COMPOSE_PATH=./docker-compose.source.yml bash install.sh

以上命令适用于官方文档当前列出的PgVector中国大陆镜像源配置。版本、镜像地址和文件路径可能调整,执行前应再次打开官方Docker文档核对。

4. 启动容器并访问页面

进入docker-compose.yml所在目录,执行:

docker compose --profile prepull pull
docker compose up -d
docker compose ps

默认主服务宿主机端口通常为3000,成功启动后访问http://localhost:3000。如果部署在服务器上,应使用服务器地址和实际映射端口,不要把容器内部地址直接填入浏览器。

如果页面打不开,先执行docker compose ps确认容器状态,再执行docker compose logs --tail=200查看启动日志。若容器持续重启,应先停止继续配置模型,优先处理日志中的数据库、环境变量或端口错误。

模型、AI Proxy与访问地址怎么配置

FastGPT不是只启动一个前端容器。官方架构说明中,MongoDB用于存储非向量数据,PostgreSQL、Milvus、OceanBase或SeekDB等组件用于向量数据,AI Proxy负责模型请求代理和管理员渠道管理。查看官方部署架构说明

AI Proxy配置

从FastGPT 4.17.0起,官方文档要求部署或接入AI Proxy,并在FastGPT容器中配置:

AIPROXY_API_ENDPOINT=http://aiproxy:3000
AIPROXY_API_TOKEN=你的管理员Token

AIPROXY_API_ENDPOINT填写AI Proxy服务根地址,不要额外附加/v1;AIPROXY_API_TOKEN不能为空,并且需要与AI Proxy服务端的管理员凭证一致。官方文档明确说明,单独配置OPENAI_BASE_URL和CHAT_API_KEY不能替代这两个变量。查看AI Proxy环境变量要求

三类模型不要混淆

  • 语言模型:用于对话、内容生成和问答回复。
  • 索引模型:用于把文档切分并建立知识库索引,通常与向量模型配置相关。
  • 向量模型:用于生成向量并支持知识库检索。没有配置时,可能出现对话正常但知识库没有索引进度。

模型配置完成后,先用一段短文本测试对话,再上传小文件测试索引,最后再导入完整资料。这样可以区分模型连接问题、向量模型问题和文档处理问题。

域名、端口与沙盒地址

如果只在本机体验,通常先验证3000端口即可;如果通过域名访问,应把FE_DOMAIN设置为用户实际访问的完整地址,不能填写容器内部地址。启用Agent或Skill沙盒时,还要按实际版本核对沙盒WebSocket地址;4.16及以上版本还涉及沙盒预览地址。端口和地址属于部署配置,不能直接照搬其他机器的值。

官方文档当前列出主服务默认宿主机端口为3000,S3服务端口为9000,Sandbox Proxy默认宿主机端口为3006,MCP服务为3003。不需要的服务不要盲目开放端口,应以实际compose文件和业务需求为准。查看端口与域名配置说明

常见部署失败怎么排查

端口被占用

表现为容器启动失败或日志出现端口绑定错误。先检查宿主机端口是否已被其他程序使用,再修改compose中的映射端口,格式是“宿主机端口:容器端口”。不要随意修改容器内部端口;修改后重新执行docker compose up -d。官方FAQ也说明,桥接网络下通常是映射端口冲突,而不是容器运行端口冲突。查看端口冲突说明

Mongo无法启动或反复重启

先执行docker compose logs mongo查看日志。官方文档提到,部分旧设备可能因CPU不支持AVX指令集导致Mongo启动失败,这时需要根据实际compose版本和硬件情况调整Mongo版本;不要直接删除数据目录。若已经产生数据,先备份挂载目录,再尝试配置修改。

页面能打开但无法对话

  1. 先查看FastGPT容器日志,确认AI Proxy地址和Token是否存在。
  2. 确认语言模型渠道已启用,模型密钥和接口地址可访问。
  3. 再检查向量模型是否配置;对话正常但索引没有进度,官方FAQ将未配置向量模型列为常见原因。
  4. 如果页面崩溃,关闭浏览器翻译功能,并检查配置文件是否正确加载。

页面可以回复但API测试失败时,官方FAQ提醒页面使用stream=true模式,接口测试也应按模型兼容性检查流式参数。查看官方常见问题排查

登录密码忘记

当前部署生成的root密码应以安装脚本终端输出为准。若已忘记,官方FAQ提供了命令行重置方式:

docker compose exec fastgpt-app node /app/scripts/reset-root-password.cjs '新密码'

执行前确认服务名称与当前compose文件一致;如果服务名不同,先用docker compose ps确认。

部署完成后的保存与验收清单

完成首次登录后,不要立即删除配置文件或数据目录。建议按以下顺序验收:

  1. 容器状态:执行docker compose ps,确认核心服务没有持续重启。
  2. 页面访问:打开实际访问地址,确认登录、退出和再次登录均正常。
  3. 模型测试:用短问题验证语言模型回复,再测试向量模型。
  4. 知识库测试:上传小型文档,确认能够完成索引并检索到内容。
  5. 数据持久化:确认Mongo、向量库和对象存储对应的数据目录已挂载到宿主机。
  6. 密码保存:保存root密码、AI Proxy Token、数据库密码和生成后的compose文件。
  7. 升级前备份:先查看对应版本的升级说明,备份数据和配置,不要直接跨多个版本升级。

如果只是个人体验,到“页面可登录、模型可回复、知识库可完成一次索引”即可停止扩展配置;如果用于团队或长期服务,再继续配置域名、反向代理、备份、访问控制和监控。

常见问题

FastGPT本地部署一定要源码编译吗?

不需要。只想使用FastGPT时,优先选择Docker Compose;只有需要修改源码、开发功能或调试项目时,才需要安装Git、Node.js和pnpm并走源码开发路线。

Windows可以本地部署FastGPT吗?

可以,但应按官方文档使用Windows WSL或WSL 2后端运行Docker。项目和数据尽量放在Linux文件系统中,减少文件挂载、权限和性能问题。

FastGPT启动后为什么打不开localhost:3000?

先执行docker compose ps确认容器是否运行,再执行docker compose logs --tail=200查看日志。重点检查3000端口是否被占用、容器是否持续重启、FE_DOMAIN是否填写错误,以及数据库是否初始化失败。

FastGPT 4.17.0及以上版本还要配置什么?

根据当前官方部署文档,从4.17.0起需要部署或接入AI Proxy,并配置AIPROXY_API_ENDPOINT和AIPROXY_API_TOKEN。具体变量名和要求应以实际版本文档及compose文件为准。

为什么可以对话,但知识库没有索引进度?

优先检查向量模型是否已配置并启用,再查看FastGPT日志和模型接口状态。官方FAQ将未配置向量模型列为“对话正常但索引没有进度”的常见原因。

相关阅读

参考资料

  1. FastGPT官方文档:Docker Compose部署
  2. FastGPT官方文档:本地开发
  3. FastGPT官方文档:通用问题排查
  4. FastGPT技术中心:Docker版本部署配置与三种部署方法
  5. FastGPT开源仓库:Docker部署文档