Kasm Workspaces на сервере: частые ошибки и решения

MAATRIX

Kasm Workspaces выглядит как самый удобный способ выдавать людям изолированные рабочие столы и приложения прямо из браузера — контейнер вместо VM, свежий образ на каждую сессию, ничего не ставится на клиентскую машину. На практике первое знакомство упирается в один и тот же набор проблем: инсталлятор падает на середине, сессия открывается чёрным экраном, образы не скачиваются, а диск за неделю неожиданно забит под ноль. Ниже — разбор, откуда растут эти ошибки и как их закрыть, с конкретными командами и проверками.

Как устроена архитектура Kasm и где рвётся связь

Kasm — не один процесс, а связка сервисов, которые общаются между собой через внутреннюю сеть Docker, и большинство «непонятных» ошибок сводятся к разрыву именно этой связи. Core-компоненты после стандартной установки:

• kasm_proxy — обратный прокси на nginx, принимает трафик снаружи и первым видит проблемы с TLS и WebSocket;
• kasm_manager и kasm_api — управляющий слой: веб-панель, API, распределение сессий по агентам;
• kasm_agent — сервис на каждом сервере, где реально поднимаются контейнеры с рабочими столами;
• kasm_db (PostgreSQL) и kasm_redis — состояние и кэш сессий;
• kasm_share — вспомогательный сервис для функции «поделиться экраном».

В простой установке всё это крутится на одной машине, но роли разделены логически с самого начала — поэтому Kasm умеет масштабироваться на несколько серверов позже. Отсюда практический вывод: когда сессия не открывается, полезно понять, на каком слое проблема — прокси не пропускает WebSocket, manager не достучался до agent, agent не может поднять контейнер, или контейнер падает внутри. Первая команда для диагностики почти всегда одна и та же:

sudo docker ps -a --filter "name=kasm"
sudo docker logs kasm_agent --tail 100
sudo docker logs kasm_manager --tail 100

Если контейнер kasm_agent в статусе Restarting — проблема на уровне инфраструктуры (Docker, диск, права), и разбирать сессии рано.

Установка: частые ошибки install.sh и подготовки сервера

Официальный путь — скачать архив релиза и запустить install.sh от root:

cd /tmp
curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release/kasm_release_latest.tar.gz
tar -xf kasm_release_latest.tar.gz
sudo bash kasm_release/install.sh

(Точный URL и номер версии стоит сверить в актуальной документации — Kasm регулярно выпускает релизы, и старая ссылка может вести на устаревший архив.)

Инсталлятор сам ставит Docker, если его нет, разворачивает набор контейнеров и генерирует случайные пароли для admin-панели — их важно сохранить сразу, они выводятся один раз в конце и попадают в файл на диске (путь стоит проверить в выводе самого инсталлятора, он отличается между версиями). Частые причины падения на середине:

• Мало места на диске. Установщик разворачивает несколько тяжёлых образов ещё до создания первой сессии. Если / смонтирован на маленьком разделе, установка обрывается с no space left on device или зависает на шаге pull. Проверяйте df -h до запуска, а не после.
• Мало оперативной памяти или swap. На минимальных VPS без свопа установщик или первая сессия может упасть по OOM во время распаковки образов — как правильно настроить своп, разобрано в статье про своп-файл.
• Конфликт портов 443 и 3000. Kasm поднимает свой nginx на 443 по умолчанию — если на сервере уже слушает Apache, другой nginx или Guacamole, инсталлятор либо падает, либо kasm_proxy не стартует после. Проверьте sudo ss -tulpn | grep -E ':443|:3000' заранее.
• Незавершённая предыдущая попытка. Если install.sh прерывали (Ctrl+C, обрыв SSH), повторный запуск иногда падает на уже существующих томах Docker — проще снести созданные ранее контейнеры и тома Kasm и поставить с нуля, чем чинить частично поднятое состояние.

Проверить, что все контейнеры действительно поднялись и здоровы: sudo docker ps --filter "name=kasm" --format "table {{.Names}}\t{{.Status}}" — все строки должны быть в статусе Up, без Restarting и Exited.

Образы рабочих столов: pull не идёт, диск переполняется

Каждый workspace (Chrome, Firefox, Ubuntu Desktop, VS Code и так далее) — отдельный Docker-образ, который тянется с Docker Hub или из собственного registry Kasm при первом запуске сессии. Здесь два класса проблем.

Первый — rate limit Docker Hub на анонимные pull. Если сервер тянет сразу несколько образов подряд (например, при первом знакомстве администратор кликает по очереди все workspace), можно упереться в лимит анонимных запросов — сессия зависает на «Preparing container», а в логах agent видно 429 Too Many Requests. Решение — авторизовать Docker под учётной записью Docker Hub (docker login) с более высоким лимитом.

Второй, более коварный — диск незаметно забивается образами и логами: каждая новая версия каждого workspace — это ещё несколько гигабайт в /var/lib/docker, а старые слои сами по себе не удаляются. Через несколько месяцев это выливается в остановку новых сессий с ошибкой нехватки места, хотя формально «ничего не менялось». Регулярная очистка неиспользуемых образов и слоёв разобрана в статье про переполнение диска Docker — с уточнением для Kasm: не чистите образы командой docker rmi без разбора, если Kasm ссылается на них по тегу в своей базе конфигураций, иначе сессия перестанет запускаться до повторного pull.

