Initial commit
This commit is contained in:
345
README.md
Normal file
345
README.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# Polotsk Transit API
|
||||
|
||||
Система управления информацией об общественном транспорте города Полоцка с REST API, веб-панелью администратора и поддержкой offline-синхронизации.
|
||||
|
||||
## 🚀 Возможности
|
||||
|
||||
### MVP (Версия 1.0 - статические данные)
|
||||
- ✅ REST API для маршрутов и остановок
|
||||
- ✅ Геопространственные запросы (PostGIS)
|
||||
- ✅ Расчет ETA на основе расписания
|
||||
- ✅ Offline-синхронизация для мобильных приложений
|
||||
- ✅ Веб-панель администратора
|
||||
- ✅ Кеширование через Redis
|
||||
- ✅ Аутентификация по API ключам
|
||||
- ✅ Rate limiting
|
||||
|
||||
### Технологический стек
|
||||
|
||||
**Backend:**
|
||||
- Node.js + Express
|
||||
- PostgreSQL + PostGIS
|
||||
- Redis
|
||||
- Docker
|
||||
|
||||
**Frontend (Admin Panel):**
|
||||
- React + Vite
|
||||
- Tailwind CSS
|
||||
- React Leaflet (карты)
|
||||
- Axios
|
||||
|
||||
## 📋 Требования
|
||||
|
||||
- Docker и Docker Compose
|
||||
- Node.js 18+ (для разработки без Docker)
|
||||
- Статический IP или динамический DNS
|
||||
- ~2GB свободного места на диске
|
||||
|
||||
## 🛠 Установка и запуск
|
||||
|
||||
### 1. Клонирование и настройка
|
||||
|
||||
```bash
|
||||
# Создайте .env файл из примера
|
||||
cp .env.example .env
|
||||
|
||||
# Настройте переменные окружения
|
||||
nano .env
|
||||
```
|
||||
|
||||
Важные переменные в `.env`:
|
||||
```env
|
||||
# Обязательно измените в продакшене!
|
||||
DB_PASSWORD=your_secure_password_here
|
||||
API_KEY_SALT=generate_random_salt_with_openssl
|
||||
|
||||
# Для разработки оставьте как есть
|
||||
CORS_ORIGIN=http://localhost:3001
|
||||
API_URL=http://localhost:3000/api/v1
|
||||
```
|
||||
|
||||
Генерация безопасного salt:
|
||||
```bash
|
||||
openssl rand -base64 32
|
||||
```
|
||||
|
||||
### 2. Запуск с Docker (рекомендуется)
|
||||
|
||||
```bash
|
||||
# Сборка и запуск всех сервисов
|
||||
docker-compose up -d
|
||||
|
||||
# Проверка статуса
|
||||
docker-compose ps
|
||||
|
||||
# Просмотр логов
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
Сервисы будут доступны:
|
||||
- **API**: http://localhost:3000
|
||||
- **Admin Panel**: http://localhost:3001
|
||||
- **PostgreSQL**: localhost:5432
|
||||
- **Redis**: localhost:6379
|
||||
|
||||
### 3. Проверка работоспособности
|
||||
|
||||
```bash
|
||||
# Проверка API
|
||||
curl http://localhost:3000/health
|
||||
|
||||
# Проверка базы данных
|
||||
docker exec -it polotsk-transit-db psql -U transit_admin -d polotsk_transit -c "SELECT COUNT(*) FROM routes;"
|
||||
```
|
||||
|
||||
### 4. Разработка без Docker
|
||||
|
||||
**Backend:**
|
||||
```bash
|
||||
cd backend
|
||||
npm install
|
||||
cp .env.example .env
|
||||
|
||||
# Убедитесь, что PostgreSQL и Redis запущены локально
|
||||
# Настройте DATABASE_URL и REDIS_URL в .env
|
||||
|
||||
npm run dev
|
||||
```
|
||||
|
||||
**Frontend:**
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
cp .env.example .env
|
||||
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## 📱 Использование API
|
||||
|
||||
### Аутентификация
|
||||
|
||||
Все запросы требуют API ключ в заголовке:
|
||||
```bash
|
||||
curl -H "X-API-Key: dev_key_12345678" http://localhost:3000/api/v1/routes
|
||||
```
|
||||
|
||||
### Основные эндпоинты
|
||||
|
||||
**Маршруты:**
|
||||
```bash
|
||||
GET /api/v1/routes # Все маршруты
|
||||
GET /api/v1/routes/:id # Маршрут с остановками
|
||||
POST /api/v1/routes # Создать маршрут
|
||||
PUT /api/v1/routes/:id # Обновить маршрут
|
||||
DELETE /api/v1/routes/:id # Удалить маршрут
|
||||
```
|
||||
|
||||
**Остановки:**
|
||||
```bash
|
||||
GET /api/v1/stops # Все остановки
|
||||
GET /api/v1/stops/:id # Конкретная остановка
|
||||
GET /api/v1/stops/nearby?lat=55.4869&lon=28.7856&radius=500 # Ближайшие
|
||||
POST /api/v1/stops # Создать остановку
|
||||
PUT /api/v1/stops/:id # Обновить остановку
|
||||
DELETE /api/v1/stops/:id # Удалить остановку
|
||||
```
|
||||
|
||||
**ETA (расчет времени прибытия):**
|
||||
```bash
|
||||
POST /api/v1/eta/calculate
|
||||
{
|
||||
"stopId": 1,
|
||||
"routeId": 1
|
||||
}
|
||||
|
||||
GET /api/v1/eta/stop/:stopId # ETA для всех маршрутов на остановке
|
||||
```
|
||||
|
||||
**Синхронизация (для offline-режима):**
|
||||
```bash
|
||||
GET /api/v1/sync # Полная синхронизация
|
||||
GET /api/v1/sync?lastSync=2025-11-19T10:00:00Z # Инкрементальная
|
||||
GET /api/v1/sync/status # Статус системы
|
||||
```
|
||||
|
||||
### Примеры запросов
|
||||
|
||||
**Создание маршрута:**
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/v1/routes \
|
||||
-H "X-API-Key: dev_key_12345678" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"route_number": "1",
|
||||
"name": "Центр - Вокзал",
|
||||
"type": "bus",
|
||||
"color": "#0066CC",
|
||||
"description": "Основной маршрут через центр города"
|
||||
}'
|
||||
```
|
||||
|
||||
**Создание остановки:**
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/v1/stops \
|
||||
-H "X-API-Key: dev_key_12345678" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "Площадь Свободы",
|
||||
"latitude": 55.4869,
|
||||
"longitude": 28.7856,
|
||||
"address": "ул. Ленина, 1"
|
||||
}'
|
||||
```
|
||||
|
||||
**Поиск ближайших остановок:**
|
||||
```bash
|
||||
curl -H "X-API-Key: dev_key_12345678" \
|
||||
"http://localhost:3000/api/v1/stops/nearby?lat=55.4869&lon=28.7856&radius=500"
|
||||
```
|
||||
|
||||
## 🔐 Безопасность домашнего сервера
|
||||
|
||||
### Обязательные меры безопасности
|
||||
|
||||
1. **Cloudflare Tunnel** (рекомендуется):
|
||||
```bash
|
||||
# Установка cloudflared
|
||||
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
|
||||
sudo mv cloudflared /usr/local/bin/
|
||||
sudo chmod +x /usr/local/bin/cloudflared
|
||||
|
||||
# Аутентификация
|
||||
cloudflared tunnel login
|
||||
|
||||
# Создание туннеля
|
||||
cloudflared tunnel create polotsk-transit
|
||||
|
||||
# Запуск
|
||||
cloudflared tunnel run polotsk-transit
|
||||
```
|
||||
|
||||
2. **Настройка SSL в Nginx:**
|
||||
```bash
|
||||
# Получение сертификата Let's Encrypt
|
||||
sudo certbot --nginx -d api.yourdomain.com -d admin.yourdomain.com
|
||||
|
||||
# Сертификаты автоматически обновятся
|
||||
```
|
||||
|
||||
3. **Fail2ban:**
|
||||
```bash
|
||||
sudo apt install fail2ban
|
||||
sudo systemctl enable fail2ban
|
||||
sudo systemctl start fail2ban
|
||||
```
|
||||
|
||||
4. **Мониторинг:**
|
||||
```bash
|
||||
# Установка Prometheus + Grafana (опционально)
|
||||
# Или простой мониторинг через Docker stats
|
||||
docker stats
|
||||
```
|
||||
|
||||
### Создание API ключей
|
||||
|
||||
API ключи можно создать через базу данных:
|
||||
|
||||
```sql
|
||||
INSERT INTO api_keys (key, app_name, rate_limit)
|
||||
VALUES ('your_secure_key_here', 'iOS App', 10000);
|
||||
```
|
||||
|
||||
Или через скрипт:
|
||||
```javascript
|
||||
const crypto = require('crypto');
|
||||
const apiKey = crypto.randomBytes(32).toString('hex');
|
||||
console.log(apiKey);
|
||||
```
|
||||
|
||||
## 📊 Админ-панель
|
||||
|
||||
Откройте http://localhost:3001 в браузере.
|
||||
|
||||
**Функции:**
|
||||
- Управление маршрутами
|
||||
- Создание и редактирование остановок на карте
|
||||
- Просмотр статистики
|
||||
- Управление расписаниями (в разработке)
|
||||
|
||||
## 🗄 Структура базы данных
|
||||
|
||||
```sql
|
||||
routes # Маршруты
|
||||
stops # Остановки (с PostGIS геометрией)
|
||||
route_stops # Связь маршрутов и остановок
|
||||
schedules # Расписания
|
||||
vehicles # Транспортные средства
|
||||
historical_delays # Статистика задержек
|
||||
alerts # Уведомления
|
||||
api_keys # API ключи
|
||||
sync_log # Лог изменений для синхронизации
|
||||
```
|
||||
|
||||
## 🔄 Обновления
|
||||
|
||||
```bash
|
||||
# Остановка сервисов
|
||||
docker-compose down
|
||||
|
||||
# Обновление кода
|
||||
git pull
|
||||
|
||||
# Перезапуск
|
||||
docker-compose up -d --build
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
**База данных не стартует:**
|
||||
```bash
|
||||
docker-compose logs postgres
|
||||
docker-compose down -v # Удалит volumes, ОСТОРОЖНО!
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
**API не отвечает:**
|
||||
```bash
|
||||
docker-compose logs backend
|
||||
docker-compose restart backend
|
||||
```
|
||||
|
||||
**Frontend не собирается:**
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
**PostGIS ошибки:**
|
||||
```bash
|
||||
docker exec -it polotsk-transit-db psql -U transit_admin -d polotsk_transit
|
||||
SELECT PostGIS_Version();
|
||||
```
|
||||
|
||||
## 📝 Следующие шаги (Roadmap)
|
||||
|
||||
### Версия 2.0 - Краудсорсинг GPS
|
||||
- [ ] Endpoint для получения GPS от пользователей
|
||||
- [ ] Агрегация и фильтрация GPS данных
|
||||
- [ ] WebSocket для реалтайм-обновлений
|
||||
- [ ] Функция "Я еду в маршруте" в приложениях
|
||||
|
||||
### Версия 3.0 - Продвинутые функции
|
||||
- [ ] IoT GPS-трекеры интеграция
|
||||
- [ ] Машинное обучение для предсказания задержек
|
||||
- [ ] Push-уведомления
|
||||
- [ ] Аналитика и отчеты
|
||||
|
||||
## 🤝 Контакты и поддержка
|
||||
|
||||
Создано для города Полоцка 🇧🇾
|
||||
|
||||
## 📄 Лицензия
|
||||
|
||||
MIT License - используйте свободно!
|
||||
Reference in New Issue
Block a user