WSL2环境下如何从VS Code开发容器及Python连接Docker PostgreSQL？

核心原因 #

WSL2环境中，Docker Desktop的容器运行在专属的docker-desktop WSL发行版网络里，Windows宿主机的127.0.0.1和WSL2子系统的localhost属于不同网络栈，直接用Windows侧的localhost访问容器端口会失效。

针对不同场景的解决方案 #

1. pgAdmin无法用127.0.0.1/localhost连接PostgreSQL #

• 用awesome-compose启动的pgAdmin和PostgreSQL处于同一个Docker自定义网络，Docker内部DNS会解析容器名postgresdb到容器内网IP，所以只能用容器名直接连接。
• 要通过IP连接，需用WSL2的实际IP：
  • 打开WSL终端，执行hostname -I获取WSL2的IP（通常是172.x.x.x网段）。
  • 在pgAdmin的连接配置中，把主机地址换成这个WSL2 IP，端口保持5432即可。

2. Windows宿主机Python代码无法连接PostgreSQL #

• 替换代码中的127.0.0.1为WSL2的实际IP，示例代码：

  import psycopg2
  connection = psycopg2.connect(
      database="postgres",
      user='postgres',
      password='postgres',
      host='172.17.0.1',  # 替换为你的WSL2 IP
      port=5432
  )
  

• 同时确保Docker Desktop已开启WSL集成：打开Settings > Resources > WSL Integration，勾选默认WSL发行版的集成开关。

3. VS Code开发容器中连接PostgreSQL #

• 如果开发容器和PostgreSQL在同一个Docker网络（比如同属一个Compose项目），直接用容器名postgresdb作为host连接：

  import psycopg2
  connection = psycopg2.connect(
      database="postgres",
      user='postgres',
      password='postgres',
      host='postgresdb',
      port=5432
  )
  

• 不在同一网络的话，把开发容器加入PostgreSQL所在网络：
  1. 执行docker network ls找到目标网络（比如postgres-pgadmin_default）。
  2. 执行docker network connect postgres-pgadmin_default <你的开发容器ID>。

4. 单独启动PostgreSQL容器时的连接问题 #

• 映射端口5433:5432后，Windows侧需用WSL2 IP+5433连接，而非127.0.0.1:5433。
• 额外检查PostgreSQL的监听配置：
  1. 进入容器：docker exec -it <postgres容器ID> bash。
  2. 修改/var/lib/postgresql/data/postgresql.conf，确保listen_addresses = '*'。
  3. 重启容器：docker restart <postgres容器ID>。

内容的提问来源于stack exchange，提问作者Peter K.