FastGPT Docker部署教程｜适合企业用户

一、前言：为什么企业用户适合用 Docker 部署 FastGPT

随着大语言模型在企业知识库、智能客服、内部助手、业务流程自动化等场景中的应用越来越广，越来越多企业开始关注如何快速、稳定、可控地部署 AI 应用平台。FastGPT 是一个面向企业知识库问答、AI 工作流和智能应用构建的平台，支持知识库管理、文件解析、向量检索、对话应用、工作流编排等能力，非常适合企业用于搭建内部 AI 助手、客服机器人、售前问答系统、文档检索系统等。

对于企业用户来说，部署方式往往比个人用户更加重要。个人用户可能更关注“能不能快速跑起来”，而企业用户则需要考虑更多维度，例如系统稳定性、数据安全、后续维护、版本升级、备份恢复、权限控制、资源规划以及与现有系统的集成能力。相比直接在服务器上手动安装各种依赖，Docker 部署方式更适合企业环境，因为它具备环境隔离、部署一致、升级方便、迁移简单等优势。

本文将围绕企业用户的实际需求，介绍如何使用 Docker 部署 FastGPT，并从环境准备、部署流程、配置说明、常见问题、运维建议、安全建议等方面进行系统讲解，帮助企业用户更稳妥地完成 FastGPT 私有化部署。

二、FastGPT 简介

FastGPT 是一个基于大语言模型的 AI 应用构建平台，核心能力包括：

• 知识库管理：支持导入企业文档、网页内容、FAQ、Markdown、PDF、Word 等资料。
• 向量检索：通过 Embedding 模型将文本向量化，实现语义检索。
• 智能问答：结合大模型能力，对知识库内容进行问答。
• 应用编排：支持构建多种 AI 应用，例如知识库机器人、客服助手、流程助手等。
• 工作流能力：可以通过节点化方式编排复杂业务逻辑。
• 多模型接入：支持接入 OpenAI、Azure OpenAI、国产大模型或企业自建模型服务。
• 权限与团队管理：适合企业多人协作和部门级使用。

对于企业而言，FastGPT 的价值不仅在于“问答”，更在于能够将分散在企业内部的制度文件、产品资料、技术文档、客服话术、操作手册等内容统一管理，并通过 AI 的方式降低员工查找信息和客户获取答案的成本。

三、Docker 部署的优势

企业部署 FastGPT 时，推荐优先选择 Docker 或 Docker Compose 方式，主要原因如下。

1. 环境一致性强

传统部署方式需要在服务器上分别安装 Node.js、MongoDB、PostgreSQL、向量数据库、反向代理等组件，不同服务器环境可能存在版本差异，容易出现“开发环境正常，生产环境异常”的问题。

Docker 可以将应用及其依赖封装在容器中，确保不同环境下运行结果一致。

2. 部署和迁移更方便

使用 Docker Compose 可以通过一个配置文件管理多个服务，例如 FastGPT 主服务、数据库、向量数据库等。后续如果需要迁移服务器，只需要迁移配置文件和数据卷，再重新启动容器即可。

3. 便于升级和回滚

企业系统上线后，升级往往需要谨慎。Docker 镜像具备版本管理能力，可以指定固定版本镜像。如果新版本出现问题，也可以快速回滚到之前版本，降低运维风险。

4. 服务隔离更安全

不同服务运行在不同容器中，彼此隔离。即使某个组件出现问题，也不会直接污染宿主机环境，有利于提高系统安全性和可维护性。

5. 适合自动化运维

Docker 部署方式更容易与 CI/CD、监控系统、日志系统、备份系统结合，适合企业逐步建设标准化运维体系。

四、部署前准备

在开始部署之前，建议企业用户先完成以下准备工作。

1. 服务器配置建议

FastGPT 的资源需求与使用规模、知识库大小、并发访问量、模型调用方式有关。一般企业内部试点可以从较低配置开始，后续再扩容。

