Руководство по настройке

Введение

Хоть и стандартная конфигурация подходит в большинстве случаев, приложение на vstutils является высоко настраиваемой системой. Для расширенных настроек (масштабируемость, выделенная база данных, настраиваемый кэш, логгирование или директории) вы можете глубоко настраивать приложение, основанное на vstutils, изменяя файл настроек /etc/{{app_name or app_lib_name}}/settings.ini.

Самое важное, о чем нужно помнить при планировании архитектуры вашего приложения, это то, что приложения, основанные на vstutils, имеют сервисно-ориентированную структуру. Чтобы построить распределенную масштабируемую систему, вам нужно только подключиться к общей базе данных, общему кэшу, блокировкам и общей службе rpc (MQ, такому как RabbitMQ, Redis и т. д.). В некоторых случаях может потребоваться общее файловое хранилище, но vstutils не требует его.

Рассмотрим основные разделы конфигурации и их параметры:

Основные настройки

Раздел [main].

Этот раздел предназначен для настроек, относящихся ко всему приложению на основе vstutils (как рабочему процессу, так и веб-интерфейсу). Здесь вы можете указать уровень подробности вывода информации о работе приложения на основе vstutils, что может быть полезно при устранении неполадок (уровень логгирования и т. д.). Также здесь находятся настройки для изменения часового пояса приложения в целом и разрешенных доменов.

Чтобы использовать протокол LDAP, создайте следующие настройки в разделе [main].

ldap-server = ldap://server-ip-or-host:port
ldap-default-domain = domain.name
ldap-auth_format = cn=<username>,ou=your-group-name,<domain>

ldap-default-domain - это необязательный аргумент, который направлен на то, чтобы сделать авторизацию проще (без ввода доменного имени).

ldap-auth_format это необязательный аргумент, который направлен на то, чтобы кастомизировать LDAP авторизацию. Значение по умолчанию: cn=<username>,<domain>

