TQE Documentation portal logo
Помощь
Обновлена 9 ноября 2026 г. в 13:01

Конфигурация модуля API

Параметры конфигурации компонента модуля API необходимо определить до его запуска и запуска TQE(MQ), чтобы избежать проблем с подключением к очереди сообщений и аварийного завершения работы модуля.

YAML-файл конфигурации модуля API называется config.service.yml и содержит несколько разделов. Полный перечень настроек представлен в следующем примере:

app_name: MESSAGE_QUEUE_EE_APIapp_version: testcore_host: 0.0.0.0core_port: 18184grpc_host: 0.0.0.0grpc_port: 18182producer:  enabled: true  tarantool:    user: tqe_producer_user    pass: pass    connections:      routers:        - "localhost:3301"consumer:  enabled: true  polling_timeout: 500ms  cursor_serilizer: 'yaml'  buffer: 12  concurrency: 2  access_mode: 'prefer_ro'  tarantool:    user: tqe_consumer_user    pass: pass    connections:      storage-1:        - "localhost:3301"log:  to: file  file: log.jsonl  format: json  level: info

Основные параметры API

Основные параметры задают адреса и порты для подключения модуля API:

  • app_name - название приложения.
  • app_version - версия приложения.
  • core_host - адрес сбора метрик и проверки состояния модуля API.
  • core_port - порт сбора метрик и проверки состояния модуля API.
  • grpc_options - раздел конфигурации gRPC-сервера. См. подробнее. Установленные значения не изменяются после запуска gRPC-сервера:
    • initial_conn_window_size - начальный размер окна http2-соединения в байтах. Значение по умолчанию: 64kb.
    • initial_window_size - начальный размер окна http2-потока в байтах. Значение по умолчанию: 64kb.
    • header_table_size - размер динамической таблицы заголовков http2. Значение по умолчанию не задано (динамическая таблица не используется).
    • max_header_list_size - максимальный размер таблицы заголовков http2. Значение по умолчанию не задано.
    • max_concurrent_streams - количество одновременных http-потоков. Значение по умолчанию: 128.
    • num_stream_workers - количество обработчиков входящих запросов. Значение по умолчанию: 0 (под каждый http2-поток создается отдельная горутина).
    • max_recv_msg_size - максимальный размер входящего сообщения в байтах. Значение по умолчанию: 4mb.
    • max_send_msg_size - максимальный размер исходящего сообщения в байтах. Значение по умолчанию: 2mb.
    • read_buffer_size - размер буфера на чтение. Значение по умолчанию: 256kb.
    • write_buffer_size - размер буфера на запись. Значение по умолчанию: 256kb.
    • shared_write_buffer - позволяет переиспользовать буфер на запись, а не создавать новый для каждого подключения. Значение по умолчанию: false.
  • grpc_listen - набор интрефейсов, на которых gRPC-сервер принимает подключения.
    • uri - адрес для прослушивания, например: unix:///tmp/tqe-mq.sock или tcp://localhost:18182.
  • grpc_host - адрес модуля API (устарел после введения grpc_listen).
  • grpc_port - порт модуля API (устарел после введения grpc_listen).
  • cursor_serializer - тип сериализатора курсора для gRPC API. Применяется как для формирования курсора в ответе BroadcastResponse (Producer), так и для десериализации курсора в запросе SubscribeRequest (Consumer). По умолчанию пустое значение (используется сериализатор base64). Доступные значения: json, yaml.

Пример:

app_name: MESSAGE_QUEUE_EE_APIapp_version: 1.0core_host: 0.0.0.0core_port: 18184grpc_listen:  - uri: 'tcp://0.0.0.0:18182'grpc_host: 0.0.0.0grpc_port: 18182grpc_options:  initial_conn_window_size: 65535  initial_window_size: 65535  header_table_size: 16777216  max_header_list_size: 128  max_concurrent_streams: 128  num_stream_workers: 0  max_recv_msg_size: 4294967296  max_send_msg_size: 2147483647  read_buffer_size: 262144  write_buffer_size: 262144  shared_write_buffer: false

