시놀로지 Docker 컨테이너끼리 통신이 안 될 때 Bridge Network 확인 방법

시놀로지 NAS에서 Docker를 사용하다 보면 각각의 컨테이너는 정상적으로 실행되고 있는데 컨테이너끼리 통신이 되지 않는 문제가 발생할 수 있습니다.

예를 들어 웹 애플리케이션 컨테이너와 데이터베이스 컨테이너를 함께 운영하는 경우입니다.

구조는 일반적으로 다음과 같습니다.

웹 애플리케이션

↓

MariaDB 또는 PostgreSQL

그런데 웹 애플리케이션에서 데이터베이스에 연결하려고 하면 접속 오류가 발생합니다.

컨테이너 자체는 모두 정상적으로 실행되고 있고 NAS에서도 문제가 없어 보이기 때문에 처음에는 원인을 찾기가 쉽지 않습니다.

이런 경우 가장 먼저 확인해야 할 부분 중 하나가 Docker 네트워크 구성입니다.

특히 두 컨테이너가 서로 다른 네트워크에 연결되어 있거나, 컨테이너에서 접근할 주소를 잘못 지정한 경우 통신이 되지 않을 수 있습니다.

시놀로지 Container Manager에서 Docker 컨테이너끼리 통신이 되지 않는다면 Bridge Network가 어떻게 구성되어 있는지 확인하는 것부터 시작하는 것이 좋습니다.

Docker 컨테이너는 왜 서로 통신해야 할까?

Docker로 여러 서비스를 운영하면 하나의 컨테이너만 사용하는 경우보다 여러 컨테이너가 서로 연결되는 경우가 많습니다.

예를 들어 다음과 같은 구조입니다.

WordPress

↓

MariaDB

또는

Jellyfin

↓

DB 또는 기타 서비스

또는

웹 애플리케이션

↓

Redis

이런 구조에서는 각 컨테이너가 별도의 프로세스로 실행되더라도 필요한 경우 서로 네트워크 통신을 해야 합니다.

문제는 컨테이너가 실행 중이라고 해서 모든 컨테이너가 자동으로 서로 통신할 수 있는 것은 아니라는 점입니다.

Docker에서는 어떤 네트워크에 연결되어 있는지가 중요합니다.

Bridge Network란?

Docker에서 Bridge는 컨테이너가 사용할 수 있는 가상 네트워크를 제공하는 방식입니다.

컨테이너는 이 네트워크를 통해 다른 컨테이너나 외부 네트워크와 통신할 수 있습니다.

쉽게 표현하면 다음과 같습니다.

시놀로지 NAS

↓

Docker Network

↓

컨테이너 A

컨테이너 B

두 컨테이너가 같은 Docker 네트워크에 연결되어 있다면 서로 통신할 수 있는 환경을 만들기 쉽습니다.

반대로 컨테이너가 서로 다른 네트워크에 연결되어 있다면 별도의 네트워크 구성이 필요할 수 있습니다.

컨테이너가 실행 중인데 통신이 안 되는 이유

가장 먼저 이해해야 할 부분은 컨테이너 실행 상태와 네트워크 연결 상태는 별개의 문제라는 것입니다.

Container Manager에서 실행 중으로 표시되더라도 해당 컨테이너가 원하는 네트워크에 연결되어 있지 않을 수 있습니다.

예를 들어 다음과 같은 상황을 생각해 볼 수 있습니다.

웹 컨테이너 → network1

DB 컨테이너 → network2

두 컨테이너가 모두 정상적으로 실행되고 있지만 서로 다른 네트워크에 있기 때문에 원하는 방식으로 통신하지 못할 수 있습니다.

따라서 컨테이너 간 통신 문제가 발생하면 두 컨테이너가 어떤 네트워크에 연결되어 있는지 먼저 확인해야 합니다.

가장 먼저 확인할 것은 네트워크 이름

