LyEdu 常见问题
编辑日期：2026-02-26
基于 ly-edu 项目与使用反馈整理
一、开发环境
1. 一键启动脚本报错
现象：.\scripts\dev\start.ps1 执行失败。
排查：
- 确认已复制
dev-config.example.yml为dev-config.yml - 检查
database、redis连接信息是否正确 - 若本机无 MySQL，设置
start_docker_mysql_redis: true，确保 Docker 已启动 - PowerShell 执行策略：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
2. Python 依赖安装失败
现象：pip install -r requirements.txt 报错。
排查：
- 使用 Python 3.10+，确认
python --version - 使用国内源：
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple - 若缺少
openpyxl等，可单独pip install openpyxl
3. 前端 npm install 慢或失败
现象：依赖安装超时或网络错误。
解决：
- 配置 npm 镜像：
npm config set registry https://registry.npmmirror.com - 或在
scripts/docker/.env中配置NPM_REGISTRY - 使用 pnpm：
pnpm install（若项目支持）
4. 数据库迁移失败
现象：alembic upgrade head 或 Flyway 报错。
排查：
- 确认数据库已创建，且用户有足够权限
- 检查
DATABASE_URL/application.yml中的库名、字符集 - 若表已存在冲突，可先备份，再根据报错信息决定是否
downgrade或手动修复
二、Feishu 集成
1. Feishu 登录失败
现象：扫码后无法登录或提示错误。
排查：
- App ID、App Secret 是否正确
- 回调地址是否与 Feishu 应用配置一致（含协议、域名、路径）
- Feishu 应用是否已发布/生效，权限是否已开通
- 网络能否访问
open.feishu.cn
2. 通讯录同步不完整
现象：部门或用户同步缺失。
排查：
- 检查 Feishu 应用是否有通讯录读取权限
- 查看同步日志或管理后台的同步记录
- 是否有 API 调用频率限制导致的失败
三、视频与播放
1. 视频无法播放
现象：视频加载失败或黑屏。
排查：
- 确认视频已成功上传，文件存在且可读
- 检查视频格式（推荐 MP4、WebM）
- 浏览器控制台是否有 CORS、404 等错误
- 若使用 CDN，检查 CDN 配置与回源
2. 播放器防拖拽/禁倍速不生效
现象：配置了仍可拖拽或倍速。
排查：
- 在「系统配置」→「播放器配置」中确认已保存
- 清除浏览器缓存后重试
- 确认前端播放器组件已读取该配置
四、部署与运行
1. Docker 容器启动失败
现象：docker compose up -d 后容器退出。
排查：
docker compose logs api查看日志- 确认 MySQL、Redis 先于 API 启动完成
- 检查环境变量、数据卷挂载是否正确
2. 系统运行缓慢
现象：页面加载慢、接口响应慢。
排查：
- 检查 CPU、内存、磁盘 IO
- 优化数据库索引与慢查询
- 配置 Redis 缓存热点数据
- 视频等大文件考虑 CDN 或对象存储
3. 访问 404 或路由错误
现象：刷新页面或直接访问子路径出现 404。
排查：
- Nginx/Caddy 需配置 SPA fallback：
try_files $uri $uri/ /index.html - 检查前端
base或publicPath与部署路径是否一致
五、考试与证书
1. 考试提交失败
现象：交卷时报错或成绩未保存。
排查：
- 检查网络与 API 状态
- 查看后端日志是否有异常
- 确认考试未过期、未重复提交
2. 证书未生成
现象：学习/考试完成但无证书。
排查：
- 确认证书规则与任务/考试关联正确
- 检查证书模板是否已配置
- 查看任务完成状态与颁证逻辑