1. FastGPT与Docker Compose部署概述

第一次接触FastGPT时，我被它强大的知识问答能力惊艳到了。作为一个基于大语言模型的系统，FastGPT能快速处理各种文本数据，构建智能问答应用。但真正让我兴奋的是，通过Docker Compose可以轻松实现一键部署，完全不需要从零搭建复杂的开发环境。

Docker Compose就像个智能管家，它能用一份配置文件（docker-compose.yml）同时管理多个容器服务。比如FastGPT需要MongoDB存常规数据、PostgreSQL存向量数据，还要搭配模型服务容器。传统部署方式得逐个安装配置，现在只需要写好docker-compose.yml，一条命令就能全搞定。

config.json则是FastGPT的核心配置文件，相当于系统的大脑。它决定了模型选择、处理并发数、数据库连接等关键参数。我遇到过不少新手卡在配置环节，其实只要掌握几个关键参数，就能轻松驾驭这个文件。比如"vectorMaxProcess"控制向量处理的并行数，数值越大处理越快，但超过服务器CPU核心数反而会拖慢速度。

2. 部署前的准备工作

2.1 环境检查与依赖安装

在开始前，建议先检查服务器配置。根据我的经验，2核4G是起步配置，如果要处理大量数据，最好准备4核8G以上。内存不足会导致MongoDB频繁崩溃，这点我踩过坑。

安装Docker和Docker Compose其实很简单。在Ubuntu上可以这样操作：

# 安装Docker
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun
systemctl enable --now docker

# 安装docker-compose
curl -L https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

Windows用户建议使用WSL 2，性能更好。安装Docker Desktop后，记得在设置里启用WSL 2后端。有个小技巧：把项目文件放在WSL的文件系统中（比如/home/yourname/），不要放在Windows的C盘，否则可能会遇到权限问题。

2.2 配置文件获取

官方提供了几种不同版本的docker-compose.yml，区别主要在于向量数据库的选择：

• docker-compose-pgvector.yml：轻量级，适合小规模应用
• docker-compose-milvus.yml：高性能，适合海量数据
• docker-compose-zilliz.yml：云端托管方案

我建议新手先用pgvector版本练手：

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

3. 配置文件深度解析

3.1 docker-compose.yml关键配置

打开docker-compose.yml，你会看到多个服务定义。重点看这几个部分：

mongo:
  image: mongo:5.0.18
  command: mongod --keyFile /data/mongodb.key --replSet rs0
  environment:
    - MONGO_INITDB_ROOT_USERNAME=myusername
    - MONGO_INITDB_ROOT_PASSWORD=mypassword

这里设置了MongoDB的初始账号密码，务必修改默认值。我见过太多人用默认密码导致的安全问题。command参数启用了副本集模式，这是FastGPT的必要配置。

pgvector服务部分需要注意：

pg:
  image: pgvector/pgvector:v0.5.0
  volumes:
    - ./pg/data:/var/lib/postgresql/data

volumes配置把数据持久化到宿主机，避免容器重启数据丢失。建议定期备份这个目录。

3.2 config.json核心参数

config.json中有几个关键配置项需要特别关注：

{
  "systemEnv": {
    "vectorMaxProcess": 15,
    "qaMaxProcess": 15,
    "pgHNSWEfSearch": 100
  },
  "chatModels": [
    {
      "model": "gpt-3.5-turbo",
      "maxContext": 4000,
      "maxResponse": 4000
    }
  ]
}

• vectorMaxProcess：向量处理并发数，建议设为CPU核心数的1.5倍
• pgHNSWEfSearch：向量搜索范围，值越大结果越准但速度越慢
• chatModels：模型列表，可以添加多个模型配置

4. 部署实战步骤

4.1 启动容器服务

配置修改完成后，启动服务很简单：

docker-compose up -d

但这里有个常见问题：MongoDB副本集初始化可能失败。如果看到日志报错，可以手动初始化：

# 进入MongoDB容器
docker exec -it mongo bash

# 连接MongoDB
mongo -u myusername -p mypassword --authenticationDatabase admin

# 初始化副本集
rs.initiate({
  _id: "rs0",
  members: [{ _id: 0, host: "mongo:27017" }]
})

4.2 访问与初始化

服务启动后，访问http://服务器IP:3000 就能看到登录界面。默认账号是root，密码在docker-compose.yml的DEFAULT_ROOT_PSW环境变量中设置。

首次登录会提示配置模型，这里需要特别注意API地址要加/v1后缀。比如用OpenAI的API，地址应该是https://api.openai.com/v1。我见过很多人漏掉这个后缀导致连接失败。

5. 常见问题排查

5.1 配置文件未生效

如果修改config.json后没效果，检查三点：

1. 文件是否挂载正确：执行docker exec -it fastgpt ls /app/data看是否存在config.json
2. JSON格式是否正确：可以用在线工具验证
3. 是否重启了服务：修改后需要docker-compose down && docker-compose up -d

5.2 模型连接失败

模型连接问题90%是配置错误：

• 检查OPENAI_BASE_URL是否包含/v1
• 确认API_KEY有效
• 测试网络连通性：docker exec -it fastgpt curl https://api.openai.com

5.3 性能优化技巧

当处理大量数据时，可以调整这些参数：

1. 增加docker-compose.yml中的资源限制：

fastgpt:
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 4G

2. 修改config.json中的maxProcess参数
3. 使用更高效的向量数据库如Milvus

6. 进阶配置与优化

6.1 多模型管理

通过OneAPI可以实现多模型统一管理。在docker-compose.yml中添加：

oneapi:
  image: ghcr.io/songquanpeng/one-api:latest
  ports:
    - 3001:3000

然后在FastGPT的OPENAI_BASE_URL指向http://oneapi:3000/v1，就能在OneAPI界面添加多个模型渠道。

6.2 自定义知识库

上传知识文档前，建议先调整config.json中的文本处理参数：

{
  "systemEnv": {
    "chunkSize": 500,
    "overlapSize": 50
  }
}

chunkSize控制文本分块大小，overlapSize是块间重叠字数。根据我的经验，500/50的组合对中文效果较好。

6.3 监控与日志

查看实时日志：

docker-compose logs -f

监控资源使用情况：

docker stats

建议配置Prometheus+Grafana进行长期监控，特别是CPU和内存使用率。