시놀로지 Container Manager에서 컨테이너의 네트워크 설정을 확인합니다.

컨테이너마다 연결된 네트워크가 표시되는데, 통신해야 하는 컨테이너가 동일한 사용자 정의 Docker 네트워크에 연결되어 있는지 확인하는 것이 좋습니다.

예를 들어

web

→ my_network

database

→ my_network

처럼 구성되어 있다면 같은 네트워크를 통해 통신하도록 구성할 수 있습니다.

반대로

web

→ network_a

database

→ network_b

라면 네트워크 구성을 다시 확인해야 합니다.

기본 Bridge와 사용자 정의 Bridge는 차이가 있다

여기서 한 가지 주의할 점이 있습니다.

Docker에는 기본적으로 Bridge 네트워크가 존재하지만, 컨테이너 간 통신을 구성할 때는 사용자 정의 Bridge 네트워크를 사용하는 방식이 더 관리하기 편리한 경우가 많습니다.

사용자 정의 Bridge 네트워크를 사용하면 컨테이너 간 이름 기반 통신을 구성하기가 편리합니다.

예를 들어

web

database

두 컨테이너를 같은 사용자 정의 네트워크에 연결할 수 있습니다.

이 경우 애플리케이션에서 데이터베이스 서버를 지정할 때 상황에 따라 IP 주소 대신 컨테이너 이름이나 서비스 이름을 사용하는 방식을 고려할 수 있습니다.

이것이 컨테이너 환경에서 중요한 이유입니다.

데이터베이스 주소를 NAS IP로 입력하면 안 되는 경우

컨테이너 간 통신 문제에서 흔히 발생하는 실수 중 하나가 데이터베이스 주소를 무조건 NAS의 IP 주소로 입력하는 것입니다.

예를 들어 NAS의 IP가 192.168.0.10이라고 해서 데이터베이스 컨테이너에 무조건 192.168.0.10을 입력하는 것이 올바른 방법은 아닙니다.

컨테이너가 같은 Docker 네트워크에 연결되어 있다면 Docker 네트워크에서 제공하는 컨테이너 간 통신 구조를 사용하는 것이 더 적절한 경우가 많습니다.

예를 들어 데이터베이스 컨테이너 이름이 mariadb라면 애플리케이션에서 mariadb를 데이터베이스 호스트로 지정하는 구성을 사용할 수 있습니다.

단, 실제 설정 방법은 사용하는 애플리케이션과 Compose 구성에 따라 달라질 수 있습니다.

컨테이너의 IP 주소를 직접 사용하면 문제가 생길 수 있다

Docker 컨테이너에는 자체적인 IP 주소가 할당될 수 있습니다.

하지만 컨테이너 IP를 직접 설정에 입력해 사용하는 방식은 주의해야 합니다.

컨테이너를 삭제하고 다시 생성하거나 네트워크를 재구성하면 IP가 변경될 수 있기 때문입니다.

예를 들어 처음에는 172.18.0.2였던 데이터베이스 컨테이너가 다시 생성된 후 172.18.0.3이 될 수도 있습니다.

그렇게 되면 애플리케이션에 기존 IP를 입력해 둔 경우 데이터베이스 연결이 끊어질 수 있습니다.

따라서 컨테이너 간 통신에서는 고정 IP를 직접 입력하기보다 Docker의 이름 기반 통신을 활용하는 방법을 먼저 검토하는 것이 좋습니다.

포트 매핑과 컨테이너 간 통신은 다르다

이 부분은 특히 중요합니다.

Docker를 처음 사용할 때는 컨테이너 간 통신을 위해 반드시 포트 매핑이 필요하다고 생각하기 쉽습니다.

하지만 컨테이너끼리 같은 Docker 네트워크에서 직접 통신하는 경우에는 외부 접근을 위한 포트 매핑과는 개념이 다릅니다.

예를 들어 데이터베이스 컨테이너가 내부적으로 3306 포트를 사용한다고 가정해 보겠습니다.