Раздел настроек TLS

Параметры сетевого подключения клиента к очереди по протоколу зашифрованного канала связи TLS (Transport Layer Security) указываются в разделе настроек grpc_options файла config.service.yml:

  • tls - раздел настроек подключения по протоколу зашифрованного канала связи TLS (Transport Layer Security).
    • enabled - включает или выключает подключение по TLS. Обязательный параметр. Принимает значения:
      • true - подключение по TLS включено.
      • false - подключение по TLS выключено. Используется по умолчанию.
    • cert_file - абсолютный или относительный путь к файлу с публичным сертификатом TLS (public_key). Параметр обязателен при enabled: true.
    • key_file - абсолютный или относительный путь к файлу с закрытым (приватным) ключом. Параметр обязателен при enabled: true.
    • ca_file - абсолютный или относительный путь к файлу с сертификатами доверенных удостоверяющих центров.
    • password - пароль для расшифровки файла закрытого ключа. Если указан одновременно с password_file, приоритетным считается путь в password_file.
    • password_file - абсолютный или относительный путь к файлу с паролем для расшифровки закрытого ключа. Если указан одновременно с password, то приоритетным считается путь в password_file.
    • ciphers - список алгоритмов шифрования, разрешенных при установке защищенного соединения. Подключение выполняется, только если клиент и сервер имеют хотя бы один общий алгоритм в списках разрешенных. Список поддерживаемых алгоритмов представлен в таблице ниже. Поддерживаются в том числе ГОСТ-алгоритмы (см. раздел ГОСТ-шифры и сертификаты). Если параметр ciphers задан, версия протокола фиксируется на TLS 1.2.

Поддерживаемые алгоритмы шифрования:

  • ECDHE-ECDSA-AES256-GCM-SHA384
  • ECDHE-RSA-AES256-GCM-SHA384
  • ECDHE-ECDSA-CHACHA20-POLY1305
  • ECDHE-RSA-CHACHA20-POLY1305
  • ECDHE-ECDSA-AES128-GCM-SHA256
  • ECDHE-RSA-AES128-GCM-SHA256
  • ECDHE-ECDSA-AES128-SHA256
  • ECDHE-RSA-AES128-SHA256
  • ECDHE-ECDSA-AES256-SHA
  • ECDHE-RSA-AES256-SHA
  • ECDHE-ECDSA-AES128-SHA
  • ECDHE-RSA-AES128-SHA
  • ECDHE-RSA-DES-CBC3-SHA
  • ECDHE-ECDSA-RC4-SHA
  • ECDHE-RSA-RC4-SHA
  • AES256-GCM-SHA384
  • AES128-GCM-SHA256
  • AES128-SHA256
  • AES256-SHA
  • AES128-SHA
  • DES-CBC3-SHA
  • RC4-SHA
  • GOST2012-GOST8912-GOST8912
  • GOST2001-GOST89-GOST89

Пример:

grpc_options:  tls:    enabled: true    cert_file: /path/to/server.crt    key_file: /path/to/server.key    ca_file: /path/to/ca.crt    password: "secret"    password_file: /path/to/passwords.txt      ciphers: 'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256'

ГОСТ-шифры и сертификаты

gRPC API использует ГОСТ-шифры (ГОСТ Р 34.12-2015) и ГОСТ-сертификаты (ГОСТ Р 34.10-2012) в формате PEM через OpenSSL.

ГОСТ-шифры задаются в параметре ciphers по их OpenSSL-именам:

Алгоритм
OpenSSL название
ГОСТ Р 34.12-2015
GOST2012-GOST8912-GOST8912
ГОСТ Р 34.10-2001
GOST2001-GOST89-GOST89

Пример конфигурации с ГОСТ-шифрами и ГОСТ-сертификатами:

grpc_options:  tls:    enabled: true    cert_file: /path/to/gost-server.crt    key_file: /path/to/gost-server.key    ca_file: /path/to/gost-ca.crt    ciphers: 'GOST2012-GOST8912-GOST8912'

