Конфигурация СУБД

Все необходимые данные для подключения и работы сервера приложения с используемыми СУБД можно задать в файле /etc/webim/db.json, а также в json-файлах в директории /etc/webim/db.json.d. При инициализации сервера все данные, хранящиеся в этих файлах, будут объединены в один словарь, так что Вы можете использовать оба предложенных способа. После создания словаря в нём будет произведён поиск необходимых данных. При удачном исходе поиска данные будут использованы для подключения к СУБД.

Вы можете задать конфигурации для всех используемых системой СУБД:

Реляционные СУБД - MySQL, MariaDB, PostgreSQL. Ключевые СУБД, используются для хранения большей части данных;
Колоночная СУБД - ClickHouse, используется для работы с модулем Статистики;
Поисковый движок — Elasticsearch или OpenSearch (на Webim Server 10.8+ подключение к обоим вариантам поддерживается одинаково), используется для ускорения поиска по истории чатов;

Из представленного списка обязательными для работы сервиса являются только реляционные СУБД - одна из них должна быть активна, настроена и подключена к серверу. Остальные СУБД являются опциональными и подключаются при необходимости.

Структура файла конфигурации СУБД

В db.json предусмотрена конкретная структура, неследование которой может повлечь за собой неработоспособность сервиса. Параметры для подключения СУБД хранятся в объекте dbs. Необходимым минимумом для работы сервиса является наличие в объекте dbs объектов meta и pro.default, внутри которых хранятся параметры, используемые сервером для подключения к соответствующим базам реляционной СУБД. Перечень принимаемых параметров зависит от типа СУБД, который указывается в соответствующем объекте.

В объекте default содержатся параметры для подключения к СУБД по умолчанию. Его наличие является обязательным для схемы pro и опциональным для остальных СУБД (кроме схемы meta - её параметры не оборачиваются в какие-либо дополнительные объекты, т. к. эта схема существует в единственном экземпляре и содержит в себе информацию об аккаунтах). В случае, если на Вашем Webim Server работает только один аккаунт, Вы можете использовать в качестве ключа обёртки как default, так и имя Вашего аккаунта (указанный Вами при регистрации сайт без точек). В тех случаях, если на Вашем Webim Server работают несколько аккаунтов, необходимо "расселить" их по разным БД, в противном случае данные из БД будут доступны всем аккаунтам. Для каждого аккаунта необходимо указать свою конфигурацию для подключения к СУБД, ключом для такой конфигурации будет имя аккаунта (например, wwwtestru).

При необходимости (например, при возникновении дублирования данных или большом размере конфигурационного файла) параметры подключения к СУБД можно хранить отдельно от основной конфигурации (в т. ч. и в другом файле). Для этого используется объект connections, внутри которого могут находиться объекты с произвольными именами, содержащие в себе параметры подключения к СУБД. Для их применения в конфигурации необходимо указать параметр connection, значением которого является один из ключей connections.

Для ClickHouse-кластера в dbs.stats.default используется параметр cluster_connection. Он указывает на ключ в connections и ожидает объект с типом подключения clickhouse_cluster.

N.B.

Подключение к ClickHouse в режиме кластера (cluster_connection / clickhouse_cluster) поддерживается начиная с версии Webim 10.8.

Во избежание путаницы мы рекомендуем удалять из конфигурации подключения параметры, указанные в используемом объекте из connections. Параметры из connection/cluster_connection являются приоритетными в сравнении с остальными параметрами конфигурации, указанными в объекте.

Описание принимаемых параметров конфигурации СУБД

Список возможных типов СУБД:

mysql
postgresql
clickhouse
elastic (в т. ч. типы elasticsearch и opensearch в значении поля type внутри секции — см. таблицу ниже)
clickhouse_cluster — только в объекте connections: описание кластера ClickHouse для ссылки через cluster_connection (Webim 10.8 и выше)

N.B.

