故障排查
排查注意
FastGPT注意事项
注意事项
在使用 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/16TRUSTED_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 或相关社群中搜索类似问题。
- 提供信息：联系技术人员时，请务必提供：
- 当前使用的完整版本号。
- 问题的详细描述（包括复现步骤）。
- 相关的系统错误日志或截图。