1F-Core (Backend)¶
ℹ️ 1F-CORE — это backend-сервис приложения Первая Форма, разработанный на платформе .NET. Сервис выполняет роль API-сервера, обрабатывая входящие запросы от клиентских приложений и взаимодействуя с базой данных
Помимо основной работы с API, при установке флага CORE_IS_JOB_SERVER=true приложение выполняет функции job-сервера — запускает и обрабатывает фоновые служебные задачи (например, планировщики, обработчики очередей и интеграционные процессы).
Запуск в Docker Compose¶
Запуск в K8s¶
Конфигурация¶
Основной файл конфигурации: appsettings.json.
Возможные способы загрузки конфигурации:
-
через переменные окружения (ENV) > генерируется финальный JSON-конфиг из шаблона;
-
либо подключить статичный appsettings.json как volume.
Если нужно изменить путь к шаблону, используется переменная окружения:
CORE_CONFIG_TEMPLATE
Передача переменных окружения через файл¶
Любая переменная окружения, используемая сервисом, может быть передана в контейнер через файл. Это позволяет безопасно хранить и передавать секреты (пароли, ключи и т.д.), не указывая их напрямую в переменных окружения.
Механизм работы:
1. Создайте файл с нужным значением переменной. Например:
echo "SuperSecretPassword" > /secrets/db_password
2. Подключите файл в контейнер через volume:
docker run -v /secrets/db_password:/run/secrets/db_password ...
3. Передайте путь к файлу в переменной окружения с суффиксом _FILE: Например, для переменной CORE_DB_PASSWORD:
CORE_DB_PASSWORD_FILE=/run/secrets/db_password
При старте контейнера сервис определит, что для переменной CORE_DB_PASSWORD задана версия с суффиксом _FILE, прочитает содержимое указанного файла и присвоит его значением переменной CORE_DB_PASSWORD.
Преимущества:
-
Повышенная безопасность — секреты не попадают в историю команд или логи.
-
Удобная интеграция с Docker Secrets, Kubernetes Secrets и другими системами управления секретами.
Описание переменных окружения¶
Параметры подключения к основной базе данных — тип СУБД, адрес сервера, порт, имя базы, учётные данные и настройки безопасности соединения.
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| CORE_DB_TYPE | Тип базы данных (СУБД) для основного хранилища данных | mssql / postgresql | nil |
| CORE_DB_SERVER | Адрес или имя сервера базы данных | string | nil |
| CORE_DB_PORT | Порт для подключения к БД (актуально для PostgreSQL) | int | 5432 |
| CORE_DB_NAME | Имя базы данных | string | d10task |
| CORE_DB_USER | Имя пользователя базы данных | string | d10taskuser |
| CORE_DB_PASSWORD | Пароль пользователя БД | string | nil |
| CORE_DB_TRUST_SERVER_CERTIFICATE | Доверять сертификату сервера БД (например, самоподписанному SSL-сертификату) | true / false | true |
| CORE_DB_PACKET_SIZE | Размер пакета (байт) для подключения к БД | int | 4096 |
| CORE_DB_ENCRYPT | Использовать ли шифрование SSL при подключении к БД | true / false | false |
Параметры подключения для системы очередей сообщений Rebus
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| REBUS_DB_SERVER | Сервер базы данных для хранилища очередей Rebus. По умолчанию используется тот же, что и основной (CORE_DB_SERVER) | string | CORE_DB_SERVER |
| REBUS_DB_PORT | Порт БД для Rebus. По умолчанию соответствует CORE_DB_PORT | int | CORE_DB_PORT |
| REBUS_DB_NAME | Имя базы данных для сообщений Rebus. По умолчанию совпадает с CORE_DB_NAME | string | CORE_DB_NAME |
| REBUS_DB_USER | Имя пользователя БД для Rebus. Для MSSQL по умолчанию используется CORE_DB_USER, для PostgreSQL — пользователь rebus | string | mssql/CORE_DB_USER; postgresql/rebus |
| REBUS_DB_PASSWORD | Пароль пользователя БД для Rebus | string | nil |
| REBUS_DB_TRUST_SERVER_CERTIFICATE | Доверять сертификату сервера БД для Rebus (аналогично CORE_DB_TRUST_SERVER_CERTIFICATE) | true / false | true |
| REBUS_DB_PACKET_SIZE | Размер пакета при подключении к БД для Rebus | int | 4096 |
| REBUS_LOGGER_TYPE | Тип логгера для системы очередей Rebus | Возможные значения: None (нет логирования), Console, NLog | None |
| REBUS_LOG_LEVEL | Уровень детализации логирования Rebus. Возможные значения: None, Debug, Info, Warn, Error (уровни накопительны) | None / Debug / Info / Warn / Error | None |
| REBUS_MESSAGE_BUS | Провайдер шины сообщений (MessageBus) для обмена между сервисами | Возможные значения: RebusSQL, RebusPostgre, Redis, None. По умолчанию выбирается на основе типа БД: MSSQL → RebusSQL, PostgreSQL → RebusPostgre. | mssql/RebusSQL; postgresql/RebusPostgre |
Настройки отдельного соединения с БД для SMART-запросов — аналитические и тестовые запросы через выделенного read-only пользователя.
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| CORE_ENABLE_SMART_CONNECTION_STRING | Флаг разрешения выполнения SMART-выражений (отдельного соединения для SMART‑тестов и TSQL) | true / false | false |
| SMART_DB_USER | Имя пользователя БД для выполнения SMART-выражений (например, read-only пользователь) | string | d10taskreader |
| SMART_DB_PASSWORD | Пароль пользователя БД для SMART-выражений | string | nil |
Параметры подключения к Redis-серверу
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| CORE_SIGNAL_REDIS_CONNECTION_STRING | Строка подключения к Redis (например, {redis_host}:{redis_port},Password={redis_pass}). Используется для интеграции (SignalR и др.) | string | nil |
Общие параметры конфигурации приложения — режимы работы сервера, сетевые порты, уникальный идентификатор экземпляра и разрешённые хосты.
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| CORE_APPLICATION_INSTANCE_ID | Идентификатор экземпляра приложения (название очереди сообщений). Должен быть уникальным для каждой установки; может содержать буквы, цифры и '_' (без дефиса) | string | 1f_core |
| CORE_IS_MAIN_SERVER | Флаг главного сервера. Если на кластере не указан явный сервер задач (CORE_IS_JOB_SERVER=true), то периодические задания будут выполняться на том экземпляре, у которого CORE_IS_MAIN_SERVER=true | true / false | false |
| CORE_IS_JOB_SERVER | Флаг сервера задач (Job Server). При значении true данный экземпляр запускает задачи по расписанию (по таймеру) | true / false | false |
| CORE_ISOLATION_LEVEL | Уровень изоляции транзакций приложения (IsolationLevel) | Возможные значения: 0=Serializable, 1=RepeatableRead, 2=ReadCommitted (значение по умолчанию, является рекомендуемым), 3=ReadUncommitted, 4=Snapshot, 5=Chaos, 6=Unspecified | 2 |
| CORE_HTTP_PORT | Порт для HTTP (небезопасного) доступа к сервису | int | 8000 |
| CORE_HTTPS_PORT | Порт для HTTPS доступа к сервису. Если не указан, HTTPS отключен | int | nil |
| CORE_ALLOWED_HOSTS | Список разрешенных имен хостов для приложения. Несколько имен указываются через ";". Символ "*" обозначает разрешение всех хостов | string | * |
Настройки аутентификации и авторизации — параметры токенов (сроки жизни, обновление), интеграция с LDAP, SAML, OpenID Connect, мультифакторная аутентификация и прочее.
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| CORE_AUTH_TOKEN_LOGIN_URL | URL страницы входа для токен-авторизации (SPA). Используется для перенаправления на страницу логина. | string (URL) | ~/spa/entry/signin |
| CORE_AUTH_TOKEN_REFRESH_STRATEGY | Стратегия обновления токенов аутентификации. Возможные значения: SlidingExpiration (автообновление при активности), None (без обновления, требуется повторный вход), RefreshToken (используются refresh-токены через API) | SlidingExpiration / None / RefreshToken | None |
| CORE_AUTH_TOKEN_EXPIRES | Срок жизни access-токена в минутах. (По умолчанию \~25 часов) | int | 1500 |
| CORE_AUTH_REFRESH_TOKEN_EXPIRES | Срок жизни refresh-токена в минутах. Если не задано, используется значение по умолчанию (\~30 дней) | int | nil |
| CORE_AUTH_REFRESH_TOKEN_PERIOD | Период автоматического обновления refresh-токена в минутах | int | nil |
| CORE_AUTH_TEMP_TOKEN_EXPIRES | Время жизни временного access-токена (в минутах) с ограниченными правами, выдаваемого при смене пароля | int | nil |
| CORE_AUTH_ALIGNED_RESPONSE_TIME | Минимальное время (мс) выполнения аутентификации и выдачи токена. Используется для выравнивания времени ответа | int | 700 |
| CORE_SAML_ENTITY_ID | Идентификатор сущности SAML (Entity ID) — обычно доменное имя Service Provider для SAML SSO | string | nil |
| CORE_SAML_CERTIFICATES_ROOT | Путь к директории, где размещен .pfx-сертификат SAML (для подписывания запросов SP и проверки ответов IDP) | string (path) | nil |
| CORE_CONCURRENT_SESSION_MIN_LENGH | Минимальная продолжительность активной сессии (в минутах) для конкурентной лицензии. Определяет время, по истечении которого освобождается лицензия при неактивности пользователя | int | nil |
| CORE_LDAP_SEARCH_BASE | Базовый DN для LDAP-поиска пользователей (LDAP Search Base) | string | nil |
| CORE_LDAP_SECURE | Использовать SSL (LDAPS) при аутентификации через LDAP. (По умолчанию true, актуально для режима LDAP) | true / false | nil |
| CORE_WIN_AUTH_HOST | Включение интегрированной Windows-аутентификации. Укажите значение IIS для использования Windows Auth под IIS, либо disabled для отключения | IIS / disabled | disabled |
| CORE_OIDC_ALIASES | Алиасы OpenID Connect провайдеров (если используется несколько). Значения перечисляются через запятую | string | nil |
| CORE_MULTIFACTOR_IS_ENABLED | Включение двухфакторной аутентификации (системы MULTIFACTOR) | true / false | false |
| CORE_MULTIFACTOR_HOST | Адрес хоста, для которого должен быть активирован MULTIFACTOR (двухфакторный провайдер) | string (URL) | nil |
Ключи для интеграции с сервером редактирования документов
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| R7_SECRET_KEY | Секретный ключ для интеграции с сервером редактирования документов (R7 Office Docs). Используется для подписи JWT; минимальная длина — 16 символов | string | nil |
Настройки механизма TUS (resumable upload) — предварительная загрузка файлов, параметры хранилища (S3 или локальное) и время жизни загруженных файлов.
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| CORE_TUS_PREUPLOAD_ENABLED | Определяет, включен ли механизм предварительной загрузки файлов (Tus pre-upload) | true / false | false |
| CORE_TUS_PREUPLOAD_ENPOINT | URI конечной точки для запроса предварительной загрузки | string | /files/tus/preupload |
| CORE_TUS_FILE_EXPIRATION_IN_HOURS | Время жизни загруженных файлов (preupload) в часах. По истечении этого времени файлы будут удалены плановой задачей. (Если не задано, файлы не удаляются автоматически) | int | 24 |
| CORE_TUS_STORE_TYPE | Тип хранилища для загрузки файлов через TUS. Возможные варианты: локальное хранилище или S3-совместимое | Local / S3 | nil |
S3-хранилище (TUS)
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| CORE_TUS_S3_BUCKET_NAME | Имя bucket'а в S3, в который будут сохраняться файлы | string | nil |
| CORE_TUS_S3_REGION | Регион S3-хранилища | string | us-east-1 |
| CORE_TUS_S3_ENDPOINT | URL конечной точки S3 (например, для MinIO) | string | nil |
| CORE_TUS_S3_FORCE_PATH_STYLE | Использовать ли Path-Style при обращении к хранилищу S3 (true - адрес вида |
true / false | true |
| CORE_TUS_S3_ACCESS_KEY | Ключ доступа (Access Key) для S3 | string | nil |
| CORE_TUS_S3_SECRET_KEY | Секретный ключ, соответствующий Access Key для S3 | string | nil |
| CORE_TUS_S3_PREFERRED_PART_SIZE_IN_BYTES | Рекомендуемый размер части при разбивке загружаемого файла (байт) | int | 5242880 |
Локальное хранилище (TUS)
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| CORE_TUS_LOCAL_PATH | Локальный путь для хранения загружаемых файлов (при использовании Local-хранилища) | string (path) | tmp/tus |
Параметры системы телеметрии — трассировка, метрики, OpenTelemetry endpoint.
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| CORE_TELEMETRY_ENABLE_TRACING | Включить сбор трасс (distributed tracing) для приложения | true / false | false |
| CORE_TELEMETRY_ENABLE_METRICS | Включить сбор метрик для приложения | true / false | false |
| CORE_TELEMETRY_OTLP_ENDPOINT | Endpoint для отправки телеметрии (traces/metrics/logs) в формате OpenTelemetry. | string (URL) | http://localhost:4317 |
Прочие ключи конфигурации приложения — режимы работы, лимиты, включение/отключение функций и специфические параметры.
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| CORE_CODE_MIGRATIONS_IS_ENABLED | Включение автоматического применения миграций кода при запуске. (true — выполнять миграции, false — не выполнять) | true / false | true |
| CORE_MAX_REQUEST_LENGTH | Максимальный размер HTTP-запроса (например, загружаемого файла) в байтах | int | 30000000 |
| CORE_IS_DEVELOPMENT_MODE | Режим разработки приложения. При true некоторые функции (например, миграции кода) отключаются для упрощения разработки | true / false | false |
| CORE_USE_404_LOGGER | Логирование ошибок 404 (Not Found) в журнале | true / false | false |
| CORE_DISABLE_AQB | Отключение компонента AspQueryBuilder (построителя запросов) | true / false | false |
| CORE_FILES_CACHE_SIZE | Максимальный объём кеша, выделенного для файлов (в мегабайтах) | int (MB) | 1500 |
| CORE_IS_HTTP2_SUPPORTED | Включить поддержку протокола HTTP/2 для хоста приложения | true / false | true |
| CORE_AUTH_USE_INSECURE_COOKIES | Разрешить использование небезопасных (без Secure-флага) cookies для токенов аутентификации. Не рекомендуется включать (true) вне среды с чистым HTTP | true / false | nil |
| CORE_IGNORE_DOMAIN_CHECK | Отключить проверку доменного имени (игнорировать ограничение AllowedHosts и позволять подключение с любого домена) | true / false | nil |
| CORE_AD_AUTHENTICATION_MODE | Режим аутентификации через Active Directory | DirectoryServices / PrincipalContext / ldap | ldap |
| CORE_CREATE_TASKS_FOR_APPOINTMENTS | Создавать ли задачи в календаре для встреч (Appointments), синхронизированных из Exchange. (true — создавать задачу, false — не создавать) | true / false | nil |
| CORE_DECODE_EDS_SIGNATURES | Проверять цифровую подпись (ЭЦП) загруженных документов. (true — проводить валидацию ЭЦП) | true / false | nil |
| CORE_DISABLE_SQL_SHELL | Отключить возможность выполнения произвольных SQL-запросов через интерфейс администрирования ("SQL Shell") | true / false | nil |
| CORE_DISABLE_ALL_CACHES_UPDATE | Отключить автоматическое обновление всех кешей после импорта конфигурации | true / false | nil |
| CORE_DONT_USE_GET_MACHINE_IP_FOR_LOG | Не записывать IP-адрес сервера (машины) в логи приложения | true / false | nil |
| CORE_ENABLE_REMOVAL_OF_UNUSED_FILES | Включить запуск задач удаления неиспользуемых файлов. При значении true, планировщик будет периодически удалять устаревшие файлы | true / false | nil |
| CORE_EXCLUDE_AD_SUBDOMAINS | Список поддоменов, исключаемых при интеграции с AD (например, при построении дерева доменов или при поиске). Поддомены указываются через запятую | string | nil |
| CORE_EXCHANGE_TRACE_LISTENER_FLAGS | Флаги трассировки Exchange (TraceFlags) для сбора логов Exchange-синхронизации. Если не заданы, подробные логи Exchange не собираются | flags (int) | nil |
| CORE_FILES_EXTENSIONS_TO_NOT_CACHE | Список расширений файлов, которые не нужно кэшировать (перечисляются через запятую) | string | nil |
| CORE_LICENSE_KEY | Лицензионный ключ приложения (принудительная установка лицензии) | string | nil |
| CORE_INVALIDATE_USERS_CACHE_BY_EVENT | Включить сброс (инвалидацию) кэша пользователей по событию от мастер-сервера. (Не рекомендуется использовать без необходимости) | true / false | nil |
| CORE_IS_CACHING_DISABLED | Отключить все механизмы кэширования в приложении | true / false | nil |
| CORE_IS_EXCHANGE_SYNC_SERVER | Пометить этот экземпляр как сервер синхронизации с Exchange. При true именно этот сервис устанавливает соединение с Exchange и обрабатывает уведомления о событиях | true / false | nil |
| CORE_MULTIPART_BODY_LENGTH_LIMIT | Максимальный размер каждой части multipart-запроса (например, при загрузке нескольких файлов) в байтах. (По умолчанию \~134 217 728 байт ≈ 128 МБ) | int | nil |
| CORE_OPEN_LDAP_PROTOCOL_VERSION | Версия LDAP-протокола для подключения к OpenLDAP. Если не указано, по умолчанию используется версия 3 | int | nil |
| CORE_PHONE_PROFILE_LOCATION | Идентификатор телефонной локации (для телефонии). Параметр используется у клиентов с несколькими контурами (инстансами) системы | string | nil |
| CORE_PROVIDER_TYPE | Тип провайдера аутентификации по умолчанию. Например, SAML (для включения SAML-SSO) или другой поддерживаемый тип | string | nil |
| CORE_REMOVAL_OF_UNUSED_FILES_BATCH_COUNT | Ограничение на число файлов, обрабатываемых за один запуск задачи удаления неиспользуемых файлов. Позволяет ограничить длительность самой долгой задачи (RemovePreparedFileStorageFilesJob) | int | nil |
| CORE_RESTRICT_ABSENCE_MESSAGE_FOR_ALL | Ограничить автоматическое сообщение об отсутствии (Out of Office) для всех пользователей | true / false | nil |
| CORE_SET_COOKIE_FOR_UPPER_LEVEL_DOMAIN | Определяет домен для cookie аутентификации. Если true, cookie 1FormaAuth будет устанавливаться на домен верхнего уровня; если false — на полный домен хоста | true / false | false |
| CORE_USE_CLASSIC_ENCODE_IN_COMMENTS | Использовать классический метод кодирования символов в комментариях | true / false | nil |
| CORE_USE_DEV_EXPRESS_DOC_TO_PDF_CONVERTER | Использовать библиотеку DevExpress для конвертации документов DOC в PDF (иначе используется встроенный или альтернативный механизм) | true / false | nil |
| CORE_USE_EXCHANGE_AUTODISCOVER | Использовать функцию Autodiscover для подключения к Exchange Server | true / false | nil |
| CORE_USE_HACKS_FOR_MAIL_SENDING | Включить специальные обработки ("хаки") при отправке писем (например, автоопределение необходимости кодирования темы письма) | true / false | nil |
| CORE_USE_TRANSACTION_ON_TASK_SYNCHRONIZATION | Использовать транзакцию при синхронизации задач (объединять операции синхронизации в транзакцию) | true / false | nil |
| CORE_USE_SPA_PORTALS | Включить использование новых SPA-порталов в старом фронтенде. (True — подключает механизм новых порталов) | true / false | nil |
| CORE_WIN_TO_FORMS_REDIRECT_FORMS_URL | Базовый URL веб-приложения (Forms) для перенаправления с Windows-приложения (thick client) | string (URL) | nil |
| CORE_WIN_TO_FORMS_REDIRECT_WIN_URL | Базовый URL Windows-приложения для перенаправления с веб-приложения (Forms) | string (URL) | nil |
| CORE_FORWARDED_HEADERS | Позволяет ASP.NET правильно формировать URL перенаправления с учетом схемы (HTTPS), с которой пользователь пришел на сайт. Если ключ отсутствует, ASP.NET не применяет заголовки к запросу, и хост остается видимым приложению "как есть". Доступные значения: , * — Обозначает обработку всех заголовков. Рекомендуется использовать его с осторожностью. , None — Отключает обработку любых заголовков. application будет игнорировать все заголовки, переданные через прокси. , For — Включает обработку заголовка X-Forwarded-For, который содержит IP-адрес отправившего запрос. , Host — Включает обработку заголовка Host, который указывает доменное имя, к которому был отправлен запрос. , Proto — Включает обработку заголовка X-Forwarded-Proto, который указывает протокол (HTTP или HTTPS), используемый для первоначального запроса. , Prefix — Включает обработку заголовков, начинающихся с префикса X-Forwarded-. Это может включать такие заголовки, как X-Forwarded-For, X-Forwarded-Proto и другие. Несколько значений могут быть перечислены через запятую. Пример значения: CORE_FORWARDED_HEADERS=For,Proto,Host,Prefix | string | nil |
Произвольные пользовательские ключи — напрямую добавляются в appsettings.json без изменения шаблона.
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| CORE_CUSTOM_KEYS | Произвольные дополнительные ключи для appsettings.json (строка в формате JSON, которая будет встроена в конфигурацию) | string (JSON) | nil |