logboard/docs/troubleshooting.md

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

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

## Содержание

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

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

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

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

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

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

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

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

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

#### Решения

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

2. **Проблема с правами доступа**
   ```bash
   # Проверка прав на директории
   ls -la snapshots/
   
   # Установка правильных прав
   chmod 755 snapshots/
   chown $USER:$USER snapshots/
   ```

3. **Проблема с Docker**
   ```bash
   # Проверка статуса Docker
   sudo systemctl status docker
   
   # Перезапуск Docker
   sudo systemctl restart docker
   ```

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

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

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

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

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

#### Решения

1. **Отсутствуют обязательные переменные**
   ```bash
   # Создание .env из примера
   make setup
   
   # Редактирование .env
   nano .env
   ```

2. **Неправильный формат переменных**
   ```bash
   # Проверка формата
   # Переменные должны быть в формате KEY=value
   # Без пробелов вокруг знака равенства
   ```

## Проблемы с Docker

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

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

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

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

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

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

#### Решения

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

2. **Изменение прав на Docker socket**
   ```bash
   # Временное решение (не рекомендуется для продакшена)
   sudo chmod 666 /var/run/docker.sock
   ```

3. **Перезапуск Docker daemon**
   ```bash
   sudo systemctl restart docker
   ```

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

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

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

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

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

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

#### Решения

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

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

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

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

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

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

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

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

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

#### Решения

1. **Контейнер остановлен**
   ```bash
   # Запуск контейнера
   docker start <container_id>
   
   # Проверка статуса
   docker ps
   ```

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

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

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

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

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

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

```bash
# Проверка переменных аутентификации
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. **Неправильные учетные данные**
   ```bash
   # Проверка и исправление .env
   LOGBOARD_USER=admin
   LOGBOARD_PASS=your-correct-password
   
   # Перезапуск приложения
   make restart
   ```

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

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

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

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

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

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

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

#### Решения

1. **Истекший токен**
   ```bash
   # Увеличение времени жизни токена
   SESSION_TIMEOUT=7200  # 2 часа
   
   # Перезапуск приложения
   make restart
   ```

2. **Неправильный формат токена**
   ```bash
   # Получение нового токена
   curl -X POST "http://localhost:9001/api/auth/login" \
     -H "Content-Type: application/json" \
     -d '{"username":"admin","password":"your-password"}'
   ```

3. **Проблема с часовыми поясами**
   ```bash
   # Установка правильного часового пояса
   TZ_TS=UTC
   
   # Перезапуск приложения
   make restart
   ```

## Проблемы с WebSocket

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

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

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

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

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

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

#### Решения

1. **Проблема с прокси**
   ```nginx
   # Настройка Nginx для WebSocket с корректными путями API
   location /api/websocket/ {
       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. **Проблема с токеном**
   ```javascript
   // Проверка токена в WebSocket URL
   const token = "your-valid-token";
   const ws = new WebSocket(`ws://localhost:9001/api/websocket/logs/container-id?token=${token}`);
   ```

3. **Проблема с CORS**
   ```bash
   # Добавление CORS заголовков в конфигурацию
   # (если используется)
   ```

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

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

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

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

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

#### Решения

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

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

3. **Проблема с сетевыми таймаутами**
   ```bash
   # Настройка keepalive
   # В конфигурации прокси или балансировщика
   ```

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

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

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

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

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

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

#### Решения

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

2. **Ограничение ресурсов**
   ```bash
   # Настройка лимитов в docker-compose.yml
   deploy:
     resources:
       limits:
         memory: 512M
         cpus: '0.5'
       reservations:
         memory: 256M
         cpus: '0.25'
   ```

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

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

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

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

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

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

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

#### Решения

1. **Ограничение памяти**
   ```bash
   # Установка лимитов памяти
   # В docker-compose.yml
   deploy:
     resources:
       limits:
         memory: 512M
   ```

2. **Оптимизация кода**
   ```bash
   # Уменьшение размера буферов
   # Уменьшение количества одновременных соединений
   MAX_CONNECTIONS=50
   ```

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

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

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

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

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

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

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

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

#### Решения

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

2. **Проблема с сетевыми настройками**
   ```bash
   # Проверка Docker сетей
   docker network ls
   
   # Пересоздание сетей
   docker compose down
   docker compose up -d
   ```

3. **Проблема с файрволом**
   ```bash
   # Проверка файрвола
   sudo ufw status
   
   # Разрешение порта
   sudo ufw allow 9001
   ```

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

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

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

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

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

#### Решения

1. **Настройка привязки к интерфейсам**
   ```yaml
   # В docker-compose.yml
   ports:
     - "0.0.0.0:9001:9001"
   ```

2. **Настройка reverse proxy**
   ```nginx
   # Nginx конфигурация
   location / {
       proxy_pass http://localhost:9001;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
   }
   ```

3. **Настройка файрвола**
   ```bash
   # Разрешение внешнего доступа
   sudo ufw allow from 192.168.1.0/24 to any port 9001
   ```

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

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

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

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

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

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

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

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

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

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

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

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

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

### Отладка API

```bash
# Проверка 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/containers/services" \
  -H "Authorization: Bearer $TOKEN"
```

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

```bash
# Создание диагностического отчета
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"
```

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

```bash
# Быстрая диагностика
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/containers/services" \
  -H "Authorization: Bearer $TOKEN" | jq 'length'
```