Docker Compose 部署

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

前置知识

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

部署架构图

推荐配置

向量数据库选型对比

PgVector 版本

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

Milvus 版本

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

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

点击查看 Milvus 官方推荐配置

zilliz cloud 版本

Zilliz Cloud 提供托管向量数据库。容量、网络连通性、SLA 与费用以所选服务方案为准。

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

SeekDB 版本

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

前置工作

准备 Docker-compose 环境

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

brew install orbstack

开始部署

1. 获取配置文件

方法一：使用 AI Agent 代部署

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

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

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

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

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”并输入文件路径，也可以通过环境变量传入路径：

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 文件到服务器，例如：

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

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

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

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

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 模式：

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

如果启用 Agent/Skill 沙盒，还需要同步替换 Compose 文件中的沙盒相关镜像，以及 AGENT_SANDBOX_SEALOS_IMAGE 或 AGENT_SANDBOX_OPENSANDBOX_IMAGE，确保沙盒 provider 可以拉取对应镜像。具体配置见 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 版本时获取账号和密钥, 其他版本可直接下一步。

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 以上，否则可能无法执行自动化命令。

# 预拉取所有服务及沙盒运行时镜像
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 密码。
• 旧版本（v4.17.2 及更早）：密码为 docker-compose.yml 环境变量里设置的 DEFAULT_ROOT_PSW。如果使用交互式脚本部署，脚本会随机生成并在完成后输出登录密码。每次重启容器都会按该变量自动更新密码。

6. 配置模型

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

7. 按需安装系统插件

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

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

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

打开 Zilliz Cloud , 创建实例并获取相关秘钥。

部署后运维与故障排查

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