Руководство по установке и развёртыванию

Содержание

1. Обзор
2. Компоненты и порты
3. Запуск бинарников напрямую
4. Запуск с Docker
5. Примеры Docker Compose
6. Обновление запущенной инсталляции
7. Справочник переменных окружения
8. Режим SQLite
9. Mock Resolver
10. Runner Agent
11. Server Generator
12. Настройка TLS
13. Резервное копирование и восстановление
14. Проверки здоровья
15. Рекомендации для продакшена
16. Развёртывание в Kubernetes

Обзор

Что такое Docker? Docker – это инструмент, который упаковывает приложения в легковесные переносимые контейнеры, чтобы они работали одинаково на любой машине. Использование Docker для Mockarty упрощает развёртывание: вы получаете воспроизводимое окружение со всеми зависимостями, простое масштабирование через Docker Compose и отсутствие необходимости устанавливать что-либо на хост, кроме самого Docker.

Mockarty распространяется двумя способами:

1. Готовые бинарные файлы — скачайте с GitHub Releases и запустите как нативные процессы
2. Официальные Docker-образы — скачайте с Docker Hub и запустите в контейнерах

Официальные образы Docker Hub:

Исходный код не требуется. Все бинарники и Docker-образы самодостаточны и включают встроенный веб-интерфейс, миграции базы данных и конфигурацию по умолчанию.

