Устранение неполадок эмулятора Azure Cosmos DB

Статья
11/20/2024

Эмулятор Azure Cosmos DB предоставляет среду, которая эмулирует облачную службу для разработки. Советы, приведенные в этой статье, помогут устранить неполадки, которые могут возникнуть при установке или использовании эмулятора.

Контрольный список по устранению неполадок

Ниже приведен список распространенных действий по устранению неполадок, которые необходимо выполнить, если эмулятор Azure Cosmos DB не работает должным образом.

Сброс данных

Если вы установили новую версию эмулятора, и у вас возникли ошибки, убедитесь, что вы сбрасываете данные. Чтобы сбросить данные, откройте контекстное меню эмулятора Azure Cosmos DB в области системы и нажмите кнопку "Сбросить данные".

Если сброс данных не исправляет ошибки, можно:

Удалите эмулятор.
Удалите старые версии эмулятора (если они существуют).
Удалите папку %ProgramFiles%\Azure Cosmos DB Emulator .
Переустановите эмулятор.

Кроме того, если сброс данных не работает, перейдите в %LOCALAPPDATA%\CosmosDBEmulator расположение и удалите папку.

Просмотр поврежденных счетчиков производительности Windows

Если эмулятор Azure Cosmos DB перестает отвечать, соберите файлы дампа из %LOCALAPPDATA%\CrashDumps папки, сжать файлы, а затем откройте запрос в службу поддержки в портал Azure.
Если Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe перестает отвечать, это сбой может указать, что счетчики производительности повреждены. Чтобы проверить состояние счетчика, выполните следующую команду:
```
lodctr /R
```

Диагностика проблем с подключением

Если возникла проблема с подключением, соберите файлы трассировки, сжать файлы, а затем откройте запрос в службу поддержки в портал Azure.
Если вы получаете сообщение "Служба недоступна", эмулятор может не инициализировать сетевой стек. Проверьте, установлен ли клиент Pulse Secure Client или Juniper Networks, так как их драйверы сетевого фильтра могут вызвать проблему. Вы также можете попробовать удалить другие драйверы сетевого фильтра, чтобы устранить проблему. Кроме того, запустите эмулятор, используя /DisableRIO для переключения сетевого взаимодействия эмулятора на обычный Winsock.
Если вы получаете сообщение об ошибке подключения, например "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting...", это сообщение об ошибке может указывать на глобальные изменения в ОС (например, предварительная версия сборки 20170) или изменения в параметрах браузера, включающих TLS 1.3 в качестве протокола по умолчанию. Аналогичное сообщение об ошибке, например "Microsoft.Azure.Documents.DocumentClientException: запрос выполняется с запрещенным шифрованием в транзитном протоколе или шифре. Если вы используете пакет SDK для выполнения запроса к эмулятору Azure Cosmos DB, можно создать параметр протокола SSL/TLS с минимальным разрешенным протоколом SSL/TLS. Эта ошибка также может возникнуть, так как эмулятор Azure Cosmos DB поддерживает только протокол TLS 1.2. Рекомендуемое решение — задать TLS 1.2 как стандартное.

Например:
1. В диспетчере IIS перейдите на веб-сайты> по умолчанию.
2. Найдите привязки сайта для порта 8081 и измените их, чтобы отключить TLS 1.3. Вы также можете обновить параметры для веб-браузера с помощью параметра "Параметры ".
  
  Примечание.
  
  Если компьютер входит в спящий режим или запускает обновления ОС во время работы эмулятора, может появиться сообщение об ошибке "Служба недоступна".
3. Чтобы сбросить данные эмулятора, щелкните правой кнопкой мыши значок, который отображается в области уведомлений Windows, а затем выберите "Сбросить данные".

Сбор файлов трассировки

Чтобы собрать трассировки отладки, выполните следующие команды от имени администратора в окне командной строки:

Перейдите к пути, в котором установлен эмулятор:
```
cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
```
Завершите работу эмулятора и просмотрите системную область, чтобы убедиться, что программа завершает работу:
```
Microsoft.Azure.Cosmos.Emulator.exe /shutdown
```
Примечание.

