logboard/docs/troubleshooting.md

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

Автор: Сергей Антропов
Сайт: https://devops.org.ru

Содержание

1. Общие проблемы
2. Проблемы с Docker
3. Проблемы с аутентификацией
4. Проблемы с WebSocket
5. Проблемы с производительностью
6. Проблемы с сетью
7. Диагностика и логи

Общие проблемы

Приложение не запускается

Симптомы

• Ошибка при выполнении make up
• Контейнер не стартует
• Ошибки в логах Docker

Диагностика

# Проверка статуса контейнеров
make status

# Просмотр логов
make logs

# Проверка конфигурации
make validate

# Проверка переменных окружения
make env-check

Решения

1. Проблема с портом

   # Проверка занятости порта
   netstat -tlnp | grep 9001
   
   # Изменение порта в .env
   LOGBOARD_PORT=9002
   

2. Проблема с правами доступа

   # Проверка прав на директории
   ls -la snapshots/
   
   # Установка правильных прав
   chmod 755 snapshots/
   chown $USER:$USER snapshots/
   

3. Проблема с Docker

   # Проверка статуса Docker
   sudo systemctl status docker
   
   # Перезапуск Docker
   sudo systemctl restart docker
   

Ошибки конфигурации

Симптомы

• Ошибки при парсинге переменных окружения
• Неправильная работа функций
• Ошибки в логах приложения

Диагностика

# Проверка синтаксиса .env файла
cat .env | grep -v "^#" | grep -v "^$"

# Проверка обязательных переменных
grep -E "^(LOGBOARD_PASS|SECRET_KEY|ENCRYPTION_KEY)=" .env

Решения

1. Отсутствуют обязательные переменные

   # Создание .env из примера
   make setup
   
   # Редактирование .env
   nano .env
   

2. Неправильный формат переменных

   # Проверка формата
   # Переменные должны быть в формате KEY=value
   # Без пробелов вокруг знака равенства
   

Проблемы с Docker

Ошибка подключения к Docker socket

Симптомы

• Ошибка "Permission denied" при доступе к Docker
• Контейнеры не отображаются в интерфейсе
• Ошибки в логах приложения

Диагностика

# Проверка прав доступа к Docker socket
ls -la /var/run/docker.sock

# Проверка группы docker
getent group docker

# Проверка пользователя в группе
groups $USER

Решения

1. Добавление пользователя в группу docker

   # Создание группы docker (если не существует)
   sudo groupadd docker
   
   # Добавление пользователя в группу
   sudo usermod -aG docker $USER
   
   # Перезагрузка группы
   newgrp docker
   
   # Проверка
   docker ps
   

2. Изменение прав на Docker socket

   # Временное решение (не рекомендуется для продакшена)
   sudo chmod 666 /var/run/docker.sock
   

3. Перезапуск Docker daemon

   sudo systemctl restart docker
   

Контейнеры не отображаются

Симптомы

• Пустой список контейнеров в интерфейсе
• Ошибки при получении списка контейнеров
• Контейнеры видны в docker ps, но не в LogBoard+

Диагностика

# Проверка списка контейнеров
docker ps -a

# Проверка меток контейнеров
docker inspect <container_id> | grep -A 10 "Labels"

# Проверка фильтров проектов
echo $COMPOSE_PROJECT_NAME
echo $LOGBOARD_PROJECTS

Решения

1. Проблема с фильтрами проектов

   # Очистка фильтров в .env
   # COMPOSE_PROJECT_NAME=
   # LOGBOARD_PROJECTS=
   
   # Перезапуск приложения
   make restart
   

2. Проблема с метками контейнеров

   # Проверка меток Docker Compose
   docker inspect <container_id> | grep "com.docker.compose"
   
   # Перезапуск контейнеров с правильными метками
   docker compose down && docker compose up -d
   

3. Проблема с исключенными контейнерами

   # Проверка файла исключений
   cat excluded_containers.json
   
   # Очистка исключений
   echo '{"excluded_containers": []}' > excluded_containers.json
   

Ошибки получения логов

Симптомы

• Логи не загружаются
• Ошибки при запросе логов
• Пустые логи в интерфейсе

Диагностика

# Проверка логов контейнера напрямую
docker logs <container_id>

# Проверка статуса контейнера
docker inspect <container_id> | grep -A 5 "State"

# Проверка прав доступа к логам
docker logs <container_id> 2>&1

Решения

1. Контейнер остановлен

   # Запуск контейнера
   docker start <container_id>
   
   # Проверка статуса
   docker ps
   

2. Проблема с драйвером логирования

   # Проверка драйвера логирования
   docker inspect <container_id> | grep "LogDriver"
   
   # Изменение драйвера логирования
   docker run --log-driver=json-file ...
   

