# 故障排除指南

## 常见问题及解决方案

### 1. 数据库字段错误

#### 问题：
```
pymysql.err.OperationalError: (1105, "errCode = 2, detailMessage = Unknown column 'xxx' in 'xxx'")
```

#### 原因：
数据库表结构与代码中使用的字段名不匹配。

#### 解决方案：
1. 查看 `DATABASE_SETUP.md` 了解如何配置字段
2. 修改对应脚本中的SQL查询，使用实际存在的字段名
3. 如果是分类字段不存在，这些字段是可选的，代码会自动跳过

#### 已修复的字段：
- ✅ `category_level2_id` 和 `category_level3_id` 现在是可选的
- ✅ 基础功能不依赖分类字段

---

### 2. 连接超时

#### 问题：
```
pymysql.err.OperationalError: (2003, "Can't connect to MySQL server...")
```

#### 解决方案：
1. 检查数据库配置：`config/offline_config.py`
2. 确认网络连接和防火墙设置
3. 运行测试：`python3 test_connection.py`

---

### 3. 内存不足

#### 问题：
程序运行时内存占用过高或被杀死。

#### 解决方案：
1. 减少回溯天数：`--lookback_days 365`（从730改为365）
2. 减少输出数量：`--top_n 20`（从50改为20）
3. 先运行单个算法：
   ```bash
   python3 scripts/i2i_session_w2v.py  # 内存占用较小
   ```
4. 跳过Swing算法（内存占用最大）：
   ```bash
   python3 run_all.py --skip-i2i
   ```

---

### 4. 运行时间过长

#### 解决方案：
1. 减少数据量：`--lookback_days 180`
2. 只运行特定算法：
   ```bash
   python3 run_all.py --only-w2v
   ```
3. 考虑使用C++版本的Swing（性能提升10倍）

---

### 5. 依赖包安装失败

#### 解决方案：
```bash
# 单独安装失败的包
pip3 install pandas sqlalchemy pymysql gensim numpy

# 或使用国内镜像
pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

---

### 6. Redis连接失败

#### 问题：
```
redis.exceptions.ConnectionError: Error connecting to Redis
```

#### 解决方案：
1. Redis是可选的，只影响索引加载功能
2. 如果不需要Redis，可以跳过：
   ```bash
   python3 run_all.py  # 只运行离线任务，不加载到Redis
   ```
3. 如果需要Redis，确认Redis已安装并运行：
   ```bash
   redis-cli ping  # 应该返回 PONG
   ```

---

### 7. 输出文件为空

#### 可能原因：
1. 数据量太少（没有满足最小阈值）
2. 时间范围内没有数据
3. SQL查询条件过于严格

#### 解决方案：
1. 检查日志：`tail -f logs/run_all_*.log`
2. 调整参数：
   - 增加时间范围：`--lookback_days 1000`
   - 减少阈值：修改配置文件中的 `min_interaction_count`
3. 检查数据库中是否有数据：
   ```python
   # 运行简单查询测试
   python3 test_connection.py
   ```

---

### 8. 权限问题

#### 问题：
```
PermissionError: [Errno 13] Permission denied
```

#### 解决方案：
```bash
# 给脚本添加执行权限
chmod +x install.sh run_all.py

# 确保有写入权限
chmod 755 output/ logs/
```

---

### 9. Python版本问题

#### 要求：
Python 3.7+

#### 检查版本：
```bash
python3 --version
```

#### 如果版本过低，需要升级Python

---

### 10. 编码问题

#### 问题：
```
UnicodeDecodeError: 'utf-8' codec can't decode byte...
```

#### 解决方案：
确保所有文件使用UTF-8编码，特别是配置文件和输出文件。

---

## 调试技巧

### 1. 查看详细日志
```bash
tail -f logs/run_all_*.log
```

### 2. 运行单个任务（便于调试）
```bash
python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10
```

### 3. 使用较小的数据量测试
```bash
python3 run_all.py --lookback_days 30 --top_n 10
```

### 4. 检查中间结果
```bash
ls -lh output/
head -n 20 output/i2i_swing_*.txt
```

---

## 获取支持

如果以上方法都无法解决问题：

1. **查看文档**：
   - `README.md` - 详细说明
   - `DATABASE_SETUP.md` - 数据库配置
   - `QUICKSTART.md` - 快速开始

2. **查看日志**：
   - `logs/` 目录下的所有日志文件

3. **简化测试**：
   - 先运行 `test_connection.py`
   - 再运行单个脚本
   - 使用小数据量测试

4. **记录错误信息**：
   - 完整的错误堆栈
   - 使用的命令
   - 配置文件内容

---

**提示**：大部分问题都与数据库字段名不匹配有关，请优先查看 `DATABASE_SETUP.md`。