首页 › 部署运维 › 常见问题
部署运维

常见问题排查

本页汇总了安装、配置和运行 EduBuddy 过程中最常见的问题及解决方案。

🔧 安装问题

问题：better-sqlite3 编译失败

错误信息：gyp ERR! build error 或 node-gyp error

原因：系统缺少 C++ 编译工具链。

解决方案：

# Ubuntu / Debian
sudo apt install -y build-essential python3 node-gyp

# 安装后清理并重新安装
cd backend
rm -rf node_modules package-lock.json
npm install

如果仍然失败，可尝试使用预构建二进制：

cd backend
npx node-pre-gyp install --fallback-to-build=false \
  -C ./node_modules/better-sqlite3

最终方案：使用 Docker 部署，无需本地编译。

问题：Node.js 版本不兼容

错误信息：engine "node" is incompatible 或语法错误

解决方案：确保 Node.js 版本 ≥ 18.x：

node --version  # 应显示 v18.x.x 或以上

# 使用 nvm 切换版本
nvm install 20
nvm use 20

问题：npm install 网络超时

解决方案：配置国内镜像源：

# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com

# 或使用 cnpm
npm install -g cnpm
cnpm install

🚀 启动问题

问题：后端启动报 "端口已被占用"

错误信息：Error: listen EADDRINUSE :::3001

# 查找占用 3001 端口的进程
lsof -i :3001
# 或
ss -tulnp | grep 3001

# 终止进程
kill -9 <PID>

# 或修改 .env 中的 PORT 为其他端口
PORT=3002

问题：前端无法连接后端（CORS 错误）

错误信息：浏览器控制台出现 Access-Control-Allow-Origin 错误

排查步骤：

  1. 确认后端已启动，访问 http://localhost:3001/health 应返回 JSON
  2. 确认前端 VITE_API_URL 正确（默认 http://localhost:3001/api）
  3. 确认后端 CORS 配置包含前端地址（localhost:5173 或 localhost:3000）
# 检查后端 CORS 配置（server.ts）
# 开发环境应包含：
origin: ['http://localhost:3000', 'http://localhost:5173']

问题：数据库初始化失败

错误信息：SQLITE_CANTOPEN: unable to open database file

# 确保数据目录存在且有写权限
mkdir -p ./data
chmod 755 ./data

# 检查 DB_PATH 配置
cat backend/.env | grep DB_PATH

🤖 AI 功能问题

问题：AI 接口返回 "AI服务暂时不可用"

原因：API Key 无效、网络不通、或余额不足。

排查步骤：

# 测试 API 连通性
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models

# 检查 .env 中的配置
cat backend/.env | grep OPENAI

问题：图片 OCR 不工作

原因：所使用的模型不支持 Vision（多模态）功能。

解决方案：将 OPENAI_MODEL 改为支持 Vision 的模型：

OPENAI_MODEL=gpt-4o
# 或
OPENAI_MODEL=gpt-4-vision-preview

问题：语音转文字不工作

原因：Whisper API 目前只有 OpenAI 官方支持，第三方兼容 API 通常不提供。

解决方案：使用 OpenAI 官方 API Key，或改用文本/图片方式录入题目。

问题：AI 生成题目返回格式错误

错误信息：AI返回格式异常，请重试

原因：某些较小的模型（特别是本地模型）可能无法严格遵循 JSON 格式输出。

解决方案：

问题：AI 接口触发速率限制（429）

原因：AI 接口默认限制 20 次/分钟。

解决方案：等待 1 分钟后重试。如需调整限制，修改 backend/src/server.ts：

const aiLimiter = rateLimit({
  windowMs: 60000,
  max: 50,  // 调整为更大的值
  ...
});

📤 文件上传问题

问题：上传文件返回 413 错误

原因：文件超过默认 10MB 限制。

解决方案：在 .env 中调整：

MAX_FILE_SIZE=20971520  # 20MB（单位：字节）

如使用 Nginx，还需在 Nginx 配置中添加：

client_max_body_size 20M;

问题：PDF 解析内容为空或乱码

原因：部分 PDF 为扫描版（图片 PDF），不含可提取文字。

解决方案：对扫描版 PDF，截图后使用「图片识别」功能代替 PDF 上传。

🖥️ 前端问题

问题：登录后页面空白或一直 loading

排查步骤：

  1. 打开浏览器开发者工具（F12）查看 Console 和 Network 标签页
  2. 检查是否有 API 请求失败（红色条目）
  3. 清除 localStorage：localStorage.clear()，然后刷新页面

问题：图表不显示

原因：可能是还没有任何练习数据，图表数据为空。

解决方案：先完成几道练习题，再查看进度页面。

问题：语音朗读没有声音

原因：浏览器 Web Speech API 支持情况不同，或音量/静音设置问题。

解决方案：

🔑 认证问题

问题：登录后频繁退出登录

原因：JWT Token 过期（默认 7 天），或服务端重启时 JWT_SECRET 发生变化（使用了随机生成的临时密钥）。

解决方案：在 .env 中设置固定的 JWT_SECRET，避免每次启动时变化：

JWT_SECRET=your-fixed-secret-key-that-never-changes

问题：注册时提示"用户名或邮箱已存在"

用户名和邮箱在系统中是唯一的。请换一个用户名或邮箱重新注册。

📊 性能问题

问题：AI 接口响应很慢

AI 接口响应时间取决于：

前端对上传/AI 接口设置了 120 秒超时，通常足够。如果经常超时，可考虑切换到响应更快的模型（如 DeepSeek）。

问题：数据库查询变慢

随着数据量增长，可检查索引是否正确创建：

# 连接数据库检查
sqlite3 ./data/edubuddy.db
.indexes
# 应显示 idx_practice_records_user、idx_knowledge_mastery_user 等索引
.quit

📋 获取帮助

如果以上方案无法解决你的问题，可以：