logboard/docs/remote-clients.md

Удаленные клиенты LogBoard

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

Обзор

LogBoard поддерживает работу с удаленными клиентами, которые могут отправлять логи с других серверов в центральный LogBoard сервер. Это позволяет централизованно собирать и анализировать логи с множества серверов.

Архитектура

┌─────────────────┐    HTTP/JSON    ┌─────────────────┐
│   Server A      │ ──────────────► │  LogBoard       │
│  (Client)       │                 │  Server         │
│                 │                 │                 │
│ ┌─────────────┐ │                 │ ┌─────────────┐ │
│ │LogBoard     │ │                 │ │API          │ │
│ │Client       │ │                 │ │Endpoint     │ │
│ │Container    │ │                 │ │/logs/remote │ │
│ └─────────────┘ │                 │ └─────────────┘ │
│         ▲       │                 │         │       │
│         │       │                 │         ▼       │
│ ┌─────────────┐ │                 │ ┌─────────────┐ │
│ │Docker       │ │                 │ │File         │ │
│ │Socket       │ │                 │ │Storage      │ │
│ └─────────────┘ │                 │ └─────────────┘ │
└─────────────────┘                 └─────────────────┘
         │                                    ▲
         │                                    │
         ▼                                    │
┌─────────────────┐                           │
│   Server B      │ ──────────────────────────┘
│  (Client)       │
│                 │
│ ┌─────────────┐ │
│ │LogBoard     │ │
│ │Client       │ │
│ │Container    │ │
│ └─────────────┘ │
│         ▲       │
│         │       │
│ ┌─────────────┐ │
│ │Docker       │ │
│ │Socket       │ │
│ └─────────────┘ │
└─────────────────┘

Установка клиента

1. Клонирование репозитория

git clone <repository-url>
cd logboard/client

2. Настройка переменных окружения

cp env.example .env
# Отредактируйте .env файл

3. Запуск клиента

# Используя Makefile
make install

# Или вручную
docker-compose up -d

Конфигурация

Переменные окружения клиента

Переменная	Описание	Обязательно	По умолчанию
LOGBOARD_SERVER_URL	URL сервера LogBoard	Да	http://localhost:8000
LOGBOARD_API_KEY	API ключ для аутентификации	Да	-
HOSTNAME	Имя хоста	Нет	Автоопределение
LOGBOARD_INTERVAL	Интервал отправки (сек)	Нет	60

Переменные окружения сервера

Переменная	Описание	Обязательно	По умолчанию
LOGBOARD_API_KEYS	Список разрешенных API ключей	Нет	-
LOGBOARD_DEFAULT_API_KEY	Ключ по умолчанию для разработки	Нет	dev-key-123

API Endpoints

POST /api/v1/logs/remote

Прием логов от удаленных клиентов.

Заголовки:

Authorization: Bearer <api_key>
Content-Type: application/json

Тело запроса:

{
  "hostname": "server-01",
  "container_name": "nginx",
  "logs": [
    "2024-01-01T12:00:00.000Z nginx: [info] Server started",
    "2024-01-01T12:00:01.000Z nginx: [info] Listening on port 80"
  ],
  "timestamp": "2024-01-01T12:00:01.000Z"
}

Ответ:

{
  "status": "success",
  "message": "Received 2 log lines",
  "hostname": "server-01",
  "container_name": "nginx",
  "timestamp": "2024-01-01T12:00:01.000Z",
  "log_file": "nginx-20240101.log"
}

Структура хранения логов

Логи от удаленных клиентов сохраняются в следующей структуре:

logs/
├── remote/
│   ├── server-01/
│   │   ├── nginx-20240101.log
│   │   ├── mysql-20240101.log
│   │   └── app-20240101.log
│   └── server-02/
│       ├── nginx-20240101.log
│       └── redis-20240101.log

Безопасность

Аутентификация

• Все запросы от клиентов должны содержать валидный API ключ
• API ключи передаются в заголовке Authorization: Bearer <key>
• Сервер проверяет ключи против списка разрешенных ключей

Настройка API ключей

1. На сервере LogBoard:

   # В .env файле сервера
   LOGBOARD_API_KEYS=key1,key2,key3
   

2. На клиенте:

   # В .env файле клиента
   LOGBOARD_API_KEY=key1
   

Рекомендации по безопасности

• Используйте уникальные API ключи для каждого клиента
• Регулярно ротируйте API ключи
• Используйте HTTPS для передачи данных
• Ограничьте доступ к серверу LogBoard по IP адресам

Мониторинг

Логи клиента

# Просмотр логов клиента
docker-compose logs -f logboard-client

# Проверка статуса
docker-compose ps logboard-client

Логи сервера

# Просмотр логов сервера
docker-compose logs -f logboard

# Проверка принятых логов
ls -la logs/remote/

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

Проблемы подключения

1. Ошибка аутентификации (401):

   • Проверьте правильность API ключа
   • Убедитесь, что ключ добавлен в LOGBOARD_API_KEYS на сервере

2. Ошибка подключения к серверу:

   • Проверьте URL сервера в LOGBOARD_SERVER_URL
   • Убедитесь, что сервер доступен по сети
   • Проверьте настройки firewall

3. Ошибка доступа к Docker:

   • Убедитесь, что Docker socket доступен
   • Проверьте права доступа к /var/run/docker.sock

Отладка

# Тестирование подключения
cd client
python test_client.py

# Проверка переменных окружения
docker-compose exec logboard-client env

# Просмотр логов в реальном времени
docker-compose logs -f logboard-client

Примеры использования

Множественные серверы

# docker-compose.yml на сервере A
services:
  logboard-client:
    environment:
      - LOGBOARD_SERVER_URL=http://logboard.example.com:8000
      - LOGBOARD_API_KEY=server-a-key
      - HOSTNAME=production-server-a

# docker-compose.yml на сервере B
services:
  logboard-client:
    environment:
      - LOGBOARD_SERVER_URL=http://logboard.example.com:8000
      - LOGBOARD_API_KEY=server-b-key
      - HOSTNAME=production-server-b

Настройка на центральном сервере

# .env на сервере LogBoard
LOGBOARD_API_KEYS=server-a-key,server-b-key,server-c-key

Производительность

Рекомендации

• Установите разумный интервал отправки логов (30-60 секунд)
• Используйте фильтрацию логов на стороне клиента
• Мониторьте размер логовых файлов
• Настройте ротацию логов

Ограничения

• Максимальный размер запроса: 10MB
• Таймаут запроса: 30 секунд
• Максимальное количество строк в одном запросе: 1000

Разработка

Локальная разработка

# Запуск в режиме разработки
cd client
make dev

# Тестирование
python test_client.py

Добавление новых функций

1. Расширьте API эндпоинты в app/api/v1/endpoints/logs.py
2. Обновите клиент в client/app/main.py
3. Добавьте тесты в client/test_client.py
4. Обновите документацию

Поддержка

• Автор: Сергей Антропов
• Сайт: https://devops.org.ru
• Issues: Создавайте issues в репозитории проекта