215 lines
5.9 KiB
Markdown
215 lines
5.9 KiB
Markdown
# Telegram Infrastructure
|
||
|
||
Мінімальний стек для інтеграції Telegram-ботів з системою агентів DAGI/microDAO.
|
||
|
||
## 🏗️ Архітектура
|
||
|
||
Цей стек складається з трьох сервісів:
|
||
|
||
### 1. **telegram-bot-api** (Local Telegram Bot API)
|
||
- Офіційний Local Telegram Bot API від Telegram
|
||
- Працює в режимі `--local` (HTTP only, без SSL)
|
||
- Доступний тільки на `127.0.0.1:8081` (не публічний)
|
||
- Дозволяє використовувати Bot API без зовнішніх запитів до Telegram серверів
|
||
|
||
### 2. **nats** (Message Bus)
|
||
- NATS як шина подій між сервісами
|
||
- Простий режим без кластера
|
||
- Доступний на `127.0.0.1:4222`
|
||
|
||
### 3. **telegram-gateway** (Python FastAPI)
|
||
- Міст між Telegram Bot API і NATS
|
||
- Базовий FastAPI сервіс з `/healthz` endpoint
|
||
- Буде розширений через Cursor для:
|
||
- Читання апдейтів з Telegram
|
||
- Публікації подій у NATS
|
||
- Прийому HTTP команд від інших сервісів
|
||
|
||
## 📋 Передумови
|
||
|
||
- Docker + Docker Compose
|
||
- Telegram API credentials (API ID, API Hash) з https://my.telegram.org/apps
|
||
- Домен, що вказує на ваш сервер (опціонально для майбутнього HTTPS)
|
||
|
||
## 🚀 Швидкий старт
|
||
|
||
### 1. Налаштування змінних середовища
|
||
|
||
Створіть `.env` файл у кореневій директорії:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
Заповніть `.env` вашими значеннями:
|
||
|
||
```env
|
||
TELEGRAM_API_ID=YOUR_API_ID
|
||
TELEGRAM_API_HASH=YOUR_API_HASH
|
||
GATEWAY_DOMAIN=gateway.daarion.city
|
||
```
|
||
|
||
### 2. Запуск стеку
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
### 3. Перевірка статусу
|
||
|
||
Перевірте, що всі контейнери запущені:
|
||
|
||
```bash
|
||
docker compose ps
|
||
```
|
||
|
||
Очікуваний вивід:
|
||
```
|
||
NAME STATUS PORTS
|
||
telegram-bot-api running 127.0.0.1:8081->8081/tcp
|
||
nats running 127.0.0.1:4222->4222/tcp
|
||
telegram-gateway running 127.0.0.1:8000->8000/tcp
|
||
```
|
||
|
||
## 🧪 Тестування
|
||
|
||
### 1. Перевірка telegram-gateway
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8000/healthz
|
||
```
|
||
|
||
Очікувана відповідь:
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"service": "telegram-gateway",
|
||
"telegram_api": "http://telegram-bot-api:8081",
|
||
"nats": "nats://nats:4222"
|
||
}
|
||
```
|
||
|
||
### 2. Перевірка Local Telegram Bot API
|
||
|
||
Замініть `<YOUR_BOT_TOKEN>` на ваш реальний токен бота:
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8081/bot<YOUR_BOT_TOKEN>/getMe
|
||
```
|
||
|
||
Очікувана відповідь (JSON з інформацією про бота):
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"result": {
|
||
"id": 123456789,
|
||
"is_bot": true,
|
||
"first_name": "YourBot",
|
||
"username": "your_bot"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. Перевірка NATS
|
||
|
||
```bash
|
||
docker logs nats
|
||
```
|
||
|
||
Має показувати успішний запуск NATS сервера.
|
||
|
||
## 📁 Структура проєкту
|
||
|
||
```
|
||
telegram-infrastructure/
|
||
├── docker-compose.yml # Конфігурація Docker Compose
|
||
├── .env # Змінні середовища (не в git)
|
||
├── .env.example # Приклад змінних
|
||
├── README.md # Ця документація
|
||
├── data/ # Дані (автоматично створюється)
|
||
│ └── telegram-bot-api/ # Дані Local Telegram Bot API
|
||
└── telegram-gateway/ # Telegram Gateway сервіс
|
||
├── Dockerfile
|
||
├── requirements.txt
|
||
└── app/
|
||
├── __init__.py
|
||
└── main.py # FastAPI додаток
|
||
```
|
||
|
||
## 🔒 Безпека
|
||
|
||
- **telegram-bot-api** доступний тільки на localhost (`127.0.0.1:8081`)
|
||
- **nats** доступний тільки на localhost (`127.0.0.1:4222`)
|
||
- **telegram-gateway** доступний тільки на localhost (`127.0.0.1:8000`)
|
||
- Для публічного доступу додайте reverse proxy (Caddy/Traefik/nginx) з HTTPS
|
||
|
||
## 🔄 Управління
|
||
|
||
### Зупинка сервісів
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
### Перезапуск сервісу
|
||
|
||
```bash
|
||
docker compose restart telegram-gateway
|
||
```
|
||
|
||
### Перегляд логів
|
||
|
||
```bash
|
||
# Всі сервіси
|
||
docker compose logs -f
|
||
|
||
# Конкретний сервіс
|
||
docker compose logs -f telegram-gateway
|
||
```
|
||
|
||
### Rebuild після змін коду
|
||
|
||
```bash
|
||
docker compose up -d --build telegram-gateway
|
||
```
|
||
|
||
## 📝 Наступні кроки
|
||
|
||
Після того, як інфраструктура запрацює, використовуйте **Cursor** для розробки логіки `telegram-gateway`:
|
||
|
||
1. **Інтеграція aiogram** — для роботи з Telegram Bot API
|
||
2. **NATS publisher** — публікація подій у NATS
|
||
3. **Webhook endpoints** — прийом команд від інших сервісів
|
||
4. **Message routing** — маршрутизація повідомлень між агентами
|
||
|
||
## 🐛 Troubleshooting
|
||
|
||
### Контейнери не запускаються
|
||
|
||
```bash
|
||
docker compose logs telegram-bot-api
|
||
```
|
||
|
||
### Порти зайняті
|
||
|
||
Переконайтесь, що порти 8081, 4222, 8000 вільні:
|
||
|
||
```bash
|
||
lsof -i :8081
|
||
lsof -i :4222
|
||
lsof -i :8000
|
||
```
|
||
|
||
### Проблеми з правами доступу
|
||
|
||
```bash
|
||
chmod -R 755 data/
|
||
```
|
||
|
||
## 📚 Посилання
|
||
|
||
- [Local Telegram Bot API](https://github.com/tdlib/telegram-bot-api)
|
||
- [NATS](https://nats.io/)
|
||
- [FastAPI](https://fastapi.tiangolo.com/)
|
||
- [aiogram](https://docs.aiogram.dev/) (для майбутньої інтеграції)
|