Настройки подключений к ядру

Ядро TQE(MQ) включает в себя маршрутизаторы, хранилища и оркестраторы.

Подключение к ядру может быть динамическим, когда обнаружение топологии ядра происходит через удаленную службу Tarantool configuration Storage (TcS) или распределенное хранилище etcd.

При необходимости можно использовать статическое подключение. Тогда адреса маршрутизаторов и хранилищ задаются в конфигурации модуля API по отдельности.

Динамическое подключение к ядру

При динамическом подключении обнаружение топологии ядра происходит через удаленную службу TcS или распределенное хранилище etcd.

Настройки подключения к TcS указываются в разделе config.storage:

  • endpoints - данные точек подключения в формате списка, содержащего:
    • uri - URI точки подключения.
    • login - логин для подключения.
    • password - пароль для подключения.
    • params - параметры подключения по протоколу зашифрованного канала связи TLS:
      • transport - включает или выключает подключение по TLS. Обязательный параметр. Принимает значения:
        • ssl - подключение по TLS включено.
        • plain - подключение по TLS выключено. Используется по умолчанию.
      • ssl_ca_file - абсолютный или относительный путь к файлу с сертификатами доверенных удостоверяющих центров. По этому файлу клиент проверяет, что сертификат сервера выпущен доверенным центром. Если параметр не задан, проверки не происходит вовсе - системное хранилище сертификатов при этом не используется: трафик шифруется, но подлинность сервера не подтверждается.
      • ssl_cert_file - абсолютный или относительный путь к файлу с публичным сертификатом клиента (public_key). Задается только для двусторонней аутентификации (mTLS) - когда сервер требует сертификат и от клиента. Для обычного TLS, где клиент проверяет сервер, а сервер клиента не проверяет, параметр не нужен. Задается вместе с ssl_key_file.
      • ssl_key_file - абсолютный или относительный путь к файлу с закрытым (приватным) ключом клиентского сертификата. Задается вместе с ssl_cert_file.
      • ssl_password - пароль для расшифровки файла закрытого ключа. Если указан одновременно с ssl_password_file, приоритетным считается путь в ssl_password_file.
      • ssl_password_file - абсолютный или относительный путь к файлу с паролем для расшифровки закрытого ключа. Если указан одновременно с ssl_password, приоритетным считается путь в ssl_password_file.
      • ssl_ciphers - список алгоритмов шифрования, разрешенных при установке защищенного соединения. Подключение выполняется, только если клиент и сервер имеют хотя бы один общий алгоритм в списках разрешенных. См. список разрешенных алгоритмов.
  • username - логин для подключения. Используется если логин (login) не задан в списке данных точки подключения в endpoints.
  • password - пароль для подключения. Используется если пароль (password) не задан в списке данных точки подключения в endpoints.
  • prefix - префикс для маршрутизации внутри удаленной службы.
  • timeout - время ожидания подключения в секундах.
  • reconnect_after - интервал в секундах между повторными подключениями.
  • max_reconnect_attempts - максимальное число попыток повторного подключения.

Пример настройки:

config:  storage:    endpoints:      - uri: "127.0.0.1:4401"        login: sampleuser        password: "123456"      - uri: "127.0.0.1:4440"        login: sampleuser        password: "123456"        params:          transport: "ssl"          ssl_cert_file: "examples/tls-full/certs/tcs/storage.crt"          ssl_key_file: "examples/tls-full/certs/tcs/storage.key"          ssl_ca_file: 'examples/tls-full/certs/ca/ca.crt'    username: sampleuser    password: "123456"    prefix: "/tarantool/tqe-mq"    timeout: 5s    reconnect_after: 5s    max_reconnect_attempts: 3