测试环境建议

• CPU：2 核及以上
• 内存：4GB 及以上
• 磁盘：50GB 及以上
• 系统：Ubuntu 20.04 / 22.04 或其他主流 Linux 发行版

企业生产环境建议

• CPU：4 核及以上
• 内存：8GB 或 16GB 及以上
• 磁盘：100GB 及以上，建议使用 SSD
• 网络：稳定公网或内网访问环境
• 系统：Ubuntu Server LTS 版本

如果企业需要处理大量文档、较高并发或部署本地大模型，则需要更高配置，尤其是内存、磁盘和 GPU 资源。

2. 域名与 HTTPS

如果 FastGPT 面向企业内部员工使用，可以使用内网域名或 VPN 访问。如果需要对外提供服务，例如客户问答机器人，则建议配置公网域名和 HTTPS 证书。

企业生产环境不建议直接使用 IP 加端口暴露服务，推荐使用 Nginx、Caddy、Traefik 等反向代理，并启用 HTTPS。

3. 模型服务准备

FastGPT 本身是 AI 应用平台，实际回答能力依赖大语言模型和 Embedding 模型。企业部署前需要明确模型来源：

• 使用 OpenAI API；
• 使用 Azure OpenAI；
• 使用国内大模型服务商接口；
• 使用企业自建模型网关；
• 使用本地部署的大模型服务。

对于企业用户，建议统一通过模型网关或中间层管理模型调用，这样方便做额度控制、审计、切换模型和统一鉴权。

4. 安装 Docker 和 Docker Compose

在 Ubuntu 服务器上，可以使用以下命令安装 Docker：

curl -fsSL https://get.docker.com | bash

安装完成后，启动 Docker 服务：

systemctl enable docker
systemctl start docker

查看 Docker 版本：

docker version

查看 Docker Compose 版本：

docker compose version

如果系统提示没有 docker compose，需要根据系统版本安装 Docker Compose 插件。

五、FastGPT Docker Compose 部署思路

FastGPT 通常需要多个组件协同工作，常见组件包括：

• FastGPT 主应用服务；
• MongoDB 数据库；
• PostgreSQL 数据库；
• 向量数据库，例如 pgvector；
• 文件解析服务；
• 模型接口配置；
• 反向代理服务。

企业部署时建议采用 Docker Compose 管理这些服务，方便统一启动、停止、升级和排查。

典型目录结构可以设计如下：

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

其中：

• docker-compose.yml 用于定义容器服务；
• config 用于存放 FastGPT 配置文件；
• data 用于持久化数据库数据；
• logs 用于保存日志或挂载日志目录。

实际部署时，应以 FastGPT 官方文档提供的最新 Docker Compose 文件为准。企业用户不建议随意复制来源不明的配置文件，因为镜像版本、环境变量、数据库结构可能会随着版本变化而调整。

六、部署步骤

下面以通用流程介绍部署方法，具体镜像名称、版本和配置字段请结合官方文档确认。

第一步：创建部署目录

mkdir -p /opt/fastgpt
cd /opt/fastgpt

建议将 FastGPT 部署在 /opt 目录下，便于统一管理企业应用。

第二步：准备 Docker Compose 文件

在 /opt/fastgpt 目录下创建 docker-compose.yml 文件。企业用户建议从官方仓库或官方文档复制对应版本的 Compose 文件，然后根据实际环境调整。

需要重点关注以下配置：

• FastGPT 镜像版本；
• MongoDB 连接地址；
• PostgreSQL 连接地址；
• 数据卷挂载路径；
• 应用访问端口；
• 模型接口地址；
• 管理员初始化配置；
• 文件解析服务配置；
• 日志输出方式。

生产环境中不建议长期使用 latest 镜像标签，而应使用明确版本号，例如：

image: fastgpt/fastgpt:v4.x.x

