Локальная настройка

Previous Next

Руководство по настройке локального окружения для разработки AIOps.

Статус контента

  • Статус: Stable
  • Проверено: 2026-03-12
  • Источник версий: services/*/pyproject.toml, services/*/go.mod

Требования

Обязательные

  • Python 3.12+ — для всех Python сервисов
  • Go 1.26+ — для API Gateway
  • Docker & Docker Compose — для локальных зависимостей (PostgreSQL, Redis, Kafka)
  • Git — version control
  • uv — современный Python package manager

Рекомендуемые

  • kubectl — для работы с Kubernetes
  • helm — для деплоя charts
  • grpcurl — для тестирования gRPC endpoints
  • jq — для работы с JSON в CLI

Шаг 1: Установить базовые инструменты

Python (uv)

1
2
3
4
5
# Установить uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Проверить установку
uv --version

Go

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# macOS
brew install go@1.26

# Linux
wget https://go.dev/dl/go1.26.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.26.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

# Проверить
go version

Docker

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# macOS
brew install docker docker-compose

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install docker.io docker-compose

# Проверить
docker --version
docker-compose --version

grpcurl

1
2
3
4
5
6
7
8
# macOS
brew install grpcurl

# Linux
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

# Проверить
grpcurl --version

Шаг 2: Клонировать репозиторий

1
2
git clone https://gitlab.com/ai-operations/ai-ops.git
cd ai-ops

Шаг 3: Запустить инфраструктуру

Docker Compose для локальной разработки

1
2
cd infra/local
docker-compose up -d

Что запускается: - PostgreSQL (порт 5432) — основная БД - Redis (порт 6379) — кеширование - Kafka (порт 9092) — события - Zookeeper (порт 2181) — для Kafka

Проверить статус

1
2
3
4
5
6
7
docker-compose ps

# Должны быть running:
# - postgres
# - redis
# - kafka
# - zookeeper

Логи

1
2
3
4
5
# Все сервисы
docker-compose logs -f

# Конкретный сервис
docker-compose logs -f postgres

Шаг 4: Настроить Python окружение

Identity Service (пример)

1
2
3
4
5
6
7
8
cd services/auth/identity-service

# Создать виртуальное окружение и установить зависимости
uv sync

# Активировать окружение
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

Проверить установку

1
2
3
4
uv run python --version
uv run pytest --version
uv run mypy --version
uv run ruff --version

Шаг 5: Настроить базы данных

Создать базы данных

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Подключиться к PostgreSQL
docker exec -it aiops-postgres psql -U postgres

# Создать БД для сервисов
CREATE DATABASE identity_db;
CREATE DATABASE credential_db;
CREATE DATABASE account_db;
CREATE DATABASE herald_db;
CREATE DATABASE token_db;

# Выйти
\q

Применить миграции (Identity Service)

1
2
3
4
5
6
7
cd services/auth/identity-service

# Применить миграции
uv run alembic upgrade head

# Проверить статус
uv run alembic current

Шаг 6: Настроить конфигурацию

Environment Variables

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

1
cd services/auth/identity-service

Создать файл .env: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# Database
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/identity_db

# Redis
REDIS_URL=redis://localhost:6379/0

# Kafka
KAFKA_BOOTSTRAP_SERVERS=localhost:9092

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=50051

# Logging
LOG_LEVEL=DEBUG

Важно: .env файлы НЕ коммитятся в Git (проверь .gitignore)!

Шаг 7: Запустить сервис

Identity Service

1
2
3
4
5
6
7
cd services/auth/identity-service

# Запустить API сервер
uv run python -m identity_service.api

# В другом терминале: запустить Worker (Outbox)
uv run python -m identity_service.worker

Вывод: 

1
2
3
INFO     Starting Identity Service API
INFO     gRPC server listening on [::]:50051
INFO     Health check endpoint available

Проверить health

1
grpcurl -plaintext localhost:50051 grpc.health.v1.Health/Check

Ответ: 

1
2
3
{
  "status": "SERVING"
}

Список доступных методов

1
grpcurl -plaintext localhost:50051 list

Шаг 8: Запустить тесты

Unit Tests

1
2
3
4
5
6
7
cd services/auth/identity-service

# Все unit tests
uv run pytest tests/unit -v

# С coverage
uv run pytest tests/unit --cov=identity_service --cov-report=html

Integration Tests

1
2
# Integration tests (требуют Docker для testcontainers)
uv run pytest tests/integration -v

Линтеры

1
2
3
4
5
6
7
8
# Ruff check
uv run ruff check src/ tests/

# Ruff format
uv run ruff format src/ tests/

# MyPy
uv run mypy src/

Шаг 9: API Gateway (Go)

Установить зависимости

1
2
cd services/api-gateway
go mod download

Запустить

1
go run cmd/control-plane/main.go

Вывод: 

1
2
INFO  Starting API Gateway Control Plane
INFO  Listening on :8080

Структура проекта (напоминание)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
ai-ops/
├── services/
│   ├── auth-platform/
│   │   ├── identity-service/      # Python, gRPC
│   │   ├── credential-service/    # Python, gRPC
│   │   ├── auth-service/          # Planned
│   │   └── ...
│   └── api-gateway/               # Go, Envoy
├── libs/
│   └── python/
│       ├── common/                # contracts, context, observability, utils
│       ├── communication/         # grpc-stubs, kafka, clients, …
│       ├── storage/               # postgres, redis, uow, outbox
│       └── runtime/               # api runtimes, dishka, workers
├── proto/                         # Protocol Buffers
├── infra/
│   ├── k8s/                       # Kubernetes manifests
│   └── local/                     # Docker Compose
└── docs/                          # Документация

Полезные скрипты

Создать новую миграцию (Alembic)

1
2
cd services/auth/identity-service
uv run alembic revision --autogenerate -m "add users table"

Перегенерировать Proto stubs

1
2
# из корня репозитория
make -C scripts/tools proto-python-compile

Сбросить БД и накатить миграции заново

1
2
3
4
5
6
7
cd services/auth/identity-service

# Откатить все миграции
uv run alembic downgrade base

# Накатить заново
uv run alembic upgrade head

Troubleshooting

PostgreSQL connection refused

1
2
3
4
5
6
# Проверить, что контейнер запущен
docker ps | grep postgres

# Перезапустить
cd infra/local
docker-compose restart postgres

Kafka not available

1
2
3
4
5
# Kafka долго стартует (~30-60 сек)
# Проверить логи
docker-compose logs kafka

# Дождаться сообщения "Kafka Server started"

Import errors в Python

1
2
3
4
5
# Убедись, что используешь правильную venv
which python  # должен показывать .venv/bin/python

# Переустановить зависимости
uv sync --reinstall

Port already in use

1
2
3
4
5
6
7
# Найти процесс, занимающий порт
lsof -i :50051  # macOS/Linux
netstat -ano | findstr :50051  # Windows

# Убить процесс
kill -9 <PID>  # macOS/Linux
taskkill /PID <PID> /F  # Windows

Docker Compose fails to start

1
2
3
4
5
6
# Проверить логи
docker-compose logs

# Очистить volumes и перезапустить
docker-compose down -v
docker-compose up -d

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

После настройки локального окружения:

  1. Git Workflow — как работать с Git
  2. Coding Standards — стандарты кода
  3. How to Find the Right Service — навигация по сервисам
  4. Developer FAQ — частые вопросы

Связанные страницы

Быстрый старт Карта репозиториев