# Docker Compose 部署

> 使用 Docker Compose 快速部署 FastGPT，包含架构拓扑、向量数据库选型对比、硬件规格估算与一键安装脚本说明。

Source: https://doc.fastgpt.cn/zh-CN/self-host/deploy/docker

FastGPT 支持通过 Docker Compose 在单台 Linux、macOS 或 Windows 服务器上一键拉起完整私有化服务栈，涵盖主应用、插件服务、AI Proxy 模型网关、MongoDB、RustFS 对象存储，以及 PostgreSQL（pgvector）、Milvus、Zilliz、OceanBase、SeekDB 或 OpenGauss 向量数据库。

## 前置知识

1. 基础的网络知识：端口，防火墙……
2. Docker 和 Docker Compose 基础知识

## 部署架构图

![FastGPT 核心部署拓扑](/imgs/diagrams/deployment-core.zh-CN.light.svg)

> * MongoDB：保存业务元数据、集合和数据块；原始文件等资源由对象存储保存。
> * PostgreSQL/Milvus/OceanBase/SeekDB/OpenGauss：存储向量数据
> * AI Proxy：必需的模型服务，负责模型请求代理和管理员渠道管理。

## 推荐配置

### 向量数据库选型对比

| 向量库方案                  | 部署形态与接入协议               | 混合检索支持                | 运维复杂度     | 适用规模与场景                         |
| ---------------------- | ----------------------- | --------------------- | --------- | ------------------------------- |
| **PgVector**           | 单容器 PostgreSQL 扩展（`pg`） | 向量检索 + MongoDB 全文检索   | 低（单实例易备份） | 默认推荐；快速验证、中小规模及百万级向量生产环境        |
| **Milvus**             | 独立分布式向量引擎（需 ≥ 2.5.16）   | 向量检索 + Milvus 原生 BM25 | 中高（独立组件）  | 千万级以上大规模向量、高并发检索与独立算力扩容         |
| **Zilliz Cloud**       | 全托管云端 Milvus 服务         | 向量检索 + 云端原生全文检索       | 极低（云端免运维） | 追求免运维弹性扩展、降低本地内存开销的生产团队         |
| **OceanBase / SeekDB** | 分布式数据库 / MySQL 协议接入     | 向量检索 + 混合召回           | 中         | 已具备 OceanBase 或 MySQL 运维体系的企业环境 |
| **OpenGauss**          | 国产企业级关系型向量库             | 向量检索 + 混合召回           | 中         | 信创合规与国产化基础设施环境                  |

### PgVector 版本

以下为历史容量估算，实际资源需求取决于向量维度、索引参数、文档大小、并发和其他同机服务。部署前用目标数据量压测，并为备份与增长预留空间。

| 环境               | 最低配置（单节点）   | 推荐配置         |
| ---------------- | ----------- | ------------ |
| 测试（可以把计算进程设置少一些） | 2c4g        | 2c8g         |
| 100w 组向量         | 4c8g 50GB   | 4c16g 50GB   |
| 500w 组向量         | 8c32g 200GB | 16c64g 200GB |

### Milvus 版本

适合需要独立管理向量检索服务的部署，具体容量与性能需要压测验证。

**Milvus 版本要求：≥ 2.5.16。** 使用 Milvus 作为向量库时，全文检索自动启用 Milvus BM25（`modeldata_v2` 单表）；低于 2.5.16 时 FastGPT 启动会直接报错退出。

