# 定时任务

**Repository Path**: xbcode-plugin/xbCrontab

## Basic Information

- **Project Name**: 定时任务
- **Description**: 基于积木云实现的定时任务管理器
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-18
- **Last Updated**: 2026-02-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xbCrontab 定时任务插件

xbCrontab 是一款基于 Webman 框架开发的定时任务管理插件，旨在为系统提供强大、灵活且易于管理的定时任务执行引擎。它集成了任务调度、执行日志记录、状态监控以及插件化扩展能力，是积木云（xbCode）生态系统中的核心组件之一。

## 1. 插件信息

- **插件名称**：xbCrontab (定时任务)
- **当前版本**：1.0.0
- **作者**：积木云
- **核心依赖**：
  - `workerman/crontab`：提供高精度的定时任务调度能力。
  - `webman/channel`：实现跨进程的任务同步与状态更新。

## 2. 主要特性

- **多任务类型支持**：
  - **Shell命令**：直接执行系统级的 Shell 脚本或命令。
  - **访问URL**：通过 HTTP 协议触发远程或本地接口。
  - **PHP代码**：在系统环境下动态执行 PHP 代码片段。
- **灵活的执行周期**：支持秒、分钟、小时、天、周、月、年等多种时间维度，能够满足从高频触发到长周期执行的各种业务需求。
- **完善的日志系统**：详细记录每次任务的执行时间、耗时及运行结果，方便开发者进行故障排查和性能分析。
- **实时状态监控**：支持查看任务的当前运行状态（运行中、已停止、未运行），并可实时手动启动或停止任务。
- **插件化集成**：支持其他插件通过 `config/crontab.php` 配置文件自动注册定时任务，极大简化了功能扩展的复杂度。
- **异步事件机制**：集成 Webman Event 机制，在任务添加、编辑、删除时发布相关事件，便于业务逻辑解耦。

## 3. 核心概念

### 任务类型 (TaskType)
- **10 (Shell)**：执行服务器指令。
- **20 (URL)**：GET 方式访问指定地址。
- **30 (PHP)**：直接运行指定的 PHP 逻辑。

### 执行周期 (TaskCycle)
插件支持多种复杂的周期设定，包括但不限于：
- 每 N 秒执行一次
- 每星期 N 的固定时间执行
- 每月固定日期的固定时间执行
- 每年固定月份固定日期的固定时间执行

## 4. 目录结构

```text
plugin/xbCrontab/
├── api/            # 核心接口，提供任务管理、安装、卸载等 API
├── app/            # 应用层，包含模型、控制器及定时任务处理进程
├── command/        # 命令行工具，支持日志清理等功能
├── config/         # 插件配置信息
├── enum/           # 枚举定义（任务类型、周期、状态）
├── install.sql     # 数据库表结构
└── plugins.json    # 插件元数据
```

## 5. 开发者使用指南

### 5.1 其他插件自动注册任务
在您的插件目录下创建 `config/crontab.php`：

```php
return [
    [
        'title' => '示例任务',
        'name' => 'demo_task',
        'type' => '30', // PHP代码
        'unit' => '20', // 每 N 分钟
        'period_unit' => 5, // 5分钟
        'command' => '\app\service\Test::run()',
    ]
];
```

### 5.2 调用 API 管理任务
可以通过 `plugin\xbCrontab\api\CrontabApi` 进行编程化管理：

```php
use plugin\xbCrontab\api\CrontabApi;

// 添加任务
CrontabApi::make()->add([
    'title' => '动态任务',
    'type' => '10',
    'command' => 'echo "hello"',
    // ... 其他参数
]);
```

## 6. 安装与配置

1. 确保已安装 `workerman/crontab`。
2. 导入 `install.sql` 到您的 MySQL 数据库。
3. 在 Webman 后台插件管理中启用 **定时任务** 插件。

## 7. 注意事项

- **秒级任务**：由于高频执行对服务器资源消耗较大，请谨慎配置秒级定时任务。
- **环境依赖**：执行 Shell 命令时，请确保 Web 运行用户具有相应的系统权限。
- **并发控制**：默认情况下任务是顺序执行的，若有复杂并发需求请结合队列使用。