Руководство по конфигурации Saga¶

Архитектура UnifiedConfig¶

Основные компоненты¶

backend/config/
├── unified_config.go           # Структура конфигурации с множественными секциями
├── unified_config_interface.go # ConfigInterface с 280+ методами доступа
├── unified_config_loader.go    # Система загрузки из разных источников
├── legacy_adapter.go          # Совместимость со старым кодом
└── unified_config_test.go     # Comprehensive тесты

Процесс загрузки¶

// Загрузка конфигурации в приложении
cfg, err := config.LoadUnifiedConfig()
if err != nil {
    return fmt.Errorf("ошибка загрузки конфигурации: %w", err)
}

Система автоматически:

Устанавливает значения по умолчанию
Загружает и переопределяет из config.yaml (если существует)
Переопределяет переменными окружения (если установлены)
Валидирует критические параметры

Расположение конфигурационных файлов¶

config.yaml¶

Основной файл: /config.yaml (корень проекта)
Альтернатива: backend/config.yaml (legacy поддержка)

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

Поддерживаются все параметры с префиксом соответствующих секций: - JWT_SECRET → auth.jwt_secret - DB_HOST → database.host
- HD_WALLET_XPUB → blockchain.hd_wallet.xpub

Критические параметры¶

HD Wallet конфигурация¶

Environment variables:

export HD_WALLET_XPUB="xpub..."
export HD_WALLET_MASTER_ADDRESS="0xYOUR_MASTER_ADDRESS_HERE"  # ИСПРАВЛЕНО: используйте ваш мастер адрес

config.yaml:

blockchain:
  hd_wallet:
    xpub: "your-xpub-key-here"
    master_address: ""  # ИСПРАВЛЕНО: используется переменная окружения HD_WALLET_MASTER_ADDRESS

ВНИМАНИЕ: Эти параметры критичны для генерации депозитных адресов. Неправильные значения приведут к генерации невалидных адресов!

JWT Secret¶

Environment variable:

export JWT_SECRET="dev-saga-jwt-secret-key-2025-for-local-development-only-do-not-use-in-production"

config.yaml:

auth:
  jwt_secret: "dev-saga-jwt-secret-key-2025-for-local-development-only-do-not-use-in-production"
  jwt_expiration_hours: 24

База данных¶

Environment variables:

export DB_HOST="127.0.0.1"
export DB_PORT="5432"
export DB_USER="aisee"
export DB_PASSWORD="aisee"
export DB_NAME="saga"

config.yaml:

database:
  host: "127.0.0.1"
  port: 5432
  user: "aisee"
  password: "aisee"
  dbname: "saga"
  ssl_mode: "disable"

Добавление новых параметров¶

При добавлении нового параметра:

Добавьте поле в структуру UnifiedConfig в unified_config.go
Добавьте значение по умолчанию в функцию setDefaults() в unified_config_loader.go
Добавьте getter-метод в интерфейс ConfigInterface
Добавьте тег env для поддержки переменных окружения
Добавьте параметр в config.yaml с описанием
Напишите тест в unified_config_test.go

Пример добавления нового параметра:

type APIConfig struct {
    RateLimit int `yaml:"rate_limit" env:"API_RATE_LIMIT" default:"100"`
}

Использование в коде¶

Правильное использование¶

import "github.com/saga/backend/config"

// Загрузка конфигурации
cfg, err := config.LoadUnifiedConfig()
if err != nil {
    return fmt.Errorf("ошибка загрузки конфигурации: %w", err)
}

// Доступ к параметрам через интерфейс
apiBaseURL := cfg.GetAPIBaseURL()
jwtSecret := cfg.GetJWTSecret()
hdWallet := cfg.GetHDWalletConfig()
dbDSN := cfg.GetDatabaseDSN()

// Проверка окружения
if cfg.IsProduction() {
    // Production логика
}

// Работа с сетями
network, err := cfg.GetNetworkConfig("localhost")
if err != nil {
    return fmt.Errorf("сеть не найдена: %w", err)
}

Неправильное использование¶

// НЕ ИСПОЛЬЗУЙТЕ прямые вызовы os.Getenv в production коде!
jwtSecret := os.Getenv("JWT_SECRET")  // ❌ ПЛОХО

