이 2026년 1월 Nextcloud/MariaDB 스레드는 컨테이너 네트워킹을 계층별로 진단해야 하는 이유를 보여 주는 가장 명확한 사례 중 하나입니다. 사용자는 Nextcloud와 MariaDB 앱을 별도로 설치했고, MariaDB는 정상적인 “연결 수락 준비” 상태에 도달했지만 Nextcloud는 초기 설정 중 실패했습니다. mariadb에 대한 getaddrinfo 실패두 앱을 모두 다시 설치하고 해당 폴더를 삭제해도 오류는 바뀌지 않았습니다.
커뮤니티가 MariaDB 컨테이너의 실제 Docker IP를 테스트했을 때 돌파구가 마련되었습니다. Nextcloud가 즉시 설치를 시작했습니다. 이는 데이터베이스 서버, 자격 증명, TCP 경로가 기본적으로 정상적으로 작동했지만 호스트 이름은 mariadb Nextcloud 컨테이너에서 확인되지 않았습니다.
사용자는 Nextcloud용 별도 MariaDB 데이터베이스를 원했습니다
초기 답변에서는 PostgreSQL이 포함된 올인원 Nextcloud 이미지나 phpMyAdmin을 통해 MariaDB 데이터베이스와 사용자를 수동으로 생성하는 방법 등의 대안이 논의되었습니다. 하지만 이러한 제안은 최종적인 문제가 아니었습니다. 사용자는 이미 MariaDB를 실행 중이었고 Nextcloud가 여기에 연결되도록 해야 했습니다.
MariaDB 로그를 통해 데이터베이스가 정상임을 확인할 수 있었습니다
커뮤니티에서는 데이터베이스가 이미 초기화된 후 MariaDB 비밀번호와 환경 변수를 반복해서 변경하지 말라고 올바르게 조언했습니다. 많은 데이터베이스 이미지는 데이터 디렉터리를 처음 생성할 때만 초기화 변수를 적용합니다.
데이터베이스 호스트는 Nextcloud 내부에서 연결 가능해야 합니다
Nextcloud의 초기 설정 중 데이터베이스 호스트 필드에는 다음과 같이 호스트 이름과 포트를 입력할 수 있습니다.
mariadb:3306이는 Docker 네트워킹이 이름 확인을 제공할 때만 작동합니다 mariadb Nextcloud 컨테이너에서 발생했습니다.
mariadb에 대한 getaddrinfo 실패는 DNS 스타일의 컨테이너 오류인가?
핵심 오류는 다음과 같았습니다.
php_network_getaddresses: mariadb에 대한 getaddrinfo 실패이 문제는 MariaDB가 사용자 이름과 비밀번호를 수락하거나 거부하기 전에 발생합니다. 이름을 IP 주소로 확인하지 못하면 데이터베이스 자격 증명은 아직 평가되지 않은 상태입니다.
두 앱이 모두 “브리지”로 표시되어도 이름 확인 문제는 해결되지 않았습니다
사용자는 두 애플리케이션 모두 ZimaOS에서 브리지 네트워킹으로 표시되었다고 확인했지만 mariadb 여전히 해결되지 않았습니다. 이는 중요한 Docker의 세부 사항입니다. Docker의 기본 브리지에 독립적으로 연결된 컨테이너는 사용자가 정의한 브리지 네트워크에 연결된 서비스와 동일한 서비스 이름 DNS 동작을 자동으로 제공받지 않습니다.
따라서 “둘 다 bridge라고 표시된다”는 사실만으로는 한 컨테이너가 다른 컨테이너의 이름을 확인할 수 있다는 충분한 증거가 되지 않습니다.
완전히 새로 설치해도 네트워크 동작은 해결되지 않았습니다
사용자는 Nextcloud와 MariaDB를 모두 제거하고 폴더를 삭제한 뒤 처음부터 다시 설치했습니다. 동일한 호스트 이름 오류가 다시 발생했습니다. 이 부정적 테스트는 문제가 단순히 오래된 MariaDB 데이터나 일시적인 잘못된 비밀번호 때문이 아니었음을 보여 주므로 유용합니다.
Nextcloud의 로컬 액세스 경고는 별개의 문제였습니다
사용자는 온라인에서 다음 설정을 활성화하라는 제안을 찾았습니다. allow_local_remote_servers초기 설정 중 이 설정을 적용하자 Nextcloud가 정상적으로 시작되지 않았습니다. 커뮤니티에서는 이 옵션이 다른 Nextcloud 보안 규칙을 다루는 설정이며 Docker 이름 확인 문제를 해결하지는 않는다고 설명했습니다.
커뮤니티는 직접적인 Docker 네트워크 테스트로 전환했습니다
응답자는 다음 사항을 확인해 달라고 요청했습니다.
- 두 컨테이너가 모두 실행 중인지
- Docker에서 실제로 보고한 네트워크 모드
- Nextcloud가 확인하거나 핑할 수 있는지
mariadb; - MariaDB 컨테이너의 현재 Docker IP입니다.
구성 스크린샷만으로는 동작을 설명하기 어려워진 뒤에 취해야 할 올바른 다음 단계는 Nextcloud가 실행되는 동일한 네트워크 네임스페이스에서 연결을 테스트하는 것입니다.
MariaDB 컨테이너 IP를 사용하자 Nextcloud가 설치되었습니다
결정적인 테스트는 다음과 같이 변경하는 것이었습니다. mariadb:3306 MariaDB 컨테이너의 Docker IP와 포트를 임시로 사용했습니다. 원문 작성자는 그러자 Nextcloud가 설치되었다고 답했습니다.
응답자는 결과를 명확하게 요약했습니다.
-
mariadb:3306실패했습니다; - 직접 지정한 Docker IP의 3306 포트로는 즉시 연결되었습니다.
이는 컨테이너 이름 확인 문제라는 강력한 증거입니다.
컨테이너 IP를 직접 사용하는 것은 유효한 진단용 우회 방법입니다
IP를 사용하면 데이터베이스에 연결할 수 있다는 것이 입증되어 설치를 진행할 수 있습니다. 원래 사례에서는 효과적인 우회 방법이었습니다.
하지만 컨테이너가 다시 생성되거나, 삭제되거나, 다른 네트워크에 연결되면 자동으로 할당된 컨테이너 IP가 변경될 수 있습니다. 영구적으로 의존하는 설정은 172.17.x.x 나중에 Nextcloud나 MariaDB의 구성 변경 없이도 문제가 발생할 수 있습니다.
사용자 정의 Docker 네트워크가 장기적으로 더 나은 설계입니다
더 견고한 아키텍처는 Nextcloud와 MariaDB를 동일한 사용자 정의 Docker 네트워크에 연결하고 데이터베이스 호스트에 안정적인 서비스 이름 또는 컨테이너 이름을 사용하는 것입니다. Docker는 이러한 목적을 위해 사용자 정의 네트워크에서 임베디드 DNS를 제공합니다.
현재 ZimaOS의 기본 YAML 편집 기능을 사용하면 이러한 네트워크 정의를 소스 스레드가 작성되었을 때보다 쉽게 설정할 수 있습니다. 공유 Nextcloud 및 MariaDB 네트워크를 구축할 때 현재 ZimaOS Compose 구성 모델을 사용하세요.
MariaDB 데이터는 신중하게 보존하세요
MariaDB에 이미 작동하는 Nextcloud 데이터베이스가 있다면 Docker 네트워킹을 변경하기 위해 영구 데이터 디렉터리를 삭제하지 마세요. 데이터베이스 콘텐츠를 다시 만들지 않고도 네트워크 멤버십을 변경할 수 있습니다.
마이그레이션하기 전에 데이터베이스를 백업하고 현재 사용자, 데이터베이스 이름, 볼륨 매핑을 기록하세요.
Docker DNS 문제를 해결하기 위해 Nextcloud 보안 제어를 비활성화하지 마세요
신뢰할 수 있는 도메인, 로컬 원격 서버 액세스, 리버스 프록시 구성과 같은 설정은 HTTP/애플리케이션 계층에서 Nextcloud를 보호합니다. 해당하는 Nextcloud 오류가 발생할 때만 변경해야 합니다.
A getaddrinfo 데이터베이스 호스트 이름에 대한 오류는 Docker 네트워크 계층에서 발생합니다.
더 나은 진단 트리
- MariaDB가 실행 중이며 3306 포트에서 수신 대기 중인지 확인하세요.
- 사용하려는 데이터베이스가 존재하고 자격 증명을 알고 있는지 확인하세요.
- Nextcloud가 데이터베이스 호스트 이름을 확인할 수 있는지 테스트하세요.
- 호스트 이름 확인에 실패하면 데이터베이스 컨테이너의 IP를 테스트하세요.
- IP로 작동한다면 데이터베이스 비밀번호를 변경하지 말고 Docker 네트워크를 수정하세요.
- 지속적으로 사용할 수 있는 호스트 이름을 위해 두 컨테이너를 안정적인 사용자 정의 네트워크로 이동하세요.
Nextcloud 및 MariaDB FAQ
MariaDB 자체에 문제가 있었나요?
아니요. 로그에는 연결을 수락할 준비가 되었다고 표시되었습니다.
getaddrinfo for mariadb failed는 무슨 의미인가요?
Nextcloud는 인증 단계에 도달하기도 전에 데이터베이스 호스트 이름을 확인하지 못했습니다.
진단을 확정한 근거는 무엇인가요?
MariaDB 컨테이너의 직접 Docker IP를 사용하자 Nextcloud 설치가 시작되었습니다.
컨테이너의 직접 IP를 영구적인 데이터베이스 호스트로 사용해야 하나요?
작동할 수는 있지만, 안정적인 이름 확인이 가능한 공유 사용자 정의 Docker 네트워크가 더 견고합니다.
두 앱을 모두 재설치하니 문제가 해결되었나요?
아니요. 사용자는 새로 깔끔하게 재설치했지만 동일한 호스트 이름 확인 오류가 다시 발생했습니다.