3. Проблема с размером логов

   # Очистка логов контейнера
   docker logs --since 1h <container_id>
   
   # Ограничение размера логов
   docker run --log-opt max-size=10m ...
   

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

Ошибка входа в систему

Симптомы

• Не удается войти в систему
• Ошибка "Неверное имя пользователя или пароль"
• Бесконечная перезагрузка страницы входа

Диагностика

# Проверка переменных аутентификации
grep -E "^(LOGBOARD_USER|LOGBOARD_PASS)=" .env

# Проверка API аутентификации
curl -X POST "http://localhost:9001/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

Решения

1. Неправильные учетные данные

   # Проверка и исправление .env
   LOGBOARD_USER=admin
   LOGBOARD_PASS=your-correct-password
   
   # Перезапуск приложения
   make restart
   

2. Проблема с JWT токенами

   # Проверка SECRET_KEY
   grep "SECRET_KEY" .env
   
   # Генерация нового ключа
   openssl rand -hex 32
   
   # Обновление .env
   SECRET_KEY=your-new-secret-key
   

3. Проблема с cookies

   # Очистка cookies браузера
   # Или использование режима инкогнито
   

Ошибки авторизации API

Симптомы

• Ошибка 401 при запросах к API
• "Требуется авторизация" в ответах
• Не работает WebSocket API

Диагностика

# Проверка токена
curl -X GET "http://localhost:9001/api/auth/me" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Проверка времени жизни токена
echo $SESSION_TIMEOUT

Решения

1. Истекший токен

   # Увеличение времени жизни токена
   SESSION_TIMEOUT=7200  # 2 часа
   
   # Перезапуск приложения
   make restart
   

2. Неправильный формат токена

   # Получение нового токена
   curl -X POST "http://localhost:9001/api/auth/login" \
     -H "Content-Type: application/json" \
     -d '{"username":"admin","password":"your-password"}'
   

3. Проблема с часовыми поясами

   # Установка правильного часового пояса
   TZ_TS=UTC
   
   # Перезапуск приложения
   make restart
   

Проблемы с WebSocket

WebSocket соединения не устанавливаются

Симптомы

• Ошибки WebSocket в консоли браузера
• Логи не обновляются в реальном времени
• Ошибка "WebSocket connection failed"

Диагностика

# Проверка WebSocket endpoint
curl -I "http://localhost:9001/ws/logs/test"

# Проверка логов приложения
make logs | grep -i websocket

# Проверка в браузере
# Открыть Developer Tools -> Console

Решения

1. Проблема с прокси

   # Настройка Nginx для WebSocket
   location /ws/ {
       proxy_pass http://localhost:9001;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       proxy_set_header Host $host;
   }
   

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

   // Проверка токена в WebSocket URL
   const token = "your-valid-token";
   const ws = new WebSocket(`ws://localhost:9001/ws/logs/container-id?token=${token}`);
   

3. Проблема с CORS

   # Добавление CORS заголовков в конфигурацию
   # (если используется)
   

WebSocket соединения разрываются

Симптомы

• Соединения закрываются через некоторое время
• Ошибки "Connection closed unexpectedly"
• Логи перестают обновляться

Диагностика

# Проверка таймаутов
grep -E "TIMEOUT|timeout" .env

# Проверка нагрузки на систему
top
free -h

Решения

1. Увеличение таймаутов

   # Увеличение таймаутов в .env
   CONNECTION_TIMEOUT=120
   READ_TIMEOUT=300
   
   # Перезапуск приложения
   make restart
   

2. Проблема с нагрузкой

   # Ограничение количества соединений
   MAX_CONNECTIONS=50
   
   # Увеличение ресурсов контейнера
   # В docker-compose.yml
   deploy:
     resources:
       limits:
         memory: 1G
         cpus: '1.0'
   

3. Проблема с сетевыми таймаутами

   # Настройка keepalive
   # В конфигурации прокси или балансировщика
   

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

Медленная загрузка логов

Симптомы

• Долгая загрузка страниц
• Медленное получение логов
• Высокая нагрузка на CPU

Диагностика

# Проверка ресурсов системы
htop
iostat 1
df -h

# Проверка настроек производительности
grep -E "TAIL|INTERVAL" .env

Решения

1. Оптимизация настроек

   # Уменьшение количества строк логов
   LOGBOARD_TAIL=100
   
   # Увеличение интервала обновления
   LOGBOARD_AJAX_UPDATE_INTERVAL=5000
   
   # Перезапуск приложения
   make restart
   

2. Ограничение ресурсов

   # Настройка лимитов в docker-compose.yml
   deploy:
     resources:
       limits:
         memory: 512M
         cpus: '0.5'
       reservations:
         memory: 256M
         cpus: '0.25'
   

