240 lines
8.1 KiB
Markdown
240 lines
8.1 KiB
Markdown
# Telegram CLI Bot
|
||
|
||
Бот для выполнения CLI команд на вашем ПК через Telegram с многоуровневым меню и гибкой настройкой.
|
||
|
||
## Возможности
|
||
|
||
- 🖥️ **Выполнение CLI команд** - запуск любых команд от имени пользователя
|
||
- 📋 **Многоуровневое меню** - навигация через inline-кнопки
|
||
- ⚙️ **Настройка из бота** - изменение имени, описания, иконки прямо в диалоге
|
||
- 🎯 **Предустановленные команды** - готовые команды для файловой системы, поиска, системы и сети
|
||
- 👥 **Управление доступом** - ограничение круга пользователей
|
||
- 🔧 **Легкое добавление команд** - простая регистрация новых команд через код
|
||
|
||
## Установка
|
||
|
||
### 1. Клонирование репозитория
|
||
|
||
```bash
|
||
cd /home/mirivlad/git
|
||
git clone <repository_url> telegram-cli-bot
|
||
cd telegram-cli-bot
|
||
```
|
||
|
||
### 2. Создание виртуального окружения
|
||
|
||
```bash
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
```
|
||
|
||
### 3. Установка зависимостей
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 4. Получение токена бота
|
||
|
||
1. Откройте [@BotFather](https://t.me/BotFather) в Telegram
|
||
2. Отправьте `/newbot`
|
||
3. Следуйте инструкциям
|
||
4. Скопируйте полученный токен
|
||
|
||
### 5. Настройка токена
|
||
|
||
**Способ 1: Через файл .env (рекомендуется)**
|
||
|
||
Скопируйте `.env.example` в `.env` и укажите токен:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# Отредактируйте .env, вставив ваш токен
|
||
```
|
||
|
||
**Способ 2: Через переменную окружения**
|
||
|
||
```bash
|
||
export TELEGRAM_BOT_TOKEN='your_token_here'
|
||
```
|
||
|
||
**Способ 3: Интерактивная настройка**
|
||
|
||
Запустите скрипт `run.sh` — он сам запросит токен:
|
||
|
||
```bash
|
||
./run.sh
|
||
```
|
||
|
||
### 6. Запуск бота
|
||
|
||
```bash
|
||
python bot.py
|
||
# или через скрипт
|
||
./run.sh
|
||
```
|
||
|
||
## Использование
|
||
|
||
### Команды бота
|
||
|
||
| Команда | Описание |
|
||
|---------|----------|
|
||
| `/start` | Запустить бота, показать главное меню |
|
||
| `/help` | Показать справку |
|
||
| `/settings` | Открыть настройки бота |
|
||
|
||
### Главное меню
|
||
|
||
- **🖥️ Выполнить команду** - ввод произвольной CLI команды
|
||
- **📋 Предустановленные команды** - меню с готовыми командами
|
||
- **⚙️ Настройки бота** - конфигурация бота
|
||
- **ℹ️ О боте** - информация о боте
|
||
|
||
### Предустановленные команды
|
||
|
||
#### Файловая система
|
||
- `ls -la` - список файлов
|
||
- `pwd` - текущая директория
|
||
- `df -h` - свободное место
|
||
- `du -sh *` - размер папок
|
||
|
||
#### Поиск
|
||
- `find . -name` - поиск файлов
|
||
- `grep пример` - поиск по содержимому
|
||
- `which command` - путь к командам
|
||
|
||
#### Система
|
||
- `top -n 1` - процессы
|
||
- `ps aux` - список процессов
|
||
- `free -h` - использование памяти
|
||
- `uname -a` - информация о системе
|
||
- `uptime` - время работы
|
||
|
||
#### Сеть
|
||
- `ip addr` - сетевые интерфейсы
|
||
- `ping google` - проверка связи
|
||
- `netstat` - сетевые подключения
|
||
- `curl ifconfig.me` - внешний IP
|
||
|
||
### Настройка бота
|
||
|
||
Через меню **⚙️ Настройки бота**:
|
||
|
||
1. **📝 Изменить имя бота** - новое отображаемое имя
|
||
2. **📄 Изменить описание** - описание бота
|
||
3. **🎨 Изменить иконку** - emoji для бота
|
||
4. **👥 Управление доступом** - whitelist пользователей
|
||
|
||
## Добавление новых команд
|
||
|
||
### Быстрое добавление через меню
|
||
|
||
Найдите функцию `init_menus()` в `bot.py` и добавьте новую кнопку:
|
||
|
||
```python
|
||
# В нужное меню добавьте:
|
||
MenuItem("🔥 Ваша команда", "cmd_your", command="ваша_команда", icon="🔥"),
|
||
```
|
||
|
||
### Пример добавления команды для git:
|
||
|
||
```python
|
||
# В init_menus() добавьте новое меню:
|
||
git_menu = [
|
||
MenuItem("git status", "cmd_git_status", command="git status", icon="📊"),
|
||
MenuItem("git log", "cmd_git_log", command="git log --oneline -10", icon="📜"),
|
||
MenuItem("⬅️ Назад", "preset", icon="⬅️"),
|
||
]
|
||
menu_builder.add_menu("git", git_menu)
|
||
|
||
# И добавьте кнопку в preset_menu:
|
||
MenuItem("🔗 Git", "git_menu", icon="🔗"),
|
||
```
|
||
|
||
### Продвинутое: регистрация через декоратор
|
||
|
||
Используйте `command_registry` для сложной логики:
|
||
|
||
```python
|
||
@command_registry.register("my_command")
|
||
async def my_custom_command(update, context):
|
||
# Ваша логика
|
||
pass
|
||
```
|
||
|
||
## Конфигурация
|
||
|
||
Все настройки хранятся в файле `.env`:
|
||
|
||
```bash
|
||
# Токен бота
|
||
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
|
||
|
||
# Настройки бота
|
||
BOT_NAME=CLI Assistant
|
||
BOT_DESCRIPTION=Бот для выполнения CLI команд
|
||
BOT_ICON_EMOJI=🤖
|
||
|
||
# Разрешённые пользователи (список ID через запятую)
|
||
# Пустой список = доступ открыт для всех
|
||
ALLOWED_USERS=123456789,987654321
|
||
|
||
# Рабочая директория для команд
|
||
WORKING_DIRECTORY=/home/user
|
||
```
|
||
|
||
| Параметр | Описание |
|
||
|----------|----------|
|
||
| `TELEGRAM_BOT_TOKEN` | Токен бота от @BotFather |
|
||
| `BOT_NAME` | Отображаемое имя бота |
|
||
| `BOT_DESCRIPTION` | Описание бота |
|
||
| `BOT_ICON_EMOJI` | Emoji-иконка |
|
||
| `ALLOWED_USERS` | Список разрешённых user ID через запятую (пусто = все) |
|
||
| `WORKING_DIRECTORY` | Рабочая директория для выполнения команд |
|
||
|
||
⚠️ **Важно:** После изменения `.env` требуется перезапуск бота.
|
||
|
||
## Безопасность
|
||
|
||
⚠️ **Важные предупреждения:**
|
||
|
||
1. Бот выполняет команды от имени запустившего пользователя
|
||
2. Не запускайте бота от root
|
||
3. Ограничьте доступ через `ALLOWED_USERS` в `.env`:
|
||
```bash
|
||
ALLOWED_USERS=123456789,987654321
|
||
```
|
||
Ваш ID можно узнать через @userinfobot
|
||
4. Будьте осторожны с деструктивными командами (`rm`, `dd`, etc.)
|
||
5. **Никогда не передавайте файл `.env`** — он содержит токен бота
|
||
6. Добавьте `.env` в `.gitignore` (уже сделано)
|
||
|
||
## Логи
|
||
|
||
Логи сохраняются в `bot.log` в директории бота.
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
telegram-cli-bot/
|
||
├── bot.py # Основной файл бота
|
||
├── requirements.txt # Зависимости Python
|
||
├── .env # Конфигурация (создаётся автоматически, не коммитить)
|
||
├── .env.example # Пример конфигурации
|
||
├── .gitignore # Git ignore
|
||
├── bot.log # Лог файл
|
||
├── run.sh # Скрипт запуска
|
||
└── README.md # Документация
|
||
```
|
||
|
||
## Требования
|
||
|
||
- Python 3.8+
|
||
- Библиотеки: `python-telegram-bot`, `pyyaml`
|
||
- Доступ к Telegram API
|
||
|
||
## Лицензия
|
||
|
||
MIT
|