DeskVNCServer - Przewodnik

Pierwsze kroki

1. Ustaw hasło

Otwórz Ustawienia (ikona koła zębatego, dolny pasek narzędzi) i wypełnij hasło VNC. Standardowi klienci VNC używają RFB DES challenge, który respektuje tylko pierwsze 8 bajtów kompatybilnych z ASCII — wybierz hasło nie dłuższe niż 8 znaków.

2. Uruchom serwer

1. W oknie głównym kliknij Start. Wskaźnik stanu przełącza się na Running.
2. Naraz uruchamiane są cztery nasłuchy: VNC 5900, QREX control 5911, QREX media 4010 oraz file API 8766.
3. Kliknij Copy Info, aby skopiować jednolinijkowy tekst z hostem, portami i aktualnym PIN-em do schowka.

3. Połącz klienta

Dla standardowej przeglądarki VNC (macOS Screen Sharing, RealVNC, TightVNC, mobilne aplikacje VNC):

1. Otwórz przeglądarkę i jako adres wpisz vnc://<your-mac-ip>:5900
2. Wpisz hasło VNC ustawione w kroku 1
3. Natychmiast steruj swoim Makiem — klawiatura, mysz, kopiowanie/wklejanie przez RFB

Dla aplikacji QuickRemote:

1. Otwórz QuickRemote na telefonie lub tablecie i wybierz Add Mac
2. Wpisz 6-cyfrowy PIN parowania wyświetlony przez DeskVNCServer (lub zeskanuj kod QR, jeśli Twoja wersja QuickRemote to obsługuje)
3. QuickRemote zapisuje zwrócony Bearer token i odblokowuje rozszerzone funkcje — IME, audio, synchronizację schowka i przesyłanie plików

Przegląd interfejsu

Wiersz statusu

Przyciski akcji

• Start — Uruchamia wszystkie cztery nasłuchy.
• Stop — Zamyka każdy nasłuch i rozłącza aktywne sesje.
• Copy Info — Kopiuje krótkie podsumowanie połączenia (host, port VNC, port kontrolny, PIN) do schowka, aby łatwo udostępnić klientowi.

Panel połączenia

Wyświetla bind host, porty, aktualne Server ID i aktywny PIN parowania. Tekst jest automatycznie odświeżany przy zmianie ustawień.

Panel QuickRemote API

Szybkie odniesienie do protokołów, którymi posługuje się serwer. Wymienia obsługiwane wersje RFB, kształty endpointów QREX oraz zestaw komend IME, aby QuickRemote (lub Twój własny klient) wiedział, co jest dostępne.

Protokoły i porty

Uwierzytelnianie

• Klienci VNC — hasło RFB DES (pierwsze 8 bajtów skonfigurowanego hasła kompatybilnych z ASCII).
• Klienci QREX — Początkowa wymiana 6-cyfrowego PIN-u w POST /qr/v1/pair zwraca Bearer token. Każde kolejne wywołanie HTTP QREX i ramka WebSocket muszą zawierać Authorization: Bearer <token>.
• Jeśli hasło VNC jest puste, serwer ogłasza standardowy tryb RFB no-auth. Przydatne tylko dla zaufanych segmentów LAN.

Szybkie odniesienie do endpointów QREX

GET  /qr/v1/capabilities    # public, returns supported features
POST /qr/v1/pair            # public, exchange PIN for Bearer token
GET  /qr/v1/ws              # WebSocket, auth required
POST /qr/v1/ime/get         # auth required, query active IME
POST /qr/v1/ime/list        # auth required, list available IMEs
POST /qr/v1/ime/set         # auth required, switch IME
POST /qr/v1/ime/toggle      # auth required, toggle IME on/off
POST /qr/v1/ime/commit      # auth required, commit a text string

Ustawienia

Przykłady klientów

macOS Screen Sharing

1. Finder → Go → Connect to Server
2. Wpisz vnc://<your-mac-ip>:5900
3. Wprowadź hasło VNC

cURL — odkrywanie możliwości

