docs: record redirect-to-VM architecture and deploy steps

2026-09-02 18:40:54 +03:00
parent 5360893b2a
commit 87399a35c9
1 changed files with 81 additions and 0 deletions
@@ -0,0 +1,81 @@
+# tf_docs: переход на 302-редирект + раздача через ВМ
+
+Дата: 2026-09-02
+
+## Проблема
+
+Отдача больших MkDocs-страниц (~133 KB) через под managed-кластера `nodejsk8s`
+захлёбывалась: `273 B/s` через `tf_docs` (за 80 c скачано 21 KB). Входной шлюз
+managed-кластера рвёт большие тела (как в drhider: шлюз режет >~64 KB, egress не ограничен).
+
+## Диагностика (замеры)
+
+| Путь → S3 | Скорость |
+|---|---|
+| `tf_docs` (кластер) | 273 B/s |
+| локальная машина (Node.js) | 24.5 KiB/s |
+| **ВМ `5.172.178.213`** | **5.6 MB/s** (133 KB за 0.023 с) |
+
+Вывод: S3 быстрый, медленный — путь от managed-кластера/внешней сети. ВМ имеет
+быстрый прямой канал до S3. Паттерн решения взят из drhider («ВМ-буфер», `~/nubes/HowTo/vm-file-upload-service.md`): большие данные — мимо шлюза кластера, через ВМ.
+
+## Решение (финальная архитектура)
+
+```
+Браузер → tf_docs (кластер, только 302) → ВМ nginx → статика (зеркало S3)
+```
+
+- `tf_docs` — тонкий редирект-роутер: `/health` + `302` на ВМ. Без S3, без стримов.
+- ВМ `5.172.178.213` — nginx раздаёт статику из локального зеркала S3.
+- URL без версий: `/nubes-test/...` → S3 `docs/nubes-test/nubes/...` (перезапись).
+
+## Изменения
+
+### `tf_docs` (репо, запушено `5360893`, версия `0.0.3`)
+
+- `server.js` — переписан на 302-роутер (сгенерирован DeepSeek Flash):
+  - `GET /health` → `200 ok`
+  - `GET /:stand/...` → `302 Location: ${VM_DOCS_BASE_URL}/:stand/...`
+  - убраны `@aws-sdk/client-s3`, S3-креды, стрим
+- `package.json` — `0.0.3`, зависимостей нет (чистый `http`).
+- `test/server.test.js` — 4 теста (health, redirect, root, 405) — PASS.
+- `.gitignore` — добавлен `deploy-vm/`.
+
+### `tf_docs/deploy-vm/` (локально, НЕ в git)
+
+- `nginx-tf-docs.conf` — location `/(nubes-test|nubes-dev|nubes)/` → статика `/var/www/tf-docs/`.
+- `mirror-s3.sh` — `mc mirror` из S3 `docs/<stand>/nubes/` → `/var/www/tf-docs/<stand>/`.
+- `README.md` — инструкция деплоя на ВМ.
+
+### `tf_provider` (репо, запушено `dc469c6`)
+
+- `scripts/publish-docs.sh` — заливка **без версии** (`docs/<ns>/<name>/`), перезапись `mc mirror --overwrite --remove`.
+- `TOOLS/scripts/04_build_and_publish_docs.sh` — `site_url: https://<host>/<namespace>/` (без name/version); `docs_dir` относительный (для docker-сборки); хост `tf-docs.nodejsk8s.dev.nubes.ru`.
+
+## Env tf_docs (jsonEnv в UI)
+
+```json
+{
+  "VM_DOCS_BASE_URL": "http://5.172.178.213"
+}
+```
+
+S3-креды `tf_docs` больше не нужны (не ходит в S3). Креды — только на ВМ в `mirror-s3.sh`.
+
+## Порядок деплоя
+
+1. **tf_docs**: redeploy в ЛК облака (образ из gitea `5360893`), env `VM_DOCS_BASE_URL`, health `/health`.
+2. **ВМ**: скопировать `deploy-vm/`, `./mirror-s3.sh nubes-test`, вставить nginx-конфиг, `nginx -t && reload`.
+3. **Перезалить документацию**: `04` + `publish-docs.sh` → `docs/nubes-test/nubes/` (без версии).
+
+## Проверка
+
+```bash
+curl -I https://tf-docs.nodejsk8s.dev.nubes.ru/nubes-test/   # 302 → ВМ
+curl -I http://5.172.178.213/nubes-test/                      # 200 index.html
+```
+
+## Урок (не повторять)
+
+- `kube5s.ru` — **legacy**, закрывается. Не использовать ни в коде, ни в доках.
+- HowTo-документация местами устарела (описывает legacy-домен как рабочий) — сверять с актуальными источниками.