В примере выше логика авторизации будет следующая:

  1. Система проверяет комбинацию login:password в базе данных

  2. Система проверяет комбинацию login:password в LDAP:

    • Если домен был указан, то он будет установлен во время авторизации (например, если пользователь ввел login без user@domain.name` или без DOMAIN\user);

    • Если авторизация была успешной и пользователь с предоставленными данными существует в базе данных, сервер создает сессию этого пользователя.

  • debug - Включить режим отладки. По умолчанию: false.

  • allowed_hosts - Разделенный запятой список доменов, которым разрешено обслуживание. По умолчанию: *.

  • first_day_of_week - Целочисленное значение первого дня недели. по умолчанию: 0.

  • ldap-server - Подключение к серверу LDAP.

  • ldap-default-domain - Домен по умолчанию для аутентификации

  • ldap-auth_format - Формат запроса поиска по умолчанию для аутентификации. По умолчанию: cn=<username>,<domain>.

  • timezone - часовой пояс для веб-приложения. По умолчанию: UTC.

  • log_level - Уровень логгирования. По умолчанию WARNING.

  • enable_django_logs - Включить или выключить вывод логов Django. Полезно для отладки. По умолчанию: false.

  • enable_admin_panel - Включить или выключить панели администратора Django. По умолчанию: false.

  • enable_registration - Включить или выключить самостоятельную регистрацию пользователей. По умолчанию: false.

  • enable_user_self_remove - Включить или выключить самоудаление пользователей. По умолчанию: false.

  • auth-plugins - Список аутентифицированных бэкендов Django, разделенных запятыми. Попытка авторизации повторяется до первой успешной в соответствии с порядком, указанным в списке.

  • auth-cache-user - Включить или выключить кэширование экземпляра пользователя. Это увеличивает производительность сеанса при каждом запросе, но сохраняет экземпляр модели в небезопасном хранилище (кэше Django по умолчанию). Экземпляр сериализуется в строку с использованием стандартного модуля python pickle, а затем шифруется с помощью шифра Виженера. Дополнительную информацию можно найти в документации vstutils.utils.SecurePickling. По умолчанию: false.

Настройки базы данных

Раздел [databases].

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

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

  • default_tablespace - Табличное пространство по умолчанию, используемое для индексов полей, в которых оно не указано, если бэкенд это поддерживает. Дополнительную информацию можно найти в разделе Объявление табличных пространств для индексов.

  • default_index_tablespace - Табличное пространство по умолчанию, используемое для индексов полей, в которых оно не указано, если бэкенд это поддерживает Дополнительную информацию можно найти в разделе Объявление табличных пространств для индексов.»

  • databases_without_cte_support - Разделенный запятыми список разделов баз данных которые не поддерживают CTEs (Common Table Expressions).

Предупреждение

Хоть MariaDB и поддерживает CTEs (Common Table Expressions), но база данных, подключенная к MariaDB все равно должна быть добавлена в список databases_without_cte_support. Проблема заключается в том, что реализация рекурсивных запросов MariaDB не позволяет использовать их в стандартной форме. MySQL (начиная с версии 8.0) работает ожидаемым образом.

Также, все подразделы этого раздела представляют собой доступные подключения к СУБД. Таким образом, раздел databases.default будет использоваться Django в качестве подключения по умолчанию.

Здесь вы можете изменять настройки, связанные с базой данных, которую будет использовать приложение, основанное на vstutils. Приложение, основанное на vstutils, поддерживает все базы данных, поддерживаемые Django. Список поддерживаемых баз данных изначально включает SQLite (выбор по умолчанию), MySQL, Oracle или PostgreSQL. Подробную информацию о конфигурации можно найти в документации Django по базам данных. Для запуска приложения, основанного на vstutils, на нескольких узлах (кластере) используйте клиент-серверную базу данных (SQLite не подходит), используемую всеми узлами.

Вы также можете задать базовый шаблон для подключения к базе данныхв разделе database.

Раздел [database].

Этот раздел предназначен для определения базового шаблона для подключения к различным базам данных. Это может быть полезно для сокращения списка настроек в подразделах databases.* путем установки одного и того же подключения для различного набора баз данных в проекте. Дополнительные сведения можно найти в документации Django о множественных базах данных

Здесь приведен список настроек, необходимых для базы данных MySQL/MariaDB

Во-первых, если вы используете MySQL/MariaDB и установили часовой пояс, отличный от «UTC», вам следует выполнить следующую команду:

mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql

Во-вторых, чтобы использовать MySQL/MariaDB установите следующие настройки в файле settings.ini:

[database.options]
connect_timeout = 10
init_command = SET sql_mode='STRICT_TRANS_TABLES', default_storage_engine=INNODB, NAMES 'utf8', CHARACTER SET 'utf8', SESSION collation_connection = 'utf8_unicode_ci'

Наконец, добавьте некоторые настройки в конфигурацию MySQL/MariaDB

[client]
default-character-set=utf8
init_command = SET collation_connection = @@collation_database

[mysqld]
character-set-server=utf8
collation-server=utf8_unicode_ci

Настройки кэша

Раздел [cache].

В этом разделе находятся настройки, связанные с кэшем, используемые приложением, основанным на vstutils. vstutils поддерживает все бэкэнды кэша, которые поддерживает Django. Файловая система, в памяти, memcached поддерживаются изначально, а многие другие поддерживаются с помощью дополнительных плагинов. Подробную информацию о настройках кэша можно найти в документации Django о поддерживаемых кэшах. При кластеризации мы рекомендуем делить кэш между узлами для повышения производительности с использованием реализаций клиент-серверного кэша. Мы рекомендуем использовать Redis в производственных окружениях.

Настройки блокировок

Раздел [locks].

Блокировки - это система, которую приложение, основанное на vstutils, использует для предотвращения повреждения от параллельных действий, выполняемых одновременно над одной сущностью. Она основана на кэше Django, поэтому есть еще одна группа настроек, аналогичных настройкам cache. Вы можете спросить, почему для них существует еще один раздел. Потому что бэкэнд кэша, используемый для блокировки, должен обеспечивать некоторые гарантии, которые не требуются для обычного кэша: он ДОЛЖЕН быть общим для всех потоков и узлов приложения, основанного на vstutils. Например, бэкенд in-memory не подходит. В случае кластеризации настоятельно рекомендуется использовать Redis или Memcached в качестве бэкэнда для этой цели. Бэкэнд кэша и блокировок могут быть одним и тем же, но не забывайте о требованиях, о которых мы говорили выше.

Настройки кэша сессий

Раздел [session].

Приложение, основанное на vstutils, хранит сеансы в базе данных, но для повышения производительности мы используем кэшевый бэкэнд для сеансов. Он также основан на кэше Django, поэтому здесь есть еще одна группа настроек, аналогичных настройкам cache. По умолчанию настройки получаются из cache.

Настройки RPC

Раздел [rpc].

Приложение, основанное на vstutils, использует Celery для выполнения длительных асинхронных задач. Celery основан на концепции очереди сообщений, поэтому между веб-сервисом и рабочими процессами, работающими под управлением Celery, должен быть некий брокер сообщений (например, RabbitMQ). Эти настройки относятся к этому брокеру и самому Celery. В них указывается бэкэнд брокера, количество рабочих процессов на узел и некоторые настройки, используемые для устранения проблем взаимодействия сервера, брокера и рабочих процессов.

Для этого раздела требуется vstutils с дополнительной зависимостью rpc.

  • connection - Соединение с брокером celery. По умолчанию: filesystem:///var/tmp.

  • concurrency - Количество потоков рабочего процесса Celery. По умолчанию: 4.

  • heartbeat - Интервал между отправкой пакетов-сигналов, которые говорят, что соединение все еще активно. По умолчанию: 10.

  • enable_worker - Включить или отключить рабочий процесс с веб-сервером. По умолчанию: true.

Также поддерживаются следующие переменные из настроек Django (с соответствующими типами):

Настройки рабочего процесса (worker`a)