这样可以避免镜像自动变化导致不可控风险。

第三步：准备配置文件

FastGPT 通常需要配置模型、知识库、系统参数等内容。企业用户应重点配置以下内容：

模型配置

包括聊天模型和向量模型。例如：

• 聊天模型用于生成回答；
• Embedding 模型用于知识库向量化；
• Rerank 模型用于提高检索排序质量。

企业在选择模型时，不应只看回答效果，还要考虑稳定性、成本、数据合规和响应速度。

数据库配置

数据库是 FastGPT 的核心依赖，必须启用持久化存储。不要将数据库数据只保存在容器内部，否则容器删除后数据可能丢失。

系统访问地址

如果配置了域名，需要在系统配置中写入正式访问地址，避免回调、资源加载或分享链接异常。

安全密钥

涉及 Token、Secret、API Key 的配置，必须使用强随机值，不应使用默认值。企业生产环境中应将敏感配置放入安全的环境变量管理系统，避免明文散落在多人可见的文件中。

第四步：启动服务

在部署目录执行：

docker compose up -d

查看容器状态：

docker compose ps

查看日志：

docker compose logs -f

如果所有服务正常启动，就可以通过服务器 IP 和端口访问 FastGPT。

第五步：初始化系统

首次访问 FastGPT 后，一般需要完成管理员账号初始化。企业用户建议创建专门的系统管理员账号，并启用强密码策略。

初始化完成后，可以进入后台进行以下操作：

• 配置模型；
• 创建团队或组织；
• 创建知识库；
• 上传测试文档；
• 创建 AI 应用；
• 进行问答测试；
• 调整提示词和检索参数。

第六步：配置反向代理

生产环境建议通过 Nginx 反向代理访问 FastGPT。例如：

server {
    listen 80;
    server_name fastgpt.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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;
    }
}

如果使用 HTTPS，可以通过 Certbot 申请证书：

apt install certbot python3-certbot-nginx -y
certbot --nginx -d fastgpt.example.com

对于企业内网环境，也可以使用自签证书或企业 CA 证书，但需要确保浏览器和客户端信任该证书。

七、企业用户重点配置建议

1. 数据持久化

数据库数据必须挂载到宿主机目录或企业存储系统。建议定期检查数据卷是否正确挂载。可以通过以下命令查看挂载情况：

docker inspect 容器名称

如果数据库没有持久化，后续容器重建或服务器故障可能导致数据丢失。

2. 版本固定

生产环境中不要盲目追求最新版本。建议采用以下策略：

• 测试环境先升级；
• 验证功能和数据兼容；
• 备份生产数据；
• 低峰期升级生产环境；
• 保留旧版本镜像用于回滚。

升级前应仔细阅读官方 Release Notes，确认是否涉及数据库迁移、配置变更或不兼容改动。

3. 权限控制

企业使用 FastGPT 时，通常会涉及多个部门和角色。建议至少划分以下角色：

• 系统管理员：负责部署、配置和维护；
• 知识库管理员：负责文档上传、更新和质量控制；
• 应用管理员：负责 AI 应用搭建和发布；
• 普通用户：仅使用问答或应用能力。

权限控制做得越清晰，后期越容易维护，也更利于数据安全。

4. 知识库治理

知识库质量直接影响问答效果。企业部署 FastGPT 后，不应简单把所有文档一次性上传，而应建立知识库治理机制。

建议遵循以下原则：

• 文档内容保持准确、最新；
• 删除过期制度和旧版本资料；
• 按业务场景拆分知识库；
• 文件命名规范清晰；
• 对高频问题建立标准答案；
• 定期抽查问答结果。

AI 问答效果不佳时，很多时候不是模型问题，而是知识库内容不清晰、文档结构混乱或检索参数不合理。

5. 日志与审计

企业环境中，应关注系统访问日志、错误日志和模型调用日志。日志可以帮助排查问题，也有助于进行安全审计。

