使用Docker启动后端时出现SequelizeConnectionRefusedError连接失败问题

执行docker compose up启动后端时，抛出错误：

ConnectionRefusedError [SequelizeConnectionRefusedError]: connect ECONNREFUSED 172.20.0.2:5432

Postgres容器（node_db）已正常运行，但后端服务（customerportal）无法完成连接初始化，相关配置代码如下：

数据库配置（database.js） #

const Sequelize = require('sequelize');

const sequelize = new Sequelize(
  process.env.PGDATABASE,
  process.env.PGUSER,
  process.env.PGPASSWORD,
  {
    host: process.env.PGHOST,
    dialect: 'postgres'
  }
)

module.exports = sequelize;

Dockerfile #

FROM node:14

EXPOSE 3001

WORKDIR /src

RUN npm install i npm@latest -g

COPY package.json package-lock*.json ./

RUN npm install

COPY . .

CMD ["node", "app/index.js"]

docker-compose.yml #

services:
  node_backend:
    container_name: customerportal
    image: customerportal:0.0.4
    build:
      context: .
    ports:
      - "3001:3001"
    environment:
      - EXTERNAL_PORT=3001
      - PGDATABASE=customerportal_db
      - PGUSER=filip
      - PGPASSWORD=12345
      - PGHOST=node_db
    depends_on:
      - node_db
  node_db:
    container_name: node_db
    image: "postgres:15"
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_USER=filip
      - POSTGRES_PASSWORD=12345
      - POSTGRES_DB=customerportal_db
    volumes:
      - nps_data:/var/lib/postgresql/data

volumes:
  nps_data: {}

核心原因：容器启动顺序≠服务就绪 #

depends_on仅能保证node_db容器先于后端启动，但PostgreSQL 15启动时需要完成数据库初始化、用户创建等操作，这个过程需要几秒时间。后端容器启动后会立即尝试连接，此时数据库服务还未完全就绪，因此抛出连接拒绝错误。

排查方向 #

• 网络连通性验证：进入后端容器执行ping node_db和telnet node_db 5432，确认网络是否可达。如果ping通但telnet失败，说明数据库端口未开放或服务未就绪。
• 环境变量检查：在后端容器内执行docker exec customerportal printenv，确认PGHOST、PGDATABASE等变量与docker-compose配置一致。
• Postgres日志排查：执行docker logs node_db，如果日志中出现database system is ready to accept connections，说明数据库服务已就绪。

解决方案 #

方案1：添加启动等待脚本 #

使用wait-for-it.sh让后端等待Postgres端口开放后再启动：

1. 下载脚本到项目根目录：

curl -O https://raw.githubusercontent.com/vishnubob/wait-for-it/master/wait-for-it.sh
chmod +x wait-for-it.sh

2. 修改Dockerfile的启动命令：

CMD ["./wait-for-it.sh", "node_db:5432", "--", "node", "app/index.js"]

方案2：配置Docker Compose健康检查 #

给Postgres容器添加健康检查，让后端仅在数据库就绪后启动：

services:
  node_backend:
    # 保留原有配置
    depends_on:
      node_db:
        condition: service_healthy
  node_db:
    # 保留原有配置
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U filip -d customerportal_db"]
      interval: 2s
      timeout: 5s
      retries: 5

方案3：应用代码添加重连逻辑 #

修改Sequelize初始化代码，增加自动重连机制：

const Sequelize = require('sequelize');

const sequelize = new Sequelize(
  process.env.PGDATABASE,
  process.env.PGUSER,
  process.env.PGPASSWORD,
  {
    host: process.env.PGHOST,
    dialect: 'postgres',
    retry: {
      match: [/ConnectionRefusedError/],
      max: 5,
      backoffBase: 1000,
      backoffExponent: 1.5
    }
  }
);

async function connect() {
  try {
    await sequelize.authenticate();
    console.log('数据库连接成功');
  } catch (error) {
    console.log('数据库连接失败，正在重试...');
    setTimeout(connect, 2000);
  }
}

connect();

module.exports = sequelize;

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