Celery 连接 Django 项目报 Redis Connection Error 如何排查？

Celery 连接 Redis 报错时，核心排查逻辑是“先网络后配置”。绝大多数问题集中在 Redis 服务不可达、密码认证失败或防火墙拦截。

先说结论：优先确认 Redis 服务进程状态及网络端口连通性，再核对 Django 配置中的连接字符串格式与密码安全性。

先确认：Redis 服务是否运行且端口监听正常（使用 nc 或 redis-cli）
先处理：修正 settings.py 中的 CELERY_BROKER_URL，密码建议使用环境变量
再验证：观察 Celery Worker 启动日志，确认无 Connection refused 或 NOAUTH 错误

快速排查命令

在 Django 应用所在的服务器上执行以下命令，按顺序排查网络与服务状态。

Celery 连接 Django 项目报 Redis Connection Error 如何排查？

# 1. 测试 TCP 端口连通性 (推荐 nc，若未安装可尝试 telnet)
nc -zv <host> <port>

# 2. 测试 Redis 协议连通性 (需安装 redis-tools)
redis-cli -h <host> -p <port> -a <password> ping

# 3. Python 脚本验证 (无 redis-cli 时的替代方案)
python -c "import redis; r = redis.Redis(host='<host>', port=<port>, password='<password>'); print(r.ping())"

注意：若 nc 命令不存在，最小化 Linux 环境可能需要安装 netcat 包，或使用 Python 脚本作为替代验证手段。

Django 配置安全写法

在 settings.py 中配置 Broker URL 时，严禁硬编码明文密码，避免敏感信息泄露至版本控制系统。

# settings.py
import os

# 建议通过环境变量注入敏感信息
REDIS_PASSWORD = os.environ.get('REDIS_PASSWORD', '')
REDIS_HOST = os.environ.get('REDIS_HOST', '127.0.0.1')
REDIS_PORT = os.environ.get('REDIS_PORT', '6379')

# 构建连接字符串
CELERY_BROKER_URL = f'redis://:{REDIS_PASSWORD}@{REDIS_HOST}:{REDIS_PORT}/0'
CELERY_RESULT_BACKEND = f'redis://:{REDIS_PASSWORD}@{REDIS_HOST}:{REDIS_PORT}/1'

若密码中包含特殊字符（如 @, /, :），必须进行 URL 编码，否则会导致连接字符串解析错误。

典型报错日志对照

根据 Celery Worker 启动时的报错信息，可以快速定位问题根源：

Connection refused / Error 111：网络不通或 Redis 服务未启动。检查 netstat -tlnp | grep 6379 及防火墙安全组。
NOAUTH Authentication required：Redis 开启了密码验证但连接串未提供密码，或密码错误。
Invalid password：密码认证失败，核对配置文件中的密码字符串。
Max retries exceeded：连接池耗尽或网络波动，检查 broker_connection_max_retries 配置。

验证是否生效

启动 Celery Worker 后，日志中应出现 Connected to redis://... 字样。随后触发一个异步任务，确认任务状态变为 SUCCESS 且无异常堆栈。

# 启动 Worker 观察日志
celery -A <project_name> worker -l info

常见坑与安全建议

Bind 地址限制：Redis 默认绑定 127.0.0.1，远程连接需修改 redis.conf 中的 bind 配置或注释该行。
密码特殊字符：URL 中的密码若含特殊字符，需使用 urllib.parse.quote_plus 进行编码。
SSL/TLS 配置：若 Redis 启用 SSL，连接串需以 rediss:// 开头，并确保客户端证书配置正确。
版本兼容：某些新版 redis-py 库默认禁用旧版命令，确保客户端库版本与服务端版本匹配。