Раздел [worker].

Предупреждение

Эти настройки необходимы только для приложений с включенной поддержкой RPC.

Настройки рабочего процесса celery:

  • loglevel - Уровень логгирования рабочего процесса. По умолчанию: из раздела main log_level.

  • pidfile - Файл pid для рабочего процесса Celery. по умолчанию: /run/{app_name}_worker.pid»

  • autoscale - Параметры для автомасштабирования. Два числа, разделенных запятой: максимальное,минимальное.

  • beat - Включить или отключить планировщик celery beat. По умолчанию: true.

Другие настройки можно увидеть с помощью команды celery worker --help

SMTP-настройки

Раздел [mail].

Django поставляется с несколькими вариантами отправки электронной почты. За исключением бэкэнда SMTP (который является значением по умолчанию при установке host), эти бэкэнды полезны только для тестирования и разработки.

Приложения, основанные на vstutils, используют только бэкэнды smtp и console.

  • host - IP-адрес или доменное имя smtp-сервера. Если не указано, vstutils использует бэкэнд console. По умолчанию: None.

  • port - Порт для подключения к smtp-серверу. По умолчанию: 25.

  • user - Имя пользователя для подключения к SMTP-серверу. По умолчанию: "".

  • password - Пароль для аутентификации на smtp-сервере. По умолчанию: "".

  • tls - Включить или отключить TLS для подключения к smtp-серверу. По умолчанию: False

  • send_confirmation - Включить или отключить отправку сообщения с подтверждением после регистрации. По умолчанию: False.

  • authenticate_after_registration - Включить или отключить автоматический вход пользователя после подтверждения регистрации. По умолчанию: False.

Web-настройки

Раздел [web].

Эти настройки относятся к веб-серверу. Среди них: session_timeout, static_files_url и лимит пагинации.

  • allow_cors - включить cross-origin resource sharing. По умолчанию: False.

  • cors_allowed_origins, cors_allowed_origins_regexes, cors_expose_headers, cors_allow_methods, cors_allow_headers, cors_preflight_max_age - Настройки из библиотеки django-cors-headers со значениями по умолчанию.

  • enable_gravatar - Включить/отключить использование сервиса Gravatar для пользователей. По умолчанию: True.

  • rest_swagger_description - Строка справки в схеме Swagger. Полезно для разработки интеграций.

  • openapi_cache_timeout - Время кэширования данных схемы. По умолчанию: 120.

  • Количество запросов к конечной точке /api/health/. По умолчанию: 60.

  • bulk_threads - Количество потоков для PATCH /api/endpoint/. По умолчанию: 3.

  • session_timeout - Время жизни сессии. По умолчанию: 2w (две недели).

  • etag_default_timeout - Время кэширования заголовков Etag для управления кэшированием моделей. По умолчанию: 1d (один день).

  • rest_page_limit and page_limit - Максимальное количество объектов в списке API. По умолчанию: 1000.

  • session_cookie_domain - Домен, используемый для сессионных cookie. Подробнее. По умолчанию: None.

  • csrf_trusted_origins - Список хостов, которым доверяются небезопасные запросы. Подробнее. По умолчанию: значение из session_cookie_domain.

  • case_sensitive_api_filter - Включить/отключить чувствительность к регистру при фильтрации по имени. По умолчанию: True.

  • secure_proxy_ssl_header_name - Имя заголовка, которое активирует использование URL-адресов SSL в ответах. Подробнее. По умолчанию: HTTP_X_FORWARDED_PROTOCOL.

  • secure_proxy_ssl_header_value - Значение заголовка, которое активирует использование URL-адресов SSL в ответах. Подробнее. По умолчанию: https.

