Docker Compose中redis.createClient()连接Redis报ECONNREFUSED错误

云上老周

2026-8-29

问题原因

Docker Compose 默认会为项目创建独立的桥接网络，网络内每个容器拥有独立的网络栈，容器内的127.0.0.1/localhost/0.0.0.0指向的是容器自身，而非宿主机或其他同网络容器。你之前写的redis://0.0.0.0:6739、redis://localhost:6378本质都是在backend容器自身找Redis服务，backend容器内没有运行Redis进程，自然会报连接拒绝。
你修改端口后依然报127.0.0.1:6379的错误，说明你修改的连接配置根本没有被运行中的服务读取：要么是改完代码没有重新构建镜像、挂载卷的缓存导致旧代码仍在运行，要么是redis.createClient的传参格式错误，客户端 fallback 到了默认的127.0.0.1:6379配置。
你的连接地址存在笔误：第一次写的端口是6739，第二次是6378，和Redis实际监听的6379端口完全不匹配。
你的docker-compose.yml存在缩进不规范问题：redis服务下的所有配置项多缩进了2层，部分Compose版本解析时会出现异常。

修复步骤

修正Redis客户端初始化代码
容器间通信直接使用Compose的服务名作为连接host即可，Compose内置DNS会自动把服务名解析为对应容器的内部网络IP，不需要手动指定IP，也不需要用localhost。正确的初始化代码：

// 注意host为compose中定义的redis服务名，端口为Redis内部监听的6379
const client = redis.createClient({
  url: 'redis://redis:6379'
});
// 如果你用的是Redis Node.js客户端v4及以上版本，必须手动调用connect方法发起连接
client.connect();

修正docker-compose.yml配置
统一缩进规范，不需要额外配置hostname，Compose的服务名本身就可以做DNS解析，修正后的完整配置：

version: "3.7"

services:
  backend:
    container_name: test-server
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ".:/app"
      - "/app/node_modules"
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    stdin_open: true
    tty: true
    depends_on:
      - redis

  redis:
    image: redis
    command: redis-server --port 6379
    container_name: redis
    labels:
      - "name=redis"
      - "mode=standalone"
    ports:
      - "6379:6379"

注意：redis下的6379:6379端口映射是给宿主机直接连接Redis用的，容器间内部通信不需要依赖这个配置。

清除旧缓存重启服务
改完配置后不要直接启动，执行以下命令清除旧容器、旧卷缓存，重新构建镜像启动：

docker compose down -v
docker compose up --build

连通性排查

如果按上述步骤操作后依然连接失败，按以下顺序排查：

进入backend容器内部测试网络连通性：

# 进入backend容器命令行
docker exec -it test-server sh
# 若容器内没有redis-cli，先安装（Alpine镜像用以下命令，Debian镜像换apt即可）
apk add --no-cache redis
# 测试通过服务名连接Redis
redis-cli -h redis -p 6379 ping

如果命令返回PONG，说明容器间网络正常，问题出在Node.js代码层面：检查Redis客户端版本、传参格式，确认是否漏写client.connect()调用，确认配置文件是否被正确加载。

不要完全依赖depends_on判断服务状态：depends_on只会等待redis容器启动完成，不会等待Redis服务真正就绪监听端口，如果backend启动时Redis还没完成初始化，第一次连接会失败，建议给Redis客户端配置自动重连逻辑，或者给redis服务配置healthcheck，通过service_healthy条件控制backend启动顺序。

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