# Устранение неполадок

> Устранение неполадок SecureBaseline Cloud - диагностика ошибок SSH-подключения, сканирования, заданий усиления и проблем с агентом на серверах

Source: https://opennix.org/docs/haas/troubleshooting/

## Обзор

Это руководство охватывает распространенные проблемы и их решения при использовании SecureBaseline Cloud.

## Навигация

Данное руководство доступно из любой страницы системы через меню помощи.

## Проблемы подключения

### Не удается подключиться к хосту

**Симптомы**: Хост показывает offline, SSH-подключение не удается

**Решения**:
1. Убедитесь, что хост запущен и доступен
2. Проверьте статус SSH-сервиса: `systemctl status sshd`
3. Проверьте фаервол: `sudo ufw status` или `sudo firewall-cmd --list-all`
4. Протестируйте подключение вручную: `ssh user@host`
5. Проверьте корректность SSH-учетных данных
6. Проверьте правильность SSH-порта (по умолчанию: 22)

### Ошибка SSH-аутентификации

**Симптомы**: Permission denied, authentication failure

**Решения**:
1. Проверьте корректность имени пользователя
2. Для аутентификации по паролю: проверьте правильность пароля
3. Для аутентификации по ключу: проверьте наличие публичного ключа в `~/.ssh/authorized_keys`
4. Проверьте конфигурацию SSH на предмет разрешения данного метода аутентификации
5. Убедитесь, что пользователь имеет доступ к shell
6. Проверьте `/var/log/auth.log` для деталей

### Ошибка проверки ключа хоста

**Симптомы**: Ошибка несоответствия ключа хоста

**Решения**:
1. Если хост был переустановлен, очистите старый ключ
2. Убедитесь, что вы подключаетесь к правильному серверу
3. Проверьте на предмет атаки man-in-the-middle

## Проблемы сканирования

### Сканирование зависло в Pending

**Симптомы**: Сканирование не запускается, остается в состоянии pending

**Решения**:
1. Проверьте работу сервиса worker
2. Проверьте подключение к Redis
3. Просмотрите логи worker на предмет ошибок
4. Перезапустите сервис worker при необходимости

### Сканирование завершилось с ошибкой

**Симптомы**: Сканирование показывает статус failed

**Решения**:
1. Проверьте SSH-подключение к хосту
2. Проверьте права sudo для пользователя сканирования
3. Проверьте дисковое пространство на целевом хосте
4. Просмотрите сообщение об ошибке сканирования
5. Убедитесь в доступности движка сканирования

### Низкий балл соответствия

**Симптомы**: Балл ниже ожидаемого

**Решения**:
1. Просмотрите проваленные правила
2. Проверьте соответствие профиля типу хоста
3. Убедитесь, что система не была недавно установлена
4. Запустите усиление и повторите сканирование
5. Документируйте ложноположительные срабатывания

### Отсутствуют результаты сканирования

**Симптомы**: Сканирование завершено, но результаты не показываются

**Решения**:
1. Обновите страницу
2. Проверьте, что статус сканирования "completed"
3. Проверьте подключение к базе данных
4. Просмотрите логи API на предмет ошибок

## Проблемы усиления

### Задание зависло в очереди

**Симптомы**: Задание не начинает выполняться

**Решения**:
1. Проверьте статус сервиса worker
2. Проверьте подключение к Redis
3. Проверьте настройку параллельности worker
4. Просмотрите логи worker
5. Перезапустите worker при необходимости

### Усиление завершилось с ошибкой

**Симптомы**: Задание показывает статус failed

**Решения**:
1. Просмотрите вывод Ansible на предмет ошибок
2. Используйте функцию AI-диагностики
3. Распространенные причины:
   - Потеря SSH-подключения
   - Отказ sudo
   - Недоступность репозитория пакетов
   - Диск заполнен
4. Исправьте проблему и повторите попытку

### Сервисы не работают после усиления

**Симптомы**: Приложение или сервис перестает работать

**Решения**:
1. Проверьте статус сервиса: `systemctl status <service>`
2. Просмотрите журнал: `journalctl -u <service>`
3. Определите, какое правило усиления повлияло на сервис
4. Откатите при необходимости (восстановите из резервной копии)
5. Документируйте исключение на будущее

### Блокировка SSH после усиления

**Симптомы**: Не удается подключиться по SSH после усиления

**Решения**:
1. Используйте консольный доступ (консоль облачного провайдера)
2. Загрузитесь в режиме восстановления
3. Восстановите конфигурацию SSH:
   ```bash
   # Распространенные исправления
   sed -i 's/PermitRootLogin no/PermitRootLogin yes/' /etc/ssh/sshd_config
   systemctl restart sshd
   ```
4. Рассмотрите исключение правил SSH

## Проблемы расписаний

### Расписание не выполняется

**Симптомы**: Запланированные задания не выполняются

**Решения**:
1. Убедитесь, что расписание включено
2. Проверьте корректность cron-выражения
3. Проверьте работу сервиса планировщика
4. Проверьте время/часовой пояс сервера
5. Просмотрите логи планировщика

### Неправильное время выполнения

**Симптомы**: Задания выполняются в неожиданное время

**Решения**:
1. Проверьте cron-выражение
2. Проверьте часовой пояс сервера
3. Cron использует локальное время сервера
4. Протестируйте с более простым выражением

## Проблемы интерфейса

### Страница не загружается

