Установка и развертывание

Данный документ применим как для установки персональной версии, так и для корпоративной версии программного продукта. Способы установки для обеих версий одинаковы!!!

Сначала скачайте установочный пакет. По умолчанию используется учётная запись admin/admin.

Чтобы вам было проще понять параметры, которые необходимо настроить при установке, сначала ознакомьтесь с функциональными особенностями мониторинга логов.

Локальное развертывание в режиме Standalone

Подготовительные работы

• Требуется наличие среды Java: установите JDK на сервер и настройте переменные окружения. Рекомендуемые версии: JDK 8, JDK 11, JDK 17.
• Скачайте установочный архив и распакуйте его в нужную директорию.
• Если вы используете Linux‑сервер, установите OpenSSL 3; подробности см. здесь.

NOTE

В современных дистрибутивах Linux OpenSSL 3 обычно уже установлен; проверьте версию командой openssl version.

Инициализация базы данных

• Для метабазы поддерживаются MySQL, PostgreSQL или встроенная SQLite. При выборе MySQL или PostgreSQL предварительно выполните скрипт инициализации: sql/ddl_mysql.sql или sql/ddl_postgres.sql. Если используется встроенная SQLite, дополнительная инициализация не требуется.
• Для базы данных логов доступны ClickHouse, MySQL или PostgreSQL. Необходимо заранее запустить соответствующий скрипт инициализации: sql/access_log_clickhouse.sql, sql/access_log_mysql.sql или sql/access_log_postgres.sql.

IMPORTANT

Если для базы данных логов выбраны MySQL или PostgreSQL, рекомендуется размещать её на отдельном физическом экземпляре по сравнению с метабазой, чтобы обеспечить изоляцию ресурсов.

Настройка параметров

• Отредактируйте файл conf/application.properties следующим образом:

# Единый корневой путь для API‑доступа, например: http://192.168.xx.xx:8520/api/xxx
# Контекст API
dbapi.api.context=api

# Если адрес базы данных не изменён, будет использоваться встроенная SQLite
# Адрес метабазы: можно использовать MySQL, PostgreSQL или встроенную SQLite
spring.datasource.dynamic.datasource.meta-db.driver-class-name=org.sqlite.JDBC
spring.datasource.dynamic.datasource.meta-db.url=jdbc:sqlite::resource:sqlite.db
spring.datasource.dynamic.datasource.meta-db.username=
spring.datasource.dynamic.datasource.meta-db.password=

# Способ записи логов API в базу данных логов (рекомендуется: db, kafka или null)
# "db" — прямое подключение к базе данных логов
# "kafka" — запись логов в Kafka, после чего пользователь самостоятельно собирает их и загружает в базу данных
# "null" — сохранение логов только в локальный файл (logs/dbapi-access.log), который затем нужно самостоятельно импортировать в базу данных
access.log.writer=null

# Адрес базы данных логов; рекомендуется использовать MySQL, PostgreSQL, ClickHouse или Doris. Если мониторинг через веб‑интерфейс не требуется, можно не указывать адрес базы данных
spring.datasource.dynamic.datasource.access-log-db.driver-class-name=ru.yandex.clickhouse.ClickHouseDriver
spring.datasource.dynamic.datasource.access-log-db.url=jdbc:clickhouse://127.0.0.1:8123/default
spring.datasource.dynamic.datasource.access-log-db.username=default
spring.datasource.dynamic.datasource.access-log-db.password=123456

# Если access.log.writer=кafka, дополнительно необходимо указать адрес Kafka и имя топика для записи логов
access.log.kafka.topic=dbapi_access_log
spring.kafka.bootstrap-servers=127.0.0.1:9092

• ( Необязательно ) Настройка автоматической очистки логов

Если вы используете базу данных логов, можно настроить автоматическую очистку записей. Для этого отредактируйте файл conf/application.properties следующим образом:

# Включить или отключить автоматическую очистку логов доступа (true/false)
access.log.autoClean.enable=false

