In-depth Analysis and Solution for Docker Container Connection Refused Issues

Problem Background and Phenomenon Analysis

Connection refused is a frequent technical challenge during Docker container deployment. Many developers encounter this scenario when first using Docker: services start normally inside the container, logs indicate the service is listening on the specified port, but external network access results in connection refused errors. This phenomenon typically stems from misunderstandings about Docker's network model and port mapping mechanisms.

Detailed Explanation of Docker Port Mapping Mechanism

Docker's network isolation特性决定了容器内部网络环境与宿主机是分离的。The EXPOSE instruction serves only documentation purposes, declaring the ports the container listens on during runtime, but it does not automatically create port mappings. To enable external access, explicit port mapping between the host and container must be established using the --publish or -p parameter.

The basic syntax for port mapping is: docker run -p host_port:container_port image_name. Here, host_port specifies the port on the host machine, while container_port corresponds to the port inside the container. This mapping relationship allows external requests to be forwarded from the host's IP address and port to the service inside the container.

Practical Case Analysis

Consider a typical Rails application deployment scenario. The Dockerfile configures EXPOSE 8080 and the startup command specifies the service binding to 0.0.0.0:8080. After container startup, the service listens normally, but external access fails. The root cause lies in the missing port publishing step.

The correct startup command should be: docker run -it -p 8080:8080 demo. This command establishes a mapping channel from host port 8080 to container port 8080, enabling access requests via http://192.168.99.100:8080 to be correctly routed to the service inside the container.

Port Publishing Options Comparison

Docker provides two port publishing methods: -P (uppercase) and -p (lowercase). The -P option automatically maps all exposed container ports to high random ports on the host, suitable for quick testing scenarios. The -p option allows precise specification of port mapping relationships, making it more appropriate for production environment deployments.

When using the -P option, the specific port mapping situation must be checked using the docker inspect container_name command. In the output information's Ports field, the correspondence between host ports and container ports can be found.

Environmental Differences and Access Methods

Access methods to Docker container services vary across different operating system environments. In Windows 10 Home systems using Docker Toolkit, access requires obtaining the virtual machine's IP address via docker-machine ip default. In Windows 10 Pro or Linux systems, where Docker runs directly on the host, localhost or 127.0.0.1 can be used directly for access.

This difference stems from varying Docker runtime architectures. In virtual machine environments, Docker runs within an independent Linux virtual machine, thus requiring access through the virtual machine's network interface. In native Docker environments, containers share the network namespace with the host, supporting local loopback address access.

Best Practice Recommendations

To ensure accessibility of Docker container services, it is recommended to follow these best practices: always use the -p parameter to explicitly specify port mappings; use the EXPOSE instruction in Dockerfile to document service ports; bind services to 0.0.0.0 rather than 127.0.0.1 in service configuration; and choose appropriate access methods based on the runtime environment.

Additionally, comprehensive network connectivity testing before deployment is advised, including container internal service status checks, port mapping verification, and external access testing. These steps help identify and resolve network configuration issues promptly.