# run.sh 运行脚本使用指南

## 概述

`run.sh` 是一个自动化运行脚本，集成了内存监控功能，确保离线任务安全高效运行。

## 主要特性

### 1. 内存监控
- **警告阈值**: 25GB - 打印警告日志
- **强制终止阈值**: 30GB - 自动kill进程
- **检查频率**: 每10秒检查一次
- **日志文件**: `logs/memory_monitor.log`

### 2. 任务流程
1. 清理旧进程和输出
2. 运行调试模式（小数据量测试）
3. 运行生产模式（大数据量）
4. 加载索引到Redis

### 3. 错误处理
- 任何步骤失败会立即退出
- 显示详细的退出码
- 保存完整日志

## 使用方法

### 基本运行
```bash
cd /home/tw/recommendation/offline_tasks
./run.sh
```

### 查看实时输出
```bash
./run.sh | tee logs/run_$(date +%Y%m%d_%H%M%S).log
```

### 后台运行
```bash
nohup ./run.sh > logs/run_$(date +%Y%m%d_%H%M%S).log 2>&1 &
```

## 内存监控说明

### 监控逻辑

```bash
check_memory() {
    local pid=$1
    local threshold_warn=25  # 25GB警告
    local threshold_kill=30  # 30GB强制kill
    
    while 进程运行中; do
        获取内存使用
        
        if 内存 >= 30GB:
            打印错误日志
            强制终止进程
            break
        elif 内存 >= 25GB:
            打印警告日志
        
        sleep 10秒
    done
}
```

### 日志格式

**警告日志**:
```
[2025-10-17 14:30:25] ⚠️  内存警告！当前使用: 26.45GB (>= 25GB), PID=12345
```

**强制终止日志**:
```
[2025-10-17 14:35:30] ❌ 内存超限！当前使用: 31.20GB (>= 30GB), 强制终止进程 PID=12345
```

### 查看监控日志
```bash
# 实时查看
tail -f logs/memory_monitor.log

# 查看历史
cat logs/memory_monitor.log
```

## 运行流程

### 步骤1: 调试模式
```bash
python3 run_all.py --debug
```
- 使用默认参数（见 `offline_config.py`）
- 输出保存到 `output_debug/`
- 启动内存监控

### 步骤2: 生产模式
```bash
python3 run_all.py --debug
```
- 生成完整索引
- 输出保存到 `output/`
- 启动内存监控

### 步骤3: 加载Redis
```bash
python3 scripts/load_index_to_redis.py --redis-host localhost
```
- 加载所有生成的索引
- 包括新增的内容相似索引

## 输出示例

```
======================================================================
开始运行离线任务 - 2025-10-17 14:00:00
内存监控: 警告阈值=25GB, 强制终止阈值=30GB
======================================================================

>>> 步骤1: 调试模式运行（小数据量）
调试任务 PID: 12345
✓ 调试模式完成

>>> 步骤2: 生产模式运行（大数据量）
生产任务 PID: 12346
[2025-10-17 14:30:25] ⚠️  内存警告！当前使用: 26.45GB (>= 25GB), PID=12346
✓ 生产模式完成

>>> 步骤3: 加载到Redis
✓ Redis加载完成

======================================================================
所有任务完成 - 2025-10-17 16:30:00
======================================================================
```

## 自定义配置

### 修改内存阈值

编辑 `run.sh` 中的以下行：
```bash
local threshold_warn=25  # 修改警告阈值
local threshold_kill=30  # 修改强制kill阈值
```

### 修改检查频率

编辑 `run.sh` 中的以下行：
```bash
sleep 10  # 修改为其他秒数
```

### 跳过调试模式

注释掉步骤1相关代码：
```bash
# # 3. 调试模式运行（小数据量）
# echo ""
# echo ">>> 步骤1: 调试模式运行（小数据量）"
# python3 run_all.py --debug &
# ...
```

### 修改Redis配置

修改步骤3的参数：
```bash
python3 scripts/load_index_to_redis.py \
  --redis-host your-redis-host \
  --redis-port 6379 \
  --redis-db 0
```

## 故障排查

### 内存持续超限

**原因**:
- 数据量太大
- 内存泄漏
- 并发任务过多

**解决方案**:
1. 增加内存阈值（临时方案）
2. 优化代码减少内存占用
3. 分批处理数据
4. 使用增量更新

### 进程被意外终止

**检查日志**:
```bash
# 查看监控日志
cat logs/memory_monitor.log

# 查看任务日志
ls -lht logs/
cat logs/run_all_*.log
```

### 任务失败

**查看退出码**:
- 0: 成功
- 1: 一般错误
- 137: 被kill信号终止（可能是内存超限）
- 其他: 查看具体错误信息

## 监控建议

### 1. 添加系统监控
```bash
# 安装监控工具
apt install htop iotop

# 实时监控
htop -p $(pgrep -f run_all.py)
```

### 2. 设置告警
```bash
# 配置邮件告警
if [ $PROD_EXIT_CODE -ne 0 ]; then
    echo "任务失败" | mail -s "离线任务告警" admin@example.com
fi
```

### 3. 定时任务
```bash
# 添加到crontab
0 2 * * * /home/tw/recommendation/offline_tasks/run.sh >> /var/log/offline_tasks.log 2>&1
```

## 性能优化

### 内存优化建议

1. **分批处理**
   ```python
   # 在代码中使用batch处理
   batch_size = 1000
   for i in range(0, len(items), batch_size):
       batch = items[i:i+batch_size]
       process(batch)
   ```

2. **及时释放**
   ```python
   import gc
   del large_object
   gc.collect()
   ```

3. **使用生成器**
   ```python
   def process_items():
       for item in items:
           yield process(item)
   ```

## 日志管理

### 日志文件
- `logs/memory_monitor.log` - 内存监控日志
- `logs/run_all_YYYYMMDD.log` - 任务运行日志
- `output/` - 生成的索引文件
- `output_debug/` - 调试模式输出

### 清理旧日志
```bash
# 保留最近7天
find logs/ -name "*.log" -mtime +7 -delete

# 压缩旧日志
find logs/ -name "*.log" -mtime +3 -exec gzip {} \;
```

## 安全注意事项

1. **权限**: 确保脚本有执行权限 `chmod +x run.sh`
2. **路径**: 使用绝对路径避免混淆
3. **清理**: 脚本会清理旧进程，确保没有重要进程被误杀
4. **备份**: 脚本会删除output目录，请提前备份重要数据

## 总结

`run.sh` 提供了：
- ✅ 自动化运行流程
- ✅ 内存监控保护
- ✅ 详细日志记录
- ✅ 错误处理机制
- ✅ 进度显示

建议在生产环境使用前先在测试环境验证。

---

**更新时间**: 2025-10-17  
**版本**: v2.0