flea/CONFIGURATION.md

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

Этот документ описывает, как настроить микросервисную систему NOCR для различных сценариев развертывания.

Содержание

1. Обзор системы конфигурации
2. Сценарии развертывания
   • Локальная разработка (VS Code)
   • Docker Compose
   • Kubernetes
3. Приоритет конфигурации
4. Настройки для конкретных сервисов
5. Режим отладки
6. Устранение неполадок

---

Обзор системы конфигурации

Система использует многоуровневый подход конфигурации ASP.NET Core со следующими источниками (от низшего к высшему приоритету):

1. appsettings.json - Базовая конфигурация (коммитится в git)
2. appsettings.{Environment}.json - Настройки для конкретного окружения (некоторые коммитятся, некоторые нет)
3. User Secrets - Секреты только для разработки (хранятся локально, не в git)
4. Переменные окружения - Наивысший приоритет (переопределяют всё)

Важные примечания

• Никогда не коммитьте секреты в git
• Используйте файлы .example как шаблоны
• Переменные окружения всегда имеют наивысший приоритет
• Каждый сервис имеет свои требования к конфигурации

---

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

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

Для отладки отдельных сервисов в VS Code:

Шаг 1: Создание конфигурации для окружения

Для каждого сервиса, который вы хотите запустить, создайте appsettings.Development.json из примера:

# Telegram Listener
cd telegram-listener/src/Nocr.TelegramListener.Host
cp appsettings.Development.json.example appsettings.Development.json

# Text Matcher
cd text-matcher/src/Nocr.TextMatcher.Host
cp appsettings.Development.json.example appsettings.Development.json

# Users
cd users/src/Nocr.Users.Host
cp appsettings.Development.json.example appsettings.Development.json

# Telegram Client
cd telegram-client/src/Nocr.TelegramClient.Host
cp appsettings.Development.json.example appsettings.Development.json

Шаг 2: Заполните ваши значения

Отредактируйте каждый файл appsettings.Development.json и замените placeholder-значения на ваши реальные учетные данные.

Пример для Telegram Listener:

{
  "RebusRabbitMqOptions": {
    "ConnectionString": "amqp://admin:admin@localhost:5672/"
  },
  "WTelegramClientOptions": {
    "ApiId": "22101230",
    "ApiHash": "c72f884d8eb84cb7134a14362bff060b",
    "PhoneNumber": "79167310711"
  }
}

Шаг 3: Альтернатива - использование переменных окружения

Вместо создания appsettings.Development.json, вы можете использовать переменные окружения в .vscode/launch.json:

{
  "name": "Запуск сервиса",
  "type": "coreclr",
  "request": "launch",
  "env": {
    "ASPNETCORE_ENVIRONMENT": "Development",
    "RebusRabbitMqOptions__ConnectionString": "amqp://admin:admin@localhost:5672/",
    "WTelegramClientOptions__ApiId": "22101230",
    "WTelegramClientOptions__ApiHash": "c72f884d8eb84cb7134a14362bff060b",
    "WTelegramClientOptions__PhoneNumber": "79167310711"
  }
}

Примечание: Используйте двойное подчеркивание __ для представления вложенных секций конфигурации в переменных окружения.

Шаг 4: Запуск инфраструктуры

Вам нужны работающие RabbitMQ и базы данных:

# Запустить только инфраструктурные сервисы
docker-compose up nocr-rabbitmq nocr-text-matcher-db nocr-users-db -d

Шаг 5: Отладка в VS Code

Нажмите F5 или используйте панель Run and Debug для запуска вашего сервиса.

---

Docker Compose

Для запуска всей системы локально с Docker:

Шаг 1: Создание файла .nocr.env

cd /путь/к/корню/проекта
cp .nocr.env.example .nocr.env

Шаг 2: Редактирование .nocr.env

Откройте .nocr.env и заполните ваши реальные учетные данные:

