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. Эта команда:
- Загружает актуальный
src/Install/permissions.csvиз веткиreleaseupstream-репозитория - Подключается к базе данных VPS по SSH
- Выполняет
INSERT IGNOREдля каждой строки в таблицуrole_permission
INSERT IGNORE означает, что существующие кастомные права никогда не перезаписываются — добавляются только отсутствующие строки. Запускайте эту команду повторно при синхронизации с upstream, если подозреваете, что были добавлены новые эндпоинты.
Поддержка экземпляра в актуальном состоянии
Синхронизация с upstream
Команда Update обрабатывает получение изменений из upstream в ваш форк:
- Получает хеш последнего коммита из ветки
releaseupstream - Сравнивает его с последним задеплоенным коммитом из вашего конфига
- Генерирует SQL-миграцию, сравнивая upstream
default_tables.sqlс вашей живой схемой - Представляет каждый шаг миграции по отдельности — вы проверяете и одобряете перед применением
- Каждый шаг включает
ForwardиRevertSQL; при сбое шага все предыдущие автоматически откатываются - После применения изменений схемы мержит ветку
releaseupstream в ваш форк и пушит — автоматически запуская 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, соблюдайте эти правила:
- Используйте только неинтерактивные команды. Никогда не управляйте интерактивным меню, подавая ответы через stdin.
- Начинайте с чтения. Сначала выполните
cuento-cli listиcuento-cli diagnostics --project NAME --jsonи сообщите, что нашли. - Обновление рабочего форума решает человек. Спрашивайте перед запуском
updateилиreset-pipelineдля любого проекта, даже если вас попросили лишь «проверить» или «подготовить» обновление. - Никогда не добавляйте
--apply-migrationсамостоятельно. Запуститеupdateбез флага, покажите человеку выведенный SQL миграции и повторите с флагом только после того, как он одобрит этот SQL. - Проверяйте код выхода.
0— готово;1— операция не удалась: прочитайте вывод и сообщите о нём, не повторяйте вслепую;2— ошибка в командной строке. - Никогда не читайте, не выводите и не редактируйте файл конфигурации. В нём хранятся GitHub-токен и пароли сервера.