Добавлена полная документация проекта LogBoard+
- Создан основной README.md с описанием проекта - Добавлена подробная документация в папке docs/ - Создан файл LICENSE (MIT) - Обновлен .gitignore - Добавлена документация по безопасности с генерацией ключей - Включены примеры конфигураций и устранение неполадок Автор: Сергей Антропов Сайт: https://devops.org.ru
This commit is contained in:
Сергей Антропов
313
docs/index.md
Normal file
313
docs/index.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# Документация LogBoard+
|
||||
|
||||
**Автор:** Сергей Антропов
|
||||
**Сайт:** https://devops.org.ru
|
||||
|
||||
## Обзор
|
||||
|
||||
LogBoard+ - это современная веб-панель для мониторинга и просмотра логов Docker контейнеров в реальном времени. Приложение предоставляет удобный веб-интерфейс для работы с логами микросервисов, поддерживает множественные проекты Docker Compose и включает в себя функции безопасности.
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
### Установка
|
||||
|
||||
```bash
|
||||
# Клонирование репозитория
|
||||
git clone <repository-url>
|
||||
cd logboard
|
||||
|
||||
# Настройка переменных окружения
|
||||
make setup
|
||||
|
||||
# Запуск приложения
|
||||
make up
|
||||
```
|
||||
|
||||
### Доступ
|
||||
|
||||
- **URL:** http://localhost:9001
|
||||
- **Пользователь:** `admin`
|
||||
- **Пароль:** `admin` (обязательно измените в продакшене!)
|
||||
|
||||
## Документация
|
||||
|
||||
### Основные разделы
|
||||
|
||||
1. **[Установка и настройка](./installation.md)**
|
||||
- Предварительные требования
|
||||
- Пошаговая установка
|
||||
- Настройка для продакшена
|
||||
- Устранение проблем установки
|
||||
|
||||
2. **[API Документация](./api.md)**
|
||||
- REST API endpoints
|
||||
- WebSocket API
|
||||
- Примеры использования
|
||||
- Коды ошибок
|
||||
|
||||
3. **[WebSocket API](./websocket.md)**
|
||||
- Подключение к WebSocket
|
||||
- Real-time логи
|
||||
- Обработка ошибок
|
||||
- Лучшие практики
|
||||
|
||||
4. **[Конфигурация](./configuration.md)**
|
||||
- Переменные окружения
|
||||
- Настройка Docker
|
||||
- Настройка безопасности
|
||||
- Примеры конфигураций
|
||||
|
||||
5. **[Безопасность](./security.md)**
|
||||
- Генерация ключей
|
||||
- Аутентификация
|
||||
- Настройка HTTPS
|
||||
- Мониторинг безопасности
|
||||
|
||||
6. **[Устранение неполадок](./troubleshooting.md)**
|
||||
- Общие проблемы
|
||||
- Проблемы с Docker
|
||||
- Проблемы с аутентификацией
|
||||
- Диагностика и логи
|
||||
|
||||
### Дополнительные ресурсы
|
||||
|
||||
- **[README.md](../README.md)** - Основная документация проекта
|
||||
- **[env.example](../env.example)** - Пример конфигурации
|
||||
- **[Makefile](../Makefile)** - Команды управления
|
||||
|
||||
## Архитектура
|
||||
|
||||
### Технологический стек
|
||||
|
||||
- **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/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` |
|
||||
|
||||
### Настройка проектов
|
||||
|
||||
```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+** - Удобный просмотр логов микросервисов в реальном времени.
|
||||
Reference in New Issue
Block a user