CLI и деплой

Cuento CLI — интерактивный инструмент с меню, который управляет всем жизненным циклом деплоя: от форка исходных репозиториев до подготовки VPS, запуска деплой-пайплайнов и управления живым экземпляром.

Установка CLI

Скачайте готовый бинарник для вашей ОС со страницы GitHub Releases. Установка не нужна — запустите напрямую:

# macOS
chmod +x cuento-cli-macos
./cuento-cli-macos

# Windows
cuento-cli-windows.exe

CLI не имеет флагов или подкоманд. Всё управляется через интерактивные меню.

Создание нового проекта

Выбор Create new project в главном меню запускает 21-шаговый мастер. При прерывании на любом шаге следующий запуск продолжит с того места, где остановился — прогресс сохраняется в ~/.config/cuento/config.json после каждого завершённого шага.

Что собирает мастер

Перед началом работы мастер запрашивает:

  • Персональный токен GitHub (нужны права repo и workflow)
  • Ваш GitHub-логин
  • IP-адрес VPS, SSH-пользователя и SSH/sudo-пароли
  • Доменное имя для форума
  • Учётные данные базы данных (root-пароль + выделенный пользователь/пароль приложения)

Всё сохраняется в ~/.config/cuento/config.json (режим 0600) и переиспользуется при повторных запусках.

Шаг 1 — Форк репозиториев

CLI форкает cuento-backend и cuento-frontend на ваш GitHub-аккаунт через GitHub API. Форки — это репозитории, из которых будут собираться и деплоиться ваши CI/CD-пайплайны. Форки принадлежат вам — изменения из upstream-репозитория вносятся явно через команду Update, а не автоматически.

Шаги 2–6 — Настройка секретов GitHub Actions

Мастер устанавливает следующие секреты в оба форка через GitHub API:

Секрет Значение
SSH_HOST IP-адрес VPS
SSH_USER SSH-пользователь
SSH_PRIVATE_KEY ed25519 приватный ключ (генерируется на этом шаге)
DB_PASSWORD Пароль пользователя базы данных приложения
DOMAIN Домен форума

На этом шаге локально генерируется пара ключей ed25519. Приватный ключ сохраняется как секрет SSH_PRIVATE_KEY, чтобы GitHub Actions мог подключаться к VPS по SSH для деплоя. Публичный ключ загружается в ~/.ssh/authorized_keys на сервере на более позднем шаге.

Шаги 7–14 — Подготовка VPS

CLI подключается к серверу по SSH и устанавливает полный продакшен-стек:

MariaDB — устанавливается через apt, настраивается с указанными root и app-учётными данными. Создаются база данных и пользователь приложения.

Caddy — устанавливается как обратный прокси. Caddyfile записывается со следующей структурой маршрутов:

your-domain.com {
  handle /ws*       { reverse_proxy 127.0.0.1:8080 { flush_interval -1 } }
  handle /api/*     { uri strip_prefix /api; reverse_proxy 127.0.0.1:8080 }
  handle /backend/* { file_server { root /var/www/backend } }
  handle            { file_server { root /var/www/frontend; try_files {path} /index.html } }
}

Маршрут /ws использует flush_interval -1 для поддержания WebSocket-соединений. Catch-all раздаёт Angular SPA с fallback на index.html для клиентской маршрутизации.

Systemd-сервис — юнит cuento-backend.service записывается в /etc/systemd/system/. Бэкенд запускается от имени выделенного пользователя cuento, бинарник находится по адресу /var/www/backend/cuento-backend. Переменные окружения (учётные данные БД, домен и т. д.) записываются непосредственно в файл юнита.

Брандмауэр — ufw настраивается на разрешение только портов 22, 80 и 443.

SSH-ключ — сгенерированный публичный ключ добавляется в ~/.ssh/authorized_keys, чтобы runner GitHub Actions мог деплоить без пароля.

Шаги 15–17 — Загрузка деплой-воркфлоу

CLI загружает файлы GitHub Actions-воркфлоу в ваши форки:

Воркфлоу Ветка Триггер Что делает
backend/deploy.yml release Push в release Собирает Go-бинарник, копирует на VPS через SCP, перезапускает systemd-сервис
frontend/deploy.yml release Push в release Запускает npm run build, копирует _site/ в /var/www/frontend на VPS
frontend/monitor.yml monitor Push в monitor То же, что деплой фронтенда, но с инструментацией New Relic

Файлы воркфлоу встроены в бинарник CLI во время компиляции. Плейсхолдер __PROJECT_NAME__ в шаблонах заменяется именем вашего проекта на этом шаге.

Шаги 18–21 — Установка вспомогательных сервисов

Три дополнительных GitHub Actions-воркфлоу загружаются и автоматически запускаются на runner-е форка:

Sonic — поисковый движок для полнотекстового поиска. Устанавливает бинарник, записывает sonic.cfg и регистрирует systemd-юнит.

Qdrant — векторная база данных для семантического поиска. Устанавливает бинарник и регистрирует systemd-юнит.

nginx image hosting — опциональный сервис для проксирования изображений с S3-аутентификацией. Собирается из исходников с модулем ngx_aws_auth. Systemd-юнит регистрируется, но оставляется остановленным; порт 8888 остаётся закрытым до ручного включения.

После завершения этих воркфлоу VPS полностью готов к работе.

Как работают деплои после настройки

Деплои запускаются пушем в ветку release форкнутого репозитория бэкенда или фронтенда. GitHub Actions подключается к VPS по SSH, копирует новый бинарник или результат сборки и перезапускает сервис. SSH в продакшен не требуется.

# Деплой бэкенда
git checkout release
git merge main
git push origin release

# Деплой фронтенда — та же схема
git checkout release
git merge main
git push origin release

Деплой бэкенда перезапускает cuento-backend.service через systemd. Деплой фронтенда заменяет содержимое /var/www/frontend без перезапуска сервисов, так как Caddy раздаёт статические файлы напрямую.

Первые шаги после деплоя

Настройка суперпользователя

После первого деплоя в базе данных нет настоящих аккаунтов — только системные пользователи guest (ID 0) и The Nameless One (ID 1). Создайте первый admin-аккаунт через команду Add user в CLI, затем сразу запустите для него Set superuser. Первый созданный аккаунт получает ID 2.

Add user запрашивает логин и пароль, хеширует пароль через SHA-256, затем bcrypt, и вставляет строку в таблицы users и user_role напрямую через SSH к базе данных VPS. Роль user выдаётся всегда, а admin — если ответить «да» на вопрос Make this user an admin?

Set superuser записывает переменную окружения SUPERUSER_ID в файл systemd-юнита, затем выполняет systemctl daemon-reload и перезапускает сервис:

# /etc/systemd/system/cuento-backend.service
[Service]
Environment="SUPERUSER_ID=2"

Бэкенд читает SUPERUSER_ID один раз при запуске (Services/user_service.go). Значение не хранится в базе данных, поэтому меняется только при повторном запуске команды.

Что может суперпользователь:

  • Эксклюзивные функции — настройка ИИ-моделей (Controllers/ai_model.go), резервные копии в Google Drive (Controllers/backup.go) и настройки с пометкой needs_superuser в global_settings, например API-ключи (Controllers/settings.go). Ни одна роль их не даёт.
  • Обход прав эндпоинтов — Middlewares/permissions.go не проверяет для суперпользователя таблицу role_permission, поэтому он работает даже до импорта прав.
  • Не обходится — правила доступа к подфорумам (права типа 1) распространяются и на суперпользователя.

Импорт прав доступа по умолчанию

Система прав доступа контролирует, какие роли пользователей могут обращаться к каким API-эндпоинтам. Значения по умолчанию определены в permissions.csv в upstream-репозитории бэкенда.

После первого деплоя запустите Import default permissions из меню CLI. Эта команда:

  1. Загружает актуальный src/Install/permissions.csv из ветки release upstream-репозитория
  2. Подключается к базе данных VPS по SSH
  3. Выполняет INSERT IGNORE для каждой строки в таблицу role_permission

INSERT IGNORE означает, что существующие кастомные права никогда не перезаписываются — добавляются только отсутствующие строки. Запускайте эту команду повторно при синхронизации с upstream, если подозреваете, что были добавлены новые эндпоинты.

Поддержка экземпляра в актуальном состоянии

Синхронизация с upstream

Команда Update обрабатывает получение изменений из upstream в ваш форк:

  1. Получает хеш последнего коммита из ветки release upstream
  2. Сравнивает его с последним задеплоенным коммитом из вашего конфига
  3. Генерирует SQL-миграцию, сравнивая upstream default_tables.sql с вашей живой схемой
  4. Представляет каждый шаг миграции по отдельности — вы проверяете и одобряете перед применением
  5. Каждый шаг включает Forward и Revert SQL; при сбое шага все предыдущие автоматически откатываются
  6. После применения изменений схемы мержит ветку release upstream в ваш форк и пушит — автоматически запуская CI-деплой

Сброс деплой-пайплайна

При обновлении CLI до новой версии встроенные файлы воркфлоу могут измениться. Запустите Reset deployment pipeline, чтобы повторно загрузить все файлы воркфлоу в ветки main, release и monitor обоих форков. Безопасно запускать в любое время — обновляются только YAML-файлы, не код приложения.

Диагностика базы данных

Database diagnostics подключается к живой базе данных VPS, сравнивает текущую схему с upstream default_tables.sql и показывает разницу с уровнями риска для каждого изменения:

Риск Смысл
Minimal Добавление nullable-колонки или индекса
Low Изменение значения по умолчанию для колонки
Medium Изменение типа колонки
High Удаление колонки или таблицы

Отсюда можно применять отдельные изменения в интерактивном режиме. Удобно для исследования расхождений схемы между вашим форком и upstream без полного обновления.

Неинтерактивный режим

Начиная с CLI 2.1.0 бинарник также выполняет отдельные команды из аргументов, поэтому его могут использовать скрипты и ИИ-агенты. Без аргументов он, как и раньше, открывает интерактивное меню.

cuento-cli list                                         # имена сохранённых проектов
cuento-cli update --project NAME [--apply-migration]
cuento-cli diagnostics --project NAME [--json]
cuento-cli reset-pipeline --project NAME
  • Команды никогда ничего не спрашивают. Учётные данные берутся из файла конфигурации проекта (см. ниже); флагов для токенов и паролей нет.
  • update выводит SQL миграции и останавливается до слияния, если схема изменилась, — пока не указан --apply-migration. Код никогда не деплоится без соответствующего изменения схемы.
  • diagnostics только формирует отчёт; создание и изменение таблиц остаётся в интерактивном меню. --json выводит отчёт в формате JSON в stdout.
  • Коды выхода: 0 успех, 1 операция не удалась, 2 неверное использование.

Файл конфигурации проекта

Всё, что нужно CLI для управления экземпляром, хранится в ~/.config/cuento/config.json (режим 0600): GitHub-токен, учётные данные VPS, пара SSH-ключей, пароли базы данных и счётчик setup_step для возобновления мастера. Сделайте резервную копию этого файла — его потеря означает повторный ввод всех учётных данных вручную.

Инструкция для ИИ-агента

Если вы ИИ-агент и управляете экземпляром Cuento через CLI, соблюдайте эти правила:

  1. Используйте только неинтерактивные команды. Никогда не управляйте интерактивным меню, подавая ответы через stdin.
  2. Начинайте с чтения. Сначала выполните cuento-cli list и cuento-cli diagnostics --project NAME --json и сообщите, что нашли.
  3. Обновление рабочего форума решает человек. Спрашивайте перед запуском update или reset-pipeline для любого проекта, даже если вас попросили лишь «проверить» или «подготовить» обновление.
  4. Никогда не добавляйте --apply-migration самостоятельно. Запустите update без флага, покажите человеку выведенный SQL миграции и повторите с флагом только после того, как он одобрит этот SQL.
  5. Проверяйте код выхода. 0 — готово; 1 — операция не удалась: прочитайте вывод и сообщите о нём, не повторяйте вслепую; 2 — ошибка в командной строке.
  6. Никогда не читайте, не выводите и не редактируйте файл конфигурации. В нём хранятся GitHub-токен и пароли сервера.