# Telegram Listener - получить на https://my.telegram.org/apps
WTelegramClientOptions__ApiId=22101230
WTelegramClientOptions__ApiHash=c72f884d8eb84cb7134a14362bff060b
WTelegramClientOptions__PhoneNumber=79167310711

# Telegram Client Bot - получить у @BotFather
TelegramBotOptions__Token=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

# Опционально: включить отладочное логирование
# NOCR_DEBUG_MODE=true

Шаг 3: Создание конфигурационных файлов для DockerCompose

Каждому сервису нужен appsettings.DockerCompose.json:

# Для каждого сервиса
cd telegram-listener/src/Nocr.TelegramListener.Host
cp appsettings.DockerCompose.json.example appsettings.DockerCompose.json

cd text-matcher/src/Nocr.TextMatcher.Host
cp appsettings.DockerCompose.json.example appsettings.DockerCompose.json

cd users/src/Nocr.Users.Host
cp appsettings.DockerCompose.json.example appsettings.DockerCompose.json

cd telegram-client/src/Nocr.TelegramClient.Host
cp appsettings.DockerCompose.json.example appsettings.DockerCompose.json

Примечание: Эти файлы содержат имена хостов Docker-сети (например, nocr-rabbitmq:5672 вместо localhost:5672).

Шаг 4: Запуск всех сервисов

docker-compose up

Или со сборкой:

docker-compose up --build

Шаг 5: Проверка работоспособности сервисов

• Telegram Listener: http://localhost:5040/health
• Text Matcher: http://localhost:5041/health
• Users: http://localhost:5042/health
• Telegram Client: http://localhost:5050/health
• RabbitMQ Management: http://localhost:15672 (admin/admin)

---

Kubernetes

Для production-развертывания на Kubernetes:

Шаг 1: Создание Kubernetes Secrets

НЕ используйте файл .nocr.env в K8s. Вместо этого создайте Secrets:

# Создать namespace
kubectl create namespace nocr

# Создать secrets для Telegram Listener
kubectl create secret generic telegram-listener-secrets \
  --from-literal=WTelegramClientOptions__ApiId=22101230 \
  --from-literal=WTelegramClientOptions__ApiHash=c72f884d8eb84cb7134a14362bff060b \
  --from-literal=WTelegramClientOptions__PhoneNumber=79167310711 \
  -n nocr

# Создать secrets для Telegram Client
kubectl create secret generic telegram-client-secrets \
  --from-literal=TelegramBotOptions__Token=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz \
  -n nocr

Шаг 2: Ссылка на Secrets в Deployment

Пример манифеста Kubernetes deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: telegram-listener
  namespace: nocr
spec:
  template:
    spec:
      containers:
      - name: telegram-listener
        image: nocr-telegram-listener:latest
        env:
        - name: ASPNETCORE_ENVIRONMENT
          value: "Production"
        envFrom:
        - secretRef:
            name: telegram-listener-secrets

Шаг 3: Создание appsettings.Production.json

Создайте production-конфигурационные файлы с именами сервисов K8s:

{
  "RebusRabbitMqOptions": {
    "ConnectionString": "amqp://admin:admin@rabbitmq-service:5672/"
  }
}

Примечание: Секреты из переменных окружения переопределят эти значения.

Шаг 4: Деплой

kubectl apply -f deployment/

---

Приоритет конфигурации

Понимание приоритета критически важно при устранении проблем с конфигурацией.

Порядок приоритета (от низшего к высшему)

1. ⬇️ appsettings.json (базовый)
2. ⬆️ appsettings.{Environment}.json (например, Development, DockerCompose, Production)
3. ⬆️ User Secrets (только Development)
4. ⬆️⬆️ Переменные окружения (ВСЕГДА ВЫИГРЫВАЮТ)

Пример сценария

Если у вас есть:

• appsettings.json: "ConnectionString": ""
• appsettings.DockerCompose.json: "ConnectionString": "amqp://admin:admin@nocr-rabbitmq:5672/"
• Переменная окружения: RebusRabbitMqOptions__ConnectionString=amqp://admin:admin@localhost:5672/