URL-адреса в примерах: Во всех примерах используется localhost:5770 как адрес Mockarty по умолчанию. Если ваш экземпляр работает на удалённом сервере, замените localhost:5770 на реальный адрес (например, https://mockarty.company.com или http://192.168.1.50:5770). Подробнее — в разделе Полезные функции и советы.

Компоненты и порты

Примечание: Порт 5773 — внутренний gRPC-порт координатора для регистрации resolver/runner нод. Он не предназначен для gRPC мок-трафика.

Чек-лист для фаервола

Откройте следующие порты admin-ноды для клиентов и соседних сервисов:

• 5770/tcp — HTTP: веб-интерфейс, REST API, мок-трафик (stubs). Открывайте для конечных пользователей и SDK/CLI-клиентов.
• 5771/tcp — HTTPS: то же самое с TLS. Открывайте для пользователей при HTTPS_ENABLED=true.
• 5772/tcp — MCP (Model Context Protocol). Открывайте только для хостов с MCP-совместимыми AI-ассистентами.
• 5773/tcp — координатор gRPC. Открывайте только resolver/runner-нодам, не публикуйте в интернет.

Resolver-ноды дополнительно используют 5780/tcp (мок-трафик) и 6780/tcp (дашборд); runner-агенты используют 6770/tcp (дашборд). Открывайте эти порты только там, где соответствующий компонент действительно развернут.

Запуск бинарников напрямую

1. Скачайте

Скачайте подходящий бинарник для вашей платформы с GitHub Releases.

2. Сделайте исполняемым (Linux/macOS)

chmod +x mockarty

3. Запуск бинарника

Самый простой способ запуска — с SQLite, без внешней базы данных:

DB_USE=sqlite ./mockarty

Mockarty запустится по адресу http://localhost:5770 с базой данных SQLite в ~/.mockarty/data.db.

Учётные данные администратора по умолчанию: admin / admin (смените сразу после первого входа).

4. Запуск с PostgreSQL

export DB_USE=pg
export DB_DSN="postgres://mockarty:password@localhost:5432/mockarty?sslmode=disable"
export FIRST_ADMIN_PASSWORD=change_me

./mockarty

Admin нода запустится по адресу http://localhost:5770.

5. Запуск с SQLite (без PostgreSQL)

export DB_USE=sqlite
export DB_DSN="/path/to/mockarty.db"
export FIRST_ADMIN_PASSWORD=change_me

./mockarty

Если DB_DSN не указан при DB_USE=sqlite, база данных по умолчанию создаётся в ~/.mockarty/data.db.

Маршрутизация URL для резолвинга моков

Mockarty использует систему маршрутизации URL на основе неймспейсов. Весь мок-трафик проходит через префикс /stubs/, за которым следует имя неймспейса:

http://localhost:5770/stubs/{namespace}/{ваш-маршрут-мока}

Например, если вы создали мок с маршрутом /api/users в неймспейсе sandbox:

# Вызов мока
curl http://localhost:5770/stubs/sandbox/api/users

# С параметрами запроса
curl "http://localhost:5770/stubs/sandbox/api/users?page=1&limit=10"

# POST-запрос
curl -X POST http://localhost:5770/stubs/sandbox/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "John"}'

Неймспейс sandbox создаётся автоматически при первом запуске. Дополнительные неймспейсы можно создать через Админ-панель или страницу Настроек.

Важно: Префикс /stubs/{namespace}/ обязателен для всех запросов резолвинга моков. Веб-интерфейс, REST API и эндпоинты управления используют другие пути (например, /ui/, /mock/, /api/).

6. Управление миграциями

Миграции применяются автоматически при запуске. Для ручного управления:

# Применить все ожидающие миграции
./mockarty --migrate up

# Применить N миграций
./mockarty --migrate up --migrate-steps N

# Откатить N миграций
./mockarty --migrate down --migrate-steps N

# Показать текущую версию миграции
./mockarty --migrate version

# Пробный запуск (вывести SQL без выполнения)
./mockarty --migrate up --migrate-dry-run

# Автоисправление грязного состояния миграции
./mockarty --migrate up --migrate-fix-dirty

7. Запуск как systemd-сервис (Linux)

Создайте /etc/systemd/system/mockarty.service:

[Unit]
Description=Mockarty Mock Server
After=network.target postgresql.service

[Service]
Type=simple
User=mockarty
ExecStart=/opt/mockarty/mockarty
WorkingDirectory=/opt/mockarty
Environment=DB_USE=pg
Environment=DB_DSN=postgres://mockarty:password@localhost:5432/mockarty?sslmode=disable
Environment=FIRST_ADMIN_PASSWORD=change_me
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable mockarty
sudo systemctl start mockarty

Запуск с Docker

Внимание: HTTP_BIND_ADDR — Внутри Docker-контейнеров вы ОБЯЗАТЕЛЬНО должны установить HTTP_BIND_ADDR=0.0.0.0. Значение по умолчанию localhost делает сервер недоступным извне контейнера.

Внимание: COOKIE_SECURE — При работе без HTTPS (разработка) установите COOKIE_SECURE=false, чтобы избежать зацикливания аутентификации.

Использование официальных Docker-образов

Самый быстрый способ — использовать официальные образы с Docker Hub:

Admin нода

docker run -d \
  --name mockarty \
  -p 5770:5770 \
  -p 5771:5771 \
  -p 5772:5772 \
  -e HTTP_BIND_ADDR=0.0.0.0 \
  -e DB_USE=pg \
  -e DB_DSN="postgres://mockarty:password@postgres:5432/mockarty?sslmode=disable" \
  -e FIRST_ADMIN_PASSWORD=change_me \
  mockarty/mockarty:latest

С SQLite (без сервера базы данных)

docker run -d \
  --name mockarty \
  -p 5770:5770 \
  -e HTTP_BIND_ADDR=0.0.0.0 \
  -e DB_USE=sqlite \
  -e DB_DSN="/data/mockarty.db" \
  -e FIRST_ADMIN_PASSWORD=change_me \
  -v mockarty-data:/data \
  mockarty/mockarty:latest

Сборка собственного Docker-образа из бинарника

Если вы не можете использовать Docker Hub (air-gapped окружение), создайте минимальный образ из скачанного бинарника:

FROM alpine:3.20
RUN apk add --no-cache ca-certificates tzdata curl
COPY mockarty /usr/local/bin/mockarty
RUN chmod +x /usr/local/bin/mockarty
EXPOSE 5770 5771 5772 5773
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:5770/health/live || exit 1
ENTRYPOINT ["mockarty"]

Сборка и запуск:

docker build -t mockarty:latest -f Dockerfile.admin .
docker run -d \
  --name mockarty \
  -p 5770:5770 \
  -e HTTP_BIND_ADDR=0.0.0.0 \
  -e DB_USE=sqlite \
  -e FIRST_ADMIN_PASSWORD=change_me \
  mockarty:latest

Важно: Используйте бинарник linux/amd64 или linux/arm64, соответствующий архитектуре вашего Docker-хоста.

Примеры Docker Compose

Минимальный: Admin + PostgreSQL

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: mockarty
      POSTGRES_PASSWORD: change_me
      POSTGRES_DB: mockarty
    volumes:
      - pg-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mockarty"]
      interval: 5s
      retries: 10

  mockarty:
    image: mockarty/mockarty:latest
    ports:
      - "5770:5770"   # HTTP — Web UI, REST API, мок-трафик
      - "5771:5771"   # HTTPS
      - "5772:5772"   # MCP
      - "5773:5773"   # gRPC координатор (для resolver/runner нод)
    environment:
      HTTP_BIND_ADDR: "0.0.0.0"
      DB_USE: pg
      DB_DSN: postgres://mockarty:change_me@postgres:5432/mockarty?sslmode=disable
      FIRST_ADMIN_PASSWORD: change_me
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5770/health/live"]
      interval: 10s
      timeout: 5s
      retries: 10

volumes:
  pg-data:

Минимальный: Admin + SQLite (без сервера БД)

services:
  mockarty:
    image: mockarty/mockarty:latest
    ports:
      - "5770:5770"
      - "5771:5771"
    environment:
      HTTP_BIND_ADDR: "0.0.0.0"
      DB_USE: sqlite
      DB_DSN: /data/mockarty.db
      FIRST_ADMIN_PASSWORD: change_me
    volumes:
      - mockarty-data:/data

volumes:
  mockarty-data:

Полный: Admin + PostgreSQL + Redis + Resolver + Runner

Распределённое развёртывание требует двухфазного запуска, поскольку resolver- и runner-ноды нуждаются в интеграционных токенах, которые генерируются admin-нодой.

Фаза 1: Запуск admin-ноды и базы данных

Создайте docker-compose.yml:

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: mockarty
      POSTGRES_PASSWORD: change_me
      POSTGRES_DB: mockarty
    volumes:
      - pg-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mockarty"]
      interval: 5s
      retries: 10

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      retries: 10

  mockarty:
    image: mockarty/mockarty:latest
    ports:
      - "5770:5770"
      - "5771:5771"
      - "5772:5772"
      - "5773:5773"   # gRPC координатор (внутренний — открывайте только внутри compose-сети)
    environment:
      HTTP_BIND_ADDR: "0.0.0.0"
      DB_USE: pg
      DB_DSN: postgres://mockarty:change_me@postgres:5432/mockarty?sslmode=disable
      CACHE_TYPE: redis
      REPO_REDIS_HOST: redis
      REPO_REDIS_PORT: "6379"
      FIRST_ADMIN_PASSWORD: change_me
      RUNNER_GRPC_BIND_ADDR: "0.0.0.0"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5770/health/live"]
      interval: 10s
      timeout: 5s
      retries: 10

  resolver:
    image: mockarty/resolver:latest
    ports:
      - "5780:5780"
      - "6780:6780"
    environment:
      COORDINATOR_ADDR: mockarty:5773
      API_TOKEN: "${RESOLVER_API_TOKEN}"
      RESOLVER_NAME: "resolver-1"
      DB_DSN: postgres://mockarty:change_me@postgres:5432/mockarty?sslmode=disable
      HTTP_PORT: "5780"
    depends_on:
      mockarty:
        condition: service_healthy

  runner:
    image: mockarty/runner:latest
    environment:
      COORDINATOR_ADDR: mockarty:5773
      API_TOKEN: "${RUNNER_API_TOKEN}"
      RUNNER_NAME: "runner-1"
      SHARED: "true"
      CAPABILITIES: "api_test,performance"
    depends_on:
      mockarty:
        condition: service_healthy

volumes:
  pg-data:

Сначала запустите только admin-ноду:

docker compose up -d postgres redis mockarty

Дождитесь готовности admin-ноды, затем войдите в веб-интерфейс по адресу http://localhost:5770/ui/ и смените пароль по умолчанию.

Фаза 2: Генерация токенов и запуск resolver/runner

Сгенерируйте токены для resolver и runner через API:

# Создать токен для resolver
curl -X POST http://localhost:5770/api/v1/integrations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"resolver-1","type":"mock_resolver"}'

# Создать токен для runner
curl -X POST http://localhost:5770/api/v1/integrations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"runner-1","type":"test_runner"}'

Каждый ответ содержит поле token (формат: mki_...). Сохраните токены сразу — они показываются только один раз.

Поместите токены в .env файл рядом с docker-compose.yml:

RESOLVER_API_TOKEN=mki_your_resolver_token_here
RUNNER_API_TOKEN=mki_your_runner_token_here

Теперь запустите полный стек:

docker compose up -d

Resolver- и runner-ноды аутентифицируются у admin-ноды с помощью интеграционных токенов и регистрируются через gRPC-порт координатора (5773).

Важно: Если resolver или runner запустятся без действительных токенов, они не смогут подключиться и будут перезапускаться в цикле. Всегда генерируйте токены перед запуском этих компонентов.

С генерированными серверами

Серверы, созданные mockarty-server-generator, — это автономные сервисы, которые обращаются к admin ноде Mockarty для резолвинга моков:

services:
  mockarty:
    image: mockarty/mockarty:latest
    ports:
      - "5770:5770"
    environment:
      HTTP_BIND_ADDR: "0.0.0.0"
      DB_USE: pg
      DB_DSN: postgres://mockarty:change_me@postgres:5432/mockarty?sslmode=disable
      FIRST_ADMIN_PASSWORD: change_me

  # Генерированный MCP-сервер (собранный из сгенерированного кода)
  mcp-server:
    image: my-mcp-server:latest
    ports:
      - "8080:8080"   # Админ-панель
      - "8910:8910"   # MCP SSE эндпоинт
    environment:
      HTTP_ADMIN_BASE_URL: http://mockarty:5770
      NAMESPACE: sandbox
      MCP_SSE_PORT: "8910"
    depends_on:
      - mockarty

  # Генерированный gRPC-сервер (собранный из сгенерированного кода)
  grpc-server:
    image: my-grpc-server:latest
    ports:
      - "4770:4770"   # gRPC
      - "8081:8080"   # Админ-панель
    environment:
      HTTP_ADMIN_BASE_URL: http://mockarty:5770
      GRPC_PORT: "4770"
      NAMESPACE: sandbox
    depends_on:
      - mockarty

Примечание: Генерированные серверы собираются из кода, созданного mockarty-server-generator. Подробности в Руководстве по генератору кода.

Обновление запущенной инсталляции

Mockarty поставляется в виде набора версионированных Docker-образов на Docker Hub. Процесс обновления одинаков и для Docker Compose, и для Helm: меняем tag образа и даём оркестратору пересоздать контейнеры. Миграции базы применяются автоматически при старте admin-ноды — вручную SQL выполнять не нужно.

Образы на Docker Hub

Каждый образ публикуется с двумя тегами: точная версия (например, mockarty/mockarty:0.0.4-beta) и latest. В продакшене фиксируйте точную версию — latest может незаметно поменяться.

Перед обновлением

1. Сделайте бэкап базы. На single-node: docker compose exec postgres pg_dump -U mockarty mockarty > backup.sql. На Helm-кластере используйте штатный workflow бэкапа Postgres.
2. Прочитайте release notes целевой версии: https://mockarty.ru/downloads или GitHub.
3. Проверьте здоровье текущей инсталляции: curl -fsS http://<admin>/health/live.

Обновление Docker Compose

# 1. Зафиксируйте новую версию в .env:
#    VERSION=0.0.4-beta

# 2. Скачайте новые образы
docker compose -f docker-compose.minimal.yml pull

# 3. Пересоздайте контейнеры in-place (volumes сохраняются)
docker compose -f docker-compose.minimal.yml up -d

# 4. Следите за логами пока admin-нода не сообщит «migrations applied»
docker compose -f docker-compose.minimal.yml logs -f mockarty

Для распределённого стека обновляйте в таком порядке, чтобы не оборвать трафик во время миграций:

docker compose -f docker-compose.distributed.yml pull
docker compose -f docker-compose.distributed.yml up -d --no-deps mockarty
docker compose -f docker-compose.distributed.yml up -d --no-deps mockarty-resolver
docker compose -f docker-compose.distributed.yml up -d --no-deps mockarty-runner

Обновление Helm / Kubernetes

# Вариант A — поднять tag на все компоненты разом (проще всего)
helm upgrade mockarty deploy/helm/mockarty \
  --namespace mockarty \
  --reuse-values \
  --set admin.image.tag=0.0.4-beta \
  --set resolver.image.tag=0.0.4-beta \
  --set runner.image.tag=0.0.4-beta \
  --set orchestrator.image.tag=0.0.4-beta

# Вариант B — держать values.yaml источником правды
#   отредактируйте values.yaml и поднимите image.tag у каждого компонента
helm upgrade mockarty deploy/helm/mockarty --namespace mockarty -f values.yaml

Kubernetes обновляет pods стратегией RollingUpdate (maxSurge=1, maxUnavailable=0), поэтому трафик резолверов и раннеров не прерывается. Admin StatefulSet раскатывается по одному поду — кратковременное мигание UI во время обновления admin-ноды ожидаемо.

Откат

# Docker Compose: укажите прежний VERSION в .env и повторите up -d
VERSION=0.0.3 docker compose -f docker-compose.minimal.yml up -d

# Helm: откат релиза
helm rollback mockarty --namespace mockarty

Откат миграций (./mockarty --migrate down --migrate-steps N) возможен только для последних N миграций и только если новая версия явно описала down-путь. Если уверенности нет — восстанавливайте из бэкапа.

Справочник переменных окружения

Основные

HTTP сервер

MCP сервер

LLM / AI-ассистент

AI-агент (ADK)

База данных

Кеш

Аутентификация

OAuth провайдеры

Рекомендация: Настраивайте OAuth-провайдеров через веб-интерфейс Админ-панели (Панель администрирования > Провайдеры авторизации) для поддержки горячей перезагрузки. Переменные окружения ниже поддерживаются для обратной совместимости и начальной загрузки.

LDAP / Active Directory

LDAP/AD аутентификация настраивается исключительно через веб-интерфейс Админ-панели (Панель администрирования > Провайдеры авторизации). Настройки хранятся в базе данных и применяются без перезапуска. Переменных окружения для LDAP нет — войдите под bootstrap-админом и завершите настройку в UI.

Email уведомления

Координатор Runner

Хаос-инженерия

Хаос-инженерия требует PRO-лицензии и подключённого кластера Kubernetes. Подробности см. в руководстве Хаос-инженерия.

Контрактное тестирование

Контрактное тестирование проверяет соответствие моков спецификациям API. Подробности см. в руководстве Контрактное тестирование.

Контрактное тестирование включается пользователем в Настройках пользователя и не требует дополнительных переменных окружения. Прогоны контрактной валидации настраиваются через UI или API.

Лицензия

Лицензионные ключи вводятся через панель администратора: Администрирование → Лицензия. Переменные окружения для активации лицензии не нужны.

Безопасность

Кластер

Шина событий

Режим SQLite

Mockarty поддерживает SQLite для небольших развёртываний, не требующих PostgreSQL. Режим SQLite идеален для:

• Развёртываний на одном сервере
• Окружений разработки и тестирования
• Быстрой оценки возможностей

# Прямой запуск
DB_USE=sqlite DB_DSN="/data/mockarty.db" ./mockarty

# Docker
docker run -d \
  --name mockarty \
  -p 5770:5770 \
  -e HTTP_BIND_ADDR=0.0.0.0 \
  -e DB_USE=sqlite \
  -e DB_DSN="/data/mockarty.db" \
  -e FIRST_ADMIN_PASSWORD=change_me \
  -v mockarty-data:/data \
  mockarty/mockarty:latest

SQLite использует режим WAL для конкурентного чтения с одним писателем.

Ограничения:

• Нет поддержки распределённых resolver/runner — resolver-ноды требуют PostgreSQL через DB_DSN для общего доступа к базе данных, что невозможно с одним файлом SQLite
• Некоторые запросы статистики дашборда могут возвращать пустые результаты на SQLite
• Если DB_DSN не указан при DB_USE=sqlite, база создаётся в ~/.mockarty/data.db

Mock Resolver

Подробные инструкции по настройке см. в Руководстве по интеграциям.

Resolver-ноды обрабатывают трафик резолвинга моков, разгружая admin ноду. Направляйте весь мок-трафик (HTTP, gRPC и т.д.) на resolver-ноды; веб-интерфейс и API управления остаются на admin ноде.

Запуск напрямую

export COORDINATOR_ADDR=mockarty:5773
export API_TOKEN="mki_your_resolver_token"
export RESOLVER_NAME="resolver-1"
export DB_DSN="postgres://mockarty:password@localhost:5432/mockarty?sslmode=disable"
export HTTP_PORT=5780

./mockarty-resolver

Примечание: Resolver требует прямой доступ к базе данных (DB_DSN) для чтения определений моков. Он должен использовать ту же базу данных, что и admin-нода.

Запуск с Docker

resolver:
  image: mockarty/resolver:latest
  ports:
    - "5780:5780"   # Трафик резолвинга моков
    - "6780:6780"   # Дашборд
  environment:
    COORDINATOR_ADDR: mockarty:5773
    API_TOKEN: "mki_your_token"
    RESOLVER_NAME: "resolver-1"
    DB_DSN: postgres://mockarty:password@postgres:5432/mockarty?sslmode=disable
    HTTP_PORT: "5780"
  depends_on:
    - mockarty

Переменные окружения

Создание интеграционных токенов

Создайте токены resolver через API (требуется аутентификация администратора):

curl -X POST http://localhost:5770/api/v1/integrations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"resolver-1","type":"mock_resolver"}'

Ответ содержит поле token (показывается один раз, сохраните немедленно). Формат токена: mki_*.

Совет: Получите YOUR_API_TOKEN в Настройки > API Токены в веб-интерфейсе после входа как администратор.

Runner Agent

Подробные инструкции по настройке см. в Руководстве по интеграциям.

Runner-агенты выполняют нагрузочные тесты и коллекции API-тестов. Они подключаются к admin ноде через gRPC на порту 5773.

Запуск напрямую

export COORDINATOR_ADDR=mockarty:5773
export API_TOKEN="mki_your_runner_token"
export RUNNER_NAME="runner-1"
export SHARED=true
export CAPABILITIES="api_test,performance"

./mockarty-runner

Запуск с Docker

runner:
  image: mockarty/runner:latest
  environment:
    COORDINATOR_ADDR: mockarty:5773
    API_TOKEN: "mki_your_runner_token"
    RUNNER_NAME: "runner-1"
    SHARED: "true"
    MAX_CONCURRENT_TASKS: "3"
    CAPABILITIES: "api_test,performance"
  depends_on:
    - mockarty

Переменные окружения

Создание интеграционных токенов

curl -X POST http://localhost:5770/api/v1/integrations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"runner-1","type":"test_runner"}'

Ответ содержит поле token (показывается один раз, сохраните немедленно). Формат токена: mki_*.

Область видимости Runner

• Общие runner-ы (SHARED=true) — получают задачи из всех неймспейсов
• Runner-ы неймспейса (SHARED=false, NAMESPACE=sandbox) — получают задачи только из своего неймспейса

Возможности

Server Generator

Генератор серверов может работать как CLI-инструмент или как сервер-оркестратор.

Запуск оркестратора

./mockarty-server-generator orchestrator \
  -api-token mk_your_token \
  -http-admin-base-url http://localhost:5770 \
  -port 8888

Запуск оркестратора с Docker

server-generator:
  image: mockarty/generator:latest
  command: ["orchestrator", "-api-token", "mk_your_token", "-http-admin-base-url", "http://mockarty:5770", "-port", "8888"]
  ports:
    - "8888:8888"
  depends_on:
    - mockarty

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

Настройка TLS

Автоматически сгенерированные сертификаты

По умолчанию Mockarty генерирует самоподписанные TLS-сертификаты при первом запуске:

# Прямой запуск
HTTPS_ENABLED=true HTTPS_TLS_DIR=/opt/mockarty/tls ./mockarty

# Docker
docker run -d \
  -e HTTP_BIND_ADDR=0.0.0.0 \
  -e HTTPS_ENABLED=true \
  -e HTTPS_TLS_DIR=/app/tls \
  -v mockarty-tls:/app/tls \
  mockarty/mockarty:latest

Пользовательские сертификаты

# Прямой запуск
HTTPS_ENABLED=true \
HTTPS_CERT_FILE=/path/to/server.crt \
HTTPS_KEY_FILE=/path/to/server.key \
./mockarty

# Docker
docker run -d \
  -e HTTP_BIND_ADDR=0.0.0.0 \
  -e HTTPS_ENABLED=true \
  -e HTTPS_CERT_FILE=/certs/server.crt \
  -e HTTPS_KEY_FILE=/certs/server.key \
  -v /path/to/certs:/certs:ro \
  mockarty/mockarty:latest

TLS для gRPC координатора

Для защиты gRPC-канала координатора между admin и resolver/runner нодами:

RUNNER_GRPC_TLS_ENABLED=true \
RUNNER_GRPC_TLS_CERT_FILE=/certs/grpc-server.crt \
RUNNER_GRPC_TLS_KEY_FILE=/certs/grpc-server.key \
RUNNER_GRPC_TLS_CLIENT_CA_CERT=/certs/ca.crt \
./mockarty

Резервное копирование и восстановление

Mockarty включает встроенную систему резервного копирования, доступную в Панель администратора > Резервное копирование. Для PostgreSQL используется pg_dump/pg_restore, для SQLite — копирование файлов.

Официальный Docker-образ включает postgresql-client (pg_dump, pg_restore, psql), поэтому резервное копирование работает из коробки.

Ключевые возможности:

• Запланированные бэкапы — настраиваются через cron-выражение (по умолчанию: ежедневно в 2:00)
• Ручные бэкапы — создание по требованию из Панели администратора
• Несколько форматов — custom (рекомендуется), plain, tar, directory
• Сжатие — опционально, уменьшает размер файла бэкапа
• Политика хранения — автоматическое удаление старых бэкапов через N дней
• Скачивание / Восстановление — из Панели администратора или через API

Примеры API:

# Создать бэкап
curl -X POST http://localhost:5770/api/v1/admin/backups/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"config_id": "your-config-id"}'

# Скачать бэкап
curl http://localhost:5770/api/v1/admin/backups/download?path=backup_file.dump \
  -H "Authorization: Bearer $TOKEN" -o backup.dump

# Восстановить из загруженного файла
curl -X POST http://localhost:5770/api/v1/admin/backups/restore-from-file \
  -H "Authorization: Bearer $TOKEN" -F "file=@backup.dump"

Для Docker-развёртываний монтируйте постоянный том для хранения данных:

docker run -v /host/path/data:/app/data mockarty/mockarty:latest

Подробности см. в Руководстве по администрированию.

Проверки здоровья

Все компоненты предоставляют эндпоинты здоровья:

Пример проверки:

curl http://localhost:5770/health/live

Рекомендации для продакшена

1. Используйте PostgreSQL — SQLite предназначен только для разработки и небольших односерверных развёртываний
2. Установите сильные секреты — измените FIRST_ADMIN_PASSWORD с значения по умолчанию
3. Используйте reverse proxy (nginx/Traefik) перед Mockarty для терминации TLS и маршрутизации
4. Используйте Redis с CACHE_TYPE=redis для лучшей производительности admin-ноды при масштабировании
5. Включите резервное копирование — монтируйте постоянный том для хранения бэкапов
6. Используйте resolver-ноды для высоконагруженного резолвинга моков (разделяет мок-трафик от admin UI)
7. Используйте runner-агенты для распределённого выполнения тестов
8. Установите COOKIE_SECURE=true — включено по умолчанию, обеспечивает отправку кук только по HTTPS
9. Оставьте ALLOW_PROXY_TO_PRIVATE_IPS=false — по умолчанию, предотвращает SSRF через функцию проксирования
10. Установите HTTP_BIND_ADDR=0.0.0.0 в Docker/продакшене для приёма внешних подключений (по умолчанию localhost)
11. Включите контрактное тестирование для проверки соответствия моков спецификациям API. См. руководство Контрактное тестирование.
12. Используйте хаос-инженерию для тестирования устойчивости системы с помощью контролируемых экспериментов по внедрению сбоев. См. руководство Хаос-инженерия (требуется PRO-лицензия).

Развёртывание в Kubernetes

Для продакшен-окружений Kubernetes Mockarty предоставляет Helm-чарты и CRD-оператор, управляющий полным жизненным циклом кластера – масштабирование, обновления, проверки здоровья и начальная настройка токенов.

Быстрая установка через Helm

# Добавьте Helm-репозиторий Mockarty
helm repo add mockarty https://charts.mockarty.com
helm repo update

# Создайте секреты для базы данных и лицензии
kubectl create namespace mockarty
kubectl -n mockarty create secret generic mockarty-db \
  --from-literal=dsn="postgres://mockarty:secret@postgres:5432/mockarty?sslmode=require"
kubectl -n mockarty create secret generic mockarty-license \
  --from-literal=key="YOUR_LICENSE_KEY"

# Установите с файлом значений для кластера
helm install mockarty mockarty/mockarty \
  -n mockarty \
  -f values.cluster.yaml \
  --set admin.image.tag=latest \
  --set resolver.replicas=2 \
  --set runner.replicas=1

Компоненты кластера

Все компоненты регистрируются на Admin Node через gRPC-координатор (порт 5773) с использованием интеграционных токенов. Health-пробы (GET /health) предварительно настроены в Helm-шаблонах.

Управление кластером через CLI

CLI Mockarty предоставляет команды для управления кластерами Kubernetes без kubectl:

# Просмотр статуса кластера (ноды, версии, здоровье)
mockarty-cli cluster status

# Масштабирование resolver-нод
mockarty-cli cluster scale resolver --replicas 4

# Плавное обновление до нового image tag
mockarty-cli cluster upgrade --tag 1.3.0

# Перезапуск конкретного компонента
mockarty-cli cluster restart runner

# Потоковый просмотр логов компонентов кластера
mockarty-cli cluster logs resolver --follow

Хаос-оператор

Для тестирования устойчивости внутри Kubernetes установите Mockarty Chaos Operator:

mockarty-cli chaos operator install --namespace mockarty-chaos

Хаос-оператор интегрируется с функцией Хаос-инженерия для внедрения сбоев (задержки, ошибки, удаление подов) непосредственно в ваши Kubernetes-нагрузки. Требуется PRO-лицензия.

Подробнее о конфигурации на основе CRD, автомасштабировании HPA и топологиях с несколькими нодами см. руководство Архитектура масштабирования.

Смотрите также

• Быстрый старт — Начните работу за 20 минут
• Руководство администратора — Настройка после установки: пользователи, пространства имен, безопасность
• Руководство по интеграциям — Подробная настройка resolver-нод, runner-агентов и webhook
• Руководство по генератору кода — Генерация автономных серверов для всех поддерживаемых протоколов и брокеров
• Контрактное тестирование — Проверка соответствия моков спецификациям OpenAPI и реальным API
• Хаос-инженерия — Эксперименты по внедрению сбоев для тестирования устойчивости (PRO)
• Справочник API — Полная документация REST API