이 페이지에서는 일반적인 연결 문제와 가능한 해결 방법을 간략하게 설명합니다.
Atlas cluster 에 연결하는 방법에 대해 자세히 학습하려면 Atlas 시작하기 튜토리얼을 참조하세요.
참고
지원을 원하는 기업 고객인 경우 신청서를 제출하세요. 커뮤니티 지원은 MongoDB Community 리소스를 참조하세요.
지능형 어시스턴트 를 사용하여 연결 오류 디버깅을 지원할 수 있습니다.
클러스터 Connect 버튼이 비활성화되었습니다.
클러스터가 프로비저닝 상태인 경우 클러스터의 Connect 버튼이 비활성화될 수 있습니다. 클러스터는 처음 배포될 때 프로비저닝해야 합니다. 클러스터를 확장 또는 축소할 때도 프로비저닝을 해야 합니다.
Atlas 클러스터 프로비저닝이 완료되면 Connect 버튼이 활성화됩니다.
무료 클러스터의 경우 프로비저닝 15 초도 걸리지 않습니다.
Flex 및 전용 클러스터의 경우 프로비저닝 최대 10 분이 걸릴 수 있습니다.
IP 액세스 목록에 없는 IP 주소 연결
Atlas 클러스터에 연결하기 전에 호스트의 IP 주소를 클러스터 프로젝트의 IP 액세스 목록에 추가했는지 확인하세요. Atlas는 IP 액세스 목록에 있는 IP 주소 및 CIDR 주소 범위의 클라이언트 연결만 허용합니다.
클러스터에 대한 인증에 실패했습니다.
Atlas에 연결하려면 MongoDB database 사용자로 인증해야 합니다. 클러스터에 대한 데이터베이스 사용자를 생성하려면 데이터베이스 사용자 구성을 참조하세요.
가능한 솔루션
사용자를 만들었는데 인증하는 데 문제가 있는 경우 다음을 시도해 보세요:
데이터베이스 사용자에 대해 올바른 사용자 이름과 비밀번호를 사용하고 있으며 올바른 클러스터에 연결하고 있는지 확인하세요.
연결 문자열에 올바른
authSource데이터베이스를 지정하고 있는지 확인하세요.비밀번호에 특수 문자가 포함된 경우 연결 문자열 비밀번호의 특수 문자를 참조하세요.
클러스터에 대해 열려 있는 연결이 너무 많음
Atlas는 클러스터에 대한 동시 수신 연결에 대한 제한을 설정합니다. 클러스터의 경우 이는 클러스터 계층을 기반으로 합니다. 이 제한에 도달했을 때 연결을 시도하면 MongoDB는 connection refused because too many open connections 라는 오류를 표시합니다.
클러스터 계층과 최대 동시 연결 수에 대한 자세한 비교는 연결 제한 및 클러스터 계층을 참조하세요.
가능한 솔루션
현재 사용하지 않는 클러스터에 대한 열려 있는 연결을 모두 닫습니다.
더 많은 동시 연결을 지원하려면 클러스터를 더 상위 계층으로 스케일링합니다.
애플리케이션을 다시 시작합니다.
앞으로 이 문제를 방지하려면
maxPoolSize연결 문자열 옵션을 사용하여 연결 풀의 연결 수를 제한하는 것이 좋습니다.
이 문제를 해결하는 방법을 알아보려면 연결 문제 해결 페이지를 참조하세요.
연결 수가 급증하는 동안 샤딩된 클러스터의 성능 저하
Atlas는 비공개 엔드포인트 서비스의 로드 밸런서를 사용하여 샤딩된 클러스터에 대해 최적화된 SRV 연결 문자열을 생성할 수 있습니다. 최적화된 연결 문자열을 사용하면 Atlas는 애플리케이션과 샤딩된 클러스터 간의 mongos 당 연결 수를 제한합니다. mongos 당 제한된 연결은 연결 수가 급증하는 동안 성능을 향상시킵니다.
비공개 엔드포인트를 사용하는 샤딩된 클러스터에 대해 최적화된 연결 문자열에 대해 자세히 학습 보려면 비공개 엔드포인트 사용하여 샤딩된 클러스터에 대한 연결 성능을 최적화하려면 어떻게 해야 하나요?를 참조하세요.
방화벽 뒤에서 연결을 시도하는 경우
Atlas UI에 연결
Atlas CDN을 사용하여 콘텐츠를 빠르게 제공 . 조직 방화벽 사용하는 경우 방화벽의 허용 목록에 다음 Atlas CDN 호스트를 추가하여 Atlas UI 액세스하는 데 문제가 발생하지 않도록 하세요.
https://assets.mongodb-cdn.com/https://downloads.mongodb.com/( 데이터 탐색기 기능 에 필요)
클러스터에 연결
Atlas 클러스터는 포트 27017에서 작동합니다. 클러스터에 연결하려면 이 포트에 연결할 수 있어야 합니다. 또한, 다음에 대해 적절한 포트가 열려 있는지 확인합니다.
샤딩된 클러스터의 경우 포트 27016에 대한 액세스 권한을 부여합니다.
BI Connector의 경우 포트 27015에 대한 액세스 권한을 허용하세요.
타사 Outgoing port tester를 사용하여 포트에 도달할 수 있는지 확인할 수 있습니다.
예시
포트 27017에 연결할 기능 확인하려면 http://portquiz.net:27017를 방문하세요.
해당 포트에 액세스할 수 없는 경우 시스템 방화벽 설정을 확인하고 해당 설정이 대상 포트에 대한 액세스를 차단하고 있지 않은지 확인하세요.
클러스터 가용성
mongodb+srv:// 연결 문자열을 사용 중이고 드라이버 또는 셸에서 Atlas 클러스터의 DNS 호스트를 찾을 수 없는 경우 클러스터가 일시 중지되거나 삭제될 수 있습니다. 클러스터가 존재하는지 확인합니다. 일시 중지된 클러스터인 경우 필요시 클러스터를 다시 시작할 수 있습니다.
참고
Atlas 연결이 없는 30 일 후에 유휴 상태인 무료 클러스터(이전의 M0)를 자동으로 일시 중지합니다.
MongoDB Compass 문제 해결
MongoDB Compass를 사용하여 cluster에 연결했는데 문제가 발생하는 경우 다음을 참조하세요:
MongoDB Compass 문서의 Compass 연결 오류 섹션.
자체 관리형 X.509 인증서 또는 Atlas에서 관리하는 자동 생성 X.509 인증서를 사용하여 MongoDB 데이터베이스에 인증하는 경우 MongoDB Compass에 연결할 때 다음을 수행해야 합니다.
MongoDB Compass에서 Fill in connection fields individually를 선택합니다.
Authentication 드롭다운 메뉴에서
X.509를 선택합니다.More Options0}을 선택합니다.
SSL 드롭다운 메뉴에서 Server and Client Validation를 선택합니다.
다운로드한 Atlas 관리형 인증서에 동일한 경로를 추가하거나 자체 관리형 인증서(사용하는 항목에 따라 다름)를 Certificate Authority, Client Certificate, Client Private Key 등의 각 필드에 추가합니다.
자세한 내용은 MongoDB Compass 문서에서 MongoDB에 연결하기를 참조하세요.
연결 문자열 문제
잘못된 연결 문자열 형식
Atlas에 연결하는 데 사용하는 연결 문자열 형식은 다음과 같은 여러 요인에 따라 달라집니다:
mongosh버전. 자세한 학습 은 mongosh 통해 클러스터에 연결을참조하세요.드라이버 버전. 자세한 학습은 클라이언트 라이브러리를 통해 클러스터에 연결을 참조하세요.
연결 문자열을 프로덕션에 적용하기 전에 테스트 환경에서 확인하세요.
연결 문자열 비밀번호의 특수 문자
암호에 특수 문자가 포함되어 있고 연결 문자열 URI에 암호를 사용하는 경우 특수 문자를 인코딩합니다.
퍼센트 인코딩이 필요한 특수 문자를 사용하여 비밀번호를 업데이트 하려고 하면 다음 오류 메시지가 나타납니다.
This password contains special characters which will be URL-encoded.
참고
다음의 문자와 공백 문자는 사용자 이름 또는 비밀번호에 포함된 경우 퍼센트 인코딩을 사용하여 변환해야 합니다.
: / ? # [ ] @ ! $ & ' ( ) * , ; = %
예를 들어 일반 텍스트의 비밀번호가 p@ssw0rd'9'!인 경우 비밀번호를 다음과 같이 인코딩해야 합니다:
p%40ssw0rd%279%27%21
➤ 언어 선택 드롭다운 메뉴를 사용하여 이 섹션의 인코딩 예시의 언어를 설정합니다.
1 package main 2 3 import ( 4 "context" 5 "fmt" 6 "net/url" 7 8 "go.mongodb.org/mongo-driver/bson" 9 "go.mongodb.org/mongo-driver/mongo" 10 "go.mongodb.org/mongo-driver/mongo/options" 11 ) 12 13 func main() { 14 username := "<username>" 15 password := "<password>" 16 cluster := "<clusterName>" 17 authSource := "<authSource>" 18 authMechanism := "<authMechanism>" 19 20 uri := "mongodb+srv://" + url.QueryEscape(username) + ":" + 21 url.QueryEscape(password) + "@" + cluster + 22 "/?authSource=" + authSource + 23 "&authMechanism=" + authMechanism 24 25 client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri)) 26 if err != nil { 27 panic(err) 28 } 29 defer client.Disconnect(context.TODO()) 30 31 collection := client.Database("<dbName>").Collection("<collName>") 32 33 cursor, err := collection.Find(context.TODO(), bson.D{}) 34 if err != nil { 35 panic(err) 36 } 37 38 var results []bson.D 39 if err = cursor.All(context.TODO(), &results); err != nil { 40 panic(err) 41 } 42 for _, result := range results { 43 fmt.Println(result) 44 } 45 }
1 import com.mongodb.client.MongoClient; 2 import com.mongodb.client.MongoClients; 3 import com.mongodb.client.MongoCollection; 4 import com.mongodb.client.MongoDatabase; 5 6 import org.bson.Document; 7 import java.net.URLEncoder; 8 9 public class Encoding { 10 11 public static void main(String [] args){ 12 13 try{ 14 String username = URLEncoder.encode("<username>", "UTF-8"); 15 String password = URLEncoder.encode("<password>", "UTF-8"); 16 String cluster = "<clusterName>"; 17 String authSource = "<authSource>"; 18 String authMechanism = "<authMechanism>"; 19 20 String uri = "mongodb+srv://" + username + ":" + password + "@" + cluster + 21 "/?authSource=" + authSource + "&authMechanism=" + authMechanism; 22 23 MongoClient mongoClient = MongoClients.create(uri); 24 25 MongoDatabase database = mongoClient.getDatabase("<dbName>"); 26 MongoCollection<Document> collection = database.getCollection("<collName>"); 27 28 collection.find().forEach(doc -> System.out.println(doc.toJson())); 29 30 } catch(Exception e){ 31 System.err.println(e.getCause()); 32 33 } 34 } 35 }
1 const { MongoClient } = require("mongodb"); 2 3 const username = encodeURIComponent("<username>"); 4 const password = encodeURIComponent("<password>"); 5 const cluster = "<clusterName>"; 6 const authSource = "<authSource>"; 7 const authMechanism = "<authMechanism>"; 8 9 let uri = 10 `mongodb+srv://${username}:${password}@${cluster}/?authSource=${authSource}&authMechanism=${authMechanism}`; 11 12 const client = new MongoClient(uri); 13 14 async function run() { 15 try { 16 await client.connect(); 17 18 const database = client.db("<dbName>"); 19 const ratings = database.collection("<collName>"); 20 21 const cursor = ratings.find(); 22 23 await cursor.forEach(doc => console.dir(doc)); 24 } finally { 25 await client.close(); 26 } 27 } 28 run().catch(console.dir);
1 import pymongo 2 from urllib.parse import quote_plus 3 4 username = quote_plus('<username>') 5 password = quote_plus('<password>') 6 cluster = '<clusterName>' 7 authSource = '<authSource>' 8 authMechanism = '<authMechanism>' 9 10 uri = 'mongodb+srv://' + username + ':' + password + '@' + cluster + '/?authSource=' + authSource + '&authMechanism=' + authMechanism 11 12 client = pymongo.MongoClient(uri) 13 14 result = client["<dbName"]["<collName>"].find() 15 16 # print results 17 for i in result: 18 print(i)
중요
연결 문자열 URI 외부에서 비밀번호를 사용하는 경우(예시: mongosh에 붙여넣기) 비밀번호의 특수 문자를 인코딩하지 마세요.
드라이버 버전과 호환되지 않는 연결 문자열
이 오류 메시지가 표시되면 드라이버가 최신 버전이 아닐 수 있습니다. 드라이버 업데이트에 대한 지침은 해당 드라이버 설명서를 참조하세요.
인터넷 서비스 제공자 DNS에 의한 연결 문자열 차단
DNS 시드 목록 연결 문자열 형식을 사용하여 Atlas에 연결할 때 다음 오류가 표시될 수 있습니다.
DNSHostNotFound: Failed to look up service "<MongoDB service name>"
이 오류는 ISP가 제공하는 기본 DNS 서버를 사용할 때 발생할 수 있습니다. 해당 DNS 서버는 DNS 시드 목록 연결 문자열 형식이 사용하는 SRV 조회를 지원하지 않을 수 있습니다.
이 문제를 해결하려면 공용 DNS 서버 사용하도록 DNS구성을 변경해 볼 수 있습니다.
예시
ISP의 DNS 서버 대신 Google Public DNS를 사용하도록 네트워크 설정을 구성할 수 있습니다.
공용 DNS 서버를 사용하도록 네트워크 설정을 업데이트한 후 클러스터에 연결합니다.
DB 도구의 연결 문자열 오류
DNS 시드 목록 연결 문자열 형식(mongodb+srv://)을 사용하여 MongoDB Database Tools (mongodump, mongorestore 등) 중 하나에서 Atlas에 연결할 때 다음 오류가 표시될 수 있습니다.
lookup nta8e.mongodb.net on 123.45.67.8:27017: cannot unmarshal DNS message
이 경우 다음 연결 옵션 중 하나를 대신 사용합니다.
--uri옵션을 SRV가 아닌 연결 문자열(mongodb://)과 함께 사용합니다.--host옵션을 사용하여 연결할 호스팅하다 지정합니다.
SRV 연결 문자열을 사용한 연결이 거부됨
드라이버 또는 Compass와 함께 DNS 시드 목록 연결 문자열 형식(mongodb+srv://)을 사용하는 경우 다음 오류가 나타날 수 있습니다.
Error: querySrv ECONNREFUSED _mongodb._tcp.<SRV Record>
이 오류를 해결하려면 다음 단계를 완료하세요.
DNS SRV 이름 찾기
애플리케이션 연결의 1~6 단계를 따르세요.
드라이버 및 버전을 선택합니다.
Use this connection string in your application 아래에서 SRV 호스트 이름이
mongodb+srv://연결 문자열에 나타납니다..mongodb.net으로 끝나는 호스트 이름의 일부입니다.예를 들어
cluster0.dfget.mongodb.net입니다.
노드의 호스트 이름 및 포트 번호 찾기
동일한 연결 모달에서:
Use this connection string in your application에서 SRV Connection String 토글을 끕니다.
각 노드의 호스트 이름과 포트 번호를 나열하는 표준 연결 문자열 (
mongodb://)이 표시됩니다.클러스터의 연결 문자열 토폴로지 및 연결 방법에 따라 다양한 호스트 이름과 포트를 가질 수 있습니다. 비공개 엔드포인트에 대해 자세히 학습하려면 비공개 엔드포인트 구성을 참조하세요.
기본 네트워크 연결 테스트
문제가 발생한 애플리케이션 서버의 터미널 또는 명령 프롬프트에서 다음 명령을 실행하세요.
DNS SRV 확인 테스트
Linux 또는 macOS의 경우 다음 명령을 실행 .
dig SRV _mongodb._tcp.<DNS SRV name> Windows 의 경우 다음 명령을 실행 .
nslookup -debug -q=SRV _mongodb._tcp.<DNS SRV name> 응답의 ANSWER SECTION에서 클러스터의 각 노드에 대한 결과가 하나씩 표시되어야 합니다. 예시는 다음과 같습니다.
;; ANSWER SECTION: _mongodb._tcp.gcluster0.dfget.mongodb.net. 60 IN SRV 0 0 27017 cluster0-shard-00-00.dfget.mongodb.net. _mongodb._tcp.gcluster0.dfget.mongodb.net. 60 IN SRV 0 0 27017 cluster0-shard-00-01.dfget.mongodb.net. _mongodb._tcp.gcluster0.dfget.mongodb.net. 60 IN SRV 0 0 27017 cluster0-shard-00-02.dfget.mongodb.net. DNS 노드 호스트 이름 확인 테스트
클러스터 의 각 호스트 이름에 대해 다음을 수행합니다.
Linux 또는 macOS의 경우 다음 명령을 실행 .
dig <Node Hostname> Windows 의 경우 다음 명령을 실행 .
nslookup -debug -q=A <Node Hostname> 응답의 ANSWER SECTION에서 DNS 호스트명이 확인된 IP 주소를 볼 수 있어야 합니다. 예시는 다음과 같습니다.
;; ANSWER SECTION: cluster0-shard-00-00.ag9in.mongodb.net. 60 IN A 10.10.10.10 핑 테스트
참고
ICMP 요청은 클라우드 공급자가 비공개 엔드포인트 연결에서 차단할 수 있습니다.
클러스터 의 각 호스트 이름에 대해 다음을 수행합니다.
Linux 또는 macOS의 경우 다음 명령을 실행 .
ping -c 10 <Node Hostname> Windows 의 경우 다음 명령을 실행 .
ping /n 10 <Node Hostname> 출력을 검토하여 패킷 손실 및 왕복 시간(RTT)을 확인합니다. 패킷 손실 또는 지연 시간 길면 서버 와 클러스터 노드 간의 네트워크 문제를 의미할 수 있습니다.
엔드투엔드 네트워크 연결 테스트
Linux 또는 macOS의 경우 다음 명령을 실행 .
nc -zv <Node Hostname> <Node Port Number> Windows 의 경우 다음 명령을 실행 .
Test-NetConnection -Port <Node Port Number> -InformationLevel "Detailed" -ComputerName "<Node Hostname>"
문제 해결
이전 단계에서 테스트를 실행 후 다음 지침 사용하여 실패한 테스트에 따라 연결 오류를 해결합니다.
DNS SRV 확인 테스트 실패: DNS 확인자가 SRV 기록 조회를 지원하지 않거나 아웃바운드 DNS 트래픽이 차단되었습니다. 다음 중 하나를 시도합니다.
mongodb+srv://대신 비SRV 연결 문자열 형식(mongodb://)으로 전환합니다. 비SRV 연결 문자열 가져오려면 Atlas 에서 Connect 모달을 열고 드라이버 와 버전을 선택한 다음 Use this connection string in your application 아래에서 SRV Connection String 토글을 끄세요.Google Public DNS와 같이 SRV 조회를 지원하는 공용 DNS 서버사용하도록 네트워크를 구성합니다.
DNS 노드 호스트 이름 확인 테스트 실패: DNS 확인자가 개별 노드 호스트 이름을 확인할 수 없습니다. 비공개 엔드포인트 사용하는 경우 비공개 엔드포인트 DNS 구성이 올바른지 확인합니다.
핑 테스트 실패: 방화벽 이나 클라우드 공급자 에 의해 ICMP 트래픽이 차단되었을 수 있습니다. 이것이 반드시 TCP 연결 문제를 나타내는 것은 아닙니다. 엔드 투 엔드 네트워크 연결 테스트를 진행하여 포트
27017에서 TCP 연결을 확인합니다.엔드 투 엔드 네트워크 연결 테스트 실패: 방화벽 또는 네트워크 정책이 노드 호스트 이름의 포트
27017에 대한 액세스 차단하고 있습니다. 다음을 확인합니다.애플리케이션 서버의 IP 주소를 클러스터의 IP 액세스 목록에 추가합니다.
방화벽 통해 포트
27017에서 아웃바운드 TCP 연결을 허용합니다.
모든 테스트를 통과했지만 오류가 지속됨: 드라이버 버전에 문제가 있을 수 있습니다. 이전 드라이버 버전은 SRV 연결 문자열 형식을 올바르게 지원 하지 않을 수 있습니다. 운전자 최신 버전으로 업데이트합니다. Connect 모달의 Use this connection string in your application 아래에 있는 SRV Connection String 토글을 꺼 표준(비SRV) 연결 문자열 형식 (
mongodb://)으로 전환할 수도 있습니다.