648 lines
24 KiB
Markdown
648 lines
24 KiB
Markdown
# 6.11 定时任务
|
||
|
||
:::tip 概述
|
||
定时任务系统由三部分组成：`JobService`（调度逻辑）+ `BaseTask`（任务处理器）+ Artisan 命令（`job:run` / `job:daemon` 命令行入口）。支持三种触发方式：Linux Crontab、Windows 计划任务、Daemon 守护进程。
|
||
:::
|
||
|
||
## 系统架构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 触发层（三选一） │
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ Linux Crontab│ │Windows 计划 │ │ Daemon 守护 │ │
|
||
│ │ │ │任务 │ │ 进程 │ │
|
||
│ │ * * * * * │ │ schtasks │ │ php artisan │ │
|
||
│ │ php artisan │ │ │ │ job:daemon │ │
|
||
│ │ job:run │ │ │ │ │ │
|
||
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
|
||
│ │ │ │ │
|
||
│ └─────────────────┼─────────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────────────────────┐ │
|
||
│ │ JobRunCommand / JobDaemon │ │
|
||
│ │ php artisan job:run │ │
|
||
│ │ php artisan job:daemon │ │
|
||
│ └────────────┬────────────────┘ │
|
||
└───────────────────────────┼─────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 调度层（JobService） │
|
||
│ │
|
||
│ runPending() shouldRun() │
|
||
│ ├─ 查询 status=1 的任务 ├─ 解析 cron 表达式 │
|
||
│ ├─ 逐个判断是否到执行时间 ├─ 分 时 日 月 周 逐段匹配 │
|
||
│ └─ 到期则执行 └─ 全部匹配返回 true │
|
||
│ │
|
||
│ executeJob($job) │
|
||
│ ├─ 检查执行策略（立即/排队/放弃） │
|
||
│ ├─ 调用 doExecute() 实际执行 │
|
||
│ ├─ 记录 JobLog 执行日志 │
|
||
│ └─ 返回执行结果 │
|
||
└───────────────────────────┼─────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 执行层 │
|
||
│ │
|
||
│ doExecute($job) │
|
||
│ ├─ 判断任务类型 │
|
||
│ │ │
|
||
│ ├─ http:// / https:// → executeHttp() │
|
||
│ │ └─ curl 发起 HTTP 请求 │
|
||
│ │ │
|
||
│ └─ 其它 → executeInternal() │
|
||
│ └─ 映射到 App\Task\{Name}Task::run() │
|
||
│ │
|
||
│ 示例： │
|
||
│ url = "SendSms" → App\Task\SendSmsTask::run() │
|
||
│ url = "Order/Close" → App\Task\Order\CloseTask::run() │
|
||
│ url = "https://..." → HTTP 请求 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 任务数据结构
|
||
|
||
### job 表字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `job_name` | varchar | 任务名称 |
|
||
| `job_alias` | varchar | 任务别名（唯一） |
|
||
| `job_group` | varchar | 任务分组 |
|
||
| `status` | tinyint | 状态：0=未发布 1=运行中 2=暂停 |
|
||
| `cron_expression` | varchar | Cron 表达式（5段：分 时 日 月 周） |
|
||
| `execute_policy` | tinyint | 执行策略：1=立即 2=执行一次 3=放弃 |
|
||
| `is_sync` | tinyint | 是否同步：0=否 1=是 |
|
||
| `url` | varchar | 任务地址（内部类名或外部URL） |
|
||
| `params` | text | 任务参数（JSON） |
|
||
| `note` | text | 备注 |
|
||
|
||
### job_log 表字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `job_id` | int | 关联任务ID |
|
||
| `job_name` | varchar | 任务名称 |
|
||
| `job_group` | varchar | 任务分组 |
|
||
| `job_message` | text | 执行结果消息（截取前500字符） |
|
||
| `cron_expression` | varchar | Cron 表达式 |
|
||
| `status` | tinyint | 状态：0=正常 1=失败 |
|
||
| `start_time` | datetime | 开始时间 |
|
||
| `end_time` | datetime | 结束时间 |
|
||
| `consume_time` | int | 耗时（毫秒） |
|
||
| `exception_info` | text | 异常信息（截取前2000字符） |
|
||
|
||
## 状态说明
|
||
|
||
| 状态值 | 说明 | 可执行 | 可暂停 | 可启动 |
|
||
|--------|------|--------|--------|--------|
|
||
| 0 | 未发布 | ✗ | ✗ | ✓ |
|
||
| 1 | 运行中 | ✓ | ✓ | ✗ |
|
||
| 2 | 暂停 | ✗ | ✗ | ✓ |
|
||
| 3 | 已删除 | ✗ | ✗ | ✗ |
|
||
|
||
## 执行策略
|
||
|
||
| 策略值 | 说明 | 行为 |
|
||
|--------|------|------|
|
||
| 1 | 立即执行 | 丢弃之前的执行，立即运行 |
|
||
| 2 | 执行一次 | 等待上一次完成后执行 |
|
||
| 3 | 放弃执行 | 如果上一次还在运行则跳过 |
|
||
|
||
## Cron 表达式语法
|
||
|
||
标准 5 段格式：`分 时 日 月 周`
|
||
|
||
```text
|
||
┌────────── 分钟（0-59）
|
||
│ ┌──────── 小时（0-23）
|
||
│ │ ┌────── 日（1-31）
|
||
│ │ │ ┌──── 月（1-12）
|
||
│ │ │ │ ┌── 周（0-6，0=周日）
|
||
│ │ │ │ │
|
||
* * * * *
|
||
```
|
||
|
||
| 表达式 | 说明 |
|
||
|--------|------|
|
||
| `* * * * *` | 每分钟 |
|
||
| `0 * * * *` | 每小时整点 |
|
||
| `0 0 * * *` | 每天 0 点 |
|
||
| `0 2 * * *` | 每天凌晨 2 点 |
|
||
| `0 0 * * 1` | 每周一 0 点 |
|
||
| `0 0 1 * *` | 每月 1 号 0 点 |
|
||
| `*/5 * * * *` | 每 5 分钟 |
|
||
| `0 */2 * * *` | 每 2 小时 |
|
||
| `0 9-18 * * 1-5` | 工作日 9-18 点每小时 |
|
||
| `0 2 1,15 * *` | 每月 1 号和 15 号凌晨 2 点 |
|
||
|
||
## 方式一：Linux Crontab（推荐）
|
||
|
||
:::tip 适用场景
|
||
Linux / macOS 服务器，最常用的定时任务触发方式。系统级 cron 每分钟触发一次 Artisan 命令。
|
||
:::
|
||
|
||
### 配置步骤
|
||
|
||
```bash
|
||
# 1. 编辑 crontab
|
||
crontab -e
|
||
|
||
# 2. 添加定时任务（每分钟执行一次，推荐）
|
||
* * * * * cd /www/RXThinkCMF_Laravel13_NaiveVue && /usr/bin/php artisan job:run >> /dev/null 2>&1
|
||
|
||
# 调试时改为写入日志文件
|
||
* * * * * cd /www/RXThinkCMF_Laravel13_NaiveVue && /usr/bin/php artisan job:run >> /var/log/job.log 2>&1
|
||
|
||
# 3. 保存后验证
|
||
crontab -l # 查看已配置的 cron
|
||
tail -f /var/log/syslog | grep CRON # 查看 cron 日志
|
||
cd /www/RXThinkCMF_Laravel13_NaiveVue && php artisan job:run # 手动执行一次
|
||
```
|
||
|
||
:::warning 路径注意
|
||
- `cd` 必须切换到**项目根目录**，否则 Laravel 无法找到 `.env` 与配置
|
||
- `php` 建议使用绝对路径（如 `/usr/bin/php`），避免 cron 环境变量不同导致找不到 PHP
|
||
- `>> /dev/null 2>&1` 表示丢弃输出，调试时改为写入日志文件
|
||
:::
|
||
|
||
### Crontab 常用命令
|
||
|
||
```bash
|
||
crontab -e # 编辑当前用户的 cron
|
||
crontab -l # 列出当前用户的 cron
|
||
crontab -r # 删除当前用户的所有 cron（慎用）
|
||
```
|
||
|
||
## 方式二：Windows 计划任务
|
||
|
||
:::tip 适用场景
|
||
Windows Server 或本地开发环境（Laragon），通过任务计划程序定时触发。
|
||
:::
|
||
|
||
### 方式 A：图形界面配置
|
||
|
||
```text
|
||
1. Win + R → taskschd.msc → 回车（打开任务计划程序）
|
||
2. 右侧点击"创建基本任务"
|
||
3. 名称：定时任务
|
||
4. 触发器：每天，重复间隔 1 分钟，持续时间无限期
|
||
5. 操作：启动程序
|
||
程序或脚本：D:\laragon\bin\php\php-8.3.x-Win32-vs16-x64\php.exe
|
||
添加参数：artisan job:run
|
||
起始于：D:\laragon\www\RXThinkCMF_Laravel13_NaiveVue
|
||
6. 勾选"不管用户是否登录都要运行" → 完成
|
||
```
|
||
|
||
### 方式 B：命令行配置（schtasks）
|
||
|
||
```powershell
|
||
# 创建每分钟执行的任务（含工作目录与日志重定向）
|
||
schtasks /create /tn "RXThinkCMF_Job" /tr "cmd /c cd /d D:\laragon\www\RXThinkCMF_Laravel13_NaiveVue && D:\laragon\bin\php\php-8.3.x-Win32-vs16-x64\php.exe artisan job:run >> storage\job.log 2>&1" /sc minute /mo 1 /f
|
||
|
||
# 查询 / 手动运行 / 删除
|
||
schtasks /query /tn "RXThinkCMF_Job"
|
||
schtasks /run /tn "RXThinkCMF_Job"
|
||
schtasks /delete /tn "RXThinkCMF_Job" /f
|
||
```
|
||
|
||
:::warning Windows 常见问题
|
||
1. **路径空格**：路径含空格时必须用引号包裹
|
||
2. **PHP 路径**：使用 `php.exe` 的完整路径（Laragon 多版本共存时尤其注意 8.3 的路径）
|
||
3. **工作目录**：必须设置为项目根目录
|
||
4. **输出重定向**：`>>` 在 `cmd /c` 内生效，注意相对路径基于工作目录
|
||
:::
|
||
|
||
## 方式三：Daemon 守护进程
|
||
|
||
:::tip 适用场景
|
||
需要更精确的执行时机，或不想依赖系统 cron 的场景。进程常驻内存，自行调度。
|
||
:::
|
||
|
||
### 原理
|
||
|
||
```text
|
||
Daemon 进程启动
|
||
│
|
||
▼
|
||
┌─────────────────────┐
|
||
│ while (true) │ 无限循环
|
||
│ │ │
|
||
│ ├─ runPending() │ 扫描并执行到期任务
|
||
│ ├─ sleep(60) │ 休眠 60 秒
|
||
│ └─ 继续循环 │
|
||
└─────────────────────┘
|
||
```
|
||
|
||
- 锁文件：`storage/app/job_daemon.lock`（内容为当前进程 PID，防止重复启动）
|
||
- 防重复：同一任务在同一分钟内只执行一次（`hasRunThisMinute` 查 JobLog）
|
||
|
||
### 运行方式
|
||
|
||
**常用命令：**
|
||
|
||
```bash
|
||
php artisan job:daemon # 前台常驻（开发观察）
|
||
php artisan job:daemon --stop # 停止
|
||
php artisan job:run # 一次性执行（交给系统 cron 每分钟触发）
|
||
nohup php artisan job:daemon > storage/logs/job_daemon.log 2>&1 & # 后台
|
||
```
|
||
|
||
#### 方式 A：前台运行（本地调试）
|
||
|
||
```cmd
|
||
:: 项目根目录打开 CMD —— 启动
|
||
php artisan job:daemon
|
||
|
||
:: 停止（另开一个 CMD 窗口）
|
||
php artisan job:daemon --stop
|
||
```
|
||
|
||
**启动成功输出：**
|
||
|
||
```text
|
||
[2026-10-07 22:10:06] Daemon 已启动 (PID: 32116)
|
||
[2026-10-07 22:10:06] 每分钟检查一次到期任务，按 Ctrl+C 优雅退出
|
||
```
|
||
|
||
**运行日志：**
|
||
|
||
```text
|
||
[2026-10-07 22:10:06] [执行] 定时任务演示 (cron: */5 * * * *)
|
||
[2026-10-07 22:10:06] [执行] 定时任务案例 (cron: */5 * * * *)
|
||
[2026-10-07 22:10:06] 本轮执行完成，共执行 2 个任务
|
||
```
|
||
|
||
| 标记 | 含义 |
|
||
|------|------|
|
||
| `[执行]` | 任务已触发执行，括号内显示 cron 表达式 |
|
||
| `[跳过]` | 同一分钟内该任务已执行过，自动跳过（防重复） |
|
||
| `[失败]` | 任务执行异常，后跟错误信息（单个任务失败不影响其他任务） |
|
||
| `本轮执行完成` | 当前分钟扫描完毕，显示执行数量 |
|
||
|
||
:::tip
|
||
没有到期任务时 Daemon 静默等待（不输出日志），属正常行为。
|
||
:::
|
||
|
||
**前端联动：** Daemon 启动后，「定时任务」模块顶部显示绿色「守护进程运行中 (PID: xxx)」按钮；未启动时显示灰色。
|
||
|
||
:::tip 状态检测原理
|
||
前端通过 `GET /api/job/daemonStatus` 轮询，后端读取 `storage/app/job_daemon.lock` 中的 PID 并检查进程是否存活。若进程非正常退出但锁文件残留，前端可能仍显示「运行中」——执行 `php artisan job:daemon --stop` 或删除锁文件清理。
|
||
:::
|
||
|
||
#### 方式 B：Supervisor 管理（Linux 生产推荐）
|
||
|
||
```ini
|
||
; /etc/supervisor/conf.d/rxthinkcmf-job.conf
|
||
|
||
[program:rxthinkcmf-job]
|
||
command=php /www/RXThinkCMF_Laravel13_NaiveVue/artisan job:daemon
|
||
directory=/www/RXThinkCMF_Laravel13_NaiveVue
|
||
autostart=true
|
||
autorestart=true
|
||
user=www-data
|
||
numprocs=1
|
||
redirect_stderr=true
|
||
stdout_logfile=/var/log/rxthinkcmf-job.log
|
||
stdout_logfile_maxbytes=10MB
|
||
stdout_logfile_backups=5
|
||
```
|
||
|
||
```bash
|
||
sudo supervisorctl reread && sudo supervisorctl update
|
||
sudo supervisorctl start rxthinkcmf-job
|
||
sudo supervisorctl status rxthinkcmf-job
|
||
tail -f /var/log/rxthinkcmf-job.log
|
||
```
|
||
|
||
#### 方式 C：systemd 服务（Linux 生产推荐）
|
||
|
||
```ini
|
||
; /etc/systemd/system/rxthinkcmf-job.service
|
||
|
||
[Unit]
|
||
Description=RXThinkCMF Job Daemon
|
||
After=network.target mysql.service
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=www-data
|
||
WorkingDirectory=/www/RXThinkCMF_Laravel13_NaiveVue
|
||
ExecStart=/usr/bin/php /www/RXThinkCMF_Laravel13_NaiveVue/artisan job:daemon
|
||
Restart=always
|
||
RestartSec=10
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
```bash
|
||
sudo systemctl enable rxthinkcmf-job
|
||
sudo systemctl start rxthinkcmf-job
|
||
sudo systemctl status rxthinkcmf-job
|
||
sudo journalctl -u rxthinkcmf-job -f
|
||
```
|
||
|
||
#### 方式 D：nohup 后台运行（简单场景）
|
||
|
||
```bash
|
||
nohup php artisan job:daemon > storage/logs/job_daemon.log 2>&1 &
|
||
ps aux | grep job:daemon
|
||
kill $(pgrep -f "job:daemon")
|
||
```
|
||
|
||
#### Docker 环境
|
||
|
||
```bash
|
||
docker compose exec app php artisan job:daemon
|
||
# 或以独立常驻容器运行 app 镜像的 artisan 命令
|
||
```
|
||
|
||
### 三种方式对比
|
||
|
||
| 特性 | Crontab | Windows 计划任务 | Daemon 守护进程 |
|
||
|------|---------|-----------------|----------------|
|
||
| 适用系统 | Linux / macOS | Windows | 全平台 |
|
||
| 最小间隔 | 1 分钟 | 1 分钟 | 分钟级（每轮 sleep 60s） |
|
||
| 资源占用 | 低（按需启动） | 低（按需启动） | 常驻内存 |
|
||
| 可靠性 | 高 | 高 | 高（配合 Supervisor/systemd） |
|
||
| 日志追踪 | 需重定向 | 任务计划程序 | 自带输出 |
|
||
| 推荐场景 | 生产环境 | Windows 生产 | 开发调试 / 不便配置 cron |
|
||
|
||
:::tip 推荐选择
|
||
- **Linux 生产环境**：Crontab（简单可靠）
|
||
- **Windows 生产环境**：任务计划程序 或 Daemon + 计划任务守护
|
||
- **Docker 环境**：Daemon（容器内运行）
|
||
- **本地开发调试**：Daemon 前台运行（直接观察日志输出）
|
||
:::
|
||
|
||
## 新建定时任务步骤
|
||
|
||
### 1. 创建任务处理器
|
||
|
||
```php
|
||
<?php
|
||
// app/Task/CleanLogTask.php（本步骤新建的处理器）
|
||
|
||
namespace App\Task;
|
||
|
||
/**
|
||
* 清理过期日志任务
|
||
*
|
||
* 数据库 url 字段：CleanLog
|
||
* 参数格式：{"days": 30}
|
||
*/
|
||
class CleanLogTask extends BaseTask
|
||
{
|
||
/**
|
||
* 执行任务
|
||
*
|
||
* @param array $params 任务参数
|
||
* @return string 执行结果消息
|
||
* @throws \Exception 执行失败时抛出
|
||
*/
|
||
public function run(array $params = []): string
|
||
{
|
||
$days = $params['days'] ?? 30;
|
||
$cutoffDate = date('Y-m-d H:i:s', strtotime("-{$days} days"));
|
||
|
||
// 清理登录日志
|
||
$loginCount = LoginLog::where('create_time', '<', $cutoffDate)->delete();
|
||
|
||
// 清理操作日志
|
||
$operCount = OperationLog::where('create_time', '<', $cutoffDate)->delete();
|
||
|
||
// 清理任务日志
|
||
$jobCount = JobLog::where('start_time', '<', $cutoffDate)->delete();
|
||
|
||
return "已清理 {$days} 天前的日志：登录日志 {$loginCount} 条，操作日志 {$operCount} 条，任务日志 {$jobCount} 条";
|
||
}
|
||
}
|
||
```
|
||
|
||
内置示例处理器：`app/Task/HelloWorldTask.php`（验证 daemon 调度）、`app/Task/SendSmsTask.php`（示例任务）。
|
||
|
||
### 2. 在数据库 job 表中配置
|
||
|
||
```sql
|
||
INSERT INTO laravel_job (
|
||
job_name, job_alias, job_group, job_trigger,
|
||
url, params, cron_expression,
|
||
execute_policy, status, is_sync,
|
||
is_delete, create_user, create_time
|
||
) VALUES (
|
||
'清理过期日志', 'CleanLog', '系统维护', 'cron',
|
||
'CleanLog', '{"days":30}', '0 2 * * *',
|
||
2, 1, 0,
|
||
0, 'admin', NOW()
|
||
);
|
||
```
|
||
|
||
（也可在「定时任务」管理界面新增。）
|
||
|
||
### 3. 配置触发方式（三选一）
|
||
|
||
```bash
|
||
# 方式一：Linux Crontab
|
||
crontab -e
|
||
# 添加：* * * * * cd /项目路径 && /usr/bin/php artisan job:run >> /dev/null 2>&1
|
||
|
||
# 方式二：Windows 计划任务（见上文 schtasks 示例）
|
||
|
||
# 方式三：Daemon 守护进程
|
||
php artisan job:daemon
|
||
# 停止：php artisan job:daemon --stop
|
||
```
|
||
|
||
## Service 配置（摘自 `app/Services/JobService.php` 实际代码）
|
||
|
||
```php
|
||
class JobService extends BaseService
|
||
{
|
||
use HasCrudOperations, HasQueryScopes, HasUniqueCheck;
|
||
|
||
protected string $modelClass = Job::class;
|
||
|
||
// 任务名 / 任务别名模糊匹配
|
||
protected array $pageLikeFields = ['job_name', 'job_alias'];
|
||
|
||
// 状态 / 任务分组精确匹配
|
||
protected array $pageEqFields = ['status', 'job_group'];
|
||
|
||
// 任务别名全局唯一
|
||
protected array $uniqueFields = ['job_alias'];
|
||
}
|
||
```
|
||
|
||
:::info 未配置字典翻译与文件字段
|
||
任务表的 `status`、`execute_policy` 等枚举直接以数值存储，前端按 [6.11 定时任务](/zh/modules/job.html) 状态说明渲染，`JobService` 未声明 `serializeMaps` / `fileFields`。
|
||
:::
|
||
|
||
## API 接口
|
||
|
||
### 任务管理
|
||
|
||
| 方法 | 路径 | 权限码 | 说明 |
|
||
|------|------|--------|------|
|
||
| GET | `/api/job/page` | sys:job:page | 分页列表 |
|
||
| GET | `/api/job/list` | sys:job:list | 全量列表 |
|
||
| GET | `/api/job/detail/{id}` | sys:job:detail | 详情 |
|
||
| GET | `/api/job/runOnce/{id}` | sys:job:execute | 手动执行一次 |
|
||
| GET | `/api/job/pause/{id}` | sys:job:pause | 暂停任务 |
|
||
| GET | `/api/job/resume/{id}` | sys:job:resume | 恢复任务 |
|
||
| GET | `/api/job/daemonStatus` | — | 守护进程状态 |
|
||
| POST | `/api/job/add` | sys:job:add | 新增任务 |
|
||
| POST | `/api/job/status` | sys:job:update | 设置状态 |
|
||
| PUT | `/api/job/update` | sys:job:update | 修改任务 |
|
||
| DELETE | `/api/job/delete/{id}` | sys:job:delete | 删除任务 |
|
||
| DELETE | `/api/job/batchDelete` | sys:job:batchDelete | 批量删除 |
|
||
|
||
### 任务日志
|
||
|
||
| 方法 | 路径 | 权限码 | 说明 |
|
||
|------|------|--------|------|
|
||
| GET | `/api/job/log/page` | sys:job:page | 日志分页 |
|
||
| GET | `/api/job/log/detail/{id}` | sys:job:detail | 日志详情 |
|
||
| DELETE | `/api/job/log/delete/{id}` | sys:job:delete | 删除日志 |
|
||
| DELETE | `/api/job/log/batchDelete` | sys:job:batchDelete | 批量删除 |
|
||
|
||
## 核心代码解析
|
||
|
||
### Cron 表达式匹配（JobService::matchCronField）
|
||
|
||
```php
|
||
// app/Services/JobService.php（来自项目实际代码）
|
||
|
||
/**
|
||
* 匹配 cron 字段
|
||
*
|
||
* 支持以下语法：
|
||
* - *：匹配所有
|
||
* - */n：每隔 n 个单位
|
||
* - n-m：范围匹配
|
||
* - n,m,...：逗号分隔的多值
|
||
* - n：单个值精确匹配
|
||
*/
|
||
protected function matchCronField(string $cronField, int $current): bool
|
||
{
|
||
if ($cronField === '*') {
|
||
return true;
|
||
}
|
||
|
||
// 处理 */n（每隔 n 分钟/小时等）
|
||
if (preg_match('/^\*\/(\d+)$/', $cronField, $m)) {
|
||
return $current % (int) $m[1] === 0;
|
||
}
|
||
|
||
// 处理 n-m（范围）
|
||
if (preg_match('/^(\d+)-(\d+)$/', $cronField, $m)) {
|
||
return $current >= (int) $m[1] && $current <= (int) $m[2];
|
||
}
|
||
|
||
// 处理逗号分隔的多个值
|
||
if (strpos($cronField, ',') !== false) {
|
||
$values = array_map('intval', explode(',', $cronField));
|
||
return in_array($current, $values);
|
||
}
|
||
|
||
// 单个值
|
||
return (int) $cronField === $current;
|
||
}
|
||
```
|
||
|
||
### 防重复执行（JobService::hasRunThisMinute）
|
||
|
||
```php
|
||
/**
|
||
* 检查任务在当前分钟是否已执行过
|
||
*
|
||
* Daemon 模式下，防止同一分钟内重复执行。
|
||
*/
|
||
public function hasRunThisMinute(int $jobId): bool
|
||
{
|
||
$minuteStart = date('Y-m-d H:i') . ':00';
|
||
$minuteEnd = date('Y-m-d H:i') . ':59';
|
||
|
||
return JobLog::where('job_id', $jobId)
|
||
->where('start_time', '>=', $minuteStart)
|
||
->where('start_time', '<=', $minuteEnd)
|
||
->count() > 0;
|
||
}
|
||
```
|
||
|
||
### JobService 能力清单
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `runPending()` | 扫描并执行全部到期任务，返回执行数 |
|
||
| `shouldRun($job)` | 解析 cron 判断任务是否到期 |
|
||
| `executeJob($job)` | 执行入口（策略检查 + 执行 + 记录 JobLog） |
|
||
| `runOnce($id)` | 手动执行一次（忽略 cron） |
|
||
| `setStatus($id, $status)` / `pause($id)` / `resume($id)` | 状态流转 |
|
||
| `executeHttp($url, $params)` | HTTP 类任务执行 |
|
||
| `executeInternal($url, $params)` | 内部 Task 类执行（映射 `App\Task\{Name}Task`） |
|
||
|
||
## 注意事项
|
||
|
||
1. **互斥运行**：Cron 模式和 Daemon 模式不要同时使用，否则会导致任务重复执行
|
||
2. **防重复执行**：Daemon 模式内置防重复机制，同一任务在同一分钟内不会重复执行
|
||
3. **错误隔离**：单个任务执行失败不影响其他任务和主循环
|
||
4. **优雅退出**：Daemon 支持 `SIGTERM`/`SIGINT` 信号，`Ctrl+C` 或 `kill` 均可优雅停止
|
||
5. **锁文件**：Daemon 的锁文件位于 `storage/app/job_daemon.lock`，异常退出后残留锁会自动检测并清理
|
||
6. **Windows 兼容**：Daemon 在 Windows 下可正常运行，但信号处理（pcntl）不可用，需通过 `--stop` 参数或 `taskkill` 停止
|
||
7. **日志截断**：执行结果消息截取前 500 字符，异常信息截取前 2000 字符写入 job_log
|
||
8. **create_user**：命令行执行的任务日志中 `create_user` 由 HasAuditColumns trait 自动处理（无登录用户时为空）
|
||
|
||
## 常见问题
|
||
|
||
### Q: 任务不执行？
|
||
|
||
A: 检查以下几点：
|
||
|
||
1. 任务状态是否为 `1`（运行中）
|
||
2. Cron 表达式格式是否正确（5 段）
|
||
3. Crontab 是否已配置且 cron 服务已启动
|
||
4. PHP 路径是否正确（建议使用绝对路径）
|
||
5. 手动执行 `php artisan job:run` 是否正常
|
||
|
||
### Q: 任务重复执行？
|
||
|
||
A: Daemon 模式下检查 `hasRunThisMinute` 是否生效；Crontab 模式下确保只有一个 cron 在触发（`crontab -l` 检查重复项）。
|
||
|
||
### Q: 任务执行超时？
|
||
|
||
A: 检查 PHP 的 `max_execution_time` 配置，长时间任务建议拆分或在处理器内调大 `set_time_limit(0)`。
|
||
|
||
### Q: 如何查看任务执行日志？
|
||
|
||
A: 两种方式：
|
||
|
||
1. **控制台实时日志**：Daemon 前台运行时，`[执行]`、`[跳过]`、`[失败]` 直接输出到终端
|
||
2. **数据库持久化日志**：通过 `GET /api/job/log/page` 查询，或直接查 `laravel_job_log` 表
|
||
|
||
### Q: Daemon 控制台没有新日志输出，是卡住了吗？
|
||
|
||
A: 不是。Daemon 每分钟检查一次，没有到期任务时静默等待，不输出任何日志。
|
||
|
||
### Q: Windows 下 Daemon 如何启动和停止？
|
||
|
||
A: 项目根目录打开 CMD：
|
||
|
||
```cmd
|
||
:: 启动
|
||
php artisan job:daemon
|
||
|
||
:: 停止（另开一个 CMD 窗口）
|
||
php artisan job:daemon --stop
|
||
```
|
||
|
||
如提示 `Daemon 已在运行中 (PID: xxx)`，先执行 `php artisan job:daemon --stop` 停止旧进程，或手动删除 `storage/app/job_daemon.lock`。
|
||
|
||
### Q: 提示找不到 Task 类？
|
||
|
||
A: 确认 `url` 字段的类名与 `app/Task/` 下的类文件一致（命名空间 `App\Task`），且类名采用大驼峰（`SendSms` → `SendSmsTask`）。
|