FastGPT 私有化部署实战：从环境准备到完整命令一篇搞定

发布人：慈云数据-客服中心发布时间：12小时前阅读量：5

FastGPT 私有化部署方案｜附完整命令

一、为什么要选择 FastGPT 私有化部署？

随着大模型应用在企业内部的落地，越来越多团队开始关注“知识库问答”“智能客服”“企业内部助手”“流程自动化 Agent”等场景。FastGPT 正是一个面向大模型应用构建的开源平台，它支持知识库管理、数据集检索、可视化工作流编排、多模型接入、API 调用、团队权限管理等能力，非常适合企业快速搭建自己的 AI 应用平台。

相比直接使用公有云上的 SaaS 服务，私有化部署 FastGPT 有几个明显优势：

数据更安全
企业知识库、内部文档、客户资料、合同、研发文档等往往包含敏感信息。私有化部署可以将数据保存在企业自己的服务器或内网环境中，降低数据外泄风险。
可控性更强
私有化环境下，企业可以自主选择大模型服务，例如 OpenAI、Azure OpenAI、通义千问、智谱、DeepSeek、Moonshot、Ollama 本地模型等，也可以根据业务需要调整数据库、向量库、存储和网络策略。
更方便集成内部系统
FastGPT 支持通过 API 与第三方系统集成。私有化部署后，可以更方便地与企业现有的 OA、CRM、ERP、工单系统、知识管理系统、IM 工具等进行连接。
成本更可控
对于使用频率较高的企业，如果完全依赖 SaaS 平台，长期费用可能较高。私有化部署后，可以根据自身规模选择服务器配置，并结合本地模型或自建模型服务优化成本。

本文将以 Docker Compose 方式介绍 FastGPT 的私有化部署方案，覆盖环境准备、目录规划、配置文件、启动命令、模型配置、常见维护命令以及常见问题排查，帮助你从零搭建一套可用的 FastGPT 私有化环境。

二、部署架构说明

FastGPT 私有化部署通常包含以下几个核心组件：

组件	作用
FastGPT	核心应用服务，提供 Web 页面、知识库、应用编排、API 等能力
MongoDB	存储用户、应用、知识库配置、对话记录等结构化数据
PostgreSQL / PGVector	用于向量检索，存储知识库向量数据
Redis	用于缓存、队列、会话等场景
OneAPI / New API	可选组件，用于统一管理多个大模型渠道
Nginx	可选组件，用于反向代理、HTTPS、域名访问

在实际企业环境中，比较推荐的架构是：

用户浏览器 / 内部系统
        |
     Nginx
        |
     FastGPT
   /    |     \
MongoDB Redis PGVector
        |
   大模型服务 / OneAPI / New API

如果只是测试或小规模使用，可以将这些服务部署在同一台服务器上。如果是正式生产环境，建议将数据库、向量库和应用服务分开部署，或者至少做好数据备份、资源隔离和监控告警。

三、服务器配置建议

FastGPT 本身对服务器要求不算特别高，但知识库规模、并发量、模型调用方式会明显影响资源消耗。

1. 测试环境配置

适合个人体验、小团队测试、功能验证。

CPU：2 核及以上
内存：4GB 及以上
磁盘：40GB 及以上
系统：Ubuntu 20.04 / Ubuntu 22.04 / Debian 11+

2. 小型生产环境配置

适合 10～50 人团队、少量知识库、低到中等并发。

CPU：4 核及以上
内存：8GB～16GB
磁盘：100GB SSD 及以上
系统：Ubuntu 22.04 LTS

3. 中大型生产环境配置

适合较多知识库、较高并发、多个业务系统集成。

CPU：8 核及以上
内存：32GB 及以上
磁盘：300GB SSD 及以上
数据库：建议独立部署
对象存储：建议使用 MinIO / S3 / 云厂商 OSS

