다음을 통해 공유

Azure Cosmos DB 에뮬레이터 문제 해결

  • 아티클

Azure Cosmos DB 에뮬레이터는 개발을 위해 클라우드 서비스를 에뮬레이트하는 환경을 제공합니다. 이 문서의 팁을 사용하여 에뮬레이터를 설치하거나 사용할 때 발생할 수 있는 문제를 해결할 수 있습니다.

문제 해결 검사 목록

다음은 Azure Cosmos DB 에뮬레이터가 예상대로 작동하지 않는 경우 따라야 하는 일반적인 문제 해결 단계 목록입니다.

데이터 다시 설정

새 버전의 에뮬레이터를 설치하고 오류가 발생하는 경우 데이터를 다시 설정해야 합니다. 데이터를 다시 설정하려면 시스템 트레이에서 Azure Cosmos DB 에뮬레이터 상황에 맞는 메뉴를 열고 데이터 다시 설정을 선택합니다.

데이터를 다시 설정해도 오류가 해결되지 않으면 다음을 수행할 수 있습니다.

  • 에뮬레이터를 제거합니다.
  • 에뮬레이터의 이전 버전을 제거합니다(있는 경우).
  • 폴더를 제거합니다 %ProgramFiles%\Azure Cosmos DB Emulator .
  • 에뮬레이터를 다시 설치합니다.

또는 데이터 재설정이 작동하지 않는 경우 위치로 %LOCALAPPDATA%\CosmosDBEmulator 이동한 다음 폴더를 삭제합니다.

손상된 Windows 성능 카운터 검토

  • Azure Cosmos DB 에뮬레이터가 응답을 중지하는 경우 폴더에서 %LOCALAPPDATA%\CrashDumps 덤프 파일을 수집하고 파일을 압축한 다음 Azure Portal에서 지원 티켓을 엽니다.

  • 응답을 중지하면 Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe 이 크래시가 성능 카운터가 손상되었음을 나타낼 수 있습니다. 카운터 상태를 확인하려면 다음 명령을 실행합니다.

    lodctr /R

연결 문제 진단

  • 연결 문제가 발생하는 경우 추적 파일을 수집하고 파일을 압축한 다음 Azure Portal에서 지원 티켓을 엽니다.

  • "서비스를 사용할 수 없음" 메시지가 표시되면 에뮬레이터가 네트워크 스택을 초기화하지 않을 수 있습니다. 네트워크 필터 드라이버로 인해 문제가 발생할 수 있으므로 Pulse Secure Client 또는 Juniper Networks Client가 설치되어 있는지 확인합니다. 다른 네트워크 필터 드라이버를 제거하여 문제를 해결할 수도 있습니다. 또는 에뮬레이터 네트워크 통신을 일반 Winsock으로 전환하는 데 사용하여 /DisableRIO 에뮬레이터를 시작합니다.

  • 다음과 같은 "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting..."연결 오류 메시지가 표시되는 경우 이 오류 메시지는 OS의 전역 변경 내용(예: Insider Preview Build 20170) 또는 TLS 1.3을 기본 프로토콜로 사용하도록 설정하는 브라우저 설정의 변경 내용을 나타낼 수 있습니다. "Microsoft.Azure.Documents.DocumentClientException: 전송 프로토콜 또는 암호에서 금지된 암호화를 사용하여 요청이 수행되고 있습니다. SDK를 사용하여 Azure Cosmos DB 에뮬레이터에 대한 요청을 실행하는 경우 계정 SSL/TLS 최소 허용 프로토콜 설정"이 생성될 수 있습니다. Azure Cosmos DB 에뮬레이터가 TLS 1.2 프로토콜만 지원하므로 이 오류가 발생할 수도 있습니다. 권장되는 해결 방법은 TLS 1.2를 기본값으로 설정하는 것입니다.

    예시:

    1. IIS 관리자에서 사이트 기본 웹 사이트>로 이동합니다.

    2. 포트 8081의 사이트 바인딩을 찾아 편집하여 TLS 1.3을 사용하지 않도록 설정합니다. 설정 옵션을 사용하여 웹 브라우저에 대한 설정을 업데이트할 수도 있습니다.

      참고 항목

      에뮬레이터가 실행되는 동안 컴퓨터가 절전 모드로 전환되거나 OS 업데이트를 실행하는 경우 "서비스를 현재 사용할 수 없음" 오류 메시지가 표시될 수 있습니다.

    3. 에뮬레이터 데이터를 다시 설정하려면 Windows 알림 트레이에 표시되는 아이콘을 마우스 오른쪽 단추로 클릭한 다음 데이터 다시 설정을 선택합니다.

추적 파일 수집

디버깅 추적을 수집하려면 명령 프롬프트 창에서 관리자 권한으로 다음 명령을 실행합니다.

  1. 에뮬레이터가 설치된 경로로 이동합니다.

    cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"

  2. 에뮬레이터를 종료하고 시스템 트레이를 감시하여 프로그램이 종료되었는지 확인합니다.

    Microsoft.Azure.Cosmos.Emulator.exe /shutdown

    참고 항목

    프로세스가 완료되는 데 1분 정도 걸릴 수 있습니다. Azure Cosmos DB 에뮬레이터 사용자 인터페이스에서 끝내기를 선택할 수도 있습니다.

  3. 다음 명령을 실행하여 로깅을 시작합니다.

    Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces

  4. 에뮬레이터를 시작합니다.

    Microsoft.Azure.Cosmos.Emulator.exe

  5. 문제를 재현하세요. 데이터 탐색기가 작동하지 않는 경우 브라우저가 로드될 때까지 몇 초만 기다려야 오류를 검색할 수 있습니다.

  6. 로깅 중지:

    Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

  7. 경로로 이동하고 %ProgramFiles%\Azure Cosmos DB Emulator docdbemulator_000001.etl 파일을 찾 습니다 .

  8. Azure Portal에서 지원 티켓을 열고 문제를 재현하는 데 필요한 모든 단계와 함께 .etl 파일을 포함합니다.