В случае, если Вы желаете использовать MariaDB, в качестве типа СУБД укажите mysql. Принимаемые параметры этой СУБД аналогичны параметрам MySQL.

Список принимаемых параметров для MySQL и MariaDB:

Параметр	Тип	Пример	Описание	Является обязательным
`type`	`String`	`mysql`	Тип СУБД	Нет, так как любая СУБД по умолчанию имеет тип `mysql`
`host`	`String`	`127.0.0.1`	Адрес сервера СУБД (IPv4 или доменное имя)	Да
`port`	`Integer`	`3306`	Порт для подключения к СУБД	Нет, по умолчанию используется порт, соответствующий типу СУБД (параметр `type`)
`user`	`String`	`webim_site`	Учётная запись СУБД, используемая для выполнения запросов к БД. Обязательно наличие всех привилегий	Да
`password`	`String`	`somepass`	Пароль для соответствующей учётной записи СУБД	Да
`database`	`String`	`webim_hosted_meta`	Название БД, к которой будет осуществляться подключение	Да
`slave`	`Object`		Slave-узел для СУБД, используется при масштабировании (репликации). Внутри объекта содержатся аналогичные приведённым в таблице параметры. Репликация между различными СУБД не поддерживается.	Нет

Список принимаемых параметров для PostgreSQL:

Параметр	Тип	Пример	Описание	Является обязательным
`type`	`String`	`postgresql`	Тип СУБД	Да
`host`	`String`	`127.0.0.1`	Адрес сервера СУБД (IPv4 или доменное имя)	Да
`port`	`Integer`	`5432`	Порт для подключения к СУБД	Нет, по умолчанию используется порт, соответствующий типу СУБД (параметр `type`)
`user`	`String`	`webim_site`	Учётная запись СУБД, используемая для выполнения запросов к БД. Обязательно наличие всех привилегий	Да
`password`	`String`	`somepass`	Пароль для соответствующей учётной записи СУБД	Да
`db`	`String`	`some_db`	Название БД, к которой будет осуществляться подключение	Да
`schema`	`String`	`webim_hosted_meta`	Название схемы, с которой будут выполняться действия	Да
`slave`	`Object`		Slave-узел для СУБД, используется при масштабировании (репликации). Внутри объекта содержатся аналогичные приведённым в таблице параметры. Репликация между различными СУБД не поддерживается.	Нет

Список принимаемых параметров для ClickHouse:

Параметр	Тип	Пример	Описание	Является обязательным
`type`	`String`	`clickhouse`	Тип СУБД	Да
`host`	`String`	`127.0.0.1`	Адрес сервера СУБД (IPv4 или доменное имя)	Да
`port`	`Integer`	`9000`	Порт для подключения к СУБД	Нет; для ClickHouse по умолчанию используется порт 9000 (нативный протокол), если порт не задан явно
`user`	`String`	`webim_stats`	Учётная запись СУБД, используемая для выполнения запросов к БД. Обязательно наличие всех привилегий	Да
`password`	`String`	`somepass`	Пароль для соответствующей учётной записи СУБД	Да
`database`	`String`	`webim_stats`	Название БД, к которой будет осуществляться подключение	Да
`slave`	`Object`		Slave-узел для СУБД, используется при масштабировании (репликации). Внутри объекта содержатся аналогичные приведённым в таблице параметры.	Нет

Объект stats в dbs обязателен. Для одного узла ClickHouse без кластера его часто оставляют пустым ("stats": {}), а параметры подключения задают в stats_root (см. примеры ниже в статье). Для кластера (Webim 10.8 и выше) используйте stats.default: в нём указывают cluster_connection и связанные поля (таблицы ниже и пример).

Список полей объекта с type: clickhouse_cluster в connections (кластер ClickHouse; Webim 10.8 и выше):

Параметр	Тип	Пример	Описание	Является обязательным
`type`	`String`	`clickhouse_cluster`	Тип подключения в `connections`	Да
`cluster_name`	`String`	`webim_stats_cluster`	Имя кластера в ClickHouse (Distributed-таблицы, миграции)	Да
`nodes`	`Array`		Список узлов кластера; каждый элемент — объект с `type: clickhouse` (см. следующую таблицу)	Да

