Codex
71e2fef4d9
UTF-8 without BOM + chcp 65001 showed '????' because cmd reads .bat under the OEM codepage, not chcp. A UTF-8 BOM makes cmd read the file as UTF-8 regardless of the console codepage; verified Cyrillic in echo/set/for displays correctly even when cmd starts at cp866. AGENTS.md updated accordingly.
111 lines
9.4 KiB
Markdown
111 lines
9.4 KiB
Markdown
# AGENTS.md
|
||
|
||
Руководство для агентов (и людей), работающих с этим репозиторием.
|
||
|
||
## Сопровождение этого файла (ВАЖНО)
|
||
|
||
- **AGENTS.md должен отражать актуальное состояние кода.** Это живой документ,
|
||
а не одноразовая справка.
|
||
- При любом изменении, влияющем на: архитектуру, состав пакетов/файлов, флаги
|
||
CLI или env-переменные (`WEBVNC_*`), протокол/поведение гейтвея, скрипты,
|
||
кодировки файлов, процесс сборки/запуска или известные ограничения —
|
||
**обязательно обнови соответствующий раздел AGENTS.md в том же коммите**.
|
||
- Если заметил расхождение между AGENTS.md и реальным кодом (функция переименована,
|
||
файл удалён, флаг изменён и т.п.) — сначала приведи AGENTS.md в соответствие
|
||
с кодом, затем продолжай работу. Не оставляй устаревшие инструкции.
|
||
- Коммит, меняющий поведение/структуру, но не трогающий AGENTS.md при расхождении,
|
||
считается неполным.
|
||
## Что это
|
||
|
||
`web-vnc` — один Go-бинарник, который открывает доступ к рабочему столу (VNC)
|
||
через браузер (noVNC) с защитой по паролю. Гейтвей сам раздаёт noVNC-клиент,
|
||
проверяет пароль, ставит HMAC-сессию и прозрачно релеит WebSocket браузера в
|
||
TCP VNC-сервера (RFB). Опционально сам находит и запускает VNC-сервер.
|
||
|
||
## Ключевые принципы (НЕ нарушать)
|
||
|
||
- **Только стандартная библиотека Go.** Внешних Go-модулей нет и быть не должно —
|
||
проект собирается офлайн (в среде сборки нет интернета/Go-proxy).
|
||
WebSocket (RFC 6455) и хэш пароля (PBKDF2-HMAC-SHA256) реализованы вручную
|
||
в `internal/relay` и `internal/auth`.
|
||
- **noVNC-клиент скачивается отдельно** (`scripts/get-novnc.*`) во встроенную
|
||
статику `internal/server/static/`. Эти папки (`core/`,`app/`,`vendor/`,
|
||
`utils/`,`novnc-original.html`) в git не коммитятся (см. `.gitignore`).
|
||
Наша собственная обёртка — `internal/server/static/vnc.html` (коммитится).
|
||
- **Пароль** — один общий для всех (по требованию). Веб-пароль (PBKDF2) хранится
|
||
как `--password-hash`; тот же пароль может передаваться VNC-серверу через
|
||
`--vnc-password`/`WEBVNC_VNC_PASSWORD`, чтобы noVNC авторизовался
|
||
автоматически (одно поле ввода для пользователя).
|
||
|
||
## Сборка и запуск
|
||
|
||
```powershell
|
||
# среда без интернета: Go уже установлен, прокси недоступен -> stdlib-only
|
||
$env:GOCACHE = "$env:TEMP\go-build" # дефолтный кэш бывает без прав на запись
|
||
go build -o web-vnc.exe ./cmd/web-vnc
|
||
.\web-vnc.exe --gen-hash "пароль" # напечатает хэш
|
||
.\web-vnc.exe --password-hash <хэш> --spawn
|
||
```
|
||
|
||
Проверка: `go vet ./...`, `gofmt -l internal cmd` (должно быть пусто).
|
||
|
||
## Структура
|
||
|
||
```
|
||
cmd/web-vnc/main.go CLI: флаги, спавн VNC, запуск сервера, --gen-hash
|
||
internal/config флаги + env (WEBVNC_*)
|
||
internal/auth PBKDF2-HMAC-SHA256, HMAC session-cookie, rate-limit
|
||
internal/relay websocket.go — RFC6455 на stdlib; relay.go — WS<->TCP
|
||
internal/vncspawner кросс-ОС поиск/запуск VNC-сервера (build-теги по ОС)
|
||
internal/server HTTP-роуты, /api/status, middleware сессии, embed.FS
|
||
internal/server/static встроенные ассеты (vnc.html + noVNC core/app/vendor)
|
||
scripts/get-novnc.{ps1,sh} скачать noVNC
|
||
scripts/get-vnc.ps1 скачать портативный UltraVNC в vnc/ (с верификацией zip)
|
||
scripts/list-ips.ps1 список IPv4 машины (используется run.bat)
|
||
scripts/open-firewall.bat открыть порт 8080 в Windows Firewall (от админа)
|
||
scripts/ensure-vnc-password.ps1 синхронизирует VNC-пароль UltraVNC с паролем из run.bat (пишет только при несовпадении; UAC только при смене) — вызывается из run.bat
|
||
run.bat запуск в один клик (спрашивает только пароль); синхронизирует VNC-пароль UltraVNC с введённым (см. ensure-vnc-password.ps1); если 5900 уже занят (сервис UltraVNC) — не порождает второй VNC-сервер, а подключается к существующему
|
||
```
|
||
|
||
## Соглашения и подводные камни
|
||
|
||
- **Кодировка файлов `.bat`:** **UTF-8 с BOM**, окончания строк **CRLF**, и `chcp 65001 >nul`
|
||
после `@echo off`. Именно **BOM** заставляет `cmd` читать .bat как UTF-8 независимо
|
||
от OEM-кодировки консоли (без BOM + `chcp 65001` в `cmd` даёт `????` — cmd читает
|
||
файл по OEM-кодировке, а не по `chcp`). BOM + `chcp 65001` проверено: кириллица в
|
||
`echo`/`set /p`/`for /f` отображается корректно, `@echo off` работает. Альтернатива
|
||
без BOM — включить системную опцию «Beta: Use Unicode UTF-8 for worldwide language
|
||
support» (тогда OEM-кодировка = 65001), но это влияет на всю систему (нужен reboot,
|
||
могут ломаться legacy-приложения под cp866/cp1251) — поэтому по умолчанию BOM.
|
||
Пиши через `[System.IO.File]::WriteAllText(path, content -replace "(?<!\r)\n","`r`n", [Text.UTF8Encoding]::new($true))`.
|
||
- **Go-файлы:** UTF-8 **без BOM**, LF. То же самое правило — не использовать
|
||
`Set-Content -Encoding UTF8` (ставит BOM). Используй
|
||
`[System.IO.File]::WriteAllText(path, content, [Text.UTF8Encoding]::new($false))`.
|
||
- **`.gitignore`:** бинарники игнорируются **root-anchored** (`/web-vnc`,
|
||
`/web-vnc.exe`), иначе шаблон `web-vnc` ловит пакет `cmd/web-vnc/`.
|
||
- **vncspawner:** функции поиска VNC-сервера определены через build-теги
|
||
(`detect_windows.go`/`detect_linux.go`/`detect_darwin.go`), каждый файл
|
||
определяет `func candidates() []Candidate`. Не ссылаться на
|
||
платформо-специфичные функции из общих файлов.
|
||
- **Тесты в этой среде:** интернет отсутствует; проверяй через локальные
|
||
заглушки (TCP-эхо-сервер на 5900, `Get-NetIPAddress` часто пуст —
|
||
`list-ips.ps1` имеет фолбэк на `ipconfig`). Запущенный web-vnc.exe из
|
||
фонового job может остаться «зомби» (Stop-Process иногда access denied);
|
||
используй разные порты для тестов и по возможности запускай killable-способом.
|
||
- **Hijack WebSocket:** `internal/relay` сам делает апгрейд через
|
||
`http.Hijacker`; гейтвей НЕ использует gorilla/websocket.
|
||
|
||
## Что делать дальше (известные TODO)
|
||
|
||
- Надёжный авто-скачиватель VNC-сервера (URL UltraVNC на SourceForge нестабилен —
|
||
`get-vnc.ps1` теперь верифицирует zip-магию и даёт фолбэк на ручную установку).
|
||
- На Windows захват экрана может требовать запуск VNC-сервера от администратора.
|
||
- VNC-сервер требует свой пароль; `--vnc-password` передаёт его noVNC
|
||
автоматически, но пароль VNC-сервера нужно один раз настроить под тот же.
|
||
**UltraVNC как сервис (`uvnc_service`, LocalSystem):** пароль хранится в
|
||
`%ProgramData%\UltraVNC\ultravnc.ini`; задать его обычным пользователем через
|
||
tray-иконку молча не получается (нет прав на запись).
|
||
`run.bat` синхронизирует этот пароль сам через `scripts/ensure-vnc-password.ps1`
|
||
(пишет только при несовпадении; UAC только при смене пароля). VNC-пароль = первые 8 байт,
|
||
поэтому используй ASCII-пароль <= 8 символов и там, и в `run.bat`.
|