生产环境中NestJS+Bull Queue连接Redis遇maxRetriesPerRequest错误

问题背景 #

项目基于NestJS 9.2.0 + Bull Queue 4.9.0，通过Redis调度任务，本地运行正常，但部署到预发布环境时Bull无法连接Redis，抛出maxRetriesPerRequest错误。已尝试以下方案未解决：

• 使用rediss://协议的Redis URL
• 在URL后追加?tls=true参数
• 在Redis配置中传入空对象tls: {}并在AppModule的BullModule工厂中配置

怀疑是TLS连接问题的依据：

1. 本地无TLS的Redis连接完全正常
2. 本地设置无效URL模拟连接失败时，控制台报错表现与预发布/生产环境一致
3. 已确认预发布、生产环境的Redis实例运行正常，URL配置正确

可行排查与解决步骤 #

1. 按照ioredis规范配置TLS参数 #

Bull Queue底层依赖ioredis，需遵循其TLS配置规则，而非简单传空对象或URL参数。尝试在BullModule中明确指定完整TLS配置：

// app.module.ts
import { BullModule } from '@nestjs/bull';
import * as fs from 'fs';

@Module({
  imports: [
    BullModule.forRootAsync({
      useFactory: () => ({
        redis: {
          host: process.env.REDIS_HOST,
          port: parseInt(process.env.REDIS_PORT),
          password: process.env.REDIS_PASSWORD,
          tls: {
            rejectUnauthorized: process.env.NODE_ENV === 'production', // 生产环境建议开启证书验证
            // 若Redis使用自定义CA证书，需添加以下配置
            // ca: fs.readFileSync('/path/to/your-ca-cert.pem'),
          },
        },
      }),
    }),
  ],
})
export class AppModule {}

2. 修正Redis URL格式 #

使用rediss://协议时，无需额外追加tls=true参数，确保URL包含完整认证信息：

rediss://:<password>@<host>:<port>

部分托管Redis服务（如AWS ElastiCache）可能需要禁用rejectUnauthorized，需根据服务端要求调整。

3. 验证Redis服务端TLS可用性 #

用redis-cli直接测试预发布环境的Redis连接，确认TLS服务正常：

redis-cli -h <host> -p <port> -a <password> --tls

若该命令能成功连接，说明Redis服务端TLS配置正常，问题出在应用端配置。

4. 锁定依赖版本兼容性 #

Bull Queue 4.9.0适配ioredis@4.x系列版本，若项目自动升级到ioredis@5.x可能出现配置不兼容，建议在package.json中锁定版本：

{
  "dependencies": {
    "ioredis": "^4.28.5"
  }
}

5. 启用调试日志定位细节 #

启动服务时添加环境变量开启Bull调试日志，查看连接失败的具体原因：

DEBUG=bull* npm run start:prod

日志会输出Redis握手、证书验证等环节的错误信息，帮助精准定位问题。

总结 #

maxRetriesPerRequest是连接多次失败后的兜底错误，核心原因多为TLS配置不匹配或握手失败。重点排查ioredis的TLS参数是否符合Redis服务端要求，结合调试日志和CLI验证缩小问题范围。

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