Docker-Compose启动的Postgres容器本地DBeaver连接超时问题解决

场景还原 #

• 最初直接用docker run启动Postgres容器时，本地DBeaver工具和C#项目都能正常连接数据库，执行表创建、初始化操作无任何问题
• 改用Docker Compose同时部署C#服务和Postgres服务后出现异常：
  • 处于同一Docker网络内的C#服务可以正常连接Postgres，业务逻辑运行正常
  • 本地通过DBeaver连接Postgres时持续出现连接超时错误

问题排查与定位 #

1. 检查Docker Compose配置中的Postgres端口映射规则，发现配置的宿主机映射端口为5040:5432
2. 确认当前运行的所有容器未占用5040端口，但通过Windows系统端口排查命令（netstat -ano | findstr :5040）发现，该端口疑似被系统进程占用
3. 将宿主机映射端口更换为5041:5432或5060:5432后，本地DBeaver立即可以正常连接Postgres

示例配置对比 #

问题版配置（端口5040导致本地连接失败） #

version: '3.8'
services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: apppass
      POSTGRES_DB: appdb
    ports:
      - "5040:5432"  # 此端口被系统占用，导致本地工具无法访问
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - app-network

  csharp-service:
    build: .
    environment:
      ConnectionStrings__DefaultConnection: "Host=postgres;Port=5432;Database=appdb;Username=appuser;Password=apppass"
    depends_on:
      - postgres
    networks:
      - app-network

volumes:
  postgres_data:

networks:
  app-network:
    driver: bridge

修复版配置（更换未被占用的端口） #

version: '3.8'
services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: apppass
      POSTGRES_DB: appdb
    ports:
      - "5041:5432"  # 更换为未被系统占用的端口
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - app-network

  csharp-service:
    build: .
    environment:
      ConnectionStrings__DefaultConnection: "Host=postgres;Port=5432;Database=appdb;Username=appuser;Password=apppass"
    depends_on:
      - postgres
    networks:
      - app-network

volumes:
  postgres_data:

networks:
  app-network:
    driver: bridge

关键结论 #

• Docker Compose的内部网络中，服务通过容器名和容器内部端口（如postgres:5432）通信，不受宿主机端口映射影响，因此C#服务能正常访问数据库
• 本地工具（如DBeaver）依赖宿主机端口映射访问容器，若宿主机端口被系统或其他后台进程占用，会直接导致连接超时
• 解决这类问题的核心：更换为未被占用的宿主机端口，建议避开1-1024的系统保留端口及常用应用端口

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