1. 方案与环境#

推荐做法：

• FastGPT 用独立 Docker Compose 部署，数据库和附件放在本机目录。
• cloudflared 以系统服务运行，把本机回环地址上的端口映射到自己的域名。
• 向量库选用 PostgreSQL + pgvector。
• 聊天、索引、重排都走外部 API，降低本机算力需求。

示例环境：4 核、16GB 内存的 x86 小主机，Ubuntu 24.04 LTS，已安装 Docker 与 Compose。近年 Intel 小主机一般支持 AVX / AVX2，不必为此降级 MongoDB。若 CPU 不支持 AVX，再查 MongoDB 官方说明。

部署目录示例：/opt/fastgpt。

NOTE

本机若已有面板、博客、数据库或其他容器，先确认端口和内存，不要直接使用官方默认的 MinIO 9000 / 9001。下文用覆盖文件把服务绑到 127.0.0.1，只给 Tunnel 访问。

2. 部署前检查资源#

先看内存、负载、容器和监听端口：

1
free -h
2
uptime
3
sudo docker stats --no-stream
4
sudo docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Ports}}'
5
sudo ss -lntp

普通用户访问 Docker socket 可能报 permission denied，加上 sudo 即可，不必重装 Docker。

如果机器上有已经不用、但很占内存的服务，先停掉并关闭开机自启，数据可以先留着。以 GitLab 为例：

1
sudo gitlab-ctl status
2
sudo systemctl status gitlab-runsvdir --no-pager
3
sudo gitlab-ctl stop
4
sudo systemctl disable --now gitlab-runsvdir

这不会卸载软件，也不会删除仓库和数据库。是否彻底清理可以以后再决定。

重点看 free -h 的 available，不要只看 free 列。Linux 会把空闲内存拿去当文件缓存，这部分可以回收。

3. Cloudflare Tunnel#

1
cloudflared --version
2
dpkg-query -W -f='${Status}\n' cloudflared

1
update-alternatives: 候选项路径 /etc/mysql/mariadb.cnf 不存在

1
sudo systemctl status cloudflared --no-pager -l
2
sudo journalctl -u cloudflared --since "10 minutes ago" --no-pager -n 40

1
/usr/bin/cloudflared --no-autoupdate tunnel run --token-file /etc/cloudflared/token

1
Failed to read token file: open /etc/cloudflared/token: no such file or directory

1
sudo systemctl stop cloudflared
2
sudo install -d -m 700 /etc/cloudflared
3
sudo -v

1
read -r -s -p "请粘贴Token并按回车：" cf_tunnel_token

1
printf '\n'
2
if [ -n "$cf_tunnel_token" ]; then
3
  printf '%s' "$cf_tunnel_token" | sudo tee /etc/cloudflared/token >/dev/null
4
  sudo chmod 600 /etc/cloudflared/token
5
else
6
  echo "没有输入 Token，请重试"
7
fi
8
unset cf_tunnel_token
9
sudo systemctl restart cloudflared

4. 生成 FastGPT 配置#

1
sudo mkdir -p /opt/fastgpt
2
sudo chown "$(id -un):$(id -gn)" /opt/fastgpt
3
cd /opt/fastgpt
4
umask 077
5
curl -fL --retry 3 https://doc.fastgpt.cn/deploy/install.sh -o install.sh
6
bash -n install.sh

国内域名失败时，可改用 https://doc.fastgpt.io/deploy/install.sh。

首次生成配置：

1
FASTGPT_REGION=cn \
2
FASTGPT_VECTOR=pg \
3
FASTGPT_AUTO_GENERATE_CREDENTIALS=true \
4
FASTGPT_FE_DOMAIN=https://gpt.example.com \
5
FASTGPT_PORT=3300 \
6
bash install.sh

把 FASTGPT_FE_DOMAIN 换成你的主站 HTTPS 地址。向导里选择稳定版 v4.16，并填写：

• Sandbox WebSocket：wss://sandbox.example.com
• Sandbox 预览：https://sandbox.example.com
• Sandbox 宿主机端口：3006

脚本会随机生成 root 密码、服务 Token 和数据库凭证。把原配置备份好，以后不要直接重跑生成流程覆盖已有凭证。

v4.16 向导可能不会询问 S3 外部地址，不要照搬旧教程强行加存储变量。附件的外网访问和引用行为，以你实际上传测试为准。

常见组件包括 App、Plugin、AIProxy，以及 PostgreSQL、pgvector、MongoDB、Redis、MinIO、Code Sandbox、Agent Sandbox Proxy、OpenSandbox Server、Volume Manager。

5. 端口与并发覆盖文件#

先备份官方生成的 Compose 文件：

1
cd /opt/fastgpt
2
cp -p docker-compose.yml "docker-compose.yml.bak-$(date +%Y%m%d-%H%M%S)"
3
chmod 600 docker-compose.yml

新建 /opt/fastgpt/docker-compose.override.yml。作用有两件：把端口绑到回环地址，避免和本机已有 9000 / 9001 冲突；把解析并发压到适合小主机的水平。

1
services:
2
  fastgpt-app:
3
    ports: !override
4
      - "127.0.0.1:3300:3000"
5
    environment:
6
      DATASET_PARSE_MAX_PROCESS: "2"
7
      VECTOR_MAX_PROCESS: "2"
8
      QA_MAX_PROCESS: "1"
9
      VLM_MAX_PROCESS: "1"
10

11
  fastgpt-agent-sandbox-proxy:
12
    ports: !override
13
      - "127.0.0.1:3006:1006"
