Установка и первый запуск

Как скачать готовую поставку, пройти мастер настройки и настроить платформу через админ-панель. Для интеграции приложений см. раздел Public API.

1. Системные требования

Компонент	Требование
ОС	Linux x86_64 (Ubuntu 20.04+, CentOS 8+ и др.), Windows 10+, macOS 12+
ОЗУ	от 512 МБ (рекомендуется 2 ГБ)
Диск	от 500 МБ свободного места
СУБД	MySQL 8.0+ или PostgreSQL 14+ (можно поднять отдельно или в Docker)

2. Установка и запуск

Рекомендуемый способ для Linux — готовый дистрибутив ядра.

2.1. Скачивание

wget https://cascad360.ru/downloads/core/1.0.9/cascad360-1.0.9-linux-x86_64.tar.gz

# или
curl -LO https://cascad360.ru/downloads/core/1.0.9/cascad360-1.0.9-linux-x86_64.tar.gz

Прямая ссылка: cascad360-1.0.9-linux-x86_64.tar.gz

2.2. Распаковка

tar -xzf cascad360-1.0.9-linux-x86_64.tar.gz
cd cascad360

# опционально: установка в /opt
# sudo mv cascad360 /opt/cascad360
# cd /opt/cascad360

2.3. Запуск

Новая установка (рекомендуется в 1.0.7+): сначала мастер первичной настройки:

./cascad360 --setup

# Откройте в браузере (порт по умолчанию — 5050):
# http://localhost:5050/setup

После завершения мастера основное приложение запускается автоматически в фоне — как systemd-сервис cascad360 (при установке от root) или фоновый процесс. Дальнейшее управление — через systemctl (рекомендуется) или команды ./cascad360.

Уже настроенная система — запуск и остановка через systemd:

sudo systemctl start cascad360
sudo systemctl stop cascad360
sudo systemctl status cascad360

Если unit не настроен (локальная отладка без root):

./cascad360 start

# если исполняемый файл в bin/:
# ./bin/cascad360 start

2.4. Управление сервисом (systemd)

После установки и завершения мастера настройки КАСКАД 360 работает как фоновый сервис под управлением systemd. Unit — cascad360.service; при установке от администратора сервера мастер может создать его и включить автозапуск автоматически.

Основные команды (от root или через sudo):

systemctl status cascad360   # статус: running / stopped, последние строки лога
systemctl start cascad360    # запуск сервиса
systemctl stop cascad360     # остановка
systemctl enable cascad360   # автозапуск при загрузке ОС

Команда	Когда использовать
status	Проверить, что платформа запущена и нет ошибок unit
start / stop	Ручной запуск и остановка — перед обновлением, правкой config.yml или диагностикой
enable	Включить автозапуск после перезагрузки сервера (если ещё не включён)

После изменения config.yml перезапустите сервис:

sudo systemctl restart cascad360

Просмотр логов в реальном времени:

journalctl -u cascad360 -f

3. Базовая конфигурация

Основной файл — config.yml в каталоге установки. При первой установке можно скопировать шаблон:

cp config.yml.example config.yml

Минимально полезные параметры перед первым запуском:

app:
  name: Контур
  version: 1.0.9
  setup_completed: false
  setup_app_configured: false   # true после шага 3 мастера (1.0.7+)

web:
  host: 0.0.0.0
  port: 5000
  public_port: 5001
  public_api_separate: false   # true — Public API на отдельном порту
  public_api_enabled: true

plugin_ports:
  enabled: false             # true — HTTP-listener'ы плагинов (см. 3.1)

database:
  driver: mysql
  host: localhost
  port: 3306
  database: cascad360
  username: cascad_user
  password: change-me

Параметры подключения к БД можно также указать в мастере настройки (/setup) — тогда правка config.yml не обязательна до первого входа.

3.1. Настройка портов

Порты задаются в config.yml. После изменения перезапустите сервис: sudo systemctl restart cascad360 (см. раздел 2.4).

Порт / диапазон	Параметр	Назначение
5000	web.port	Основной HTTP: админ-панель, служебные функции платформы, шлюз, маршрутизация
5001	web.public_port	Public API — только при public_api_separate: true
8000–8999	plugin_ports	Диапазон HTTP-listener'ов плагинов (при enabled: true)

Основной порт платформы (web)

• port — порт админки и служебные функции платформы (по умолчанию 5000).
• public_api_separate: false — Public API на том же порту (режим по умолчанию, как в 1.0.5).
• public_api_separate: true — служебные функции платформы на port, Public API на public_port; удобно для сетевого разделения контуров.
• public_api_enabled: false — отключить Public API полностью.

# Раздельные порты платформы и Public API
web:
  port: 5000
  public_port: 5001
  public_api_separate: true
  public_api_enabled: true

Порты расширений (plugin_ports, 1.0.6)

Для плагинов с собственным веб-интерфейсом. По умолчанию выключено — ядро остаётся компактным.

