Конфигурация (env)¶

Всё настраивается через переменные окружения. Эталонный пример — backend/.env.example.

Никогда не коммитьте секреты

backend/.env, корневой .env и backend.env — все в gitignore. Добавляя переменную, задокументируйте её в README — но никогда не её значение.

Основное¶

Переменная	Пример	Назначение
`PORT`	`8080`	Порт, который слушает API
`ENVIRONMENT`	`production`	Включает строгие продакшен-проверки
`DEBUG`	`false`	Подробное логирование
`ALLOWED_ORIGINS`	`https://open.gerege.mn`	Список разрешённых origin для CORS (через запятую; `*` запрещён)
`TRUSTED_PROXIES`	—	Адреса обратных прокси

База данных и Redis¶

Переменная	Назначение
`DB_POSTGRE_DSN` / `DB_POSTGRE_URL`	Строка подключения
`DB_MAX_OPEN_CONNS`, `DB_MAX_IDLE_CONNS`, `DB_CONN_MAX_LIFE_MINS`	Настройка пула
`REDIS_HOST`, `REDIS_PASS`, `REDIS_EXPIRED`	Подключение к Redis и TTL

В продакшене DSN должен использовать sslmode=verify-full

Этого требует продакшен-проверка. Стек Docker Compose намеренно работает с ENVIRONMENT=development, потому что у его внутренней базы нет TLS.

API не должен подключаться суперпользователем

RLS работает только тогда, когда приложение подключается ролью с минимальными правами. Роль суперпользователя или с BYPASSRLS прерывает старт в продакшене.

JWT и сессии¶

Переменная	Назначение
`JWT_SECRET`	≥32 символов. Смена делает все сессии недействительными
`JWT_EXPIRED`, `JWT_REFRESH_EXPIRED`	Время жизни access / refresh
`JWT_ISSUER`	Обычно домен приложения. Смена делает все выданные токены недействительными

eID (доверяющая сторона)¶

Переменная	Назначение
`EID_BASE_URL`	Базовый адрес eID Mongolia `/v3` (или ретранслятор подписи SSO)
`EID_RP_UUID`, `EID_RP_SECRET`	Учётные данные RP
`SIGN_RELAY_TOKEN`	Общий токен для ретрансляции подписи (пусто — выключено)

Gerege SSO (сторона RP — приложение как клиент)¶

Переменная	Пример	Назначение
`SSO_ISSUER`	`https://sso.gerege.mn`	Значение по умолчанию, если не задано
`SSO_CLIENT_ID` / `SSO_CLIENT_SECRET`	—	Пусто — поток SSO неактивен
`SSO_REDIRECT_URI`	`https://open.gerege.mn/sso/callback`	Должен быть зарегистрирован у клиента SSO точь-в-точь
`SSO_SCOPE`	`openid profile email nationalid`	`nationalid` добавляет регистрационный номер гражданина
`SSO_NATIVE_CLIENT_ID`	—	Клиент для мобильного потока (PKCE, публичный)
`SSO_EID_PROXY_BASE_URL`	—	Если задано, интерфейс eID PKI идёт через прокси SSO

Незарегистрированный клиент возвращает invalid_client

Если SSO_CLIENT_ID отсутствует в хранилище клиентов провайдера, шаг authorize вернёт {"error":"invalid_client"}. Redirect URI также должен совпадать точно.

Сторона провайдера OIDC (приложение как провайдер)¶

Переменная	Назначение
`OAUTH_ISSUER`	Например, `https://open.gerege.mn`. Провайдер включается только при заданном значении
`SSO_STATE_KEY`	Ключ HMAC для временного состояния входа/согласия (≥32 байт)
`SSO_FIRSTPARTY_CLIENTS`	Собственные клиенты, пропускающие экран согласия
`SSO_ADMIN_API_KEYS`, `SSO_ADMIN_SUBS`	Доступ к административному API

Поверхность входа (`AUTH_MODE`)¶

Аутентифицирует ли платформа пользователей сама или перенаправляет в вышестоящий SSO — это не различие в коде: решает одна переменная.

Значение	На главной странице и `/login`
`provider`	Карточка входа (eID рег. номер/QR · Google) отображается здесь
`client`	Перенаправление в вышестоящий SSO (`SSO_ISSUER`)

AUTH_MODE=client      # эталонное развёртывание этого шаблона — доверяющая сторона SSO
AUTH_MODE=provider    # служба идентификации вроде sso.dgov.mn / sso.gerege.mn

Если оставить пустым, режим выводится из наличия SSO_CLIENT_ID — поэтому существующим развёртываниям менять ничего не нужно.

Опечатка — НЕ тихий откат

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

ОТДЕЛЬНАЯ ось от OAUTH_ISSUER

OAUTH_ISSUER отвечает на вопрос «является ли платформа issuer-ом для других приложений»; AUTH_MODE — «где входят пользователи этой платформы». Оба режима могут быть активны одновременно — цепочка.

Фронтенд получает режим из публичного GET /api/v1/site/auth (без аутентификации и без секретов), поэтому дублирующих переменных на фронтенде нет.

Языки интерфейса¶

Платформа поставляется со встроенными переводами для монгольского и шести официальных языков ООН (арабский · китайский · английский · французский · русский · испанский). Все семь работают сразу — с пустой базой данных и без какого-либо шага перевода.

Для арабского автоматически устанавливается <html dir="rtl">.

Переменная	Примечание
—	Настройка не требуется; языки приходят в таблицу `languages` как `is_builtin`

Если нужны дополнительные языки, супер-администратор добавляет их в разделе Языки и заполняет переводы через Gemini — они хранятся как overlay в БД.

Сторонние сервисы и хранилище¶

Переменная	Назначение
`GEMINI_API_KEY`	AI-конвейер. Без него `/ai/*` возвращает настоящую 500
`GOOGLE_CLIENT_ID` / `SECRET`	Привязка Google (кнопка скрыта, если пусто)
`VERIFY_API_BASE`, `VERIFY_API_KEY`, `VERIFY_CHANNEL`	Проверка граждан / организаций
`XYP_API_BASE`, `XYP_CLIENT_ID`, `XYP_CLIENT_SECRET`	Запросы к государственному реестру
`GSPACE_*`	Собственное SFTP-хранилище приложения (квота на пользователя)
`INTEGRATION_ENC_KEY`	≥16 байт. Шифрует OAuth-токены и MFA суперадмина

INTEGRATION_ENC_KEY обязателен

Развёртывания требуют этот ключ, и после установки его нельзя менять — ротация сломает все ранее зашифрованные значения.

Наблюдаемость¶

Переменная	Назначение
`OTEL_EXPORTER`, `OTEL_SAMPLE_RATIO`	Трассировка OpenTelemetry
`OBSERVABILITY_TOKEN`	Bearer-токен, закрывающий `/metrics` и `/swagger` в продакшене

Фронтенд¶

Переменная	Назначение
`BACKEND_URL`	Внутренний адрес, к которому обращается BFF (например, `http://api:8080`)

Имя api может конфликтовать в общей сети

Когда несколько стеков делят одну сеть Docker, http://api:8080 может разрешиться в другой контейнер, и каждый вызов /api/v1/* превратится в 404. В таком случае укажите в BACKEND_URL полное имя своего контейнера api.