Также поддерживаются следующие переменные из настроек Django (с соответствующими типами):

Следующие настройки влияют на эндпоинт метрик Prometheus (который может использоваться для мониторинга приложения):

  • metrics_throttle_rate - Количество запросов к эндпоинту /api/metrics/. По умолчанию: 120.

  • enable_metrics - Включить/отключить эндпоинт /api/metrics/ для приложения. По умолчанию: true.

  • metrics_backend - Путь к классу Python с бэкендом сборщика метрик. По умолчанию: vstutils.api.metrics.DefaultBackend. Стандартный бэкенд собирает метрики из рабочих процессов uwsgi и информацию о версии Python.

Раздел [uvicorn].

Вы можете настроить необходимые параметры для запуска сервера uvicorn. vstutils поддерживает практически все опции из командной строки, за исключением тех, которые настраивают приложение и соединение.

Вы можете посмотреть все доступные настройки uvicorn, введя команду uvicorn --help

Настройки клиента Centrifugo

Раздел [centrifugo].

Для установки приложения с клиентом Centrifugo должен быть задан раздел [centrifugo]. Centrifugo используется приложением для автоматического обновления данных на странице. Когда пользователь изменяет какие-либо данные, другие клиенты получают уведомление на канале subscriptions_update с меткой модели и первичным ключом. Без этой службы все клиенты GUI получают данные страницы каждые 5 секунд (по умолчанию).

  • address - Адрес сервера Centrifugo.

  • api_key - Ключ API для клиентов.

  • token_hmac_secret_key - Ключ API для генерации JWT-токена.

  • timeout - Таймаут подключения.

  • verify - Проверка подключения.

  • subscriptions_prefix - Префикс, используемый для генерации каналов обновления, по умолчанию «{VST_PROJECT}.update».

Примечание

Эти настройки также добавляют параметры в схему OpenAPI и меняют работу системы автообновления в GUI. token_hmac_secret_key используется для генерации JWT-токена (на основе времени истечения сессии). Токен будет использоваться для клиента Centrifugo-JS.

Настройки хранилища

Раздел [storages].

Приложения, основанные на vstutils, поддерживают хранение файлов в файловой системе из коробки. Чтобы настроить пользовательский медиа-каталог и относительный URL, установите значения media_root и media_url в разделе [storages.filesystem]. По умолчанию они будут равны {/path/to/project/module}/media и /media/.

Приложения, основанные на vstutils, также поддерживают хранение файлов во внешних службах с помощью Apache Libcloud и Boto3.

Настройки Apache Libcloud группируются по разделам с именами [storages.libcloud.provider], где provider - это имя хранилища. Каждый раздел имеет четыре ключа: type, user, key и bucket. Подробнее о настройках можно прочитать в документации django-storages libcloud.

Эта настройка необходима для настройки соединений с провайдерами облачного хранилища. Каждая запись соответствует отдельному ‘bucket’ хранилища. Вы можете иметь несколько buckets для одного провайдера услуг (например, несколько buckets S3), и вы можете определить buckets в нескольких провайдерах.

Для Boto3 все настройки группируются в разделе с именем [storages.boto3]. Раздел должен содержать следующие ключи: access_key_id, secret_access_key, storage_bucket_name. Подробнее о настройках можно прочитать в документации django-storages amazon-S3.

При выборе движка хранилища используется следующий приоритет, если их было предоставлено несколько:

  1. Хранилище Libcloud, когда конфигурация содержит этот раздел.

  2. Хранилище Boto3, когда у вас есть раздел и имеются все необходимые ключи.

  3. В противном случае хранилище FileSystem.

После того, как вы определили ваших провайдеров Libcloud, у вас есть возможность установить одного, как провайдера по умолчанию для хранилища Libcloud. Вы можете сделать это, настроив раздел [storages.libcloud.default] или же vstutils установит первое хранилище, как хранилище по умолчанию.

Если вы настроили провайдера Libcloud по умолчанию, vstutils будет использовать его в качестве глобального хранилища файлов. Чтобы переопределить это, установите default=django.core.files.storage.FileSystemStorage в разделе [storages]. Когда [storages.libcloud.default] пусто, по умолчанию используется django.core.files.storage.FileSystemStorage. Чтобы переопределить это, установите default=storages.backends.apache_libcloud.LibCloudStorage в разделе [storages] и используйте провайдера Libcloud, как по умолчанию.

