Добавлена полная документация проекта LogBoard+
- Создан основной README.md с описанием проекта - Добавлена подробная документация в папке docs/ - Создан файл LICENSE (MIT) - Обновлен .gitignore - Добавлена документация по безопасности с генерацией ключей - Включены примеры конфигураций и устранение неполадок Автор: Сергей Антропов Сайт: https://devops.org.ru
This commit is contained in:
Сергей Антропов
385
README.md
Normal file
385
README.md
Normal file
@@ -0,0 +1,385 @@
|
||||
# LogBoard+
|
||||
|
||||
**Веб-панель для просмотра логов микросервисов**
|
||||
|
||||
[](https://www.python.org/)
|
||||
[](https://fastapi.tiangolo.com/)
|
||||
[](https://www.docker.com/)
|
||||
[](LICENSE)
|
||||
|
||||
**Автор:** Сергей Антропов
|
||||
**Сайт:** https://devops.org.ru
|
||||
**Версия:** 1.0.0
|
||||
|
||||
## Описание
|
||||
|
||||
LogBoard+ - это современная веб-панель для мониторинга и просмотра логов Docker контейнеров в реальном времени. Приложение предоставляет удобный веб-интерфейс для работы с логами микросервисов, поддерживает множественные проекты Docker Compose и включает в себя функции безопасности.
|
||||
|
||||
### Основные возможности
|
||||
|
||||
- **Просмотр логов в реальном времени** - WebSocket соединения для live-логов
|
||||
- **Поддержка множественных проектов** - Фильтрация по проектам Docker Compose
|
||||
- **Безопасность** - JWT аутентификация и авторизация
|
||||
- **Фильтрация контейнеров** - Исключение проблемных контейнеров
|
||||
- **Снимки логов** - Сохранение логов в файлы для анализа
|
||||
- **Статистика** - Анализ уровней логирования
|
||||
- **Адаптивный интерфейс** - Поддержка светлой и темной темы
|
||||
- **WebSocket API** - Для интеграции с внешними системами
|
||||
|
||||
## Скриншоты
|
||||
|
||||
### Светлая тема
|
||||
|
||||
|
||||
### Темная тема
|
||||
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
### Предварительные требования
|
||||
|
||||
- Docker Engine 20.10+
|
||||
- Docker Compose 2.0+
|
||||
- 1 GB RAM
|
||||
- 1 CPU core
|
||||
|
||||
### Установка и запуск
|
||||
|
||||
1. **Клонирование репозитория**
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd logboard
|
||||
```
|
||||
|
||||
2. **Настройка переменных окружения**
|
||||
```bash
|
||||
make setup
|
||||
# Отредактируйте файл .env под свои нужды
|
||||
```
|
||||
|
||||
3. **Запуск приложения**
|
||||
```bash
|
||||
make up
|
||||
```
|
||||
|
||||
4. **Доступ к веб-интерфейсу**
|
||||
```
|
||||
http://localhost:9001
|
||||
```
|
||||
|
||||
### Учетные данные по умолчанию
|
||||
|
||||
- **Пользователь:** `admin`
|
||||
- **Пароль:** `admin`
|
||||
|
||||
**Важно:** Обязательно измените пароль в продакшене!
|
||||
|
||||
## Архитектура
|
||||
|
||||
### Технологический стек
|
||||
|
||||
- **Backend:** Python 3.11, FastAPI 0.104.1
|
||||
- **Web Server:** Uvicorn с uvloop
|
||||
- **Docker Integration:** Docker SDK for Python 6.1.3
|
||||
- **Authentication:** JWT с PyJWT
|
||||
- **Frontend:** HTML5, CSS3, JavaScript (Vanilla)
|
||||
- **Templates:** Jinja2
|
||||
- **Containerization:** Docker, Docker Compose
|
||||
|
||||
### Структура проекта
|
||||
|
||||
```
|
||||
logboard/
|
||||
├── app.py # Основное приложение FastAPI
|
||||
├── docker-compose.yml # Конфигурация Docker Compose
|
||||
├── Dockerfile # Образ Docker
|
||||
├── requirements.txt # Зависимости Python
|
||||
├── Makefile # Команды управления
|
||||
├── env.example # Пример переменных окружения
|
||||
├── excluded_containers.json # Исключенные контейнеры
|
||||
├── templates/ # HTML шаблоны
|
||||
│ ├── index.html # Главная страница
|
||||
│ ├── login.html # Страница входа
|
||||
│ └── error.html # Страницы ошибок
|
||||
├── snapshots/ # Снимки логов
|
||||
└── screenshots/ # Скриншоты интерфейса
|
||||
```
|
||||
|
||||
## API Документация
|
||||
|
||||
### REST API
|
||||
|
||||
#### Аутентификация
|
||||
|
||||
- `POST /api/auth/login` - Вход в систему
|
||||
- `POST /api/auth/logout` - Выход из системы
|
||||
- `GET /api/auth/me` - Информация о текущем пользователе
|
||||
|
||||
#### Контейнеры и сервисы
|
||||
|
||||
- `GET /api/services` - Список контейнеров
|
||||
- `GET /api/projects` - Список проектов Docker Compose
|
||||
- `GET /api/logs/{container_id}` - Логи контейнера
|
||||
- `GET /api/logs/stats/{container_id}` - Статистика логов
|
||||
|
||||
#### Управление
|
||||
|
||||
- `GET /api/settings` - Настройки приложения
|
||||
- `GET /api/excluded-containers` - Список исключенных контейнеров
|
||||
- `POST /api/excluded-containers` - Обновление исключенных контейнеров
|
||||
- `POST /api/snapshot` - Создание снимка логов
|
||||
|
||||
### WebSocket API
|
||||
|
||||
- `ws://host:port/ws/logs/{container_id}` - Логи отдельного контейнера
|
||||
- `ws://host:port/ws/fan/{service_name}` - Логи сервиса (все реплики)
|
||||
- `ws://host:port/ws/fan_group` - Логи группы сервисов
|
||||
|
||||
## Конфигурация
|
||||
|
||||
### Переменные окружения
|
||||
|
||||
Основные настройки приложения:
|
||||
|
||||
| Переменная | Описание | По умолчанию |
|
||||
|------------|----------|--------------|
|
||||
| `LOGBOARD_PORT` | Порт веб-интерфейса | `9001` |
|
||||
| `LOGBOARD_USER` | Имя пользователя | `admin` |
|
||||
| `LOGBOARD_PASS` | Пароль пользователя | `admin` |
|
||||
| `LOGBOARD_TAIL` | Количество строк логов | `500` |
|
||||
| `SECRET_KEY` | Секретный ключ JWT | `your-secret-key-here` |
|
||||
|
||||
### Настройка проектов
|
||||
|
||||
Для фильтрации контейнеров по проектам Docker Compose:
|
||||
|
||||
```bash
|
||||
# Один проект
|
||||
COMPOSE_PROJECT_NAME=myproject
|
||||
|
||||
# Несколько проектов
|
||||
LOGBOARD_PROJECTS=project1,project2,project3
|
||||
```
|
||||
|
||||
### Исключение контейнеров
|
||||
|
||||
Создайте файл `excluded_containers.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"excluded_containers": [
|
||||
"noisy-container-1",
|
||||
"noisy-container-2"
|
||||
],
|
||||
"description": "Контейнеры с избыточным логированием"
|
||||
}
|
||||
```
|
||||
|
||||
## Управление
|
||||
|
||||
### Команды Makefile
|
||||
|
||||
```bash
|
||||
make help # Справка по командам
|
||||
make setup # Настройка переменных окружения
|
||||
make build # Сборка Docker образа
|
||||
make up # Запуск сервисов
|
||||
make down # Остановка сервисов
|
||||
make restart # Перезапуск сервисов
|
||||
make logs # Просмотр логов
|
||||
make clean # Очистка проекта
|
||||
make status # Статус сервисов
|
||||
make shell # Подключение к контейнеру
|
||||
```
|
||||
|
||||
### Docker Compose команды
|
||||
|
||||
```bash
|
||||
# Запуск
|
||||
docker compose up -d
|
||||
|
||||
# Остановка
|
||||
docker compose down
|
||||
|
||||
# Просмотр логов
|
||||
docker compose logs -f
|
||||
|
||||
# Пересборка
|
||||
docker compose build --no-cache
|
||||
```
|
||||
|
||||
## Безопасность
|
||||
|
||||
### Рекомендации для продакшена
|
||||
|
||||
1. **Измените пароли по умолчанию**
|
||||
```bash
|
||||
LOGBOARD_PASS=your-secure-password
|
||||
```
|
||||
|
||||
2. **Настройте секретные ключи**
|
||||
```bash
|
||||
SECRET_KEY=your-very-secure-secret-key
|
||||
ENCRYPTION_KEY=your-encryption-key
|
||||
```
|
||||
|
||||
3. **Используйте HTTPS**
|
||||
- Настройте reverse proxy (nginx, traefik)
|
||||
- Включите SSL/TLS сертификаты
|
||||
|
||||
4. **Ограничьте доступ к Docker socket**
|
||||
```bash
|
||||
# Создайте группу docker и добавьте пользователя
|
||||
sudo usermod -aG docker $USER
|
||||
```
|
||||
|
||||
5. **Настройте файрвол**
|
||||
```bash
|
||||
# Ограничьте доступ к порту 9001
|
||||
sudo ufw allow from 192.168.1.0/24 to any port 9001
|
||||
```
|
||||
|
||||
### Аутентификация
|
||||
|
||||
Приложение использует JWT токены для аутентификации:
|
||||
|
||||
- Токены хранятся в HTTP-only cookies
|
||||
- Время жизни токена настраивается через `SESSION_TIMEOUT`
|
||||
- Поддерживается автоматическое обновление токенов
|
||||
|
||||
## Мониторинг и логирование
|
||||
|
||||
### Health Check
|
||||
|
||||
```bash
|
||||
curl http://localhost:9001/healthz
|
||||
# Ответ: ok
|
||||
```
|
||||
|
||||
### Логирование
|
||||
|
||||
Приложение логирует:
|
||||
- Ошибки подключения к Docker
|
||||
- Проблемы с контейнерами
|
||||
- Ошибки аутентификации
|
||||
- WebSocket соединения
|
||||
|
||||
### Метрики
|
||||
|
||||
Доступные метрики:
|
||||
- Количество активных WebSocket соединений
|
||||
- Статистика по уровням логирования
|
||||
- Количество исключенных контейнеров
|
||||
- Время ответа API
|
||||
|
||||
## Разработка
|
||||
|
||||
### Локальная разработка
|
||||
|
||||
1. **Клонирование и настройка**
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd logboard
|
||||
make setup
|
||||
```
|
||||
|
||||
2. **Запуск в режиме разработки**
|
||||
```bash
|
||||
make up
|
||||
```
|
||||
|
||||
3. **Просмотр логов**
|
||||
```bash
|
||||
make logs
|
||||
```
|
||||
|
||||
### Тестирование
|
||||
|
||||
```bash
|
||||
# Проверка конфигурации
|
||||
make validate
|
||||
|
||||
# Проверка переменных окружения
|
||||
make env-check
|
||||
|
||||
# Тестирование API
|
||||
curl -X GET "http://localhost:9001/api/services" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
```
|
||||
|
||||
## Устранение неполадок
|
||||
|
||||
### Частые проблемы
|
||||
|
||||
1. **Ошибка подключения к Docker**
|
||||
```bash
|
||||
# Проверьте права доступа к Docker socket
|
||||
ls -la /var/run/docker.sock
|
||||
sudo usermod -aG docker $USER
|
||||
```
|
||||
|
||||
2. **Контейнеры не отображаются**
|
||||
```bash
|
||||
# Проверьте фильтры проектов
|
||||
docker ps --format "table {{.Names}}\t{{.Labels}}"
|
||||
```
|
||||
|
||||
3. **Ошибки аутентификации**
|
||||
```bash
|
||||
# Проверьте переменные окружения
|
||||
make env-check
|
||||
```
|
||||
|
||||
4. **WebSocket соединения не работают**
|
||||
```bash
|
||||
# Проверьте настройки прокси
|
||||
# Убедитесь, что WebSocket поддерживается
|
||||
```
|
||||
|
||||
### Логи и отладка
|
||||
|
||||
```bash
|
||||
# Просмотр логов приложения
|
||||
make logs
|
||||
|
||||
# Подключение к контейнеру
|
||||
make shell
|
||||
|
||||
# Проверка статуса
|
||||
make status
|
||||
```
|
||||
|
||||
## Лицензия
|
||||
|
||||
MIT License - см. файл [LICENSE](LICENSE) для подробностей.
|
||||
|
||||
## Поддержка
|
||||
|
||||
- **Автор:** Сергей Антропов
|
||||
- **Сайт:** https://devops.org.ru
|
||||
- **Issues:** Создавайте issues в репозитории проекта
|
||||
- **Документация:** [./docs/](./docs/)
|
||||
|
||||
## Вклад в проект
|
||||
|
||||
1. Fork репозитория
|
||||
2. Создайте feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Commit изменения (`git commit -m 'Add amazing feature'`)
|
||||
4. Push в branch (`git push origin feature/amazing-feature`)
|
||||
5. Откройте Pull Request
|
||||
|
||||
## Changelog
|
||||
|
||||
### v1.0.0 (2024-01-XX)
|
||||
- Первый релиз LogBoard+
|
||||
- Поддержка множественных проектов Docker Compose
|
||||
- JWT аутентификация
|
||||
- WebSocket API для live-логов
|
||||
- Адаптивный веб-интерфейс
|
||||
- Система исключения контейнеров
|
||||
- Снимки логов
|
||||
- Статистика логирования
|
||||
|
||||
---
|
||||
|
||||
**LogBoard+** - Удобный просмотр логов микросервисов в реальном времени.
|
||||
Reference in New Issue
Block a user