docs(readme): conventional section order, nav buttons, compact TOC

This commit is contained in:
Loki 2026-11-15 23:49:40 +01:00
parent 918e561a61
commit 246d42ddfa
Signed by: boba
GPG key ID: 6CDE87BC9A778D97
2 changed files with 85 additions and 59 deletions

135
README.md
View file

@ -10,12 +10,18 @@
![Version](https://img.shields.io/badge/version-0.3.0--dev-green?style=flat-square)
![Status](https://img.shields.io/badge/status-development-yellow?style=flat-square)
[![Docs](https://img.shields.io/badge/docs-index-blue?style=for-the-badge&logo=readthedocs&logoColor=white)](docs/README.md)
[![Quick start](https://img.shields.io/badge/quick%20start-2%20minutes-success?style=for-the-badge)](#быстрый-старт)
[![Configuration](https://img.shields.io/badge/configuration-config.toml-yellow?style=for-the-badge)](docs/configuration.md)
[![API](https://img.shields.io/badge/API-manager-purple?style=for-the-badge&logo=openapiinitiative&logoColor=white)](docs/api.md)
[![License](https://img.shields.io/badge/license-GPLv3-lightgrey?style=for-the-badge&logo=gnu&logoColor=white)](LICENSE)
[Русский](#русский) · [English](#english)
</div>
> [!WARNING]
> Проект в активной разработке. Числа производительности и API могут меняться.
> Проект в активной разработке: API и числа производительности могут меняться.
---
@ -23,28 +29,19 @@
## Русский
### Содержание
[Обзор](#обзор) · [Возможности](#возможности) · [Требования](#требования) · [Установка](#установка) · [Быстрый старт](#быстрый-старт) · [Конфигурация](#конфигурация) · [Плагины](#протокол-плагины) · [Производительность](#производительность) · [Документация](#документация) · [Разработка](#разработка) · [Лицензия](#лицензия)
- [Что это](#что-это)
- [Как это работает](#как-это-работает)
- [Возможности](#возможности)
- [Требования](#требования)
- [Быстрый старт](#быстрый-старт)
- [Конфигурация](#конфигурация)
- [Протокол-плагины](#протокол-плагины)
- [Производительность](#производительность)
- [Документация](#документация)
- [Разработка](#разработка)
- [Лицензия](#лицензия)
### Что это
### Обзор
Rampart отбрасывает атакующий трафик до того, как он дойдёт до вашего сервиса.
Фильтрация идёт в три уровня: XDP/eBPF в ядре, PoW-challenge в userspace и
L7-анализ протокола. Логика конкретного протокола вынесена в плагины, поэтому
одна и та же платформа защищает и веб-сервис, и игровой сервер.
одна платформа защищает и веб-сервис, и игровой сервер.
### Как это работает
Подходит, если нужен свой edge-фильтр на VDS: без покупки «коробки», с
конфигом в TOML и метриками в Prometheus.
**Как это работает**
```
Атакующий → [XDP/eBPF] → [PoW] → [Userspace Core] → [Плагин] → Ваш сервис
@ -80,28 +77,34 @@ L7-анализ протокола. Логика конкретного прот
| XDP | Linux 5.10+, `clang` с `-target bpf`, `libbpf`/`libelf` |
| Опционально | Redis (синхронизация блэклиста), ClickHouse (события), GeoIP-база |
### Быстрый старт
### Установка
```bash
# 1. Сборка edge-ноды с HTTP-обработчиком
# Сборка edge-ноды с HTTP-обработчиком
cargo build --release --features protocol-http
# 2. Конфиг (путь по умолчанию /etc/rampart/config.toml, переопределяется $RAMPART_CONFIG)
# Конфиг: путь по умолчанию /etc/rampart/config.toml,
# переопределяется переменной $RAMPART_CONFIG
sudo mkdir -p /etc/rampart
sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml
# 3. Запуск
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
```
С XDP (нужен root либо `CAP_BPF` + `CAP_NET_ADMIN`):
С XDP-фильтром (нужен root либо `CAP_BPF` + `CAP_NET_ADMIN`):
```bash
cargo build --release --features protocol-http,xdp
# в конфиге: [xdp] enabled = true, interface = "eth0"
```
Проверить, что всё собрано и работает:
### Быстрый старт
```bash
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
```
В конфиге для XDP: `[xdp] enabled = true`, `interface = "eth0"`. Метрики —
`http://127.0.0.1:9090/metrics`.
Проверить чекаут перед изменениями:
```bash
cargo fmt --all --check
@ -111,8 +114,21 @@ cargo test --all-features
### Конфигурация
Полный справочник — [docs/configuration.md](docs/configuration.md). Минимальный конфиг:
bind-адрес и порт, список upstream'ов, `[limits]`, опционально `[store]` и `[xdp]`.
```toml
[bind]
address = "0.0.0.0"
port = 25565
[backend]
upstreams = ["127.0.0.1:25566"]
[xdp]
enabled = false # требует сборки с feature `xdp`
interface = "eth0"
udp_policy = "pass" # pass | drop | rate-limit
```
Все поля и значения по умолчанию — [docs/configuration.md](docs/configuration.md).
### Протокол-плагины
@ -173,28 +189,19 @@ GNU General Public License v3.0 — [LICENSE](LICENSE).
## English
### Contents
[Overview](#overview) · [Features](#features) · [Requirements](#requirements) · [Installation](#installation) · [Quick start](#quick-start) · [Configuration](#configuration) · [Plugins](#protocol-plugins) · [Performance](#performance) · [Documentation](#documentation) · [Development](#development) · [License](#license)
- [What it is](#what-it-is)
- [How it works](#how-it-works)
- [Features](#features)
- [Requirements](#requirements)
- [Quick start](#quick-start)
- [Configuration](#configuration)
- [Protocol plugins](#protocol-plugins)
- [Performance](#performance)
- [Documentation](#documentation)
- [Development](#development)
- [License](#license)
### What it is
### Overview
Rampart drops malicious traffic before it reaches your service. Filtering happens
at three levels: XDP/eBPF in the kernel, a proof-of-work challenge in userspace,
and L7 protocol analysis. Protocol-specific logic lives in plugins, so the same
platform protects a web service and a game server alike.
### How it works
It fits teams that need their own edge filter on a VDS: no appliance to buy, a
TOML config, and Prometheus metrics out of the box.
**How it works**
```
Attacker → [XDP/eBPF] → [PoW] → [Userspace Core] → [Plugin] → Your service
@ -231,28 +238,34 @@ Attacker → [XDP/eBPF] → [PoW] → [Userspace Core] → [Plugin] → Your ser
| XDP | Linux 5.10+, `clang` with `-target bpf`, `libbpf`/`libelf` |
| Optional | Redis (blacklist sync), ClickHouse (events), GeoIP database |
### Quick start
### Installation
```bash
# 1. Build the edge node with the HTTP handler
# Build the edge node with the HTTP handler
cargo build --release --features protocol-http
# 2. Install the config (default is /etc/rampart/config.toml, override with $RAMPART_CONFIG)
# Config: default path is /etc/rampart/config.toml,
# override it with $RAMPART_CONFIG
sudo mkdir -p /etc/rampart
sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml
# 3. Run
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
```
With XDP (root or `CAP_BPF` + `CAP_NET_ADMIN`):
With the XDP filter (root or `CAP_BPF` + `CAP_NET_ADMIN`):
```bash
cargo build --release --features protocol-http,xdp
# config: [xdp] enabled = true, interface = "eth0"
```
Verify the checkout:
### Quick start
```bash
RAMPART_CONFIG=/etc/rampart/config.toml ./target/release/rampart
```
For XDP set `[xdp] enabled = true` and `interface = "eth0"`. Metrics are served
at `http://127.0.0.1:9090/metrics`.
Verify the checkout before making changes:
```bash
cargo fmt --all --check
@ -262,9 +275,21 @@ cargo test --all-features
### Configuration
Full reference: [docs/configuration.md](docs/configuration.md). The minimal config
needs a bind address and port, upstreams, and `[limits]`; `[store]` and `[xdp]`
are optional.
```toml
[bind]
address = "0.0.0.0"
port = 25565
[backend]
upstreams = ["127.0.0.1:25566"]
[xdp]
enabled = false # requires the `xdp` feature
interface = "eth0"
udp_policy = "pass" # pass | drop | rate-limit
```
Every field and its default: [docs/configuration.md](docs/configuration.md).
### Protocol plugins

View file

@ -152,10 +152,11 @@ guard/
- [x] `docs/README.md` — единый индекс документации (начало работы, how-to, reference,
протоколы, теория/research) + правила ведения: русский язык, один документ = одна
задача, reference правится в том же PR, что и код, плоская структура, kebab-case.
- [x] `README.md` — двуязычный: русская часть сверху, английская снизу, общий шапка/бейджи/
переключатель языка; структура по практике (что это → как работает → возможности →
требования → quick start → конфиг → плагины → производительность → документация →
разработка → лицензия); TOC, копируемые команды, ссылки на docs/README.md.
- [x] `README.md` — двуязычный: русская часть сверху, английская снизу, общая шапка/бейджи/
переключатель языка, ряд кнопок-навигации (docs, quick start, config, API, license);
секции по конвенции (обзор → возможности → требования → установка → быстрый старт →
конфигурация → плагины → производительность → документация → разработка → лицензия),
компактный TOC строкой, копируемые команды, ссылки на docs/README.md.
- [x] `docs/configuration.md` — полная таблица `[xdp]` (включая `udp_policy`) и покрытие IPv4/IPv6;
`docs/testing.md` — реальные XDP-smoke'и, а не только clang-проверка.
- [x] TUI (ratatui): live-метрики из Prometheus endpoint — готово (src/tui/, 564613b).