ljwx-stock/TROUBLESHOOTING.md

故障排除和常见问题

前端连接问题

问题：前端无法连接到API (Failed to fetch)

原因：CORS跨域问题或API URL配置错误

解决方案：

1. 清除浏览器缓存 (Ctrl+Shift+Del)
2. 刷新页面
3. 检查nginx是否运行：docker compose ps frontend
4. 查看前端日志：docker compose logs frontend
5. 测试API直接访问：curl http://85.239.237.116:8001/health

快速修复流程：

# 重建前端
docker compose build frontend --no-cache
docker compose restart frontend
sleep 30

# 清除浏览器缓存并访问
# http://85.239.237.116:8090/

---

数据源问题

问题：获得的是Mock数据而不是真实数据

原因：

1. TuShare token无效 ("token不对，请确认")
2. yfinance无法获取A股数据 ("No price data found")
3. 系统退回到使用Mock数据

查看数据源：

# 检查日志
docker compose logs backend | grep -E "(Fetching|TuShare|yfinance|Using mock)"

获取真实数据：

方式1：更新TuShare token

# 1. 访问 https://tushare.pro/ 获取有效token
# 2. 编辑 .env
TUSHARE_TOKEN=your_new_valid_token

# 3. 重启backend
docker compose restart backend

# 4. 等待缓存过期或清除缓存
docker compose exec redis redis-cli FLUSHALL

方式2：使用其他数据源

• 修改 backend/app/modules/data_fetcher.py
• 实现新的 _fetch_bloomberg_data() 或其他API
• 更新优先级顺序

---

后端API问题

问题：API返回500错误

检查步骤：

# 1. 查看后端日志
docker compose logs backend | tail -100

# 2. 检查容器状态
docker compose ps backend

# 3. 重启后端
docker compose restart backend

# 4. 清除缓存
docker compose exec redis redis-cli FLUSHALL

常见错误及解决方案：

错误	原因	解决方案
Database connection failed	PostgreSQL连接失败	docker compose restart postgres
Feature shape mismatch	ML模型配置错误	重建后端：docker compose build backend --no-cache
Cannot access local variable	Python代码错误	检查日志找到具体行号，修复代码
Redis connection error	缓存层失败	docker compose restart redis

---

数据库问题

查看数据库状态：

# 检查PostgreSQL
docker compose exec postgres pg_isready

# 连接到数据库
docker compose exec postgres psql -U stock_user -d stock_db

# 查看表
\dt

# 退出
\q

重置数据库：

# 删除数据并重新初始化
docker compose down -v
docker compose up -d

---

缓存问题

清除所有缓存：

docker compose exec redis redis-cli FLUSHALL

查看缓存统计：

docker compose exec redis redis-cli INFO stats

查看缓存中的键：

docker compose exec redis redis-cli KEYS "*"

---

系统健康检查

# 完整系统检查
docker compose ps

# 资源使用情况
docker stats

# 检查所有API端点
curl http://85.239.237.116:8001/health

# 测试推荐API
curl http://85.239.237.116:8001/api/recommendations | python3 -m json.tool

# 检查前端
curl -I http://85.239.237.116:8090/

---

性能优化

如果API响应缓慢：

# 1. 清除缓存
docker compose exec redis redis-cli FLUSHALL

# 2. 重启后端
docker compose restart backend

# 3. 检查日志
docker compose logs backend | grep -E "(error|Error|ERROR|took)"

# 4. 如需要，重建后端
docker compose build backend --no-cache
docker compose restart backend

优化缓存TTL：

编辑 .env 文件：

# 增加缓存时间（秒）
CACHE_TTL_QUOTE=120          # 从60增加到120
CACHE_TTL_FEATURES=600       # 从300增加到600
CACHE_TTL_RECOMMENDATION=300 # 从60增加到300

---

日志查看

# 实时查看所有日志
docker compose logs -f

# 只看后端日志
docker compose logs -f backend

# 只看前端日志
docker compose logs -f frontend

# 只看最后100行
docker compose logs --tail=100 backend

# 结合grep搜索特定内容
docker compose logs backend | grep -E "(error|warning|ERROR|WARNING)"

---

完全重启系统

如果遇到无法解决的问题，可以尝试完全重启：

# 停止所有容器
docker compose down

# 删除数据（警告：会删除所有数据）
docker compose down -v

# 重新构建所有镜像
docker compose build --no-cache

# 重新启动
docker compose up -d

# 等待30秒让所有服务启动
sleep 30

# 验证状态
docker compose ps

---

获得帮助

1. 查看日志：docker compose logs [service]
2. 查看docs目录中的文档
3. 检查API文档：http://85.239.237.116:8001/docs
4. 测试单个组件的健康状态

---

快速命令参考

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f backend

# 重启服务
docker compose restart backend

# 清除缓存
docker compose exec redis redis-cli FLUSHALL

# 测试API
curl http://85.239.237.116:8001/health

# 数据库访问
docker compose exec postgres psql -U stock_user stock_db