troubleshooting-guide

故障排除和部署指南

常见问题诊断

项目结构问题

问题：模块导入失败

症状: ModuleNotFoundError: No module named 'xxx' 排查步骤:

1. 检查backend目录是否有__init__.py文件
2. 确认使用相对导入：from .module_name import ClassName
3. 验证启动脚本中的导入路径：from backend.module_name import ClassName
4. 检查Python路径设置和工作目录

问题：包结构错误

症状: 导入成功但运行时出现属性错误 排查步骤:

1. 确认所有Python文件都在正确的目录中
2. 检查backend/init.py文件存在
3. 验证相对导入路径的正确性
4. 重新启动Python解释器清除缓存

服务器启动问题

问题：FastAPI服务器无法启动

症状: 运行python start_game.py时出现错误 排查步骤:

1. 检查Python版本 (需要3.7+)
2. 验证依赖安装: pip install -r requirements.txt
3. 检查端口占用: netstat -an | findstr :8000
4. 查看错误日志中的具体错误信息
5. 确认backend包结构正确

问题：OpenAI API连接失败

症状: AI对话功能不工作，返回API错误 排查步骤:

1. 检查.env文件中的OPENAI_API_KEY
2. 验证API密钥有效性和余额
3. 检查网络连接和防火墙设置
4. 查看backend/ai_service.py中的错误处理
5. 确认backend/config.py配置正确

前端问题诊断

问题：页面无法加载或显示空白

症状: 浏览器显示空白页面或加载失败 排查步骤:

1. 打开浏览器开发者工具查看控制台错误
2. 检查网络标签页中的HTTP请求状态
3. 验证静态文件路径是否正确
4. 检查frontend/desktop.html中的资源引用
5. 确认FastAPI服务器正常运行

问题：角色对话显示异常

症状: 切换角色时对话历史显示错误或重复 排查步骤:

1. 检查conversationHistory数组结构
2. 验证showCharacterConversation()方法逻辑
3. 查看浏览器控制台中的JavaScript错误
4. 确认角色ID和名称匹配正确
5. 检查会话状态管理

问题：流式输出不工作

症状: AI回答不是逐字显示，而是一次性出现 排查步骤:

1. 检查浏览器是否支持Server-Sent Events
2. 验证流式API端点是否正常工作
3. 查看网络请求中的响应类型
4. 检查frontend/static/js/desktop.js中的流式处理逻辑

WebSocket连接问题

问题：实时通信失败

症状: 游戏状态不同步，WebSocket连接断开 排查步骤:

1. 检查WebSocket连接URL是否正确
2. 验证session_id是否有效
3. 查看服务器端WebSocket处理逻辑
4. 检查网络代理或防火墙设置
5. 监控连接重试机制

问题：会话管理异常

症状: 游戏状态丢失或会话过期 排查步骤:

1. 检查会话ID生成和存储
2. 验证会话超时设置
3. 查看服务器内存中的会话管理
4. 检查浏览器本地存储

调试技巧

前端调试

JavaScript调试

// 在关键位置添加调试信息
console.log('当前游戏状态:', this.gameState);
console.log('对话历史:', this.conversationHistory);
console.log('选中角色:', this.selectedCharacter);

// 使用断点调试
debugger; // 浏览器会在此处暂停执行

// 检查DOM元素状态
console.log('角色列表元素:', document.getElementById('character-list'));
console.log('对话区域:', document.getElementById('conversation-area'));

// 监控状态变化
const originalUpdateState = this.updateGameState;
this.updateGameState = function(newState) {
    console.log('状态更新前:', this.gameState);
    console.log('新状态:', newState);
    originalUpdateState.call(this, newState);
    console.log('状态更新后:', this.gameState);
};