简介：这是一份专为Django开发者设计的Celery异步任务进度可视化轻量级解决方案，面向中初级Web后端工程师，解决Celery任务执行过程缺乏实时进度反馈的常见痛点。资源包共17个文件，含11个Python核心模块（如tasks.py、views.py、backend.py）、2个JavaScript前端交互脚本（支撑进度条动态渲染）、1个README.md说明文档、1个LICENSE授权文件及配置类文件，整体仅14KB，结构精简无冗余依赖。已有417人学习下载，体现其在Django+Celery工程实践中的实用热度。用户可直接获得开箱即用的进度条集成方案：包含完整的Django URL路由配置、后台任务状态轮询机制、前端JS事件绑定逻辑，以及配套的静态资源组织方式；预览显示项目已实现从settings注册、URL挂载到模板渲染的全链路示例，大幅降低Celery进度功能的接入门槛。
1. celery-progress：为什么 Django + Celery 的任务进度总像黑匣子？
你写好了异步任务，加了@shared_task，也配好了 Redis Broker，任务能跑、日志有输出、结果能取回——但用户点下“开始处理 5000 条订单”后，页面就卡在“正在执行…”不动，连个百分比都没有。这不是体验问题，是信任崩塌：用户不知道是卡住了、失败了，还是只是慢；运维查日志要翻十几屏；前端不敢加重试逻辑，怕重复提交；更别说做超时熔断或资源预估。
celery-progress就是为解决这个「进度不可见」而生的轻量方案：它不改 Celery 核心调度逻辑，不依赖前端框架（Vue/React 都可接），不强制用特定数据库（Redis 就够），也不要求你动 Django Model 或重写任务函数——只靠一个装饰器 + 一行前端轮询，就能把任意@task的执行过程变成可读、可测、可干预的实时流。它不是监控平台，而是给每个 Celery 任务装上「进度探针」：从0%到100%，中间每一步update_state(state='PROGRESS', meta={'current': 123, 'total': 5000})都能被结构化捕获。适合所有已上线 Celery 的 Django 项目，尤其当你正被「用户投诉任务没反应」「测试环境进度永远卡 99%」「临时加个进度条要三天排期」这类问题反复消耗时——它就是那条不用改架构、不引入新服务、今天下午就能上线的「后悔药」。
2. 用 celery-progress 在本地跑通最小可运行示例
2.1 安装与基础集成：三行命令 + 一个装饰器
先确认环境：Django ≥ 3.2，Celery ≥ 5.0（推荐 5.3+），Redis 已作为 Broker 运行（redis-server默认端口 6379）。
pip install celery-progress django-celery-progress提示：
celery-progress是核心库（提供ProgressRecorder和状态更新逻辑），django-celery-progress是 Django 专用胶水层（含视图、模板、静态文件）。两者必须同时安装，缺一不可。
然后在 Django 的settings.py中注册应用：
# settings.py INSTALLED_APPS = [ # ... 其他 app 'django_celery_progress', ]接着在urls.py中挂载进度查询端点（无需自定义视图）：
# urls.py from django.urls import path, include urlpatterns = [ # ... 其他路由 path('celery-progress/', include('django_celery_progress.urls')), ]最后，在celery.py或任务模块中启用ProgressRecorder：
# tasks.py from celery import shared_task from celery_progress.backend import ProgressRecorder @shared_task def long_running_task(total=1000): progress_recorder = ProgressRecorder(long_running_task) for i in range(total): # 模拟耗时操作（如数据库批量更新、文件解析） import time time.sleep(0.01) # 每次迭代上报当前进度 progress_recorder.set_progress(i + 1, total, description=f"处理第 {i+1} 条") return f"完成 {total} 条"逻辑说明：
ProgressRecorder(task)会自动绑定当前任务实例，调用set_progress(current, total, description)时，它将生成标准 Celery 状态事件（state='PROGRESS',meta={'current':..., 'total':..., 'description':...}），并存入 Redis（使用 Celery 默认 result backend）。关键点：set_progress不阻塞任务执行，且description字段支持中文和动态变量，前端可直接渲染。
2.2 前端轮询：用原生 fetch 实现零框架进度条
Celery 任务启动后，前端需主动轮询/celery-progress/接口获取状态。该接口返回 JSON，结构固定：
{ "complete": false, "success": true, "progress": { "current": 42, "total": 1000, "percent": 4.2, "description": "处理第 42 条" } }以下是一个最小可用 HTML + JS 示例（无需构建工具，直接<script>内联）：
<!-- index.html --> <button id="start-btn">启动任务</button> <div id="progress-bar" style="width: 300px; height: 20px; background: #eee; margin: 10px 0;"> <div id="progress-fill" style="height: 100%; width: 0%; background: #4CAF50; transition: width 0.3s;"></div> </div> <p id="progress-text">等待启动...</p> <script> let task_id = null; const startBtn = document.getElementById('start-btn'); const progressBar = document.getElementById('progress-bar'); const progressFill = document.getElementById('progress-fill'); const progressText = document.getElementById('progress-text'); startBtn.addEventListener('click', async () => { // 1. 启动 Celery 任务（假设你的任务 URL 是 /api/start-task/） const res = await fetch('/api/start-task/', { method: 'POST' }); const data = await res.json(); task_id = data.task_id; // 2. 开始轮询进度 const pollInterval = setInterval(async () => { if (!task_id) return; try { const progressRes = await fetch(`/celery-progress/?id=${task_id}`); const progressData = await progressRes.json(); if (progressData.complete) { clearInterval(pollInterval); progressText.textContent = `任务完成：${progressData.result}`; return; } // 更新 UI const percent = progressData.progress.percent || 0; progressFill.style.width = `${percent}%`; progressText.textContent = progressData.progress.description || `进度 ${percent.toFixed(1)}%`; } catch (e) { console.error('轮询失败', e); progressText.textContent = '连接失败，请重试'; } }, 500); // 每 500ms 查一次，生产环境建议 1-2s }); </script>参数说明：
?id=${task_id}是必须参数，值为 Celery 任务返回的task.id（字符串）；- 轮询间隔
500ms是开发调试值，线上建议设为1000-2000ms，避免压垮 Redis；progressData.complete === true表示任务已结束（无论成功/失败），此时progressData.result为返回值或错误信息；- 若任务抛出异常，
progressData.success为false，progressData.result包含 traceback（默认开启，可通过CELERY_TASK_SERIALIZER='json'关闭敏感信息）。
3. 自定义进度上报：从「固定步长」到「真实业务节点」
3.1 用update_state()手动控制进度粒度
ProgressRecorder.set_progress()适合线性循环场景，但真实任务常含多阶段：数据校验 → 数据清洗 → 模型推理 → 结果入库。若强行用i+1/total，进度条会「假快真慢」——前 10% 花 1 秒，后 90% 卡 3 分钟。这时需手动调用 Celery 原生update_state()：
# tasks.py from celery import shared_task @shared_task(bind=True) # 注意：必须加 bind=True，才能访问 self def multi_stage_task(self, file_path): # 阶段 1：校验（快） self.update_state( state='PROGRESS', meta={ 'current': 1, 'total': 4, 'stage': 'validate', 'description': '正在校验文件格式...' } ) validate_file(file_path) # 阶段 2：清洗（中等） self.update_state( state='PROGRESS', meta={ 'current': 2, 'total': 4, 'stage': 'clean', 'description': '正在清洗脏数据...' } ) clean_data(file_path) # 阶段 3：推理（慢，需细粒度） model = load_model() total_rows = count_rows(file_path) for i, row in enumerate(read_rows(file_path)): predict(model, row) # 每 10 行报一次（避免 Redis 写风暴） if i % 10 == 0: self.update_state( state='PROGRESS', meta={ 'current': 2 + (i / total_rows) * 1, 'total': 4, 'stage': 'infer', 'description': f'模型推理中：{i}/{total_rows}' } ) # 阶段 4：入库（快） self.update_state( state='PROGRESS', meta={ 'current': 4, 'total': 4, 'stage': 'save', 'description': '正在保存结果...' } ) save_results() return "全部完成"逻辑说明：
bind=True让任务函数获得self引用，从而调用self.update_state()；meta字段完全自定义：stage用于前端分阶段样式（如不同颜色进度条），current/total仍按 0–100% 映射，但计算逻辑由你掌控；- 关键技巧：避免高频上报。每循环一次都
update_state()会导致 Redis QPS 暴涨（尤其total=10w时），应按比例（如i % 100 == 0）或时间窗口（time.time() - last_update > 1.0）限流。
3.2 前端适配多阶段：用 CSS 变量动态切换进度条主题
当后端传回meta.stage，前端可据此改变 UI：
<!-- 在轮询回调中 --> if (progressData.progress.stage) { progressBar.style.setProperty('--stage', `"${progressData.progress.stage}"`); // 或直接加 class progressBar.className = `progress-stage-${progressData.progress.stage}`; }配合 CSS：
/* 支持 stage 类型：validate/clean/infer/save */ .progress-stage-validate { background: #e3f2fd; } .progress-stage-clean { background: #fff3cd; } .progress-stage-infer { background: #f8d7da; } .progress-stage-save { background: #d4edda; } .progress-stage-validate #progress-fill { background: #2196f3; } .progress-stage-clean #progress-fill { background: #ffc107; } .progress-stage-infer #progress-fill { background: #dc3545; } .progress-stage-save #progress-fill { background: #28a745; }提示：
celery-progress不限制meta结构，所有字段都会透传到前端。这意味着你可以加estimated_time_left、error_count、retry_times等业务字段，只要后端写进去、前端读出来即可——它本质是「状态管道」，不是「进度规范」。
4. 避坑：celery-progress 的 4 个血泪经验
4.1 现象：进度条永远停在 0%，但任务实际已执行完毕
原因：Celery 任务未正确配置result_backend，或CELERY_RESULT_BACKEND指向了不支持get_task_meta()的后端（如rpc://或未启用的数据库）。celery-progress依赖app.AsyncResult(task_id).result读取状态，若 backend 不支持，/celery-progress/接口始终返回空。
解决：确认settings.py中设置了CELERY_RESULT_BACKEND = 'redis://127.0.0.1:6379/1'（与BROKER_URL分开库），并确保 Redis 实例正常运行。用celery -A proj inspect active_queues验证 broker 连通性。
4.2 现象：前端轮询返回{"complete": false, "success": true, "progress": {}}，progress字段为空
原因：任务中未调用set_progress()或update_state()，或调用时state不是'PROGRESS'（如误写成'PROGESS'）。celery-progress只识别state='PROGRESS'的事件。
解决：在任务中加日志验证：
self.update_state(state='PROGRESS', meta={'debug': 'hit here'}) # 确保这行被执行再检查 Redis 中对应 key：celery-task-meta-{task_id}是否存在PROGRESS状态记录（用redis-cli执行HGETALL "celery-task-meta-xxx"）。
4.3 现象：进度条跳变（如 0%→75%→20%→100%），数值不连续
原因：多个进程/线程并发执行同一任务（如 Celery worker 开了 4 个进程，但任务未加锁），导致update_state()被多次调用，Redis 中的meta被后写覆盖。
解决：
- 方案 A（推荐）：任务加分布式锁（如
redis-py的lock），确保单任务单执行； - 方案 B：改用
current累加式上报（如current += 10），而非绝对位置（current = i）； - 方案 C：前端做平滑处理——只接受
percent递增的更新，丢弃倒退值。
4.4 现象：Django Admin 中任务状态显示正常，但/celery-progress/返回 404
原因：django-celery-progress的 URL 配置未生效，常见于：
urls.py中include()未加尾部/（应为include('django_celery_progress.urls')，不是include('django_celery_progress.urls/')）；- Django 版本 ≥ 4.0 时，
path()第二个参数需为include(...)，不能是字符串； INSTALLED_APPS中django_celery_progress未添加，或拼写错误（如django_celery_progress写成django-celery-progress）。
解决：运行python manage.py show_urls（需安装django-extensions），确认/celery-progress/路由是否存在；检查INSTALLED_APPS拼写，重启 Django 开发服务器。
5. 生产级加固：超时控制、错误降级与前端防抖
5.1 给轮询加超时熔断：避免无限等待
用户网络波动或 Celery worker 挂起时，前端轮询可能持续数分钟。需设置最大等待时间：
// 修改轮询逻辑 let startTime = Date.now(); const MAX_WAIT_MS = 5 * 60 * 1000; // 5 分钟 const pollInterval = setInterval(async () => { if (Date.now() - startTime > MAX_WAIT_MS) { clearInterval(pollInterval); progressText.textContent = '任务超时，请稍后重试或联系管理员'; return; } // ... 原轮询逻辑 }, 1000);进阶技巧：后端任务也可设硬超时。在
@shared_task中加soft_time_limit=120, time_limit=180，Celery 会在 120s 发送SoftTimeLimitExceeded信号（可捕获并优雅退出），180s 强制 kill 进程。此时celery-progress会收到state='FAILURE'，前端可展示具体超时提示。
5.2 错误状态分级：区分「可恢复」与「需人工介入」
celery-progress默认将所有异常归为success=false，但业务需区分：
- 网络抖动导致的临时失败（重试即可）；
- 数据格式错误（需用户修正输入）；
- 系统资源不足（需运维扩容）。
改造任务，让meta携带错误码：
@shared_task(bind=True, autoretry_for=(ConnectionError,), retry_kwargs={'max_retries': 3}) def robust_task(self, payload): try: do_work(payload) except ValidationError as e: self.update_state( state='FAILURE', meta={ 'error_code': 'VALIDATION_ERROR', 'message': str(e), 'suggestion': '请检查上传文件格式' } ) raise except Exception as e: self.update_state( state='FAILURE', meta={ 'error_code': 'SYSTEM_ERROR', 'message': '服务内部异常', 'suggestion': '已通知运维团队' } ) raise前端根据error_code渲染不同提示：
if (!progressData.success && progressData.result?.error_code) { const err = progressData.result; progressText.innerHTML = ` <span style="color:red">❌ ${err.message}</span><br> <small>${err.suggestion}</small> `; }5.3 前端防抖：防止用户狂点「启动」导致任务堆积
用户连续点击按钮，会触发多个相同任务，造成资源浪费。用简单防抖：
let isTaskRunning = false; startBtn.addEventListener('click', () => { if (isTaskRunning) { alert('任务已在运行中，请勿重复提交'); return; } isTaskRunning = true; startBtn.disabled = true; startBtn.textContent = '运行中...'; // 任务完成后重置 // （在轮询 complete 回调中） // isTaskRunning = false; // startBtn.disabled = false; // startBtn.textContent = '启动任务'; });我的血泪经验：上线前必做三件事——
- 用
celery -A proj control inspect看 worker 是否健康；- 在 Redis CLI 中手动
HGETALL "celery-task-meta-{id}"验证状态写入；- 用 Chrome DevTools 的 Network 面板，过滤
/celery-progress/请求，确认响应时间 < 50ms（否则优化 Redis 连接池）。
celery-progress的价值不在炫技，而在把「看不见的后台」变成「可对话的流程」。当用户看到「正在清洗脏数据（321/5000）」，焦虑就少了三分；当你在日志里看到stage='infer', current=2.75，排查就快了一倍。它不解决所有问题，但让每个问题都变得可定位、可解释、可沟通。希望帮到你。
本文还有配套的精品资源，点击获取
