企业官网建设流程全解析

Next AI Draw.io 故障排查完整指南：10 分钟定位 AI 绘图不生效、白屏与保存卡顿

【免费下载链接】next-ai-draw-ioA next.js web application that integrates AI capabilities with draw.io diagrams. This app allows you to create, modify, and enhance diagrams through natural language commands and AI-assisted visualization.项目地址: https://gitcode.com/GitHub_Trending/ne/next-ai-draw-io

Next AI Draw.io 是一款用自然语言生成和修改 draw.io 图表的 AI 绘图工具，你输入一句话，它就把图表画出来。当界面白屏、AI 不出图、保存失败或启动报错时，这份指南带你按「先分诊 → 再速查 → 再深挖 → 再预防」的路径，一步步把问题定位到具体环节并修好。

先定位：三步自检

这一节帮你在动手修之前，先用 10 分钟判断问题出在环境、配置还是服务本身。

第 1 步：环境和网络。打开浏览器访问http://localhost:6002（开发模式默认端口），确认页面能加载。绘图画布依赖 draw.io 的内嵌服务，内网或离线部署时需要把NEXT_PUBLIC_DRAWIO_BASE_URL指向可访问的自建 draw.io 地址，否则画布区域会一直空白。这步不通，先看浏览器控制台是否有网络拦截报错。

第 2 步：配置和密钥。检查.env文件（可对照仓库里的env.example）：AI_PROVIDER选了哪个供应商，对应的*_API_KEY是否已填，AI_MODEL的模型 ID 是否与供应商匹配。密钥缺失或模型 ID 写错时，AI 功能会直接报错而不是卡住。这步不通，先看服务端输出的具体报错关键词（如 invalid key、model not found）。

第 3 步：服务与依赖状态。确认依赖装全了（npm install是否有失败项）、Node.js 版本满足要求、端口没被其他进程占用。Docker 用户则检查容器是否处于运行状态、端口映射是否正确。这步不通，先看服务进程的启动日志。

高频故障速查表

这一节把最常见的六类症状对应的直接修复动作列出来，先对号入座。

深入排查：三个典型场景

速查表没覆盖到的情况，按下面三个高频场景深挖。

场景一：启动失败自查（服务起不来或起来就崩）

症状：执行npm run dev或 Docker 启动后，页面打不开、端口无响应，或启动日志直接报错退出。

可能原因：

1. 依赖未装全，npm install阶段有包安装失败
2. 6002/3000 端口被其他进程占用
3. Node.js 版本过低，不满足 Next.js 16 的运行要求

逐步修复：

1. 删掉node_modules后重新npm install，观察是否有失败项
2. 用端口占用检查命令确认端口空闲，或在启动参数里改用其他端口
3. 升级 Node.js 到较新版本（LTS 即可）再启动
4. 仍失败则保留完整启动日志，对照package.json的依赖版本核对是否冲突

场景二：API 密钥配置检查（AI 功能报错或不绘图）

症状：界面正常，但发送自然语言指令后没有图表产出，或弹出报错提示。

可能原因：

1. AI_PROVIDER与实际填写的密钥不配套（比如选了 openai 却只填了 Anthropic 的 key）
2. 模型 ID 拼错或该供应商已下线该模型
3. 多模型配置AI_MODELS_CONFIG/ai-models.json的 JSON 格式有误

逐步修复：

1. 打开 docs/en/ai-providers.md 按供应商小节逐项核对密钥与环境变量名
2. 用供应商官方的文档确认模型 ID 拼写，替换AI_MODEL中的值
3. 如使用多模型 JSON 配置，先精简为单个模型验证链路是否通
4. 修改.env后重启服务，再发一条最简单的指令（如"画一个登录流程图"）验证

场景三：画布空白排查（离线/内网部署）

症状：聊天区正常，但右侧绘图区空白，提示找不到embed.diagrams.net。

可能原因：

1. 内网环境访问不了公网 draw.io 服务
2. 自建 draw.io 的地址填成了 Docker 内部别名（如http://drawio:8080），浏览器解析不了
3. 改了NEXT_PUBLIC_*变量但没有重新构建——这类变量是构建期打包进前端代码的，运行时修改无效

逐步修复：

1. 确认浏览器能直接访问你配置的 draw.io 地址（注意必须是http://YOUR_SERVER_IP:8080这种浏览器可达的地址）
2. 在 Docker 构建的args中传入NEXT_PUBLIC_DRAWIO_BASE_URL，重建镜像
3. 按 docs/en/docker.md 的示例核对 compose 配置
4. 重建后清缓存强刷页面验证

配置与部署排查清单

部署类问题基本都藏在这份清单里，逐项勾掉：

• .env已按env.example补全必填项，AI_PROVIDER、AI_MODEL、对应密钥三者配套
• 子目录部署时已设置NEXT_PUBLIC_BASE_PATH（如/nextaidrawio）
• NEXT_PUBLIC_*类变量改动后已重新构建（运行时修改不生效）
• Docker 部署时端口映射正确，ai-models.json挂载路径与AI_MODELS_CONFIG_PATH一致
• 反向代理场景下已按需调整ALLOW_PRIVATE_URLS安全开关
• 域名解析指向正确实例，SSL 证书未过期，HTTPS 下资源无混合内容拦截

日志速查：去哪里找答案

• 浏览器控制台（F12）：白屏、画布不加载、网络请求被拦截，第一眼都看这里
• 终端 / 容器日志：docker logs <容器名>或服务进程输出，含 API 报错、构建错误、依赖冲突
• data/settings.json：管理后台修改过的运行时设置都存这里，且优先级高于环境变量，配置"改了没生效"先查它
• Langfuse 追踪面板：若配置了LANGFUSE_*变量，可逐条查看 LLM 请求的完整链路，定位"只思考不出图"类问题

一次到位的预防动作

1. 锁定模型版本：在AI_MODEL里指定带版本号的稳定模型，避免供应商升级后行为突变。
2. 配置变更后强刷验证：改.env或后台设置后，重启服务并强刷页面，防止旧构建/旧缓存误导判断。
3. 定期清理浏览器缓存：本地存储里的会话和图表数据偶发损坏，清缓存是最快的兜底手段。
4. 启用可观测性：配置 Langfuse 追踪，线上出问题时能直接看到每次模型调用的输入输出，省掉大量猜测。

排查到这里，多数问题都能收敛到"环境、密钥、构建"三板斧之一。保留好你的启动日志和浏览器控制台输出，下次再遇到疑难杂症，它们就是最快的线索。

【免费下载链接】next-ai-draw-ioA next.js web application that integrates AI capabilities with draw.io diagrams. This app allows you to create, modify, and enhance diagrams through natural language commands and AI-assisted visualization.项目地址: https://gitcode.com/GitHub_Trending/ne/next-ai-draw-io