Integ Docs

Appearance

Troubleshooting ​

Расширенное руководство по диагностике и решению проблем. Для быстрого поиска по конкретным ошибкам используй ERRORS.md.

Диагностика проблем ​

Общий алгоритм ​

  1. Определи тип проблемы:

    • Build/TypeScript → см. секцию Build
    • Deploy/Cloudflare → см. секцию Deploy
    • Runtime/D1 → см. секцию Runtime
    • Локальная разработка → см. секцию Development

  2. Проверь логи:

    bash
    # Логи локального сервера
pnpm start sofa  # смотри консоль

# Логи Cloudflare Worker
wrangler tail --env dev

  3. Проверь конфигурацию:

    bash
    # Doppler
doppler secrets --config dev

# wrangler.toml
cat integrations/sofa/wrangler.toml

Build проблемы ​

TypeScript не компилируется ​

Симптомы: pnpm build падает с ошибками TS.

Диагностика:

bash
# Проверь конкретный пакет
pnpm --filter sofa typecheck

# Полный typecheck
pnpm typecheck

Частые причины:

  1. Пакет не установлен:

    bash
    pnpm install

  2. Пакет не собран:

    bash
    pnpm build

  3. Устаревшие типы:

    bash
    # Очисти кэш и пересобери
rm -rf node_modules/.cache
pnpm install
pnpm build

  4. Конфликт версий:

    bash
    # Проверь lockfile
git diff pnpm-lock.yaml

ESLint ошибки ​

Симптомы: Pre-commit hook падает или pnpm lint показывает ошибки.

Решение:

bash
# Автофикс
pnpm lint:fix

# Форматирование
pnpm format

# Если не помогло - проверь конкретные файлы
pnpm eslint path/to/file.ts --fix

Игнорирование правил (крайний случай):

typescript
// eslint-disable-next-line @typescript-eslint/no-unused-vars
const _temp = value;

Deploy проблемы ​

Worker не деплоится ​

Симптомы: pnpm deploy:dev падает с ошибкой.

Диагностика:

bash
# Проверь авторизацию
wrangler whoami

# Проверь конфиг
cat integrations/sofa/wrangler.toml

Частые причины:

  1. Не авторизован:

    bash
    wrangler login

  2. Неверный account_id:

    bash
    # Проверь в wrangler.toml
grep account_id integrations/sofa/wrangler.toml

# Должен совпадать с
wrangler whoami

  3. wrangler.toml не сгенерирован:

    bash
    pnpm generate:env -- dev

Service binding не найден ​

Симптомы: При деплое gateway ошибка Service "integ-xxx" not found.

Причина: Worker интеграции не задеплоен.

Решение:

bash
# 1. Сначала деплой интеграцию
pnpm deploy:dev --filter=xxx

# 2. Потом gateway
pnpm deploy:dev --filter=integ-gateway

Секреты не найдены ​

Симптомы: Error: Secret CRYPTO_KEY not found.

Решение:

bash
# 1. Проверь Doppler
doppler secrets --config dev | grep CRYPTO_KEY

# 2. Синхронизируй секреты
pnpm sync-secrets:dev

# 3. Проверь что секрет установлен
wrangler secret list --env dev

Runtime проблемы ​

D1 база недоступна ​

Симптомы: D1_ERROR или no such table.

Диагностика:

bash
# Локально - проверь что база создана
ls -la .wrangler/state/v3/d1/

# Remote - проверь базу в Cloudflare
wrangler d1 list

Решения:

  1. Локально — база не создана:

    bash
    pnpm setup:local

  2. Локально — миграции не выполнены:

    bash
    # Миграции применяются через код (worker должен быть запущен)
curl -X POST http://localhost:8787/{integration}/setup

  3. Remote — миграции не выполнены:

    bash
    # Задеплой worker, затем вызови setup
pnpm deploy:dev --filter=sofa
curl -X POST https://integ.dev.happ.tools/{integration}/setup

  4. Локально — данные повреждены:

    bash
    pnpm setup:reset

