定时任务

CloudPaste 提供了完整的定时任务系统，支持自动化执行清理、同步等后台任务。管理员可以通过后台管理界面配置和监控所有定时任务。

功能概述

定时任务系统支持以下核心功能：

✅ 多种调度模式：支持固定间隔（interval）和 Cron 表达式两种调度方式
✅ 分布式锁机制：防止多实例环境下的重复执行
✅ 手动触发：支持立即执行任务
✅ 执行历史：记录每次执行的状态、耗时和结果
✅ 统计分析：提供 24 小时执行热力图

1. 访问定时任务管理

登录 CloudPaste 后台管理界面
在左侧菜单中点击「定时任务」
进入定时任务管理页面

2. 任务类型

CloudPaste 内置以下任务类型：

2.1 清理分片上传会话（cleanup_upload_sessions）

功能说明：

自动清理过期的分片上传会话
标记超时的活跃会话为过期状态
删除超出保留期限的历史会话记录

配置参数：

参数	类型	默认值	说明
keepDays	number	30	历史记录保留天数
activeGraceHours	number	24	活跃会话最大空闲时长（小时）

清理逻辑：

将 expires_at < 当前时间 的活跃会话标记为过期
将超过 activeGraceHours 未更新的活跃会话标记为过期
删除状态为 completed/aborted/error/expired 且超过 keepDays 天的记录

2.2 存储同步（scheduled_sync_copy）

功能说明：

定期在不同存储配置之间同步文件
支持单向增量同步（仅复制新增/更新的文件）
支持配置多个源-目标路径对

配置参数：

参数	类型	默认值	说明
pairs	array	-	源-目标路径对数组
sourcePath	string	-	简单模式的源路径
targetPath	string	-	简单模式的目标路径
skipExisting	boolean	true	是否跳过已存在的文件（增量模式）
maxConcurrency	number	5	并发复制线程数（最大 32）

配置示例：

json

{
  "pairs": [
    {
      "sourcePath": "/mount1/backup",
      "targetPath": "/mount2/archive"
    },
    {
      "sourcePath": "/mount1/photos",
      "targetPath": "/mount3/photos-backup"
    }
  ],
  "skipExisting": true,
  "maxConcurrency": 5
}

3. 创建定时任务

3.1 基本步骤

在定时任务管理页面点击「新建任务」
选择任务类型（Handler）
填写任务配置信息
设置调度计划
点击「保存」创建任务

3.2 配置字段说明

任务名称（可选）
- 自定义的任务显示名称
- 未填写时使用任务类型的默认名称
任务描述（可选）
- 任务的说明文字
- 便于识别任务用途
调度类型
- 固定间隔：按固定时间间隔执行
- Cron 表达式：使用标准 Cron 表达式定义执行时间
执行间隔（固定间隔模式）
- 支持秒/分钟/小时/天等单位
- 最小间隔：60 秒
Cron 表达式（Cron 模式）
- 标准五字段格式：分时日月周
- 界面会自动显示 Cron 表达式的可读描述
启用状态
- 开启后任务将按计划自动执行
- 关闭后任务将暂停执行
配置参数
- 任务特定的配置项
- 支持表单模式和 JSON 模式切换

3.3 Cron 表达式示例

表达式	说明
`0 0 * * *`	每天凌晨 0 点执行
`0 /6 * *`	每 6 小时执行一次
`30 2 * * *`	每天凌晨 2:30 执行
`0 0 * * 0`	每周日凌晨 0 点执行
`0 0 1 * *`	每月 1 日凌晨 0 点执行

4. 任务管理操作

4.1 查看任务列表

任务列表页面显示以下信息：

任务名称和描述
执行周期（间隔或 Cron 表达式）
上次执行时间
下次执行时间
累计执行次数
当前状态

4.2 任务状态说明

状态	说明
已禁用	任务已关闭，不会自动执行
等待中	任务已启用，等待下次执行时间
等待触发	执行时间已到，等待调度器触发
运行中	任务正在执行

4.3 手动执行任务

在任务列表中找到目标任务
点击操作列的「立即执行」按钮（闪电图标）
系统将立即执行该任务
执行完成后自动刷新状态

4.4 启用/禁用任务

点击任务状态开关切换启用状态
禁用后任务将不再自动执行
禁用状态下仍可手动执行

4.5 编辑任务

点击任务操作列的「编辑」按钮
修改任务配置
点击「保存」应用更改

4.6 删除任务

点击任务操作列的「删除」按钮
确认删除操作
任务及其执行历史将被删除

注意：删除操作不可恢复，请谨慎操作。

5. 查看执行历史

5.1 访问执行历史

在任务列表中点击目标任务的「查看详情」按钮
在弹出的详情窗口中查看执行历史

5.2 执行历史信息

每条执行记录包含：

执行状态：success（成功）/ failure（失败）/ skipped（跳过）
触发方式：auto（自动）/ manual（手动）
开始时间：任务开始执行的时间
执行耗时：任务执行所花费的时间（毫秒）
执行摘要：任务执行结果的简要描述
错误信息：失败时的错误详情

6. 统计热力图

定时任务管理页面顶部显示 24 小时执行热力图：