Скачать конкретный образ вручную, если он битый или недокачан, — sudo docker pull kasmweb/chrome:1.15.0, но тег версии перед этим сверьте с тем, что прописан в настройках workspace в админ-панели (Workspaces → редактирование образа).

Сеть, WebSocket и обратный прокси: чёрный экран и обрывы сессии

Kasm стримит рабочий стол в браузер через WebSocket поверх собственного протокола KasmVNC — механика похожа на Guacamole (см. статью про частые ошибки Apache Guacamole), и симптомы почти идентичны: сессия открывается, картинка даже прорисовывается один раз, но дальше — чёрный экран или зависание.

За собственным kasm_proxy без внешнего слоя WebSocket настроен из коробки и проблем обычно нет. Они начинаются, когда перед Kasm ставят ещё один прокси — внешний nginx, Cloudflare или балансировщик для терминации TLS на отдельном домене. Тогда прокси обязан явно апгрейдить соединение до WebSocket, иначе сессия рвётся при первой же передаче кадра:

location / {
    proxy_pass https://127.0.0.1:443;
    proxy_ssl_verify off;
    proxy_http_version 1.1;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

proxy_ssl_verify off здесь нужен потому, что внутренний kasm_proxy поднимается с самоподписанным сертификатом — если на внешнем слое уже стоит нормальный сертификат через Let's Encrypt, это ожидаемо и безопасно. Общие принципы reverse-proxy на nginx, включая грабли с таймаутами, разобраны в статье про nginx как обратный прокси.

Отдельная причина обрывов — файрвол или облачный security group режут долгоживущие WebSocket-соединения по таймауту простоя. Если сессия обрывается ровно через фиксированный интервал независимо от активности, проверьте таймауты на уровне сетевого экрана перед сервером, а не только в конфиге nginx или Kasm — это разные точки.

Ресурсы и производительность: память, CPU и GPU-ускорение

Каждая открытая сессия Kasm — полноценный контейнер с графическим окружением внутри, а не лёгкий терминал, и по ресурсам это ближе к небольшой виртуалке, чем к обычному Docker-сервису. Ориентировочно на один рабочий стол с браузером стоит закладывать от 2 vCPU и 2-4 ГБ RAM с запасом — цифра сильно зависит от того, что пользователь делает внутри сессии, так что это ориентир для планирования, а не норматив.

Лимиты на контейнер задаются в админ-панели при редактировании образа workspace (вкладка с ресурсами) — без явных лимитов одна тяжёлая сессия может забрать большую часть ресурсов сервера и просадить остальные. Общая логика распределения CPU и памяти между контейнерами Docker применяется к Kasm так же, как к любому другому Docker-сервису.

Отдельная тема — GPU-ускорение для тяжёлой графики или 3D внутри workspace. Kasm поддерживает проброс видеокарты через nvidia-container-toolkit, но это требует физического GPU на сервере, совместимого драйвера на хосте и отдельно настроенного образа workspace — просто включить галочку в панели недостаточно. Без такой настройки рендер идёт программно на CPU и заметно лагает.

Аутентификация, LDAP/SAML и права доступа

После установки в Kasm уже есть учётная запись администратора — логин и пароль выводятся в конце работы install.sh и, как правило, дублируются в файле на диске. Первое, что стоит сделать после входа, — сменить пароль через Admin → Users, особенно если панель смотрит наружу.

Для команд имеет смысл подключить внешний источник пользователей вместо ручного заведения каждого аккаунта — Kasm работает с LDAP и SAML через Admin → Authentication. Типичная ошибка вроде Invalid Credentials при неверном bind-пароле или пустых групп при неверном base DN — общая для любой системы на LDAP. Если внешние пользователи логинятся, но не видят ни одного workspace — почти всегда дело в том, что группам с LDAP/SAML-пользователями не назначены права на образы (Admin → Groups → Permissions), это отдельный шаг после того, как вход заработал.

Для панели администратора, у которой доступ ко всем сессиям сразу, разумно включить двухфакторную аутентификацию — Kasm поддерживает TOTP так же, как большинство современных веб-панелей.

Масштабирование на несколько серверов

Когда одного сервера перестаёт хватать по нагрузке, Kasm поддерживает разнесение ролей: manager на одной машине, а сессии реально поднимаются на отдельных серверах-агентах, которые регистрируются через Infrastructure → Zones/Agents с провизионным токеном.

Частая ошибка на этом шаге — агент числится offline, хотя сервис физически запущен. Причина почти всегда сетевая: manager должен видеть агент по указанному адресу и порту, а не наоборот — если файрвол между серверами пропускает трафик только в одну сторону, регистрация формально проходит (агент один раз достучался до manager), а дальнейшие проверки — нет. Проверьте связность в обе стороны явно: curl -k -v https://IP_АГЕНТА:443/ с manager и обратно с агента, а не полагайтесь на то, что раз агент зарегистрировался — значит его видно.

Для агентских серверов важна предсказуемая сеть без NAT-сюрпризов между узлами — под такую роль подходят выделенные серверы и VPS с постоянным IP в локациях RU, US и UK, которые можно объединить в одну инфраструктуру и оплатить из России картой или криптой.

Частые вопросы