KV недоступен ​

Симптомы: Ошибки при работе с кэшем.

Диагностика:

bash
# Проверь namespace
wrangler kv:namespace list

# Проверь binding в wrangler.toml
grep -A5 "kv_namespaces" integrations/sofa/wrangler.toml

Решение:

bash
# Создай namespace если его нет
wrangler kv:namespace create integ-kv --env dev

# Обнови wrangler.toml
pnpm generate:env -- dev

Credentials не расшифровываются ​

Симптомы: Error: Failed to decrypt credentials.

Причины:

  1. Неверный CRYPTO_KEY или CRYPTO_SALT
  2. Ключи изменились после шифрования данных

Решение:

bash
# 1. Проверь что ключи одинаковы везде
doppler secrets --config dev | grep CRYPTO

# 2. Если ключи менялись — пересоздай credentials через Admin UI или CLI
# pnpm cli creds:set sofa NETHUNT_API_KEY "new-value"

Development проблемы ​

Порт занят ​

Симптомы: Error: listen EADDRINUSE: address already in use :::8787.

Решение:

bash
# Найди процесс
lsof -i :8787

# Убей его
kill -9 <PID>

# Или используй другой порт
pnpm start sofa -- --port 8788

Doppler не настроен ​

Симптомы: Error: Doppler project not configured.

Решение:

bash
doppler login
doppler setup
# Выбери project: integ-core
# Выбери config: dev

Miniflare проблемы ​

Симптомы: Ошибки с локальным хранилищем.

Решение:

bash
# Пересоздай локальные базы
pnpm setup:reset

# Или очисти только данные
rm -rf .wrangler/state
pnpm setup:local

Hot reload не работает ​

Симптомы: Изменения кода не применяются.

Решение:

  1. Перезапусти dev server: Ctrl+C → pnpm start sofa
  2. Очисти кэш:
    bash
    rm -rf node_modules/.cache
pnpm start sofa

Network проблемы ​

Webhook не доходит ​

Диагностика:

bash
# Проверь что worker отвечает
curl https://integ.dev.happ.tools/sofa/health

# Проверь webhook endpoint
curl -X POST https://integ.dev.happ.tools/sofa/webhook/webinar-call-originate \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+380991234567"}'

Частые причины:

  1. Worker не задеплоен:

    bash
    pnpm deploy:dev --filter=sofa

  2. Gateway не обновлён:

    bash
    pnpm deploy:dev --filter=integ-gateway

  3. DNS не обновился:

    • Подожди 5-10 минут
    • Проверь в Cloudflare Dashboard

Rate limit ​

Симптомы: Error: Rate limit exceeded.

Решение:

  1. Подожди минуту
  2. Уменьши частоту запросов
  3. Если нужно больше — измени лимит в коде

Debugging tips ​

Включить verbose логи ​

bash
# Verbose логирование (LOG_LEVEL=debug) — видны step :input/:output
pnpm debug sofa
pnpm debug gateway

# При тестах
DEBUG=* pnpm test

Проверить env переменные ​

bash
# Локально
cat .env

# В Cloudflare
wrangler secret list --env dev

Проверить состояние базы ​

bash
# Локально
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite

# Remote
wrangler d1 execute integ-db --env dev --command "SELECT * FROM migrations;"

Чеклист перед обращением за помощью ​

  • [ ] Прочитал ошибку и понял что она значит
  • [ ] Проверил ERRORS.md на наличие решения
  • [ ] Выполнил pnpm install && pnpm build
  • [ ] Проверил что Doppler настроен: doppler setup
  • [ ] Проверил логи (консоль/wrangler tail)
  • [ ] Погуглил текст ошибки
  • [ ] Попробовал pnpm setup:reset для локальных проблем

Связанные документы ​

  • ERRORS — каталог ошибок с решениями
  • DEVELOPMENT — настройка локальной разработки
  • SECRETS — управление секретами
  • CI_CD — настройка CI/CD