颜色深浅表示该时段的执行次数
悬停显示具体的执行次数
颜色等级：
- 浅色：1-3 次
- 中等：4-7 次
- 较深：8-12 次
- 深色：>12 次

7. 调度机制说明

7.1 Cloudflare Workers 环境

通过 Cloudflare Scheduled Events 触发
默认每 5 分钟检查一次到期任务
配置位置：wrangler.toml 中的 cron 字段

7.2 Docker/Node.js 环境

通过 node-schedule 库实现
默认每分钟检查一次到期任务
可通过环境变量 SCHEDULED_TICK_CRON 自定义

7.3 分布式锁机制

系统使用数据库锁防止多实例重复执行
锁定时间默认 5 分钟
执行完成后自动释放锁

8. 最佳实践

8.1 清理任务配置建议

keepDays：根据存储空间和合规要求设置，通常 7-30 天
activeGraceHours：建议设置为 24 小时以上，避免误标记正在进行的上传
执行间隔：建议每天执行一次（86400 秒）

8.2 同步任务配置建议

skipExisting：建议开启，实现增量同步，提高效率
maxConcurrency：根据网络带宽和存储性能调整，通常 3-10
执行间隔：根据数据更新频率设置，如每小时或每天

8.3 注意事项

避免重叠执行：设置合理的执行间隔，确保任务有足够时间完成
监控执行状态：定期检查任务执行历史，关注失败记录
合理设置参数：根据实际数据量调整配置参数
测试后启用：新建任务后先手动执行测试，确认无误后再启用自动执行

9. 常见问题

9.1 任务没有按时执行

可能原因：

任务未启用
调度器未正常运行
上一次执行尚未完成（持有锁）

解决方法：

确认任务状态为「已启用」
检查系统日志确认调度器正常
等待锁超时或重启服务

9.2 任务执行失败

可能原因：

配置参数错误
存储配置无效
网络连接问题

解决方法：

查看执行历史中的错误信息
检查任务配置参数
验证相关存储配置是否正常

9.3 同步任务文件不完整

可能原因：

maxConcurrency 设置过高导致超时
源路径或目标路径配置错误
存储空间不足

解决方法：

降低 maxConcurrency 值
检查路径配置是否正确
确认目标存储有足够空间

10. API 接口

定时任务提供以下管理 API（需要 admin.all 权限）：

方法	端点	功能
GET	`/api/admin/scheduled/types`	获取任务类型列表
GET	`/api/admin/scheduled/jobs`	获取任务列表
GET	`/api/admin/scheduled/jobs/:taskId`	获取任务详情
POST	`/api/admin/scheduled/jobs`	创建任务
PUT	`/api/admin/scheduled/jobs/:taskId`	更新任务
DELETE	`/api/admin/scheduled/jobs/:taskId`	删除任务
POST	`/api/admin/scheduled/jobs/:taskId/run`	立即执行任务
GET	`/api/admin/scheduled/jobs/:taskId/runs`	获取执行历史
GET	`/api/admin/scheduled/analytics`	获取执行统计

定时任务 ​

功能概述 ​

1. 访问定时任务管理 ​

2. 任务类型 ​

2.1 清理分片上传会话（cleanup_upload_sessions） ​

2.2 存储同步（scheduled_sync_copy） ​

3. 创建定时任务 ​

3.1 基本步骤 ​

3.2 配置字段说明 ​

3.3 Cron 表达式示例 ​

4. 任务管理操作 ​

4.1 查看任务列表 ​

4.2 任务状态说明 ​

4.3 手动执行任务 ​

4.4 启用/禁用任务 ​

4.5 编辑任务 ​

4.6 删除任务 ​

5. 查看执行历史 ​

5.1 访问执行历史 ​

5.2 执行历史信息 ​

6. 统计热力图 ​

7. 调度机制说明 ​

7.1 Cloudflare Workers 环境 ​

7.2 Docker/Node.js 环境 ​

7.3 分布式锁机制 ​

8. 最佳实践 ​

8.1 清理任务配置建议 ​

8.2 同步任务配置建议 ​

8.3 注意事项 ​

9. 常见问题 ​

9.1 任务没有按时执行 ​

9.2 任务执行失败 ​

9.3 同步任务文件不完整 ​

10. API 接口 ​

定时任务

功能概述

1. 访问定时任务管理

2. 任务类型

2.1 清理分片上传会话（cleanup_upload_sessions）

2.2 存储同步（scheduled_sync_copy）

3. 创建定时任务

3.1 基本步骤

3.2 配置字段说明

3.3 Cron 表达式示例

4. 任务管理操作

4.1 查看任务列表

4.2 任务状态说明

4.3 手动执行任务

4.4 启用/禁用任务

4.5 编辑任务

4.6 删除任务

5. 查看执行历史

5.1 访问执行历史

5.2 执行历史信息

6. 统计热力图

7. 调度机制说明

7.1 Cloudflare Workers 环境

7.2 Docker/Node.js 环境

7.3 分布式锁机制

8. 最佳实践

8.1 清理任务配置建议

8.2 同步任务配置建议

8.3 注意事项

9. 常见问题

9.1 任务没有按时执行

9.2 任务执行失败

9.3 同步任务文件不完整

10. API 接口