Домен и доступ из аудитории — документация Colloq

Выберите способ публикации сервера и проверьте настоящую студенческую ссылку.

Выбор транспорта

Команды make host, host-direct, relay-setup и tunnel-setup запускаются из checkout открытого репозитория github.com/sleep3r/colloq на теге выбранного выпуска; его коммит записан в поле sourceCommit файла release.json. Из этих инструментов архив colloq-deploy.tar.gz содержит только scripts/host.sh. С ним работают relay и Cloudflare tunnel, а прямой режим и первичная настройка relay или named tunnel требуют checkout. Можно обойтись и без этих инструментов, если настроить собственный HTTPS reverse proxy к 127.0.0.1:30080. Для занятия на своём компьютере после pip install colloq ту же публикацию выполняет colloq host <имя>; без имени поднимается quick tunnel. colloq start --share поднимает занятие и quick tunnel одной командой и печатает ссылку для студентов, см. «Одна ссылка со своего компьютера».

Ситуация	Способ	Что нужно
Свой публичный IP и порты 80/443	Прямой Caddy	Домен, root и DNS-настройка.
Ноутбук или VM за NAT	Свой relay с FRP	Публичный relay с Caddy/frps, исходящее соединение.
Короткая демонстрация	Quick Cloudflare tunnel	Доступность Cloudflare из сети аудитории; URL меняется.
Постоянный адрес через Cloudflare	Named tunnel	Предварительная настройка tunnel и DNS.

Проверяйте доступность выбранного транспорта из реальной сети студентов. Cloudflare tunnel может быть недоступен из части российских сетей; постоянное доменное имя само по себе этот маршрут не меняет.

Любой транспорт публикует только сервер, который подтверждает изоляцию комнат: поле isolation в /api/health должно быть docker (контейнер на комнату) или broker (Pod на комнату в k3s). Иначе make host, colloq host, --share и --host отказываются ещё до того, как что-то открыть. Поле появляется только после успешной проверки ядра, поэтому сервер с остановленным Docker или слишком старый, чтобы назвать поле, не публикуется.

После pip install colloq занятие запускается и выходит в сеть одной командой:

colloq start --share

Colloq поднимает занятие, открывает quick tunnel Cloudflare и печатает в терминале один блок: ссылку занятия для студентов, https://….trycloudflare.com/s/…. Если занятия ещё нет, блок называет панель по публичному адресу: создайте занятие там и скопируйте его ссылку из списка — ссылки в списке уже ведут на публичный адрес. Ссылки с /admin/ — это ключи от панели; не отправляйте их никому.

Ссылка работает, пока открыт терминал; Ctrl+C закрывает её вместе с занятием. Quick tunnel при каждом запуске получает новый адрес, поэтому рассылайте новую ссылку каждый раз. Адреса Cloudflare не открываются из России: для студентов там публикуйте занятие через свой relay командой colloq start --host <имя>.

Если cloudflared не установлен, первый --share скачивает закреплённый выпуск с GitHub в ~/.colloq/bin и сверяет его SHA-256 до первого запуска. COLLOQ_CLOUDFLARED=/путь/к/cloudflared подставляет свой файл, COLLOQ_CLOUDFLARED_DOWNLOAD=0 запрещает загрузку. Поддерживаются macOS и Linux; на Windows — через WSL 2.

Занятие публикуется, только если ядро каждой комнаты работает в своём контейнере: Docker запущен, а сервер подтверждает изоляцию в /api/health. Иначе --share, --host и colloq host отказываются, а занятие продолжает работать локально. Комнаты — укреплённые контейнеры без доступа к домашней сети, но ссылка всё равно остаётся дверью: кто её получил, тот запускает код в песочнице на вашем компьютере. Давайте её только своей группе.

Прямой публичный сервер

Если у машины действительно есть публичный адрес и доступные TCP 80/443, host-инструменты могут настроить Caddy:

sudo make host-direct HOST=seminar.example.edu

Инструменты сами создают A-запись имени через API Cloudflare, поэтому зона домена должна обслуживаться Cloudflare. Впишите в .env checkout токен CF_TOKEN с правами Zone:Read и DNS:Edit. Если токен не видит список зон, добавьте ещё CF_ZONE. Проксирование для записи выключается. Эти полномочия нужны оператору, не приложению. Если 80 и 443 снаружи закрыты, команда откажется ещё до изменений; на Vast VM всегда будет так. Caddy работает на хосте как служба, продолжает работать после закрытия терминала и проксирует production на 127.0.0.1:30080. Для k3s-установки нужна та же строка COLLOQ_CLUSTER=1 в .env, что и для relay.

Свой relay

На отдельной публичной машине один раз настройте Caddy и FRP:

DOMAIN=colloq.example.edu make relay-setup WHERE=root@your-relay
make host HOST=seminar.colloq.example.edu

Без DOMAIN скрипт настраивает relay на зону проекта colloq.ru, которая вам не принадлежит. Направьте *.colloq.example.edu A-записью на адрес relay. Если зона в Cloudflare, отключите проксирование. Сертификат для каждого имени Caddy получает при первом обращении; один сертификат на всю зону даёт RELAY_WILDCARD=1 с CF_TOKEN. Имя занятия — одна метка перед зоной, например seminar.colloq.example.edu: make host отправляет на relay только имена под RELAY_DOMAIN, а любое другое имя уходит в Cloudflare.

