FastGPT + Docker Self-Hosted AI Customer Service: 3 Pitfalls You'll Definitely Hit

FastGPT is an open-source knowledge-base-driven chatbot framework, and many teams use it to build internal knowledge Q&A systems or customer-facing AI customer service. The official documentation looks straightforward — one-click launch with Docker Compose — but in real environments, a few details can bring your installation to a dead halt.

After deploying FastGPT v4.15 with Docker on a fresh Linux machine, one developer documented the three most failure-prone steps. Below, we break down the causes and practical solutions based on his hands-on experience.

Pitfall 1: MinIO Image Can No Longer Be Pulled from Docker Hub

FastGPT's default Compose file relies on MinIO to store knowledge base files. But MinIO has removed its public image from Docker Hub, so running docker compose up directly throws pull access denied for minio/minio.

This isn't a network issue on your end, nor a credential configuration problem — the image simply isn't there anymore. The most direct fix is to switch to the same-version MinIO from FastGPT's official mirror: registry.cn-hangzhou.aliyuncs.com/fastgpt/minio.

Note that this Alibaba Cloud mirror is slow to access outside mainland China, so pulling may require patience or a pre-configured proxy. If you're deploying overseas, you can also consider building your own MinIO image or finding another trusted mirror source, but you'll need to verify version compatibility yourself.

MinIO is an open-source object storage service compatible with the Amazon S3 API. It can be self-hosted and is commonly used as a file storage backend in private cloud environments. It supports enterprise-grade features such as distributed deployment, erasure coding, and versioning, while also offering a lightweight single-node mode — which is why it's often chosen as the default file storage component in open-source projects. FastGPT uses MinIO to store original documents uploaded to the knowledge base, parsed chunk data, and vector index files.

Notably, MinIO adjusted its image distribution strategy in 2025, removing the community edition image from Docker Hub and instead publishing through its own site and select cloud vendor registries. This has caused many long-outdated tutorials and default Compose files to break outright. When you encounter pull access denied, it means the image repository path has changed — not a local Docker configuration or network issue. The typical fix is to replace it with the project's officially maintained mirror, or manually download the binary from MinIO's website and build the image yourself.

Pitfall 2: CSV Import for FAQ Requires Three Columns

FastGPT supports bulk import of Q&A pairs via CSV files. Many people naturally prepare a two-column file with q,a — one column for questions, one for answers. Logically, that makes perfect sense.

But the system will reject the import outright with a format error. The actual required header is q,a,indexes, where the third column indexes specifies the knowledge base index associated with that Q&A pair. Without this column, the parser won't recognize it.

This design seems counterintuitive at first, but considering that FastGPT's knowledge base can be partitioned by index, the third column exists to give precise control over where data lands during bulk import. It's best to just add this column when preparing your CSV — even leaving it empty is easier than getting an error and starting over.

Pitfall 3: A Chat Model Alone Isn't Enough — You Need an Embedding Model

This is the most easily overlooked and most confusing one. Many people configure an API key for DeepSeek^Ad or another chat model and assume they're ready to build a knowledge base — only to get a "System not embedding model" error when creating one.

FastGPT's knowledge base retrieval relies on vector embeddings. The chat model generates answers, but converting documents into vectors and converting user questions into vectors for similarity matching — these all require an embedding model. The two serve different roles and cannot substitute for each other.

In other words, you need to configure at least two types of models: a chat model for conversation generation and an embedding model for knowledge base indexing and retrieval. No matter how powerful DeepSeek's conversational ability is, it cannot fill the gap left by a missing embedding model. Before deploying, make sure your model provider offers an embedding API and that it's correctly configured in the FastGPT admin panel.

Vector embedding is the process of converting text into high-dimensional numerical vectors, where semantically similar texts are closer together in vector space. FastGPT's knowledge base retrieval works in two steps: first, the embedding model converts uploaded documents — after chunking — into vectors segment by segment and stores them in a vector database; when a user asks a question, the same embedding model converts the question into a vector, and by computing cosine similarity or inner product, the most relevant document chunks are found. These chunks are then passed as context to the chat model to generate an answer.