curl http://<your-mac-ip>:5911/qr/v1/capabilities

cURL — parowanie i wywołanie IME bridge

# 1. Exchange the PIN for a Bearer token
TOKEN=$(curl -s http://<your-mac-ip>:5911/qr/v1/pair \
  -H "Content-Type: application/json" \
  -d '{"pin":"123456"}' | jq -r .token)

# 2. Commit text via the IME bridge
curl http://<your-mac-ip>:5911/qr/v1/ime/commit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"hello from remote"}'

Wskazówki

• Obniż liczbę klatek na sekundę i maksymalne wymiary klatki, gdy jesteś na wolnym łączu Wi-Fi lub kierujesz połączenie przez VPN.
• Każde urządzenie sparuj raz. Po początkowej wymianie PIN-u Bearer token przetrwa ponowne uruchomienia, więc QuickRemote łączy się ponownie po cichu.
• Użyj Copy Info jako szybkiego sposobu na wysłanie szczegółów połączenia przez czat lub e-mail — zawiera wszystko, czego potrzebuje klient.
• Pozostaw Enable file mutations wyłączone, chyba że naprawdę potrzebujesz przesyłania. Tryb tylko do odczytu wystarczy do przeglądania zrzutów ekranu, notatek lub pobranych plików.
• Wyłącz audio API, gdy go nie używasz. Bezczynne kodeki nadal kosztują niewielką ilość CPU na ścieżce kodowania.

Rozwiązywanie problemów

Serwer nie uruchamia się

• Inny serwer VNC (np. macOS Screen Sharing) może już być na porcie 5900. Zatrzymaj go w System Settings → General → Sharing lub zmień port w ustawieniach DeskVNCServer.
• Porty 5911 / 4010 / 8766 muszą być wszystkie wolne. Sprawdź za pomocą lsof -i :5911 i podobnych.

Klienci VNC nie mogą się uwierzytelnić

• Upewnij się, że hasło ma najwyżej 8 bajtów kompatybilnych z ASCII. Znaki wielobajtowe lub dłuższe ciągi są po cichu obcinane przez uwierzytelnianie RFB DES.
• Jeśli celowo nie chcesz hasła, pozostaw pole puste i połącz się przeglądarką, która obsługuje VNC no-auth.

QuickRemote nie może się sparować

• Potwierdź, że telefon lub tablet jest w tej samej sieci Wi-Fi co Mac.
• Otwórz panel Connection i przeczytaj PIN ponownie. PIN można zregenerować z Ustawień.
• Sprawdź ustawienia zapory macOS — połączenia przychodzące na portach QREX muszą być dozwolone.

Zdalne sterowanie jest opóźnione

• Obniż liczbę klatek na sekundę i maksymalne wymiary klatki w Ustawieniach.
• Wyłącz funkcje, których nie używasz (audio, schowek, IME), aby zwolnić CPU.

Pliki nie są przesyłane

• Potwierdź, że Enable file transfer jest włączone. Listowanie tylko do odczytu działa bez Enable file mutations.
• Jeśli przesyłanie się nie powiedzie, włącz również Enable file mutations. W przeciwnym razie file API odpowiada tylko na żądania odczytu.

Prywatność

• Wszystkie sesje działają bezpośrednio między klientem a Twoim Makiem. Nie ma przekaźnika w chmurze, telemetrii ani analityki.
• Hasło VNC, QREX Bearer token, PIN parowania i stabilne Server ID są przechowywane tylko w lokalnych ustawieniach aplikacji.
• Mutacje plików są domyślnie wyłączone. Klienci zdalni mogą tylko odczytywać, dopóki nie przyznasz wyraźnie dostępu do zapisu.
• W dowolnym momencie wyłącz dowolne rozszerzenie (audio, schowek, przesyłanie plików, IME, zdalne wejście), aby natychmiast odebrać tę możliwość.
• Jeśli chcesz utrzymać serwer lokalny dla swojego Maca, ustaw bind host na 127.0.0.1.