From 7a6b1a84cc5eb41fb19e26f43f4d2bfc0dda8fa2 Mon Sep 17 00:00:00 2001 From: Aleksey Sabilin Date: Mon, 27 Jul 2026 13:25:00 +0300 Subject: [PATCH] Docs: stage access is direct HTTPS (*.calentiq.com); :8787 proxy is DNS fallback only. [skip ci] --- .cursor/rules/stage-browser.mdc | 12 ++--- README.md | 2 +- STAGE-BROWSER.md | 68 ++++++++++++++++++--------- WORKFLOW.md | 10 ++-- scripts/stage-browser-alias-proxy.mjs | 14 ++++-- 5 files changed, 68 insertions(+), 38 deletions(-) diff --git a/.cursor/rules/stage-browser.mdc b/.cursor/rules/stage-browser.mdc index af3807a..5ba6690 100644 --- a/.cursor/rules/stage-browser.mdc +++ b/.cursor/rules/stage-browser.mdc @@ -1,15 +1,15 @@ --- -description: Как открыть stage UI в Cursor Browser (alias + proxy) +description: Stage UI в Cursor Browser — прямой HTTPS; proxy только DNS-fallback alwaysApply: true --- # Stage browser (Cursor) -`*.eventhub.local` часто не резолвится в Chromium/Cursor Browser. +**Канон:** прямой HTTPS с валидным TLS/DNS: -Канон: **`http://ui.stage.eventhub.test:8787`** через локальный proxy. +- Client: `https://stage.calentiq.com/` +- Admin: `https://admin.stage.calentiq.com/` -Полная инструкция: `EventHubSpec/STAGE-BROWSER.md` -Скрипт: `EventHubSpec/scripts/stage-browser-alias-proxy.mjs` (запуск **Windows Node** на `:8787`). +Локальный proxy `http://ui.stage.eventhub.test:8787` (`scripts/stage-browser-alias-proxy.mjs`) — **только fallback**, если Cursor/Chromium не резолвит hostname. Не из‑за сертификата. -Hosts: `127.0.0.1 ui.stage.eventhub.test` +Полная инструкция: `EventHubSpec/STAGE-BROWSER.md` diff --git a/README.md b/README.md index d05cc71..9134280 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ ## 2. [EventHub Admin UI — Техническое задание](EventHubFrontAdminSpec.md) ## 3. [EventHub Client UI — Техническое задание](EventHubFrontSpec.md) ## 4. [Правила работы (workflow)](WORKFLOW.md) -## 5. [Stage UI в Cursor Browser](STAGE-BROWSER.md) +## 5. [Stage UI в Cursor Browser](STAGE-BROWSER.md) (HTTPS `*.calentiq.com`; proxy — fallback) ## 6. [UX backlog (Client UI)](UX-BACKLOG.md) # **Репозитории разработки EventHub** diff --git a/STAGE-BROWSER.md b/STAGE-BROWSER.md index 05e105b..e774d27 100644 --- a/STAGE-BROWSER.md +++ b/STAGE-BROWSER.md @@ -1,28 +1,58 @@ # Stage UI в Cursor Browser -Chromium / Cursor IDE Browser часто **не резолвят** `*.eventhub.local` (mDNS), даже если Windows/`nslookup` через OpenWRT уже видят stage. +Stage уже доступен по **публичному DNS с валидным TLS** (Let's Encrypt). Агенты и ручной просмотр **по умолчанию** ходят **напрямую по HTTPS** — без локального `:8787` proxy. -Для агентов и ручного просмотра stage используем **локальный alias + HTTP-прокси**. +Локальный alias-proxy — **только fallback**, если Cursor/Chromium не резолвит hostname stage (не из‑за сертификата). -## URL +Публичные URL стенда также зафиксированы в `EventHubDevOps/docs/STANDS.md` (раздел stage). + +## Канон (прямые HTTPS) + +| URL | Сервис | +|-----|--------| +| `https://stage.calentiq.com/` | client-ui | +| `https://admin.stage.calentiq.com/` | admin-ui | +| `https://api.stage.calentiq.com` | eventhub API | +| `https://ws.stage.calentiq.com` | WebSocket | +| `https://admin-api.stage.calentiq.com` | admin API | +| `https://calentiq.com` | 301 → `stage.calentiq.com` | + +Для агентского Cursor Browser обычно достаточно: + +- Client: `https://stage.calentiq.com/login` +- Admin: `https://admin.stage.calentiq.com/` + +Client/admin SPA ходят в API **same-origin** через nginx (`/v1/`, `/ws`). + +Внутренний QA (`*.stage.eventhub.local`) по-прежнему есть; для браузера агента **предпочтительны** публичные `*.calentiq.com` выше. + +## Auth / учётки + +- Smoke: `~/.cursor/secrets/eventhub-stage.env` (`SMOKE_USER_*`). +- IFT e2e: только `~/.cursor/secrets/eventhub-ift.env` (не подмешивать stage). +- Не коммитить пароли/токены из smoke env. + +## Fallback: локальный alias-proxy + +Использовать **только** если прямое открытие `https://stage.calentiq.com/` (или admin) в Cursor Browser не работает из‑за **DNS / резолва hostname** (например Chromium и `*.local`). Не поднимать proxy «на всякий случай» и не из‑за TLS — публичный cert валиден. | Открывать в браузере | Upstream | |----------------------|----------| -| `http://ui.stage.eventhub.test:8787` | `https://ui.stage.eventhub.local` → `195.208.119.190` | +| `http://ui.stage.eventhub.test:8787` | `https://ui.stage.eventhub.local` → stage IP | -## Одноразовая настройка hosts +### Hosts (только для fallback) -В `C:\Windows\System32\drivers\etc\hosts` (или WSL `/etc/hosts` не помогает Cursor на Windows): +В `C:\Windows\System32\drivers\etc\hosts` (WSL `/etc/hosts` не помогает Cursor на Windows): ```text 127.0.0.1 ui.stage.eventhub.test ``` -## Прокси +### Прокси -Скрипт в репозитории: [`scripts/stage-browser-alias-proxy.mjs`](scripts/stage-browser-alias-proxy.mjs) +Скрипт: [`scripts/stage-browser-alias-proxy.mjs`](scripts/stage-browser-alias-proxy.mjs) -Копия для быстрого старта агента: `~/.cursor/eventhub/stage-browser-alias-proxy.mjs` (если есть — можно любой из двух). +Копия: `~/.cursor/eventhub/stage-browser-alias-proxy.mjs` (если есть — можно любой). **Важно:** процесс должен слушать на **Windows** `127.0.0.1:8787` (Node из Windows). Прокси только в WSL Cursor с Windows часто не достучится. @@ -32,18 +62,15 @@ Start-Process -FilePath "C:\Program Files\nodejs\node.exe" ` -WindowStyle Hidden ``` -Или из Spec (если скрипт уже скопирован в `~/.cursor/eventhub/`): +Или из корня EventHubSpec: ```powershell -# из корня EventHubSpec Start-Process -FilePath "C:\Program Files\nodejs\node.exe" ` -ArgumentList (Resolve-Path ".\scripts\stage-browser-alias-proxy.mjs") ` -WindowStyle Hidden ``` -Проверка: открыть `http://ui.stage.eventhub.test:8787/login`. - -Переменные окружения (опционально): +Проверка fallback: `http://ui.stage.eventhub.test:8787/login`. | Env | Default | |-----|---------| @@ -53,16 +80,11 @@ Start-Process -FilePath "C:\Program Files\nodejs\node.exe" ` | `STAGE_UI_HOST` | `ui.stage.eventhub.local` | | `ALIAS_HOST` | `ui.stage.eventhub.test` | -## Auth - -Same-origin через прокси: `/v1/login`, `/v1/register`, logout — как на настоящем stage. - -- Smoke: `~/.cursor/secrets/eventhub-stage.env` (`SMOKE_USER_*`). -- IFT e2e: только `~/.cursor/secrets/eventhub-ift.env` (не подмешивать stage). -- Прокси **не** подставляет пользователя: только Host/SNI rewrite на Traefik. +Прокси **не** подставляет пользователя: только Host/SNI rewrite на Traefik. ## Что не делать -- Не ждать, что Cursor Browser сам пойдёт на `https://ui.stage.eventhub.local`. -- Не поднимать прокси только в WSL, если агентский браузер на Windows. +- Не считать `:8787` / `ui.stage.eventhub.test` каноном — канон это `https://stage.calentiq.com` (и admin). +- Не поднимать proxy, пока не подтверждён сбой резолва прямого HTTPS. +- Не поднимать proxy только в WSL, если агентский браузер на Windows. - Не коммитить пароли/токены из smoke env. diff --git a/WORKFLOW.md b/WORKFLOW.md index 7cfaad3..12725c8 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -275,11 +275,12 @@ IFT и stage крутят **одну и ту же** сборку `sha-*`. Produc ### Stage UI в Cursor Browser -`*.eventhub.local` часто не резолвится в Chromium/Cursor IDE Browser (mDNS). Для ручного и агентского просмотра stage: +Stage: публичный DNS + валидный TLS. **Канон — прямой HTTPS** (не локальный `:8787`): -- URL: `http://ui.stage.eventhub.test:8787` -- Инструкция + proxy: **`STAGE-BROWSER.md`**, скрипт `scripts/stage-browser-alias-proxy.mjs` (Windows Node на `:8787`) -- Hosts: `127.0.0.1 ui.stage.eventhub.test` +- Client: `https://stage.calentiq.com/` +- Admin: `https://admin.stage.calentiq.com/` +- Инструкция: **`STAGE-BROWSER.md`** +- Proxy `ui.stage.eventhub.test:8787` — **только fallback** при сбое резолва hostname в Cursor/Chromium - Учётки smoke: `~/.cursor/secrets/eventhub-stage.env` (не коммитить) --- @@ -376,6 +377,7 @@ error rate > 1% **или** mean request > 500 ms (hold ≥2 мин в фазе) | Дата | Изменение | |------|-----------| +| 2026-07-27 | §6 / STAGE-BROWSER: канон — прямой HTTPS `*.calentiq.com`; proxy `:8787` только DNS-fallback | | 2026-07-22 | §6: Stage UI в Cursor Browser — `STAGE-BROWSER.md` + alias proxy | | 2026-07-22 | §2.1: Agent shell — не PowerShell для сложного; `.sh` + WSL; Front push только после lint/build/IFT | | 2026-07-15 | §7: анализ через EventHub `/metrics` + admin `nodes/metrics`; compose Prom опционален | diff --git a/scripts/stage-browser-alias-proxy.mjs b/scripts/stage-browser-alias-proxy.mjs index 02f470e..abe2c7b 100644 --- a/scripts/stage-browser-alias-proxy.mjs +++ b/scripts/stage-browser-alias-proxy.mjs @@ -1,10 +1,16 @@ #!/usr/bin/env node /** - * Cursor-browser alias for stage UI. + * Optional DNS fallback for Cursor browser → internal stage UI. * - * Why: Chromium treats *.local as mDNS and often ignores unicast DNS / hosts. - * This proxy serves http://ui.stage.eventhub.test:8787 → https://stage - * with Host/SNI ui.stage.eventhub.local (Traefik + existing cert). + * Canonical access is direct HTTPS (valid public DNS + TLS): + * https://stage.calentiq.com/ (client) + * https://admin.stage.calentiq.com/ + * + * Use this proxy ONLY when Cursor/Chromium cannot resolve the stage hostname + * (e.g. *.local mDNS quirks) — not because of certificates. + * + * Serves http://ui.stage.eventhub.test:8787 → https://ui.stage.eventhub.local + * with Host/SNI rewrite for Traefik. * * Usage: * node stage-browser-alias-proxy.mjs