- All remaining #[cfg(test)] modules left src/ (manager auth/heartbeat, protocol registry and HTTP parser, traffic hook/prefix/profile, TUI Prometheus); 41 tests moved into 10 integration suites with the same names and assertions, so `grep -rn '#[cfg(test)]' src/` is now empty. - runbook.md: degradation signals (overloaded connections, ClickHouse drops, XDP drops, generic mode, EMFILE backoff) and how to verify XDP was detached. - troubleshooting.md: accept backoff, orphaned XDP, password/JWT startup requirements, ClickHouse event loss. - TODO: review round recorded as fixed/deferred.
5.9 KiB
Troubleshooting - FAQ и диагностика
Edge нода
"XDP не загружается"
systemd-detect-virt # openvz/lxc → XDP не работает, нужен KVM
uname -r # нужно 5.10+
dpkg -l | grep libbpf # libbpf-dev нужен при сборке
journalctl -u rampart | grep -i "xdp\|ebpf\|bpf"
# Проверить компиляцию BPF-программы вручную:
clang -O2 -g -target bpf -c xdp/core/universal_filter.c -o /tmp/uf.o
# Не помогло — отключи XDP в config.toml ([xdp] enabled = false) и рестарт.
"accept error: ... backing off" / "Too many open files"
# Кончились дескрипторы: демон сам делает backoff, но сервис уже деградирует
ulimit -n # для процесса
systemctl show rampart -p LimitNOFILE
journalctl -u rampart | grep -E "accept error|EMFILE|backing off"
ss -s | head -5
Поднять LimitNOFILE (например, 65535), перезапустить, проверить утечки
соединений (ss -tan state established | wc -l). Backoff в списке логов — это
симптом, а не причина.
"XDP не снимается после остановки демона"
bpftool net show dev eth0
ip link show eth0 | grep -i xdp
Если программа осталась — загрузчик не снял её (регрессия), снять вручную
ip link set dev eth0 xdp off и завести баг с режимом attach из лога
(native (drv) / generic (skb)).
"Rate limit блокирует реальных клиентов"
# Смотрим метрики
curl -s http://EDGE_IP:9090/metrics | grep rate_limit
# Клиенты за NAT (один IP — много людей) → увеличь лимиты в config.toml:
# [limits] max_connections_per_ip = 50
# Или добавь их адрес в whitelist (только IP), рестарт.
"Высокое CPU на edge ноде"
top -p $(pgrep rampart)
perf top -p $(pgrep rampart)
# Частые причины:
# 1. Много мусорных коннектов в userspace → включи XDP ([xdp] enabled = true)
# 2. Заниженные rate limit → соединения постоянно рвутся и пересоздаются
# 3. Не хватает воркеров → [workers] count = числу vCPU
"Edge не стартует: no protocol plugins compiled"
Реестр протоколов пуст: rampart требует хотя бы один ProtocolHandler.
Для Minecraft Java собери edge с --features protocol-minecraft и включи
[protocol.minecraft] в конфиге; для HTTP используй --features protocol-http.
Без зарегистрированного обработчика edge завершится с ошибкой при запуске.
Подробная инструкция: Minecraft Java.
Manager
"Manager не стартует: JWT_SECRET must be set"
export JWT_SECRET="$(openssl rand -hex 32)" # минимум 32 байта
export API_PASSWORD="сильный_пароль" # 'changeme' запрещён
export REDIS_URL="redis://127.0.0.1:6379/0" # опционально
rampart-manager
"Manager не стартует: API_PASSWORD must be ..."
API_PASSWORD должен быть непустым и не короче 16 символов, JWT_SECRET —
не короче 32 непробельных байт. Пустой пароль раньше принимался как валидный,
поэтому теперь это ошибка старта, а не тихий вход без пароля.
systemctl show rampart-manager -p Environment | tr ' ' '\n' | grep -E "API_PASSWORD|JWT_SECRET" | sed 's/=.*/=<redacted>/'
"Manager отдаёт 401"
Токен истёк (JWT_EXPIRATION_SECS, дефолт 86400) — перелогинься:
curl -s -X POST localhost:8080/api/v1/auth/login \
-H 'Content-Type: application/json' -d '{"password":"..."}'
Redis
"Redis падает с OOM"
redis-cli INFO memory | grep used_memory_human
redis-cli CONFIG SET maxmemory 2gb
redis-cli CONFIG SET maxmemory-policy allkeys-lru
"Edge не синхронизирует блэклист через Redis"
# redis_url задан и не пустой? Сборка с feature store-redis (дефолт)?
grep redis_url /etc/rampart/config.toml
journalctl -u rampart | grep -i redis
Без Redis edge работает автономно на локальном кэше блэклиста.
ClickHouse
"ClickHouse не принимает данные"
systemctl status clickhouse-server
curl http://localhost:8123/ping
clickhouse-client --query "SHOW TABLES FROM rampart"
df -h /var/lib/clickhouse
Запись настраивается store.clickhouse_url в config.toml. Ошибки записи не
роняют edge: события складываются в bounded-буфер (10 000) и при переполнении
или таймауте учитываются в rampart_clickhouse_dropped_total.
curl -s http://EDGE_IP:9090/metrics | grep clickhouse_dropped
Растущий счётчик = ClickHouse не успевает; защита при этом работает, но аналитика теряет события.
Общая диагностика
rampart-cli doctor # полная диагностика через Manager API
rampart-cli status # краткий статус
Честно: набор проверок
doctorограничен тем, что реализовано в CLI (см. src/cli/commands/doctor.rs) и доступно Manager API.
Версия: 2.0 | Август 2026