plugin_ports:
  enabled: true
  port_range_min: 8000
  port_range_max: 8999
  max_listeners: 10
  reserved_ports: [5000, 5001, 5050]  # порты, которые плагины не могут занять
  auto_start_on_boot: false
  default_host: 0.0.0.0
  hook_timeout_seconds: 30

Управление listener'ами — в админ-панели (раздел плагинов) с правами plugin_ports_view, plugin_ports_manage, plugin_ports_operate.

4. Мастер первичной настройки

При первой установке запустите ./cascad360 --setup и откройте http://localhost:5050/setup. Альтернатива: при setup_completed: false мастер доступен на основном порту — http://localhost:5000/setup.

Мастер выполняется в браузере. С версии 1.0.7 переход между шагами возможен только после реальной готовности предыдущего этапа — индикаторы прогресса отражают фактическое состояние, а не дефолты конфигурации.

1. Подключение к БД — тип (MySQL / PostgreSQL), хост, порт, имя базы, учётные данные. Кнопка «Проверить соединение» обязательна перед переходом к следующему шагу.
2. Администратор — создание первой учётной записи (логин, пароль, email). Жёсткого дефолтного пароля нет.
3. Параметры приложения — название контура и базовые настройки. После сохранения выставляется app.setup_app_configured: true.

Когда все три шага выполнены, становится активной кнопка «Завершить настройку». После нажатия:

• конфигурация сохраняется (app.setup_completed: true);
• система пытается запустить основное приложение — через systemctl start cascad360 (при root + systemd), установку unit с enable --now или фоновый процесс ./cascad360;
• при недоступном автозапуске вы получите чёткую команду для ручного запуска — без перехода на страницу, которая ещё не работает;
• после успешного запуска откроется страница входа на основном порту: http://localhost:5000/login.

После завершения откройте http://localhost:5000 и войдите с учётной записью, созданной на шаге 2.

5. Админ-панель: что где находится

После входа в админ-панель настройка выполняется через боковое меню. Набор доступных разделов зависит от вашей роли.

6. Базы данных

Работа с данными выполняется в трёх связанных разделах админ-панели.

6.1. База данных платформы

Просмотр структуры основной базы данных платформы: список таблиц, проверка схемы. Используется для диагностики после установки.

6.2. Базы данных сервисов

Привязка отдельных баз данных к подключённым сервисам:

• выбор источника данных (datasource) и создание новой БД для сервиса;
• выполнение install SQL при первичной настройке сервиса;
• переход в Студию БД по кнопке «Открыть в студии».

6.3. Студия БД

Единый интерфейс для любой привязанной базы (ядро или сервис):

• просмотр основной БД ядра и сервисных баз — служебные каталоги СУБД скрыты;
• список таблиц и представлений, структура (колонки, индексы, FK);
• просмотр данных с пагинацией, сортировкой и фильтрами — при переключении контекста данные на экране обновляются без «чужих» строк;
• добавление, редактирование и удаление строк через формы;
• SQL-консоль (read-only или с правом на изменение — по роли);
• журнал изменяющих операций (аудит);
• проверка схемы — полный актуальный набор таблиц ядра.

В верхней части студии выберите источник данных и базу — контекст сохраняется в URL, ссылку можно передать коллеге.

6.4. Public Swagger UI

Интерактивная read-only документация Public API: /api/docs/public. Спецификация — GET /api/openapi.json. Подробнее — OpenAPI и метрики.

6.5. Веб-контур расширений (опционально, 1.0.6)

Если плагин предоставляет собственный HTTP-интерфейс, включите plugin_ports.enabled: true в config.yml — параметры и диапазоны портов описаны в разделе 3.1. Регистрация и запуск listener'ов — в админ-панели (раздел плагинов) с учётом RBAC.

7. Сервисы и маршрутизация

7.1. Сервисы

На странице сервисов отображаются подключённые бэкенды: статус, health-check, метрики. Доступны действия запуска, остановки, перезапуска и масштабирования — через кнопки в интерфейсе.

7.2. Маршрутизация

Настройка правил, по которым запросы /api/module/<модуль>/… проксируются к целевым сервисам:

• создание и редактирование правил (шаблон пути, целевой сервис, метод);
• предпросмотр маршрута перед сохранением;
• горячая перезагрузка правил без рестарта ядра.

7.3. Балансировка

Выбор алгоритма распределения запросов между репликами сервиса (round-robin, least connections и др.).

7.4. Контейнеры

Обзор и управление Docker-контейнерами, если Service Discovery работает через Docker.

8. Обновления и маркет

8.1. Центр обновлений

Управление версиями ядра, модулей и плагинов:

• проверка доступных обновлений по каналу (stable, beta);
• запуск задачи обновления или отката из интерфейса;
• readiness-проверка перед обновлением в production.

Канал и URL реестра задаются в config.yml (секция updates), остальное — в панели.

8.2. Маркет

Витрина модулей и плагинов поверх центра обновлений:

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

