Docker端口配置疑问及服务访问故障排查求助

1. Docker端口概念梳理 #

• 容器内部端口：是容器中运行的服务实际监听的端口（比如Postgres默认5432，你的Node服务默认3000），这个端口由服务本身的配置决定，多个容器可以用相同的内部端口——因为它们处于各自独立的网络命名空间，互不干扰，不需要强制唯一。
• 主机端口：是宿主机上的端口，通过主机端口:容器内部端口的映射关系，将外部请求转发到容器内的服务。主机端口必须唯一，否则会出现端口冲突，导致容器启动失败。
• 容器间通信：在同一个Docker网络（比如你的backend网络）中，容器之间通过服务名（如main_db、test_db）直接访问对方的容器内部端口，完全不需要用到主机端口。

2. test服务访问失败的排查与解决 #

你遇到的Error: Failure when receiving data from the peer通常是因为test服务未正常启动，或启动后无法连接到test_db导致服务崩溃。常见原因和解决方法：

• 数据库未就绪就启动服务：depends_on仅保证容器启动顺序，不保证数据库完成初始化（Postgres第一次启动需要创建用户、数据库，需要一定时间）。
  解决：给test_db添加健康检查，让test服务等数据库就绪后再启动。修改docker-compose配置：

  test_db:
      image: postgres:16
      container_name: test_db
      ports:
          - 5433:5432
      volumes:
          - test_db_pgdata:/var/lib/postgresql/data
      networks:
          - backend
      healthcheck:
          test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
          interval: 5s
          timeout: 5s
          retries: 5
  test:
      ports:
          - 3003:3000
      depends_on:
          test_db:
              condition: service_healthy
      networks:
          - backend
  

• test服务的数据库配置错误：检查test服务的.env文件，DATABASE_URL必须指向test_db:5432，如果误写为main_db或主机端口5433，会导致连接失败、服务崩溃。

3. DATABASE_URL配置说明 #

你的main服务的DATABASE_URL配置DATABASE_URL=postgresql://user:123456@main_db:5432/mydb是正确的，原因：

• main_db是Docker Compose中数据库服务的名称，在backend网络中可以被main服务直接解析到对应容器的IP。
• 5432是Postgres容器内部监听的端口，容器间通信必须用这个端口——主机映射的5432端口仅用于外部工具（如本地pgAdmin）连接数据库。
• 同理，test服务的DATABASE_URL应配置为：DATABASE_URL=postgresql://user:123456@test_db:5432/mydb

额外说明：修改容器内部端口为何出问题？ #

你之前尝试给每个服务设置唯一容器内部端口却出现数据库问题，大概率是因为修改端口后，服务本身的配置未同步更新（比如Node服务仍监听3000，但你把容器内部端口改成了其他值，导致映射失效；或数据库端口被改，但连接字符串还是用5432）。实际上，容器内部端口不需要唯一，只要服务监听端口和映射的容器内部端口一致即可。

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