miHAN Chat API backend
FastAPI-сервис публичного API, internal Open Lines/settings API, WebSocket realtime, Message Safety orchestration, S3 lifecycle и PostgreSQL workers.
Запуск
Python 3.12+:
python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"
alembic upgrade head
uvicorn app.main:app --host 0.0.0.0 --port 8000
Миграции выполняются отдельным deployment step. Приложение не применяет DDL при старте.
Workers запускаются независимо:
han-delivery-worker
han-safety-worker
han-cleanup-worker
Переменные окружения
Сервис читает только инфраструктурные параметры и секреты из корневого backend/.env.
Локальный .env не коммитится. Business settings создаются миграцией в
han_app.app_settings.
Обязательны:
APP_ENV,API_PORT,LOG_LEVEL,DATABASE_URL;REDIS_URL,REDIS_REALTIME_URL;KEYCLOAK_PUBLIC_URL,KEYCLOAK_INTERNAL_URL,KEYCLOAK_REALM,KEYCLOAK_AUDIENCE;MESSAGE_SAFETY_URL,MESSAGE_SAFETY_SERVICE_TOKEN,MESSAGE_SAFETY_POST_TIMEOUT_SEC,MESSAGE_SAFETY_TASK_POLL_INTERVAL_SEC,MESSAGE_SAFETY_TASK_POLL_MAX_SEC,MESSAGE_SAFETY_CIRCUIT_FAILURE_THRESHOLD,MESSAGE_SAFETY_CIRCUIT_OPEN_SEC;BITRIX_LOCAL_APP_BASE_URL,BITRIX_LOCAL_APP_INTERNAL_TOKEN,BITRIX_API_INBOX_TOKEN,BITRIX_LOCAL_APP_HTTP_TIMEOUT_SEC,BITRIX_LOCAL_APP_CIRCUIT_FAILURE_THRESHOLD,BITRIX_LOCAL_APP_CIRCUIT_OPEN_SEC;KEYCLOAK_SETTINGS_BRIDGE_TOKEN;SELECTEL_S3_ENDPOINT_URL,SELECTEL_S3_BUCKET_DOCUMENTS,SELECTEL_S3_BUCKET_ATTACHMENTS,SELECTEL_S3_BUCKET_QUARANTINE,SELECTEL_S3_ACCESS_KEY,SELECTEL_S3_SECRET_KEY;CURSOR_HMAC_SECRET— случайный секрет не короче 32 байт;OTEL_EXPORTER_OTLP_ENDPOINT— опциональный endpoint collector.
Токены генерируются openssl rand -hex 32. S3 read-only credentials Message Safety
не передаются этому контейнеру. В production подключение PostgreSQL должно использовать
TLS, а internal endpoints — быть доступны только из backend-сети.
Проверки
ruff check .
ruff format --check .
mypy app
pytest
/health/live проверяет процесс. /health/ready проверяет критические зависимости и
возвращает 503, если сервис не может безопасно обслуживать protected API.