Telegram Insights Bot - Полное руководство по развертыванию

📋 Структура проекта

insights-bot/
├── main.py                 # Основной файл с логикой бота
├── database.py             # Функции для работы с БД
├── export_excel.py         # Функции для экспорта в Excel
├── requirements.txt        # Зависимости Python
├── .env.example           # Пример конфигурации
├── Procfile               # Конфигурация для Render
├── runtime.txt            # Версия Python
└── README.md              # Этот файл

🚀 Быстрый старт

1. Подготовка Supabase базы данных

1. Зарегистрируйтесь на supabase.com
2. Создайте новый проект
3. Откройте SQL Editor и выполните следующий запрос:

CREATE TABLE insights (
    id SERIAL PRIMARY KEY,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    theme VARCHAR(255) NOT NULL,
    description TEXT NOT NULL,
    macro_region VARCHAR(50) NOT NULL,
    industry VARCHAR(100) NOT NULL,
    file_id VARCHAR(255),
    filename VARCHAR(255),
    user_id BIGINT NOT NULL
);

CREATE INDEX idx_macro_region ON insights(macro_region);
CREATE INDEX idx_industry ON insights(industry);
CREATE INDEX idx_user_id ON insights(user_id);

4. Скопируйте Project URL и API Key (выберите анон ключ) из Settings → API

2. Создание Telegram бота

1. Откройте чат с @BotFather в Telegram
2. Отправьте команду /newbot
3. Следуйте инструкциям и получите BOT_TOKEN

3. Локальное развертывание (для тестирования)

# Клонируйте репозиторий или создайте папку
mkdir insights-bot
cd insights-bot

# Создайте виртуальное окружение
python -m venv venv

# Активируйте окружение
# На Windows:
venv\Scripts\activate
# На macOS/Linux:
source venv/bin/activate

# Установите зависимости
pip install -r requirements.txt

# Создайте .env файл
cp .env.example .env

# Отредактируйте .env с вашими данными
nano .env

4. Развертывание на Render (рекомендуется)

4.1 Подготовка GitHub репозитория

# Инициализируйте Git репозиторий
git init
git add .
git commit -m "Initial commit: Telegram insights bot"

# Создайте репозиторий на GitHub и залейте код
git remote add origin https://github.com/YOUR_USERNAME/insights-bot.git
git branch -M main
git push -u origin main

4.2 Развертывание на Render

1. Зайдите на render.com

2. Нажмите New + → Web Service

3. Подключите GitHub репозиторий

4. Настройки:

   • Name: insights-bot
   • Runtime: Python 3.11
   • Build Command: pip install -r requirements.txt
   • Start Command: gunicorn --bind 0.0.0.0:$PORT main:app --worker-class aiohttp.GunicornWebWorker

5. Добавьте переменные окружения в Environment:

   • BOT_TOKEN - ваш токен от BotFather
   • SUPABASE_URL - URL вашего Supabase проекта
   • SUPABASE_KEY - API ключ Supabase (анон)
   • WEBHOOK_URL - будет автоматически вида https://insights-bot-xxxx.onrender.com

6. Нажмите Create Web Service

