guard/docs/troubleshooting.md
loki5512344 280284667f
docs: per-task roadmap, architecture and changelog
- Split TODO into a thin status index plus docs/roadmap/ with one file per
  task (v0.4 reliability, v0.5 product, v0.6 research, icebox).
- Add docs/architecture.md (current processes, packet/data path, layers,
  storage, metrics) and docs/development.md (rules, gates, DoD).
- Add CHANGELOG.md reconstructed from history; move round details out of
  TODO.
- Align docs with the code: config defaults and missing [detect]/
  [protocol.http] sections, XDP metric names, ClickHouse table and TTL,
  Redis RDB restore, multiarch clang include, CLI binary name.
- Add scripts/check_docs_links.sh and run it in CI.
- release profile: thin LTO + one codegen unit. Binary 12.3 MB -> 9.7 MB,
  http parser bench 314 ns -> 278 ns; panic=abort stays off for
  catch_unwind in the Redis subscriber.
- Drop the unused JWT role claim; fix 'rampart doctor' hints in the CLI.
2026-11-16 14:51:50 +01:00

6 KiB
Raw Blame History

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 -I"/usr/include/$(gcc -print-multiarch)" \
  -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.


Версия: 3.0 | Ноябрь 2026