added readme
This commit is contained in:
Uber Veng
561
README.md
Normal file
561
README.md
Normal file
@@ -0,0 +1,561 @@
|
||||
# TUI Client — удалённый запуск скриптов
|
||||
|
||||
Консольный клиент с текстовым интерфейсом (TUI) на Rust. Загружает иерархическое меню с сервера и позволяет запускать bash-скрипты, скачивать файлы и выполнять HTTP-запросы прямо из терминала. Все диалоги (выбор из списка, подтверждение, ввод текста) реализованы внутри интерфейса — никаких сырых `read -p` в терминале.
|
||||
|
||||
---
|
||||
|
||||
## Навигация
|
||||
|
||||
| Клавиша | Действие |
|
||||
|---|---|
|
||||
| `↑` / `↓` | Перемещение по списку |
|
||||
| `Enter` | Войти в категорию / запустить действие |
|
||||
| `Esc` | Выйти из категории / закрыть popup / отменить скрипт |
|
||||
| `q` | Выйти из приложения |
|
||||
| `R` | Перезагрузить меню с сервера |
|
||||
|
||||
В попапе запущенного скрипта:
|
||||
|
||||
| Клавиша | Действие |
|
||||
|---|---|
|
||||
| `↑` / `↓` | Прокрутка лога (если нет активного запроса) / навигация по селектору |
|
||||
| `PgUp` / `PgDn` | Прокрутка лога на 10 строк |
|
||||
| `Y` / `N` | Быстрый ответ на подтверждение |
|
||||
| `Esc` | Прервать скрипт и закрыть popup |
|
||||
|
||||
---
|
||||
|
||||
## Конфигурация
|
||||
|
||||
При первом запуске создаётся файл `~/.config/tui-client/config.toml`:
|
||||
|
||||
```toml
|
||||
server_url = "http://your-server/api/menu"
|
||||
timeout_sec = 10
|
||||
|
||||
[theme]
|
||||
selected_bg = "blue"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Формат меню (JSON)
|
||||
|
||||
Сервер должен отдавать `GET /api/menu` с `Content-Type: application/json`.
|
||||
|
||||
### Корневая структура
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"menu": [ ...пункты... ]
|
||||
}
|
||||
```
|
||||
|
||||
### Категория
|
||||
|
||||
Содержит вложенные пункты. Отображается с иконкой `📁`.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "bitrix",
|
||||
"title": "1С Битрикс",
|
||||
"description": "Инструменты администрирования",
|
||||
"children": [
|
||||
...пункты меню...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обязательное | Описание |
|
||||
|---|---|---|
|
||||
| `id` | ✓ | Уникальный идентификатор |
|
||||
| `title` | ✓ | Отображаемое название |
|
||||
| `description` | — | Текст в нижней панели при выборе |
|
||||
| `children` | ✓ | Вложенные категории и действия |
|
||||
|
||||
### Действие
|
||||
|
||||
Отображается с иконкой `⚡`.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "db_manage",
|
||||
"title": "Управление БД",
|
||||
"description": "Дамп, импорт, подключение к базе",
|
||||
"action": {
|
||||
"type": "bash",
|
||||
"script": "#!/bin/bash\necho hello",
|
||||
"interaction": "structured",
|
||||
"confirm": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обязательное | Описание |
|
||||
|---|---|---|
|
||||
| `id` | ✓ | Уникальный идентификатор |
|
||||
| `title` | ✓ | Отображаемое название |
|
||||
| `description` | — | Текст в нижней панели |
|
||||
| `action` | ✓ | Объект действия |
|
||||
|
||||
#### `confirm` и `confirm_message`
|
||||
|
||||
Если `confirm: true`, перед запуском появится диалог подтверждения.
|
||||
`confirm_message` переопределяет текст вопроса.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "drop_db",
|
||||
"title": "Удалить базу данных",
|
||||
"action": {
|
||||
"type": "bash",
|
||||
"script": "...",
|
||||
"interaction": "structured",
|
||||
"confirm": true,
|
||||
"confirm_message": "Внимание! База данных будет удалена без возможности восстановления. Продолжить?"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Типы действий
|
||||
|
||||
### `bash` — запуск скрипта
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "bash",
|
||||
"script": "#!/bin/bash\n...",
|
||||
"interaction": "structured",
|
||||
"confirm": false
|
||||
}
|
||||
```
|
||||
|
||||
| Параметр | Значения | Описание |
|
||||
|---|---|---|
|
||||
| `script` | строка | Полный текст bash-скрипта включая shebang |
|
||||
| `interaction` | `"structured"` / `"terminal"` | Режим взаимодействия (см. ниже) |
|
||||
| `confirm` | `true` / `false` | Запросить подтверждение перед запуском |
|
||||
| `confirm_message` | строка | Кастомный текст диалога подтверждения |
|
||||
|
||||
**`interaction: "terminal"`** — скрипт запускается как дочерний процесс, вывод игнорируется клиентом. Подходит для простых неинтерактивных команд.
|
||||
|
||||
**`interaction: "structured"`** — скрипт общается с клиентом через протокол команд (см. раздел ниже). Весь вывод отображается в прокручиваемом логе с поддержкой ANSI-цветов. Поддерживает интерактивные элементы: селекторы, поля ввода, подтверждения.
|
||||
|
||||
### `download` — скачивание файла
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "download",
|
||||
"url": "https://example.com/file.tar.gz",
|
||||
"filename": "backup.tar.gz",
|
||||
"target_dir": "/var/backups",
|
||||
"confirm": false
|
||||
}
|
||||
```
|
||||
|
||||
| Параметр | Описание |
|
||||
|---|---|
|
||||
| `url` | Адрес файла |
|
||||
| `filename` | Имя сохраняемого файла (по умолчанию — из URL) |
|
||||
| `target_dir` | Директория сохранения (по умолчанию — текущая) |
|
||||
|
||||
### `download_and_run` — скачать и выполнить
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "download_and_run",
|
||||
"url": "https://example.com/installer.sh",
|
||||
"run_args": ["--silent", "--prefix=/opt"],
|
||||
"keep_file": false,
|
||||
"confirm": true
|
||||
}
|
||||
```
|
||||
|
||||
| Параметр | Описание |
|
||||
|---|---|
|
||||
| `run_args` | Аргументы командной строки |
|
||||
| `keep_file` | Оставить файл после выполнения (по умолчанию `false`) |
|
||||
|
||||
### `http_request` — HTTP-запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "http_request",
|
||||
"method": "POST",
|
||||
"url": "https://api.example.com/deploy",
|
||||
"headers": {
|
||||
"Authorization": "Bearer token123",
|
||||
"Content-Type": "application/json"
|
||||
},
|
||||
"body": "{\"env\": \"production\"}",
|
||||
"confirm": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Интерактивные скрипты (structured)
|
||||
|
||||
При `interaction: "structured"` скрипт может запрашивать у пользователя данные через специальный протокол. Клиент показывает соответствующий элемент интерфейса ratatui и ждёт ответа.
|
||||
|
||||
### Базовые хелперы
|
||||
|
||||
Добавьте эти функции в начало каждого интерактивного скрипта:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# Отправить команду и получить ответ от пользователя
|
||||
ask() {
|
||||
printf 'CMD:%s\n' "$1" >&2
|
||||
read -r _response
|
||||
printf '%s' "$_response"
|
||||
}
|
||||
|
||||
# Отправить уведомление (не ждёт ответа)
|
||||
notify() {
|
||||
printf 'CMD:%s\n' "$1" >&2
|
||||
}
|
||||
```
|
||||
|
||||
Команды отправляются в **stderr** (`>&2`), ответы приходят в **stdin** через `read`. Это позволяет использовать `$(ask '...')` для захвата результата.
|
||||
|
||||
---
|
||||
|
||||
### Ввод текста (`input`)
|
||||
|
||||
Показывает текстовое поле с заголовком. Поддерживает маскировку для паролей.
|
||||
|
||||
**Команда:**
|
||||
```json
|
||||
{"type":"input","prompt":"Введите имя пользователя:","default":"admin","secret":false}
|
||||
```
|
||||
|
||||
| Поле | Описание |
|
||||
|---|---|
|
||||
| `prompt` | Заголовок поля ввода |
|
||||
| `default` | Значение по умолчанию (опционально) |
|
||||
| `secret` | Если `true` — символы заменяются на `•` |
|
||||
|
||||
**Пример:**
|
||||
```bash
|
||||
username=$(ask '{"type":"input","prompt":"Имя пользователя:","default":"admin"}')
|
||||
password=$(ask '{"type":"input","prompt":"Пароль:","secret":true}')
|
||||
echo "Логин: $username"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Выбор из списка (`menu`)
|
||||
|
||||
Показывает список с навигацией `↑`/`↓` и выбором по `Enter`. Возвращает `id` выбранного пункта.
|
||||
|
||||
**Команда:**
|
||||
```json
|
||||
{
|
||||
"type": "menu",
|
||||
"prompt": "Выберите действие:",
|
||||
"options": [
|
||||
{"id": "dump", "label": "Создать дамп базы"},
|
||||
{"id": "import", "label": "Импортировать дамп"},
|
||||
{"id": "connect","label": "Подключиться к БД"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Описание |
|
||||
|---|---|
|
||||
| `prompt` | Заголовок списка |
|
||||
| `options` | Массив объектов `{"id": "...", "label": "..."}` |
|
||||
|
||||
**Ответ:** строка `id` выбранного пункта.
|
||||
|
||||
**Пример:**
|
||||
```bash
|
||||
action=$(ask '{"type":"menu","prompt":"Выберите действие:","options":[
|
||||
{"id":"dump","label":"Создать дамп"},
|
||||
{"id":"import","label":"Импортировать"},
|
||||
{"id":"exit","label":"Отмена"}
|
||||
]}')
|
||||
|
||||
case $action in
|
||||
dump) echo "Создаю дамп..." ;;
|
||||
import) echo "Импортирую..." ;;
|
||||
exit) exit 0 ;;
|
||||
esac
|
||||
```
|
||||
|
||||
**Динамический список** (например, файлы на диске):
|
||||
```bash
|
||||
files=($(ls *.sql 2>/dev/null))
|
||||
|
||||
options='['
|
||||
for i in "${!files[@]}"; do
|
||||
[ $i -gt 0 ] && options+=','
|
||||
escaped=$(printf '%s' "${files[$i]}" | sed 's/"/\\"/g')
|
||||
options+="{\"id\":\"$i\",\"label\":\"${escaped}\"}"
|
||||
done
|
||||
options+=']'
|
||||
|
||||
idx=$(ask "{\"type\":\"menu\",\"prompt\":\"Выберите файл:\",\"options\":${options}}")
|
||||
selected="${files[$idx]}"
|
||||
echo "Выбран: $selected"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Подтверждение (`confirm`)
|
||||
|
||||
Показывает вопрос с кнопками `[Y] Да` и `[N] Нет`. Нажатия `Y`/`N` обрабатываются без `Enter`.
|
||||
|
||||
**Команда:**
|
||||
```json
|
||||
{"type":"confirm","prompt":"Данные будут перезаписаны. Продолжить?"}
|
||||
```
|
||||
|
||||
**Ответ:** `"y"` или `"n"`.
|
||||
|
||||
**Пример:**
|
||||
```bash
|
||||
answer=$(ask '{"type":"confirm","prompt":"Удалить временные файлы?"}')
|
||||
|
||||
if [[ "$answer" =~ ^[Yy]$ ]]; then
|
||||
rm -rf /tmp/myapp_*
|
||||
echo "Файлы удалены"
|
||||
else
|
||||
echo "Отменено"
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Сообщение (`message`)
|
||||
|
||||
Показывает информационное сообщение с цветовым выделением. Скрипт продолжается после нажатия `Enter`.
|
||||
|
||||
**Команда:**
|
||||
```json
|
||||
{"type":"message","level":"info","text":"Операция завершена успешно!"}
|
||||
```
|
||||
|
||||
| `level` | Цвет | Когда использовать |
|
||||
|---|---|---|
|
||||
| `"info"` | Зелёный | Успешное завершение, информация |
|
||||
| `"warn"` | Жёлтый | Предупреждение, нестандартная ситуация |
|
||||
| `"error"` | Красный | Ошибка, критическая проблема |
|
||||
|
||||
**Пример:**
|
||||
```bash
|
||||
if ! command -v mysqldump &> /dev/null; then
|
||||
ask '{"type":"message","level":"error","text":"mysqldump не найден. Установите пакет mysql-client."}' > /dev/null
|
||||
exit 1
|
||||
fi
|
||||
|
||||
ask '{"type":"message","level":"warn","text":"База данных занимает более 10 ГБ. Дамп может занять несколько минут."}' > /dev/null
|
||||
|
||||
echo "Начинаю создание дампа..."
|
||||
```
|
||||
|
||||
> `> /dev/null` — сбрасывает пустой ответ клиента, чтобы он не попал в переменную.
|
||||
|
||||
---
|
||||
|
||||
### Прогресс (`progress`)
|
||||
|
||||
Обновляет прогресс-бар без остановки скрипта. Скрипт продолжает выполнение немедленно.
|
||||
|
||||
**Команда:**
|
||||
```json
|
||||
{"type":"progress","percent":45,"message":"Копирование файлов..."}
|
||||
```
|
||||
|
||||
| Поле | Описание |
|
||||
|---|---|
|
||||
| `percent` | Число от 0 до 100 |
|
||||
| `message` | Подпись под прогресс-баром (опционально) |
|
||||
|
||||
**Пример:**
|
||||
```bash
|
||||
notify '{"type":"progress","percent":0,"message":"Начало..."}'
|
||||
|
||||
mysqldump -h "$host" -u "$user" "$db" > backup.sql
|
||||
notify '{"type":"progress","percent":60,"message":"Дамп создан, сжимаю..."}'
|
||||
|
||||
gzip backup.sql
|
||||
notify '{"type":"progress","percent":100,"message":"Готово!"}'
|
||||
echo "Файл: backup.sql.gz ($(du -h backup.sql.gz | cut -f1))"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Запуск внешнего приложения (`exec`)
|
||||
|
||||
Временно **передаёт терминал** внешней программе (mysql, vim, htop и т.д.). Клиент скрывает ratatui, программа работает на полном экране, после завершения TUI восстанавливается. Возвращает код завершения.
|
||||
|
||||
**Команда:**
|
||||
```json
|
||||
{"type":"exec","shell":"mysql -h localhost -u root mydb"}
|
||||
```
|
||||
|
||||
| Поле | Описание |
|
||||
|---|---|
|
||||
| `shell` | Команда, которая будет выполнена через `bash -c` |
|
||||
|
||||
**Ответ:** код завершения программы (`"0"`, `"1"` и т.д.).
|
||||
|
||||
**Примеры:**
|
||||
```bash
|
||||
# Интерактивная сессия mysql
|
||||
exit_code=$(ask "{\"type\":\"exec\",\"shell\":\"mysql -h \\\"$host\\\" -u \\\"$user\\\" -p\\\"$pass\\\" \\\"$db\\\"\"}")
|
||||
echo "Сессия завершена (код: $exit_code)"
|
||||
|
||||
# Редактирование конфига
|
||||
ask '{"type":"exec","shell":"vim /etc/nginx/nginx.conf"}' > /dev/null
|
||||
notify '{"type":"progress","percent":0,"message":"Перезагружаю nginx..."}'
|
||||
systemctl reload nginx
|
||||
|
||||
# Мониторинг ресурсов
|
||||
ask '{"type":"exec","shell":"htop"}' > /dev/null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Полный пример скрипта
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
ask() {
|
||||
printf 'CMD:%s\n' "$1" >&2
|
||||
read -r _response
|
||||
printf '%s' "$_response"
|
||||
}
|
||||
|
||||
notify() {
|
||||
printf 'CMD:%s\n' "$1" >&2
|
||||
}
|
||||
|
||||
# Запрос данных
|
||||
host=$(ask '{"type":"input","prompt":"Хост базы данных:","default":"localhost"}')
|
||||
db=$(ask '{"type":"input","prompt":"Имя базы данных:"}')
|
||||
user=$(ask '{"type":"input","prompt":"Пользователь:","default":"root"}')
|
||||
pass=$(ask '{"type":"input","prompt":"Пароль:","secret":true}')
|
||||
|
||||
echo "Подключаюсь к $db на $host..."
|
||||
|
||||
# Выбор действия
|
||||
action=$(ask "{\"type\":\"menu\",\"prompt\":\"Выберите действие:\",\"options\":[
|
||||
{\"id\":\"dump\", \"label\":\"Создать дамп\"},
|
||||
{\"id\":\"shell\", \"label\":\"Открыть mysql-консоль\"},
|
||||
{\"id\":\"cancel\", \"label\":\"Отмена\"}
|
||||
]}")
|
||||
|
||||
case $action in
|
||||
dump)
|
||||
confirm=$(ask '{"type":"confirm","prompt":"Создать дамп базы данных?"}')
|
||||
[[ ! "$confirm" =~ ^[Yy]$ ]] && exit 0
|
||||
|
||||
backup="backup_${db}_$(date +%Y%m%d_%H%M%S).sql"
|
||||
notify '{"type":"progress","percent":10,"message":"Создание дампа..."}'
|
||||
|
||||
if mysqldump -h "$host" -u "$user" -p"$pass" "$db" > "$backup"; then
|
||||
notify '{"type":"progress","percent":100,"message":"Готово!"}'
|
||||
echo "Дамп сохранён: $backup ($(du -h "$backup" | cut -f1))"
|
||||
else
|
||||
ask '{"type":"message","level":"error","text":"Ошибка при создании дампа!"}' > /dev/null
|
||||
exit 1
|
||||
fi
|
||||
;;
|
||||
|
||||
shell)
|
||||
echo "Открываю mysql-консоль..."
|
||||
code=$(ask "{\"type\":\"exec\",\"shell\":\"mysql -h \\\"$host\\\" -u \\\"$user\\\" -p\\\"$pass\\\" \\\"$db\\\"\"}")
|
||||
echo "Сессия завершена с кодом $code"
|
||||
;;
|
||||
|
||||
cancel)
|
||||
echo "Отменено"
|
||||
exit 0
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Структура сервера
|
||||
|
||||
Рекомендуемая организация серверной части:
|
||||
|
||||
```
|
||||
server/
|
||||
├── index.php # Собирает JSON из menu_structure.json + scripts/
|
||||
├── menu_structure.json # Иерархия меню (script_file вместо script)
|
||||
└── scripts/
|
||||
├── bitrix_db_manage.sh
|
||||
├── bitrix_monitoring.sh
|
||||
└── wordpress_db_backup.sh
|
||||
```
|
||||
|
||||
В `menu_structure.json` вместо поля `"script"` используется `"script_file"`:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "db_manage",
|
||||
"title": "Управление БД",
|
||||
"action": {
|
||||
"type": "bash",
|
||||
"script_file": "bitrix_db_manage.sh",
|
||||
"interaction": "structured",
|
||||
"confirm": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`index.php` подставляет содержимое файла при каждом запросе — скрипты редактируются без изменения JSON.
|
||||
|
||||
### Добавление нового пункта меню
|
||||
|
||||
1. Создать скрипт `server/scripts/myapp_action.sh`
|
||||
2. Добавить пункт в `menu_structure.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "myapp_action",
|
||||
"title": "Название в меню",
|
||||
"description": "Описание для нижней панели",
|
||||
"action": {
|
||||
"type": "bash",
|
||||
"script_file": "myapp_action.sh",
|
||||
"interaction": "structured",
|
||||
"confirm": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Именование файлов: `{категория}_{подкатегория}_{действие}.sh`
|
||||
|
||||
---
|
||||
|
||||
## Сборка
|
||||
|
||||
**Linux:**
|
||||
```bash
|
||||
cd Ratatui
|
||||
cargo build --release
|
||||
# → target/release/tui-client
|
||||
```
|
||||
|
||||
**Кросс-компиляция с macOS → Linux (musl, статический бинарь):**
|
||||
```bash
|
||||
rustup target add x86_64-unknown-linux-musl
|
||||
brew install FiloSottile/musl-cross/musl-cross
|
||||
|
||||
CARGO_TARGET_X86_64_UNKNOWN_LINUX_MUSL_LINKER=x86_64-linux-musl-gcc \
|
||||
cargo build --release --target x86_64-unknown-linux-musl
|
||||
# → target/x86_64-unknown-linux-musl/release/tui-client
|
||||
```
|
||||
|
||||
Бинарь собирается статически и не требует никаких зависимостей на целевом сервере.
|
||||
Reference in New Issue
Block a user