diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 6ada173..e7de788 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -1,69 +1,80 @@ # 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. -## Что показывает +## Что показывает (все варианты) -- 2 swarm nodes: **odroid** (manager, 192.168.1.96) и **xu4** (worker, пуст в снапшоте) +- 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 component: `nginx_nginx` (jwilder/nginx-proxy, Replicas=0) -- Deploy flow: brencher → стеки +- Dead: `nginx_nginx` (Replicas=0) — overlay-сеть nginx_ingress жива +- Deploy flow: brencher → стеки (dashed rose arrows) ## Что НЕ показывает (для следующих уровней) -- Каждый отдельный контейнер и его IP в overlay-сетях -- Volume mounts и где лежат данные (особенно `gitea_data` NFS на 192.168.1.96) +- Каждый отдельный контейнер в overlay-сетях +- Volume mounts и где лежат данные - Swarm secrets (LFS_JWT_SECRET, JWT_SECRET, INTERNAL_TOKEN) -- DNS-резолвинг детально (search `anoa-bebop.ts.net`, ExtServers 192.168.1.1) -- Traffic flow конкретных сервисов (gmail MCP, immich ML pipeline и т.д.) +- DNS-резолвинг детально +- Traffic flow конкретных сервисов -## Известные неточности (TODO перед фиксацией) +## Известные неточности (TODO) -1. `endpoint.Ports` у gitea_server пустое, но ingress маршрутизирует — legacy endpoint или ручной `docker service update --publish-add`. -2. `xu4` worker пуст в снапшоте — перепроверить перед merge. -3. `nginx_nginx` Replicas=0 — dead, но overlay-сеть `nginx_ingress` (10.0.3.0/24) жива. -4. Tailscale роль — subnet router (подтверждено), но MagicDNS для `rudolf.keenetic.link` неизвестно. -5. brencher-stack-compose для каждого стека отсутствует в `admin/ansible` (только `poc/*`) — долг. +1. `endpoint.Ports` у gitea_server пустое, но ingress маршрутизирует — legacy. +2. `xu4` worker пуст в снапшоте. +3. `nginx_nginx` Replicas=0 — dead. +4. Tailscale роль (subnet router) требует подтверждения. +5. brencher-stack-compose для каждого стека отсутствует в `admin/ansible`. ## Варианты -| Файл | Формат | Где рендерится | Плюсы | Минусы | +| # | Файл | Формат | Где рендерится | Комментарий | |---|---|---|---|---| -| `mermaid.md` | Markdown + Mermaid | Gitea UI, PR preview, любой MD-рендерер | Diff-friendly, версионируется, не требует внешних тулзов | Стиль спартанский, нет полного layout-control | -| `standalone.svg` | Raw SVG | Браузер, можно вставить в README/wiki/slack | Single file, no deps, точный layout | Ручная правка, нет динамики | -| `standalone.html` | HTML + inline SVG + dark theme | Браузер | Красиво (pulsing dot, summary cards), single file, no JS | Не рендерится в Gitea preview, нужен браузер | +| 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 | Работает везде, не зависит от рендерера | -## Какой выбрать +## Рекомендация после тестов -**Если важно версионировать и видеть diff в PR** → `mermaid.md`. Он рендерится прямо в Gitea. +| Цель | Использовать | +|---|---| +| 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` | -**Если важно показать всем (внешним людям, в презентации, в slack)** → `standalone.html`. Открывается в браузере, выглядит презентабельно. +## Что работает в Gitea 1.27 preview (проверено через `/api/v1/markdown`) -**Если нужен в README.md файле как изображение** → `standalone.svg`. Вставляется как `![arch](docs/architecture/standalone.svg)`. +| Синтаксис | Результат | +|---|---| +| `![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#7` — gitea stack actually deploys (RCA для og:url warning) -- `admin/ansible#5` — re-deploy `hermes_squid` from feat/docker-socket-proxy-readonly -- `admin/ansible#6` — pre-create `socket_proxy` overlay network - -## Следующие уровни (если зайдёт этот стиль) - -- **Level 2 — Network diagram:** все 22 overlay-сети, какие контейнеры в каких, IP-адреса -- **Level 3 — Service topology:** gitea stack целиком (server + runner + volumes + secrets + DB) -- **Level 4 — Deploy flow:** brencher → git pull → docker stack deploy → brencher-state-proxy отчёт -- **Level 5 — Secrets/Vault:** где лежат LFS_JWT_SECRET, JWT_SECRET, gmail token, registry auth - -## Редактирование - -Все три файла можно править руками: -- `mermaid.md` — поменять Mermaid-блок -- `standalone.svg` — поменять ``, ``, `` -- `standalone.html` — поменять CSS или SVG-блок - -После правок пересмотри в браузере. Когда устаканится — коммить в `docs/architecture/` этого репо. +- `admin/ansible#5` — re-deploy `hermes_squid` +- `admin/ansible#6` — pre-create `socket_proxy` overlay +- `admin/ansible#7` — gitea stack deploy / app.ini fix diff --git a/docs/architecture/ascii.txt b/docs/architecture/ascii.txt new file mode 100644 index 0000000..f6d459a --- /dev/null +++ b/docs/architecture/ascii.txt @@ -0,0 +1,49 @@ +Production architecture — ASCII variant +===================================== + +Snapshot: 2026-08-27 +Sources: docker_socket_proxy + gitea admin API + gitea_server logs + +EXTERNAL (LAN 192.168.1.0/24) DOCKER SWARM CLUSTER ++------------------------------+ +-----------------------------------------------+ +| | | | +| ( Client ) | | odroid (manager) · 192.168.1.96 · arm64 | +| | | | | +| v | | +------------+ +------------------+ | +| +---------+ +---------+ | | | ingress | | Stacks | | +| |Tailscale|-->|Keenetic |---+-----------> | 10.0.0.2 |----->| | | +| | (subnet)| |DNS+TLS | | | +------------+ | +----+ +----+ | | +| +---------+ +---------+ | | | | |git | |herm| | | +| | | | | | ea | | es | | | +| | | v | +----+ +----+ | | +| | | +---------------+ | | | ++------------------------------+ | | gitea_server | | (7 stacks total) | | + | | .235 / 3000 | | | | + | +---------------+ +------------------+ | + | | + | nginx_nginx (dead) — Replicas: 0 | + | | + | xu4 (worker) | + | worker tasks: (пусто в снапшоте) | + +-----------------------------------------------+ + +Flow: + Client → Tailscale (subnet router) → Keenetic (DNS, Let's Encrypt TLS term) + → plain HTTP → swarm ingress-endpoint (10.0.0.2) → gitea_server + +Brencher deploys: gitea, immich, hermes_infra (через git pull + docker stack deploy) + +Overlay networks (22 total): + ingress 10.0.0.0/24 ← все сервисы на swarm mesh + gitea_gitea 10.0.17.0/24 ← gitea_stack + nginx_ingress 10.0.3.0/24 ← для nginx-proxy (но Replicas=0) + immich 10.0.2.0/24 + hermes_infra_* 10.0.12-15.0/24 + brencher* 10.0.5-7.0/24 + +Nodes: + odroid manager j9bljgaqh9qc Linux 5.15 ARM64 192.168.1.96 + xu4 worker u2ynmimtl0lu (tasks empty in snapshot) + +Dead/disabled: + nginx_nginx jwilder/nginx-proxy Replicas=0 (overlay-сеть nginx_ingress жива)