# Расписание задачи очистки логов (по умолчанию выполняется ежедневно в 3:00 утра)
access.log.autoClean.cron=0 0 3 * * ?

# Количество дней хранения логов перед очисткой (по умолчанию — 15 дней)
access.log.autoClean.retention.days=15

NOTE

Эта настройка доступна только в корпоративной версии.

• ( Необязательно ) Изменение порта

Измените значение параметра server.port в файле conf/application-standalone.properties:

server.port=8520

• ( Необязательно ) Ограничение доступа к веб‑интерфейсу

Отредактируйте параметр dbapi.ui.allowed.ips в файле conf/application-standalone.properties:

# В режиме Standalone задаётся список IP‑адресов, имеющих доступ к веб‑интерфейсу; если не указано, доступ предоставляется всем
dbapi.ui.allowed.ips=

• ( Необязательно ) Настройка параметров памяти

Измените значение параметра standalone_opts в файле bin/jvm_env.properties:

# standalone_opts="-Xms1g -Xmx4g -Xmn2g"

Можно оставить значения по умолчанию.

• ( Необязательно ) Указание пути к команде Java

Если на вашем сервере установлено несколько версий JDK и требуется использовать определённую версию, настройте этот параметр. Если не указывать, будет использоваться команда Java из переменных окружения.

Укажите полный путь к команде Java в файле bin/jvm_env.properties, например: /usr/bin/java.

JAVA_LOCATION="/usr/bin/java"

Команды запуска

Linux

• Используйте скрипты для запуска и остановки:

# Для систем Ubuntu/Debian используйте bash, а не sh
bash bin/dbapi-daemon.sh start standalone
bash bin/dbapi-daemon.sh stop standalone

# Перезапуск
bash bin/dbapi-daemon.sh restart standalone

# Проверка статуса
bash bin/dbapi-daemon.sh status standalone

• Чтобы запустить процесс в фоновом режиме для просмотра логов, выполните:

bash bin/dbapi.sh start standalone

Windows

• Щёлкните правой кнопкой мыши по файлу bin/dbapi.ps1 и выберите «Запустить с помощью PowerShell».
• Для запуска в фоновом режиме выполните в PowerShell команду bin/start.ps1.
• Чтобы остановить сервис, запущенный с помощью bin/start.ps1, выполните в PowerShell команду bin/stop.ps1.

NOTE

Файлы логов в режиме Standalone сохраняются в logs/dbapi-standalone.log.

NOTE

Система Windows поддерживает только режим Standalone, не поддерживая кластерный режим.

WARNING

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

• Откройте браузер и перейдите по адресу http://192.168.xx.xx:8520 для входа в веб‑интерфейс.

TIP

Если ранее была установлена старая версия, нажмите Ctrl+F5, чтобы принудительно обновить кэш браузера и избежать проблем, связанных с кэшированием страниц.

Локальное развертывание в кластерном режиме

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

• В кластере существуют три типа служебных процессов: manager, gateway и apiServer.
• manager — это административный сервис, предоставляющий веб‑интерфейс. Через него можно создавать источники данных, группы и API, а также управлять онлайн‑отладкой, выполнением, публикацией и снятием API с публичного доступа. В кластере существует только один такой процесс.
• gateway — шлюзовый сервис, распределяющий запросы API между различными apiServer. В кластере существует только один такой процесс.
• apiServer — сервис, обрабатывающий API‑запросы и выполняющий бизнес‑логику внутри API. В кластере может быть несколько таких процессов.

Подготовительные работы

• Для развертывания кластера требуются Nacos, база данных (MySQL или PostgreSQL) и Redis. Сначала установите Nacos (рекомендуется версия 1.4.2), базу данных (MySQL или PostgreSQL) и Redis.
• Подготовьте несколько Linux‑серверов, на каждом из которых установите JDK; рекомендуемые версии: JDK 8, JDK 11, JDK 17.
• На каждом сервере установите OpenSSL 3; подробности см. здесь.

NOTE

