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

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

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

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

1. 数据更安全
   企业知识库、内部文档、客户资料、合同、研发文档等往往包含敏感信息。私有化部署可以将数据保存在企业自己的服务器或内网环境中，降低数据外泄风险。

2. 可控性更强
   私有化环境下，企业可以自主选择大模型服务，例如 OpenAI、Azure OpenAI、通义千问、智谱、DeepSeek、Moonshot、Ollama 本地模型等，也可以根据业务需要调整数据库、向量库、存储和网络策略。

3. 更方便集成内部系统
   FastGPT 支持通过 API 与第三方系统集成。私有化部署后，可以更方便地与企业现有的 OA、CRM、ERP、工单系统、知识管理系统、IM 工具等进行连接。

4. 成本更可控
   对于使用频率较高的企业，如果完全依赖 SaaS 平台，长期费用可能较高。私有化部署后，可以根据自身规模选择服务器配置，并结合本地模型或自建模型服务优化成本。

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

二、部署架构说明

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

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

用户浏览器 / 内部系统
        |
     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 指定，例如上文配置的是：

123456

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

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

如果服务器启用了 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 为例，安装命令如下：

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 的关键数据主要包括：

1. MongoDB 数据；
2. PostgreSQL / PGVector 数据；
3. 配置文件；
4. 上传文件或对象存储数据；
5. 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 应用平台。通过私有化部署，企业既能获得大模型应用的效率提升，也能更好地掌握数据、安全和成本的主动权。