Embedding models and chat models are two completely different types of models — the former outputs vectors, the latter outputs text — with different architectures, training objectives, and API interfaces. Common embedding models include OpenAI's text-embedding-3 series, BAAI's bge series, and Alibaba's text-embedding-v series. Many chat model providers do not offer embedding APIs. FastGPT's admin panel requires a separate API key and endpoint for the embedding model, and once chosen, switching it later will invalidate existing vectors and require re-indexing. It's therefore advisable to settle on a long-term embedding model provider early in deployment.

Additional Warning: Docker Bypasses ufw Firewall

This is a Docker behavior unrelated to FastGPT but equally critical: ports published by Docker bypass ufw rules by default. You think ufw is blocking port 3000, but Docker has actually exposed it directly through iptables.

The author's approach was to bind FastGPT's port to 127.0.0.1 and place a reverse proxy (Nginx or Caddy) in front to handle external access and TLS. This ensures security while centralizing entry point management.

When Docker starts a container and publishes a port, it writes DNAT and FORWARD rules directly into iptables' nat and filter tables. ufw is essentially just a front-end management tool for iptables, with its rules written in specific chains. Docker's added rules take priority over ufw's default policies, so even if ufw shows a port as denied, Docker can still forward external traffic directly to the container via iptables.

There are two officially recommended mitigations: first, bind the container port to 127.0.0.1 so it's inaccessible externally, then expose services uniformly through a reverse proxy like Nginx or Caddy; second, set "iptables": false in /etc/docker/daemon.json, but this affects all containers' networking and requires manual forwarding rule maintenance, so it's generally not recommended. For production environments, binding to localhost plus a reverse proxy is the safer approach, and the reverse proxy layer can also centrally handle TLS certificates, access logs, and rate limiting.

Resource Planning: 2GB RAM Isn't Enough

On a test machine, FastGPT's idle memory usage is around 2.1 GB. This means a 2GB RAM VPS will struggle just to start, let alone handle actual requests. At least 4GB of RAM is recommended; if the knowledge base is large or there are many concurrent users, you'll need to scale up further.

FastGPT's memory usage comes mainly from several components: the Node.js backend service itself, PostgreSQL with its vector extension pgvector, MinIO, Redis, and optional auxiliary services like OneAPI. Even at idle with no actual requests, the combined baseline memory overhead of these processes is around 2 GB, with pgvector loading indexes and MinIO's caching mechanism consuming additional memory.

As the volume of knowledge base documents grows, vector index memory usage increases linearly; as concurrent requests increase, Node.js processes and database connection pools consume further memory. On a 4GB machine, the system itself takes about 500 MB, and the remaining memory barely supports a small-to-medium knowledge base; if documents exceed tens of thousands or concurrent users exceed a few dozen, it's advisable to go straight to 8GB or use a separate database instance — otherwise you risk triggering the OOM Killer and having containers forcibly terminated by the system.

Summary

FastGPT's out-of-box experience is generally good, but the MinIO image source, CSV format requirements, and embedding model configuration are three steps where any one getting stuck will halt the entire deployment. Combined with Docker's firewall behavior and memory requirements, there are more details to watch for in actual deployment than the official quick-start documentation suggests. Knowing these pitfalls in advance can save considerable troubleshooting time.

One-line Summary

FastGPT Docker deployment tested: MinIO image failure, three-column CSV format, and missing embedding model are the three major pitfalls.

Paragraph Summary

This article documents typical issues a developer encountered deploying FastGPT v4.15 on a fresh Linux machine. The first pitfall is that MinIO has pulled its public image from Docker Hub, requiring a switch to FastGPT's official Alibaba Cloud mirror; the second is that CSV bulk import for FAQ requires a header of q,a,indexes — three columns — and a missing indexes column causes a format error; the third is that configuring only a chat model won't allow knowledge base creation — an embedding model is required for vector retrieval. It also warns that Docker port publishing bypasses ufw firewall by default, recommends binding to 127.0.0.1 with a front reverse proxy, and notes that FastGPT's idle memory usage is around 2.1 GB, so a 2GB VPS is insufficient — at least 4GB is recommended.