如果你计划在同一台机器上运行本地大模型，例如 Qwen、DeepSeek、Llama 等，还需要额外配置 GPU。FastGPT 本身不是模型推理服务，它主要负责应用编排和知识库检索，模型推理可以由 OpenAI API、国产大模型 API、Ollama、vLLM、Xinference 等服务提供。

四、安装 Docker 与 Docker Compose

以下命令以 Ubuntu 22.04 为例。如果你的服务器是 CentOS、Debian 或其他 Linux 发行版，命令可能略有差异。

1. 更新系统软件包

sudo apt update
sudo apt upgrade -y

2. 安装基础依赖

sudo apt install -y ca-certificates curl gnupg lsb-release

3. 添加 Docker 官方 GPG Key

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

4. 添加 Docker 软件源

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

5. 安装 Docker

sudo apt update

sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

6. 验证安装

docker --version
docker compose version

如果输出 Docker 和 Docker Compose 的版本号，说明安装成功。

7. 配置当前用户使用 Docker

如果你不希望每次执行 Docker 命令都加 sudo，可以执行：

sudo usermod -aG docker $USER

然后退出当前 SSH 会话并重新登录，或者执行：

newgrp docker

验证：

docker ps

五、创建部署目录

建议将 FastGPT 的部署文件统一放在 /opt/fastgpt 目录下，方便后续维护和备份。

sudo mkdir -p /opt/fastgpt
sudo chown -R $USER:$USER /opt/fastgpt
cd /opt/fastgpt

创建数据目录：

mkdir -p data/mongo
mkdir -p data/pg
mkdir -p data/redis
mkdir -p config

目录结构建议如下：

/opt/fastgpt
├── docker-compose.yml
├── config
│   └── config.json
└── data
    ├── mongo
    ├── pg
    └── redis

六、编写 Docker Compose 配置

在 /opt/fastgpt 目录下创建 docker-compose.yml：

cat > docker-compose.yml <<'EOF'
version: "3.9"

services:
  mongo:
    image: mongo:5.0
    container_name: fastgpt-mongo
    restart: always
    command: mongod --keyFile /data/mongodb.key --replSet rs0
    environment:
      MONGO_INITDB_ROOT_USERNAME: username
      MONGO_INITDB_ROOT_PASSWORD: password
    volumes:
      - ./data/mongo:/data/db
    entrypoint:
      - bash
      - -c
      - |
        openssl rand -base64 756 > /data/mongodb.key
        chmod 400 /data/mongodb.key
        chown 999:999 /data/mongodb.key
        exec docker-entrypoint.sh mongod --keyFile /data/mongodb.key --replSet rs0
    ports:
      - "27017:27017"

  mongo-init:
    image: mongo:5.0
    container_name: fastgpt-mongo-init
    depends_on:
      - mongo
    restart: "no"
    entrypoint:
      - bash
      - -c
      - |
        sleep 8
        mongosh --host mongo:27017 -u username -p password --authenticationDatabase admin --eval '
          try {
            rs.initiate({
              _id: "rs0",
              members: [{ _id: 0, host: "mongo:27017" }]
            })
          } catch(e) {
            print(e)
          }
        '

  pg:
    image: ankane/pgvector:v0.5.1
    container_name: fastgpt-pg
    restart: always
    environment:
      POSTGRES_USER: username
      POSTGRES_PASSWORD: password
      POSTGRES_DB: fastgpt
    volumes:
      - ./data/pg:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:7.2-alpine
    container_name: fastgpt-redis
    restart: always
    command: redis-server --requirepass password
    volumes:
      - ./data/redis:/data
    ports:
      - "6379:6379"

  fastgpt:
    image: ghcr.io/labring/fastgpt:latest
    container_name: fastgpt
    restart: always
    depends_on:
      - mongo
      - pg
      - redis
    ports:
      - "3000:3000"
    environment:
      DEFAULT_ROOT_PSW: "123456"
      OPENAI_BASE_URL: "https://api.openai.com/v1"
      CHAT_API_KEY: "sk-your-api-key"
      DB_MAX_LINK: "30"
      TOKEN_KEY: "any"
      ROOT_KEY: "root_key"
      FILE_TOKEN_KEY: "filetoken"
      MONGODB_URI: "mongodb://username:password@mongo:27017/fastgpt?authSource=admin&replicaSet=rs0"
      PG_URL: "postgresql://username:password@pg:5432/fastgpt"
      REDIS_URL: "redis://:password@redis:6379"
    volumes:
      - ./config/config.json:/app/data/config.json
