Initial commit: Rampart v0.2.0

Multi-layer DDoS protection for Minecraft servers.

- rampart-core: Edge node with XDP/eBPF + Rust L7 filtering
- rampart-manager: REST API with JWT auth, Redis sync
- rampart-cli: CLI tool for operators
- velocity-plugin: Domain check, HMAC verify, server registry, load balancer
- paper-plugin: Auto-registration, heartbeat, HMAC verify
- dashboard: React + Vite web UI for management

docs/troubleshooting.md

@@ -0,0 +1,327 @@
+# Troubleshooting - FAQ и диагностика
+
+---
+
+## Edge нода
+
+### "XDP не загружается"
+
+```bash
+# Проверяем виртуализацию
+systemd-detect-virt
+# openvz / lxc -> XDP не работает, нужен KVM
+
+# Проверяем ядро
+uname -r
+# Нужно 5.10+
+
+# Проверяем зависимости
+dpkg -l | grep libbpf
+# libbpf-dev должен быть установлен
+
+# Смотрим ошибку загрузки
+journalctl -u rampart-edge | grep -i "xdp\|ebpf\|bpf"
+
+# Если драйвер не поддерживает native - fallback на generic
+# В конфиге:
+[xdp]
+mode = "generic"   # вместо "native" или "auto"
+```
+
+### "Edge не коннектится к Manager"
+
+```bash
+# Проверяем WireGuard
+ping 10.0.0.1
+# Нет ответа -> WireGuard не работает
+
+wg show
+# Смотрим peer Manager - есть ли last handshake?
+# Нет handshake -> проблема с ключами или firewall у Manager
+
+# Проверяем firewall на Manager
+ssh root@MANAGER_IP 'iptables -L INPUT -n | grep 51820'
+# Должно быть правило ACCEPT для UDP 51820
+
+# Проверяем что Manager слушает
+ssh root@MANAGER_IP 'ss -ulnp | grep 51820'
+
+# Пересоздаём WireGuard handshake
+wg set wg0 peer MANAGER_PUBKEY endpoint MANAGER_IP:51820
+```
+
+### "Rate limit блокирует реальных игроков"
+
+```bash
+# Симптом: игроки жалуются что не могут зайти
+
+# Смотрим кого блокируем
+journalctl -u rampart-edge | grep "RATE_LIMIT" | tail -50
+
+# Если блокируем целые подсети мобильных операторов (NAT):
+# Увеличиваем лимит для мобильных ASN
+rampart config set rate_limit.mobile_multiplier 3.0
+
+# Или поднимаем общий лимит
+rampart config set rate_limit.max_connections_per_ip 10
+rampart config reload
+```
+
+### "Высокое CPU на edge ноде"
+
+```bash
+# Смотрим что жрёт CPU
+top -p $(pgrep rampart-edge)
+
+# Профилируем
+perf top -p $(pgrep rampart-edge)
+
+# Частые причины:
+# 1. Слишком много активных соединений -> включить XDP чтобы дропать раньше
+# 2. HMAC считается для каждого пакета -> норма, так и должно быть
+# 3. GeoIP lookup медленный -> включить кэш
+[geo]
+cache_size = 100000
+cache_ttl_secs = 3600
+```
+
+---
+
+## Velocity плагин
+
+### "Velocity не видит серверы"
+
+```bash
+# В логах Velocity ищем:
+grep -i "rampart\|registry\|redis" /opt/velocity/logs/latest.log
+
+# Частые причины:
+
+# 1. Redis недоступен
+redis-cli -h 10.0.0.1 -a $REDIS_PASSWORD ping
+# Connection refused -> Redis не слушает на WireGuard IP
+
+# 2. Неверный пароль Redis
+# В config.yml проверяем redis.password
+
+# 3. Velocity не в WireGuard сети
+ping 10.0.0.1   # с ноды Velocity
+# Нет ответа -> настраиваем WireGuard
+
+# 4. Серверы не зарегистрированы (Paper агент не запущен)
+redis-cli -h 10.0.0.1 -a $REDIS_PASSWORD keys "rampart:servers:*"
+# Пустой ответ -> Paper агент не работает
+```
+
+### "Игроков не пускает - 'Подключение по IP запрещено'"
+
+```bash
+# Это нормально если игрок подключается по IP, а не домену
+# Проверяем что DNS работает:
+nslookup play.yourserver.com
+# Должен вернуть IP edge ноды
+
+# Если игрок подключается через домен и всё равно кикает:
+# Проверяем что edge HMAC совпадает с Velocity
+
+# На Velocity смотрим логи:
+grep "HMAC\|shield" /opt/velocity/logs/latest.log
+
+# Частые причины:
+# 1. Разные HMAC секреты на edge и Velocity
+# Сравниваем:
+cat /etc/rampart/config.toml | grep hmac_secret
+grep RAMPART_HMAC_SECRET /opt/velocity/velocity.conf
+
+# 2. Edge нода не добавляет HMAC (add_hmac_header = false)
+# В /etc/rampart/config.toml:
+[shield]
+add_hmac_header = true
+```
+
+### "Игрок попадает не на тот сервер"
+
+```bash
+# Проверяем стратегию балансировщика
+grep "strategy" /opt/velocity/plugins/rampart/config.yml
+
+# Смотрим онлайн по серверам
+rampart server list
+
+# Если сервер переполнен но всё равно получает игроков:
+# Проверяем что Paper агент обновляет онлайн
+redis-cli -h 10.0.0.1 -a $REDIS_PASSWORD \
+  GET rampart:servers:hub_1
+# В JSON смотрим "online" - должно обновляться
+```
+
+---
+
+## Paper агент
+
+### "Агент не регистрирует сервер"
+
+```bash
+# В логах Minecraft сервера:
+grep -i "rampart\|shield agent" /opt/minecraft/logs/latest.log
+
+# Частые причины:
+
+# 1. Redis недоступен с этой ноды
+redis-cli -h 10.0.0.1 -a $REDIS_PASSWORD ping
+
+# 2. Неверный IP в конфиге (указан публичный вместо WireGuard)
+# Проверить env RAMPART_SERVER_IP
+# Должен быть 10.0.x.x (WireGuard IP)
+
+# 3. Дублирующееся имя сервера
+redis-cli -h 10.0.0.1 -a $REDIS_PASSWORD \
+  keys "rampart:servers:*"
+# Если имя уже есть - изменить RAMPART_SERVER_NAME
+
+# 4. Агент не установлен
+ls /opt/minecraft/plugins/ | grep rampart-paper
+# Должен быть .jar файл
+```
+
+---
+
+## Redis
+
+### "Redis падает с OOM"
+
+```bash
+# Проверяем использование памяти
+redis-cli -a $REDIS_PASSWORD INFO memory | grep used_memory_human
+
+# Настраиваем eviction policy
+redis-cli -a $REDIS_PASSWORD CONFIG SET maxmemory 2gb
+redis-cli -a $REDIS_PASSWORD CONFIG SET maxmemory-policy allkeys-lru
+
+# Смотрим что занимает место
+redis-cli -a $REDIS_PASSWORD --bigkeys
+```
+
+### "Redis медленно отвечает"
+
+```bash
+# Запускаем latency monitor
+redis-cli -a $REDIS_PASSWORD --latency-history -i 1
+
+# Смотрим slowlog
+redis-cli -a $REDIS_PASSWORD SLOWLOG GET 10
+
+# Частые причины:
+# 1. KEYS команда (блокирует) -> заменить на SCAN
+# 2. Нет persistent connection pool -> Jedis pool в Velocity плагине
+# 3. Сеть: проверяем пинг от Velocity до Redis через WireGuard
+ping 10.0.0.1
+```
+
+---
+
+## WireGuard
+
+### "Ноды не видят друг друга"
+
+```bash
+# На каждой ноде
+wg show
+# Смотрим:
+# - есть ли peer с нужным PublicKey
+# - есть ли "latest handshake" (должен быть свежий)
+# - endpoint правильный
+
+# Если нет handshake:
+# 1. Проверяем что Manager слушает UDP 51820
+ss -ulnp | grep 51820
+
+# 2. Проверяем firewall на Manager
+iptables -L INPUT -n | grep 51820
+
+# 3. Проверяем что ключи правильные
+wg pubkey < /etc/wireguard/private.key
+# Должен совпасть с PublicKey у peer на Manager
+
+# Форс рестарт
+systemctl restart wg-quick@wg0
+```
+
+### "Высокий пинг через WireGuard"
+
+```bash
+# Измеряем
+ping 10.0.0.1
+# Нормально: < 5 мс внутри датацентра, < 50 мс между регионами
+
+# Если > 200 мс -> проблема с маршрутизацией
+traceroute 10.0.0.1
+
+# MTU проблема (фрагментация):
+ping -M do -s 1400 10.0.0.1
+# Если drops -> MTU слишком большой
+# В /etc/wireguard/wg0.conf добавить:
+MTU = 1380
+```
+
+---
+
+## ClickHouse
+
+### "ClickHouse не принимает данные"
+
+```bash
+# Проверяем что запущен
+systemctl status clickhouse-server
+# или
+docker compose ps rampart-clickhouse
+
+# Проверяем таблицы
+clickhouse-client --query "SHOW TABLES FROM rampart"
+
+# Проверяем ошибки вставки в логах Manager
+journalctl -u rampart-manager | grep -i "clickhouse\|insert"
+
+# Частые причины:
+# 1. Таблица не создана -> запускаем миграции
+rampart db migrate
+
+# 2. Нет места на диске
+df -h
+# ClickHouse хранит в /var/lib/clickhouse/
+
+# 3. Неверная схема (после обновления)
+clickhouse-client --query "DESCRIBE TABLE rampart.blocked"
+```
+
+---
+
+## Общая диагностика
+
+```bash
+# Полная проверка системы одной командой
+rampart doctor
+
+# Что проверяет:
+# ✅ WireGuard туннели
+# ✅ Redis доступность
+# ✅ NATS доступность
+# ✅ Manager API
+# ✅ Все edge ноды online
+# ✅ Все Velocity ноды online
+# ✅ Хотя бы один Hub онлайн
+# ✅ HMAC секрет одинаковый везде
+# ✅ Сертификаты не истекают в ближайшие 30 дней
+# ✅ Redis память < 80%
+# ✅ Место на дисках > 20%
+
+# Вывод:
+# [OK]   Redis: 10.0.0.1:6379
+# [OK]   Manager API: /api/health
+# [WARN] Edge eu-1: last seen 45 sec ago (порог 30 сек)
+# [FAIL] Hub_5: не зарегистрирован в Redis
+```
+
+---
+
+*Версия: 1.0 | Июль 2026*