После развертывания скопируйте URL (например, https://insights-bot-xxxx.onrender.com) и добавьте его в переменную WEBHOOK_URL.

5. Альтернатива: Railway.app

1. Зайдите на railway.app

2. Нажмите New Project → Deploy from GitHub

3. Выберите ваш репозиторий

4. Добавьте переменные окружения в Variables:

   • BOT_TOKEN
   • SUPABASE_URL
   • SUPABASE_KEY
   • WEBHOOK_URL

5. Railway автоматически запустит приложение

📱 Функциональность бота

Главное меню

• ➕ Создать новый инсайт - создание новой записи
• 🔍 Поиск и просмотр - поиск по фильтрам
• 📊 Экспорт в Excel - скачать все данные

Создание инсайта

Процесс пошагово:

1. Введите тему инсайта
2. Введите описание
3. Выберите макрорегион из списка (количество записей показывается на кнопке)
4. Выберите отрасль (количество записей показывается на кнопке)
5. Опционально: прикрепите файл или фото

Поиск и просмотр

1. Выберите макрорегион
2. Выберите отрасль
3. Просмотрите найденные инсайты:
   • Кнопки навигации ⬅️ и ➡️
   • Кнопка 📎 Скачать файл (если файл прикреплен)

Экспорт в Excel

Нажимаете 📊 Экспорт в Excel и получаете файл со всеми записями, где указано:

• Дата создания
• Тема
• Описание
• Макрорегион
• Отрасль
• Наличие прикрепленного файла

🔧 Настройка и расширение

Добавление новых макрорегионов

Отредактируйте в main.py:

MACRO_REGIONS = ["МСК", "ЦФО", "СЗФО", "УФО", "ЮФО", "ПФО", "СДФО", "СНГ", "НОВЫЙ"]

Добавление новых отраслей

Отредактируйте в main.py:

INDUSTRIES = ["Оборона", "Промышленность", "Торговля", "Банки", "Нефть и газ", "Энергетика", "НОВАЯ"]

Кэширование подсчета

Для оптимизации при большом объеме данных добавьте в database.py:

from functools import lru_cache
from datetime import datetime, timedelta

cache_timeout = {}

@lru_cache(maxsize=128)
async def get_cached_count(field: str, value: str):
    cache_key = f"{field}_{value}"
    if cache_key in cache_timeout:
        if datetime.now() - cache_timeout[cache_key] < timedelta(minutes=5):
            return await get_count_by_field(field, value)
    
    count = await get_count_by_field(field, value)
    cache_timeout[cache_key] = datetime.now()
    return count

🔒 Безопасность

Переменные окружения

Никогда не коммитьте .env файл! Используйте .env.example как шаблон.

Добавьте в .gitignore:

.env
.env.local
__pycache__
venv/
*.pyc
*.xlsx

Row Level Security в Supabase

Для ограничения доступа пользователей:

ALTER TABLE insights ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can view all insights"
ON insights FOR SELECT
USING (true);

CREATE POLICY "Users can create own insights"
ON insights FOR INSERT
WITH CHECK (true);

📊 Мониторинг

Логирование

Логи автоматически выводятся в консоль. На Render посмотрите их в Logs табе.

Для сохранения логов локально добавьте в main.py:

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('bot.log'),
        logging.StreamHandler()
    ]
)

Основные события:

• Создание инсайта
• Поиск по фильтрам
• Экспорт данных
• Ошибки при работе с БД

🐛 Решение проблем

Бот не отвечает

1. Проверьте, что BOT_TOKEN правильный
2. Убедитесь, что webhook установлен: https://api.telegram.org/botTOKEN/getWebhookInfo
3. Проверьте логи на Render/Railway
4. Убедитесь, что приложение запустилось (статус должен быть "Running")

Ошибка подключения к Supabase

1. Проверьте SUPABASE_URL и SUPABASE_KEY
2. Убедитесь, что таблица insights создана
3. Проверьте, что ключ типа "anon" (анонимный)

Excel файл не скачивается

1. Убедитесь, что в БД есть данные
2. Проверьте прав доступа к /tmp директории
3. Увеличьте timeout на Render/Railway

📈 Масштабирование

Оптимизация при росте данных

1. Индексы - уже добавлены на macro_region, industry, user_id
2. Пагинация - добавьте LIMIT в SQL запросы
3. Кэширование - используйте Redis для кэша

Перейти на платные тарифы

• Supabase: при росте объема данных выше 500 МБ
• Render: при необходимости большего количества часов в месяц

📚 Полезные ссылки

• Aiogram документация
• Supabase документация
• Telegram Bot API
• Render документация
• Railway документация

📝 Лицензия

Этот проект предоставляется в образовательных целях.

🤝 Поддержка

Если возникли вопросы, обратитесь к документации проекта или создайте Issue в репозитории.

---

Версия: 1.0.0
Последнее обновление: Ноябрь 2025