409 lines
14 KiB
Markdown
409 lines
14 KiB
Markdown
# Документация LogBoard+
|
||
|
||
**Автор:** Сергей Антропов
|
||
**Сайт:** https://devops.org.ru
|
||
|
||
## Обзор
|
||
|
||
LogBoard+ - это современная веб-панель для мониторинга и просмотра логов Docker контейнеров в реальном времени. Приложение идеально подходит для локальной разработки, позволяя разработчикам всегда держать логи микросервисов перед глазами на втором мониторе.
|
||
|
||
### Идеально для локальной разработки
|
||
|
||
LogBoard+ особенно полезен для разработчиков, работающих с микросервисной архитектурой:
|
||
|
||
- **Второй монитор** - Держите логи всех микросервисов постоянно видимыми
|
||
- **Быстрая отладка** - Мгновенный доступ к логам без переключения между терминалами
|
||
- **Мониторинг в реальном времени** - Видите проблемы сразу, как они возникают
|
||
- **Централизованный просмотр** - Все логи в одном месте, а не в десятках терминалов
|
||
|
||
### Оптимизирован для Docker и Docker Compose
|
||
|
||
Если ваша инфраструктура основана на Docker и Docker Compose, LogBoard+ станет незаменимым инструментом:
|
||
|
||
- **Автоматическое обнаружение** всех проектов Docker Compose
|
||
- **Быстрый просмотр логов** всех контейнеров в проекте
|
||
- **Фильтрация по проектам** - легко переключаться между разными проектами
|
||
- **Multi-view режим** - одновременный просмотр логов нескольких контейнеров
|
||
- **Интеграция с Docker API** - прямая работа с контейнерами
|
||
|
||
### Производительность и удобство
|
||
|
||
Приложение предоставляет удобный веб-интерфейс для работы с логами микросервисов, поддерживает множественные проекты Docker Compose и включает в себя функции безопасности.
|
||
|
||
## Быстрый старт
|
||
|
||
### Вариант A: Разработка
|
||
|
||
```bash
|
||
# Клонирование репозитория
|
||
git clone <repository-url>
|
||
cd logboard
|
||
|
||
# Настройка переменных окружения
|
||
make setup
|
||
|
||
# Запуск приложения
|
||
make up
|
||
```
|
||
|
||
### Вариант B: Продакшен (пример docker-compose-prod.yaml)
|
||
|
||
```yaml
|
||
services:
|
||
logboard:
|
||
image: docker.io/inecs/logboard:v1
|
||
container_name: logboard
|
||
environment:
|
||
LOGBOARD_PORT: "9001"
|
||
LOGBOARD_TAIL: "500"
|
||
LOGBOARD_USER: "admin"
|
||
LOGBOARD_PASS: "admin"
|
||
LOGBOARD_SNAPSHOT_DIR: "/app/snapshots"
|
||
LOGBOARD_STATIC_DIR: "/app/static"
|
||
LOGBOARD_INDEX_HTML: "./app/templates/index.html"
|
||
TZ_TS: "Europe/Moscow"
|
||
DOCKER_HOST: "unix:///var/run/docker.sock"
|
||
SECRET_KEY: "your-secret-key-here"
|
||
ENCRYPTION_KEY: "your-encryption-key-here"
|
||
LOG_LEVEL: "INFO"
|
||
LOG_FORMAT: "json"
|
||
DEBUG_MODE: "false"
|
||
AUTH_ENABLED: "true"
|
||
SESSION_TIMEOUT: "3600"
|
||
ports:
|
||
- "9001:9001"
|
||
volumes:
|
||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||
- ./snapshots:/app/snapshots
|
||
restart: unless-stopped
|
||
user: 0:0
|
||
```
|
||
|
||
После запуска интерфейс доступен по адресу: http://localhost:9001
|
||
|
||
Учетные данные по умолчанию:
|
||
- Пользователь: `admin`
|
||
- Пароль: `admin` (обязательно измените в продакшене)
|
||
|
||
## Документация
|
||
|
||
### Основные разделы
|
||
|
||
1. **[Установка и настройка](./installation.md)**
|
||
- Предварительные требования
|
||
- Пошаговая установка
|
||
- Настройка для продакшена
|
||
- Устранение проблем установки
|
||
|
||
2. **[Структура проекта](./project-structure.md)**
|
||
- Архитектура приложения
|
||
- Описание модулей
|
||
- Принципы организации
|
||
- Добавление новых модулей
|
||
|
||
3. **[API Документация](./api.md)**
|
||
- REST API endpoints
|
||
- WebSocket API
|
||
- Примеры использования
|
||
- Коды ошибок
|
||
|
||
4. **[WebSocket API](./websocket.md)**
|
||
- Подключение к WebSocket
|
||
- Real-time логи
|
||
- Обработка ошибок
|
||
- Лучшие практики
|
||
|
||
5. **[Конфигурация](./configuration.md)**
|
||
- Переменные окружения
|
||
- Настройка Docker
|
||
- Настройка безопасности
|
||
- Примеры конфигураций
|
||
|
||
6. **[Безопасность](./security.md)**
|
||
- Генерация ключей
|
||
- Аутентификация
|
||
- Настройка HTTPS
|
||
- Мониторинг безопасности
|
||
|
||
7. **[Устранение неполадок](./troubleshooting.md)**
|
||
- Общие проблемы
|
||
- Проблемы с Docker
|
||
- Проблемы с аутентификацией
|
||
- Диагностика и логи
|
||
|
||
### Дополнительные ресурсы
|
||
|
||
- **[README.md](../README.md)** - Основная документация проекта
|
||
- **[env.example](../env.example)** - Пример конфигурации
|
||
- **[Makefile](../Makefile)** - Команды управления
|
||
|
||
## Скриншоты
|
||
|
||
### Страница входа
|
||
| Светлая тема | Темная тема |
|
||
|--------------|-------------|
|
||
|  |  |
|
||
|
||
### Основной интерфейс
|
||
| Светлая тема | Темная тема |
|
||
|--------------|-------------|
|
||
|  |  |
|
||
|
||
### Multi-view режим
|
||
|
||
|
||
### Карточки контейнеров
|
||
|
||
|
||
### Проекты
|
||
|
||
|
||
### Настройки
|
||
|
||
|
||
### Сворачиваемая боковая панель
|
||
|
||
|
||
### Справка
|
||
|
||
|
||
### Страницы ошибок
|
||
|
||
|
||
## Архитектура
|
||
|
||
### Технологический стек
|
||
|
||
- **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
|
||
|
||
### Основные возможности
|
||
|
||
- **Просмотр логов в реальном времени** - WebSocket соединения для live-логов
|
||
- **Поддержка множественных проектов** - Фильтрация по проектам Docker Compose
|
||
- **Безопасность** - JWT аутентификация и авторизация
|
||
- **Фильтрация контейнеров** - Исключение проблемных контейнеров
|
||
- **Снимки логов** - Сохранение логов в файлы для анализа
|
||
- **Статистика** - Анализ уровней логирования
|
||
- **Адаптивный интерфейс** - Поддержка светлой и темной темы
|
||
|
||
## API Endpoints
|
||
|
||
### REST API
|
||
|
||
#### Аутентификация
|
||
- `POST /api/auth/login` - Вход в систему
|
||
- `POST /api/auth/logout` - Выход из системы
|
||
- `GET /api/auth/me` - Информация о текущем пользователе
|
||
|
||
#### Контейнеры и сервисы
|
||
- `GET /api/containers/services` - Список контейнеров
|
||
- `GET /api/containers/projects` - Список проектов Docker Compose
|
||
- `GET /api/logs/{container_id}` - Логи контейнера
|
||
- `GET /api/logs/stats/{container_id}` - Статистика логов
|
||
|
||
#### Управление
|
||
- `GET /api/settings` - Настройки приложения
|
||
- `GET /api/containers/excluded` - Список исключенных контейнеров
|
||
- `POST /api/containers/excluded` - Обновление исключенных контейнеров
|
||
- `POST /api/logs/snapshot` - Создание снимка логов
|
||
|
||
### WebSocket API
|
||
|
||
- `ws://host:port/api/websocket/logs/{container_id}` - Логи отдельного контейнера
|
||
- `ws://host:port/api/websocket/fan/{service_name}` - Логи сервиса (все реплики)
|
||
- `ws://host:port/api/websocket/fan_group` - Логи группы сервисов
|
||
|
||
## Конфигурация
|
||
|
||
### Основные переменные окружения
|
||
|
||
| Переменная | Описание | По умолчанию |
|
||
|------------|----------|--------------|
|
||
| `LOGBOARD_PORT` | Порт веб-интерфейса | `9001` |
|
||
| `LOGBOARD_USER` | Имя пользователя | `admin` |
|
||
| `LOGBOARD_PASS` | Пароль пользователя | `admin` |
|
||
| `LOGBOARD_TAIL` | Количество строк логов | `500` |
|
||
| `SECRET_KEY` | Секретный ключ JWT | `your-secret-key-here` |
|
||
|
||
### Настройка проектов
|
||
|
||
```bash
|
||
# Один проект
|
||
COMPOSE_PROJECT_NAME=myproject
|
||
|
||
# Несколько проектов
|
||
LOGBOARD_PROJECTS=project1,project2,project3
|
||
```
|
||
|
||
## Управление
|
||
|
||
### Команды 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. **Измените пароли по умолчанию**
|
||
2. **Настройте секретные ключи**
|
||
3. **Используйте HTTPS**
|
||
4. **Ограничьте доступ к Docker socket**
|
||
5. **Настройте файрвол**
|
||
|
||
### Аутентификация
|
||
|
||
Приложение использует JWT токены для аутентификации:
|
||
- Токены хранятся в HTTP-only cookies
|
||
- Время жизни токена настраивается через `SESSION_TIMEOUT`
|
||
- Поддерживается автоматическое обновление токенов
|
||
|
||
## Мониторинг и логирование
|
||
|
||
### Health Check
|
||
|
||
```bash
|
||
curl http://localhost:9001/healthz
|
||
# Ответ: ok
|
||
```
|
||
|
||
### Логирование
|
||
|
||
Приложение логирует:
|
||
- Ошибки подключения к Docker
|
||
- Проблемы с контейнерами
|
||
- Ошибки аутентификации
|
||
- WebSocket соединения
|
||
|
||
## Примеры использования
|
||
|
||
### Python
|
||
|
||
```python
|
||
import requests
|
||
|
||
# Аутентификация
|
||
response = requests.post('http://localhost:9001/api/auth/login', json={
|
||
'username': 'admin',
|
||
'password': 'your-password'
|
||
})
|
||
token = response.json()['access_token']
|
||
|
||
# Получение списка контейнеров
|
||
headers = {'Authorization': f'Bearer {token}'}
|
||
containers = requests.get('http://localhost:9001/api/services', headers=headers).json()
|
||
```
|
||
|
||
### JavaScript
|
||
|
||
```javascript
|
||
// Получение токена
|
||
const response = await fetch('http://localhost:9001/api/auth/login', {
|
||
method: 'POST',
|
||
headers: {'Content-Type': 'application/json'},
|
||
body: JSON.stringify({
|
||
username: 'admin',
|
||
password: 'your-password'
|
||
})
|
||
});
|
||
const {access_token} = await response.json();
|
||
|
||
// WebSocket подключение
|
||
const ws = new WebSocket(`ws://localhost:9001/ws/logs/container-id?token=${access_token}`);
|
||
```
|
||
|
||
### cURL
|
||
|
||
```bash
|
||
# Получение токена
|
||
TOKEN=$(curl -s -X POST "http://localhost:9001/api/auth/login" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"username":"admin","password":"your-password"}' \
|
||
| jq -r '.access_token')
|
||
|
||
# Получение списка контейнеров
|
||
curl -X GET "http://localhost:9001/api/services" \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
## Устранение неполадок
|
||
|
||
### Частые проблемы
|
||
|
||
1. **Ошибка подключения к Docker**
|
||
```bash
|
||
sudo usermod -aG docker $USER
|
||
newgrp docker
|
||
```
|
||
|
||
2. **Контейнеры не отображаются**
|
||
```bash
|
||
docker ps --format "table {{.Names}}\t{{.Labels}}"
|
||
```
|
||
|
||
3. **Ошибки аутентификации**
|
||
```bash
|
||
make env-check
|
||
```
|
||
|
||
### Диагностика
|
||
|
||
```bash
|
||
# Проверка статуса
|
||
make status
|
||
|
||
# Просмотр логов
|
||
make logs
|
||
|
||
# Проверка конфигурации
|
||
make validate
|
||
```
|
||
|
||
## Поддержка
|
||
|
||
- **Автор:** Сергей Антропов
|
||
- **Сайт:** https://devops.org.ru
|
||
- **Issues:** Создавайте issues в репозитории проекта
|
||
- **Документация:** [./docs/](./docs/)
|
||
|
||
## Лицензия
|
||
|
||
MIT License - см. файл [LICENSE](../LICENSE) для подробностей.
|
||
|
||
---
|
||
|
||
**LogBoard+** - Удобный просмотр логов микросервисов в реальном времени.
|