Устранение ошибки Azure: указанное CGI‑приложение завершило работу

Ошибка «указанное CGI‑приложение завершило работу» в Azure обычно означает, что процесс веб‑приложения перестал отвечать, был завершён или не удалось корректно интегрироваться с IIS. Ниже пошагово разберём причины, действия для диагностики и набор практических решений, а также критерии приёмки и чек‑листы для разных ролей.

Что означает эта ошибка

Кратко: сервер IIS или механизм хоста ожидает отклика от CGI/процесса (в случае .NET — Kestrel/ASP.NET Core), но не получает его в разумное время. Это может быть таймаут, аварийное завершение процесса, исключение на старте, несовместимость версий или проблема с сертификатом/конфигурацией.

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

• CGI — интерфейс для запуска внешних процессов из веб‑сервера; в контексте Azure означает «внешний» процесс приложения.
• IIS Integration — модуль, который связывает IIS и процесс Kestrel/ASP.NET.

Основные причины

• Длительное время запуска приложения (heavy startup) — превышение внутреннего таймаута.
• Отсутствие или неправильная интеграция с IIS (UseIISIntegration не включён там, где нужен).
• Ошибка на начальной инициализации (несовместимые зависимости, неправильная конфигурация сертификатов).
• Проблемы с ресурсами: память, CPU, квоты App Service Plan.
• Некорректные версии .NET Core / Net Core runtime в среде Azure.
• Отсутствие необходимых сертификатов в хранилище App Service.

Как по шагам диагностировать и исправить

1. Включите сбор данных и Auto‑Heal

1. Откройте портал Azure и выберите ваш App Service.
2. Выберите раздел “Диагностика и устранение проблем”.

3. В разделе диагностических инструментов откройте “Диагностические инструменты” → “Автоматическое восстановление (Auto‑Heal)”.

4. Добавьте правило: по увеличению количества ошибок/таймаутов перезапускать процесс, сохранять дамп и включать логирование.
5. Сохраните конфигурацию и перезапустите приложение.

Важно: Auto‑Heal собирает дампы и трассы, которые помогут понять, где происходит зависание.

2. Проверьте интеграцию IIS в коде хоста

Если ваше приложение использует старый WebHostBuilder (ASP.NET Core 2.x), убедитесь, что включена UseIISIntegration:

public static void Main(string[] args)
{
  var host = new WebHostBuilder()
    .UseContentRoot(Directory.GetCurrentDirectory())
    .UseKestrel()
    .UseIISIntegration() // Необходимо для корректной работы под IIS/Azure
    .UseStartup()
    .Build();
  host.Run();
}

В современных проектах (ASP.NET Core 3.x и выше) используется Generic Host. Рекомендуемый шаблон:

public static IHostBuilder CreateHostBuilder(string[] args) =>
  Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
      webBuilder.UseStartup();
    });

Примечание: Host.CreateDefaultBuilder и ConfigureWebHostDefaults настраивают множество параметров по умолчанию; проверьте документацию по вашей версии .NET.

3. Проверьте версию .NET и runtime в App Service

• В портале App Service откройте “Конфигурация” → “Образ среды” и убедитесь, что установлен нужный стек .NET.
• Если приложение было развернуто с самодостаточным (self-contained) билдом — проверьте, что артефакты включают нужные runtime‑файлы.

4. Включите Always On и Health Check

• Always On удерживает приложение живым и снижает количество «холодных» запусков.
• Health Check (в настройках App Service) позволяет Azure автоматически помечать и перезапускать инстансы при проблемах.

5. Соберите расширенные логи и дампы

• Включите Application Logging (Filesystem) и Web Server Logging.
• В Diagnostic Logs включите Detailed Error Messages и Failed Request Tracing.
• Скачайте дампы (через Auto‑Heal или вручную) и проанализируйте с dotnet‑dump или WinDbg.

6. Проверка сертификатов и TLS

Если приложение использует клиентские сертификаты, Key Vault или специфические SSL‑настройки, убедитесь, что сертификаты загружены в App Service и имеют правильные политики доступа.

7. Ресурсы и масштабирование

• Проверьте метрики CPU, память и количество запросов.
• Если приложение падает из‑за OOM — увеличьте план App Service или оптимизируйте использование памяти.
• Для пиковых нагрузок используйте вертикальное/горизонтальное масштабирование и слоты развертывания.

8. Проверка browser / TLS клиентских ошибок

Иногда в браузере (например, Chrome) вы увидите дополнительные подсказки по ошибкам TLS/SSL или кэшированию. Используйте режим инкогнито и отключите расширения для корректной проверки.

Чек‑лист для разных ролей

Разработчик:

• Проверить UseIISIntegration/Generic Host.
• Прогнать локальный старт с конфигурацией, приближённой к Azure.
• Добавить тайм‑аута и обработку исключений на старте.

DevOps/Инженер платформы:

• Включить Auto‑Heal и собрать дампы.
• Проверить Always On и Health Check.
• Проверить конфигурацию App Service Plan и квоты.

SRE/операции:

• Настроить алерты по росту ошибок и превышению CPU.
• Автоматизировать скачивание дампов и их хранение.

Когда предложенные решения могут не помочь

• Если причина — баг в самом коде, приводящий к дедлоку или бесконечной инициализации, то инфраструктурные правки только скроют симптомы. Нужен анализ дампов и исправление кода.
• Если проблема в сторонней библиотеке или нативном зависимом компоненте, может потребоваться переход на другой образ App Service или контейнеризацию.

Быстрый план действий при инциденте

1. Включить Auto‑Heal и собрать дамп. 2. Включить логирование сервера и приложения. 3. Перезапустить приложение, включив Always On. 4. Проверить версии runtime и интеграцию с IIS. 5. Если не помогает — проанализировать дамп и стек вызовов.

flowchart TD
  A[Ошибка CGI / процесс завершился] --> B{Авто‑восстановление включено?}
  B -- Да --> C[Собрать дамп и логи]
  B -- Нет --> D[Включить Auto‑Heal + перезапуск]
  C --> E{Дамп показывает исключение на старте?}
  E -- Да --> F[Исправить код/зависимости]
  E -- Нет --> G{Проблема с интеграцией IIS?}
  G -- Да --> H[Проверить UseIISIntegration/Host]
  G -- Нет --> I[Проверить ресурсы/сертификаты/таймауты]

Критерии приёмки

• Приложение запускается стабильно в течение 24 часов без появления ошибки.
• Логи не содержат повторяющихся ошибок старта или таймаутов.
• Метрики CPU/памяти находятся в ожидаемом диапазоне.

Глоссарий (в одну строку)

• CGI — интерфейс запуска внешних приложений веб‑сервером.
• IIS — веб‑сервер Microsoft, используемый в Azure App Service.
• Kestrel — встроенный HTTP‑сервер в ASP.NET Core.
• Auto‑Heal — механизм в App Service для автоматического перезапуска и снятия дампов.

Краткое резюме

Важно: начните с включения Auto‑Heal и сбора дампов — это даст самое быстрое понимание корня проблемы. Затем проверьте интеграцию с IIS, соответствие версии runtime, настройки Always On и Health Check. Если инфраструктурные настройки не помогают, анализ дампа и исправление кода — следующий шаг.

Если хотите, могу подготовить шаблон запроса в поддержку Azure для передачи дампов и логов, а также помочь проанализировать дамп по стеку вызовов.