EventHub/EventHubSpec
3
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs: stage access is direct HTTPS (*.calentiq.com); :8787 proxy is DNS fallback only. [skip ci]

Browse Source
This commit is contained in:
Aleksey Sabilin
2026-07-27 13:25:00 +03:00
parent 01904e9873
commit 7a6b1a84cc
5 changed files with 68 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/rules/stage-browser.mdc
+6 -6
View File
@@ -1,15 +1,15 @@
--- ---
description: Как открыть stage UI в Cursor Browser (alias + proxy) description: Stage UI в Cursor Browser — прямой HTTPS; proxy только DNS-fallback
alwaysApply: true alwaysApply: true
--- ---
# Stage browser (Cursor) # 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` Локальный proxy `http://ui.stage.eventhub.test:8787` (`scripts/stage-browser-alias-proxy.mjs`) — **только fallback**, если Cursor/Chromium не резолвит hostname. Не из‑за сертификата.
Скрипт: `EventHubSpec/scripts/stage-browser-alias-proxy.mjs` (запуск **Windows Node** на `:8787`).
Hosts: `127.0.0.1 ui.stage.eventhub.test` Полная инструкция: `EventHubSpec/STAGE-BROWSER.md`
README.md
+1 -1
View File
@@ -3,7 +3,7 @@
## 2. [EventHub Admin UI — Техническое задание](EventHubFrontAdminSpec.md) ## 2. [EventHub Admin UI — Техническое задание](EventHubFrontAdminSpec.md)
## 3. [EventHub Client UI — Техническое задание](EventHubFrontSpec.md) ## 3. [EventHub Client UI — Техническое задание](EventHubFrontSpec.md)
## 4. [Правила работы (workflow)](WORKFLOW.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) ## 6. [UX backlog (Client UI)](UX-BACKLOG.md)
# **Репозитории разработки EventHub** # **Репозитории разработки EventHub**
STAGE-BROWSER.md
+45 -23
View File
@@ -1,28 +1,58 @@
# Stage UI в Cursor Browser # 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 | | Открывать в браузере | 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 ```text
127.0.0.1 ui.stage.eventhub.test 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 часто не достучится. **Важно:** процесс должен слушать на **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 -WindowStyle Hidden
``` ```
Или из Spec (если скрипт уже скопирован в `~/.cursor/eventhub/`): Или из корня EventHubSpec:
```powershell ```powershell
# из корня EventHubSpec
Start-Process -FilePath "C:\Program Files\nodejs\node.exe" ` Start-Process -FilePath "C:\Program Files\nodejs\node.exe" `
-ArgumentList (Resolve-Path ".\scripts\stage-browser-alias-proxy.mjs") ` -ArgumentList (Resolve-Path ".\scripts\stage-browser-alias-proxy.mjs") `
-WindowStyle Hidden -WindowStyle Hidden
``` ```
Проверка: открыть `http://ui.stage.eventhub.test:8787/login`. Проверка fallback: `http://ui.stage.eventhub.test:8787/login`.
Переменные окружения (опционально):
| Env | Default | | Env | Default |
|-----|---------| |-----|---------|
@@ -53,16 +80,11 @@ Start-Process -FilePath "C:\Program Files\nodejs\node.exe" `
| `STAGE_UI_HOST` | `ui.stage.eventhub.local` | | `STAGE_UI_HOST` | `ui.stage.eventhub.local` |
| `ALIAS_HOST` | `ui.stage.eventhub.test` | | `ALIAS_HOST` | `ui.stage.eventhub.test` |
## Auth Прокси **не** подставляет пользователя: только Host/SNI rewrite на Traefik.
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.
## Что не делать ## Что не делать
- Не ждать, что Cursor Browser сам пойдёт на `https://ui.stage.eventhub.local`. - Не считать `:8787` / `ui.stage.eventhub.test` каноном — канон это `https://stage.calentiq.com` (и admin).
- Не поднимать прокси только в WSL, если агентский браузер на Windows. - Не поднимать proxy, пока не подтверждён сбой резолва прямого HTTPS.
- Не поднимать proxy только в WSL, если агентский браузер на Windows.
- Не коммитить пароли/токены из smoke env. - Не коммитить пароли/токены из smoke env.
WORKFLOW.md
+6 -4
View File
@@ -275,11 +275,12 @@ IFT и stage крутят **одну и ту же** сборку `sha-*`. Produc
### Stage UI в Cursor Browser ### Stage UI в Cursor Browser
`*.eventhub.local` часто не резолвится в Chromium/Cursor IDE Browser (mDNS). Для ручного и агентского просмотра stage: Stage: публичный DNS + валидный TLS. **Канон — прямой HTTPS** (не локальный `:8787`):
- URL: `http://ui.stage.eventhub.test:8787` - Client: `https://stage.calentiq.com/`
- Инструкция + proxy: **`STAGE-BROWSER.md`**, скрипт `scripts/stage-browser-alias-proxy.mjs` (Windows Node на `:8787`) - Admin: `https://admin.stage.calentiq.com/`
- Hosts: `127.0.0.1 ui.stage.eventhub.test` - Инструкция: **`STAGE-BROWSER.md`**
- Proxy `ui.stage.eventhub.test:8787` — **только fallback** при сбое резолва hostname в Cursor/Chromium
- Учётки smoke: `~/.cursor/secrets/eventhub-stage.env` (не коммитить) - Учётки 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 | §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-22 | §2.1: Agent shell — не PowerShell для сложного; `.sh` + WSL; Front push только после lint/build/IFT |
| 2026-07-15 | §7: анализ через EventHub `/metrics` + admin `nodes/metrics`; compose Prom опционален | | 2026-07-15 | §7: анализ через EventHub `/metrics` + admin `nodes/metrics`; compose Prom опционален |
scripts/stage-browser-alias-proxy.mjs
+10 -4
View File
@@ -1,10 +1,16 @@
#!/usr/bin/env node #!/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. * Canonical access is direct HTTPS (valid public DNS + TLS):
* This proxy serves http://ui.stage.eventhub.test:8787 → https://stage * https://stage.calentiq.com/ (client)
* with Host/SNI ui.stage.eventhub.local (Traefik + existing cert). * 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: * Usage:
* node stage-browser-alias-proxy.mjs * node stage-browser-alias-proxy.mjs