- 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.
90 lines
5.5 KiB
Markdown
90 lines
5.5 KiB
Markdown
# Документация Rampart
|
||
|
||
> Индекс всей документации проекта и правила её ведения.
|
||
> Точка входа — [README.md](../README.md); текущий статус — [TODO.md](../TODO.md);
|
||
> история — [CHANGELOG.md](../CHANGELOG.md).
|
||
|
||
---
|
||
|
||
## 1. С чего начать
|
||
|
||
| Документ | Когда читать |
|
||
|----------|--------------|
|
||
| [architecture.md](architecture.md) | Понять устройство: процессы, путь трафика, слои, хранилища, метрики |
|
||
| [deployment.md](deployment.md) | Первый деплой edge-ноды и manager'а |
|
||
| [configuration.md](configuration.md) | Все поля `config.toml` и переменные окружения Manager |
|
||
| [development.md](development.md) | Правила кода, тестов, гейты и Definition of Done |
|
||
|
||
## 2. Эксплуатация (how-to)
|
||
|
||
| Документ | О чём |
|
||
|----------|-------|
|
||
| [runbook.md](runbook.md) | Метрики, рестарты, снятие банов, аварийные процедуры |
|
||
| [troubleshooting.md](troubleshooting.md) | Диагностика типовых проблем |
|
||
| [disaster_recovery.md](disaster_recovery.md) | Восстановление после отказа Redis/ноды |
|
||
| [testing.md](testing.md) | Гейты, тесты, XDP-smoke на реальном ядре |
|
||
|
||
## 3. Справочник (reference)
|
||
|
||
| Документ | О чём |
|
||
|----------|-------|
|
||
| [configuration.md](configuration.md) | Все поля конфига, границы и значения по умолчанию |
|
||
| [api.md](api.md) | HTTP API manager'а: аутентификация, эндпоинты, лимиты |
|
||
| [vds_compatibility.md](vds_compatibility.md) | Ограничения окружений и ядер |
|
||
|
||
## 4. Планы и процесс
|
||
|
||
| Документ | О чём |
|
||
|----------|-------|
|
||
| [roadmap/README.md](roadmap/README.md) | Индекс задач по версиям, статусы, правила ведения |
|
||
| [roadmap/](roadmap/) | По одному файлу на задачу (v0.4, v0.5, v0.6, icebox) |
|
||
| [development.md](development.md) | KISS/DRY/SOLID, лимиты файлов, гейты, anti-patterns |
|
||
| [../TODO.md](../TODO.md) | Только текущий статус и ссылки на планы |
|
||
| [../CHANGELOG.md](../CHANGELOG.md) | Что и когда изменилось |
|
||
|
||
## 5. Протоколы
|
||
|
||
| Документ | О чём |
|
||
|----------|-------|
|
||
| [minecraft-java.md](minecraft-java.md) | Minecraft-edge: Paper, PROXY protocol, закрытый backend |
|
||
|
||
## 6. Теория и исследования
|
||
|
||
| Раздел | О чём |
|
||
|--------|-------|
|
||
| [kb/](kb/README.md) | База знаний: анатомия атак, уровни защиты, практика (двуязычная) |
|
||
| [research/](research/README.md) | Глубокие разборы: архитектура, eBPF, DDoS, Rust-производительность, конкуренты |
|
||
|
||
`kb/` отвечает на вопрос «как это работает и как защищаться», `research/` — на
|
||
вопрос «какое решение выбрать и почему». Статус проекта не живёт ни там, ни там —
|
||
только в [TODO.md](../TODO.md) и [roadmap/](roadmap/README.md).
|
||
|
||
---
|
||
|
||
## 7. Как вести документацию
|
||
|
||
1. **Язык.** `docs/` — русский. Исключение: [docs/kb/](kb/README.md), где статьи
|
||
двуязычные (`## English` / `## Русский`). Комментарии в коде — английский
|
||
([development.md](development.md) §5).
|
||
2. **Один документ = одна задача.** How-to начинается с цели («что получится в
|
||
конце»), содержит копируемые команды и заканчивается проверкой результата.
|
||
3. **Reference синхронизируется с кодом в том же PR.** Меняешь поле конфига, флаг
|
||
CLI или эндпоинт — правишь `configuration.md` / `api.md` там же. Расхождение =
|
||
баг.
|
||
4. **Планы не растут в TODO.** Новая задача — новый файл в
|
||
[roadmap/](roadmap/README.md); в `TODO.md` добавляется только строка-ссылка.
|
||
5. **Новый документ** кладётся в подходящую категорию (1–6) и сразу добавляется в
|
||
эту таблицу; если он является точкой входа — ссылка добавляется и в корневой
|
||
README.
|
||
6. **Не размножай папки.** Плоская структура `docs/*.md` — норма; подпапка нужна
|
||
только для серии документов (`kb/`, `research/`, `roadmap/`).
|
||
7. **Имена файлов** — kebab-case, `.md`, без дат в имени; дата и версия — внутри
|
||
документа.
|
||
8. **Никаких битых ссылок.** Перед коммитом: `bash scripts/check_docs_links.sh`
|
||
(этот же скрипт работает в CI).
|
||
9. **Не дублируй архитектуру.** Схемы и описания слоёв живут в
|
||
[architecture.md](architecture.md); остальные документы ссылаются на него.
|
||
|
||
---
|
||
|
||
*Версия: 3.0 | Ноябрь 2026*
|