EOF

注意：上面的 username、password、DEFAULT_ROOT_PSW、CHAT_API_KEY 等都应该在正式部署前修改为强密码或真实密钥。不要在生产环境中使用示例密码。

七、编写 FastGPT 配置文件

FastGPT 支持通过配置文件定义模型、向量模型、重排模型、语音模型等。这里先给出一个通用示例，以 OpenAI 兼容接口为例。

创建配置文件：

cat > config/config.json <<'EOF'
{
  "systemEnv": {
    "vectorMaxProcess": 15,
    "qaMaxProcess": 15,
    "pgHNSWEfSearch": 100
  },
  "llmModels": [
    {
      "model": "gpt-4o-mini",
      "name": "gpt-4o-mini",
      "maxContext": 128000,
      "maxResponse": 16000,
      "quoteMaxToken": 120000,
      "maxTemperature": 1.2,
      "charsPointsPrice": 0,
      "censor": false,
      "vision": true,
      "datasetProcess": true,
      "usedInClassify": true,
      "usedInExtractFields": true,
      "usedInToolCall": true,
      "usedInQueryExtension": true,
      "toolChoice": true,
      "functionCall": true,
      "defaultSystemChatPrompt": ""
    }
  ],
  "vectorModels": [
    {
      "model": "text-embedding-3-small",
      "name": "text-embedding-3-small",
      "price": 0,
      "defaultToken": 700,
      "maxToken": 8192
    }
  ],
  "reRankModels": [],
  "audioSpeechModels": [],
  "whisperModel": {
    "model": "whisper-1",
    "name": "whisper-1",
    "charsPointsPrice": 0
  }
}
EOF

如果你使用的是兼容 OpenAI API 的国内模型服务，例如 DeepSeek、Moonshot、智谱、通义千问或通过 OneAPI / New API 转发的模型，只需要重点修改两处：

OPENAI_BASE_URL: "你的模型服务地址"
CHAT_API_KEY: "你的模型服务密钥"

以及 config.json 里的模型名称，例如：

{
  "model": "deepseek-chat",
  "name": "DeepSeek Chat"
}

不同模型服务商对模型名称、上下文长度、Embedding 模型名称的要求不同，建议以服务商文档为准。

八、启动 FastGPT

在 /opt/fastgpt 目录下执行：

docker compose up -d

查看容器状态：

docker compose ps

查看日志：

docker compose logs -f fastgpt

如果所有容器都正常运行，浏览器访问：

http://服务器IP:3000

默认管理员密码由 DEFAULT_ROOT_PSW 指定，例如上文配置的是：

首次登录后，请立即修改管理员密码，并检查系统配置、模型配置和知识库功能是否正常。

九、配置防火墙与安全策略

如果服务器启用了 UFW 防火墙，可以开放 3000 端口：

sudo ufw allow 3000/tcp
sudo ufw reload
sudo ufw status

但在生产环境中，更推荐只开放 80 和 443 端口，由 Nginx 反向代理到 FastGPT 的 3000 端口，数据库端口不要暴露到公网。

如果你已经将数据库、Redis、PGVector 部署在同一台机器上，建议删除或限制以下端口的公网访问：

27017 MongoDB
5432  PostgreSQL
6379  Redis

如果没有外部访问需求，可以在 docker-compose.yml 中移除这些服务的 ports 映射，让它们只在 Docker 内部网络中通信。

