DeskVNCServer - Руководство

Начало работы

1. Задайте пароль

Откройте Настройки (значок шестерёнки в нижней панели) и заполните VNC password. Стандартные VNC-клиенты используют DES-челлендж RFB, который учитывает только первые 8 ASCII-совместимых байтов: выбирайте пароль длиной не более 8 символов.

2. Запустите сервер

1. В главном окне нажмите Start. Индикатор состояния сменится на Running.
2. Одновременно поднимаются четыре слушателя: VNC 5900, управление QREX 5911, медиа QREX 4010 и file API 8766.
3. Нажмите Copy Info, чтобы скопировать в буфер обмена однострочную строку с хостом, портами и текущим PIN.

3. Подключите клиента

Для стандартного VNC-просмотрщика (macOS Screen Sharing, RealVNC, TightVNC, мобильные VNC-приложения):

1. Откройте просмотрщик и введите vnc://<your-mac-ip>:5900 в качестве адреса
2. Введите VNC password, заданный на шаге 1
3. Управляйте Mac немедленно — клавиатура, мышь, копирование/вставка через RFB

Для приложения QuickRemote:

1. Откройте QuickRemote на телефоне или планшете и выберите Add Mac
2. Введите 6-значный PIN сопряжения, показанный в DeskVNCServer (или отсканируйте QR-код, если ваша сборка QuickRemote это поддерживает)
3. QuickRemote сохранит полученный токен Bearer и откроет расширенные возможности — IME, аудио, синхронизацию буфера обмена и передачу файлов

Обзор интерфейса

Строка состояния

Кнопки действий

• Start — поднимает все четыре слушателя.
• Stop — закрывает все слушатели и отключает активные сессии.
• Copy Info — копирует короткую сводку подключения (хост, порт VNC, порт управления, PIN) в буфер обмена, чтобы удобно отправить её клиенту.

Панель подключения

Отображает bind-хост, порты, текущий Server ID и активный PIN сопряжения. Текст обновляется автоматически при изменении настроек.

Панель QuickRemote API

Быстрая справка по протоколам, на которых говорит сервер. Перечисляет поддерживаемые версии RFB, формы эндпоинтов QREX и набор команд IME, чтобы QuickRemote (или ваш собственный клиент) знал, что доступно.

Протоколы и порты

Аутентификация

• Клиенты VNC — пароль RFB DES (первые 8 ASCII-совместимых байтов настроенного пароля).
• Клиенты QREX — начальный обмен 6-значным PIN на POST /qr/v1/pair возвращает токен Bearer. Каждый последующий HTTP-вызов QREX и WebSocket-фрейм должен содержать Authorization: Bearer <token>.
• Если VNC password пуст, сервер анонсирует стандартный режим RFB no-auth. Полезно только для доверенных сегментов LAN.

Краткая справка по эндпоинтам 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

Настройки

Примеры клиентов

macOS Screen Sharing

1. Finder → Переход → Подключение к серверу
2. Введите vnc://<your-mac-ip>:5900
3. Введите VNC password

cURL — получить capabilities

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

cURL — сопрячься и вызвать 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"}'

Советы

• Снижайте частоту кадров и максимальные размеры кадра при медленном Wi-Fi или маршрутизации через VPN.
• Сопрягите каждое устройство один раз. После первого обмена PIN токен Bearer переживает перезагрузки, и QuickRemote переподключается молча.
• Используйте Copy Info как быстрый способ отправить детали подключения по чату или email — туда входит всё, что нужно клиенту.
• Держите Enable file mutations выключенным, если действительно не нужны загрузки. Режима «только чтение» хватает для просмотра скриншотов, заметок или загрузок.
• Отключайте audio API, когда не используете. Простаивающие кодеки всё равно расходуют немного CPU на пути кодирования.

Устранение неполадок

Сервер не запускается

• Возможно, порт 5900 уже занят другим VNC-сервером (например, macOS Screen Sharing). Остановите его в System Settings → General → Sharing или измените порт в настройках DeskVNCServer.
• Порты 5911 / 4010 / 8766 все должны быть свободны. Проверьте командами вроде lsof -i :5911.

VNC-клиенты не аутентифицируются

• Убедитесь, что пароль не длиннее 8 ASCII-совместимых байтов. Многобайтовые символы или более длинные строки молча обрезаются аутентификацией RFB DES.
• Если хотите осознанно обойтись без пароля, оставьте поле пустым и подключайтесь просмотрщиком, поддерживающим режим VNC no-auth.

QuickRemote не может выполнить сопряжение

• Подтвердите, что телефон или планшет в той же Wi-Fi-сети, что и Mac.
• Откройте панель подключения и заново прочитайте PIN. PIN можно перегенерировать в настройках.
• Проверьте настройки брандмауэра macOS — входящие подключения на порты QREX должны быть разрешены.

Удалённое управление тормозит

• Снизьте частоту кадров и максимальные размеры кадра в настройках.
• Отключите неиспользуемые функции (аудио, буфер обмена, IME), чтобы освободить CPU.

Файлы не передаются

• Подтвердите, что Enable file transfer включён. Перечни «только чтение» работают и без Enable file mutations.
• Если загрузки не проходят, включите ещё и Enable file mutations. Иначе File API отвечает только на запросы чтения.

Конфиденциальность

• Все сессии идут напрямую между клиентом и вашим Mac. Никакого облачного ретранслятора, телеметрии или аналитики.
• VNC password, токен Bearer QREX, PIN сопряжения и Stable Server ID хранятся только в локальных настройках приложения.
• Мутации файлов по умолчанию выключены. Удалённые клиенты могут только читать, пока вы явно не разрешите запись.
• Любое расширение (аудио, буфер обмена, передача файлов, IME, удалённый ввод) можно отключить в любой момент, чтобы немедленно отозвать соответствующую возможность.
• Если хотите оставить сервер локальным только для Mac, задайте bind host равным 127.0.0.1.