FastGPT + Docker 自建AI客服：3个必踩的坑

FastGPT 是一个开源的基于知识库的聊天机器人框架，很多团队用它来搭建内部知识问答或对外的AI客服。官方文档看起来步骤清晰，Docker Compose 一键拉起，但在真实环境里，有几个细节会让你的安装直接卡死。

一位开发者在全新的 Linux 机器上用 Docker 部署 FastGPT v4.15 后，记录了三个最容易翻车的环节。以下结合他的实测经验，逐一拆解问题原因和可行解法。

坑一：MinIO 镜像从 Docker Hub 拉不到了

FastGPT 的默认 Compose 文件依赖 MinIO 来存储知识库文件。但 MinIO 已经撤下了 Docker Hub 上的公开镜像，执行 docker compose up 时会直接报 pull access denied for minio/minio。

这不是你网络的问题，也不是认证配置的问题——镜像本身已经不在那里了。最直接的解法是改用 FastGPT 官方镜像源中的同版本 MinIO：registry.cn-hangzhou.aliyuncs.com/fastgpt/minio。

需要注意的是，这个阿里云^广告镜像源在中国大陆以外访问速度较慢，拉取时可能需要耐心等待，或者提前配置好代理。如果你在海外部署，也可以考虑自行构建 MinIO 镜像或寻找其他可信镜像源，但版本兼容性需要自己验证。

MinIO 是一个兼容 Amazon S3 API 的开源对象存储服务，可以自托管部署，常被用作私有云环境下的文件存储后端。它支持分布式部署、纠删码、版本控制等企业级特性，同时提供轻量的单机模式，因此在开源项目中常被选作默认的文件存储组件。FastGPT 使用 MinIO 来保存知识库上传的原始文档、解析后的分块数据以及向量索引等文件。

值得注意的是，MinIO 官方在 2025 年调整了镜像分发策略，从 Docker Hub 撤下了社区版镜像，转而通过自家站点和部分云厂商镜像仓库发布。这导致很多长期未更新的教程和默认 Compose 文件直接失效。遇到 pull access denied 时，说明镜像仓库路径已经变更，而非本地 Docker 配置或网络问题。解决思路通常是替换为项目官方维护的镜像源，或手动从 MinIO 官网下载二进制文件自行构建镜像。

坑二：CSV 导入 FAQ 必须有三列

FastGPT 支持通过 CSV 文件批量导入问答对。很多人会想当然地准备一个 q,a 两列的文件——问题一列、答案一列，逻辑上完全说得通。

但系统会直接拒绝导入，并报格式错误。实际要求的表头是 q,a,indexes，第三列 indexes 用于指定该问答对关联的知识库索引。缺少这一列，解析器就不会认。

这个设计初看有点反直觉，但考虑到 FastGPT 的知识库可以按索引分区，第三列的存在是为了让批量导入时能精确控制数据落点。建议在准备 CSV 时直接加上这一列，哪怕内容留空也比报错重来省事。

坑三：只有对话模型不够，必须有嵌入模型

这是最容易被忽略、也最让人困惑的一个。很多人配置好了 DeepSeek^广告 或其他对话模型的 API Key，以为就可以开始建知识库了，结果创建时提示“System not embedding model”。

FastGPT 的知识库检索依赖向量嵌入（embedding），对话模型负责生成回答，但把文档转成向量、把用户问题转成向量进行相似度匹配，这些都需要嵌入模型来完成。两者角色不同，不能互相替代。

换句话说，你至少需要配置两类模型：一个 chat model 用于对话生成，一个 embedding model 用于知识库索引和检索。DeepSeek 的对话能力再强，也无法填补嵌入模型的空缺。部署前务必确认你的模型供应商提供了 embedding API，并在 FastGPT 后台正确配置。

向量嵌入（embedding）是将文本转换为高维数值向量的过程，语义相近的文本在向量空间中距离更近。FastGPT 的知识库检索流程分为两步：首先用嵌入模型把上传的文档切块后逐段转成向量，存入向量数据库；用户提问时，再用同一个嵌入模型把问题转成向量，通过计算余弦相似度或内积找出最相关的文档片段，最后把这些片段作为上下文交给对话模型生成回答。

嵌入模型和对话模型是两类完全不同的模型，前者输出向量，后者输出文本，架构、训练目标和 API 接口都不一样。常见的嵌入模型有 OpenAI 的 text-embedding-3 系列、BAAI 的 bge 系列、阿里的 text-embedding-v 系列等，很多对话模型供应商并不提供嵌入 API。FastGPT 后台需要单独配置嵌入模型的 API Key 和地址，且嵌入模型一旦选定，后续更换会导致已有向量失效、需要重新索引，因此建议在部署初期就确定好长期可用的嵌入模型供应商。

额外提醒：Docker 会绕过 ufw 防火墙

这是一个和 FastGPT 无关但同样致命的 Docker 行为：Docker 发布的端口默认会绕过 ufw 的规则。你以为 ufw 挡住了 3000 端口，实际上 Docker 已经通过 iptables 直接暴露了它。

作者的应对方式是把 FastGPT 的端口绑定到 127.0.0.1，然后在前端放一个反向代理（Nginx 或 Caddy）来处理外部访问和 TLS。这样既保证了安全性，也方便统一管理入口。

Docker 在启动容器并发布端口时，会直接向 iptables 的 nat 表和 filter 表中写入 DNAT 和 FORWARD 规则，而 ufw 本质上只是 iptables 的一套前端管理工具，其规则写在特定的链中。Docker 添加的规则优先级高于 ufw 的默认策略，因此即使 ufw 显示某端口被拒绝，Docker 仍然可以通过 iptables 直接把外部流量转发到容器。

官方推荐的缓解方式有两种：一是把容器端口绑定到 127.0.0.1，让外部无法直接访问，再通过 Nginx、Caddy 等反向代理统一暴露服务；二是在 /etc/docker/daemon.json 中设置 "iptables": false，但这会影响所有容器的网络功能，需要手动维护转发规则，一般不推荐。对于生产环境，绑定本地回环加反向代理是更稳妥的做法，同时反向代理层还能集中处理 TLS 证书、访问日志和限流。

资源规划：2GB 内存不够用

在测试机上，FastGPT 空闲状态下的内存占用约为 2.1 GB。这意味着 2GB RAM 的 VPS 连启动都会吃力，更不用说处理实际请求。建议至少准备 4GB 内存的机器，如果知识库规模较大或并发用户较多，还需要进一步上调。

FastGPT 的内存占用主要来自几个部分：Node.js 后端服务本身、PostgreSQL 及其向量扩展 pgvector、MinIO、Redis 以及可选的 OneAPI 等辅助服务。即使在没有实际请求的空闲状态下，这些进程的基础内存开销合计也在 2 GB 左右，其中 pgvector 加载索引和 MinIO 的缓存机制会额外占用内存。

当知识库文档量增大时，向量索引的内存占用会线性增长；当并发请求增加时，Node.js 进程和数据库连接池也会进一步消耗内存。在 4 GB 的机器上，系统本身占用约 500 MB，剩余内存勉强支撑中小规模知识库；如果文档量超过数万条或并发用户超过几十人，建议直接上 8 GB 或使用独立数据库实例，否则容易触发 OOM Killer 导致容器被系统强制终止。

小结

FastGPT 的开箱体验整体不错，但 MinIO 镜像源、CSV 格式要求、嵌入模型配置这三个环节，任何一个卡住都会让整个部署停摆。加上 Docker 的防火墙行为和内存门槛，实际部署时需要关注的细节比官方快速开始文档呈现的要多。提前了解这些坑，能省下不少排查时间。