웹 컨테이너가 같은 Docker 네트워크에 있다면 데이터베이스의 3306 포트를 컨테이너 간 통신에 사용할 수 있습니다.

이때 NAS의 3306 포트를 외부에 공개하기 위해 별도로 포트 매핑할 필요가 없는 구성도 가능합니다.

즉, 컨테이너 간 통신과 외부에서 NAS를 통해 컨테이너에 접속은 구분해서 생각해야 합니다.

데이터베이스 포트를 NAS에 공개할 필요가 없는 경우

예를 들어 다음과 같은 구조가 있다고 하겠습니다.

WordPress 컨테이너

↓

MariaDB 컨테이너

두 컨테이너가 같은 Docker 네트워크에서 통신한다면 MariaDB를 인터넷에 직접 공개할 이유가 없는 경우가 많습니다.

오히려 데이터베이스 포트를 외부에 공개하지 않고 Docker 네트워크 내부에서만 통신하도록 구성하는 것이 보안 측면에서 더 적절할 수 있습니다.

따라서 컨테이너 간 통신 문제를 해결하기 위해 무조건 공유기 포트포워딩이나 NAS 포트 매핑부터 추가하는 것은 좋은 방법이 아닙니다.

Container Manager에서 네트워크 연결 확인

시놀로지 Container Manager에서 문제가 발생한 컨테이너를 선택하고 네트워크 관련 설정을 확인합니다.

확인해야 할 핵심 내용은 다음과 같습니다.

어떤 네트워크에 연결되어 있는가

통신 대상 컨테이너와 같은 네트워크인가

컨테이너의 네트워크 모드는 무엇인가

네트워크가 정상적으로 생성되어 있는가

특히 Compose 프로젝트로 여러 컨테이너를 설치했다면 프로젝트의 네트워크 구성을 함께 확인해야 합니다.

Docker Compose에서는 networks 설정을 확인한다

Docker Compose를 사용하는 경우 네트워크를 명시적으로 지정할 수 있습니다.

예를 들어 다음과 같은 구조를 사용할 수 있습니다.

services:
  web:
    image: example/web
    networks:
      - app_network

  database:
    image: mariadb
    networks:
      - app_network

networks:
  app_network:

이렇게 구성하면 web과 database가 같은 app_network에 연결됩니다.

여기서 중요한 부분은 두 서비스가 동일한 네트워크에 연결되어 있다는 것입니다.

Compose 파일에서 네트워크 이름이나 들여쓰기가 잘못되면 컨테이너는 실행되더라도 원하는 네트워크 구성이 만들어지지 않을 수 있습니다.

Compose에서 네트워크 이름을 잘못 지정하는 경우

Compose 파일을 수정하다 보면 네트워크 이름을 잘못 입력하는 경우도 있습니다.

예를 들어 한 컨테이너에는 app_network를 지정하고 다른 컨테이너에는 app-net을 지정했다면 서로 다른 네트워크가 될 수 있습니다.

따라서 Compose 파일에서 networks 이름과 각 서비스의 networks 항목을 함께 확인해야 합니다.

네트워크 모드가 Host라면 다르게 접근해야 한다

모든 컨테이너가 Bridge 네트워크를 사용하는 것은 아닙니다.

일부 컨테이너는 Host 네트워크를 사용하도록 설정할 수 있습니다.

이 경우 컨테이너가 NAS의 네트워크 환경을 직접 사용하기 때문에 일반적인 Bridge 네트워크의 컨테이너 간 통신 방식과 차이가 생깁니다.

따라서 통신 문제가 발생했다면 두 컨테이너의 네트워크 모드가 무엇인지 먼저 확인해야 합니다.

Bridge

Host

None

등 네트워크 모드에 따라 접근 방식이 달라질 수 있습니다.