Список полей одного узла в массиве nodes (объект с type: clickhouse):

Параметр	Тип	Пример	Описание	Является обязательным
`type`	`String`	`clickhouse`	Тип узла	Да
`host`	`String`	`clickhouse-01.local`	Адрес узла (IPv4 или доменное имя)	Да
`port`	`Integer`	`9000`	Порт для подключения к узлу	Нет, по умолчанию используется порт 9000
`user`	`String`	`webim_stats`	Учётная запись ClickHouse на этом узле для рабочих запросов статистики	Да
`password`	`String`	`<your-password>`	Пароль учётной записи из поля `user`	Да
`database`	`String`	`webim_stats`	Имя БД на узле. Должно быть задано либо в каждом элементе `nodes`, либо один раз в том же `default`, где указан `cluster_connection` (в `dbs.stats.default` или в конфиге аккаунта): при развёртывании кластера поля из этого объекта дополняют каждый узел	Да (одним из этих способов)
`root_user`	`String`	`default`	Учётная запись ClickHouse с правами, достаточными для служебных операций (создание БД, миграции). Задаётся в каждом узле или один раз в том же `default`, где указан `cluster_connection`	Да (одним из этих способов)
`root_password`	`String`	`<your-password>`	Пароль для `root_user`	Да (одним из этих способов)
`weight`	`Integer`	`2`	Вес узла при выборе узла для записи. Задействуется только если `weight` задан у всех узлов и ни у одного не равен нулю; иначе Webim Server выбирает узел случайно, с равной вероятностью среди узлов списка	Нет

Для настройки ClickHouse-кластера в dbs.stats.default укажите cluster_connection, а в connections создайте объект типа clickhouse_cluster с cluster_name и массивом nodes. Ниже имя БД и учётные данные «root» заданы один раз в stats.default и не дублируются в nodes:

N.B.

В инструкции по обновлению до Webim Server 10.8 (файл UPGRADE.md в поставке сервера) кластерное подключение добавляют именно в stats.default, при этом старый connection в stats_root.default для прежнего одиночного узла удалять не обязательно — оба варианта могут временно сосуществовать.

{
    "dbs": {
        "stats": {
            "default": {
                "cluster_connection": "cluster_stats",
                "database": "webim_stats",
                "root_user": "default",
                "root_password": "<your-password>"
            }
        }
    },
    "connections": {
        "cluster_stats": {
            "type": "clickhouse_cluster",
            "cluster_name": "webim_stats_cluster",
            "nodes": [
                {
                    "type": "clickhouse",
                    "host": "clickhouse-01.local",
                    "port": 9000,
                    "user": "webim_stats",
                    "password": "<your-password>",
                    "weight": 2
                },
                {
                    "type": "clickhouse",
                    "host": "clickhouse-02.local",
                    "port": 9000,
                    "user": "webim_stats",
                    "password": "<your-password>",
                    "weight": 1
                }
            ]
        }
    }
}

Список принимаемых параметров для Elasticsearch и OpenSearch (начиная с Webim Server 10.8 в поле type допускаются значения elastic, elasticsearch и opensearch; секцию в dbs можно именовать elastic или history):

Параметр	Тип	Пример	Описание	Является обязательным
`type`	`String`	`elastic`	Тип СУБД: `elastic`, `elasticsearch` или `opensearch`	Да
`host`	`String`	`127.0.0.1`	Адрес сервера СУБД (IPv4 или доменное имя)	Да
`port`	`Integer`	`9200`	Порт для подключения к СУБД	Нет, по умолчанию используется порт, соответствующий типу СУБД (параметр `type`)
`user`	`String`	`elastic`	Учётная запись СУБД, используемая для выполнения запросов к БД. Обязательно наличие всех привилегий	Да
`password`	`String`	`somepass`	Пароль для соответствующей учётной записи СУБД	Да
`scheme`	`String`	`http`	Используемый протокол	Да
`index_name_template`	`String`	`{account}--{object}`	Шаблон, по которому будут формироваться индексы	Да

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