В современных дистрибутивах Linux OpenSSL 3 обычно уже установлен; проверьте версию командой openssl version.

Важное замечание:

Время на всех серверах должно быть синхронизировано.

Если вы включили брандмауэр, убедитесь, что manager может обращаться к gateway и apiServer, а gateway — к apiServer.

Настройка SSH без пароля

• Выберите один сервер — host1 — в качестве машины для развертывания и настройте безпарольный доступ SSH со стороны host1 ко всем остальным серверам.

ssh-keygen -t rsa -P '' -f ~/.ssh/id_rsa
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

for ip in host2 host3;     # Замените host2 и host3 на имена ваших серверов
do
  ssh-copy-id $ip   # Во время этой операции потребуется ввести пароль пользователя, который выполняет развертывание
done

Скачивание и распаковка

• Скачайте установочный пакет и распакуйте его в директорию, предназначенную для развертывания, на сервере host1.

Инициализация базы данных

• Для кластерного развертывания метабаза поддерживается MySQL или PostgreSQL. Предварительно выполните скрипт инициализации: sql/ddl_mysql.sql или sql/ddl_postgres.sql.
• База данных логов поддерживает ClickHouse, MySQL или PostgreSQL. Необходимо заранее запустить соответствующий скрипт инициализации: sql/access_log_clickhouse.sql, sql/access_log_mysql.sql или sql/access_log_postgres.sql.

IMPORTANT

Если для базы данных логов выбраны MySQL или PostgreSQL, рекомендуется размещать её на отдельном физическом экземпляре по сравнению с метабазой, чтобы обеспечить изоляцию ресурсов.

Настройка параметров

• Отредактируйте файл conf/application.properties следующим образом:

#################################### Пожалуйста, настройте параметры ниже #####################################
# Единый корневой путь для API‑доступа, например: http://192.168.xx.xx:8520/api/xxx
# Контекст API
dbapi.api.context=api

# Адрес метабазы: в кластерном режиме допустимо использовать только MySQL или PostgreSQL
spring.datasource.dynamic.datasource.meta-db.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.dynamic.datasource.meta-db.url=jdbc:mysql://127.0.0.1:3306/dbapi?useSSL=false&characterEncoding=UTF-8&serverTimezone=GMT%2B8
spring.datasource.dynamic.datasource.meta-db.username=root
spring.datasource.dynamic.datasource.meta-db.password=root

# Способ записи логов API в базу данных логов: возможны варианты "db", "kafka" или "null"
# "db" — прямое подключение к базе данных логов
# "kafka" — запись логов в Kafka, после чего пользователь самостоятельно собирает их и загружает в базу данных
# "null" — сохранение логов только в локальном файле (logs/dbapi-access.log), который затем нужно самостоятельно импортировать в базу данных
access.log.writer=null

# Адрес базы данных логов; рекомендуется использовать ClickHouse, MySQL, PostgreSQL или Doris. Если мониторинг через веб‑интерфейс не требуется, можно не указывать адрес базы данных
spring.datasource.dynamic.datasource.access-log-db.driver-class-name=ru.yandex.clickhouse.ClickHouseDriver
spring.datasource.dynamic.datasource.access-log-db.url=jdbc:clickhouse://127.0.0.1:8123/default
spring.datasource.dynamic.datasource.access-log-db.username=default
spring.datasource.dynamic.datasource.access-log-db.password=123456

# Если access.log.writer=kafka, дополнительно необходимо указать адрес Kafka и имя топика для записи логов
access.log.kafka.topic=dbapi_access_log
spring.kafka.bootstrap-servers=127.0.0.1:9092

############################## Если используется кластер, пожалуйста, настройте параметры ниже ##############################

# Адрес Nacos; необходим при работе в кластерном режиме
spring.cloud.nacos.server-addr=127.0.0.1:8848
spring.cloud.nacos.discovery.username=nacos
spring.cloud.nacos.discovery.password=nacos
spring.cloud.nacos.discovery.namespace=public