例如，可以删除：

ports:
  - "27017:27017"

这样 MongoDB 不会直接暴露到宿主机公网端口，安全性更好。

十、使用 Nginx 配置域名访问

如果你希望通过域名访问 FastGPT，例如：

https://fastgpt.example.com

可以安装 Nginx：

sudo apt install -y nginx

创建站点配置：

sudo tee /etc/nginx/sites-available/fastgpt <<'EOF'
server {
    listen 80;
    server_name fastgpt.example.com;

    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}
EOF

启用站点：

sudo ln -s /etc/nginx/sites-available/fastgpt /etc/nginx/sites-enabled/fastgpt
sudo nginx -t
sudo systemctl reload nginx

安装 Certbot 并申请 HTTPS 证书：

sudo apt install -y certbot python3-certbot-nginx

sudo certbot --nginx -d fastgpt.example.com

申请成功后，再访问：

https://fastgpt.example.com

十一、接入 OneAPI / New API 统一模型网关

如果企业需要同时接入多个模型渠道，建议在 FastGPT 前面增加一个统一模型网关，例如 OneAPI 或 New API。它们可以统一管理不同模型供应商的 API Key、额度、分组、转发地址和调用日志。

整体调用链路如下：

FastGPT -> OneAPI / New API -> OpenAI / Azure / DeepSeek / 通义千问 / 智谱 / 本地模型

此时 FastGPT 的环境变量可以配置为：

OPENAI_BASE_URL: "http://oneapi:3000/v1"
CHAT_API_KEY: "oneapi 中生成的令牌"

如果 OneAPI / New API 和 FastGPT 在同一个 Docker 网络内，可以直接使用容器名访问；如果部署在其他服务器，则填写对应的内网地址或 HTTPS 地址。

这种方式的优点是：

FastGPT 侧配置更简单；
多模型统一管理；
便于统计调用量；
方便做 Key 轮换；
支持不同业务使用不同模型分组；
后续替换模型服务时不需要频繁修改 FastGPT 配置。

十二、接入本地模型方案

如果企业对数据安全要求极高，或者希望降低模型调用成本，可以使用本地模型。常见方案包括：

方案	说明
Ollama	部署简单，适合测试和轻量场景
vLLM	性能较好，适合生产推理
Xinference	支持多种模型管理方式
LMDeploy	适合部分国产模型推理加速
LocalAI	提供 OpenAI 兼容接口

以 Ollama 为例，安装命令如下：

curl -fsSL https://ollama.com/install.sh | sh

拉取模型：

ollama pull qwen2.5:7b

启动后，Ollama 默认监听：

http://127.0.0.1:11434

如果需要让 Docker 容器访问宿主机上的 Ollama，可以将 FastGPT 的 OPENAI_BASE_URL 配置为：

OPENAI_BASE_URL: "http://host.docker.internal:11434/v1"

在 Linux 上，可能还需要在 docker-compose.yml 的 fastgpt 服务中添加：

extra_hosts:
  - "host.docker.internal:host-gateway"

然后在 FastGPT 配置文件中配置对应模型名称。不过需要注意，本地模型的指令遵循能力、函数调用能力、上下文长度和中文效果差异较大。生产环境建议充分测试知识库问答、复杂推理、工具调用和长文本处理效果。

十三、常用维护命令

1. 查看服务状态

cd /opt/fastgpt
docker compose ps

2. 查看实时日志

docker compose logs -f

只查看 FastGPT 日志：

docker compose logs -f fastgpt

查看 MongoDB 日志：

docker compose logs -f mongo

3. 重启服务

docker compose restart

只重启 FastGPT：

docker compose restart fastgpt

4. 停止服务

docker compose down

5. 启动服务

docker compose up -d

6. 更新镜像

docker compose pull
docker compose up -d

7. 查看容器资源占用

docker stats

8. 进入容器

