跳转到内容
GitHub

定时任务

定时任务存在数据库的 task_scheduler 表里,由 Celery beat 读出来按时派发、worker 执行。在「定时任务 → 任务调度」里新建、修改、启停一条任务,不用重启 beat:每次改动都会通知 beat 重新读表。每次执行的结果(成功 / 失败、返回值、异常栈、哪个 worker 跑的)记在「执行记录」里,保留 30 天。系统自带 11 条任务,日志清理、导出过期、通知投递、审批超时都靠它们。

任务调度:内置的定时任务
页面路径权限码做什么
定时任务 → 任务调度/scheduler/manage查看 task:scheduler:list · 新建 add · 修改与启停 edit · 立即执行 run · 删除 del任务列表、新建 / 编辑、cron 预览
定时任务 → 执行记录/scheduler/record查看 task:result:list每次执行的状态、重试次数、执行节点;点时间看返回值和异常栈

⚠️ 「任务调度」页的前端路由守卫认的是 task:scheduler:edit,不是 list —— 只授了查看的角色打不开这一页。「执行记录」页没有路由守卫,但它的列表接口要 task:result:list,没有这个码的人进得去、列表加载失败。

字段说明
任务名称给人看的名字
Celery 任务只能从下拉里选,列出的是 worker 里已经注册了的任务(celery.* 内置任务除外),不能手填
调度类型定时(crontab,5 段)或 间隔(按秒 / 分 / 时 / 天)
只运行一次跑完一次就停
启用停用的不会被派发
位置参数 · 关键字参数JSON 数组 · JSON 对象,原样传给任务函数
备注

服务端要求 crontab 是 5 段、能被 Celery 解析,开始时间要早于结束时间;前端的构建器也会直接拒掉 Quartz 那种带秒和 ? 的写法。

cron 预览:表单上有常用写法的快捷按钮和可视化的构建器,下面列出「接下来 5 次(服务端时区 …)」的触发时间 —— 按服务器的时区算,不是浏览器的,避免「我这里看着是 9 点、服务器上其实是 1 点」。

列表上每条任务有启停开关、「立即执行一次」(不管启没启用都会派发,返回 Celery 的任务 ID)和删除。指向一个 worker 里没注册的任务的那一行会标红 —— 这种调度 beat 照样派发、worker 收到就丢,日志里只有一句 Received unregistered task。

立即。每次通过界面或接口改动(新建、修改、启停、删除),事务提交之后都会在 Redis 里打一个「有变更」的标记,beat 每一拍都看这个标记,看到就重新读表。另外 beat 每 5 分钟无条件重读一次,兜住绕过接口直接改库的情况。

cron 按 DATETIME_TIMEZONE(默认 Asia/Shanghai)的墙上时间算:写 30 2 * * * 就是本地时间 2:30。PostgreSQL 把时间读回来是 UTC,曾经让任务晚 8 小时触发、或者 beat 一启动就把当天的任务补跑一遍;现在读回来之后先换算成应用时区。

种子数据里的 11 条,全部默认启用:

名称任务什么时候跑干什么
清理历史日志maintenance.prune_logs每天 03:15,参数 {"days": 180}删掉超过 N 天的登录、操作、开放接口、短信日志;通知投递、Webhook、数据变更记录按各自的保留天数删。见日志与审计
清理任务执行记录maintenance.prune_task_results每天 03:30,参数 {"days": 30}删掉超过 N 天的执行记录
清理回收站maintenance.purge_recycled_files每天 03:45彻底删除回收站里超过 FILE_RECYCLE_DAYS 天的文件
清理过期分片maintenance.purge_stale_multipart每天 04:00删掉过期的分片上传留下的分片
清理过期导出maintenance.purge_expired_exports每小时第 20 分删过期的导出文件、把卡住的导出记成失败、删旧记录
每日问候notification.send_daily_greeting每天 09:00给所有人发一条随机问候(演示用,不需要可以停掉)
后台任务心跳health.heartbeat每 60 秒写 worker 心跳,健康检查靠它判断 worker 活着
公告收件箱对时notice.sync_inbox每 60 秒到点发布定时公告、撤回过期公告
通知投递notification.deliver_pending每 15 秒发出排队中的邮件、短信、群机器人消息
Webhook 投递open.webhook_deliver_pending每 15 秒发出到期的 Webhook
审批超时处理workflow.handle_timeouts每 5 分钟按节点配置对超时的审批提醒、自动同意或自动驳回