# Адрес Redis; необходим при работе в кластерном режиме
spring.redis.host=localhost
spring.redis.port=6379
spring.redis.database=0
spring.redis.password=

Режим Sentinel для Redis

Если Redis работает в режиме Sentinel, необходимо изменить соответствующие настройки Redis следующим образом:

spring.redis.sentinel.master=mymaster
spring.redis.sentinel.nodes=192.168.3.10:26379,192.168.3.10:26380,192.168.3.10:26381
spring.redis.password=123456
spring.redis.timeout=2000ms

• ( Необязательно ) Настройка автоматической очистки логов

Если вы используете базу данных для хранения логов, можно настроить автоматическую очистку записей в этой базе. Для этого измените следующие параметры в файле conf/application.properties:

# Включить или отключить автоматическую очистку логов доступа (true/false)
access.log.autoClean.enable=false

# Расписание задачи очистки логов (по умолчанию выполняется ежедневно в 3:00 утра)
access.log.autoClean.cron=0 0 3 * * ?

# Количество дней хранения логов перед их удалением (по умолчанию — 15 дней)
access.log.autoClean.retention.days=15

NOTE

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

• ( Необязательно ) Изменение портов

Измените порт gateway в файле conf/application-gateway.yml:

server:
  port: 8525

Измените порт manager в файле conf/application-manager.properties:

server.port=8523

Измените порт apiServer в файле conf/application-apiServer.properties:

server.port=8524

CAUTION

Если вы включили брандмауэр, после изменения портов не забудьте настроить правила брандмауэра, чтобы обеспечить доступ manager к gateway и apiServer, а также gateway к apiServer.

• ( Необязательно ) Изменение параметров памяти

Измените значения manager_opts, apiServer_opts и gateway_opts в файле bin/jvm_env.properties:

# Параметры JVM для manager при кластерном развертывании
#manager_opts="-Xms512m -Xmx1g -Xmn512m"

# Параметры JVM для apiServer при кластерном развертывании
#apiServer_opts="-Xms1g -Xmx4g -Xmn2g"

# Параметры JVM для gateway при кластерном развертывании
#gateway_opts="-Xms1g -Xmx4g -Xmn2g"

Можно оставить значения по умолчанию.

• ( Необязательно ) Настройка пути к команде Java

Если у вас установлено несколько версий JDK и требуется использовать определённую версию, настройте этот параметр. Если не указывать, по умолчанию будет использоваться команда Java из переменной окружения.

Измените значение JAVA_LOCATION в файле bin/jvm_env.properties, указав полный путь к команде Java, например /usr/bin/java:

JAVA_LOCATION="/usr/bin/java"

WARNING

При развертывании кластерной версии настоятельно рекомендуем настроить этот параметр, поскольку скрипты запуска кластера используют SSH для удалённого выполнения команд Java. Однако при удалённом выполнении SSH по умолчанию не загружаются переменные окружения, что может привести к неправильному распознаванию команды Java системы.

• Измените файл conf/install_config.conf, указав узлы, на которых планируется установка:

# IP-адреса или имена хостов всех машин, на которых будет установлена DBApi, разделённые запятыми
ips=host1,host2,host3

sshPort=22

# Хост, на котором будет установлен gateway
gateway=host1

# Хосты, на которых будут установлены apiServer, разделённые запятыми
apiServers=host1,host2,host3

# Хост, на котором будет установлен manager
manager=host2

Копирование установочных файлов

• Скопируйте установочные файлы с машины host1 в одинаковую директорию на всех остальных машинах; можно воспользоваться скриптом для быстрого копирования:

bash bin/scp-host.sh

Команды запуска

• Скрипты управления кластером:

# Запустить кластер одним нажатием
bash bin/start-all.sh

# Остановить кластер одним нажатием
bash bin/stop-all.sh

# Просмотреть статус кластера одним нажатием
bash bin/status-all.sh

# Ручной запуск/остановка отдельных сервисов
bash bin/dbapi-daemon.sh start gateway
bash bin/dbapi-daemon.sh start manager
bash bin/dbapi-daemon.sh start apiServer

