保姆级教程：用Docker Compose在本地一键部署FastGPT知识库系统

零基础极速部署FastGPT：本地知识库系统搭建全指南

在人工智能技术快速发展的今天，拥有一个私有化的智能知识库系统不再是大型企业的专利。FastGPT作为一款基于大语言模型的开源知识库问答系统，因其轻量级、易部署的特点，正成为个人开发者和技术爱好者构建专属AI助手的热门选择。本文将手把手带你完成从零开始到完整运行的FastGPT本地部署全流程，无需任何专业运维经验，只需一台普通电脑和基础命令行操作能力。

1. 环境准备：Docker与Docker Compose安装

在开始FastGPT部署前，我们需要确保本地环境已安装必要的容器化工具。Docker作为轻量级的虚拟化技术，能够将FastGPT及其依赖项打包成标准化的运行单元，彻底解决"在我机器上能跑"的环境一致性问题。

1.1 Windows系统安装指南

对于Windows 10/11用户，推荐使用WSL2（Windows Subsystem for Linux）作为运行环境：

1. 以管理员身份打开PowerShell，执行以下命令启用WSL功能：

   wsl --install

2. 重启系统后，从Microsoft Store安装Ubuntu发行版
3. 下载Docker Desktop for Windows
4. 安装时勾选"Use WSL 2 based engine"选项

提示：确保BIOS中已启用虚拟化技术（VT-x/AMD-V），可在任务管理器→性能选项卡中确认

1.2 macOS系统安装指南

Mac用户可通过Homebrew一键完成安装：

brew install --cask docker

安装完成后，从应用程序文件夹启动Docker.app，在状态栏看到鲸鱼图标即表示服务已运行。

1.3 Linux系统安装指南

主流Linux发行版可通过包管理器快速安装：

# Ubuntu/Debian sudo apt-get update && sudo apt-get install docker.io docker-compose-plugin # CentOS/RHEL sudo yum install -y yum-utils sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo sudo yum install docker-ce docker-ce-cli containerd.io sudo systemctl start docker

验证安装是否成功：

docker --version && docker compose version

2. FastGPT核心组件部署

2.1 项目结构与配置文件获取

创建项目目录并下载官方部署文件：

mkdir fastgpt && cd fastgpt curl -O https://raw.githubusercontent.com/labring/FastGPT/main/files/deploy/fastgpt/docker-compose.yml curl -O https://raw.githubusercontent.com/labring/FastGPT/main/projects/app/data/config.json

关键配置文件说明：

• docker-compose.yml：定义服务组件和网络配置
• config.json：系统行为参数和模型设置

2.2 服务配置调整

修改docker-compose.yml中的关键环境变量：

environment: - OPENAI_BASE_URL=http://localhost:3000/v1 # API基础路径 - CHAT_API_KEY=sk-your-api-key-here # 访问密钥 - DEFAULT_ROOT_PSW=yourpassword123 # 管理员密码

常用端口映射配置示例：

2.3 服务启动与验证

执行以下命令启动所有服务：

docker compose up -d

监控服务启动日志：

docker compose logs -f

服务健康检查：

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

预期输出应包含三个状态为"Up"的容器：fastgpt、mongo和pg。

3. 系统初始化与基础配置

3.1 首次访问设置

在浏览器中打开http://localhost:3000，使用以下默认凭证登录：

• 用户名：root
• 密码：docker-compose.yml中设置的DEFAULT_ROOT_PSW值

首次登录后建议立即：

1. 修改管理员密码
2. 设置SMTP邮件服务（用于用户注册验证）
3. 配置系统全局参数

3.2 知识库创建与管理

创建第一个知识库的基本流程：

1. 左侧导航栏选择"知识库"
2. 点击"新建知识库"按钮
3. 填写基础信息：
   • 名称：技术文档库
   • 类型：普通文档
   • 分词方式：智能分词
4. 上传支持的文件格式：
   • PDF/DOCX/TXT/Markdown
   • 最大支持20MB单个文件

注意：首次处理大型文档时可能需要较长时间解析，建议从少量页面开始测试

3.3 问答测试与效果优化

在"对话测试"页面，可以实时体验知识库的问答效果。为提高回答质量，可调整以下参数：

{ "temperature": 0.7, // 控制回答创造性（0-1） "max_tokens": 1000, // 回答最大长度 "top_p": 0.9, // 核采样阈值 "presence_penalty": 0.2 // 话题新鲜度奖励 }

常见优化策略：

• 增加知识库文档的覆盖范围
• 调整提示词模板
• 设置问题分类规则
• 配置回答审核流程

4. 进阶配置与性能调优

4.1 多模型支持配置

FastGPT支持通过修改配置接入不同的大模型：

1. 编辑config.json文件：

   { "model": "gpt-3.5-turbo", "models": [ {"model": "gpt-3.5-turbo", "name": "GPT-3.5"}, {"model": "gpt-4", "name": "GPT-4"} ] }

2. 重启服务使更改生效：

   docker compose restart fastgpt

4.2 系统监控与维护

建议配置的资源监控方案：

• 容器资源使用情况：

  docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

• 日志定期轮转配置：

  # 在docker-compose.yml中添加 logging: driver: "json-file" options: max-size: "10m" max-file: "3"

4.3 备份与恢复策略

关键数据备份方法：

1. 数据库定期备份：

   docker exec fastgpt_mongo_1 sh -c 'mongodump --out=/data/backup/$(date +%Y%m%d)' docker cp fastgpt_mongo_1:/data/backup ./local_backup

2. 配置文件版本控制：

   git init && git add docker-compose.yml config.json git commit -m "Initial FastGPT configuration"

恢复流程：

docker exec fastgpt_mongo_1 sh -c 'mongorestore /data/backup/20240501'

5. 常见问题排查指南

5.1 服务启动失败排查

检查步骤：

1. 验证端口冲突：

   netstat -tulnp | grep 3000

2. 查看详细错误日志：

   docker compose logs fastgpt | grep -i error

3. 检查资源限制：

   docker inspect fastgpt --format='{{.HostConfig.Memory}}'

5.2 知识库处理异常

典型问题解决方案：

5.3 性能优化建议

硬件资源配置参考：

启动参数调整示例：

docker compose up -d --scale fastgpt=2 # 启动两个实例负载均衡