relay-setup печатает готовые строки RELAY_DOMAIN, RELAY_ADDR, RELAY_PORT и RELAY_TOKEN. Впишите их в файл .env в каталоге инструментов на машине Colloq: в checkout или в распакованном архиве выпуска. В instance.env они не нужны, приложение их не читает. Для k3s-установки добавьте в тот же .env строку COLLOQ_CLUSTER=1. Без неё скрипт ищет приложение на порту разработки 3000 вместо 127.0.0.1:30080 и завершается ошибкой. Запускайте make host на машине Colloq от root: новый адрес записывает cluster.sh public-url, а ключ для ссылки владельца лежит в каталоге данных, закрытом для обычных пользователей. Команда сама подключается к relay наружу. Понадобится frpc той же версии, что frps на relay (relay-setup ставит 0.71.0); Docker на k3s-машине не нужен. Из архива выпуска, без Makefile:

sudo env COLLOQ_HOSTNAME=seminar.colloq.example.edu bash scripts/host.sh

Туннель работает, пока работает команда, поэтому запускайте её в tmux или как службу. Vast использует этот же транспорт, и vast-up сам держит его в tmux. Что происходит с адресом после Ctrl+C, описано в разделе «Корректные ссылки».

Код продолжает исполняться на машине Colloq. Relay обслуживает трафик и становится общей точкой отказа для всех проходящих через него занятий. Следите за его пропускной способностью и ресурсами; размер аудитории проверяйте нагрузочным сценарием.

Собранный фронтенд relay раздаёт сам. make host выкладывает на него assets/, fonts/ и pdf/ из web/dist рядом со скриптом — из checkout того же выпуска после npm run build или из пакета pip; через туннель остаётся ходить только живой комнате. В архиве выпуска сборки нет, и тогда вся статика идёт через туннель. Отсутствующий или устаревший файл relay пропускает в туннель, поэтому зеркало не ломает занятие. Проверка: curl -sI https://seminar.example.edu/assets/<файл> — ответ с X-Colloq-Mirror: hit пришёл от relay. Имена кусков прежней сборки остаются доступными 30 дней.

Cloudflare tunnel

# Временный адрес
make host

# Именованный tunnel: сначала настройка, затем запуск
make tunnel-setup HOST=seminar.example.edu
make host HOST=seminar.example.edu

Транспорт выбирается по имени: HOST под RELAY_DOMAIN идёт через relay, любое другое имя — через named tunnel, без HOST поднимается quick tunnel. Для Cloudflare на машине Colloq нужен cloudflared; если его нет в PATH, скрипт берёт закреплённый выпуск, который colloq скачивает и сверяет по SHA-256 (см. «Одна ссылка»). Quick tunnel выдаёт случайный адрес и работает, пока работает процесс. Скрипт сначала получает URL, затем обновляет PUBLIC_URL. В k3s-установке cluster.sh public-url при этом перезапускает приложение, и открытые комнаты переподключаются. После остановки туннеля скрипт снимает его адрес с k3s-установки, см. корректные ссылки. Напечатанная ссылка /admin/t/… предназначена только владельцу. На k3s-установке скрипт берёт ключ из /var/lib/colloq/data/setup-token (другой каталог состояния задаёт COLLOQ_STATE_DIR). Каталог данных принадлежит приложению (UID 1000) и закрыт для остальных, поэтому запускайте скрипт через sudo; если ключ прочитать не удалось, скрипт вместо ссылки называет путь к нему.

Корректные ссылки

PUBLIC_URL — внешний origin сервера, из которого строятся ссылки. При изменении адреса установленного k3s-instance используйте:

sudo scripts/cluster.sh public-url https://seminar.example.edu

Адрес туннеля живёт, пока работает make host. На k3s-установке по Ctrl+C скрипт возвращает PUBLIC_URL к http://127.0.0.1:30080, чтобы панель не раздавала ссылки на закрытый туннель. Приложение при этом перезапускается, до трёх минут; не нажимайте Ctrl+C второй раз. Адрес возвращается, только если в кластере всё ещё тот, который выставил скрипт: другой адрес, заданный за это время, не трогается. Если кластер отказал — например, скрипт запущен не от root или блокировку состояния держит другая команда, — скрипт печатает причину и команду для ручного запуска, а кластер и .env остаются на адресе туннеля. Прямой режим (host-direct) адрес не возвращает: Caddy продолжает работать как служба. Постоянный адрес задайте командой выше.

Не оставляйте localhost во внешних ссылках. После смены origin браузер может потребовать повторного преподавательского входа. Перед занятием проверьте HTTPS, вход студента, совместную правку, запуск ячейки и открытие файла с другого устройства.

Какие порты не публиковать

Публичный вход должен вести к приложению через HTTPS. Не публикуйте runtime broker 8787, Jupyter 8888, Kubernetes API 6443, kubelet 10250 и Flannel 8472. NodePort 30080 ограничен loopback для host-прокси.

Firewall, защищающий публичные порты, не решает все обращения из Pod к локальному узлу. Прочитайте ограничение NetworkPolicy перед допуском недоверенного кода.