bash bin/dbapi-daemon.sh stop gateway
bash bin/dbapi-daemon.sh stop manager
bash bin/dbapi-daemon.sh stop apiServer

# Ручная перезагрузка отдельных сервисов
bash bin/dbapi-daemon.sh restart gateway
bash bin/dbapi-daemon.sh restart manager
bash bin/dbapi-daemon.sh restart apiServer

# Ручной запуск отдельного сервиса в фоновом режиме (логи можно просматривать в консоли)
bash bin/dbapi.sh start gateway
bash bin/dbapi.sh start manager
bash bin/dbapi.sh start apiServer

INFO

Обратите внимание: если используется система ubuntu/debian, используйте команду bash, а не sh.

NOTE

У процессов gateway, apiServer и manager в кластерной версии есть свои собственные лог‑файлы: logs/dbapi-gateway.log, logs/dbapi-apiServer.log, logs/dbapi-manager.log.

WARNING

При первом запуске система автоматически завершится; необходимо выполнить активацию, после чего перезагрузить систему — и всё готово к работе. Обязательно активируйте! Активируйте! Активируйте! Лицензия необходима для использования! Лицензия необходима для использования! Лицензия необходима для использования!

• Откройте интерфейс пользователя по адресу http://192.168.xx.xx:8523. API доступен через gateway по адресу http://192.168.xx.xx:8525/api/xx.

TIP

Если ранее вы использовали более старую версию, чтобы избежать кэширования браузера предыдущей версии, выполните принудительное обновление страницы в браузере: Ctrl+F5.

Установка MCP

Сервис MCP является отдельным компонентом DBAPI и может быть развернут независимо от однопользовательской или кластерной версии DBAPI. Даже без использования MCP основные функции DBAPI продолжают работать нормально.

Подготовка

• Убедитесь, что однопользовательская или кластерная версия DBAPI уже установлена и запущена. Только при наличии работающего DBAPI сервис MCP сможет функционировать.

Изменение конфигурации

• Перейдите в каталог установки DBAPI и отредактируйте файл mcp/mcp-config.yaml:

base_url: "http://127.0.0.1:8520"
admin_username: "admin"
admin_password: "admin"
mcp_port: 8526
refresh_interval: 60

• Пояснения к параметрам:
  • base_url: URL доступа к DBAPI. При кластерном развертывании укажите адрес сервиса manager.
  • admin_username и admin_password: учётные данные администратора DBAPI.
  • mcp_port: порт, на котором слушает сервис MCP.
  • refresh_interval: интервал обновления данных инструментами MCP, в секундах; по умолчанию — 60 секунд.

Запуск сервиса MCP

• После перехода в каталог установки DBAPI выполните команду:

# Запустить в фоновом режиме
bash bin/dbapi-mcp.sh start

# Остановить, проверить статус, перезапустить
bash bin/dbapi-mcp.sh stop
bash bin/dbapi-mcp.sh status
bash bin/dbapi-mcp.sh restart

# Запустить в интерактивном режиме
bash bin/dbapi-mcp.sh fg

• В Windows можно дважды щёлкнуть по файлу bin\dbapi-mcp.bat, чтобы запустить сервис MCP.

Использование сервиса MCP

• Сервис MCP по умолчанию слушает на адресе http://127.0.0.1:8526, а точка доступа MCP — http://127.0.0.1:8526/mcp.
• По умолчанию сервис MCP использует протокол streamableHttp.
• При обращении к закрытым API необходимо использовать токен. При вызове сервиса клиент MCP должен добавить в заголовок запроса строку Authorization следующего формата:

Authorization: <token>

• Этот токен можно получить через API запроса токена в DBAPI. Например, для Cherry Studio настройки выглядят так:

Приложения

• Быстрая установка Nacos с помощью Docker:

docker run --env MODE=standalone --name nacos -d -p 8848:8848 nacos/nacos-server:1.4.2