注意事项

在使用 FastGPT 过程中遇到问题时，请参考以下步骤进行排查和解决。

1. 版本检查与升级

很多已知问题已在最新版本中得到修复。在反馈问题前，请务必确认您的版本情况：

• 检查版本：在 FastGPT 首页或管理后台查看当前运行的版本号。
• 升级建议：如果当前不是最新版本，建议先参考 更新指南 升级至最新稳定版。

2. 问题排查步骤

若升级后问题依然存在，请按以下顺序排查：

• 查看日志：检查 Docker 容器或服务器日志，寻找具体的错误报错信息（Error Stack）。
• 清理缓存：尝试清理浏览器缓存或使用无痕模式重新访问。
• 环境检查：确认数据库（MongoDB, PostgreSQL/Milvus）连接是否正常，以及 API 密钥是否有效。

3. 反向代理客户端 IP 防伪造

FastGPT 会在 IP 限流、分享链接 IP 白名单、对话日志 IP 记录、IP 属地展示等场景读取客户端 IP。自部署时如果 FastGPT 前面有 Nginx、负载均衡、Ingress 或 CDN，需要避免客户端伪造 X-Forwarded-For 或 X-Real-IP 请求头。

推荐同时完成以下配置：

• Nginx 覆盖外部传入的 IP 请求头：最后一层反向代理不要透传用户原始 X-Forwarded-For，而是用真实连接来源覆盖。
• FastGPT 开启可信代理校验：只信任来自 Nginx、负载均衡或 Ingress 的转发头，不信任普通客户端直连请求里的 IP 头。
• 限制 FastGPT 端口暴露范围：防火墙或安全组只允许反向代理访问 FastGPT 服务端口，避免用户绕过 Nginx 直连 FastGPT。

FastGPT 环境变量示例：

TRUSTED_PROXY_ENABLE=true
TRUSTED_PROXY_IPS=172.18.0.0/16

TRUSTED_PROXY_IPS 需要填写 FastGPT 直接看到的上一跳代理 IP 或 CIDR，例如 Nginx 容器所在 Docker 网段、Ingress Controller 内网地址或负载均衡回源地址。不要填写 0.0.0.0/0，也不要把普通客户端网段加入可信列表。

单层 Nginx 直接对外时，可参考：

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

    location / {
        proxy_pass http://fastgpt:3000;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

如果 Nginx 前面还有 CDN 或负载均衡，需要先让 Nginx 只信任这些上游的出口 IP，再把还原后的真实客户端 IP 转发给 FastGPT：

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

    # 只填写你的 CDN 或负载均衡出口 IP/CIDR，不要信任所有来源。
    set_real_ip_from 10.0.0.0/8;
    set_real_ip_from 172.16.0.0/12;
    real_ip_header X-Forwarded-For;
    real_ip_recursive on;

    location / {
        proxy_pass http://fastgpt:3000;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

如果 CDN 使用专用真实 IP 头，例如 CF-Connecting-IP，需要把 real_ip_header 改成对应头名，并把 set_real_ip_from 配置为该 CDN 官方公布的出口 IP 段。

修改完成后，执行：

nginx -t && nginx -s reload

可以用伪造头验证配置是否生效：

curl -H 'X-Forwarded-For: 6.6.6.6' -H 'X-Real-IP: 6.6.6.6' https://fastgpt.example.com

如果配置正确，FastGPT 记录和校验的仍应是真实客户端 IP，而不是 6.6.6.6。

4. 联系技术支持

若以上步骤均无法解决您的问题，请通过以下方式联系我们：

• 社区反馈：在 GitHub Issues 或相关社群中搜索类似问题。
• 提供信息：联系技术人员时，请务必提供：
  • 当前使用的完整版本号。
  • 问题的详细描述（包括复现步骤）。
  • 相关的系统错误日志或截图。