Результат: Переменная окружения побеждает! Подключение будет использовать localhost:5672.

Именно поэтому мы удалили appsettings.protected.json - он неправильно переопределял настройки Docker Compose.

---

Настройки для конкретных сервисов

Telegram Listener

Обязательная конфигурация:

{
  "RebusRabbitMqOptions": {
    "ConnectionString": "amqp://user:pass@host:port/"
  },
  "WTelegramClientOptions": {
    "ApiId": "YOUR_API_ID",
    "ApiHash": "YOUR_API_HASH",
    "PhoneNumber": "YOUR_PHONE_NUMBER"
  }
}

Как получить учетные данные Telegram:

1. Посетите https://my.telegram.org/apps
2. Войдите с вашим номером телефона
3. Создайте новое приложение
4. Скопируйте api_id и api_hash

---

Text Matcher

Обязательная конфигурация:

{
  "ConnectionStrings": {
    "TextMatcherContext": "server=host;port=3306;database=nocr_text_matcher;uid=root;pwd=password"
  },
  "RebusRabbitMqOptions": {
    "ConnectionString": "amqp://user:pass@host:port/"
  }
}

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

• Development: localhost:3316
• Docker Compose: nocr-text-matcher-db:3306
• Kubernetes: text-matcher-db-service:3306

---

Users

Обязательная конфигурация:

{
  "ConnectionStrings": {
    "UsersContext": "server=host;port=3306;database=nocr_users;uid=root;pwd=password"
  }
}

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

• Development: localhost:3326
• Docker Compose: nocr-users-db:3306
• Kubernetes: users-db-service:3306

---

Telegram Client

Обязательная конфигурация:

{
  "RebusRabbitMqOptions": {
    "ConnectionString": "amqp://user:pass@host:port/"
  },
  "UsersRestEaseOptions": {
    "BasePath": "http://users-service:8080"
  },
  "TextMatcherRestEaseOptions": {
    "BasePath": "http://text-matcher-service:8080"
  },
  "TelegramBotOptions": {
    "Token": "YOUR_BOT_TOKEN"
  }
}

Как получить Bot Token:

1. Откройте Telegram и найдите @BotFather
2. Отправьте команду /newbot
3. Следуйте инструкциям для создания вашего бота
4. Скопируйте предоставленный токен

---

Режим отладки

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

Как включить

Установите переменную окружения:

export NOCR_DEBUG_MODE=true

Или в .nocr.env:

NOCR_DEBUG_MODE=true

Или в docker-compose.yml:

environment:
  NOCR_DEBUG_MODE: "true"

Пример вывода

Когда режим отладки включен, вы увидите маскированную конфигурацию при запуске:

=== [NOCR_DEBUG] Значения конфигурации ===
[NOCR_DEBUG] RebusRabbitMqOptions:
[NOCR_DEBUG]   ConnectionString: amqp://admin:***@nocr-rabbitmq:5672/
[NOCR_DEBUG]   InputQueueName: nocr.telegram.listener.queue
[NOCR_DEBUG]   DirectExchangeName: nocr.direct
[NOCR_DEBUG]   TopicsExchangeName: nocr.topics
[NOCR_DEBUG] WTelegramClientOptions:
[NOCR_DEBUG]   ApiId: 22101230
[NOCR_DEBUG]   ApiHash: c7...0b
[NOCR_DEBUG]   PhoneNumber: 79...11
=== [NOCR_DEBUG] Конец конфигурации ===

Безопасность: Пароли и секреты автоматически маскируются для защиты конфиденциальных данных.

---

Устранение неполадок

Проблема: Сервис не может подключиться к RabbitMQ

Симптомы:

Connection refused to nocr-rabbitmq:5672

Решение:

1. Проверьте, работает ли RabbitMQ: docker-compose ps nocr-rabbitmq
2. Включите режим отладки: NOCR_DEBUG_MODE=true
3. Проверьте ConnectionString в выводе отладки
4. Для Docker Compose убедитесь, что hostname - nocr-rabbitmq:5672, НЕ localhost:5672
5. Проверьте, не переопределяет ли переменная окружения appsettings