3. Оптимизация Docker

   # Очистка неиспользуемых ресурсов
   docker system prune -f
   
   # Ограничение логов контейнеров
   docker run --log-opt max-size=10m --log-opt max-file=3 ...
   

Высокое потребление памяти

Симптомы

• Контейнер LogBoard+ потребляет много памяти
• Ошибки "Out of memory"
• Медленная работа системы

Диагностика

# Проверка использования памяти
docker stats logboard

# Проверка процессов в контейнере
docker exec logboard ps aux

# Проверка логов приложения
make logs | grep -i memory

Решения

1. Ограничение памяти

   # Установка лимитов памяти
   # В docker-compose.yml
   deploy:
     resources:
       limits:
         memory: 512M
   

2. Оптимизация кода

   # Уменьшение размера буферов
   # Уменьшение количества одновременных соединений
   MAX_CONNECTIONS=50
   

3. Очистка кэша

   # Перезапуск приложения
   make restart
   
   # Очистка Docker кэша
   docker system prune -f
   

Проблемы с сетью

Недоступность веб-интерфейса

Симптомы

• Не удается открыть веб-интерфейс
• Ошибка "Connection refused"
• Таймаут при подключении

Диагностика

# Проверка статуса контейнера
make status

# Проверка портов
netstat -tlnp | grep 9001

# Проверка доступности
curl -I http://localhost:9001

Решения

1. Проблема с портом

   # Проверка занятости порта
   sudo lsof -i :9001
   
   # Изменение порта
   LOGBOARD_PORT=9002
   make restart
   

2. Проблема с сетевыми настройками

   # Проверка Docker сетей
   docker network ls
   
   # Пересоздание сетей
   docker compose down
   docker compose up -d
   

3. Проблема с файрволом

   # Проверка файрвола
   sudo ufw status
   
   # Разрешение порта
   sudo ufw allow 9001
   

Проблемы с внешним доступом

Симптомы

• Доступ только с localhost
• Не работает с внешним IP
• Проблемы с reverse proxy

Диагностика

# Проверка привязки к интерфейсам
netstat -tlnp | grep 9001

# Проверка конфигурации Docker
docker inspect logboard | grep -A 10 "NetworkSettings"

Решения

1. Настройка привязки к интерфейсам

   # В docker-compose.yml
   ports:
     - "0.0.0.0:9001:9001"
   

2. Настройка reverse proxy

   # Nginx конфигурация
   location / {
       proxy_pass http://localhost:9001;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
   }
   

3. Настройка файрвола

   # Разрешение внешнего доступа
   sudo ufw allow from 192.168.1.0/24 to any port 9001
   

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

Просмотр логов приложения

# Логи в реальном времени
make logs -f

# Логи с фильтрацией
make logs | grep ERROR

# Логи последних 100 строк
make logs | tail -100

Просмотр логов Docker

# Логи контейнера LogBoard+
docker logs logboard

# Логи с временными метками
docker logs -t logboard

# Логи последних 50 строк
docker logs --tail 50 logboard

Проверка состояния системы

# Статус сервисов
make status

# Использование ресурсов
docker stats logboard

# Информация о контейнере
docker inspect logboard

Отладка API

# Проверка health check
curl http://localhost:9001/healthz

# Проверка аутентификации
curl -X POST "http://localhost:9001/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

# Проверка API с токеном
TOKEN="your-token"
curl -X GET "http://localhost:9001/api/services" \
  -H "Authorization: Bearer $TOKEN"

Создание отчета о проблеме

# Создание диагностического отчета
cat > diagnostic_report.txt << EOF
=== LogBoard+ Diagnostic Report ===
Date: $(date)
Version: 1.0.0

=== System Information ===
OS: $(uname -a)
Docker: $(docker --version)
Docker Compose: $(docker compose version)

=== LogBoard+ Status ===
$(make status)

=== Configuration ===
$(grep -v "^#" .env | grep -v "^$")

=== Recent Logs ===
$(make logs | tail -50)

=== Docker Information ===
$(docker inspect logboard | jq '.[] | {State: .State, NetworkSettings: .NetworkSettings}')

=== System Resources ===
$(free -h)
$(df -h /)
EOF

echo "Diagnostic report saved to diagnostic_report.txt"

Частые команды для диагностики

# Быстрая диагностика
make env-check && make validate && make status

# Проверка подключения к Docker
docker ps

# Проверка доступности API
curl -s http://localhost:9001/healthz

# Проверка аутентификации
curl -s -X POST "http://localhost:9001/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq .

# Проверка списка контейнеров (требует токен)
TOKEN=$(curl -s -X POST "http://localhost:9001/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r '.access_token')
curl -s -X GET "http://localhost:9001/api/services" \
  -H "Authorization: Bearer $TOKEN" | jq 'length'