클라이언트 애플리케이션용 인증서 설치

경우에 따라 내보낸 에뮬레이터 인증서를 가져와 클라이언트 애플리케이션과 함께 사용해야 할 수 있습니다. 정확한 프로세스는 SDK에 따라 다릅니다.

TLS/SLL 인증서 내보내기

에뮬레이터 인증서를 내보내서 Windows 인증서 저장소와 통합되지 않는 언어 및 런타임 환경에서 에뮬레이터 엔드포인트를 성공적으로 사용합니다. 에뮬레이터를 처음 실행한 후 Windows 인증서 관리자 또는 PowerShell을 사용하여 인증서를 내보낼 수 있습니다.

  1. 친숙한 이름을 DocumentDbEmulatorCertificate 사용하여 인증서를 검색하고 인증서 $cert를 셸 변수에 저장합니다.

    $cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}

  2. Export-Certificate를 사용하여 인증서를 홈 폴더의 임시 파일로 내보냅니다.

    $params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params

    참고 항목

    Windows에서 홈 폴더는 일반적으로 C:\Users\[username]\홈 드라이브가 C:있다고 가정합니다.

  3. certutil을 사용하여 인증서를 Base-64로 인코딩된 X.509 인증서 파일로 변환합니다.

    certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer

  4. 임시 파일을 제거합니다.

    Remove-Item $home/tmp-cert.cer

Java 애플리케이션용 인증서 가져오기

Java 기반 클라이언트를 사용하는 Java 애플리케이션 또는 MongoDB 애플리케이션을 실행하는 경우 Java 기본 인증서 저장소에 인증서를 설치하는 것이 매개 변수를 전달하는 -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" 것보다 쉽습니다. 예를 들어 포함된 Java Demo 애플리케이션(https://localhost:8081/_explorer/index.html)은 기본 인증서 저장소에 따라 다릅니다.

TLS/SSL 인증서 만들기, 내보내기 및 가져오기의 지침에 따라 X.509 인증서를 기본 Java 인증서 저장소로 가져옵니다. keytool을 실행할 때 %JAVA_HOME% 디렉터리에서 작업하고 있음을 기억하세요. 인증서를 인증서 저장소로 가져온 후 SQL 및 Azure Cosmos DB의 API for MongoDB 클라이언트는 Azure Cosmos DB 에뮬레이터에 연결할 수 있습니다.

또는 다음 bash 스크립트를 실행하여 인증서를 가져올 수 있습니다.

#!/bin/bash

# If the emulator was started with /AllowNetworkAccess, replace the following with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH
# Delete the cert if it already exists
sudo $JAVA_HOME/bin/keytool -cacerts -delete -alias cosmos_emulator
# Import the cert
sudo $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

CosmosDBEmulatorCertificate TLS/SSL 인증서가 설치되면 애플리케이션이 로컬 Azure Cosmos DB 에뮬레이터에 연결하고 사용할 수 있어야 합니다.

문제가 있는 경우 SSL/TLS 연결 디버깅을 참조하세요. 대부분의 경우 인증서는 %JAVA_HOME%/jre/lib/security/cacerts 저장소에 설치되지 않을 수 있습니다. 예를 들어 둘 이상의 Java 버전이 설치된 경우 애플리케이션에서 업데이트한 인증서 저장소와 다른 인증서 저장소를 사용하고 있을 수 있습니다.

Python 애플리케이션용 인증서 가져오기

Python 애플리케이션에서 에뮬레이터에 연결하면 TLS 확인이 비활성화됩니다. 기본적으로 Azure Cosmos DB for NoSQL용 Python SDK는 로컬 에뮬레이터에 연결할 때 TLS/SSL 인증서를 사용하지 않습니다. 자세한 내용은 Python용 Azure Cosmos DB for NoSQL 클라이언트 라이브러리를 참조하세요.

TLS 유효성 검사를 사용하려면 소켓 개체에 대한 TLS/SSL 래퍼의 예제를 따릅니다.

Node.js 애플리케이션에 대한 인증서 가져오기

Node.js SDK에서 에뮬레이터에 연결하면 TLS 인증이 비활성화됩니다. 기본적으로 NoSQL용 API에 대한 Node.js SDK(버전 1.10.1 이상) 는 로컬 에뮬레이터에 연결할 때 TLS/SSL 인증서를 사용하지 않습니다.

TLS 유효성 검사를 사용하려면 Node.js 설명서의 예제를 따릅니다.

인증서 회전

인수를 사용하여 에뮬레이터를 열어 에뮬레이터 인증서를 강제로 다시 생성할 /ResetDataPath 수 있습니다. 이 작업은 에뮬레이터에 의해 로컬로 저장된 모든 데이터를 초기화합니다. 명령줄 인수에 대한 자세한 내용은 Windows 에뮬레이터 명령줄 인수를 참조하세요.

팁

또는 Windows 시스템 트레이의 Azure Cosmos DB 에뮬레이터 상황에 맞는 메뉴에서 데이터 재설정을 선택합니다.

인증서를 Java 인증서 저장소에 설치하거나 다른 곳에서 사용한 경우 현재 인증서를 사용하여 다시 설치해야 합니다. 애플리케이션은 인증서를 업데이트할 때까지 로컬 에뮬레이터에 연결할 수 없습니다.