Настройки подключения к etcd указываются в разделе config.etcd:

  • endpoints - HTTP-адреса точек подключения в формате списка.
  • prefix - префикс для маршрутизации внутри удаленной службы.
  • timeout - время ожидания подключения в секундах.
  • reconnect_after - интервал в секундах между повторными подключениями.
  • max_reconnect_attempts - максимальное число попыток повторного подключения.
  • ssl - параметры подключения по протоколу зашифрованного канала связи TLS:
    • ca_file - абсолютный или относительный путь к файлу с сертификатами доверенных удостоверяющих центров.
    • ca_path - абсолютный или относительный путь к каталогу, в котором хранятся файлы с сертификатами доверенных удостоверяющих центров.
    • ssl_cert - абсолютный или относительный путь к файлу с публичным сертификатом TLS (public_key).
    • ssl_key - абсолютный или относительный путь к файлу с закрытым (приватным) ключом.
    • verify_peer - включает проверку клиентом etcd цепочки сертификатов и имени хоста сервера etcd. Возможные значения:
      • true - проверка включена.
      • false - проверка выключена. Это значение используется по умолчанию.

Пример настройки:

config:  etcd:    endpoints:      - "http://localhost:2379"    prefix: "/tarantool/tqe-mq"    timeout: 5s    reconnect_after: 5s    max_reconnect_attempts: 3    ssl:      ca_file: "examples/tls-full/certs/ca/ca.crt"      ca_path: "examples/tls-full/certs/ca"      ssl_cert: "examples/tls-full/certs/tcs/storage.crt"      ssl_key: "examples/tls-full/certs/tcs/storage.key"      verify_peer: false

Статическое подключение к маршрутизаторам

При статическом подключении к маршрутизаторам их адреса задаются пользователем вручную в разделе настроек producer. Изменение адресов или списка маршрутизаторов также выполняется вручную.

Параметры статического подключения:

  • enabled - включает или выключает режим публикации сообщений в очередь. Возможные значения:
    • true - публикация сообщений включена.
    • false - публикация сообщений выключена.
  • tarantool - раздел настроек доступа к ядру TQE(MQ):
    • user - логин для доступа к очереди (задается в разделе credentials конфигурации ядра TQE(MQ)).
    • pass - пароль для доступа к очереди (задается в разделе credentials конфигурации ядра TQE(MQ)).
    • connections - перечень названий типов подключений. Не указывается в случае динамического подключения.

Пример:

producer:  enabled: true  tarantool:    user: tqe_producer_user    pass: pass    connections:      rs-1:        - "localhost:3301"

Статическое подключение к хранилищам

При статическом подключении к хранилищам их адреса задаются пользователем вручную в разделе настроек consumer. Изменение адресов или списка хранилищ также выполняется вручную.

Параметры статического подключения к хранилищам:

  • enabled - включает или выключает режим потребления сообщений из очереди. Возможные значения:
    • true - потребление сообщений включено.
    • false - потребление сообщений выключено.
  • polling_timeout - задержка между запросами на получение новых сообщений с указанием единиц измерения. Пример: 500ms - 500 миллисекунд.
  • cursor_serializer - тип сериализатора курсора. Устарел, используйте верхнеуровневый параметр cursor_serializer. По умолчанию пустое значение (используется сериализатор base64). Доступные значения: json, yaml.
  • buffer_size - размер внутреннего буфера потребителя (в сообщениях). Значение по умолчанию: 8.
  • concurrency - количество параллельных потоков потребления сообщений. Значение по умолчанию: 1.
  • access_mode - режим взаимодействия с наборами реплик Tarantool. Значение по умолчанию: prefer_rw. Подробнее о возможных значениях см. по ссылке.
  • tarantool - раздел настроек доступа к очереди TQE MQ:
    • user - логин логин для доступа к очереди (задается в разделе credentials конфигурации ядра TQE(MQ)).
    • pass - пароль длогин для доступа к очереди (задается в разделе credentials конфигурации ядра TQE(MQ)).
    • connections - раздел адресов хранилищ для подписки на сообщения. Не указываются в случае динамического подключения.
    • queues - необязательный раздел доступных очередей TQE(MQ).

Пример:

consumer:  enabled: true  polling_timeout: 500ms  cursor_serilizer: 'yaml'  buffer: 12  concurrency: 2  access_mode: 'prefer_ro'  tarantool:    user: tqe_consumer_user    pass: pass    queues:      queue:        connections:          storage-1:            - "localhost:3301"

