DOCUMENTATION / 1.0

От установки
до первого туннеля.

Portal состоит из сервера на VPS и клиента на компьютере с приложением. Клиент устанавливает исходящее соединение, поэтому открывать порты на домашнем роутере не требуется.

1. Аккаунт и клиент

Зарегистрируйтесь на главной странице сервера.
В кабинете откройте «Установка клиента» и скачайте файл для своей ОС.
В разделе «Доступ и безопасность» создайте токен и сохраните его.
Запустите команду авторизации из кабинета. Когда программа попросит токен, вставьте его и нажмите Enter.

.\portal-windows-amd64.exe auth --server https://YOUR-SERVER
# Linux / macOS:
chmod +x portal-linux-amd64
./portal-linux-amd64 auth --server https://YOUR-SERVER

Файл конфигурации хранится в каталоге конфигурации пользователя, в папке portal. Точный путь показывает команда help. Токен хранится на клиенте; не публикуйте этот файл.

2. HTTP, HTTPS и WebSocket

portal http 3000 --name my-app
portal http 127.0.0.1:5000 --name api
portal http https://localhost:8443 --name secure
portal http 3000 --endpoint ID-ИЗ-КАБИНЕТА

Публичный адрес выводится после подключения. HTTPS обслуживает сервер. Для HTTPS-приложения на локальном порту сертификат должен проходить обычную проверку доверия. WebSocket работает через HTTP-туннель автоматически. Закрытие терминала отключает туннель; имя остаётся зарезервированным.

3. Проверка без своего приложения

# Первый терминал:
portal demo --port 3000
# Второй терминал:
portal http 3000 --name demo

Откройте выданную ссылку. Вы увидите страницу локального демонстрационного приложения. Адрес /api/echo возвращает метод, путь и тело запроса в JSON.

4. TCP и SSH

portal tcp 22 --name ssh
portal tcp 127.0.0.1:5432 --name postgres
# Подключение с другого компьютера:
ssh -p ВЫДАННЫЙ-ПОРТ user@SERVER

Порт резервируется постоянно в диапазоне сервера. Сами приложения должны проверять доступ. TCP-порт принимает обычный TCP; для шифрования соединения пользователя используйте SSH или TLS целевого сервиса. Соединение клиента Portal с сервером зашифровано TLS.

5. Общий доступ к файлам

portal files ./public --name files

Публикуется содержимое указанного каталога с просмотром списка файлов. Выбирайте отдельный каталог для публикации; проверьте его содержимое и символические ссылки.

6. Несколько туннелей

server: https://YOUR-SERVER
tunnels:
  app:
    type: http
    target: "3000"
    name: my-app
  ssh:
    type: tcp
    target: "22"
    name: ssh

# Токен задайте в PORTAL_TOKEN или добавьте token в защищённый YAML.
portal start --config portal.yml

При обрыве сети клиент переподключается с увеличением интервала до 16 секунд. Отзыв токена, ручное отключение и ошибки настроек завершают процесс. Команда doctor проверяет сервер и токен.

7. Политики доступа

В настройках туннеля можно включить Basic Auth для HTTP, разрешить конкретные IP/CIDR, задать число запросов или подключений в минуту на IP и приостановить публикацию. Пустой список IP разрешает все адреса. Изменения разрывают текущие соединения; работающий клиент автоматически переподключается, если туннель не приостановлен.

8. Инспектор и повтор запросов

Метаданные HTTP-запросов сохраняются в SQLite. Запись тел выключена по умолчанию. После её включения сохраняются первые 16 КБ запроса и ответа. Заголовки Authorization, Cookie и похожие на секреты скрываются, тела не редактируются. Историю можно очистить. Повтор доступен только для полностью записанного тела; он отправляет запрос приложению снова и может изменить его данные. Скрытые заголовки не восстанавливаются. WebSocket и TCP не записываются в HTTP-инспектор.

9. Собственный домен

Добавьте домен в настройки HTTP-туннеля. Создайте предложенную TXT-запись подтверждения и CNAME на адрес Portal (для корня зоны используйте A/AAAA на VPS). Нажмите «Проверить DNS». После подтверждения сервер разрешит выпуск HTTPS-сертификата. Первое открытие может занять несколько секунд. До подтверждения работает исходный поддомен.

10. Сервер и обслуживание

На VPS приложение работает как служба portal, HTTPS обслуживает Caddy. Конфигурация: /etc/portal/portal.env, база: /var/lib/portal/portal.sqlite. Данные переживают обновление и перезапуск. Откройте 80/tcp, 443/tcp и выделенный диапазон TCP. Порт 8080 должен слушать только loopback.

systemctl status portal caddy
journalctl -u portal -f
journalctl -u caddy -f
systemctl restart portal
# Закрытие регистрации: REGISTRATION=closed в portal.env

Установочный комплект содержит службы резервного копирования, инструкцию восстановления, пример автозапуска клиента и утилиту администратора для восстановления пароля. Полное руководство хранится в README.md проекта.

Если соединение не работает

Запустите portal doctor: проверьте адрес сервера и токен.
Убедитесь, что локальный сервис открывается по указанному порту.
Проверьте статус туннеля в кабинете и сообщения терминала клиента.
Для своего домена проверьте DNS и доступность портов 80/443 VPS.
Для TCP проверьте firewall сервера и приложения.

От установкидо первого туннеля.