Типовые неисправности и способы устранения

Контейнер не запускается или перезапускается в цикле

Признаки: в выводе docker ps контейнер имеет статус Restarting или отсутствует.

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

ssh alfa "docker logs sdm_backend --tail 100"

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

• Недоступна MongoDB или Redis --- контейнер ждёт прохождения проверки здоровья зависимого сервиса. Проверить, что sdm_mongodb и sdm_redis работают.
• Ошибка в коде при запуске --- в журнале будет трассировка ошибки Python. Исправить код и перезапустить.
• Нехватка памяти --- Docker остановил контейнер из-за превышения ограничения. В журнале будет Killed или OOMKilled. Увеличить ограничение памяти в docker-compose.yml или уменьшить параметры параллельности (OCR_WORKERS, BATCH_SIZE).

Проверка причины остановки:

ssh alfa "docker inspect sdm_backend --format='{{.State.OOMKilled}}'"

Если ответ true --- контейнер был остановлен из-за нехватки памяти.

Очередь обработки зависла

Признаки: задания остаются в статусе processing длительное время (более часа), новые задания не обрабатываются.

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

# Сколько заданий «застряли»
ssh alfa "docker exec sdm_mongodb mongosh smart_doc_matcher --eval 'db.jobs.countDocuments({status:\"processing\"})'"

# Когда последний раз обновлялись задания
ssh alfa "docker exec sdm_mongodb mongosh smart_doc_matcher --eval 'db.jobs.find({status:\"processing\"}).sort({updated_at:-1}).limit(3).toArray()'"

Решение:

Сбросить зависшие задания обратно в очередь ожидания:

ssh alfa "docker exec sdm_mongodb mongosh smart_doc_matcher --eval 'db.jobs.updateMany({status:\"processing\"}, {\$set:{status:\"pending\"}})'"

Затем перезапустить серверную часть:

ssh alfa "cd /opt/alfa && docker compose restart backend"

Возможные причины зависания:

• Серверная часть была перезапущена во время обработки --- задания остались в промежуточном статусе.
• Пакетный запрос к Claude не получил ответа --- проверить журнал на наличие ошибок от Anthropic.
• Нехватка памяти при обработке крупного файла --- процесс был остановлен, но статус задания не обновился.

Расхождение между интерфейсом и базой данных

Признаки: пользовательский интерфейс показывает устаревшие данные, счётчики не совпадают с реальным состоянием, появляются ошибки при обращении к несуществующим записям.

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

Проверить, что серверная часть доступна:

ssh alfa "curl -s http://localhost:8000/health"

Сравнить данные в интерфейсе с данными в базе:

# Общее количество документов
ssh alfa "docker exec sdm_mongodb mongosh smart_doc_matcher --eval 'db.documents.countDocuments()'"

# Количество групп
ssh alfa "docker exec sdm_mongodb mongosh smart_doc_matcher --eval 'db.document_groups.countDocuments()'"

Решение:

В большинстве случаев достаточно обновить страницу в браузере (Ctrl+F5 для очистки кэша). Если данные всё ещё расходятся --- перезапустить серверную часть:

ssh alfa "cd /opt/alfa && docker compose restart backend"

Нехватка места на диске

Признаки: ошибки записи в журналах MinIO или MongoDB, контейнеры перезапускаются, загрузка новых файлов не работает.

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

ssh alfa "df -h /"

Решение:

1. Удалить устаревшие образы Docker:

ssh alfa "docker image prune -a -f"

1. Очистить журналы контейнеров:

ssh alfa "truncate -s 0 /var/lib/docker/containers/*/\*-json.log"

1. Если места по-прежнему не хватает --- рассмотреть удаление ненужных данных из архива через пользовательский интерфейс или расширение диска сервера.

Ошибка обращения к Claude

Признаки: в журнале серверной части ошибки вида AuthenticationError, RateLimitError, APIConnectionError от библиотеки Anthropic.

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

ssh alfa "docker logs sdm_backend --tail 100 2>&1 | grep -i 'anthropic\|claude\|api.*error'"

Частые ошибки и решения:

Ошибка	Причина	Решение
AuthenticationError	Неверный или просроченный ключ доступа	Проверить переменную ANTHROPIC_API_KEY в файле .env
RateLimitError	Превышен лимит запросов	Уменьшить OCR_WORKERS и BATCH_SIZE, подождать несколько минут
APIConnectionError	Нет связи с серверами Anthropic	Проверить доступность интернета с сервера: curl -s https://api.anthropic.com
InternalServerError	Временная ошибка на стороне Anthropic	Подождать и повторить. Зависшие задания сбросить (см. выше)

После исправления причины нужно сбросить задания со статусом error обратно в ожидание:

ssh alfa "docker exec sdm_mongodb mongosh smart_doc_matcher --eval 'db.jobs.updateMany({status:\"error\"}, {\$set:{status:\"pending\"}})'"
ssh alfa "cd /opt/alfa && docker compose restart backend"

MongoDB не отвечает

Признаки: серверная часть не запускается, в журнале ошибки подключения к MongoDB.

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

ssh alfa "docker logs sdm_mongodb --tail 50"
ssh alfa "docker exec sdm_mongodb mongosh --eval 'db.runCommand(\"ping\")'"

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

• Контейнер не запущен --- запустить: docker compose up -d mongodb.
• Нехватка памяти --- MongoDB с параметром --wiredTigerCacheSizeGB 3 требует не менее 4 ГБ свободной оперативной памяти.
• Повреждение данных после аварийного отключения --- в журнале будут сообщения о неконсистентности. В этом случае может потребоваться восстановление из резервной копии (см. раздел Резервное копирование).

Обработчик Celery не выполняет задачи

Признаки: задачи поиска по реестру не запускаются, в пользовательском интерфейсе поиск «зависает» на нулевом прогрессе.

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

# Проверить, что контейнер работает
ssh alfa "docker ps | grep celery"

# Посмотреть журнал
ssh alfa "docker logs sdm_celery_worker --tail 50"

# Проверить очередь Redis
ssh alfa "docker exec sdm_redis redis-cli llen celery"

Решение:

Перезапустить обработчик:

ssh alfa "cd /opt/alfa && docker compose restart celery-worker"

Если в журнале видны ошибки подключения к MongoDB или Redis --- убедиться, что эти сервисы работают.