// Используйте унифицированную систему:
jwtSecret := cfg.GetJWTSecret()      // ✅ ХОРОШО

Структура config.yaml¶

Полный пример конфигурации¶

# Основные настройки приложения
application:
  environment: development  # development, staging, production
  version: "1.8.55"
  debug: true
  data_dir: ./data

# Настройки HTTP сервера
server:
  host: 0.0.0.0
  port: 8080
  read_timeout: 30s
  write_timeout: 30s

# Настройки базы данных
database:
  host: "127.0.0.1"
  port: 5432
  user: "aisee"
  password: "aisee"
  dbname: "saga"
  ssl_mode: "disable"
  max_open_connections: 25
  max_idle_connections: 5

# Настройки аутентификации
auth:
  jwt_secret: "dev-saga-jwt-secret-key-2025-for-local-development-only-do-not-use-in-production"
  jwt_expiration_hours: 24
  allow_wallet_auth: true
  admin_permissions_enabled: true

# Настройки блокчейна
blockchain:
  default_network: localhost
  hd_wallet:
    xpub: "your-xpub-key-here"
    master_address: ""  # ИСПРАВЛЕНО: используется переменная окружения HD_WALLET_MASTER_ADDRESS
  networks:
    localhost:
      rpc_url: "http://localhost:8545"
      chain_id: 1337
      block_confirmations: 1
    saga-vps:
      rpc_url: "http://188.42.218.164:8545"
      chain_id: 1337
      block_confirmations: 1

# Настройки уведомлений
notifications:
  email:
    enabled: false
    smtp_host: ""
    smtp_port: 587
  push:
    enabled: false

# Настройки логирования
logging:
  level: info
  format: json
  output: stdout

Отладка конфигурации¶

Проверка загруженных значений¶

# Проверить основной config.yaml
cat config.yaml | grep -E "(xpub|jwt_secret|database)"

# Проверить переменные окружения
env | grep -E "(JWT_|DB_|HD_WALLET_)"

# Проверить что система запускается
make build-container

Валидация конфигурации¶

Система автоматически валидирует: - JWT секреты (минимум 32 символа) - HD Wallet XPUB и master адрес
- Порты (диапазон 1-65535) - Email адреса (если включены уведомления) - Сетевые настройки блокчейна

🆘 Решение проблем¶

"Config file not found"¶

# Создайте config.yaml из примера
cp config.example.yaml config.yaml
# или 
touch config.yaml  # Система будет использовать defaults

"Invalid xpub format"¶

Убедитесь что xpub правильный:

blockchain:
  hd_wallet:
    xpub: "your-xpub-key-here"

"JWT secret is too short"¶

JWT secret должен быть минимум 32 символа:

export JWT_SECRET="dev-saga-jwt-secret-key-2025-for-local-development-only-do-not-use-in-production"

"Database connection failed"¶

Проверьте настройки БД:

# Через переменные окружения
export DB_HOST="127.0.0.1"
export DB_USER="aisee"
export DB_PASSWORD="aisee"

# Или в config.yaml

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

Development окружение¶

В development можно хранить секреты в config.yaml для удобства.

Production окружение¶

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

export JWT_SECRET="production-secure-jwt-secret-key"
export DB_PASSWORD="secure-database-password"
export HD_WALLET_XPUB="production-hd-wallet-xpub"

Системы управления секретами¶

Для production рекомендуется: - HashiCorp Vault - Kubernetes Secrets - AWS Secrets Manager - Azure Key Vault

Проверочный чек-лист¶

config.yaml создан и настроен
Критические переменные окружения установлены
JWT secret минимум 32 символа
HD Wallet xpub и master_address корректные
База данных доступна
Все обращения к конфигурации через cfg.GetXXX() методы
Нет хардкода параметров в исходном коде

⚠️ Важно: Гибкая система конфигурации позволяет легко переключаться между окружениями и обеспечивает максимальную безопасность в production. Важно: для подключения к PostgreSQL устанавливайте DB_HOST=127.0.0.1 (а не localhost), чтобы использовать TCP и избежать попыток подключения через Unix socket /var/run/postgresql.