建议记录以下信息：

• 用户登录情况；
• 应用访问情况；
• 知识库更新记录；
• 模型调用失败记录；
• 系统异常日志；
• 重要配置变更记录。

如果企业已有日志平台，例如 ELK、Loki、Splunk，可以将 FastGPT 相关日志接入统一平台。

八、备份与恢复方案

企业部署任何生产系统，都必须提前设计备份方案。FastGPT 相关数据通常包括：

• MongoDB 数据；
• PostgreSQL 数据；
• 配置文件；
• 上传文件；
• Docker Compose 文件；
• 环境变量文件；
• 反向代理配置。

1. 数据库备份

MongoDB 可以使用 mongodump，PostgreSQL 可以使用 pg_dump。如果数据库运行在 Docker 容器中，可以通过 docker exec 执行备份命令。

示例：

docker exec mongo mongodump --out /backup/mongo

PostgreSQL 示例：

docker exec postgres pg_dump -U postgres database_name > backup.sql

实际生产环境中，建议将备份文件保存到独立存储，例如 NAS、对象存储或备份服务器，避免与应用服务器放在同一磁盘。

2. 配置文件备份

配置文件通常体积不大，但非常重要。建议将以下文件纳入备份：

docker-compose.yml
.env
config.json
nginx.conf

其中 .env 可能包含敏感信息，备份时需要注意权限控制。

3. 恢复演练

很多企业虽然有备份，但从未演练恢复，一旦发生故障才发现备份不可用。建议至少每季度进行一次恢复演练，验证以下事项：

• 备份文件是否完整；
• 数据库是否能成功恢复；
• 应用是否能正常启动；
• 知识库是否仍可检索；
• 用户和权限是否完整；
• 历史应用是否正常工作。

九、安全加固建议

1. 不要直接暴露数据库端口

MongoDB、PostgreSQL 等数据库服务不应直接暴露到公网。Docker Compose 中如果没有必要，不要映射数据库端口到宿主机公网地址。

推荐做法是让数据库仅在 Docker 内部网络中被 FastGPT 访问。

2. 使用强密码和密钥

所有数据库密码、管理员密码、API Key 都必须使用强随机值。不要使用示例密码、默认密码或过短密码。

3. 开启 HTTPS

如果系统涉及账号登录、知识库资料或客户数据，必须启用 HTTPS。HTTP 明文传输可能导致账号、Token 或敏感内容泄露。

4. 控制模型 API Key 权限

如果使用第三方模型服务，API Key 应设置额度限制和调用权限。不要将高权限 Key 分发给普通用户，也不要写入前端代码或公开仓库。

5. 定期更新镜像

安全更新很重要，但生产环境不应直接自动升级。建议定期关注官方版本更新，在测试环境验证后再升级生产环境。

6. 限制后台访问范围

如果 FastGPT 主要用于企业内部，建议通过 VPN、内网网关、零信任访问平台或 IP 白名单限制访问范围，降低被扫描和攻击的风险。

十、常见问题排查

1. 容器启动失败

可以先查看容器状态：

docker compose ps

再查看日志：

docker compose logs -f 服务名

常见原因包括端口占用、环境变量错误、数据库连接失败、镜像拉取失败、配置文件格式错误等。

2. 页面无法访问

可能原因包括：

• FastGPT 容器未启动；
• 端口未开放；
• 防火墙拦截；
• 反向代理配置错误；
• 域名解析未生效；
• HTTPS 证书配置异常。

可以先在服务器本机测试：

curl http://127.0.0.1:3000

如果本机可以访问，说明应用本身正常，问题大概率在防火墙、反向代理或域名层。

3. 知识库无法正常检索

常见原因包括：

• Embedding 模型配置错误；
• 文档解析失败；
• 向量数据库异常；
• 文档切分不合理；
• 检索参数设置不合适；
• 知识库内容质量较差。