Стандартная конфигурация: реляционная СУБД (MySQL)

{
    "dbs": {
        "meta": {
            "type": "mysql",
            "host": "database",
            "user": "webim_site",
            "password": "password",
            "database": "webim_site"
        },
        "pro": {
            "default": {
                "connection": "db1"
            }
        }
    },
    "connections": {
        "db1": {
            "type": "mysql",
            "host": "database",
            "user": "webim_service",
            "password": "password"
        }
    }
}

Рекомендуемая конфигурация: реляционная СУБД (MySQL), колоночная СУБД (ClickHouse)

{
    "dbs": {
        "meta": {
            "type": "mysql",
            "host": "database",
            "user": "webim_site",
            "password": "password",
            "database": "webim_site"
        },
        "pro": {
            "default": {
                "connection": "db1"
            }
        },
        "stats_root": {
            "default": {
                "connection": "ch1"
            }
        },
        "stats": {}
    },
    "connections": {
        "db1": {
            "type": "mysql",
            "host": "database",
            "user": "webim_service",
            "password": "password"
        },
        "ch1": {
            "type": "clickhouse",
            "host": "clickhouse",
            "user": "default",
            "password": "password"
        }
    }
}

Кластер ClickHouse (Webim 10.8 и выше)

{
    "dbs": {
        "meta": {
            "type": "mysql",
            "host": "database",
            "user": "webim_site",
            "password": "password",
            "database": "webim_site"
        },
        "pro": {
            "default": {
                "connection": "db1"
            }
        },
        "stats": {
            "default": {
                "cluster_connection": "cluster_stats",
                "database": "webim_stats",
                "root_user": "default",
                "root_password": "<your-password>"
            }
        }
    },
    "connections": {
        "db1": {
            "type": "mysql",
            "host": "database",
            "user": "webim_service",
            "password": "password"
        },
        "cluster_stats": {
            "type": "clickhouse_cluster",
            "cluster_name": "webim_stats_cluster",
            "nodes": [
                {
                    "type": "clickhouse",
                    "host": "clickhouse-01.local",
                    "port": 9000,
                    "user": "webim_stats",
                    "password": "<your-password>",
                    "weight": 2
                },
                {
                    "type": "clickhouse",
                    "host": "clickhouse-02.local",
                    "port": 9000,
                    "user": "webim_stats",
                    "password": "<your-password>",
                    "weight": 1
                }
            ]
        }
    }
}

Продвинутая конфигурация: реляционная СУБД (MySQL) с репликацией, колоночная СУБД (ClickHouse), поисковый движок (Elasticsearch или OpenSearch)

{
    "dbs": {
        "meta": {
            "type": "mysql",
            "host": "database",
            "user": "webim_site",
            "password": "password",
            "database": "webim_site"
        },
        "pro": {
            "default": {
                "connection": "db1",
                "slave": {
                  "connection": "db2"
                }
            }
        },
        "stats_root": {
            "default": {
                "connection": "ch1"
            }
        },
        "stats": {},
        "elastic": {
            "default": {
                "type": "elastic",
                "host": "elasticsearch",
                "port": 9200,
                "user": "elastic",
                "password": "password",
                "scheme": "http",
                "index_name_template": "{account}-{object}"
            }
        }
    },
    "connections": {
        "db1": {
            "type": "mysql",
            "host": "database",
            "user": "webim_service",
            "password": "password"
        },
        "db2": {
            "type": "mysql",
            "host": "database_replica",
            "user": "webim_service",
            "password": "webim_service"
        },
        "ch1": {
            "type": "clickhouse",
            "host": "clickhouse",
            "user": "default",
            "password": "password"
        }
    }
}

Последнее обновление страницы: 5 апреля 2026 г.