docker exec -it fastgpt sh

进入 MongoDB：

docker exec -it fastgpt-mongo mongosh \
  -u username \
  -p password \
  --authenticationDatabase admin

进入 PostgreSQL：

docker exec -it fastgpt-pg psql \
  -U username \
  -d fastgpt

十四、数据备份与恢复

生产环境一定要重视备份。FastGPT 的关键数据主要包括：

MongoDB 数据；
PostgreSQL / PGVector 数据；
配置文件；
上传文件或对象存储数据；
Docker Compose 部署文件。

1. 备份 MongoDB

mkdir -p /opt/backup/fastgpt

docker exec fastgpt-mongo mongodump \
  -u username \
  -p password \
  --authenticationDatabase admin \
  --archive=/tmp/mongo.archive

复制备份文件到宿主机：

docker cp fastgpt-mongo:/tmp/mongo.archive /opt/backup/fastgpt/mongo.archive

2. 备份 PostgreSQL

docker exec fastgpt-pg pg_dump \
  -U username \
  -d fastgpt \
  -F c \
  -f /tmp/fastgpt.pg.dump

复制到宿主机：

docker cp fastgpt-pg:/tmp/fastgpt.pg.dump /opt/backup/fastgpt/fastgpt.pg.dump

3. 备份配置文件

cp /opt/fastgpt/docker-compose.yml /opt/backup/fastgpt/
cp -r /opt/fastgpt/config /opt/backup/fastgpt/

4. 恢复 MongoDB

docker cp /opt/backup/fastgpt/mongo.archive fastgpt-mongo:/tmp/mongo.archive

docker exec fastgpt-mongo mongorestore \
  -u username \
  -p password \
  --authenticationDatabase admin \
  --archive=/tmp/mongo.archive

5. 恢复 PostgreSQL

docker cp /opt/backup/fastgpt/fastgpt.pg.dump fastgpt-pg:/tmp/fastgpt.pg.dump

docker exec fastgpt-pg pg_restore \
  -U username \
  -d fastgpt \
  --clean \
  --if-exists \
  /tmp/fastgpt.pg.dump

建议将备份脚本加入 crontab 定时执行，并将备份文件同步到异地存储，避免服务器磁盘故障导致数据全部丢失。

十五、生产环境优化建议

1. 不要使用默认密码

示例配置中的密码仅用于演示，生产环境必须修改：

MONGO_INITDB_ROOT_PASSWORD
POSTGRES_PASSWORD
REDIS_PASSWORD
DEFAULT_ROOT_PSW
TOKEN_KEY
ROOT_KEY
FILE_TOKEN_KEY
CHAT_API_KEY

建议使用高强度随机字符串，例如：

openssl rand -base64 32

2. 数据库不要暴露公网

MongoDB、PostgreSQL、Redis 默认不应该对公网开放。即使设置了密码，也不建议直接暴露。更安全的方式是只允许 Docker 内部网络访问，或者通过内网安全组限制访问来源。

3. 使用固定版本镜像

测试环境可以使用 latest，但生产环境建议使用固定版本，例如：

image: ghcr.io/labring/fastgpt:v4.x.x

固定版本可以避免自动升级带来的兼容性问题。升级前建议先在测试环境验证。

4. 配置 HTTPS

如果 FastGPT 面向公网访问，必须配置 HTTPS。即使只在企业内部使用，也建议通过内网域名和证书提升访问安全性。

5. 做好监控

至少应关注以下指标：

CPU 使用率；
内存占用；
磁盘空间；
容器重启次数；
MongoDB 状态；
PostgreSQL 连接数；
Redis 内存；
FastGPT 错误日志；
模型 API 调用失败率。

可以使用 Prometheus、Grafana、Uptime Kuma、云厂商监控等工具实现基础监控。

6. 控制知识库质量

FastGPT 的知识库问答效果不仅取决于模型，也取决于文档质量、切分方式、向量模型和召回策略。建议：

