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) ![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) ![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) [Русский](#русский) · [English](#english)
</div> </div>
> [!WARNING] > [!WARNING]
> Проект в активной разработке. Числа производительности и API могут меняться. > Проект в активной разработке: API и числа производительности могут меняться.
--- ---
@ -23,28 +29,19 @@
## Русский ## Русский
### Содержание [Обзор](#обзор) · [Возможности](#возможности) · [Требования](#требования) · [Установка](#установка) · [Быстрый старт](#быстрый-старт) · [Конфигурация](#конфигурация) · [Плагины](#протокол-плагины) · [Производительность](#производительность) · [Документация](#документация) · [Разработка](#разработка) · [Лицензия](#лицензия)
- [Что это](#что-это) ### Обзор
- [Как это работает](#как-это-работает)
- [Возможности](#возможности)
- [Требования](#требования)
- [Быстрый старт](#быстрый-старт)
- [Конфигурация](#конфигурация)
- [Протокол-плагины](#протокол-плагины)
- [Производительность](#производительность)
- [Документация](#документация)
- [Разработка](#разработка)
- [Лицензия](#лицензия)
### Что это
Rampart отбрасывает атакующий трафик до того, как он дойдёт до вашего сервиса. Rampart отбрасывает атакующий трафик до того, как он дойдёт до вашего сервиса.
Фильтрация идёт в три уровня: XDP/eBPF в ядре, PoW-challenge в userspace и Фильтрация идёт в три уровня: XDP/eBPF в ядре, PoW-challenge в userspace и
L7-анализ протокола. Логика конкретного протокола вынесена в плагины, поэтому L7-анализ протокола. Логика конкретного протокола вынесена в плагины, поэтому
одна и та же платформа защищает и веб-сервис, и игровой сервер. одна платформа защищает и веб-сервис, и игровой сервер.
### Как это работает Подходит, если нужен свой edge-фильтр на VDS: без покупки «коробки», с
конфигом в TOML и метриками в Prometheus.
**Как это работает**
``` ```
Атакующий → [XDP/eBPF] → [PoW] → [Userspace Core] → [Плагин] → Ваш сервис Атакующий → [XDP/eBPF] → [PoW] → [Userspace Core] → [Плагин] → Ваш сервис
@ -80,28 +77,34 @@ L7-анализ протокола. Логика конкретного прот
| XDP | Linux 5.10+, `clang` с `-target bpf`, `libbpf`/`libelf` | | XDP | Linux 5.10+, `clang` с `-target bpf`, `libbpf`/`libelf` |
| Опционально | Redis (синхронизация блэклиста), ClickHouse (события), GeoIP-база | | Опционально | Redis (синхронизация блэклиста), ClickHouse (события), GeoIP-база |
### Быстрый старт ### Установка
```bash ```bash
# 1. Сборка edge-ноды с HTTP-обработчиком # Сборка edge-ноды с HTTP-обработчиком
cargo build --release --features protocol-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 mkdir -p /etc/rampart
sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml 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 ```bash
cargo build --release --features protocol-http,xdp 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 ```bash
cargo fmt --all --check cargo fmt --all --check
@ -111,8 +114,21 @@ cargo test --all-features
### Конфигурация ### Конфигурация
Полный справочник — [docs/configuration.md](docs/configuration.md). Минимальный конфиг: ```toml
bind-адрес и порт, список upstream'ов, `[limits]`, опционально `[store]` и `[xdp]`. [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 ## 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) ### Overview
- [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
Rampart drops malicious traffic before it reaches your service. Filtering happens 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, 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 and L7 protocol analysis. Protocol-specific logic lives in plugins, so the same
platform protects a web service and a game server alike. 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 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` | | XDP | Linux 5.10+, `clang` with `-target bpf`, `libbpf`/`libelf` |
| Optional | Redis (blacklist sync), ClickHouse (events), GeoIP database | | Optional | Redis (blacklist sync), ClickHouse (events), GeoIP database |
### Quick start ### Installation
```bash ```bash
# 1. Build the edge node with the HTTP handler # Build the edge node with the HTTP handler
cargo build --release --features protocol-http 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 mkdir -p /etc/rampart
sudo cp deploy/config/edge-http.toml /etc/rampart/config.toml 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 ```bash
cargo build --release --features protocol-http,xdp 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 ```bash
cargo fmt --all --check cargo fmt --all --check
@ -262,9 +275,21 @@ cargo test --all-features
### Configuration ### Configuration
Full reference: [docs/configuration.md](docs/configuration.md). The minimal config ```toml
needs a bind address and port, upstreams, and `[limits]`; `[store]` and `[xdp]` [bind]
are optional. 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 ### Protocol plugins

View file

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