定时任务
项目界面已升级为订阅任务。新增来源与看门狗使用订阅任务 API。已升级任务通过旧修改、删除、手动触发端点操作时返回 409 subscription_task_requires_explicit_update。
管理项目的定时调度任务（CRUD、手动触发、执行日志）。
源码: apps/backend/src/routes/schedules.ts
所有端点都需要认证（combinedAuth），路由挂载在 /projects/:projectId/schedules 下。
GET /projects/:projectId/schedules
获取项目的定时任务列表。
认证方式
JWT Token / API Key（combinedAuth）
权限要求
项目访问权限（团队成员）
请求参数
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 UUID |
响应格式
状态码: 200
{
"schedules": [
{
"id": "uuid",
"project_id": "uuid",
"team_id": "uuid",
"deployment_id": "uuid",
"name": "每日数据同步",
"description": "每天凌晨同步数据",
"cron_expression": "0 0 * * *",
"timezone": "Asia/Shanghai",
"trigger_config": {},
"enabled": true,
"timeout_ms": 60000,
"max_retries": 3,
"created_at": "2026-03-07T12:00:00.000Z",
"updated_at": "2026-03-07T12:00:00.000Z",
"deleted_at": null
}
]
}按 created_at 降序排列。
错误码
| 状态码 | 错误 | 说明 |
|---|---|---|
| 403 | 无权访问该项目 | 非团队成员 |
GET /projects/:projectId/schedules/:id
获取单个定时任务详情。
认证方式
JWT Token / API Key（combinedAuth）
权限要求
项目访问权限（团队成员）
请求参数
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 UUID |
id | string | 是 | 定时任务 UUID |
响应格式
状态码: 200
{
"schedule": {
"id": "uuid",
"project_id": "uuid",
"team_id": "uuid",
"deployment_id": "uuid",
"name": "每日数据同步",
"description": "每天凌晨同步数据",
"cron_expression": "0 0 * * *",
"timezone": "Asia/Shanghai",
"trigger_config": {},
"enabled": true,
"timeout_ms": 60000,
"max_retries": 3,
"created_at": "2026-03-07T12:00:00.000Z",
"updated_at": "2026-03-07T12:00:00.000Z",
"deleted_at": null
}
}错误码
| 状态码 | 错误 | 说明 |
|---|---|---|
| 403 | 无权访问该项目 | 非团队成员 |
| 404 | 任务不存在 | 任务不存在或已删除 |
POST /projects/:projectId/schedules
创建定时任务。
认证方式
JWT Token / API Key（combinedAuth）
权限要求
项目管理员权限（admin）
请求参数
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 UUID |
Body 参数
{
"name": "每日数据同步",
"description": "每天凌晨同步数据",
"cron_expression": "0 0 * * *",
"timezone": "Asia/Shanghai",
"deployment_id": "uuid",
"trigger_config": {},
"enabled": true,
"timeout_ms": 60000,
"max_retries": 3
}| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
name | string | 是 | - | 任务名称（项目内唯一） |
cron_expression | string | 是 | - | Cron 表达式（5 字段 分 时 日 月 周 或 6 字段 秒 分 时 日 月 周） |
description | string | 否 | null | 任务描述 |
timezone | string | 否 | "UTC" | 时区 |
deployment_id | string | 否 | null | 关联的部署 UUID |
trigger_config | object | 否 | {} | 触发配置 |
enabled | boolean | 否 | true | 是否启用 |
timeout_ms | number | 否 | 站点默认值 | 超时时间（毫秒） |
max_retries | number | 否 | 3 | 最大重试次数 |
响应格式
状态码: 201
{
"schedule": {
"id": "uuid",
"project_id": "uuid",
"team_id": "uuid",
"name": "每日数据同步",
"cron_expression": "0 0 * * *",
"...": "..."
}
}错误码
| 状态码 | 错误 | 说明 |
|---|---|---|
| 400 | name 和 cron_expression 为必填 | 缺少必填字段 |
| 400 | Cron 表达式无效: ... | Cron 表达式格式错误 |
| 400 | 执行频率过高：...（code: schedule_interval_limit） | 表达式相邻两次执行间隔低于套餐允许的最小间隔 |
| 400 | 部署不存在或不属于该项目 | deployment_id 无效 |
| 403 | 需要项目管理员权限 | 缺少 admin 权限 |
| 404 | 项目不存在 | 项目不存在 |
| 409 | 启用中的定时任务已达当前套餐上限...（code: schedule_count_limit） | 团队启用中任务数达套餐上限；可停用部分任务、以停用状态创建或升级套餐 |
| 409 | 任务名称已存在 | 名称重复（唯一约束冲突） |
套餐配额
每团队「启用中」的定时任务个数与最小执行间隔按套餐分档限制，数值由管理后台 site_settings 的 team.quota_limits.schedules 配置（按 plan_code 分档，default 档兜底）。 默认档位：free 3 个 / 最小间隔 5 分钟；pro 20 个 / 1 分钟；business 与 infrastructure 100 个 / 1 分钟。 更新接口在「重新启用任务」与「修改 cron 表达式」时同样校验。
PUT /projects/:projectId/schedules/:id
更新定时任务。
认证方式
JWT Token / API Key（combinedAuth）
权限要求
项目管理员权限（admin）
请求参数
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 UUID |
id | string | 是 | 定时任务 UUID |
Body 参数
所有字段可选，仅传入需要更新的字段：
{
"name": "新名称",
"cron_expression": "0 */2 * * *",
"enabled": false
}允许更新的字段：name, description, cron_expression, timezone, deployment_id, trigger_config, enabled, timeout_ms, max_retries
响应格式
状态码: 200
{
"schedule": { "...更新后的完整记录..." }
}错误码
| 状态码 | 错误 | 说明 |
|---|---|---|
| 400 | Cron 表达式不能为空 | cron_expression 为空字符串 |
| 400 | Cron 表达式无效: ... | Cron 表达式格式错误 |
| 400 | 执行频率过高：...（code: schedule_interval_limit） | 修改后的表达式低于套餐最小执行间隔 |
| 400 | 部署不存在或不属于该项目 | deployment_id 无效 |
| 403 | 需要项目管理员权限 | 缺少 admin 权限 |
| 404 | 任务不存在 | 任务不存在或已删除 |
| 409 | 启用中的定时任务已达当前套餐上限...（code: schedule_count_limit） | 停用→启用时团队启用数已达套餐上限 |
DELETE /projects/:projectId/schedules/:id
删除定时任务（软删除，同时禁用任务）。
认证方式
JWT Token / API Key（combinedAuth）
权限要求
项目管理员权限（admin）
请求参数
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 UUID |
id | string | 是 | 定时任务 UUID |
响应格式
状态码: 200
{
"success": true
}错误码
| 状态码 | 错误 | 说明 |
|---|---|---|
| 403 | 需要项目管理员权限 | 缺少 admin 权限 |
| 404 | 任务不存在 | 任务不存在或已删除 |
POST /projects/:projectId/schedules/:id/trigger
手动触发定时任务执行。
认证方式
JWT Token / API Key（combinedAuth）
权限要求
项目访问权限（团队成员）
请求参数
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 UUID |
id | string | 是 | 定时任务 UUID |
响应格式
状态码: 200（成功）
{
"success": true,
"result": { "...执行结果..." }
}状态码: 500（执行失败）
{
"success": false,
"error": "错误信息"
}错误码
| 状态码 | 错误 | 说明 |
|---|---|---|
| 400 | 任务未关联部署 | 任务没有配置 deployment_id |
| 403 | 无权访问该项目 | 非团队成员 |
| 404 | 任务不存在 | 任务不存在或已删除 |
| 500 | <error message> | 执行过程中发生错误 |
GET /projects/:projectId/schedules/:id/logs
获取定时任务的执行日志。
认证方式
JWT Token / API Key（combinedAuth）
权限要求
项目访问权限（团队成员）
请求参数
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 UUID |
id | string | 是 | 定时任务 UUID |
Query 参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
limit | number | 50 | 返回数量 |
offset | number | 0 | 偏移量 |
响应格式
状态码: 200
{
"logs": [
{
"id": "uuid",
"schedule_id": "uuid",
"project_id": "uuid",
"status": "success",
"started_at": "2026-03-07T00:00:00.000Z",
"finished_at": "2026-03-07T00:00:05.000Z",
"error": null,
"result": { "..." }
}
],
"total": 100,
"limit": 50,
"offset": 0
}按 started_at 降序排列。
错误码
| 状态码 | 错误 | 说明 |
|---|---|---|
| 403 | 无权访问该项目 | 非团队成员 |