**Симптомы**: Пустая страница или бесконечная загрузка

**Решения**:
1. Обновите страницу
2. Очистите кэш браузера
3. Попробуйте другой браузер
4. Проверьте консоль браузера на предмет ошибок
5. Убедитесь, что сервис API работает

### Данные не обновляются

**Симптомы**: Отображаются устаревшие данные

**Решения**:
1. Нажмите кнопку обновления
2. Проверьте настройку автообновления
3. Проверьте сетевое подключение
4. Очистите кэш браузера

### Экспорт не работает

**Симптомы**: Загрузка CSV/JSON не удается

**Решения**:
1. Проверьте блокировщик всплывающих окон
2. Попробуйте другой браузер
3. Проверьте папку загрузок браузера
4. Убедитесь, что есть данные для экспорта

## Проблемы аутентификации

### Не удается войти

**Симптомы**: Вход не удается с корректными учетными данными

**Решения**:
1. Проверьте email и пароль
2. Проверьте, что аккаунт активен
3. Попробуйте сбросить пароль
4. Очистите cookies браузера
5. Проверьте статус сервиса API

### Сессия истекла

**Симптомы**: Внезапный выход из системы

**Решения**:
1. Войдите снова
2. Проверьте настройки истечения токена
3. Проверьте синхронизацию времени между клиентом и сервером
4. Просмотрите логи аутентификации

## Проблемы производительности

### Медленный ответ API

**Симптомы**: Страницы загружаются медленно

**Решения**:
1. Проверьте использование ресурсов сервера
2. Просмотрите производительность базы данных
3. Проверьте сетевую задержку
4. При необходимости скорректируйте лимит запросов
5. При необходимости масштабируйте ресурсы

### Задания обрабатываются медленно

**Симптомы**: Задания занимают слишком много времени

**Решения**:
1. Проверьте параллельность worker
2. Просмотрите использование ресурсов
3. Проверьте сеть до управляемых хостов
4. Рассмотрите масштабирование workers

## Проблемы AI

### AI не отвечает

**Симптомы**: Чат или диагностика не работают

**Решения**:
1. Проверьте, что конфигурация AI активна
2. Протестируйте подключение конфигурации
3. Проверьте валидность API-ключа
4. Проверьте доступ к Yandex Cloud
5. Просмотрите лимиты API

### Некачественные ответы AI

**Симптомы**: Бесполезные или некорректные ответы

**Решения**:
1. Переформулируйте вопрос четко
2. Предоставьте больше контекста
3. Попробуйте другую модель
4. Скорректируйте настройку temperature

## Получение помощи

### Диагностический инструмент must-gather

Самый быстрый способ собрать всю диагностическую информацию - инструмент `must-gather`, доступный на каждой VM SecureBaseline Cloud.

```bash
# Запуск на VM (использует DATABASE_URL из окружения)
/opt/haas/bin/must-gather

# Или с указанием URL базы данных и пути вывода
/opt/haas/bin/must-gather --db "postgres://haas:pass@localhost/haas?sslmode=disable" --output /tmp/diag.tar.gz

# Ограничение количества строк логов (по умолчанию: 1000)
/opt/haas/bin/must-gather --log-lines 500
```

Инструмент создает tar.gz архив, содержащий:

| Раздел | Содержимое |
|--------|------------|
| `system/info.json` | Hostname, ОС, CPU, версия, время сборки |
| `services/` | Статус systemd, docker ps, открытые порты, диск, память |
| `logs/` | Логи journalctl и docker для API, Worker, Vuls server, nginx |
| `config/` | Файлы окружения (секреты скрыты), конфигурация nginx |
| `scap/` | Версия SCAP-контента и список файлов |
| `database/stats.json` | Количество записей в таблицах, статусы хостов, неудачные задачи/сканирования (24ч), зависшие задачи, конфигурации LLM, последние сканирования и ошибки, размер БД |

Прикрепите архив при обращении в поддержку.

### Расположение логов

| Компонент | Расположение логов |
|-----------|-------------------|
| API | `journalctl -u haas-api` или `docker logs haas-api` |
| Worker | `journalctl -u haas-worker` или `docker logs haas-worker` |
| Vuls Server | `journalctl -u haas-vuls-server` или `docker logs haas-vuls-server` |
| Frontend | Консоль браузера (F12) |
| Database | Логи PostgreSQL |
| Nginx | `/var/log/nginx/access.log`, `/var/log/nginx/error.log` |

### Проверки состояния

Проверьте сервисы:

```bash
# API health
curl http://localhost:8080/healthz

# Readiness (проверяет БД и Redis)
curl http://localhost:8080/readyz

# Liveness
curl http://localhost:8080/livez

# Версия
curl http://localhost:8080/version
```

### Сообщение о проблемах

При сообщении о проблемах:

1. Запустите `must-gather` и прикрепите архив
2. Четко опишите проблему
3. Предоставьте шаги для воспроизведения
4. Опишите ожидаемое vs фактическое поведение

## Дополнительные материалы

- [Настройка SSH-учетных данных](/docs/haas/credentials/) - управление ключами и паролями для подключения к серверам
- [Усиление безопасности по CIS Benchmark](/docs/haas/hardening/) - применение правил CIS и диагностика ошибок Ansible-плейбуков
- [Обзор платформы SecureBaseline Cloud](/docs/haas/) - полный список возможностей и поддерживаемых операционных систем