Локальное окружение обычно имеет больше файлов, прав, памяти и сетевого доступа, чем cloud function. Поэтому рабочий локальный код может падать после деплоя из-за runtime, entrypoint, зависимостей, переменных или ограничений платформы.

Начните с первого исключения в облачном логе и сопоставьте версию runtime, команду запуска, переменные, IAM и содержимое пакета. Затем воспроизведите функцию контейнером или эмулятором с теми же ограничениями.

Коротко: что сделать

  • Проверить первое исключение и request ID
  • Сверить runtime и архитектуру
  • Проверить entrypoint и экспорт функции
  • Проверить переменные окружения и secrets
  • Проверить IAM, timeout и memory

Почему возникает проблема

Serverless-платформа запускает код в чистом эфемерном окружении. Неявные локальные зависимости там отсутствуют.

  • В пакет не попал модуль или ресурсный файл
  • Регистр имени файла отличается на Linux
  • Entrypoint указан неверно
  • Секрет существует локально, но не привязан к функции
  • Роль функции не имеет доступа к сервису
  • Код пишет в недоступный каталог или превышает timeout

Пошаговая диагностика

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

  • Скачать или перечислить состав deployment package
  • Проверить холодный и теплый запуск
  • Вывести безопасные метаданные окружения без секретов
  • Проверить IAM вызовом минимальной операции
  • Измерить время и пиковую память
  • Проверить доступ к DNS и внешнему endpoint

Как исправить

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

  • Закрепить версии зависимостей и runtime
  • Исправить entrypoint и структуру пакета
  • Подключить secrets через сервис платформы
  • Выдать функции минимальную IAM-роль
  • Писать временные файлы только в разрешенный каталог
  • Разбить длинную задачу или увеличить лимит обоснованно

Как проверить результат

  • Запустить тестовое событие в облаке
  • Проверить холодный старт
  • Проверить ошибочный вход и повтор вызова
  • Убедиться, что логи не содержат секреты
  • Проверить метрики времени, памяти и ошибок

Как не допустить повторения

Serverless-код должен собираться воспроизводимо и проверяться в окружении, близком к платформе.

  • Использовать lock-файл зависимостей
  • Добавить CI-деплой и smoke test
  • Хранить конфигурацию отдельно от кода
  • Настроить алерты по ошибкам и timeout

Чего не стоит делать

  • Не загружать локальный .env с секретами в архив
  • Не полагаться на постоянную файловую систему
  • Не выдавать функции административную роль
  • Не ловить все исключения без логирования request ID

Что подготовить для диагностики

  • Облачный лог ошибки
  • Runtime и регион
  • Манифест зависимостей
  • Конфигурация функции без секретов
  • Пример входного события

Частые вопросы

Почему ошибка только на холодном старте?

Инициализация модулей, соединений или загрузка секрета выполняется именно при создании нового экземпляра.

Можно ли использовать локальные файлы?

Только если они включены в пакет, либо как временные файлы в разрешенном каталоге. Постоянное состояние нужно хранить снаружи.

Почему запрос к базе локально проходит, а в облаке нет?

Могут отсутствовать сетевой маршрут, security group, DNS, сертификат или IAM-разрешение.

Когда стоит обратиться за помощью

Подключайте специалиста, если функция падает нестабильно, зависит от VPC, очередей и секретов или ошибка появилась после обновления runtime.

Итог

Разница между локальным и serverless окружением устраняется явными зависимостями, правами и воспроизводимым деплоем. Настроить функцию и CI можно через @rabotator_support.