132 lines
5 KiB
Markdown
132 lines
5 KiB
Markdown
|
# Baton — Экстренный сигнал
|
|||
|
|
|
|||
|
|
PWA-приложение для отправки экстренных сигналов с геолокацией через Telegram-бота.
|
|||
|
|
|
|||
|
|
## Стек
|
|||
|
|
|
|||
|
|
- **Backend:** Python 3.12+, FastAPI, aiosqlite, httpx
|
|||
|
|
- **Frontend:** Vanilla JS PWA (Service Worker, Web Push)
|
|||
|
|
- **База данных:** SQLite (WAL mode)
|
|||
|
|
- **Уведомления:** Telegram Bot API
|
|||
|
|
|
|||
|
|
## Запуск
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Зависимости
|
|||
|
|
pip install -r requirements.txt
|
|||
|
|
|
|||
|
|
# Переменные окружения (см. .env.example)
|
|||
|
|
cp .env.example .env
|
|||
|
|
|
|||
|
|
# Запуск
|
|||
|
|
uvicorn backend.main:app --host 0.0.0.0 --port 8000
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Переменные окружения
|
|||
|
|
|
|||
|
|
| Переменная | Обязательна | Описание |
|
|||
|
|
|---|---|---|
|
|||
|
|
| `BOT_TOKEN` | да | Токен Telegram-бота |
|
|||
|
|
| `CHAT_ID` | да | ID чата для уведомлений |
|
|||
|
|
| `WEBHOOK_SECRET` | да | Секрет для верификации Telegram webhook |
|
|||
|
|
| `WEBHOOK_URL` | да | Публичный URL `/api/webhook/telegram` |
|
|||
|
|
| `DB_PATH` | нет | Путь к SQLite-файлу (по умолчанию `baton.db`) |
|
|||
|
|
| `FRONTEND_ORIGIN` | нет | Разрешённый origin для CORS (по умолчанию `http://localhost:3000`) |
|
|||
|
|
| `WEBHOOK_ENABLED` | нет | Регистрировать webhook при старте (по умолчанию `true`) |
|
|||
|
|
| `APP_URL` | нет | Публичный URL приложения для keep-alive (например `https://baton.fly.dev`) |
|
|||
|
|
|
|||
|
|
## API
|
|||
|
|
|
|||
|
|
| Метод | Путь | Описание |
|
|||
|
|
|---|---|---|
|
|||
|
|
| `GET` | `/health` | Health check: `{"status": "ok", "timestamp": <unix_ts>}` |
|
|||
|
|
| `POST` | `/api/register` | Регистрация пользователя |
|
|||
|
|
| `POST` | `/api/signal` | Отправка экстренного сигнала |
|
|||
|
|
| `POST` | `/api/webhook/telegram` | Telegram webhook |
|
|||
|
|
|
|||
|
|
## Hosting & Keep-Alive
|
|||
|
|
|
|||
|
|
### Проблема cold start
|
|||
|
|
|
|||
|
|
На бесплатных хостингах (Render, fly.io free tier, Railway и подобных) приложение **засыпает** после периода неактивности (обычно 15–30 минут). Следующий входящий запрос ждёт пока процесс поднимется заново — **cold start занимает 3–5 секунд**. Для экстренного приложения это критично.
|
|||
|
|
|
|||
|
|
### Решения по вариантам хостинга
|
|||
|
|
|
|||
|
|
| Вариант | Стоимость | Cold start | Рекомендация |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| **fly.io Hobby** | $5/мес | Нет (всегда активен) | Оптимально для прода |
|
|||
|
|
| **fly.io free tier** | Бесплатно | 3–5 сек | Только для разработки |
|
|||
|
|
| **Render free** | Бесплатно | 3–5 сек | Только для разработки |
|
|||
|
|
| **Самохостинг (VPS)** | От $3–5/мес | Нет | Полный контроль |
|
|||
|
|
|
|||
|
|
> **Финальный выбор хостинга зависит от решения по OQ-004** (открытый вопрос по бюджету и масштабированию проекта).
|
|||
|
|
|
|||
|
|
### Keep-alive механизм (asyncio background task)
|
|||
|
|
|
|||
|
|
Приложение запускает фоновый asyncio-таск, который каждые **10 минут** пингует собственный `/health` endpoint. Это предотвращает засыпание на платформах, которые реагируют на активность процесса.
|
|||
|
|
|
|||
|
|
**Активация:** установите переменную `APP_URL`:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
APP_URL=https://your-app.fly.dev
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Без `APP_URL` таск не запускается (keep-alive отключён).
|
|||
|
|
|
|||
|
|
**Ограничение:** self-ping работает пока процесс жив. Если платформа убивает процесс при нулевом трафике — нужен внешний пингер (см. ниже).
|
|||
|
|
|
|||
|
|
### Keep-alive для самохостинга (cron / systemd timer)
|
|||
|
|
|
|||
|
|
Если приложение на VPS и нужен мониторинг извне:
|
|||
|
|
|
|||
|
|
**Вариант 1 — crontab:**
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Редактируем cron
|
|||
|
|
crontab -e
|
|||
|
|
|
|||
|
|
# Добавляем запись (каждые 10 минут):
|
|||
|
|
*/10 * * * * curl -sf https://your-app.example.com/health > /dev/null
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Вариант 2 — systemd timer:**
|
|||
|
|
|
|||
|
|
Создайте два файла:
|
|||
|
|
|
|||
|
|
`/etc/systemd/system/baton-keepalive.service`:
|
|||
|
|
```ini
|
|||
|
|
[Unit]
|
|||
|
|
Description=Baton keep-alive ping
|
|||
|
|
|
|||
|
|
[Service]
|
|||
|
|
Type=oneshot
|
|||
|
|
ExecStart=curl -sf https://your-app.example.com/health
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`/etc/systemd/system/baton-keepalive.timer`:
|
|||
|
|
```ini
|
|||
|
|
[Unit]
|
|||
|
|
Description=Run Baton keep-alive every 10 minutes
|
|||
|
|
|
|||
|
|
[Timer]
|
|||
|
|
OnBootSec=1min
|
|||
|
|
OnUnitActiveSec=10min
|
|||
|
|
|
|||
|
|
[Install]
|
|||
|
|
WantedBy=timers.target
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Активация:
|
|||
|
|
```bash
|
|||
|
|
systemctl daemon-reload
|
|||
|
|
systemctl enable --now baton-keepalive.timer
|
|||
|
|
systemctl list-timers baton-keepalive.timer
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Тесты
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
pip install -r requirements-dev.txt
|
|||
|
|
pytest
|
|||
|
|
```
|