7.2 KiB
Backend — эксплуатация
Стек
- Node.js LTS + TypeScript
- Express (HTTP-фреймворк)
- pg (PostgreSQL клиент)
- csv-parse (парсинг CSV для seed)
Быстрый старт
1. Поднять PostgreSQL
# из корня проекта
docker-compose up -d
Параметры подключения берутся из .env (см. .env.example в корне).
2. Установить зависимости
cd backend
npm install
3. Создать .env
Скопировать .env.example из корня проекта и при необходимости отредактировать:
cp ../.env.example ../.env
4. Миграции
npm run db:migrate
Миграционный раннер — собственный скрипт src/migrate.ts:
- хранит историю применённых файлов в таблице
_migrations; - идемпотентный — повторный запуск не применяет уже выполненные миграции;
- файлы миграций:
backend/migrations/*.sql, применяются в алфавитном порядке.
5. Seed (начальный набор данных)
npm run seed
- Читает
import/races_2026_calendar.csvиз корня репо. - Генерирует стабильный
idв формате{date}-{slug}. - Выполняет upsert (
INSERT … ON CONFLICT DO UPDATE) — безопасно для повторного запуска.
6. Запуск API
npm run dev # dev-режим через ts-node
npm run build # компиляция в dist/
npm start # запуск из dist/
API слушает порт: PORT (если задан), иначе API_PORT, иначе 3001.
Переменные окружения
| Переменная | Описание | По умолчанию |
|---|---|---|
DB_HOST |
Хост PostgreSQL | — |
DB_PORT |
Порт PostgreSQL | — |
DB_NAME |
Имя базы данных | — |
DB_USER |
Пользователь БД | — |
DB_PASSWORD |
Пароль БД | — |
PORT |
Порт API (приоритетнее API_PORT) |
— |
API_PORT |
Порт API-сервера | 3001 |
CORS_ORIGIN |
Разрешённый origin для CORS | http://localhost:5173 |
APP_BASE_URL |
Базовый URL frontend для ссылок подтверждения email и сброса пароля | production: https://run.vakanaut.ru, иначе http://localhost:5173 |
SMTP_HOST |
SMTP-сервер; обязателен в production | — |
SMTP_PORT |
Порт SMTP | 587 |
SMTP_SECURE |
Использовать TLS-соединение с момента подключения | false |
SMTP_USER, SMTP_PASSWORD |
Учётные данные SMTP (если требуются сервером) | — |
SMTP_FROM |
Имя и адрес отправителя | Calendar Run <no-reply@example.com> |
Фронтенд всегда обращается к API по префиксу /api на текущем origin. В локальной разработке этот префикс проксирует Vite (frontend/vite.config.ts) на http://localhost:3001; в Docker-стеке — nginx фронта проксирует на runners-calendar-backend:3000.
APP_BASE_URL задаёт origin страниц, на которые ведут ссылки в письмах. Для
production без этой переменной используется https://run.vakanaut.ru; задайте
своё значение, если frontend размещён на другом домене. В локальной разработке
используется http://localhost:5173.
При отсутствии любой из DB_* процесс падает при старте: Missing required environment variable: <NAME>.
В production backend также не запускается без SMTP_HOST.
Для тестов нужен отдельный PostgreSQL database calendar_run_test; npm test применяет миграции и очищает его перед запуском.
Поведение при недоступной БД
- Старт сервера — проходит успешно (env валидирован, Express слушает порт).
GET /api/health— всегда200 { "status": "ok" }(liveness, без обращения к БД).GET /api/ready— пробует подключиться к БД;200если ОК,503 { "error": "database_unavailable", ... }если нет.- Все остальные маршруты при ошибке БД возвращают
503 { "error": "database_unavailable" }.
Структура каталога
backend/
├── migrations/
│ ├── 001_create_races.sql
│ ├── 002_finish_place_and_registered_status.sql
│ ├── 003_cover_image_url.sql
│ ├── 004_auth_and_race_ownership.sql
│ ├── 005_public_profiles.sql
│ ├── 006_profile_usernames_and_visibility.sql
│ ├── 007_cover_image_source.sql
│ └── 008_user_last_login.sql
├── src/
│ ├── app.ts # фабрика Express (тесты)
│ ├── config.ts # загрузка и валидация env
│ ├── db.ts # pg Pool
│ ├── index.ts # запуск сервера
│ ├── migrate.ts # раннер миграций
│ ├── seed.ts # разовый импорт CSV
│ ├── mappers/
│ │ └── race.ts # snake_case ↔ camelCase
│ └── routes/
│ ├── admin.ts # /api/admin/users
│ ├── auth.ts # регистрация, вход, сессии и восстановление
│ ├── health.ts # /api/health, /api/ready, /api/meta
│ ├── races.ts # CRUD /api/races
│ └── users.ts # публичные профили
├── package.json
└── tsconfig.json
Docker: стек backend + frontend
Файл docker-compose.stack.yml поднимает API и nginx со статикой SPA в отдельной сети приложения. К внешней сети postgres_default подключается бэкенд для доступа к уже запущенному PostgreSQL. Nginx обновляет IP бэкенда через встроенный DNS Docker. Для upstream ... resolve нужен nginx OSS 1.27.3 или новее. Переменные задаются в корневом .env (шаблон .env.example), включая DB_* и CORS_ORIGIN (для фронта на порту 3033 задайте http://localhost:3033).
Порядок после старта контейнеров: node dist/migrate.js и node dist/seed.js внутри сервиса runners-calendar-backend (см. комментарии в compose-файле).