Nimbus Docs

Appearance

Руководство по запуску микросервисов ​

Это руководство поможет вам запустить все микросервисы локально для разработки и тестирования.

Источник: ранее файл services/STARTUP_GUIDE.md (перенесён и стандартизирован).

Предварительные требования ​

  • Docker и Docker Compose
  • Go 1.23+ (для локальной разработки без Docker)
  • PostgreSQL 15+ (если запускаете БД локально)
  • Redis 7+ (если запускаете Redis локально)

Быстрый старт с Docker Compose ​

1. Запуск всех сервисов ​

bash
# Из корневой директории проекта
docker-compose -f docker-compose.microservices.yml up -d

Это запустит:

  • PostgreSQL для каждого сервиса:
    • postgres-auth на порту 5433 (БД: nimbus_auth)
    • postgres-core на порту 5434 (БД: nimbus_core)
    • postgres-billing на порту 5435 (БД: nimbus_billing)
  • Redis для каждого сервиса:
    • redis-auth на порту 6379 (для auth-service)
    • redis-core на порту 6380 (для core-service)
    • redis-billing на порту 6381 (для billing-service)
  • auth-service на порту 8001
  • core-service на порту 8002
  • billing-service на порту 8003

2. Проверка работоспособности ​

bash
# Проверка auth-service
curl http://localhost:8001/health

# Проверка core-service
curl http://localhost:8002/health

# Проверка billing-service
curl http://localhost:8003/health

3. Просмотр логов ​

bash
# Все сервисы
docker-compose -f docker-compose.microservices.yml logs -f

# Конкретный сервис
docker-compose -f docker-compose.microservices.yml logs -f auth-service

4. Остановка сервисов ​

bash
docker-compose -f docker-compose.microservices.yml down

Локальная разработка (без Docker для сервисов) ​

1. Настройка баз данных ​

Создайте три базы данных PostgreSQL:

sql
CREATE DATABASE nimbus_auth;
CREATE DATABASE nimbus_core;
CREATE DATABASE nimbus_billing;

Или используйте Docker только для БД и Redis:

bash
docker-compose -f docker-compose.microservices.yml up -d postgres-auth postgres-core postgres-billing redis-auth redis-core redis-billing

2. Настройка переменных окружения ​

Создайте файлы .env в каждой директории сервиса:

services/auth-service/.env:

env
APP_ENV=dev
HTTP_PORT=8001
DATABASE_URL=postgres://postgres:postgres@localhost:5433/nimbus_auth?sslmode=disable
REDIS_URL=redis://localhost:6379/0
JWT_SECRET=uNnBTZJojS6nyp9QHKzlr41BWvyeVQemTHzGwXT3z8c=
CORS_ORIGIN=http://localhost:5173
USE_HTTPS=false
DOMAIN=localhost

services/core-service/.env:

env
APP_ENV=dev
HTTP_PORT=8002
DATABASE_URL=postgres://postgres:postgres@localhost:5434/nimbus_core?sslmode=disable
REDIS_URL=redis://localhost:6380/0
JWT_SECRET=uNnBTZJojS6nyp9QHKzlr41BWvyeVQemTHzGwXT3z8c=
CORS_ORIGIN=http://localhost:5173
AUTH_SERVICE_URL=http://localhost:8001
USE_HTTPS=false
DOMAIN=localhost

services/billing-service/.env:

env
APP_ENV=dev
HTTP_PORT=8003
DATABASE_URL=postgres://postgres:postgres@localhost:5435/nimbus_billing?sslmode=disable
REDIS_URL=redis://localhost:6381/0
JWT_SECRET=uNnBTZJojS6nyp9QHKzlr41BWvyeVQemTHzGwXT3z8c=
CORS_ORIGIN=http://localhost:5173
AUTH_SERVICE_URL=http://localhost:8001
CORE_SERVICE_URL=http://localhost:8002
USE_HTTPS=false
DOMAIN=localhost

3. Установка зависимостей ​

bash
# Auth Service
cd services/auth-service
go mod download
go mod tidy

# Core Service
cd ../core-service
go mod download
go mod tidy

# Billing Service
cd ../billing-service
go mod download
go mod tidy

4. Запуск сервисов ​

В отдельных терминалах:

bash
# Terminal 1: Auth Service
cd services/auth-service
go run cmd/server/main.go

# Terminal 2: Core Service
cd services/core-service
go run cmd/server/main.go

# Terminal 3: Billing Service
cd services/billing-service
go run cmd/server/main.go

Миграция данных из монолита ​

