DevOpsTools/LogBoard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Добавлена полная документация проекта LogBoard+

Browse Source 
- Создан основной README.md с описанием проекта
- Добавлена подробная документация в папке docs/
- Создан файл LICENSE (MIT)
- Обновлен .gitignore
- Добавлена документация по безопасности с генерацией ключей
- Включены примеры конфигураций и устранение неполадок

Автор: Сергей Антропов
Сайт: https://devops.org.ru
This commit is contained in:
Сергей Антропов
2025-08-19 01:06:23 +03:00
parent 86a2c44333
commit 5c8efe2644
11 changed files with 4932 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

767
docs/troubleshooting.md Normal file
View File

@@ -0,0 +1,767 @@
# Устранение неполадок 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/ws/logs/test"
# Проверка логов приложения
make logs | grep -i websocket
# Проверка в браузере
# Открыть Developer Tools -> Console
```
#### Решения
1. **Проблема с прокси**
```nginx
# Настройка 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. **Проблема с токеном**
```javascript
// Проверка токена в WebSocket URL
const token = "your-valid-token";
const ws = new WebSocket(`ws://localhost:9001/ws/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/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/services" \
-H "Authorization: Bearer $TOKEN" | jq 'length'
```