142 lines
6.7 KiB
Markdown
142 lines
6.7 KiB
Markdown
# TNProxy - Telegram Notification Proxy
|
||
|
||
Прокси-сервер для отправки сообщений в Telegram через внешний сервер с авторизацией приложений.
|
||
|
||
## Возможности
|
||
|
||
- Множество приложений с индивидуальными токенами
|
||
- Каждое приложение привязывается к своему боту Telegram
|
||
- Веб-интерфейс для управления приложениями (админ-панель)
|
||
- Логирование с ротацией
|
||
- Экспорт/импорт настроек
|
||
- Docker для простого развертывания
|
||
|
||
## Быстрый старт (Docker)
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# Отредактируйте .env
|
||
docker-compose up -d
|
||
```
|
||
|
||
После запуска админ-панель доступна на `http://localhost:8880/adtn` (при `ADMIN_PANEL_ENABLED=true`).
|
||
|
||
## Управление админ-панелью
|
||
|
||
По умолчанию админ-панель **отключена** (`ADMIN_PANEL_ENABLED=false`).
|
||
Включение/отключение управляется флагом `ADMIN_PANEL_ENABLED` в `.env`.
|
||
|
||
**Включить для настройки:**
|
||
```bash
|
||
# В .env установить ADMIN_PANEL_ENABLED=true
|
||
docker-compose up -d
|
||
```
|
||
Откройте `http://localhost:8880/adtn` — настройте приложения.
|
||
|
||
**Выключить после настройки:**
|
||
```bash
|
||
# В .env вернуть ADMIN_PANEL_ENABLED=false
|
||
docker-compose up -d
|
||
```
|
||
|
||
> **Важно:** используйте именно `docker-compose up -d`, а НЕ `docker-compose restart`.
|
||
> `restart` не пересоздаёт контейнер и не перечитывает `.env` — в контейнере останется
|
||
> прежнее значение флага, и админ-панель продолжит работать даже после изменения файла.
|
||
> `docker-compose up -d` пересоздаёт контейнер с новыми переменными окружения.
|
||
|
||
Когда админ-панель отключена, `/adtn`, `/logtn` и прочие админ-маршруты не регистрируются
|
||
и возвращают 404. API `/send` и `/health` продолжают работать.
|
||
|
||
## Вход в админ-панель
|
||
|
||
Логин-страница: `/logtn`. Учётные данные по умолчанию создаются автоматически при первом
|
||
запуске (см. `AdminUser.create_default` в `models.py`). После входа откроется дашборд `/adtn`.
|
||
|
||
Защита:
|
||
- Ограничение доступа по IP через `ALLOWED_ADMIN_IPS` (список через запятую; пусто = все).
|
||
- Отдельная сессионная подпись `ADMIN_SESSION_SECRET` (рекомендуется задать своё значение).
|
||
- Уведомления об успешном/неудачном входе на email (если настроен SMTP).
|
||
|
||
## Использование
|
||
|
||
### 1. Создайте приложение в веб-интерфейсе
|
||
|
||
Перейдите на `/adtn`, нажмите "Добавить приложение", введите:
|
||
- Название
|
||
- Telegram Bot Token (получить у @BotFather)
|
||
- Telegram Chat ID (ваш ID или ID канала)
|
||
|
||
Получите токен приложения.
|
||
|
||
### 2. Отправка сообщения
|
||
|
||
```http
|
||
POST /send
|
||
X-App-Token: <токен_приложения>
|
||
Content-Type: application/json
|
||
|
||
{"text": "Hello, World!"}
|
||
```
|
||
|
||
### Пример PowerShell:
|
||
|
||
```powershell
|
||
$body = @{text = "Alert!"} | ConvertTo-Json
|
||
Invoke-RestMethod -Uri "http://localhost:8880/send" -Method Post -Body $body -Headers @{
|
||
"Content-Type" = "application/json"
|
||
"X-App-Token" = "YOUR_APP_TOKEN"
|
||
}
|
||
```
|
||
|
||
> Порт в примере — `8880` (маппинг Docker `8880:8080`). Без Docker сервер по умолчанию
|
||
> слушает порт `8080` (переменная `SERVER_PORT`).
|
||
|
||
## API Endpoints
|
||
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| POST | /send | Отправить сообщение |
|
||
| GET | /health | Проверка здоровья |
|
||
| GET | /adtn | Дашборд админ-панели (только админ) |
|
||
| GET | /logtn | Страница входа |
|
||
| POST | /logtn | Вход |
|
||
| POST | /logout | Выход |
|
||
| POST | /adtn/applications | Создать приложение |
|
||
| DELETE | /adtn/applications/{id} | Удалить приложение |
|
||
| POST | /adtn/applications/{id}/toggle | Включить/отключить |
|
||
| GET | /adtn/logs | Логи (управление ротацией) |
|
||
| POST | /adtn/logs | Обновить настройки логов |
|
||
| GET | /adtn/password | Смена пароля |
|
||
| GET | /adtn/export | Экспорт настроек (JSON) |
|
||
| POST | /adtn/import | Импорт настроек (JSON) |
|
||
| GET | /adtn/api | Справка по API |
|
||
|
||
## Переменные окружения (`.env`)
|
||
|
||
| Переменная | По умолчанию | Описание |
|
||
|-----------|-------------|----------|
|
||
| `SECRET_KEY` | `change-me-in-production` | Секретный ключ приложения |
|
||
| `ADMIN_SESSION_SECRET` | = `SECRET_KEY` | Подпись сессий админ-панели |
|
||
| `ADMIN_PANEL_ENABLED` | `false` | Включить админ-панель |
|
||
| `ALLOWED_ADMIN_IPS` | пусто (все) | IP-адреса, разделённые запятыми |
|
||
| `DATABASE_URL` | `sqlite:///data/tnproxy.db` | URL базы данных |
|
||
| `LOG_DIR` | `/app/logs` | Каталог логов |
|
||
| `LOG_LEVEL` | `INFO` | Уровень логирования |
|
||
| `LOG_ROTATE_MAX_BYTES` / `LOG_ROTATE_BACKUP_COUNT` | `10485760` / `5` | Ротация логов |
|
||
| `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_FROM`, `SMTP_TO` | — | Email-уведомления |
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
.
|
||
├── config.py # Конфигурация (чтение .env / переменных окружения)
|
||
├── server.py # FastAPI сервер
|
||
├── models.py # Модели SQLAlchemy
|
||
├── database.py # База данных
|
||
├── requirements.txt # Python зависимости
|
||
├── Dockerfile # Docker образ
|
||
├── docker-compose.yml # Docker Compose
|
||
├── templates/ # HTML шаблоны
|
||
├── clients/ # Примеры клиентов
|
||
└── data/ # SQLite БД (создается при запуске)
|
||
``` |