TROUBLESHOOTING GUIDE
问题排查手册 6 大类常见问题与解决路径
汇总 CodeWave 实施落地中最常遇到的安装、建模、AI、部署、集成、性能 6 大类问题，每个问题给出清晰的解决步骤。
1. 安装与注册
注册账号后无法登录？
先确认邮箱激活；推荐使用 Chrome 100+/Edge 100+；如显示验证码错误，请清空浏览器 Cookie 重试；企业用户请联系管理员核实 SSO 配置是否生效。
私有化部署后端口冲突？
默认端口 80/443/8080/3306/6379。运行
netstat -ano | findstr :8080（Windows）或 lsof -i :8080（Linux）排查占用进程；可在 application.yml 修改端口后重启容器。IDE 加载白屏？
大概率为浏览器缓存或 CSP 拦截。Ctrl+Shift+R 强制刷新；F12 查看控制台是否有跨域错误；检查反向代理 Nginx 是否正确转发 WebSocket。
2. 数据建模
实体保存时报"字段类型不匹配"？
通常是历史数据与新字段类型冲突。先在 SQL 控制台运行
SELECT DISTINCT 字段 FROM 表 查看异常值；清理后再修改字段类型，或先把字段改为可空。多对多关联表查询慢？
为关联表的两个外键加联合索引；尽量使用 EXISTS 替代 IN；如查询频繁可建立物化视图缓存结果。
AI 数据建模生成的字段不合理？
AI 生成是初稿，需人工审查命名、类型与索引。建议生成后立刻用建模 IDE 整理，并加上业务规则（唯一约束、非空、默认值）。
3. AI 与连接器
AI 助手调用 DeepSeek 返回 401？
API Key 无效或过期。重新到 DeepSeek 开放平台生成 Key；检查租户出口 IP 是否在白名单；查看控制台余额。
D2C 设计稿识别率低？
建议使用清晰的 Figma 导出（PNG ≥ 2x），避免截屏或拍照；UI 元素需有清晰边界与对比度；复杂图表建议拆分多张图。
NASL 大模型生成代码不能直接运行？
大模型生成是辅助，建议结合 IDE 调试逐步细化。可对生成结果用"AI 智能助手"对话式优化，或交给开发者人工补全异常处理。
4. 部署与发布
应用发布后访问 502？
检查后端服务进程是否启动；Nginx 配置 upstream 是否正确；查看 nginx error.log 与应用日志；确保数据库连接池未超限。
不同环境配置错乱？
使用 CodeWave 多环境管理为 DEV/SIT/UAT/PROD 分别维护配置变量；发布时通过流水线自动注入；严禁在代码中硬编码 IP/Key。
灰度发布如何回滚？
在发布管理界面选择上一个稳定版本，点击"回滚"，CodeWave 会自动切换到指定版本；建议每次发布保留最近 3 个稳定版本。
5. 系统集成
钉钉/企微 SSO 登录失败？
核对 AppID/AppSecret；确认回调 URL 与钉钉开放平台一致；检查租户域名是否已添加白名单；查看服务端日志中 OAuth 报错。
REST 连接器调用第三方接口超时？
先用 curl 直接测试接口是否可达；检查 CodeWave 服务器出口 IP 是否被对方允许；调整连接器超时配置（默认 30 秒）；必要时增加重试。
SAP 集成后字段乱码？
SAP RFC 默认编码为非 UTF-8，需在连接器配置编码为 GBK 或显式声明字符集；中文字段建议长度按字节预留 2-3 倍。
6. 性能优化
应用列表加载缓慢？
数据量 > 10 万建议分页；为高频字段加索引；避免 N+1 查询，用 JOIN 预加载；用 Lighthouse 审计前端瓶颈。
报表导出 Excel 卡死？
数据 > 5 万行用流式导出；服务端调大 JVM 堆内存；建议改为后台异步任务+邮件通知，避免浏览器超时。
移动端响应慢？
启用静态资源 CDN；图片转 WebP；启用 HTTP/2；首屏关键 CSS 内联；非关键 JS 用 defer/async 加载。