이 페이지에서는 일반적인 연결 문제와 가능한 해결 방법을 간략하게 설명합니다.
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 라는 오류를 표시합니다.
클러스터 계층과 최대 동시 연결 수에 대한 자세한 비교는 연결 제한 및 클러스터 계층을 참조하세요.
가능한 솔루션
현재 사용하지 않는 클러스터에 대한 열려 있는 연결을 모두 닫습니다.
더 많은 동시 연결을 지원하려면 클러스터를 더 상위 계층으로 스케일링합니다.
애플리케이션을 다시 시작합니다.
To prevent this issue in the future, consider using the
maxPoolSizeconnection string option to limit the number of connections in the connection pool.
이 문제를 해결하는 방법을 알아보려면 연결 문제 해결 페이지를 참조하세요.
연결 수가 급증하는 동안 샤딩된 클러스터의 성능 저하
Atlas can generate an optimized SRV connection string for sharded clusters using the load balancers from your private endpoint service. When you use an optimized connection string, Atlas limits the number of connections per mongos between your application and your sharded cluster. The limited connections per mongos improve performance during spikes in connection counts.
비공개 엔드포인트를 사용하는 샤딩된 클러스터에 대해 최적화된 연결 문자열에 대해 자세히 학습 보려면 비공개 엔드포인트 사용하여 샤딩된 클러스터에 대한 연결 성능을 최적화하려면 어떻게 해야 하나요?를 참조하세요.
방화벽 뒤에서 연결을 시도하는 경우
Atlas UI에 연결
Atlas uses a CDN to serve content quickly. If your organization uses a firewall, add the following Atlas CDN hosts to the firewall's allow list to prevent issues accessing the 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에 연결했는데 문제가 발생하는 경우 다음을 참조하세요:
이 섹션에서 SRV 연결 문자열을 사용한 연결이 거부됨을 확인하세요.
MongoDB Compass 문서의 Compass 연결 오류 섹션.
자체 관리형 X.509 인증서 또는 Atlas 에서 managed 자동 생성 X.509 인증서를 사용하여 MongoDB database 에 인증하는 경우, 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에 연결하는 데 사용하는 연결 문자열 형식은 다음과 같은 여러 요인에 따라 달라집니다:
Your
mongoshversion. To learn more, see Connect to a Cluster via 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)
중요
Do not encode special characters in your password if you are using your password outside of a connection string URI (for example, pasting it into mongosh).
드라이버 버전과 호환되지 않는 연결 문자열
이 오류 메시지가 표시되면 드라이버가 최신 버전이 아닐 수 있습니다. 드라이버 업데이트에 대한 지침은 해당 드라이버 문서를 참조하세요.
인터넷 서비스 제공자 DNS에 의한 연결 문자열 차단
DNS 시드 목록 연결 문자열 형식을 사용하여 Atlas에 연결할 경우 다음 오류가 표시될 수 있습니다:
DNSHostNotFound: Failed to look up service "<MongoDB service name>"
이 오류는 ISP가 제공하는 기본 DNS 서버를 사용할 때 발생할 수 있습니다. 해당 DNS 서버는 DNS 시드 목록 연결 문자열 형식에서 사용하는 SRV 조회를 지원하지 않을 수 있습니다.
To resolve the issue, you can try changing your DNS configuration to use a public DNS server.
예시
You can configure your network settings to use Google Public DNS instead of your ISP's DNS servers.
공용 DNS 서버를 사용하도록 네트워크 설정을 업데이트한 후 클러스터에 연결합니다.
DB 도구의 연결 문자열 오류
You might see the following error when using the DNS seed list connection string format (mongodb+srv://) to connect to Atlas from one of the MongoDB Database Tools (mongodump, mongorestore, etc):
lookup nta8e.mongodb.net on 123.45.67.8:27017: cannot unmarshal DNS message
이 경우 다음 연결 옵션 중 하나를 대신 사용합니다.
Use the
--urioption with a non-SRV connection string (mongodb://).--host옵션을 사용하여 연결할 호스팅하다 지정합니다.
SRV 연결 문자열을 사용한 연결이 거부됨
When using the DNS seed list connection string format (mongodb+srv://) with a driver or Compass, you may receive in the following error:
Error: querySrv ECONNREFUSED _mongodb._tcp.<SRV Record>
이 오류를 해결하려면 다음 단계를 완료하세요.
DNS SRV 이름 찾기
애플리케이션 연결의 1~6 단계를 따르세요.
드라이버 및 버전을 선택합니다.
Under Use this connection string in your application, the SRV hostname appears in the
mongodb+srv://connection string. It is the part of the hostname ending with.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 resolution test fails: Your DNS resolver doesn't support SRV record lookups, or outbound DNS traffic is blocked. Try either of the following:
Switch to the non-SRV connection string format (
mongodb://) instead ofmongodb+srv://. To get the non-SRV connection string, open the Connect modal in Atlas, select your driver and version, and turn off the SRV Connection String toggle under Use this connection string in your application.Configure your network to use a public DNS server that supports SRV lookups, such as Google Public DNS.
DNS 노드 호스트 이름 확인 테스트 실패: DNS 확인자가 개별 노드 호스트 이름을 확인할 수 없습니다. 비공개 엔드포인트 사용하는 경우 비공개 엔드포인트 DNS 구성이 올바른지 확인합니다.
핑 테스트 실패: 방화벽 이나 클라우드 공급자 에 의해 ICMP 트래픽이 차단되었을 수 있습니다. 이것이 반드시 TCP 연결 문제를 나타내는 것은 아닙니다. 엔드 투 엔드 네트워크 연결 테스트를 진행하여 포트
27017에서 TCP 연결을 확인합니다.엔드 투 엔드 네트워크 연결 테스트 실패: 방화벽 또는 네트워크 정책이 노드 호스트 이름의 포트
27017에 대한 액세스 차단하고 있습니다. 다음을 확인합니다.애플리케이션 서버의 IP 주소를 클러스터의 IP 액세스 목록에 추가합니다.
방화벽 통해 포트
27017에서 아웃바운드 TCP 연결을 허용합니다.
All tests pass but the error persists: The issue may be in your driver version. Older driver versions might not correctly support the SRV connection string format. Update your driver to the latest version. You can also switch to the standard (non-SRV) connection string format (
mongodb://) by turning off the SRV Connection String toggle under Use this connection string in your application in the Connect modal.