Защищенное подключение по протоколу TLS

Подключение к экземпляру TQE (MQ) для публикации и чтения сообщений может выполняться по протоколу зашифрованного канала связи TLS (Transport Layer Security). Для включения этого протокола необходимо указать настройки подключения в разделах tarantool.params сервисов producer и consumer:

producer:  ...  tarantool:    user: user    pass: pass    params:      transport: "ssl"      ssl_cert_file: server2.crt      ssl_key_file: server2.keyconsumer:  ...  tarantool:    user: user    pass: pass    params:      transport: "ssl"      ssl_cert_file: server.crt      ssl_key_file: server.key

Параметры подключения по протоколу зашифрованного канала связи TLS:

  • transport - включает или выключает подключение по TLS. Обязательный параметр. Принимает значения:
    • ssl - подключение по TLS включено.
    • plain - подключение по TLS выключено. Используется по умолчанию.
  • ssl_ca_file - абсолютный или относительный путь к файлу с сертификатами доверенных удостоверяющих центров. По этому файлу клиент проверяет, что сертификат сервера выпущен доверенным центром. Если параметр не задан, проверки не происходит вовсе - системное хранилище сертификатов при этом не используется: трафик шифруется, но подлинность сервера не подтверждается.
  • ssl_cert_file - абсолютный или относительный путь к файлу с публичным сертификатом клиента (public_key). Задается только для двусторонней аутентификации (mTLS) - когда сервер требует сертификат и от клиента. Для обычного TLS, где клиент проверяет сервер, а сервер клиента не проверяет, параметр не нужен. Задается вместе с ssl_key_file.
  • ssl_key_file - абсолютный или относительный путь к файлу с закрытым (приватным) ключом клиентского сертификата. Задается вместе с ssl_cert_file.
  • ssl_password - пароль для расшифровки файла закрытого ключа. Если указан одновременно с ssl_password_file, приоритетным считается путь в ssl_password_file.
  • ssl_password_file - абсолютный или относительный путь к файлу с паролем для расшифровки закрытого ключа. Если указан одновременно с ssl_password, приоритетным считается путь в ssl_password_file.
  • ssl_ciphers - список алгоритмов шифрования, разрешенных при установке защищенного соединения. Подключение выполняется, только если клиент и сервер имеют хотя бы один общий алгоритм в списках разрешенных. См. список разрешенных алгоритмов.

Настройки журналирования

Параметры журналирования задаются в разделе log модуля API. Структура раздела аналогична разделу log ядра Tarantool.

