Environments / Окружения

Обзор

В проекте используется три окружения: local, dev, prod. Каждое окружение имеет свою конфигурацию сервисов, секретов и URL.

Сравнительная таблица

Параметр	Local	Dev	Production
Cloudflare Workers	wrangler dev (локально)	integ.dev.happ.tools	integ.happ.tools
API Reference	localhost:3010/reference	integ.dev.happ.tools/reference	integ.happ.tools/reference
Docs (VitePress)	localhost:5173	—	integ.docs.happ.tools
D1 Database	Локальные файлы SQLite	Cloudflare D1	Cloudflare D1
KV Cache	Локальный KV	Cloudflare KV	Cloudflare KV
Doppler Config	local	dev	prod
Секреты	.dev.vars файлы	Cloudflare Workers Secrets	Cloudflare Workers Secrets

---

Local (Локальная разработка)

Описание

Окружение для разработки и отладки на локальной машине. Все сервисы работают локально через wrangler dev.

Компоненты

Компонент	URL / Путь	Описание
Integration Worker	http://localhost:8787	Wrangler dev server
D1 Database	data/miniflare/v3/d1/	Локальные SQLite файлы
KV Cache	data/miniflare/v3/kv/	Локальные KV файлы

Конфигурация

Doppler config: local

Файлы:

• .env — корневые переменные окружения
• integrations/<name>/.dev.vars — переменные для wrangler dev

Команды:

# Запуск интеграции
pnpm start sofa

# Запуск без генерации env из Doppler
SKIP_ENV=true pnpm start sofa

# Только генерация env файлов
pnpm generate:env -- local

---

Dev (Development)

Описание

Тестовое окружение на Cloudflare для проверки перед production. Используется для тестирования интеграций и новых фич.

Компоненты

Компонент	URL	Описание
Gateway	https://integ.dev.happ.tools	Точка входа
Integration Workers	https://integ.dev.happ.tools/sofa/*	Через Gateway
D1 Database	Cloudflare D1	Удалённая база
KV Cache	Cloudflare KV	Удалённый кэш

Конфигурация

Doppler config: dev

Wrangler env: dev

Команды:

# Деплой в dev
cd integrations/sofa
pnpm deploy:dev

# Или с корня проекта
pnpm --filter sofa deploy:dev

# Быстрый деплой без sync secrets
pnpm --filter sofa deploy:dev:fast

Роутинг

integ.dev.happ.tools/*        → integ-gateway-dev
integ.dev.happ.tools/sofa/*   → integ-sofa (env: dev)

wrangler.toml

wrangler.toml генерируется автоматически при запуске generate:env dev:

name = "integ-sofa-dev"
main = "dist/index.js"

[vars]
ENVIRONMENT = "dev"

[[d1_databases]]
binding = "INTEG_DB"
database_name = "integ-db-dev"
database_id = "<id-из-doppler>"

---

Production

Описание

Боевое окружение для реальных пользователей. Максимальная надёжность и производительность.

Компоненты

Компонент	URL	Описание
Gateway	https://integ.happ.tools	Точка входа
Integration Workers	https://integ.happ.tools/sofa/*	Через Gateway
D1 Database	Cloudflare D1	Production база
KV Cache	Cloudflare KV	Production кэш

Конфигурация

Doppler config: prod

Wrangler env: production

Команды:

# Деплой в production
cd integrations/sofa
pnpm deploy

# Или с корня проекта
pnpm --filter sofa deploy

Роутинг

integ.happ.tools/*        → integ-gateway
integ.happ.tools/sofa/*   → integ-sofa (env: production)

wrangler.toml

wrangler.toml генерируется автоматически при запуске generate:env prod:

name = "integ-sofa"
main = "dist/index.js"

[vars]
ENVIRONMENT = "production"

[[d1_databases]]
binding = "INTEG_DB"
database_name = "integ-db-prod"
database_id = "<id-из-doppler>"

---

Gateway Service Bindings

Gateway роутит запросы к Integration Workers через Service Bindings.

Важно: wrangler.toml генерируется автоматически скриптом generate:env. Service bindings создаются для всех найденных интеграций.

# workers/gateway/wrangler.toml (генерируется автоматически)

# Для local/dev/prod — binding генерируется из имени интеграции
[[services]]
binding = "SOFA"
service = "integ-sofa"        # local
# или service = "integ-sofa-dev"  # dev

Пример сгенерированного файла для local:

name = "integ-gateway"
main = "src/index.ts"

[vars]
ENVIRONMENT = "local"

[[d1_databases]]
binding = "INTEG_DB"
database_name = "integ-db"
database_id = "00000000-0000-0000-0000-000000000001"

[[services]]
binding = "SOFA"
service = "integ-sofa"

---

Health Checks

Local

curl http://localhost:8787/health

Dev

curl https://integ.dev.happ.tools/health
curl https://integ.dev.happ.tools/sofa/health

Production

curl https://integ.happ.tools/health
curl https://integ.happ.tools/sofa/health

---

CI/CD Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Local     │────>│    Dev      │────>│ Production  │
│             │     │             │     │             │
│ localhost   │     │ dev-integ   │     │ integ       │
│ :8787       │     │ .happ.tools │     │ .happ.tools │
└─────────────┘     └─────────────┘     └─────────────┘

GitHub Actions (trunk-based)

feat/* → PR → main            # push в main → deploy-dev.yml → dev-окружение
main → release.yml (vX.Y.Z)   # тег на HEAD main
vX.Y.Z → deploy-prod.yml      # guard: тег ancestor main → production

Ветки dev нет: dev — это деплой-таргет. Прод НИКОГДА не деплоится из ветки, только из тега. Подробности — CI_CD.md.

---

Связанные документы

• SECRETS.md — работа с секретами
• DEVELOPMENT.md — локальная разработка
• PRODUCTION.md — production workflow