이때 Bridge와 Host 네트워크 모드의 차이를 이해하고 있어야 현재 구성에서 어떤 방식으로 통신해야 하는지 판단할 수 있습니다.

컨테이너 이름으로 접속할 수 없는 이유

같은 네트워크에 연결했는데도 컨테이너 이름으로 접속되지 않는다면 기본 Bridge와 사용자 정의 Bridge를 구분해서 확인할 필요가 있습니다.

Docker의 사용자 정의 Bridge 네트워크에서는 컨테이너 간 이름 기반 통신을 활용하기 편리합니다.

반면 기본 네트워크 구성에서는 동일한 방식으로 동작하지 않을 수 있습니다.

따라서 컨테이너 이름을 이용한 통신이 필요한 환경이라면 사용자 정의 Bridge 네트워크를 구성하는 방법을 고려하는 것이 좋습니다.

DNS 문제일 수도 있다

컨테이너 이름으로 접근하는 구조에서 통신이 되지 않는다면 Docker 네트워크의 이름 해석 문제도 확인해야 합니다.

예를 들어 database라는 컨테이너 이름으로 접근하도록 설정했는데 이름을 찾지 못한다면 해당 컨테이너가 같은 네트워크에 연결되어 있는지 먼저 확인합니다.

네트워크가 서로 다르면 이름 기반 통신이 원하는 방식으로 이루어지지 않을 수 있습니다.

방화벽 때문에 컨테이너 통신이 막힐까?

시놀로지 NAS의 방화벽 설정도 전체 네트워크 문제를 진단할 때 확인할 필요가 있습니다.

하지만 컨테이너끼리 같은 Docker 네트워크에서 통신하는 문제라면 처음부터 공유기나 외부 인터넷 문제로 접근하기보다는 Docker 네트워크 구성을 먼저 확인하는 것이 효율적입니다.

외부 접속은 되는데 컨테이너끼리 통신하지 않는다면 특히 Docker 네트워크와 애플리케이션의 연결 설정을 우선 확인해야 합니다.

컨테이너 로그도 함께 확인한다

네트워크 구성이 정상적으로 보이는데도 애플리케이션이 연결되지 않는다면 컨테이너 로그를 확인해야 합니다.

예를 들어 데이터베이스를 사용하는 애플리케이션이라면 다음과 같은 오류가 나타날 수 있습니다.

Connection refused

Connection timed out

Name or service not known

Host not found

이 오류들은 각각 의미가 다릅니다.

Name or service not known과 같은 오류라면 컨테이너 이름이나 DNS 관련 문제를 의심할 수 있습니다.

Connection refused라면 대상 컨테이너는 찾았지만 해당 포트에서 서비스가 실행되고 있지 않은 상황일 수 있습니다.

따라서 단순히 “네트워크가 안 된다”고 생각하기보다 오류 메시지를 통해 문제의 위치를 좁히는 것이 중요합니다.

데이터베이스 컨테이너가 실제로 실행 중인지 확인한다

웹 컨테이너에서 데이터베이스 연결이 되지 않는다면 네트워크부터 수정하기 전에 데이터베이스 컨테이너 자체를 확인해야 합니다.

Container Manager에서 데이터베이스 컨테이너가 실행 중인지 확인합니다.

컨테이너가 반복적으로 재시작하고 있다면 네트워크 문제가 아니라 데이터베이스 설정이나 볼륨, 권한, 환경변수 문제일 수 있습니다.

즉, 컨테이너 간 통신 문제에서는 양쪽 컨테이너가 모두 정상적으로 서비스를 제공하고 있는지도 확인해야 합니다.

컨테이너 내부에서 네트워크를 확인하는 방법

보다 정확하게 확인하려면 컨테이너 내부에서 대상 컨테이너로 통신이 가능한지 테스트할 수 있습니다.

예를 들어 애플리케이션 컨테이너에서 데이터베이스 컨테이너 이름을 대상으로 네트워크 연결을 확인합니다.

