docs: add ascii variant and refresh README

- ascii.txt: pure ASCII layout for terminals and where SVG doesn't render
- README: full table of all 10 variants with what-works-in-gitea-1.27 verification
This commit is contained in:
hermes
2026-08-27 12:08:33 +00:00
parent cd1956aaeb
commit 8672f0db37
2 changed files with 105 additions and 45 deletions
+56 -45
View File
@@ -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 → `<img>` SVG | Gitea UI | **Проверено** через `/api/v1/markdown` — работает |
| 3 | `svg-sized.md` | md → `<img>` с width | Gitea UI | Контроль размера (но `style` санитизируется) |
| 4 | `svg-inline.md` | inline SVG в `<details>` | Gitea UI | Можно зумить, но diff нечитаем |
| 5 | `svg-object.md` | md → `<object>` | **НЕ работает** в Gitea | goldmark вырезает; оставлен для справки |
| 6 | `svg-adaptive.md` | md → adaptive SVG | Gitea UI (только dark) | Светлая тема не работает через `<img>` (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)` | `<img src="/media/path.svg">` ✅ |
| `<img src="path.svg" width="600">` | `<img ... width="600">` ✅ |
| `<img src="path.svg" style="...">` | `<img ... >` без style ❌ |
| `<object data="path.svg">` | вырезается ❌ |
| `<svg>...</svg>` inline | рендерится (если внутри md) ✅ |
| `<details><summary>...</summary>...</details>` | рендерится ✅ |
## Коммиты в этой ветке
1. `docs: add production architecture diagram in three formats` — 3 базовых варианта
2. `docs: add svg-embedded variant` — `<img>` через 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` — поменять `<rect>`, `<text>`, `<path>`
- `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
+49
View File
@@ -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 жива)