AI 系统部署报错排查手册：白屏 / 502 / 超时 / 密钥一网打尽

“源码下好了，往服务器一传，白屏；改了配置，502；聊起来，一直转圈。部署 AI 系统像在闯关，每关一个错。”这是新手部署对话系统最高频的崩溃现场。报错不可怕，可怕的是瞎搜乱试。本文把报错按现象分类，每类给”看哪里、改什么”，照着走基本半小时能救活。

一、先建排查心智：报错分四层

任何 AI 系统报错归到四层之一：

• 服务器层：内存爆、进程崩、端口占。
• 环境层：PHP 扩展缺、伪静态错、权限不对。
• 接口层：Key 失效、Base URL 错、模型超时。
• 渠道层：微信回调错、HTTPS 没上、Token 配错。

定位错层=解决一半。在热点源码栏目的源码包里常附报错速查，先对照再动手。

二、白屏 / 500：九成是环境层

现象：打开空白或 500。

• 看站点 error_log（宝塔「文件」搜 error_log），第一行就是病因。
• 常见：缺 curl/redis/fileinfo 扩展 → 软件商店装上重启。
• 目录无写权限 → runtime/、storage/ 设 755。
• .env 数据库密码错 → 核对用户名密码库名。
• 伪静态未配 → 后台 404 但首页能开，粘源码给的 Nginx 规则重载。

白屏别重装，先看日志，十分钟定位。

三、502 Bad Gateway：服务器层 + 接口慢

现象：能开页面，一对话就 502。

• Nginx 反代超时：调大 fastcgi_read_timeout 到 120s。
• PHP 进程崩/OOM：2G 内存跑大模型中转易崩，升 4G。
• 模型接口太慢把 PHP 拖垮：换响应快模型或接中转。
• 看 PHP 慢日志确认是哪段卡死。

四、模型一直转圈 / 超时：接口层

现象：发消息没反应，前端转圈。

• 模型响应慢：把源码”超时时间”调大到 60-120s（默认 30s 常不够）。
• Base URL 不通：curl 测一下接口地址是否可达。
• 限流 429：免费额度用尽，升级或排队。
• 网络问题：境外接口抽风，换国产模型（见工具类系统里的国产适配）。

五、密钥 401 / invalid api key：接口层

现象：配置完对话返回 401。

• Key 复制多了首尾空格 → 去空格重填。
• Key 失效/余额不足 → 平台重新生成、查余额。
• Base URL 拼错（多了斜杠少了 v1）→ 对照文档核对。
• 文心 token 过期 → 检查定时刷新逻辑。

401 几乎都是 Key 或地址问题，别怀疑代码。

六、微信接口报错：渠道层

现象：网页能聊，微信接进来就错。

• 没上 HTTPS → 微信不让调，宝塔一键证书。
• 回调 URL/Token 不对 → 比对源码后台和公众号后台。
• 服务器配置没填 AppSecret → 补全。
• IP 白名单没加 → 公众号后台加服务器出口 IP。

七、一套可照做的排查清单

1. 开 error_log，读第一行。
2. 查 PHP 扩展 + 目录权限。
3. 配伪静态、重载 Nginx。
4. curl 测模型接口可达性。
5. 去 Key 空格、查余额。
6. 调大超时与内存。
7. 上 HTTPS、对微信配置。

逐条过，90% 报错在此闭环。参考建站 CMS部署规范，顺序别跳。

八、防大于治：部署前避坑

• 先跑环境检测脚本再上传。
• 用源码自带「报错速查表」。
• 本地镜像先跑通再上生产。
• 内存留余量（4G 比 2G 稳）。

九、谁是真受益人（把排查翻译成好处）

• 对小白：照清单半小时自救，不依赖工单等一天。
• 对运维：四层定位法让排错有条理，不盲试。
• 对站长：系统早一分钟活，少漏一分钟咨询。

十、花钱买”不卡关”的售后是隐形的效率（借口）

别把”出问题自己扛”当本事。一套带文档和售后的源码，报错时有人指点是真金白银的效率——你省下的排错时间，够接两单业务。买源码买的不是不报错（那不可能），是”报错时有人拉你一把”的兜底。对做业务的人来说，售后是给运维上的保险，不是溢价。

---

最后划重点：AI 部署报错按四层定位——服务器、环境、接口、渠道。白屏看日志补扩展，502 调超时升内存，转圈调大超时换模型，401 查 Key 和地址，微信错查 HTTPS 和回调。把清单存手机，排错不再慌。

📦 卓创源码网：每套对话系统源码开源可验 + 报错速查 + 部署售后兜底，拒绝加密废包。浏览对应栏目：{{下载页链接}} 🔗 部署流程看：AI对话系统源码部署教程