8.3. API-ключи для внешних интеграций

Если нужно подключить внешнее приложение к данным, файлам или отправке почты через платформу, создайте API-ключ в разделе Настройки и назначьте нужные разрешения (например, mail:send для Service API почты). Подробности — в документации публичного API.

10. Настройка почты (1.0.8+)

Начиная с версии 1.0.8, в поставку входит обязательный плагин mail. Все исходящие письма (алерты, сервисные уведомления, вызовы Service API) проходят через единый почтовый контур — настройка транспорта выполняется один раз в админке.

10.1. Первичная настройка

1. Войдите в админ-панель и откройте Настройки → секция «Почта» (регистрируется плагином mail).
2. Выберите режим транспорта:
   • smtp — корпоративный SMTP или облачный релей (рекомендуется для production);
   • local / postfix / sendmail — локальный MTA на сервере;
   • file — запись писем в файлы (только для разработки и отладки).
3. Укажите From (from_email, при необходимости from_name) и параметры SMTP (host, port, шифрование, учётные данные).
4. Нажмите «Отправить тест» — убедитесь, что письмо дошло или появилось в журнале outbox.

10.2. Email-каналы уведомлений

На вкладке Настройки → Уведомления создайте канал типа email. В конфигурации канала указываются только получатели (to, опционально cc) и шаблон — параметры SMTP в канале не хранятся.

При срабатывании правила алерта письмо ставится в очередь плагина mail. Статус — в журнале «Почта» → Outbox.

10.3. Service API (для интеграторов)

Внешние сервисы могут отправлять письма через платформу без прямого доступа к SMTP:

POST /api/v1/mail/send
X-API-Key: <ключ с permission mail:send>
Content-Type: application/json

{
  "to": ["user@example.com"],
  "subject": "Уведомление",
  "text": "Текст письма"
}

Подробнее — в документации Mail Service API.

10.4. Шаблоны писем (1.0.9+)

В секции Почта → Шаблоны доступны системные шаблоны (в т.ч. system.auth.verify_email) и пользовательские. Можно редактировать subject и HTML, выполнять preview и test-send. Письма подтверждения регистрации используют эти шаблоны автоматически.

10.5. Обновление с 1.0.7 / 1.0.8

• Обновите ядро до 1.0.9 и перезапустите сервис.
• Миграции БД (поля users, auth_*, mail_templates) выполняются автоматически.
• Настройте Public Auth (см. раздел 11) и почту; выполните test-send.

11. Public Auth (1.0.9+)

Public Auth API — для вашего сайта, личного кабинета или приложения. Адрес методов: /api/v1/auth/*. Подробный контракт — в документации Public Auth.

11.1. Настройки в админке

1. Откройте Настройки → Безопасность → Public Auth.
2. Укажите URL подтверждения email — базовый адрес вашего фронта, например https://lk.example.ru/auth/confirm-email. В письме будет ссылка {base}?token=....
3. Проверьте: включена ли регистрация, обязательно ли подтверждение email, роль по умолчанию для новых пользователей.
4. Настройте lockout (попытки / окно / длительность блокировки) — по умолчанию 3 попытки за 5 мин → блок 3 ч по login и IP.

11.2. Политики паролей и доступ

• Роли — в карточке роли задайте политику сложности пароля и при необходимости «Запретить внешний API».
• Пользователи — в списке виден статус email verified; можно отправить письмо подтверждения повторно или заблокировать Public API для конкретного пользователя.

11.3. Проверка для интегратора

# Регистрация (пример)
curl -X POST http://localhost:5000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","email":"demo@example.ru","password":"DemoPass1","consent_pd":true}'

# Login после verify email
curl -X POST http://localhost:5000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"DemoPass1"}'

Подробный контракт — в документации Public Auth API.

12. Проверка установки

Убедитесь, что платформа работает:

1. Убедитесь, что сервис запущен: systemctl status cascad360 — состояние active (running) (см. раздел 2.4).
2. Убедитесь, что в config.yml установлено app.setup_completed: true.
3. Откройте http://localhost:5000/login и войдите с учётной записью администратора.
4. На главной странице панели проверьте, что статус системы отображается без ошибок.
5. Откройте БД ядра — должны отображаться таблицы основной базы.
6. Откройте Студия БД — выберите основную базу ядра, переключите таблицу и убедитесь, что данные обновляются корректно.
7. Откройте Public Swagger UI (/api/docs/public) — проверьте доступность OpenAPI spec.
8. Откройте Настройки → Почта — выполните тестовую отправку; проверьте health почты (статус ok после настройки SMTP).
9. Откройте Настройки → Public Auth — проверьте URL подтверждения email и параметры lockout.
10. Откройте Почта → Шаблоны — убедитесь, что есть system.auth.verify_email.
11. Опционально: проверка health-check с командной строки:

curl http://localhost:5000/api/health
# Ожидаемый ответ: {"status":"ok","version":"1.0.9", ...}