后四条来自插件(公告、通知、能力开放、审批流),没装对应插件就没有。

  • beat 只能起一个。 起了两个,每条任务都会被派发两次。生产的 compose 给 beat 写死了 container_name: fba_beat,--scale beat=2 会直接报错,而不是悄悄起两个。worker 可以按需加。
  • 开发时 pnpm dev 在 Linux 上用 -B 把 beat 嵌在 worker 里;macOS 和 Windows 上分成两个进程。-B 只用于开发。
  • broker 用的 Redis 库默认是 1 号(CELERY_BROKER_REDIS_DATABASE)。如果这台 Redis 上还有别的项目的 Celery 也用 1 号库,两边会互相抢任务,换一个没人用的库号。
  • 任务的超时由仓库自己的 with_timeout 控制,默认 30 分钟(CELERY_TASK_TIME_LIMIT)。

定时任务本身没有参数配置项,都在界面上一条条配。.env 里的,改完重启 worker 和 beat:

键默认值说明
CELERY_BROKERredis或 rabbitmq(再配 CELERY_RABBITMQ_*)
CELERY_BROKER_REDIS_DATABASE1broker 用的 Redis 库号,和别的项目共用 Redis 时换掉
CELERY_TASK_TIME_LIMIT1800单个任务最长跑多少秒
CELERY_TASK_MAX_RETRIES5失败重试次数
DATETIME_TIMEZONEAsia/Shanghaicron 按这个时区的本地时间算
  1. 写在 apps/api/backend/app/task/tasks/<包名>/tasks.py 里 —— worker 只扫描这个目录。
  2. 用 @celery_app.task(name='包名.任务名') 注册,下面再套一层 @with_timeout()(照 tasks/base.py 的写法)。
  3. 每 60 秒或更频繁的任务要加 ignore_result=True, notify=False,否则执行记录表一天涨几千行;有测试守着。
  4. 重启 worker 之后,它就出现在「Celery 任务」的下拉里,在界面上配调度即可。
  5. 要随代码发一条默认调度:在种子 SQL 里加一行、再写一条数据迁移。不要用 Celery 的 beat_schedule —— 调度只有数据库这一个来源。

删数据的任务另有几条规矩:分批删(先取一批 ID、再按 ID 删);过滤用的列要有索引;按业务时间删,不按写入时间;处理过的行仍可能命中过滤条件时,用键集分页。细节在 app/task/AGENTS.md。

  • 界面上不能设开始 / 结束时间、过期秒数和队列(接口支持;在界面上编辑不会把已有的值清掉)。
  • 执行记录页没有删除按钮,旧记录只靠「清理任务执行记录」这条任务清掉。
  • beat 卡住时调度器的心跳仍可能在写;绕过接口直接改库的调度,最多要等 5 分钟才生效。
  • 任务完成的提示消息目前只有中文。

后端(apps/api/backend/app/task/tests/):

  • test_scheduler_timing.py:停用不用重启 beat 就生效、从库里重读的 crontab 保持本地墙上时间、一条停用的调度不会饿死其他调度。
  • test_scheduler_api.py:每次写操作提交后都通知 beat、库里每条调度都指向已注册的任务、高频任务既不记结果也不广播。
  • test_scheduler.py:beat_schedule 保持为空、上次运行时间换算成应用时区。
  • test_prune_logs.py:分批删、不是一条不设上限的大语句。

浏览器端(Playwright):scheduler.spec.ts,覆盖任务调度、执行记录、cron 预览、任务参数、执行记录筛选。

在线演示(admin / 123456):打开「定时任务 → 任务调度」,点「新建」,切到「定时」,用快捷按钮选一个写法,看下面列出的接下来 5 次触发时间;不用保存。也可以对「每日问候」点「立即执行一次」,然后去「执行记录」看它的结果,顶栏铃铛会收到那条问候。演示站是共用的,别停用内置任务。