다만 컨테이너 이미지에 ping, curl, nc 같은 도구가 포함되어 있지 않을 수도 있습니다.

따라서 명령어가 실행되지 않는다고 해서 곧바로 네트워크 오류라고 판단해서는 안 됩니다.

가능한 도구를 이용해 DNS 이름 해석과 실제 서비스 포트 연결을 각각 확인하는 것이 좋습니다.

네트워크를 삭제하고 다시 만들기 전에 확인해야 할 것

인터넷에서 Docker 네트워크 문제가 발생하면 “네트워크를 삭제하고 다시 만들라”는 해결 방법을 쉽게 찾을 수 있습니다.

하지만 시놀로지 NAS에서 운영 중인 서비스라면 무작정 네트워크를 삭제하는 것은 주의해야 합니다.

여러 컨테이너가 해당 네트워크를 사용하고 있을 수 있기 때문입니다.

따라서 먼저

어떤 컨테이너가 연결되어 있는지

Compose에서 해당 네트워크를 사용하는지

볼륨과 데이터에는 영향이 없는지

를 확인해야 합니다.

네트워크 재생성은 원인을 확인한 이후 마지막 단계에서 고려하는 것이 좋습니다.

시놀로지 Docker 컨테이너 통신 문제 확인 순서

컨테이너끼리 통신이 되지 않는다면 다음 순서로 확인하면 됩니다.

1. 두 컨테이너가 모두 실행 중인지 확인

2. 두 컨테이너의 네트워크 모드 확인

3. 동일한 Docker 네트워크에 연결되어 있는지 확인

4. 사용자 정의 Bridge 네트워크인지 확인

5. 애플리케이션에서 사용하는 대상 주소 확인

6. 컨테이너 IP를 직접 입력하고 있지 않은지 확인

7. 데이터베이스 등 대상 서비스가 실제 포트를 열고 있는지 확인

8. 컨테이너 로그에서 연결 오류 확인

9. Compose의 networks 설정 확인

10. 필요한 경우 컨테이너 내부에서 이름 해석과 포트 연결 테스트

이 순서로 확인하면 무작정 포트포워딩이나 공유기 설정을 변경하는 것보다 원인을 훨씬 쉽게 좁힐 수 있습니다.

마무리

시놀로지 NAS에서 Docker 컨테이너끼리 통신이 되지 않을 때는 포트포워딩부터 확인하는 것보다 Docker 네트워크 구조를 먼저 확인하는 것이 중요합니다.

특히 서로 통신해야 하는 컨테이너가 동일한 Docker 네트워크에 연결되어 있는지 확인해야 합니다.

또한 컨테이너 간 통신에서는 외부 접속과 달리 NAS의 IP 주소나 공유기의 포트포워딩이 반드시 필요한 것은 아닙니다.

같은 사용자 정의 Bridge 네트워크를 사용한다면 컨테이너 이름을 이용해 서로 통신하도록 구성할 수 있는 경우가 많습니다.

따라서 문제가 발생했을 때는

컨테이너 실행 상태

↓

네트워크 모드

↓

Bridge Network 연결 상태

↓

컨테이너 이름 및 포트

↓

애플리케이션 로그

순서로 확인하는 것이 좋습니다.

특히 Docker Compose를 사용하는 시놀로지 환경에서는 networks 설정을 제대로 구성하는 것이 중요합니다.

결국 컨테이너 간 통신 문제의 핵심은 “컨테이너가 실행되고 있는가?”가 아니라 “통신해야 하는 컨테이너가 같은 네트워크에서 올바른 주소와 포트로 연결되고 있는가?”를 확인하는 것입니다.

이 부분만 정확하게 이해해도 시놀로지 Container Manager에서 발생하는 데이터베이스 연결 실패, 컨테이너 간 통신 오류, Connection refused, Name or service not known 같은 문제의 원인을 훨씬 쉽게 찾아낼 수 있습니다.