14

15
  fastgpt-minio:
16
    ports: !override
17
      - "127.0.0.1:39000:9000"
18
      - "127.0.0.1:39001:9001"

!override 会整段替换端口列表，避免新旧映射叠在一起。需要 Compose 2.24.4 或更高。默认的 docker compose 命令会读取这个覆盖文件。

1
chmod 600 docker-compose.override.yml
2
sudo docker compose config --quiet

WARNING

完整的 docker compose config 输出可能带上数据库密码等凭证，不要复制到聊天或公开文档。

16GB 内存的机器上，上述并发比较稳妥。内存更宽裕再逐步加大。

6. 拉取、启动与验证#

1
cd /opt/fastgpt
2
sudo docker compose --profile prepull pull

SSH 断开或机器重启后，不确定是否拉完，可以再执行一次。Docker 会复用已经下完的镜像层。

拉取结束后立刻看退出码：

1
echo "拉取退出码：$?"

为 0 后再启动：

1
sudo docker compose up -d
2
sudo docker compose ps -a
3
free -h
4
curl -I --max-time 15 http://127.0.0.1:3300

预期：列出的常驻容器为 Up，带健康检查的为 healthy；本机主站返回 HTTP 200。再看一次 available 内存，确认还有余量。

7. 外网 Error 1033：OpenClash Fake-IP#

本机 curl 已经 200，域名却显示 Cloudflare Error 1033，说明边缘连不上这条隧道。

1
sudo systemctl is-enabled cloudflared
2
sudo systemctl is-active cloudflared
3
sudo journalctl -u cloudflared --since "10 minutes ago" --no-pager -n 40

enabled / active 只表示进程在跑，不表示隧道已经连上 Cloudflare。若路由器开了 OpenClash（或同类 Fake-IP 模式），失败日志里常能看到：

1
ip=198.18.3.173
2
ip=198.18.3.174
3
failed to dial to edge with quic: timeout: no recent network activity

198.18.0.0/16 是 Fake-IP 段。cloudflared 必须解析到 Cloudflare 边缘的真实地址，不能走这套虚假 IP。

处理步骤：

1. 在默认黑名单模式的 Fake-IP 过滤列表里追加 +.argotunnel.com、+.cftunnel.com，让这些域名解析为真实 IP。输入格式取决于 OpenClash 编辑框，不要整份覆盖 DNS 配置。
2. 在已有的持久化自定义规则里，于 rules: 下添加：

1
rules:
2
  - DOMAIN-SUFFIX,argotunnel.com,DIRECT
3
  - DOMAIN-SUFFIX,cftunnel.com,DIRECT

不要再创建第二个 rules:；新规则不要带 # 注释。放到宽泛代理规则之前，启用自定义规则后保存应用。

本机清缓存并复查：

1
sudo resolvectl flush-caches
2
getent ahostsv4 region1.v2.argotunnel.com
3
getent ahostsv4 region2.v2.argotunnel.com
4
sudo systemctl restart cloudflared
5
sudo journalctl -u cloudflared --since "2 minutes ago" --no-pager -n 30

正常日志会回到 198.41.* 一类 Cloudflare 地址，DNS / UDP / TCP 检查为 PASS，并出现多条 Registered tunnel connection。之后主站外网即可访问。

TIP

QUIC 能通则不必强制 HTTP/2。若你这边 UDP 仍不通，再试 HTTP/2。Cloudflare Tunnel 出站端口是 7844（QUIC 用 UDP，HTTP/2 用 TCP），不需要在路由器上开放入站端口。

8. 配置模型#

1
{
2
  "BAAI/bge-m3": "Pro/BAAI/bge-m3"
3
}

9. 社区版与图文知识库#

官方功能对比里，图片知识库属于商业版 / 云服务能力。配了视觉模型，不等于社区版会出现原生「图片入库 / 图片索引」入口。

把 Markdown 丢进知识库时，文中的相对图片链接也不会因为你在库里建了 figures 文件夹就自动生效。需要实际上传图片，并改写链接。

如果知识库来自本地「章节 Markdown + 配图」工程，比较稳妥的做法是：

• 工程清单文件通常只描述结构，并不等于带齐全部资源的压缩包。
• 按清单读取章节 Markdown 和图片目录。
• 上传时保留章节、页码、图号等信息，把链接改成 FastGPT 能访问的地址。
• 若还需要按图像内容检索，先生成图像说明，再参与文本索引。
• 批量导入建议做成可增量、可失败重试的同步，而不是一次性手工上传。

先用一章验证分块、问答引用和图片显示，再批量导入。

10. 上线后建议#

• 确认沙箱子域已经写进隧道路由。
• 给主站加上访问控制（例如 Cloudflare Access，只放行自己的账号）。附件域名不要直接套交互式登录页，除非已经验证服务端拉文件不受影响。
• 备份不要只复制正在写入的数据库目录。需要涵盖数据库一致性备份、附件、Compose 文件和同步状态。
• 本机若还有数据库监听在 0.0.0.0 或 IPv6 上，检查防火墙。监听所有接口不等于已经暴露到公网，但这些端口也不应加入 Tunnel。
• 若安装 cloudflared 时留下了残缺的 MariaDB 包问题，单独修复，不要和 FastGPT 绑在一起处理。

11. 参考#

• FastGPT Docker 部署
• FastGPT 版本与功能差异
• Docker Compose 合并规则
• Cloudflare Tunnel
• Cloudflare Tunnel 防火墙要求
• Mihomo DNS
• DeepSeek 视觉
• 硅基流动 Embedding