---

Проблема: Сервис не может подключиться к базе данных

Симптомы:

Unable to connect to any of the specified MySQL hosts

Решение:

1. Проверьте, что база данных запущена: docker-compose ps nocr-text-matcher-db
2. Включите режим отладки для просмотра маскированной строки подключения
3. Проверьте hostname в строке подключения:
   • Docker Compose: nocr-text-matcher-db:3306
   • Локальная разработка: localhost:3316
4. Подождите прохождения healthcheck (может занять 10-30 секунд при первом запуске)

---

Проблема: Значения конфигурации не применяются

Симптомы:

• Настройки в appsettings.Development.json игнорируются
• Сервис использует неправильную конфигурацию

Решение:

1. Проверьте, что ASPNETCORE_ENVIRONMENT установлен правильно:
   • VS Code: Development
   • Docker Compose: DockerCompose
   • K8s: Production
2. Включите режим отладки для просмотра загруженных значений
3. Проверьте переменные окружения, переопределяющие ваши настройки
4. Помните: Переменные окружения всегда выигрывают!

---

Проблема: Секреты раскрыты в логах

Решение:

• Режим отладки автоматически маскирует конфиденциальные значения
• Никогда не логируйте конфигурацию в production без маскировки
• Проверьте формат вывода отладки в Startup.cs:
  • Пароли: amqp://user:***@host
  • Секреты: ab...yz (только первые 2 + последние 2 символа)

---

Проблема: Отсутствует файл .nocr.env

Симптомы:

docker-compose up падает с ошибкой отсутствующих переменных окружения

Решение:

1. Скопируйте файл-пример: cp .nocr.env.example .nocr.env
2. Заполните ваши реальные значения
3. Убедитесь, что .nocr.env находится в корне проекта (на том же уровне, что и docker-compose.yml)

---

Краткая справка

Соглашение об именовании переменных окружения

ASP.NET Core использует двойное подчеркивание __ для представления вложенной JSON-структуры:

# JSON: { "Section": { "Key": "Value" } }
# Переменная окружения:
Section__Key=Value

# Примеры:
WTelegramClientOptions__ApiId=12345
RebusRabbitMqOptions__ConnectionString=amqp://localhost

Расположение файлов

flea/                                   # Корень проекта
├── .nocr.env                          # Ваши секреты (gitignored)
├── .nocr.env.example                  # Шаблон (коммитится)
├── docker-compose.yml                 # Ссылается на .nocr.env
│
├── telegram-listener/
│   └── src/Nocr.TelegramListener.Host/
│       ├── appsettings.json                        # Базовый (коммитится)
│       ├── appsettings.Development.json            # Локальная разработка (gitignored)
│       ├── appsettings.Development.json.example    # Шаблон (коммитится)
│       ├── appsettings.DockerCompose.json          # Docker (gitignored)
│       └── appsettings.DockerCompose.json.example  # Шаблон (коммитится)
│
└── [та же структура для text-matcher, users, telegram-client]

---

Рекомендации по безопасности

1. ✅ Никогда не коммитьте секреты - используйте файлы .example как шаблоны
2. ✅ Используйте переменные окружения для конфиденциальных данных в production
3. ✅ Используйте K8s Secrets для развертывания в Kubernetes
4. ✅ Включайте режим отладки только при устранении неполадок
5. ✅ Ротируйте учетные данные регулярно
6. ✅ Используйте User Secrets для локальной разработки (опционально)
7. ❌ Не коммитьте .nocr.env или appsettings.*.json (кроме файлов .example)
8. ❌ Не используйте appsettings.protected.json (удален из кода)

---

Дополнительные ресурсы

• Документация конфигурации ASP.NET Core
• Переменные окружения Docker Compose
• Kubernetes Secrets
• Документация Telegram API
• Telegram Bot API