上传结构清晰的 Markdown、PDF、Word 或网页文档；
避免大量重复、过期、矛盾内容；
对重要文档进行人工校验；
为不同业务场景拆分不同知识库；
根据效果调整分段长度、召回数量和相似度阈值；
使用更高质量的 Embedding 模型提升召回准确性。

十六、常见问题排查

1. 页面打不开

先检查容器是否运行：

docker compose ps

再查看 FastGPT 日志：

docker compose logs -f fastgpt

检查端口是否监听：

ss -lntp | grep 3000

如果使用云服务器，还要检查安全组是否开放 3000、80 或 443 端口。

2. 登录后模型不可用

重点检查：

OPENAI_BASE_URL
CHAT_API_KEY
config/config.json

可以在服务器上用 curl 测试模型接口：

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

如果使用 OneAPI / New API，则测试对应网关地址：

curl http://your-oneapi-host/v1/models \
  -H "Authorization: Bearer your-token"

3. 知识库导入失败

常见原因包括：

Embedding 模型配置错误；
模型服务不支持当前向量模型；
PostgreSQL / PGVector 连接异常；
文件过大；
文档格式解析失败；
服务器内存不足。

查看日志：

docker compose logs -f fastgpt
docker compose logs -f pg

4. MongoDB 报副本集错误

FastGPT 某些功能依赖 MongoDB Replica Set。如果 MongoDB 副本集没有初始化，可能会出现事务相关错误。可以进入 MongoDB 检查：

docker exec -it fastgpt-mongo mongosh \
  -u username \
  -p password \
  --authenticationDatabase admin

执行：

rs.status()

如果未初始化，可以执行：

rs.initiate({
  _id: "rs0",
  members: [{ _id: 0, host: "mongo:27017" }]
})

5. Redis 连接失败

检查环境变量：

REDIS_URL: "redis://:password@redis:6379"

检查 Redis 容器：

docker compose logs -f redis

进入 Redis 测试：

docker exec -it fastgpt-redis redis-cli -a password ping

如果返回：

PONG

说明 Redis 正常。

十七、完整部署命令汇总

如果你希望快速部署，可以参考下面的完整命令。生产环境请先修改密码和密钥。

sudo apt update
sudo apt upgrade -y

sudo apt install -y ca-certificates curl gnupg lsb-release

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update

sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

sudo mkdir -p /opt/fastgpt
sudo chown -R $USER:$USER /opt/fastgpt
cd /opt/fastgpt

mkdir -p data/mongo data/pg data/redis config

写入 docker-compose.yml 和 config/config.json 后启动：

docker compose up -d
docker compose ps
docker compose logs -f fastgpt

访问：

http://服务器IP:3000

十八、总结

FastGPT 私有化部署并不复杂，核心思路是通过 Docker Compose 将 FastGPT、MongoDB、PGVector 和 Redis 组合起来，再根据企业实际情况接入 OpenAI 兼容模型、本地模型或统一模型网关。对于测试环境，一台普通云服务器即可完成部署；对于生产环境，则需要重点关注密码安全、数据库备份、HTTPS、日志监控、模型稳定性和知识库质量。

如果你的目标只是快速体验，可以直接使用本文中的 Docker Compose 方案启动服务；如果你的目标是企业级落地，建议进一步拆分数据库、配置对象存储、接入统一模型网关、建立备份机制，并在正式上线前进行权限、性能和安全测试。

FastGPT 的价值不只是“搭一个聊天机器人”，而是让企业能够围绕自己的业务知识、流程和系统，构建可持续迭代的 AI 应用平台。通过私有化部署，企业既能获得大模型应用的效率提升，也能更好地掌握数据、安全和成本的主动权。

上一篇：FastGPT 企业私有化部署怎么做？安全、架构、落地一篇讲透

下一篇：FastGPT 本地化落地指南：源码部署、模型接入与企业知识库实战

更多栏目