企业用户可以先上传少量结构清晰的测试文档，验证模型、解析和检索链路是否正常，再逐步导入正式资料。

4. 模型调用失败

需要检查：

• API Key 是否正确；
• 模型名称是否配置正确；
• 模型服务地址是否可访问；
• 企业网络是否允许访问外部 API；
• 是否触发服务商额度限制；
• 是否存在代理配置问题。

如果企业网络对外访问有限制，建议通过统一代理或模型网关转发请求。

5. 回答效果不理想

回答效果不佳不一定是部署问题，可能与以下因素有关：

• 文档质量低；
• 知识库切分不合理；
• 提示词过于简单；
• 检索数量设置不合适；
• 模型能力不足；
• 问题表达不清晰；
• 缺少标准答案或业务规则约束。

建议从“知识库质量、检索配置、提示词设计、模型能力”四个方向逐步优化。

十一、企业上线流程建议

为了降低上线风险，建议企业按照以下流程推进：

1. 技术验证阶段：由技术团队完成 Docker 部署，验证基础功能是否可用。
2. 小范围试点阶段：选择一个部门或一个业务场景，例如客服知识库或 IT 运维问答。
3. 知识库治理阶段：整理文档结构，删除无效内容，建立更新机制。
4. 权限和安全配置阶段：配置账号、团队、访问范围、HTTPS、备份策略。
5. 生产上线阶段：通过域名正式发布，并设置监控和日志。
6. 持续优化阶段：根据用户反馈优化知识库、提示词和模型配置。

企业不要一开始就追求“大而全”，更推荐从一个高频、明确、可衡量的场景切入。例如：售后问题查询、产品资料问答、公司制度查询、IT 工单辅助、客服标准话术等。

十二、运维维护建议

FastGPT 部署完成后，并不意味着工作结束。企业应建立长期维护机制。

1. 定期检查服务状态

可以通过以下命令检查服务：

docker compose ps
docker stats

重点关注 CPU、内存、磁盘占用和容器重启次数。

2. 监控磁盘空间

知识库文件、数据库和日志都会占用磁盘。如果磁盘满了，可能导致数据库写入失败、容器异常退出或系统无法上传文件。

建议配置磁盘告警，例如当磁盘使用率超过 80% 时通知管理员。

3. 定期清理无用镜像

升级后可能留下旧镜像，可以定期清理：

docker image prune

但生产环境清理前要确认是否仍需要旧版本镜像用于回滚。

4. 建立变更记录

每次修改配置、升级版本、调整模型、变更知识库策略，都建议记录变更时间、操作人、变更内容和回滚方案。

这对于企业内部审计和故障排查非常重要。

十三、总结

FastGPT 是企业构建知识库问答和 AI 应用平台的实用工具，而 Docker 部署方式则为企业提供了更标准、更稳定、更易维护的落地路径。通过 Docker Compose，企业可以将 FastGPT、数据库、向量检索组件和相关服务统一管理，降低环境差异带来的部署风险。

对于企业用户来说，成功部署只是第一步，更关键的是后续的知识库治理、权限管理、安全加固、备份恢复和持续优化。一个真正可用的企业 AI 系统，不仅要能回答问题，还要保证数据可靠、访问安全、运维可控、效果可持续提升。

如果企业计划将 FastGPT 用于生产环境，建议遵循以下原则：

• 使用 Docker Compose 标准化部署；
• 固定镜像版本，避免不可控升级；
• 数据库和配置文件必须持久化；
• 生产环境启用 HTTPS 和访问控制；
• 建立定期备份和恢复演练机制；
• 从小场景试点，再逐步推广到更多部门；
• 持续优化知识库质量和模型配置。

只要部署架构合理、运维机制完善、知识库治理到位，FastGPT 可以成为企业 AI 应用建设中的重要基础平台，帮助企业将内部知识转化为可查询、可复用、可自动化的智能能力。