guard/docs/troubleshooting.md
loki5512344 da87d2a11f
test: move the last inline test modules to tests/, document new signals
- 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.
2026-11-16 12:36:29 +01:00

169 lines
5.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 | 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"
```bash
# Кончились дескрипторы: демон сам делает 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 не снимается после остановки демона"
```bash
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 блокирует реальных клиентов"
```bash
# Смотрим метрики
curl -s http://EDGE_IP:9090/metrics | grep rate_limit
# Клиенты за NAT (один IP — много людей) → увеличь лимиты в config.toml:
# [limits] max_connections_per_ip = 50
# Или добавь их адрес в whitelist (только IP), рестарт.
```
### "Высокое CPU на edge ноде"
```bash
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](minecraft-java.md).
---
## Manager
### "Manager не стартует: JWT_SECRET must be set"
```bash
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 непробельных байт. Пустой пароль раньше принимался как валидный,
поэтому теперь это ошибка старта, а не тихий вход без пароля.
```bash
systemctl show rampart-manager -p Environment | tr ' ' '\n' | grep -E "API_PASSWORD|JWT_SECRET" | sed 's/=.*/=<redacted>/'
```
### "Manager отдаёт 401"
Токен истёк (`JWT_EXPIRATION_SECS`, дефолт 86400) — перелогинься:
```bash
curl -s -X POST localhost:8080/api/v1/auth/login \
-H 'Content-Type: application/json' -d '{"password":"..."}'
```
---
## Redis
### "Redis падает с OOM"
```bash
redis-cli INFO memory | grep used_memory_human
redis-cli CONFIG SET maxmemory 2gb
redis-cli CONFIG SET maxmemory-policy allkeys-lru
```
### "Edge не синхронизирует блэклист через Redis"
```bash
# redis_url задан и не пустой? Сборка с feature store-redis (дефолт)?
grep redis_url /etc/rampart/config.toml
journalctl -u rampart | grep -i redis
```
Без Redis edge работает автономно на локальном кэше блэклиста.
---
## ClickHouse
### "ClickHouse не принимает данные"
```bash
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`.
```bash
curl -s http://EDGE_IP:9090/metrics | grep clickhouse_dropped
```
Растущий счётчик = ClickHouse не успевает; защита при этом работает, но
аналитика теряет события.
---
## Общая диагностика
```bash
rampart-cli doctor # полная диагностика через Manager API
rampart-cli status # краткий статус
```
> Честно: набор проверок `doctor` ограничен тем, что реализовано в CLI
> (см. src/cli/commands/doctor.rs) и доступно Manager API.
---
*Версия: 2.0 | Август 2026*