Доступ к рабочему столу

CherryPi умеет транслировать запущенный X-дисплей в браузер. Это полезно для GUI-инструментов, нужных задаче: браузер, IDE, дизайн-инструмент или отладка на хосте воркера.

Агент не запускает рабочий стол. Он подключает x11vnc к уже работающему дисплею при первом подключении браузера. Если дисплея нет, возможность просто недоступна — страница агента объясняет причину.

Требования

• X-дисплей на хосте агента (:0, :1, …).
• x11vnc, xauth и X-утилиты. Опубликованный образ агента их содержит.
• Доступ к X-сокету и authority-файлу.
• Браузер на стороне agency. NoVNC рисует RFB-поток.

X-сессия на хосте

На обычном Linux-десктопе X-сессия уже запущена. Запустите агента под пользователем, который имеет к ней доступ:

cherrypi-agent \
  --agency-url https://cherrypi.example.com \
  --token pat_… \
  --display :0 \
  --xauthority "$HOME/.Xauthority"

Эквивалентные переменные — DISPLAY и XAUTHORITY.

Для headless-машины сначала запустите виртуальный дисплей, например Xvfb :99 -screen 0 1920x1080x24, затем задайте DISPLAY=:99. CherryPi не управляет Xvfb.

Docker

Смонтируйте X-сокет и authority-файл в контейнер:

docker run -d --name cherrypi-agent \
  --restart unless-stopped \
  -v /srv/cherrypi/agent:/root/.cherrypi \
  -v /srv/cherrypi/pi:/root/.pi/agent \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v "$HOME/.Xauthority:/root/.Xauthority:ro" \
  -e DISPLAY=:0 \
  -e XAUTHORITY=/root/.Xauthority \
  -e CHERRYPI_AGENCY_URL=https://cherrypi.example.com \
  -e CHERRYPI_AGENT_TOKEN=pat_… \
  ghcr.io/cherrypidotdev/cherrypi-agent:latest

На macOS X11 по умолчанию нет; запускайте агента на Linux или Linux VM.

Использование

Откройте страницу агента и выберите Desktop. Первое подключение запускает x11vnc; следующие зрители присоединяются к тому же потоку. Для тех, кто не владеет агентом, поток доступен только для просмотра; владельцы получают клавиатуру и указатель.

Закройте вкладку, чтобы отключиться. Агент не держит VNC-сервер после ухода последнего зрителя.

Безопасность

• Рабочий стол доступен только через аутентифицированный туннель agency.
• Считайте дисплей сессией пользователя агента: все окна и все видимые там креденшелы доступны зрителям.
• По возможности используйте отдельного пользователя и дисплей для работы агента.
• Не монтируйте личный $HOME в контейнер агента только ради X-сессии.

Решение проблем

Симптом	Что проверить
Кнопка Desktop говорит, что возможность отключена	DISPLAY/--display не задан на агенте.
В логах cannot open display	X-сокет или authority-файл не смонтирован/не читается.
Чёрный экран	Дисплей есть, но нет оконного менеджера/композитора. Запустите нужную сессию.
Частые обрывы	Reverse proxy обрывает WebSocket по таймауту; отключите read timeout.

См. Решение проблем.