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:
+56
-45
@@ -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`. Вставляется как ``.
|
||||
| Синтаксис | Результат |
|
||||
|---|---|
|
||||
| `` | `<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
|
||||
|
||||
@@ -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 жива)
|
||||
Reference in New Issue
Block a user