Доступные параметры секции log:

  • to - место сохранения записей журнала. Принимаемые значения:
    • stderr - вывод событий журнала в stderr. Используется по умолчанию, если модуль API запущен не в фоновом режиме.
    • file - запись в файл, указанный в параметре log.file. Используется по умолчанию, если модуль API запущен в фоновом режиме (с параметром -d).
    • syslog - отправка в системный журнал syslog. Параметры подключения задаются в секции syslog.
  • file - абсолютный или относительный путь к файлу для записи событий журнала. Используется только при to: file. При запуске модуля API в фоновом режиме и пустом значении параметра в качестве файла записи используется server.jsonl.
  • format - формат вывода событий. Принимаемые значения:
    • plain - простой текстовый формат. Используется по умолчанию при to: stderr и to: file.
    • json - структурированный формат JSON. Используется по умолчанию при to: syslog.
  • nonblock - включает или выключает неблокирующий режим записи журнала. В неблокирующем режиме данные отправляются в буфер и приложение не ждет завершения записи в журнал. В этом режиме данные могут быть потеряны, если буфер переполнен. Принимает значения:
    • false - неблокирующий режим выключен. Пока данные не записаны в журнал, приложение не продолжает работу. Используется по умолчанию.
    • true - неблокирующий режим включен. Значение параметра используется системой при:
      • to: file - система записывает события журнала в файл через буфер diode, который допускает потерю событий при переполнении.
      • to: syslog + server: unix - система переводит подключение на канал unixgram, работающий без установки соединения, и отбрасывает события при переполнении очереди ядра. Значение параметра игнорируется системой, и при загрузке конфигурации и запуске системы журналирования выводится предупреждение об этом, если:
      • to: stderr - буфер отсутствует, и события журнала выводятся мгновенно.
      • to: syslog + server: udp - для подключения по udp неблокирующий режим всегда принудительно включен.
      • to: syslog + server: tcp / server: tcp+tls - для подключения по tcp неблокирующий режим всегда принудительно выключен.
  • level - уровень записи, определяющий важность события. Выбранное значение приводит к записи событий от этого значения и выше по приоритету. Принимаемые значения:
    • debug - детализированная диагностическая информация (самый низкий приоритет).
    • info - информационные сообщения о штатной работе. Используется по умолчанию.
    • warn - информация о потенциально опасных событиях, при которых работа приложения продолжается.
    • error - информация о серьезных ошибках, требующих внимания.
    • dpanic - информация о панике в режиме разработки.
    • panic - критическая ошибка, при которой приложение регистрирует панику и может завершить работу.
    • fatal- фатальная ошибка, которая привела к аварийной остановке приложения.
  • syslog - параметры записи событий в системный журнал syslog. Используются только при to: syslog:
    • server - URL-адрес получателя событий журнала. Поддерживаемые типы подключения:
      • unix - например, unix:/dev/log. Тип канала регулируется параметром nonblock:
        • при nonblock: false используется канал unix.
        • при nonblock: true используется канал unixgram, работающий в режиме без установления соединения.
      • udp - например, udp://host:514.
      • tcp - например, tcp://host:514.
      • tcp+tls - например, tcp+tls://host:6514.
    • identity - идентификатор приложения. Значение по умолчанию: message-queue-ee.
    • facility - категория источника записи события для сохранения в системном журнале. Принимает значения:
      • kern - ядро системы.
      • user - пользовательские процессы.
      • mail - почтовые службы.
      • daemon - фоновая служба.
      • auth - служба авторизации.
      • syslog - внутренние сообщения журнала.
      • lpr - системы печати.
      • news - новостные серверы (NNTP).
      • uucp - UUCP-подсистема.
      • cron - планировщик задач.
      • authpriv - привилегированные сообщения безопасности.
      • ftp - FTP-серверы.
      • local0...local7 - пользовательские приложения. Значение по умолчанию: local7.
    • format - формат сообщений в syslog.
      • rfc3164 - формат сообщений RFC 3164, используется по умолчанию.
      • rfc5424 - формат сообщений RFC 5424. Для unix сокетов применим только с коллектором, поддерживающим RFC 5424 (например, syslog-ng). journald не поддерживает RFC 5424, для него используйте rfc3164.
    • tls - параметры TLS. Используются только при схеме tcp+tls:
      • ca_file - абсолютный или относительный путь к файлу с сертификатами доверенных удостоверяющих центров.
      • cert_file - абсолютный или относительный путь к файлу с публичным сертификатом TLS (public_key).
      • key_file - абсолютный или относительный путь к файлу с закрытым (приватным) ключом.
      • server_name - имя сервера для проверки сертификата (SNI).
      • insecure_skip_verify - отключение проверки сертификата сервера. Значение по умолчанию: false.

Пример настройки записи событий журнала в файл:

log:  to: file  file: log.jsonl  format: json  level: info  nonblock: false

Пример настройки отправки событий в системный журнал syslog:

log:  to: syslog  level: info  syslog:    server: "unix:/dev/log"                    # также: udp://host:514 | tcp://host:514 | tcp+tls://host:6514    identity: "message-queue-ee"    facility: "local7"    tls:                                       # только для схемы tcp+tls      ca_file: /etc/ssl/syslog-ca.pem      cert_file: /etc/ssl/syslog-client.pem      key_file: /etc/ssl/syslog-client.key      server_name: ""      insecure_skip_verify: false
Была ли статья полезна?
Была ли статья полезна?