diff --git a/docs/architecture/README.md b/docs/architecture/README.md index e7de788..b694b9f 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -1,17 +1,41 @@ -# Production architecture +# Production architecture — финальный вариант -> **Экспериментальная ветка** — несколько вариантов одной диаграммы. Выбери что нравится. -> Каждый вариант — отдельный коммит, чтобы было видно как эволюционировало. +> **Snapshot:** 2026-08-27 · sources: `docker_socket_proxy` (read-only) + gitea admin API + gitea_server logs. -> Snapshot: 2026-08-27 · sources: `docker_socket_proxy` (read-only) + gitea admin API + gitea_server logs. +## Что в этой папке -## Что показывает (все варианты) +| Файл | Назначение | +|---|---| +| `svg-adaptive.md` | **Главный файл** — preview в Gitea, обёртка с описанием | +| `standalone-adaptive.svg` | Собственно SVG (адаптивный light/dark) | -- 2 swarm nodes (odroid manager + xu4 worker) -- 7 stacks на odroid: gitea, hermes, hermes_infra, immich, brencher, brencher2, gmail_mcp, torrserv_proxy -- External: Keenetic router (DNS + Let's Encrypt TLS termination), Tailscale (subnet router — транспорт), Client -- Dead: `nginx_nginx` (Replicas=0) — overlay-сеть nginx_ingress жива -- Deploy flow: brencher → стеки (dashed rose arrows) +## История решений (что было отброшено) + +Это финал после серии экспериментов. Сначала я сделал 10 вариантов одной диаграммы: + +1. ❌ Mermaid в md — спартанский стиль, трудно контролировать layout +2. ❌ `` без sizing — теряется контроль над размером +3. ❌ `` с sizing (но `style` санитизируется gitea) +4. ❌ Inline SVG в `
` — diff нечитаемый, дублирование +5. ❌ `` — gitea вырезает через goldmark санитайзер +6. ✅ **Adaptive SVG** — `` + `@media prefers-color-scheme` в самом SVG +7. ❌ Plain SVG без адаптивности +8. ❌ HTML+SVG dark theme — не рендерится в Gitea preview +9. ❌ ASCII art — работает везде, но некрасиво + +**Почему adaptive SVG зашёл:** +- Один файл, рендерится и в Gitea preview, и при прямом открытии в браузере +- Автоматически подстраивается под light/dark тему пользователя (через `` это работает только в браузере, не в Gitea-preview, но при прямом открытии SVG — адаптивно) +- Точный layout (ручной SVG, не auto-generated) +- Жёлтые кружки для физических хостов + reachability-аннотации ясно показывают кто кого видит + +## Что показывает финальная диаграмма + +- **Сеть `lan`** (192.168.1.0/24) — amber-bordered блок между Keenetic и физическими хостами +- **Физические хосты** — жёлтые кружки с цифрами (① odroid, ② xu4) +- **Стеки** на odroid: gitea, hermes, hermes_infra, immich, brencher, gmail_mcp, torrserv_proxy +- **Dead:** `nginx_nginx` (Replicas=0) +- **Reachability** — зелёные ● и красные ● показывают кто кого видит ## Что НЕ показывает (для следующих уровней) @@ -21,7 +45,7 @@ - DNS-резолвинг детально - Traffic flow конкретных сервисов -## Известные неточности (TODO) +## Известные TODO 1. `endpoint.Ports` у gitea_server пустое, но ingress маршрутизирует — legacy. 2. `xu4` worker пуст в снапшоте. @@ -29,50 +53,6 @@ 4. Tailscale роль (subnet router) требует подтверждения. 5. brencher-stack-compose для каждого стека отсутствует в `admin/ansible`. -## Варианты - -| # | Файл | Формат | Где рендерится | Комментарий | -|---|---|---|---|---| -| 1 | `mermaid.md` | Mermaid в md | Gitea UI | Спартанский стиль, diff-friendly | -| 2 | `svg-embedded.md` | md → `` SVG | Gitea UI | **Проверено** через `/api/v1/markdown` — работает | -| 3 | `svg-sized.md` | md → `` с width | Gitea UI | Контроль размера (но `style` санитизируется) | -| 4 | `svg-inline.md` | inline SVG в `
` | Gitea UI | Можно зумить, но diff нечитаем | -| 5 | `svg-object.md` | md → `` | **НЕ работает** в Gitea | goldmark вырезает; оставлен для справки | -| 6 | `svg-adaptive.md` | md → adaptive SVG | Gitea UI (только dark) | Светлая тема не работает через `` (img isolation) | -| 7 | `standalone.svg` | Raw SVG | Браузер | Точный layout, single file | -| 8 | `standalone-adaptive.svg` | SVG + prefers-color-scheme | Браузер | Адаптивная тема при прямом открытии | -| 9 | `standalone.html` | HTML+SVG dark theme | Браузер | Pulsing dot, summary cards | -| 10 | `ascii.txt` | ASCII art | Terminal / raw md | Работает везде, не зависит от рендерера | - -## Рекомендация после тестов - -| Цель | Использовать | -|---|---| -| README главной страницы | `svg-embedded.md` (вариант 2) | -| PR preview в Gitea | `svg-embedded.md` или `svg-sized.md` (вариант 3) если большая | -| Wiki-страница | `svg-embedded.md` | -| Внешний share (email, slack) | `standalone.svg` (аттач) | -| Презентация / документ | `standalone.html` (открыть в браузере) | -| Где SVG не работает | `ascii.txt` | - -## Что работает в Gitea 1.27 preview (проверено через `/api/v1/markdown`) - -| Синтаксис | Результат | -|---|---| -| `![arch](path.svg)` | `` ✅ | -| `` | `` ✅ | -| `` | `` без style ❌ | -| `` | вырезается ❌ | -| `...` inline | рендерится (если внутри md) ✅ | -| `
......
` | рендерится ✅ | - -## Коммиты в этой ветке - -1. `docs: add production architecture diagram in three formats` — 3 базовых варианта -2. `docs: add svg-embedded variant` — `` через markdown -3. `docs: add svg-sized, svg-inline, svg-object, svg-adaptive variants` -4. `docs: add ascii variant and refresh README` - ## Связанные тикеты - `admin/ansible#5` — re-deploy `hermes_squid` diff --git a/docs/architecture/standalone-adaptive.svg b/docs/architecture/standalone-adaptive.svg index f47474d..15207e4 100644 --- a/docs/architecture/standalone-adaptive.svg +++ b/docs/architecture/standalone-adaptive.svg @@ -1,10 +1,10 @@ - + Production architecture · Adaptive (dark/light via prefers-color-scheme) - Same data as standalone.svg, but uses CSS @media (prefers-color-scheme: light) - to swap colors when the viewer's browser is in light mode. Gitea 1.27 always - renders in dark (the OS theme follows browser default for goldmark preview). + Cluster overview. Snapshot 2026-08-27. + Yellow numbered circles = physical hosts (1=odroid, 2=xu4). + "lan" = the shared LAN 192.168.1.0/24 segment between Keenetic and the swarm hosts. @@ -59,113 +93,267 @@ + + + - - + + Production architecture · Adaptive (dark/light) - - Open standalone-adaptive.svg directly to see prefers-color-scheme adapt to your browser/OS theme. - - - - - EXTERNAL (LAN) - - Client - - Tailscale - - Keenetic - DNS + TLS - - - - DOCKER SWARM CLUSTER - - - - odroid (manager) · 192.168.1.96 - - - - swarm ingress - 10.0.0.2 - (routing mesh) - - + + + - - gitea - server · runner - .235 / .17.13 - .235 / .3.134 - - - hermes - agent · gateway - .204 - - - hermes_infra - squid · sarg · ui - docker_proxy - brencher-state - .106-108 - - - immich - server · db - redis · ml - .225 + + Client + из tailscale-сети - + + + - - brencher - + brencher2 - deploy tools - .105 / .102 + + lan + 192.168.1.0/24 - - gmail_mcp - gmail + telegram - MCP servers - .6 / .10 + + + Keenetic router + DNS · Let's Encrypt · TLS termination + 192.168.1.1 - - torrserv_proxy - reverseproxy - fileserver - .15 / .12 + + + Tailscale subnet + announces 192.168.1.0/24 + (runs on host 1) + + + Reachability: + + ● Client ⇄ Tailscale ⇄ Keenetic + + + ● Keenetic ⇄ host 1 (odroid):443 + + + ● host 1 (odroid) ⇄ host 2 (xu4) + + + ● Tailscale ⇄ host 1 (odroid) + + + ● ANY stack ⇄ ANY stack (overlay mesh) + + + ● Client ❌ host 2 direct (no route) + + + ● Client ❌ gitea:3000 (no port forward) + + + ● ANY stack ⇄ Keenetic (LAN gw) + + + ● ANY stack ⇄ Tailscale (via host 1) + + + ● gitea ❌ nginx_nginx (dead, no flow) + + + ● brencher ⇄ admin/ansible git (git pull) + + + ● stacks ⇄ external DNS via Keenetic + + + ● brencher ⇄ stacks (deploys via docker socket) + - - - nginx_nginx (dead) - jwilder/nginx-proxy · Replicas: 0 - overlay-сеть nginx_ingress (10.0.3.0/24) жива + + + + + DOCKER SWARM CLUSTER - - - xu4 (worker) - - worker tasks - (пусто в снапшоте 2026-08-27) + + + - - - - - - + + + 1 - - adaptive SVG · prefers-color-scheme: light/dark · open standalone-adaptive.svg directly in browser + odroid (manager) + 192.168.1.96 · arm64 · Linux 5.15 + j9bljgaqh9qc · 192.168.1.96:443 (Keenetic TLS term target) + + + + swarm ingress + 10.0.0.2 + (routing mesh) + + + + gitea + server · runner + .235 / .17.13 + .3.134 + + + hermes + agent · gateway + .204 + .11.x + + + hermes_infra + squid · sarg · ui + docker_proxy + brencher-state + .106-108 + + + + brencher + + brencher2 + deploy tools + .105 / .102 + + + gmail_mcp + gmail + telegram + MCP servers + .6 / .10 + + + torrserv_proxy + reverseproxy + fileserver + .15 / .12 + + + + nginx_nginx (dead) + jwilder/nginx-proxy · Replicas: 0 + overlay-сеть nginx_ingress (10.0.3.0/24) жива, контейнеров нет + + + + Tailscale daemon (хост 1) + advertises 192.168.1.0/24 как subnet router + 100.x.x.x для tailscale-клиентов вне LAN + + + + + + + + + 2 + + xu4 (worker) + id=u2ynmimtl0lu + tasks: пусто в снапшоте 2026-08-27 + + + worker tasks + ожидаются будущие сервисы + .5-6 (например brencher_local2) + .2 (например immich ml сейчас тут?) + + + + + ↔ swarm + manager-worker + + + + + + + + https + + + + + + + TLS term → + plain HTTP + + + + swarm + + + + + + + + + cross-node via swarm mesh (если бы task был на xu4) + + + + + + + + + + LEGEND + + + + 1 + физический хост (N=odroid, 2=xu4) + + + + сеть lan (192.168.1.0/24) + + + + swarm node (физический хост) + + + + stack (running service) + + + + routing mesh / ingress + + + + dead / disabled service + + + + solid = reach / flow + + + dashed rose = deploy / dead + + + amber = LAN traffic + + + + + adaptive SVG · prefers-color-scheme: light/dark · open standalone-adaptive.svg directly in browser · snapshot 2026-08-27 diff --git a/docs/architecture/svg-adaptive.md b/docs/architecture/svg-adaptive.md index 2fb0d43..f72ed63 100644 --- a/docs/architecture/svg-adaptive.md +++ b/docs/architecture/svg-adaptive.md @@ -1,57 +1,55 @@ # Production architecture (adaptive SVG variant) -> **Вариант №8:** тот же SVG, но с **CSS @media (prefers-color-scheme)** для автоматической -> смены тёмной/светлой темы в зависимости от темы браузера читателя. +> **Финальный вариант** — один SVG с автоматической адаптацией тёмной/светлой темы. +> Рендерится inline в Gitea preview, читается везде. ## Диаграмма ![Production architecture (adaptive)](./standalone-adaptive.svg) -## Как проверить +## Что показывает -1. Открой [`./standalone-adaptive.svg`](./standalone-adaptive.svg) напрямую в браузере -2. Переключи тему браузера: - - **Chrome/Edge:** `chrome://flags/#enable-force-dark` или DevTools → Rendering → "Emulate CSS prefers-color-scheme" - - **Firefox:** `about:config` → `ui.systemUsesDarkTheme` = 1/0 -3. SVG должен сменить цветовую палитру +- **Сеть `lan`** (192.168.1.0/24) — отдельный amber-bordered блок, соединяет Keenetic с физическими хостами +- **Жёлтые кружки с цифрами** на каждом физическом хосте: + - **① odroid** (manager) — id `j9bljgaqh9qc`, 192.168.1.96, arm64 + - **② xu4** (worker) — id `u2ynmimtl0lu`, пуст в снапшоте +- **6 стеков на odroid** (gitea, hermes, hermes_infra, immich, brencher, gmail_mcp, torrserv_proxy) + dead `nginx_nginx` (Replicas=0) +- **Reachability** — кто кого видит (зелёные ● = да, красные ● = нет), с конкретными flow'ами: + - Client ⇄ Tailscale ⇄ Keenetic + - Keenetic ⇄ odroid:443 (TLS term target) + - odroid ⇄ xu4 (swarm manager-worker) + - **Cross-node** через swarm mesh (если бы task был на xu4) + - **Brake:** gitea ❌ nginx_nginx (dead, нет flow) + - **Brake:** Client ❌ gitea:3000 напрямую (нет port forwarding) -## Палитры +## Как читать -### Dark (default) -- Background: `#020617` (slate-950) -- Stacks: `#0c4a6e` / stroke `#22d3ee` (cyan) -- Nodes: `#0f172a` / stroke `#fbbf24` (amber) -- Edge (ingress): `#064e3b` / stroke `#34d399` (emerald) -- Dead: `#1f1717` / stroke `#fb7185` (rose, dashed) -- External: `#1e293b` / stroke `#94a3b8` (slate) +1. **Слева** — `lan` блок (amber) с Keenetic и Tailscale subnet router +2. **В центре** — `odroid (①)` со всеми стеками +3. **Справа** — `xu4 (②)` (пустой, готов принимать tasks) +4. **Жёлтые стрелки (amber)** = LAN трафик, **белые сплошные** = reach, **розовые dashed** = deploy / dead -### Light (через `@media (prefers-color-scheme: light)`) -- Background: `#f8fafc` (slate-50) -- Stacks: `#ecfeff` / stroke `#0e7490` (cyan-700) -- Nodes: `#fffbeb` / stroke `#b45309` (amber-700) -- Edge: `#ecfdf5` / stroke `#047857` (emerald-700) -- Dead: `#fff1f2` / stroke `#be123c` (rose-700) -- External: `#e2e8f0` / stroke `#64748b` (slate-500) +## Reachability легенда -## Плюсы / минусы +Зелёная `●` = "видит и может связаться", красная `●` = "не видит / нет маршрута". -**+** Один файл работает в обеих темах — никаких дубликатов. -**+** Автоматически адаптируется к предпочтениям пользователя. -**+** Использует стандартный CSS, не нужен JS. -**-** Gitea preview в `/media/...svg` всегда отдаёт SVG как есть, но **рендерит внутри ``** который **не реагирует на `prefers-color-scheme`** (img-isolation). Адаптация работает только при прямом открытии SVG в браузере. -**-** Если пользователь читает SVG через `` в Gitea — увидит только дефолтную (тёмную) тему. -**-** Дублирование: тот же граф в standalone.svg, но с другой логикой цветов. +## Как проверить light theme -## Когда использовать +Открой [`./standalone-adaptive.svg`](./standalone-adaptive.svg) напрямую в браузере, переключи тему: -- Когда важно чтобы SVG был читаемым при печати (где часто светлая тема) -- Когда показываешь SVG вне Gitea (внешние пользователи, документация) -- Когда в команде есть пользователи с light-mode ОС +- **Chrome/Edge:** DevTools → Rendering → "Emulate CSS prefers-color-scheme" +- **Firefox:** `about:config` → `ui.systemUsesDarkTheme` -В **нашем Gitea preview** адаптация **не работает** (img-isolation ломает media query), -поэтому практической пользы от этого варианта мало — оставлен для сравнения. +## Файлы в этой папке + +| Файл | Что это | +|---|---| +| `standalone-adaptive.svg` | Собственно SVG (single file, адаптивный) | +| `svg-adaptive.md` | Этот файл — обёртка с описанием | +| `README.md` | История решений, что было отброшено | ## Связанные -- `standalone.svg` — фиксированная тёмная тема (этот файл используется везде) -- `standalone.html` — inline SVG с CSS, реагирует на тему браузера (но не рендерится в Gitea preview) +- `admin/ansible#5` — re-deploy `hermes_squid` +- `admin/ansible#6` — pre-create `socket_proxy` overlay +- `admin/ansible#7` — gitea stack deploy / app.ini fix