Вот пример подключения boto3 к кластеру minio с публичными правами на чтение, внешним доменом прокси и поддержкой внутреннего подключения:

[storages.boto3]
access_key_id = EXAMPLE_KEY
secret_access_key = EXAMPLEKEY_SECRET
# connection to internal service behind proxy
s3_endpoint_url = http://127.0.0.1:9000/
# external domain to bucket 'media'
storage_bucket_name = media
s3_custom_domain = media-api.example.com/media
# external domain works behind tls
s3_url_protocol = https:
s3_secure_urls = true
# settings to connect as plain http for uploading
s3_verify = false
s3_use_ssl = false
# allow to save files with similar names by adding prefix
s3_file_overwrite = false
# disables query string auth and setup default acl as RO for public users
querystring_auth = false
default_acl = public-read

Настройки Throttle

Раздел [throttle].

Путем добавления этой секции в вашу конфигурацию вы можете настроить глобальные и индивидуальные throttle rates для каждого View. Глобальные throttle rates указываются в секции [throttle]. Чтобы указать индивидуальные throttle rates для конкретного View, вам нужно добавить дочернюю секцию.

Например, если вы хотите применить ограничение количества запросов для api/v1/author:

[throttle.views.author]
rate=50/day
actions=create,update

  • rate - Ограничение количества запросов в формате number_of_requests/time_period. Expected time_periods: second/minute/hour/day.

  • actions - Разделенный запятой список действий DRF. Ограничение количества запросов будет применяться только к указанным здесь действиям. По умолчанию: update, partial_update.

Подробнее об ограничении количества запросов в документации DRF Throttle.

Настройки для продакшн-сервера

Раздел [uwsgi].

Настройки, связанные с веб-сервером, используемым в приложении на основе vstutils в продакшн-среде (по умолчанию для пакетов deb и rpm). Большинство из них относятся к системным путям (логгирование, PID-файл и т. д.). Дополнительные настройки смотрите в документации uWSGI..

Однако имейте в виду, что uWSGI устарел и может быть удален в будущих версиях. Используйте настройки uvicorn для управления сервером вашего приложения.

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

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

  1. Если вам необходимо настроить HTTPS для ваших веб-настроек, вы можете сделать это с помощью HAProxy, Nginx, Traefik или настроить в файле settings.ini.

[uwsgi]
addrport = 0.0.0.0:8443

[uvicorn]
ssl_keyfile = /path/to/key.pem
ssl_certfile = /path/to/cert.crt

  1. Мы настоятельно не рекомендуем запускать веб-сервер от имени root. Используйте HTTP-прокси, чтобы работать на привилегированных портах.

  2. Вы можете использовать {ENV[HOME:-value]} (где HOME - переменная окружения, value - значение по умолчанию) в значениях конфигурации.

  3. Вы можете использовать переменные окружения для настройки важных параметров. Однако переменные конфигурации имеют более высокий приоритет, чем переменные окружения. Доступные настройки: DEBUG, DJANGO_LOG_LEVEL, TIMEZONE и некоторые настройки с префиксом [ENV_NAME].

    Для проекта без специальных настроек и проектов с именами, начинающимися с project, эти переменные будут иметь префикс PROJECT_. Вот список этих переменных: {ENV_NAME}_ENABLE_ADMIN_PANEL, {ENV_NAME}_ENABLE_REGISTRATION, {ENV_NAME}_MAX_TFA_ATTEMPTS, {ENV_NAME}_ETAG_TIMEOUT, {ENV_NAME}_SEND_CONFIRMATION_EMAIL, {ENV_NAME}_SEND_EMAIL_RETRIES, {ENV_NAME}_SEND_EMAIL_RETRY_DELAY, {ENV_NAME}_AUTHENTICATE_AFTER_REGISTRATION, {ENV_NAME}_MEDIA_ROOT (директория с загрузками), {ENV_NAME}_GLOBAL_THROTTLE_RATE, и {ENV_NAME}_GLOBAL_THROTTLE_ACTIONS.

    Также существуют переменные, специфичные для URI, для подключения к различным сервисам, таким как базы данных и кэши. Вот некоторые из них DATABASE_URL, CACHE_URL, LOCKS_CACHE_URL, SESSIONS_CACHE_URL и ETAG_CACHE_URL. Как видно из названий, они тесно связаны с ключами и именами соответствующих секций конфигурации.

  4. Мы рекомендуем установить uvloop в ваше окружение и настроить loop = uvloop в разделе [uvicorn] для повышения производительности.