276 lines
13 KiB
Markdown
276 lines
13 KiB
Markdown
# Обзор архитектуры системы
|
||
|
||
Этот документ — единый и актуальный источник информации по платформе: архитектура, протоколы, данные, конфигурация, сценарии, эксплуатация. Заменяет собой разрозненные и устаревшие документы.
|
||
|
||
## Содержание
|
||
- Компоненты и топология
|
||
- Децентрализованный слой (членство, оценка размера сети, репликации, метрики)
|
||
- Загрузка и конвертация контента
|
||
- Просмотр и покупка контента (UI/UX требования)
|
||
- API (ключевые эндпойнты и полезная нагрузка)
|
||
- Ключи и схемы данных (DHT)
|
||
- Конфигурация и значения по умолчанию
|
||
- Наблюдаемость и метрики
|
||
- Диаграммы последовательностей (Mermaid)
|
||
- Сборка и тестирование
|
||
|
||
---
|
||
|
||
## Компоненты и топология
|
||
|
||
- Backend API: сервис на Sanic (Python) с бота́ми Telegram; база данных PostgreSQL (SQLAlchemy + Alembic).
|
||
- Хранилище: локальная ФС (uploads/derivatives); IPFS (kubo) для ретривания/пининга; tusd (resumable upload).
|
||
- Конвертеры: воркеры (ffmpeg) в контейнерах — `convert_v3`, `convert_process`.
|
||
- Frontend: SPA (Vite + TypeScript), отдается nginx-контейнером.
|
||
- Децентрализованный слой: встроенный DHT (в процессе) — членство, лизы реплик, метрики контента.
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Client -- TWA/HTTP --> Frontend
|
||
Frontend -- REST --> API[Backend API]
|
||
API -- tus hooks --> tusd
|
||
API -- SQL --> Postgres
|
||
API -- IPC --> Workers[Converters]
|
||
API -- IPFS --> IPFS
|
||
API -- DHT --> DHT[(In-Process DHT)]
|
||
DHT -- CRDT Merge --> DHT
|
||
```
|
||
|
||
---
|
||
|
||
## Децентрализованный слой
|
||
|
||
### Идентификаторы и версии
|
||
- NodeID = blake3(Ed25519 публичного ключа) — шестнадцатеричная строка (256 бит).
|
||
- ContentID = blake3(зашифрованного блоба) — неизменяемый идентификатор контента.
|
||
- schema_version = v1 — фиксируется во всех DHT-ключах/записях.
|
||
|
||
### Членство (membership)
|
||
- Рукопожатие `/api/v1/network.handshake` — запрос подписан Ed25519; верифицируется на стороне получателя. Без корректной подписи — 400 BAD_SIGNATURE.
|
||
- Полезная нагрузка включает: сведения о ноде (версия, возможности, IPFS), метрики, массив известных публичных нод, квитанции достижимости (reachability_receipts: issuer, target, ASN, timestamp, signature).
|
||
- Состояние членства — CRDT LWW-Set (добавления/удаления) с TTL (`DHT_MEMBERSHIP_TTL=600` сек), плюс HyperLogLog для оценки мощности (N_local).
|
||
- Фильтрация «островов»: ноды с `reachability_ratio < q` (по умолчанию `q=0.6`) исключаются при вычислении N_estimate и выборе реплик.
|
||
- Итоговая оценка `N_estimate = max(валидных N_local от пиров)`.
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant A as Узел A
|
||
participant B as Узел B
|
||
A->>B: POST /network.handshake {nonce, ts, node, receipts, signature}
|
||
B->>B: верификация ts/nonce, подписи
|
||
B->>B: upsert member; merge(receipts)
|
||
B-->>A: {node, known_public_nodes, n_estimate, server_signature}
|
||
A->>A: merge; N_estimate = max(N_local, полученные)
|
||
```
|
||
|
||
### Репликации и лизы
|
||
- Выбор префикса: `p = max(0, round(log2(N_estimate / R_target)))`, где `R_target ≥ 3` (по умолчанию 3).
|
||
- Ответственные ноды: чьи первые `p` бит NodeID совпадают с первыми `p` бит ContentID.
|
||
- Лидер — минимальный NodeID среди ответственных.
|
||
- Лидер выдаёт `replica_leases` (TTL=600 сек), соблюдая разнообразие: не менее 3 разных первых октетов IP и, если доступно, 3 разных ASN.
|
||
- Ранжирование кандидатов — rendezvous score `blake3(ContentID || NodeID)`.
|
||
- Сердцебиение (heartbeat) держателей — каждые 60 сек; 3 пропуска → признать down и переназначить ≤180 сек.
|
||
- Недобор/перебор фиксируются в `conflict_log` и прометеус‑метриках.
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> Discover
|
||
Discover: Рукопожатия + квитанции
|
||
Discover --> Active: TTL & кворм ASN
|
||
Active --> Leader: Выбор лидера префикса p
|
||
Leader --> Leased: Выдача лизов (diversity)
|
||
Leased --> Monitoring: Heartbeat 60s
|
||
Monitoring --> Reassign: 3 пропуска
|
||
Reassign --> Leased
|
||
```
|
||
|
||
### Метрики (окна)
|
||
- На событии просмотра формируются дельты CRDT:
|
||
- PN‑Counter — количество просмотров;
|
||
- HyperLogLog — уникальные ViewID (ViewID = blake3(ContentID || соль_устройства));
|
||
- G‑Counter — watch_time, bytes_out, количество завершений.
|
||
- Окно по часу (`DHT_METRIC_WINDOW_SEC`), ключ `MetricKey = blake3(ContentID || WindowID)`.
|
||
- Мерджи коммутативные, детерминированные.
|
||
|
||
---
|
||
|
||
## Загрузка и конвертация контента
|
||
|
||
1) Клиент грузит в `tusd` (resumable). Бэкенд получает HTTP‑hooks `/api/v1/upload.tus-hook`.
|
||
2) Создается запись в БД для зашифрованного контента, воркеры размещают производные:
|
||
- для медиа — preview/low/high;
|
||
- для бинарей — оригинал (доступен только при наличии лицензии).
|
||
3) `/api/v1/content.view` возвращает `display_options` и агрегированное состояние конвертации/загрузки.
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as Клиент
|
||
participant T as tusd
|
||
participant B as Бэкенд
|
||
participant W as Воркеры
|
||
participant DB as PostgreSQL
|
||
|
||
C->>T: upload
|
||
T->>B: hooks (pre/post-finish)
|
||
B->>DB: create content
|
||
B->>W: очередь конвертации
|
||
W->>DB: derive/previews
|
||
C->>B: GET /content.view
|
||
B->>DB: resolve derivatives
|
||
B-->>C: display_options + status
|
||
```
|
||
|
||
---
|
||
|
||
## Просмотр и покупка (UI/UX)
|
||
|
||
- `/api/v1/content.view/<content_address>` определяет доступные отображения:
|
||
- бинарный контент без превью — оригинал только при наличии лицензии;
|
||
- аудио/видео — для неавторизованных preview/low, для имеющих доступ — decrypted_low/high.
|
||
- В процессе конвертации фронтенд показывает статус «processing», без фальшивых ссылок.
|
||
- Обложка (cover):
|
||
- фиксированный квадратный слот; изображение «вписывается» без растягивания/искажения;
|
||
- пустые области не заполняются чёрным — фон совпадает с фоном страницы.
|
||
- Кнопки «Купить за TON/Stars»: всегда в одной строке (без горизонтального/вертикального скролла контента на малых экранах).
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
View[content.view] --> Resolve[Определение деривативов]
|
||
Resolve --> Ready{Готово?}
|
||
Ready -- Нет --> Info[Статус: processing/pending]
|
||
Ready -- Да --> Options
|
||
Options -- Бинарь + нет лицензии --> HideOriginal[Скрыть оригинал]
|
||
Options -- Медиа + нет лицензии --> PreviewLow[preview/low]
|
||
Options -- Есть лицензия --> Decrypted[decrypted low/high|original]
|
||
```
|
||
|
||
---
|
||
|
||
## API (ключевые)
|
||
|
||
- `GET /api/system.version` — актуальность сервиса.
|
||
- `POST /api/v1/network.handshake` — обмен членством (обязательная Ed25519‑подпись запроса). Пример запроса:
|
||
|
||
```json
|
||
{
|
||
"version": "3.0.0",
|
||
"schema_version": "v1",
|
||
"public_key": "<base58 ed25519 pubkey>",
|
||
"node_id": "<blake3(pubkey)>",
|
||
"public_host": "https://node.example",
|
||
"node_type": "public|private",
|
||
"metrics": {"uptime_sec": 123, "content_count": 42},
|
||
"capabilities": {"accepts_inbound": true, "is_bootstrap": false},
|
||
"ipfs": {"multiaddrs": ["/ip4/.../tcp/4001"], "peer_id": "..."},
|
||
"known_public_nodes": [],
|
||
"reachability_receipts": [],
|
||
"timestamp": 1710000000,
|
||
"nonce": "<hex>",
|
||
"signature": "<base58 ed25519 signature>"
|
||
}
|
||
```
|
||
|
||
- `GET /api/v1/content.view/<content_address>` — `display_options`, `status`, `conversion`.
|
||
- `GET /api/v1.5/storage/<file_hash>` — отдача файла.
|
||
- `GET /metrics` — экспозиция метрик Prometheus (либо fallback‑дамп счётчиков).
|
||
|
||
---
|
||
|
||
## Ключи и схемы DHT
|
||
|
||
- `MetaKey(content_id)` — метаданные репликаций:
|
||
- `replica_leases`: карта `{lease_id -> {node_id, issued_at, expires_at, asn, ip_first_octet, heartbeat_at, score}}`;
|
||
- `leader`: NodeID лидера; `revision`: номер ревизии;
|
||
- `conflict_log`: массив событий `UNDER/OVER/LEASE_EXPIRED` и т.п.
|
||
|
||
- `MembershipKey(node_id)` — членство:
|
||
- `members`: LWW‑Set; `receipts`: LWW‑Set;
|
||
- `hll`: HyperLogLog; `reports`: карты локальных оценок N;
|
||
- `logical_counter`: логический счётчик для LWW‑доминации.
|
||
|
||
- `MetricKey(content_id, window_id)` — метрики окна:
|
||
- `views`: PN‑Counter; `unique`: HLL; `watch_time`, `bytes_out`, `completions`: G‑Counters.
|
||
|
||
Все записи подписываются и сливаются детерминированно: CRDT‑логика + LWW‑доминация (`logical_counter`, `timestamp`, `node_id`).
|
||
|
||
---
|
||
|
||
## Конфигурация и значения по умолчанию
|
||
|
||
- Сеть/рукопожатия: `NODE_PRIVACY`, `PUBLIC_HOST`, `HANDSHAKE_INTERVAL_SEC`, `NETWORK_TLS_VERIFY`, IPFS‑пиры/бустрапы.
|
||
- DHT:
|
||
- `DHT_MIN_RECEIPTS=5`, `DHT_MIN_REACHABILITY=0.6`, `DHT_MEMBERSHIP_TTL=600`;
|
||
- `DHT_REPLICATION_TARGET=3`, `DHT_LEASE_TTL=600`,
|
||
- `DHT_HEARTBEAT_INTERVAL=60`, `DHT_HEARTBEAT_MISS_THRESHOLD=3`;
|
||
- `DHT_MIN_ASN=3`, `DHT_MIN_IP_OCTETS=3`,
|
||
- `DHT_METRIC_WINDOW_SEC=3600`.
|
||
- Конвертация: квоты `CONVERT_*`, `MAX_CONTENT_SIZE_MB`.
|
||
|
||
Примечание: PoW‑допуски и Kademlia k‑buckets на текущем этапе не активированы в коде — заложены в дизайн и могут быть реализованы отдельно.
|
||
|
||
---
|
||
|
||
## Наблюдаемость и метрики
|
||
|
||
Prometheus:
|
||
- `dht_replication_under_total`, `dht_replication_over_total`, `dht_leader_changes_total`;
|
||
- `dht_merge_conflicts_total`;
|
||
- `dht_view_count_total`, `dht_unique_view_estimate`, `dht_watch_time_seconds`.
|
||
|
||
Логи: структурированные ошибки HTTP (с id), `conflict_log` по репликациям, события регистрации нод.
|
||
|
||
---
|
||
|
||
## Диаграммы последовательностей (сводные)
|
||
|
||
### Обновление N_estimate
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Peer
|
||
participant Membership
|
||
participant DHT
|
||
Peer->>Membership: handshake(payload, receipts)
|
||
Membership->>Membership: merge LWW/receipts
|
||
Membership->>Membership: update HLL и N_local
|
||
Membership->>DHT: persist MembershipKey
|
||
Membership->>Membership: N_estimate = max(valid reports)
|
||
```
|
||
|
||
### Выбор лидера и выдача лизов
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant L as Leader
|
||
participant R as Responsible
|
||
L->>L: p = round(log2(N_est/R))
|
||
L->>R: rank by rendezvous(ContentID, NodeID)
|
||
L->>L: assign leases (diversity)
|
||
R-->>L: heartbeat/60s
|
||
L->>L: reassign on 3 misses
|
||
```
|
||
|
||
### Публикация метрик окна
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as Client
|
||
participant API as Backend
|
||
participant M as Metrics
|
||
participant D as DHT
|
||
C->>API: GET content.view?watch_time,bytes_out
|
||
API->>M: record_view(delta)
|
||
M->>D: merge MetricKey(ContentID, window)
|
||
API-->>Prom: /metrics
|
||
```
|
||
|
||
---
|
||
|
||
## Сборка и тестирование
|
||
|
||
```bash
|
||
# Старт окружения (пример для /home/configs)
|
||
docker compose -f /home/configs/docker-compose.yml --env-file /home/configs/.env up -d --build
|
||
|
||
# Тесты слоя DHT
|
||
cd uploader-bot
|
||
python3 -m unittest discover -s tests/dht
|
||
```
|