Для завершения процесса может потребоваться одна минута. Вы также можете выбрать "Выйти " в пользовательском интерфейсе эмулятора Azure Cosmos DB.
Запустите ведение журнала, выполнив следующую команду:
```
Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces
```
Запустите эмулятор:
```
Microsoft.Azure.Cosmos.Emulator.exe
```
Воспроизведите проблему. Если обозреватель данных не работает, необходимо ждать только несколько секунд, чтобы браузер мог обнаружить ошибку.

Остановка ведения журнала:

Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

Перейдите %ProgramFiles%\Azure Cosmos DB Emulator к пути и найдите файл docdbemulator_000001.etl .
Откройте запрос в службу поддержки в портал Azure и включите ETL-файл вместе с любыми шагами, необходимыми для воспроизведения проблемы.

Установка сертификатов для клиентских приложений

Иногда может потребоваться взять экспортируемый сертификат эмулятора и использовать его с клиентским приложением. Точный процесс зависит от пакета SDK.

Экспорт сертификата TLS/SLL

Экспортируйте сертификат эмулятора, чтобы успешно использовать конечную точку эмулятора из языков и сред выполнения, которые не интегрируются с Хранилищем сертификатов Windows. Вы можете экспортировать сертификат с помощью диспетчера сертификатов Windows или PowerShell после первого запуска эмулятора.

Получите сертификат с помощью понятного имени DocumentDbEmulatorCertificate и сохраните сертификат в переменной оболочки с именем $cert.
```
$cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}
```
Используйте export-Certificate для экспорта сертификата в временный файл в домашней папке.
```
$params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params
```
Примечание.

В Windows домашняя папка, как правило C:\Users\[username]\, предполагается, что ваш домашний диск является C:.
Используйте certutil для преобразования сертификата в файл сертификата в кодировке Base-64 X.509 .
```
certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer
```
Удалите временный файл.
```
Remove-Item $home/tmp-cert.cer
```

Импорт сертификата для приложений Java

При запуске приложений Java или приложений MongoDB, использующих клиент на основе Java, установка сертификата в хранилище сертификатов Java по умолчанию проще, чем передача -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" параметров. Например, включенное демонстрационное приложение Java (https://localhost:8081/_explorer/index.html) зависит от хранилища сертификатов по умолчанию.

Следуйте инструкциям по созданию, экспорту и импорту TLS/SSL-сертификатов, чтобы импортировать сертификат X.509 в хранилище сертификатов Java по умолчанию. Помните, что вы работаете в каталоге %JAVA_HOME% при запуске ключа. После импорта сертификата в хранилище сертификатов клиенты API SQL и Azure Cosmos DB для 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 отключена. По умолчанию пакет SDK Python для Azure Cosmos DB для NoSQL не пытается использовать TLS/SSL-сертификат при подключении к локальному эмулятору. Дополнительные сведения см. в клиентской библиотеке Azure Cosmos DB для NoSQL для Python.

Если вы хотите использовать проверку TLS, следуйте примерам в оболочке TLS/SSL для объектов сокета.

Импорт сертификата для приложений Node.js

При подключении к эмулятору из пакетов SDK Node.js проверка TLS отключена. По умолчанию пакет SDK Node.js (версия 1.10.1 или более поздней) для API для NoSQL не пытается использовать TLS/SSL-сертификат при подключении к локальному эмулятору.

Если вы хотите использовать проверку TLS, следуйте примерам в документации по Node.js.

Ротация сертификатов

Вы можете принудительно восстановить сертификаты эмулятора, открыв эмулятор с аргументом /ResetDataPath . Это действие удаляет все данные, хранящиеся локально эмулятором. Дополнительные сведения о аргументах командной строки см. в разделе аргументов командной строки эмулятора Windows.

Совет

Кроме того, в контекстном меню эмулятора Azure Cosmos DB выберите пункт "Сброс данных " в области системы Windows.

Если вы установили сертификаты в хранилище сертификатов Java или использовали их в другом месте, необходимо повторно использовать их с помощью текущих сертификатов. Приложение не может подключиться к локальному эмулятору, пока не будут обновлены сертификаты.

Поделиться через