Окружения

Инфраструктура использует три окружения. Каждое соответствует ветке Git, набору доменов и стратегии развёртывания.

Матрица окружений

Окружение	Ветка	Шаблон домена	Namespace	Нода	Развёртывание
dev	dev	dev-*.amzhub.ai	dev	192.168.100.20	Автоматически при push
stage	stage	stage-*.amzhub.ai	stage	192.168.100.30	Автоматически при push
prod	main	*.amzhub.ai	prod	192.168.100.40	Ручное подтверждение

TIP

Dev и stage развёртываются автоматически при обновлении соответствующих веток. Для prod требуется ручной запуск в пайплайне GitLab CI.

Настройка локальной разработки

1. Клонирование репозитория

git clone git@gitlab.amzgit.com:integrations/hub.git
cd hub

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

# Backend (Fastify)
cd backend
npm install

# Frontend (Vue 3)
cd ../frontend
npm install

3. Настройка локального окружения

Скопируйте пример файла окружения и заполните локальные значения:

cp .env.example .env

Файл .env используется только для локальной разработки. В развёрнутых окружениях конфигурация внедряется из Consul KV.

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

# Terminal 1 -- Backend
cd backend
npm run dev
# Fastify starts on http://localhost:3000

# Terminal 2 -- Frontend
cd frontend
npm run dev
# Vite dev server starts on http://localhost:5173

WARNING

Dev-сервер фронтенда проксирует запросы /api/* на localhost:3000 через конфигурацию Vite. Убедитесь, что бэкенд запущен, прежде чем тестировать API-вызовы из интерфейса.

5. Запуск тестов

# Backend tests
cd backend
npm run test

# Frontend tests
cd frontend
npm run test

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

В развёрнутых окружениях вся конфигурация хранится в Consul KV и внедряется в контейнеры через станзу template Nomad. Никакие секреты не встраиваются в Docker-образы.

Структура Consul KV

hub/
├── dev/
│   └── config      # один JSON: порт, БД, Redis, ключи
├── stage/
│   └── config
└── prod/
    └── config

У каждого сервиса своё поддерево с ключом config на каждое окружение. Значение — JSON-документ целиком; Nomad читает его при старте задачи и разворачивает в переменные окружения внутри контейнера.

Пример шаблона Nomad

В спецификации задания Nomad станза template извлекает значения из Consul KV:

template {
  data = <<EOH
{{- with key "hub/dev/config" }}
{{- $c := . | parseJSON }}
PORT={{ $c.port }}
DATABASE_URL={{ $c.db_hub.password }}
{{- end }}
EOH

  destination = "secrets/app.env"
  env         = true
  change_mode = "restart"
}

Конфигурация лежит одним JSON-документом по ключу <сервис>/<среда>/config, а не россыпью отдельных ключей. change_mode = "restart" означает, что правка значения в Consul сама перезапустит задачу.

Управление секретами

Для чтения или записи значений в Consul KV:

export CONSUL_HTTP_ADDR=http://192.168.100.1:8500
export CONSUL_HTTP_TOKEN=<ваш токен>

# Прочитать конфиг сервиса целиком
consul kv get hub/dev/config

# Записать обновлённый JSON
consul kv put hub/dev/config @config.json

DANGER

Никогда не коммитьте секреты в Git. Все конфиденциальные значения должны передаваться через Consul KV. Если секрет был случайно закоммичен, немедленно выполните его ротацию и принудительно отправьте очищенную историю.

Доступ к каждому окружению

Dev

• URL: https://dev.amzhub.ai
• API: https://dev-api.amzhub.ai/api/
• Доступ: Публичный по HTTPS, деплой автоматический при пуше в dev.

Stage

• URL: https://stage-<сервис>.amzhub.ai
• Доступ: Публичный по HTTPS. Используется для QA и предрелизной валидации.

Prod

• URL: https://amzhub.ai
• API: https://api.amzhub.ai/api/
• Доступ: Публичный. Развёртывание требует ручного подтверждения пайплайна в GitLab.

Nomad и Consul UI — общие на весь кластер и наружу не опубликованы: http://192.168.100.1:4646/ui и http://192.168.100.1:8500/ui через WireGuard. Окружения в интерфейсе разделены переключателем namespace.

Проверка статуса развёртывания

Используйте Nomad CLI для проверки статуса работающего задания в любом окружении:

export NOMAD_ADDR=http://192.168.100.1:4646
export NOMAD_TOKEN=<ваш токен>

# Статус джобы в нужном окружении
nomad job status -namespace=dev hub

# Аллокации
nomad job allocs -namespace=dev hub

Рабочий процесс продвижения

Код проходит через окружения по порядку:

dev → stage → main
 ↓      ↓       ↓
dev   stage    prod

1. Влейте функциональные ветки в dev. CI собирает и развёртывает в dev автоматически.
2. Когда dev проверен, влейте dev в stage. CI развёртывает в stage автоматически.
3. После одобрения QA на stage влейте stage в main. CI собирает образ, но ожидает ручного подтверждения перед развёртыванием в prod.

TIP

Вы можете отслеживать прогресс пайплайна в GitLab по адресу gitlab.amzgit.com/integrations/hub/-/pipelines.