Важно: порядок миграции ​

  1. Сначала запустите auth-service и выполните миграцию пользователей.
  2. Затем запустите core-service и выполните миграцию организаций и связанных данных.
  3. В конце запустите billing-service и выполните миграцию начислений.

Шаги миграции ​

1. Миграция пользователей (auth-service) ​

bash
# Подключитесь к БД монолита и экспортируйте пользователей
psql -d nimbus -c "COPY (SELECT * FROM users) TO STDOUT WITH CSV HEADER" > users.csv

# Импортируйте в auth-service БД
psql -d nimbus_auth -c "COPY users FROM STDIN WITH CSV HEADER" < users.csv

2. Миграция организаций и связанных данных (core-service) ​

bash
# Экспорт организаций
psql -d nimbus -c "COPY (SELECT * FROM organizations) TO STDOUT WITH CSV HEADER" > organizations.csv
psql -d nimbus_core -c "COPY organizations FROM STDIN WITH CSV HEADER" < organizations.csv

# Экспорт домов
psql -d nimbus -c "COPY (SELECT * FROM houses) TO STDOUT WITH CSV HEADER" > houses.csv
psql -d nimbus_core -c "COPY houses FROM STDIN WITH CSV HEADER" < houses.csv

# И так далее для всех таблиц core-service

3. Миграция начислений (billing-service) ​

bash
# Экспорт начислений
psql -d nimbus -c "COPY (SELECT * FROM bills) TO STDOUT WITH CSV HEADER" > bills.csv
psql -d nimbus_billing -c "COPY bills FROM STDIN WITH CSV HEADER" < bills.csv

API‑эндпоинты ​

Auth Service (порт 8001) ​

  • POST /api/auth/register — Регистрация пользователя
  • POST /api/auth/login — Вход в систему
  • POST /api/auth/logout — Выход из системы
  • POST /api/auth/refresh — Обновление токенов
  • GET /api/auth/user — Получить текущего пользователя
  • GET /api/auth/csrf-token — Получить CSRF токен
  • GET /api/auth/2fa/status — Статус 2FA
  • POST /api/auth/2fa/setup — Настройка 2FA
  • POST /api/auth/2fa/verify-setup — Подтверждение настройки 2FA
  • POST /api/auth/2fa/disable — Отключение 2FA
  • POST /api/auth/2fa/verify-login — Проверка 2FA при входе

Core Service (порт 8002) ​

  • GET /api/organizations — Список организаций
  • GET /api/organizations/:id — Получить организацию
  • POST /api/organizations — Создать организацию
  • PUT /api/organizations/:id — Обновить организацию
  • DELETE /api/organizations/:id — Удалить организацию

Billing Service (порт 8003) ​

  • Заготовка для будущей реализации

Тестирование ​

Тест регистрации и входа ​

bash
# 1. Получить CSRF токен
CSRF_TOKEN=$(curl -s -c cookies.txt http://localhost:8001/api/auth/csrf-token | jq -r '.csrfToken')

# 2. Регистрация
curl -X POST http://localhost:8001/api/auth/register \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -b cookies.txt \
  -c cookies.txt \
  -d '{
    "firstName": "Test",
    "lastName": "User",
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123"
  }'

# 3. Вход
curl -X POST http://localhost:8001/api/auth/login \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -c cookies.txt \
  -d '{
    "username": "testuser",
    "password": "password123"
  }'

# 4. Получить текущего пользователя
curl http://localhost:8001/api/auth/user \
  -b cookies.txt

Устранение неполадок ​

Проблема: сервис не запускается ​

  1. Проверьте логи: docker-compose -f docker-compose.microservices.yml logs <service-name>.
  2. Убедитесь, что БД доступна: docker-compose -f docker-compose.microservices.yml ps.
  3. Проверьте переменные окружения.

Проблема: ошибка подключения к БД ​

  1. Убедитесь, что PostgreSQL запущен.
  2. Проверьте DATABASE_URL в переменных окружения.
  3. Проверьте, что БД создана: psql -l | grep nimbus.

Проблема: ошибка подключения к Redis ​

  1. Убедитесь, что Redis запущен: redis-cli ping.
  2. Проверьте REDIS_URL в переменных окружения.

Проблема: CORS‑ошибки ​

  1. Убедитесь, что CORS_ORIGIN правильно настроен.
  2. Проверьте, что фронтенд использует правильный URL.

Следующие шаги ​

  1. Настройте мониторинг (Prometheus, Grafana).
  2. Настройте логирование (ELK Stack или Loki).
  3. Настройте API Gateway для маршрутизации запросов.
  4. Добавьте остальные handlers для core-service.
  5. Реализуйте функциональность billing-service.