# 持续运行模式说明

## 概述

程序已优化为持续运行模式，不再需要复杂的自动重启脚本。程序会一直运行，每次处理一条记录，包含完善的异常处理和自动恢复机制。

## 主要特性

### 1. 持续运行
- 配置 `max_cycles = 0` 表示无限循环，程序会持续运行
- 配置 `max_cycles > 0` 表示运行指定次数后退出（旧模式）

### 2. 心跳文件
程序会定期更新心跳文件 `heartbeat_{environment}.txt`，包含以下信息：
```json
{
    "timestamp": "2025-01-15 10:30:45",
    "cycle": 123,
    "status": "running",
    "pid": 12345
}
```

**状态说明**：
- `started` - 程序启动
- `processing` - 正在处理数据
- `success` - 处理成功
- `warning` - 处理有警告
- `error` - 发生错误
- `database_error` - 数据库错误
- `stopped` - 程序停止

### 3. 异常处理和自动恢复

#### 连续错误处理
- 程序会跟踪连续错误次数
- 当连续错误达到10次时，自动重新初始化服务
- 重新初始化包括：
  - 清理旧的数据库连接
  - 重新建立数据库连接
  - 重置错误计数器

#### 错误类型处理
- **数据库错误** (`PDOException`): 自动重连和重试
- **其他异常**: 记录日志并继续运行
- **致命错误**: 程序退出（需要手动重启）

### 4. 进程锁机制
- 使用锁文件 `sync_{environment}.lock` 防止多个实例同时运行
- 锁文件包含进程PID
- 程序启动时检查锁文件，如果进程已存在则拒绝启动
- 程序退出时自动清理锁文件

## 配置说明

### config/app.php

```php
return [
    'sync_interval' => 5,  // 每次处理后等待的秒数
    'max_cycles' => 0,     // 0 = 持续运行，>0 = 运行指定次数后退出
    // ... 其他配置
];
```

## 使用方法

### 启动程序

**测试环境**:
```bash
start-test.bat
# 或
php bin/sync.php env=test
```

**生产环境**:
```bash
start-prod.bat
# 或
php bin/sync.php env=prod
```

### 停止程序

按 `Ctrl+C` 停止程序，程序会自动清理资源：
- 清理锁文件
- 清理心跳文件
- 关闭数据库连接

### 监控程序

#### 检查程序是否运行
```bash
# Windows
tasklist | findstr php.exe

# 查看心跳文件
type heartbeat_prod.txt
```

#### 心跳文件监控
可以通过监控心跳文件来判断程序状态：
- 如果心跳文件不存在 → 程序未运行
- 如果心跳时间超过2分钟未更新 → 程序可能卡死
- 如果状态一直是 `error` → 程序遇到问题

## 运行流程

```
启动程序
    ↓
创建锁文件
    ↓
初始化服务
    ↓
创建心跳文件
    ↓
进入主循环 ←─────────┐
    ↓                 │
更新心跳(processing)  │
    ↓                 │
处理一条记录          │
    ↓                 │
更新心跳(success/warning/error)
    ↓                 │
等待指定秒数          │
    ↓                 │
检查是否继续 ─────────┘
    ↓ (退出)
清理资源
    ↓
删除锁文件
    ↓
删除心跳文件
    ↓
程序结束
```

## 异常恢复流程

```
发生异常
    ↓
记录错误日志
    ↓
增加连续错误计数
    ↓
更新心跳(error)
    ↓
连续错误 < 10次？
    ↓ 是
等待后重试 ──→ 继续循环
    ↓ 否
清理旧服务
    ↓
重新初始化服务
    ↓
重置错误计数
    ↓
继续循环
```

## 优势

1. **简单**: 不需要复杂的监控脚本
2. **稳定**: 自动处理异常和恢复
3. **可监控**: 通过心跳文件实时了解程序状态
4. **不会卡死**: 每次处理一条记录，处理完就等待
5. **不会异常退出**: 完善的异常处理机制
6. **资源安全**: 自动清理锁文件和心跳文件

## 注意事项

1. **只运行一个实例**: 锁文件机制确保同一环境只有一个实例运行
2. **手动停止**: 使用 Ctrl+C 优雅停止，不要直接杀进程
3. **监控心跳**: 定期检查心跳文件确保程序正常运行
4. **日志查看**: 出现问题时查看日志文件了解详情

## 从旧模式迁移

（注：`auto-restart.bat` 已于 2026-08-24 随仓库清理移除，旧模式不再可用，本节仅供理解历史。）

如果你之前使用 `auto-restart.bat` 方式：

1. 停止 `auto-restart.bat`
2. 修改 `config/app.php` 中的 `max_cycles` 为 `0`
3. 直接运行 `start-prod.bat` 或 `start-test.bat`
4. 程序会持续运行，不再需要监控脚本

## 故障排查

### 程序无法启动
- 检查是否已有实例在运行
- 检查锁文件是否存在：`sync_{environment}.lock`
- 如果确认没有其他实例，删除锁文件后重试

### 程序频繁重新初始化
- 检查数据库连接是否稳定
- 查看日志文件了解具体错误
- 检查网络连接

### 心跳文件不更新
- 程序可能卡死，需要重启
- 检查进程是否还在运行
- 查看日志文件最后的记录