【免费下载链接】context-hub项目地址https://gitcode.com/gh_mirrors/co/context-hub点击查看免费下载django-q2是一个 Django 原生的任务队列与调度器专为需要后台作业、周期调度和 Worker 集群的 Django 应用设计可避免引入 Celery 这类更重的分布式框架。本文以 Context Hub 维护者版本的 django-q2 1.9.0 文档content/django/docs/q2/python/DOC.md为主体结合仓库中该文档的 frontmatter 结构、CLI 解析与注册表实现完整讲解安装、集群配置、任务 API、定时调度、Broker 选型与常见陷阱帮助你从零跑通入队 → 后台执行 → 读取结果的完整链路。安装与可选依赖django-q2通过 pip 安装若项目对版本有锁定需求应显式指定版本python -m pip install django-q21.9.0根据官方文档与包元数据以下可选依赖分别支撑不同能力依赖用途redisRedis Brokerboto3SQS BrokerpymongoMongoDB BrokercroniterCron 调度表达式blessedqmonitor、qmemory监控命令psutilcpu_affinity性能调优例如需要 Redis Broker 与 Cron 调度时python -m pip install django-q21.9.0 redis croniter blessed需要注意一个贯穿全文的命名差异pip 包名是django-q2但 Django app label 与导入命名空间都是django_q下划线。这与其他常见包如 django-celery-beat 的django-celery-beat/django_celery_beat保持同样的惯例。最小 Django 接入1. 注册应用并迁移在INSTALLED_APPS中加入django_q# settings.py INSTALLED_APPS [ # ... django_q, ]python manage.py migrate2. 选择 Broker 并定义Q_CLUSTERRedis 是大多数非平凡部署的最佳默认选择# settings.py import os Q_CLUSTER { name: default, workers: 4, timeout: 90, retry: 120, recycle: 500, queue_limit: 50, save_limit: 250, label: Django Q2, redis: os.environ[REDIS_URL], }本地开发或小型安装则可用更简单的 ORM BrokerQ_CLUSTER { name: default, workers: 2, timeout: 90, retry: 120, queue_limit: 50, bulk: 10, orm: default, }3. 启动独立集群进程django-q2不会在 Web 进程内执行入队任务必须在独立进程中启动集群python manage.py qcluster说明集群进程通过 Django Q2 内部的 sentinel 管理一个 Worker 池。单队列场景只需启动一个集群进程并通过workers、timeout、recycle等设置横向扩容该集群而不是重复启动多个相同的集群监督进程详见下文常见陷阱。多队列集群的运行与路由按集群名启动若使用多个队列可通过环境变量Q_CLUSTER_NAME指定集群名启动Q_CLUSTER_NAMElong python manage.py qcluster任务按集群路由入队时用cluster参数把任务投递到指定命名集群from django_q.tasks import async_task async_task(myapp.tasks.generate_report, report_id, clusterlong)调度任务同样可以约束到某个命名集群通过schedule()的cluster参数见下文。核心任务用法入队一个普通可调用对象from django_q.tasks import async_task task_id async_task( myapp.tasks.send_welcome_email, user_id, groupemail, timeout60, hookmyapp.hooks.on_welcome_email_complete, )任务函数就是普通 Django 代码# myapp/tasks.py from django.core.mail import send_mail def send_welcome_email(user_id: int) - None: send_mail( subjectWelcome, messagefUser {user_id} signed up., from_emailnoreplyexample.com, recipient_list[opsexample.com], )读取结果与任务记录from django_q.tasks import fetch, result value result(task_id, wait200) task fetch(task_id, wait200)wait参数用于等待任务完成单位通常为毫秒。Agent 通常最需要的任务 APIasync_task()入队工作result()获取已保存的结果fetch()获取完整任务记录result_group()/fetch_group()处理分组任务async_iter()批量扇出fan-out任务免去手动循环使用q_options避免参数冲突如果任务函数本身需要名为hook、group、timeout的关键字参数应把队列选项放进q_options避免与函数签名冲突from django_q.tasks import async_task opts { group: reports, timeout: 30, hook: myapp.hooks.on_report_complete, } async_task(myapp.tasks.build_report, report_id, q_optionsopts)复用 Broker 连接批量入队重复入队时可复用同一个 broker 连接减少连接开销from django_q.brokers import get_broker from django_q.tasks import async_task broker get_broker() for report_id in report_ids: async_task(myapp.tasks.build_report, report_id, brokerbroker)定时调度调度可从代码创建也可在 Django admin 中管理。Cron 调度需要croniter。Cron 调度工作日每天 8 点永久重复from django_q.models import Schedule from django_q.tasks import schedule schedule( myapp.tasks.send_digest, schedule_typeSchedule.CRON, cron0 8 * * 1-5, repeats-1, clusterdefault, )间隔调度每 5 分钟一次共 24 次from datetime import datetime from django_q.models import Schedule from django_q.tasks import schedule schedule( myapp.tasks.refresh_metrics, schedule_typeSchedule.MINUTES, minutes5, repeats24, next_rundatetime.utcnow().replace(hour18, minute0), )让任务感知本应运行的时间点若任务需要知道它原本被安排在何时运行用intended_date_kwargschedule( myapp.tasks.run_billing_cycle, schedule_typeSchedule.DAILY, intended_date_kwargscheduled_for, )这样任务函数会收到名为scheduled_for的关键字参数携带原始计划执行时间。实践中最重要的调度字段字段含义schedule_typeonce、minutes、hourly、daily、weekly、monthly、quarterly、yearly 或 cronminutesSchedule.MINUTES的间隔分钟数cronSchedule.CRON的 cron 表达式repeats-1表示永久重复next_run首次执行时间cluster将调度任务路由到某个命名集群q_options每条调度专属的任务选项如timeout、broker_name配置与 Broker / 认证模型django-q2没有包级认证系统。访问控制完全来自你在Q_CLUSTER中配置的 Broker 或后端。RedisURI 方式Q_CLUSTER { name: default, workers: 4, timeout: 90, retry: 120, redis: redis://user:passwordredis.example.com:6379/0, }Redisdjango-redis 方式Q_CLUSTER { name: default, workers: 4, timeout: 90, django_redis: default, }Amazon SQSimport os Q_CLUSTER { name: sqs, workers: 4, timeout: 60, retry: 90, queue_limit: 100, bulk: 5, sqs: { aws_region: us-east-1, aws_access_key_id: os.environ[AWS_ACCESS_KEY_ID], aws_secret_access_key: os.environ[AWS_SECRET_ACCESS_KEY], }, }运维关键设置workers集群进程数timeout单个任务的最大运行时长retry支持回执receipt能力的 Broker 的重新投递延迟recycle每处理 N 个任务后重启 Workersave_limit保留多少条成功任务结果queue_limit内存中可排队的任务上限sync强制同步执行主要用于测试catch_up停机后错过的调度是否回放cpu_affinity可选性能调优需要psutil同一队列多集群进程的前提条件所有要处理同一队列的集群进程必须满足使用同一个 Broker使用同一个集群名name使用同一个 DjangoSECRET_KEY文档特别强调Django Q2 会使用SECRET_KEY对任务包签名因此跨 Worker 实例必须保持SECRET_KEY一致否则任务验签会失败。管理命令python manage.py migrate python manage.py qcluster python manage.py qmonitor python manage.py qmemory python manage.py qinfo其中qmonitor与qmemory需要blessed终端渲染支持。常见陷阱包名与导入名不一致pip 包是django-q2但INSTALLED_APPS与导入使用django_q。没有集群进程就没有后台执行除非运行qcluster进程或显式开启 sync 模式否则不会有任何后台任务执行。retry必须大于timeout且要大于真实任务的最长耗时否则带投递回执的 Broker 可能重复执行同一任务。syncTrue只用于测试与调试它绕过 Broker不能验证生产 Worker 行为。可选依赖缺一不可Cron 调度需要croniter监控命令需要blessedRedis、SQS、MongoDB、CPU 亲和性分别需要各自的可选依赖。ORM Broker 定位是本地开发Redis 或其他外部 Broker 才是生产吞吐与故障处理下的更安全默认。catch_up默认回放错过的调度如果停机后不希望出现积压突发设置catch_up: False。参数名冲突时使用q_options当任务选项名与函数关键字参数同名时把它们放进q_options。不要靠多启动相同集群进程来扩容官方集群文档建议优先调整workers、recycle与timeout。面向 1.9.0 的版本敏感说明本文档对应版本为1.9.0。官方文档流Read the Docs部分页面仍显示 Django Q2 1.6.0 的品牌信息因此在线文档适合作为概念与配置层面的参考而非 1.9.0 的精确版本快照。官方v1.8.0发布说明指出已放弃对 Python 3.8 的支持不要假设 1.9.0 仍兼容 Python 3.8。官方v1.9.0发布说明特别提及两项运维相关变更修复了与redis-py 5的兼容性并新增 Django 6.0 支持。若项目实际行为与在线文档不一致应以当前安装的包版本、PyPI 元数据及对应系列的官方发布说明为准。推荐的 Agent 工作流先确认项目确实需要 Django 原生队列而非更分布式的系统。写任务代码之前先添加django_q、执行迁移并选定 Broker。尽早启动一个真实的qcluster进程端到端验证一条简单的async_task()路径。显式设置timeout、retry与catch_up而不是无意间沿用默认值。基础后台执行跑通之后再添加调度任务。排查版本相关行为时以安装包与官方发布说明为准因为在线文档流更新滞后。在 Context Hub 中获取与使用本文档本文档是 Context Hub 仓库中维护者source: maintainer维护的版本化内容遵循仓库统一的文档规范见 docs/content-guide.md文档存放路径为 content/django/docs/q2/python/DOC.mdfrontmatter 声明了languages: python、versions: 1.9.0、revision: 2与tags供 CLI 的搜索索引与注册表使用仓库 CLI 通过 frontmatter 解析cli/src/lib/frontmatter.js读取文档元数据并在搜索与获取流程cli/src/lib/registry.js中按语言、版本解析 DOC.md 路径编码 Agent 可在写 django-q2 代码前执行chub get django/q2 --lang py拉取本文档用法见 cli/skills/get-api-docs/SKILL.md并在发现文档未覆盖的坑时通过chub annotate记录本地笔记通过chub feedback将反馈回流给维护者。结合本仓库的 README.md 与 llms.txt 可知这类文档旨在为 Agent 提供版本化、按语言组织、可直接引用的 API 指南因此本文档中的代码示例、参数表格与陷阱清单都应当被视为可直接复制执行的实战素材——入队、集群、调度三步走即可让 Django 项目具备完整的后台任务能力。赞分享【免费下载链接】context-hub项目地址https://gitcode.com/gh_mirrors/co/context-hub点击查看免费下载相关推荐Django Q 任务管理后台使用指南从成功任务到定时调度Django Q 任务管理后台使用指南从成功任务到定时调度 前言 Django Q 是一个强大的异步任务队列和调度系统它为 Django 项目提供了简单高效WinUtilWindows系统优化与批量安装的终极工具箱WinUtilWindows系统优化与批量安装的终极工具箱 你是否曾经为新电脑配置软件而烦恼是否想要一键优化Windows系统设置WinUtil正是你寻找桌面应用运维Claude API PHP 官方 SDK 实战指南安装、多平台客户端、消息请求与高级特性Claude API PHP 官方 SDK 实战指南安装、多平台客户端、消息请求与高级特性 本文基于本仓库 skills/claude api 技能集中的 P上一篇Digital颠覆性开源数字电路设计与仿真的一站式解决方案下一篇Windows 10免费安装Android子系统终极完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考