Windows Docker PostgreSQL 端口绑定失败问题记录

Windows Docker PostgreSQL 端口绑定失败问题记录

---

问题现象

• 客户端连接 localhost:55432 报错：Connection refused (10061)

• 执行 netstat -ano | findstr :55432 无任何输出，显示端口未被占用

• Docker 容器状态为 Running，PostgreSQL 日志显示 database system is ready to accept connections，说明容器内服务正常

• 容器配置显示端口映射为 HostPort: 55432 → ContainerPort: 5432，配置看似正确

根本原因

1. Windows 系统端口排除范围（Hyper-V/WSL 保留端口）

   Windows 会为虚拟化网络预留一段端口，即使没有进程占用，也会在内核层面标记为 "不可用"，普通进程（包括 Docker）无法绑定。55432 端口很可能落在这个范围内。

2. Docker 网络模式冲突

   自定义网络（如 infra_default）在 Windows 上容易出现网络转发异常，导致端口映射失效。

---

解决方案（按优先级）

方案 1：重置 WinNAT（无需重启电脑，最有效）

作用：重置 Windows NAT 服务，释放被系统 "隐性锁定" 的端口。

操作步骤：

1. 以 管理员身份 打开 PowerShell。

2. 执行以下命令：

   net stop winnat
   net start winnat

3. 重启 Docker Desktop。

4. 尝试重新连接数据库。

---

方案 2：更换宿主机端口（100% 可解决，推荐）

放弃 55432，更换一个不在系统保留范围内的端口，例如 55666。

方式 A：使用 docker-compose.yml

修改配置文件：

services:
  postgres:
    image: postgres:18
    container_name: aitsp-pg-dev
    environment:
      POSTGRES_PASSWORD: Admin@123456
    ports:
      - "55666:5432" # 宿主机端口:容器端口
    volumes:
      - infra_postgres-data:/var/lib/postgresql/18/data
    networks:
      - infra_default

volumes:
  infra_postgres-data:

networks:
  infra_default:

执行命令：

docker-compose down
docker-compose up -d

方式 B：直接使用 docker run 命令

docker run --name aitsp-pg-dev -e POSTGRES_PASSWORD=Admin@123456 -p 55666:5432 -d postgres:18

客户端连接地址改为：localhost:55666

---

方案 3：检查 Windows 保留端口范围

确认端口是否被系统保留：

netsh interface ipv4 show excludedportrange protocol=tcp

• 如果输出结果中包含 55432，说明端口被系统占用，只能通过方案 1 或方案 2 解决。

---

推荐操作顺序

1. 先执行 方案 1（重置 WinNAT），重启 Docker 后尝试连接。

2. 如果仍然失败，直接执行 **方案 2（更换端口）。

（注：文档部分内容可能由 AI 生成）