[点击查看 Milvus 官方推荐配置](https://milvus.io/docs/prerequisite-docker.md)

| 环境       | 最低配置（单节点） | 推荐配置  |
| -------- | --------- | ----- |
| 测试       | 2c8g      | 4c16g |
| 100w 组向量 | 未测试       |       |
| 500w 组向量 |           |       |

### zilliz cloud 版本

[Zilliz Cloud](https://zilliz.com.cn/) 提供托管向量数据库。容量、网络连通性、SLA 与费用以所选服务方案为准。

向量服务由云端托管，本地仍需为 FastGPT、MongoDB、对象存储及其他组件配置资源。

### SeekDB 版本

SeekDB 使用 MySQL 协议接入，FastGPT 提供对应的向量库适配。以下为容量估算，部署前应验证所用版本、模型向量维度与实际负载。

| 环境               | 最低配置（单节点）   | 推荐配置         |
| ---------------- | ----------- | ------------ |
| 测试（可以把计算进程设置少一些） | 2c4g        | 2c8g         |
| 100w 组向量         | 4c8g 50GB   | 4c16g 50GB   |
| 500w 组向量         | 8c32g 200GB | 16c64g 200GB |

> FastGPT 的 SeekDB 适配包含以下能力，支持范围以所选数据库版本和模型配置为准：
>
> * 按模型配置创建对应维度的向量索引
> * 内置 HNSW 索引算法
> * 提供批量插入和查询优化
> * 自动重试和连接池管理

## 前置工作

### 准备 Docker-compose 环境

#### Linux

```bash
# 安装 Docker（包含 Docker Compose V2 插件）
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun
systemctl enable --now docker
# 验证安装
docker -v
docker compose version
```

安装异常时请参考 [Docker 官方安装文档](https://docs.docker.com/engine/install/)。

#### MacOS

推荐直接使用 [Orbstack](https://orbstack.dev/)。可直接通过 Homebrew 来安装：

```bash
brew install orbstack
```

或者直接[下载安装包](https://orbstack.dev/download)进行安装。

#### Windows

我们建议将源代码和其他数据绑定到 Linux 容器中时，将其存储在 WSL 2 的 Linux 文件系统中，确保最佳的文件 I/O 性能和文件权限兼容性。

可以选择直接[使用 WSL 2 后端在 Windows 中安装 Docker Desktop](https://docs.docker.com/desktop/wsl/)。

也可以直接[在 WSL 2 中安装命令行版本的 Docker](https://nickjanetakis.com/blog/install-docker-in-wsl-2-without-docker-desktop)。

## 开始部署

### 1. 获取配置文件

#### 方法一：使用 AI Agent 代部署

将以下内容复制给你的 Coding Agent：

```text
参考 https://doc.fastgpt.cn/deploy/SKILL.md 帮我部署 FastGPT Docker 版本。
```

#### 方法二：使用交互式脚本部署

需要在 Linux/MacOS/Windows WSL 环境下执行。脚本依次引导选择部署版本、镜像源、向量库、是否自动生成密钥，再输入 FastGPT 访问地址、Sandbox WebSocket / 预览地址和宿主机端口，最后确认配置。

```bash
FASTGPT_DEPLOY_BASE_URL=https://doc.fastgpt.cn bash <(curl -fsSL https://doc.fastgpt.cn/deploy/install.sh)
```

如果文档站使用自定义域名、内网地址或本地地址，可通过 `FASTGPT_DEPLOY_BASE_URL` 指定下载源，取值可以是站点根地址，也可以是以 `/deploy` 结尾的地址；脚本会从该地址下载 `docker-compose.yml`；旧版 compose 仍挂载 `config.json` 时，也会一并下载该文件。

设置 `FASTGPT_NON_INTERACTIVE=true` 可进入非交互模式，脚本不再逐项询问，改从 `FASTGPT_DEPLOY_VERSION`、`FASTGPT_REGION`、`FASTGPT_VECTOR`、`FASTGPT_AUTO_GENERATE_CREDENTIALS` 等变量读取选项，未设置时依次使用 `main`、`cn`、`pg` 和自动生成密钥。识别不了镜像版本时，可用 `FASTGPT_IMAGE_TAG` 或 `FASTGPT_ROOT_ACTIVATION` 指定版本能力。

非交互模式还必须通过 `FASTGPT_FE_DOMAIN` 指定用户访问 FastGPT 的完整地址，例如 `https://fastgpt.example.com`。启用 Agent/Skill 沙盒的版本还需要通过 `FASTGPT_SANDBOX_PROXY_URL` 指定沙盒 WebSocket 地址，例如 `wss://sandbox-proxy.example.com`；4.16 及以上版本还需要通过 `FASTGPT_SANDBOX_PREVIEW_PROXY_URL` 指定 HTTP 预览地址。

访问地址和宿主机端口是独立配置。需要直连时，可通过 `FASTGPT_PORT` 设置 FastGPT 宿主机端口（默认 `3000`），通过 `FASTGPT_SANDBOX_PROXY_PORT` 设置 Sandbox Proxy 宿主机端口（默认 `3006`）；容器端口仍分别为 `3000` 和 `1006`。如果使用反向代理，`FASTGPT_FE_DOMAIN`、`FASTGPT_SANDBOX_PROXY_URL` 及预览地址中的公网端口（例如 `443`）不会被当作宿主机端口，脚本会保留 Compose 中的默认映射。

**脚本会自动完成以下操作**：

* 下载 `docker-compose.yml`。
* 部署 v4.14 版本，或本地 compose 包含 `STORAGE_EXTERNAL_ENDPOINT` 时，引导选择 S3 外部访问地址，并写入配置文件。
* 随机生成服务间 Token、应用密钥和组件密码，并写入 `docker-compose.yml`；v4.17.2 及更早版本还会随机生成 `root` 登录密码。
* 自动检测宿主机 Docker socket 路径，必要时替换 `docker-compose.yml` 中的挂载路径。

执行完成后，终端会输出 `root` 登录信息：v4.17.3 及以上版本初始密码固定为 `123456`，首次登录需完成账号激活并设置新密码；更早版本输出本次随机生成的密码。请妥善保存生成后的 `docker-compose.yml`。后续升级时建议基于该文件调整，不要直接丢失已生成的密码和密钥。

如果要使用已有的本地 `docker-compose.yml`（例如测试尚未发布到文档站的版本），在部署版本步骤选择“本地 docker-compose.yml”并输入文件路径，也可以通过环境变量传入路径：

```bash
FASTGPT_LOCAL_COMPOSE_PATH=/path/to/docker-compose.yml bash <(curl -fsSL https://doc.fastgpt.cn/deploy/install.sh)
```

#### 方法三：手动下载部署

如果需要固定使用某个 `docker-compose.yml` 文件，推荐先手动下载 `docker-compose.yml` 和 `install.sh`，再通过 `install.sh` 的本地 compose 模式生成最终配置。这样仍然可以复用脚本里的随机凭证、S3 地址写入、Docker socket 检测等能力。

1. 下载所需的 `docker-compose.yml` 文件到服务器，例如：

```bash
curl -fsSL https://doc.fastgpt.cn/deploy/docker/main/cn/docker-compose.pg.yml -o docker-compose.source.yml
```

**点击展开查看不同数据库的 docker-compose 配置文件下载地址**

* **Pgvector**
  * 中国大陆地区镜像源(阿里云)：[docker-compose.pg.yml](/deploy/docker/main/cn/docker-compose.pg.yml)
  * 全球镜像源(dockerhub, ghcr)：[docker-compose.pg.yml](/deploy/docker/main/global/docker-compose.pg.yml)
* **Oceanbase**
  * 中国大陆地区镜像源(阿里云)：[docker-compose.oceanbase.yml](/deploy/docker/main/cn/docker-compose.oceanbase.yml)
  * 全球镜像源(dockerhub, ghcr)：[docker-compose.oceanbase.yml](/deploy/docker/main/global/docker-compose.oceanbase.yml)
* **Milvus**
  * 中国大陆地区镜像源(阿里云)：[docker-compose.milvus.yml](/deploy/docker/main/cn/docker-compose.milvus.yml)
  * 全球镜像源(dockerhub, ghcr)：[docker-compose.milvus.yml](/deploy/docker/main/global/docker-compose.milvus.yml)
* **Zilliz**
  * 中国大陆地区镜像源(阿里云)：[docker-compose.zilliz.yml](/deploy/docker/main/cn/docker-compose.zilliz.yml)
  * 全球镜像源(dockerhub, ghcr)：[docker-compose.zilliz.yml](/deploy/docker/main/global/docker-compose.zilliz.yml)
* **SeekDB**
  * 中国大陆地区镜像源(阿里云)：[docker-compose.seekdb.yml](/deploy/docker/main/cn/docker-compose.seekdb.yml)
  * 全球镜像源(dockerhub, ghcr)：[docker-compose.seekdb.yml](/deploy/docker/main/global/docker-compose.seekdb.yml)
* **OpenGauss**
  * 中国大陆地区镜像源(阿里云)：[docker-compose.opengauss.yml](/deploy/docker/main/cn/docker-compose.opengauss.yml)
  * 全球镜像源(dockerhub, ghcr)：[docker-compose.opengauss.yml](/deploy/docker/main/global/docker-compose.opengauss.yml)

2. 下载 `install.sh` 到服务器：

```bash
curl -fsSL https://doc.fastgpt.cn/deploy/install.sh -o install.sh
```

3. 使用 `install.sh` 读取本地 compose 文件并生成最终部署配置：

```bash
FASTGPT_LOCAL_COMPOSE_PATH=./docker-compose.source.yml bash install.sh
```

脚本会复制该 compose 文件为最终的 `docker-compose.yml`，并继续随机生成各类凭证，需要时写入 S3 地址。生成完成后，按终端输出的 root 登录信息登录。

完全离线环境下，需要同时准备 `docker-compose.yml` 和 `install.sh`。如果无法运行脚本，则需要手动修改服务 Token、数据库密码、S3 地址等配置（`v4.17.3+` 新实例初始密码固定为 `123456`，首次登录通过激活弹窗修改密码；`v4.17.2` 及更早版本通过 `DEFAULT_ROOT_PSW` 设置）。

#### 自定义镜像源部署

如果需要使用企业内网 Harbor、私有 Registry 或自建镜像加速源，可以先下载 `docker-compose.yml`，把所有 `image:` 改成自己的镜像地址，再走本地 compose 模式：

```bash
FASTGPT_LOCAL_COMPOSE_PATH=./docker-compose.yml bash install.sh
```

如果启用 Agent/Skill 沙盒，还需要同步替换 Compose 文件中的沙盒相关镜像，以及 `AGENT_SANDBOX_SEALOS_IMAGE` 或 `AGENT_SANDBOX_OPENSANDBOX_IMAGE`，确保沙盒 provider 可以拉取对应镜像。具体配置见 [OpenSandbox 配置](/zh-CN/self-host/config/sandbox/opensandbox)。

### 2. 修改环境变量

必须填写 `fastgpt-app` 中的 `FE_DOMAIN`，设置为用户实际访问 FastGPT 的完整公网或局域网地址，例如 `https://fastgpt.example.com`。该地址必须由客户端浏览器直接访问，由协议、主机和可选端口组成。

启用 Agent/Skill 沙盒时还必须配置：

* `AGENT_SANDBOX_PROXY_URL`：浏览器访问 Sandbox Proxy 的 WebSocket 地址，使用 `ws://` 或 `wss://`，例如 `wss://sandbox-proxy.example.com`，需要由反向代理转发到 Sandbox Proxy 的宿主机端口（默认 `3006`）。
* 4.16 及以上版本额外配置 `AGENT_SANDBOX_PREVIEW_PROXY_URL`：浏览器访问沙盒文件预览的 HTTP(S) 地址，例如 `https://sandbox-proxy.example.com`，同样需要转发到该宿主机端口。

使用交互式安装脚本时，脚本会在确认部署前询问这些地址。

对于 `Zilliz 版本` 还需要获取密钥，参考 [部署 Zilliz 版本时获取账号和密钥](#8-部署-zilliz-版本时获取账号和密钥), 其他版本可直接下一步。

### 3. 开放外网端口/配置域名

以下服务需要被访问到。直连时开放脚本最终输出的宿主机端口；使用反向代理时，公网端口由代理负责：

1. 默认 `3000` 端口（FastGPT 主服务；可通过 `FASTGPT_PORT` 修改宿主机端口）
2. 9000 端口（S3 对象存储服务；默认 `short-proxy` 模式下私有文件由 FastGPT 代理下载，使用 `short-redirect` 模式或浏览器需直连公开桶加载插件 Logo 时，需在 Compose 中配置 `STORAGE_EXTERNAL_ENDPOINT` 并开放 9000 端口）
3. 默认 `3006` 端口（FastGPT Agent Sandbox Proxy 服务；可通过 `FASTGPT_SANDBOX_PROXY_PORT` 修改宿主机端口）

### 4. 启动容器

在 docker-compose.yml 同级目录下执行。请确保 `docker-compose` 版本最好在 2.17 以上，否则可能无法执行自动化命令。

```bash
# 预拉取所有服务及沙盒运行时镜像
docker compose --profile prepull pull

# 启动容器
docker compose up -d
```

### 5. 访问 FastGPT

可通过第三步开放的端口/域名访问 FastGPT。登录用户名为 `root`：

* **v4.17.3 及更高版本**：初始密码固定为 `123456`，首次登录后系统会弹出激活窗口强制要求修改密码（`v4.17.3+` 部署模板中残留的 `DEFAULT_ROOT_PSW` 环境变量会被忽略）。忘记密码时可通过内置 CLI 脚本重置，详见[修改与重置 root 密码](/zh-CN/self-host/config/root-password)。
* **旧版本（v4.17.2 及更早）**：密码为 `docker-compose.yml` 环境变量里设置的 `DEFAULT_ROOT_PSW`。如果使用交互式脚本部署，脚本会随机生成并在完成后输出登录密码。每次重启容器都会按该变量自动更新密码。

### 6. 配置模型

* 首次登录 FastGPT 后，若尚未配置模型，系统会提示“未配置相关模型”或“未配置索引模型”，并引导前往模型配置页面。系统必须至少配置语言模型和索引模型才能正常使用。
* 如果系统未正常跳转，可以在**管理员 → 系统资源 → 系统模型**页面进行模型配置。[点击查看相关教程](/zh-CN/self-host/config/model/intro)
* 目前已知可能问题：首次进入系统后，整个浏览器 tab 无法响应。此时需要删除该 tab，重新打开一次即可。

### 7. 按需安装系统插件

从 V4.14.0 版本开始，`fastgpt-plugin` 镜像仅提供运行环境，管理员可在**管理员 →（商业版：系统资源 →）系统工具**页面按需安装系统插件：

* 通过插件市场安装，默认会向公开的 FastGPT Marketplace 获取数据进行安装。
* 如果你的 FastGPT 无法访问插件市场，则可以手动访问 [FastGPT 插件市场](https://marketplace.fastgpt.cn/)，先下载 .pkg 文件，再通过文件导入的方式安装到系统里。
* 除了安装外，还可对工具进行排序、默认安装、标签管理等。

![7. 按需安装系统插件：界面示例](/imgs/optimized/image-121.png.webp)

### 8. 部署 Zilliz 版本时获取账号和密钥

打开 [Zilliz Cloud](https://zilliz.com.cn/) , 创建实例并获取相关秘钥。

![zilliz_key](/imgs/optimized/zilliz_key.png.webp)

> 1. 修改 `MILVUS_ADDRESS` 和 `MILVUS_TOKEN` 链接参数，分别对应 `zilliz` 的 `Public Endpoint` 和 `Api key`，记得把自己 ip 加入白名单。

## 部署后运维与故障排查

* **日常运维**：修改容器环境变量参见 [环境变量说明](/zh-CN/self-host/config/env)；修改或重置管理员密码参见 [修改与重置 root 密码](/zh-CN/self-host/config/root-password)；跨版本升级前请先阅读 [升级说明](/zh-CN/self-host/upgrading/upgrade-instruction)；将自带 MongoDB 5.x 迁移到 8.x 参见 [MongoDB 5.x 迁移到 8.x（导出/恢复）](/zh-CN/self-host/upgrading/mongodb-8)。
* **故障排查**：遇到组件镜像版本匹配、S3 连接异常、MongoDB 副本集初始化、`relation "modeldata" does not exist`、`Illegal instruction` 或端口冲突等问题时，请查阅 [通用问题排查](/zh-CN/self-host/troubleshooting/faq)。