102 lines
3.7 KiB
Markdown
102 lines
3.7 KiB
Markdown
# 09. Telegram Bot Architecture & Management Protocol
|
|
|
|
Tachyon includes an embedded, high-performance Telegram management bot written entirely in **ucode** (`service/telegram.uc`).
|
|
|
|
---
|
|
|
|
## 1. Architectural Highlights
|
|
|
|
```mermaid
|
|
graph LR
|
|
User[Telegram Client] -->|Encrypted HTTPS| TGAPI[Telegram Bot API Servers]
|
|
TGAPI -->|Long Polling: getUpdates| Daemon[Tachyon telegram.uc Daemon]
|
|
|
|
Daemon --> Auth{Admin Chat ID Match?}
|
|
Auth -->|No| Reject[Silent Ignore / Warning]
|
|
Auth -->|Yes| Router[Command & Callback Dispatcher]
|
|
|
|
Router -->|/doctor, /ai_doctor| AIDoc[AI Doctor Engine]
|
|
Router -->|/server, /switch| SrvMgr[Server Manager]
|
|
Router -->|/restart| SvcLife[Service Lifecycle]
|
|
Router -->|/status| StateRep[State Assembler]
|
|
```
|
|
|
|
* **No Public IP or Port Forwarding Required**: Uses outbound long-polling (`getUpdates` with 30s timeout) to securely communicate through NAT/firewalls.
|
|
* **Zero Overhead Memory Footprint**: Runs as a lightweight ucode process consuming under 2 MB RAM.
|
|
* **Role-Based Access Control**: Rejects any commands from chat IDs not explicitly listed in UCI option `telegram_chat_id`.
|
|
|
|
---
|
|
|
|
## 2. Command Set Reference
|
|
|
|
| Command | Arguments | Action |
|
|
|---|---|---|
|
|
| `/start` | — | Displays main welcome card and interactive control keyboard. |
|
|
| `/status` | — | Returns real-time health card: uptime, active server, RAM usage, ping RTT. |
|
|
| `/doctor` | — | Executes Local Rule Doctor and returns offline diagnostic report. |
|
|
| `/ai_doctor`| — | Invokes AI Doctor with LLM reasoning and returns diagnosis + fix buttons. |
|
|
| `/fix` | `<fix_code>` | Applies specific automated repair code (e.g. `/fix clear_dns_cache`). |
|
|
| `/server` | — | Opens interactive server selector with inline pagination and RTT pings. |
|
|
| `/rules` | — | Shows active routing rules with 1-click toggle switches. |
|
|
| `/restart` | `[service]` | Restarts sing-box, dnsmasq, watchdog, or entire network stack. |
|
|
| `/backup` | — | Sends latest atomic configuration backup directly to Telegram chat. |
|
|
|
|
---
|
|
|
|
## 3. Inline Keyboard & Callback Query Protocol
|
|
|
|
The bot uses dynamic inline keyboards (`InlineKeyboardMarkup`) for single-tap actions without typing commands.
|
|
|
|
### 3.1. Callback Data Scheme
|
|
Callbacks follow a structured token format: `action:target:param`
|
|
|
|
```
|
|
srv:select:node_1 # Switch active proxy server to node_1
|
|
rule:toggle:youtube # Toggle routing rule 'youtube' on/off
|
|
fix:apply:clear_dns_cache# Execute repair code 'clear_dns_cache'
|
|
page:srv:2 # Navigate to page 2 of server list
|
|
```
|
|
|
|
### 3.2. Example: Server Switcher Response
|
|
|
|
```json
|
|
{
|
|
"chat_id": 123456789,
|
|
"text": "⚡ <b>Выберите активный сервер:</b>\nТекущий: <i>🇩🇪 Frankfurt VLESS (18 ms)</i>",
|
|
"parse_mode": "HTML",
|
|
"reply_markup": {
|
|
"inline_keyboard": [
|
|
[
|
|
{"text": "🇩🇪 Frankfurt (18 ms) ✅", "callback_data": "srv:select:de_1"},
|
|
{"text": "🇳🇱 Amsterdam (24 ms)", "callback_data": "srv:select:nl_1"}
|
|
],
|
|
[
|
|
{"text": "🇫🇮 Helsinki (31 ms)", "callback_data": "srv:select:fi_1"},
|
|
{"text": "🇺🇸 New York (95 ms)", "callback_data": "srv:select:us_1"}
|
|
],
|
|
[
|
|
{"text": "🔄 Замерить пинг", "callback_data": "srv:ping:all"},
|
|
{"text": "🩺 Запустить Доктора", "callback_data": "cmd:doctor"}
|
|
]
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Configuration via CLI
|
|
|
|
```sh
|
|
# Set Bot Token
|
|
uci set tachyon.settings.enable_telegram='1'
|
|
uci set tachyon.settings.telegram_token='123456789:ABCdefGHIjklMNOpqrsTUVwxyz'
|
|
|
|
# Set Authorized Chat ID(s)
|
|
uci set tachyon.settings.telegram_chat_id='123456789'
|
|
|
|
# Commit and restart service
|
|
uci commit tachyon
|
|
/etc/init.d/tachyon restart
|
|
```
|