本地部署Git克隆版Mayan EDMS遇文档不显示、Celery启动失败问题

文档上传后长期停留在New document queued for upload and will be available shortly提示的核心原因是异步任务链路不通：Mayan EDMS 所有文档解析、预览生成、索引构建的后置逻辑全部走Celery异步队列，Worker进程异常退出或未正常运行时，上传任务会全部堆积在Redis队列中无法被消费，前端自然无法展示已上传的文档。

第一步：解决Celery Worker启动失败问题 #

• 校验依赖与启动命令正确性
  源码部署场景下禁止直接使用原生celery命令启动Worker，容易出现应用加载路径错误、配置未读取的问题。先在项目根目录激活对应虚拟环境，执行pip install -r requirements.txt完成全量依赖安装，再执行python manage.py check运行Django环境校验，确认无配置类错误后，使用Mayan封装的官方入口启动：
  • 3.x版本：python manage.py celery worker --loglevel=INFO
  • 4.x及以上版本：./manage.py mayan_platform celery_worker
• 排查Redis连通性问题
  先执行redis-cli ping确认本地Redis服务正常运行，返回PONG才代表服务可用。再核对配置文件中CELERY_BROKER_URL、CELERY_RESULT_BACKEND两个参数，本地部署默认连接地址为redis://127.0.0.1:6379/0，如果本地Redis修改过端口、设置了密码、使用了其他数据库编号，两个参数必须同步修改。
  可以进入Django shell执行代码验证Broker连接是否正常：

  from celery import current_app
  print(current_app.connection().connect())
  

  代码返回True代表连接正常，抛出异常时根据报错信息调整Redis配置即可。
• 排查权限与缓存问题
  确认MEDIA_ROOT文档存储目录、系统临时文件目录的权限，保证运行Web服务和Worker的用户对两个目录有读写权限，可执行chmod -R 755 <你的MEDIA_ROOT路径> /tmp给足权限，权限不足时Worker读取不到上传的源文件会直接崩溃退出。
  如果启动时提示任务重复注册，递归删除项目下所有__pycache__缓存目录后重试即可。禁止使用root用户启动Worker，Mayan内置的安全校验会直接拦截root用户启动的异步进程。

第二步：验证任务消费链路 #

• Worker正常启动后，终端会打印已注册的任务列表，确认列表中包含documents.tasks.task_document_upload等文档处理类任务，代表任务加载正常。
• 新开终端进入项目虚拟环境，执行python manage.py celery inspect active，能正常返回Worker运行状态代表调度链路通信正常。
• 执行redis-cli llen celery查看队列长度，正常运行状态下堆积的任务会被逐步消费，队列长度持续下降。如果队列长期无变化，执行python manage.py celery purge清空之前堆积的异常任务，重新上传文档测试即可。
• 队列消费完成后刷新前端页面，即可正常看到已上传的文档内容，排队提示会自动消失。

注：之前遇到的静态文件异常如果还未修复，执行python manage.py collectstatic --noinput重新收集所有静态资源，保证前端静态资源加载正常即可。

内容的提问来源于stack exchange，提问作者Mursaleen