Installation et déploiement

Ce document s’applique à la fois à l’installation de la version personnelle et de la version entreprise du logiciel ; les deux versions suivent exactement la même procédure d’installation !

Veuillez d’abord télécharger le package d’installation. Le compte par défaut est admin/admin.

Afin de faciliter la compréhension des paramètres à configurer lors de l’installation, nous vous invitons à consulter au préalable la documentation relative aux fonctionnalités de surveillance des journaux.

Déploiement local en mode mono‑serveur

Préparatifs

Dépendance à l’environnement Java : veuillez installer le JDK sur votre serveur et configurer les variables d’environnement. Les versions recommandées sont JDK 8, JDK 11 ou JDK 17.
Téléchargez le package d’installation et décompressez‑le dans le répertoire souhaité.
Sur un serveur Linux, installez OpenSSL 3 ; pour cela, référez-vous à cette page.

NOTE

Dans la plupart des distributions Linux récentes, OpenSSL 3 est déjà inclus. Vous pouvez vérifier la version d’OpenSSL avec la commande openssl version.

Initialisation de la base de données

La base de données métadonnées prend en charge MySQL, PostgreSQL ou SQLite intégré. Si vous choisissez MySQL ou PostgreSQL, exécutez préalablement le script d’initialisation sql/ddl_mysql.sql ou sql/ddl_postgres.sql. Pour SQLite intégré, aucune initialisation supplémentaire n’est requise.
La base de données des journaux peut être ClickHouse, MySQL ou PostgreSQL. Exécutez préalablement le script d’initialisation correspondant : sql/access_log_clickhouse.sql, sql/access_log_mysql.sql ou sql/access_log_postgres.sql.

IMPORTANT

Si vous utilisez MySQL ou PostgreSQL pour la base de données des journaux, il est recommandé de déployer cette base sur un serveur physique distinct de celui de la base de données métadonnées afin d’assurer une isolation des ressources.

Configuration des paramètres

Modifiez les paramètres suivants dans le fichier conf/application.properties :

properties

# Chemin racine uniforme pour les accès API, par exemple : http://192.168.xx.xx:8520/api/xxx
# Contexte API
dbapi.api.context=api

# Si l’adresse de la base de données n’est pas modifiée, la base de données métadonnées intégrée SQLite sera utilisée par défaut
# Adresse de la base de données métadonnées : MySQL, PostgreSQL ou SQLite intégré
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=

# Méthode d’écriture des journaux d’accès dans la base de données des journaux (recommandée : MySQL/PostgreSQL/ClickHouse/Doris) ; valeur possible : db/kafka/null
# « db » signifie que les journaux d’accès sont directement écrits dans la base de données des journaux via dbapi
# « kafka » signifie que dbapi envoie les journaux d’accès à Kafka, et que l’utilisateur doit ensuite collecter ces journaux depuis Kafka pour les transférer vers la base de données des journaux
# « null » signifie que dbapi enregistre uniquement les journaux d’accès dans un fichier local (logs/dbapi-access.log), et que l’utilisateur doit ensuite récupérer ces fichiers pour les charger dans la base de données des journaux
access.log.writer=null

# Adresse de la base de données des journaux ; recommandation : MySQL/PostgreSQL/ClickHouse/Doris. Si vous n’utilisez pas la fonction de surveillance via l’interface web, cette configuration peut être omise
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

# Si access.log.writer est configuré sur « kafka », vous devez également spécifier l’adresse Kafka ainsi que le nom du topic utilisé pour l’écriture des journaux
access.log.kafka.topic=dbapi_access_log
spring.kafka.bootstrap-servers=127.0.0.1:9092

( Optionnel ) Configurez la suppression automatique des journaux

Si vous utilisez une base de données des journaux, vous pouvez activer la suppression automatique des journaux stockés dans cette base. Modifiez les paramètres suivants dans le fichier conf/application.properties :

properties

# Activation ou désactivation de la suppression automatique des journaux d’accès (true/false)
access.log.autoClean.enable=false

# Fréquence de lancement de la tâche de nettoyage des journaux (exprimée en cron, exécutée quotidiennement à 3 h du matin par défaut)
access.log.autoClean.cron=0 0 3 * * ?

# Nombre maximal de jours de conservation des journaux avant leur suppression (15 jours par défaut)
access.log.autoClean.retention.days=15

NOTE

Cette option n’est disponible que dans la version entreprise du logiciel.

( Optionnel ) Modifiez le port utilisé

Modifiez la propriété server.port dans le fichier conf/application-standalone.properties :

properties

server.port=8520

( Optionnel ) Spécifiez les adresses IP autorisées à accéder à l’interface utilisateur

Modifiez la propriété dbapi.ui.allowed.ips dans le fichier conf/application-standalone.properties :

properties

# En mode mono‑serveur, indiquez les adresses IP autorisées à accéder à l’interface utilisateur ; si non spécifié, toutes les adresses IP sont autorisées
dbapi.ui.allowed.ips=

( Optionnel ) Ajustez les paramètres mémoire

Modifiez la valeur de la propriété standalone_opts dans le fichier bin/jvm_env.properties :

properties

# standalone_opts="-Xms1g -Xmx4g -Xmn2g"

Vous pouvez conserver les valeurs par défaut sans modification.

( Optionnel ) Configurez l’emplacement de la commande Java

Si vous avez installé plusieurs versions du JDK, veuillez spécifier la version à utiliser. Cette configuration est facultative ; si elle n’est pas définie, la commande Java par défaut définie dans les variables d’environnement sera utilisée.

Modifiez la propriété JAVA_LOCATION dans le fichier bin/jvm_env.properties en indiquant le chemin complet vers la commande Java, par exemple /usr/bin/java :

properties

JAVA_LOCATION="/usr/bin/java"

Commandes de démarrage

Linux

Utilisez les scripts pour démarrer et arrêter le service :

shell

# Sur Ubuntu/Debian, utilisez bash plutôt que sh
bash bin/dbapi-daemon.sh start standalone
bash bin/dbapi-daemon.sh stop standalone

# Redémarrage
bash bin/dbapi-daemon.sh restart standalone

# Vérification de l’état
bash bin/dbapi-daemon.sh status standalone

Pour exécuter le service en mode interactif afin de visualiser les journaux, utilisez la commande suivante :

shell

bash bin/dbapi.sh start standalone

Windows

Cliquez avec le bouton droit sur le fichier bin/dbapi.ps1 et sélectionnez « Exécuter avec PowerShell ».
Pour exécuter le service en arrière-plan, lancez bin/start.ps1 avec PowerShell.
Pour arrêter le service lancé via bin/start.ps1, exécutez bin/stop.ps1 avec PowerShell.

NOTE

Les fichiers journaux en mode mono‑serveur sont enregistrés dans logs/dbapi-standalone.log.

NOTE

Le système Windows ne supporte que le mode standalone ; le mode cluster n’est pas pris en charge.

WARNING

Après le premier démarrage, le système se ferme automatiquement. Vous devez effectuer l’activation puis redémarrer pour pouvoir utiliser le logiciel.

Ouvrez votre navigateur et accédez à l’URL http://192.168.xx.xx:8520 pour accéder à l’interface utilisateur.

TIP

Si vous avez déjà installé une ancienne version, appuyez sur Ctrl+F5 pour forcer le rafraîchissement du cache du navigateur et éviter tout problème lié au cache de la page.

Déploiement local en mode cluster

Description des rôles dans le cluster

Le cluster comprend trois types de processus de service : manager, gateway et apiServer.
Le processus manager est le service d’administration, c’est‑à‑dire le service de l’interface web. Grâce à cette interface, vous pouvez créer des sources de données, des groupes et des API, ainsi que gérer les opérations de débogage en ligne, d’exécution, de publication et de mise hors ligne des API. Un seul processus manager existe dans l’ensemble du cluster.
Le processus gateway est le service de passerelle, chargé de distribuer les requêtes API vers les différents apiServer. Un seul processus gateway existe dans l’ensemble du cluster.
Le processus apiServer est le service API, responsable de recevoir les requêtes API et d’exécuter la logique métier associée. Le nombre de processus apiServer peut varier dans le cluster.

Préparatifs

Le déploiement en cluster nécessite Nacos, une base de données (MySQL ou PostgreSQL) et Redis. Veuillez installer préalablement Nacos (version 1.4.2 recommandée), la base de données (MySQL ou PostgreSQL) et Redis.
Préparez plusieurs serveurs Linux, chacun équipé du JDK ; les versions recommandées sont JDK 8, JDK 11 ou JDK 17.
Installez OpenSSL 3 sur chaque serveur Linux ; reportez‑vous à cette page pour plus de détails.

NOTE

Dans la plupart des systèmes Linux récents, OpenSSL 3 est déjà inclus. Vous pouvez vérifier la version d’OpenSSL avec la commande openssl version.

Remarques importantes

Assurez‑vous que l’heure de tous les serveurs soit correctement synchronisée.

Si vous avez activé un pare‑feu, veillez à ce que le processus manager puisse communiquer avec les processus gateway et apiServer, et que le processus gateway puisse accéder aux processus apiServer.

Configuration SSH sans mot de passe

Sélectionnez un serveur, appelé host1, comme machine de déploiement, et configurez l’accès SSH sans mot de passe entre host1 et chaque autre serveur.

shell

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;     # Remplacez ici host2 et host3 par les noms d’hôte des machines que vous souhaitez déployer
do
  ssh-copy-id $ip   # Lors de cette opération, vous devrez saisir manuellement le mot de passe de l’utilisateur de déploiement
done

Téléchargement et décompression

Téléchargez le package d’installation et décompressez‑le dans le répertoire prévu sur la machine de déploiement, host1.

Initialisation de la base de données

Pour le déploiement en cluster, la base de données métadonnées peut être MySQL ou PostgreSQL. Exécutez préalablement le script d’initialisation sql/ddl_mysql.sql ou sql/ddl_postgres.sql.
La base de données des journaux peut être ClickHouse, MySQL ou PostgreSQL. Exécutez préalablement le script d’initialisation correspondant : sql/access_log_clickhouse.sql, sql/access_log_mysql.sql ou sql/access_log_postgres.sql.

IMPORTANT

Si vous choisissez MySQL ou PostgreSQL pour la base de données des journaux, il est recommandé de déployer cette base sur un serveur physique distinct de celui de la base de données métadonnées afin d’assurer une isolation des ressources.

Configuration des paramètres

Modifiez les paramètres suivants dans le fichier conf/application.properties :

properties

#################################### Veuillez configurer les paramètres ci‑dessous #####################################
# Chemin racine uniforme pour les accès API, par exemple : http://192.168.xx.xx:8520/api/xxx
# Contexte API
dbapi.api.context=api

# Adresse de la base de données métadonnées ; en mode cluster, seule MySQL ou PostgreSQL est autorisée
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

# Méthode d’écriture des journaux d’accès dans la base de données des journaux ; valeur possible : db/kafka/null
# « db » signifie que les journaux d’accès sont directement écrits dans la base de données des journaux via dbapi
# « kafka » signifie que dbapi envoie les journaux d’accès à Kafka, et que l’utilisateur doit ensuite collecter ces journaux depuis Kafka pour les transférer vers la base de données des journaux
# « null » signifie que dbapi enregistre uniquement les journaux d’accès dans un fichier local (logs/dbapi-access.log), et que l’utilisateur doit ensuite récupérer ces fichiers pour les charger dans la base de données des journaux
access.log.writer=null

# Adresse de la base de données des journaux ; recommandation : ClickHouse/MySQL/PostgreSQL/Doris. Si vous n’utilisez pas la fonction de surveillance via l’interface web, cette configuration peut être omise
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

# Si access.log.writer est configuré sur « kafka », vous devez également spécifier l’adresse Kafka ainsi que le nom du topic utilisé pour l’écriture des journaux
access.log.kafka.topic=dbapi_access_log
spring.kafka.bootstrap-servers=127.0.0.1:9092

############################## Si le cluster est activé, veuillez configurer les paramètres ci‑dessous ##############################

# Adresse de Nacos ; nécessaire en mode cluster
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

# Adresse de Redis ; nécessaire en mode cluster
spring.redis.host=localhost
spring.redis.port=6379
spring.redis.database=0
spring.redis.password=

Mode sentinel de Redis

Si Redis est utilisé en mode sentinel, il convient de modifier les configurations correspondantes comme suit :

properties

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

( Optionnel ) Configurer la suppression automatique des journaux

Si vous utilisez une base de données dédiée aux journaux, vous pouvez configurer la suppression automatique des logs dans cette base. Modifiez les paramètres suivants dans le fichier conf/application.properties :

properties

# Activer ou désactiver la suppression automatique des journaux d'accès (true/false)
access.log.autoClean.enable=false

# Expression Cron pour planifier l'exécution de la tâche de nettoyage des journaux d'accès (par défaut, chaque jour à 3h00 du matin)
access.log.autoClean.cron=0 0 3 * * ?

# Nombre maximal de jours de conservation des journaux avant leur suppression (par défaut : 15 jours)
access.log.autoClean.retention.days=15

NOTE

Seule la version entreprise du logiciel prend en charge cette configuration.

( Optionnel ) Modifier le port

Modifiez le port du gateway dans le fichier conf/applicaton-gateway.yml, sous la clé server.port :

yml

server:
  port: 8525

Modifiez le port du manager dans le fichier conf/applicaton-manager.properties, sous la clé server.port :

properties

server.port=8523

Modifiez le port du apiServer dans le fichier conf/applicaton-apiServer.properties, sous la clé server.port :

properties

server.port=8524

CAUTION

Si vous avez activé un pare-feu, veuillez ajuster les règles après avoir modifié les ports afin de garantir que le manager puisse accéder au gateway et au apiServer, et que le gateway puisse accéder au apiServer.

( Optionnel ) Modifier les paramètres mémoire

Modifiez les valeurs des options JVM dans le fichier bin/jvm_env.properties pour le manager, le apiServer et le gateway :

properties

# Configuration des options JVM pour le manager en mode cluster
#manager_opts="-Xms512m -Xmx1g -Xmn512m"

# Configuration des options JVM pour l'apiServer en mode cluster
#apiServer_opts="-Xms1g -Xmx4g -Xmn2g"

# Configuration des options JVM pour le gateway en mode cluster
#gateway_opts="-Xms1g -Xmx4g -Xmn2g"

Vous pouvez également conserver les valeurs par défaut sans modification.

( Optionnel ) Configurer le chemin d'accès à la commande Java

Si vous avez installé plusieurs versions de JDK et que vous souhaitez utiliser une version spécifique, configurez ce paramètre. Vous pouvez choisir de ne pas le configurer ; dans ce cas, la commande Java définie dans les variables d'environnement sera utilisée par défaut.

Modifiez la valeur de la clé JAVA_LOCATION dans le fichier bin/jvm_env.properties, en indiquant le chemin complet vers la commande Java, par exemple /usr/bin/java :

properties

JAVA_LOCATION="/usr/bin/java"

WARNING

Pour le déploiement en cluster, nous vous recommandons vivement de configurer ce paramètre, car les scripts de démarrage du cluster exécutent la commande Java via SSH. Or, lors de l'exécution distante via SSH, les variables d'environnement ne sont pas chargées par défaut, ce qui peut empêcher la reconnaissance correcte de la commande Java système.

Modifiez le fichier conf/install_config.conf pour spécifier les nœuds à installer :

shell

# Tous les adresses IP ou noms d'hôtes des machines sur lesquelles DBApi doit être installé, séparés par des virgules
ips=host1,host2,host3

sshPort=22

# Hôte sur lequel installer le gateway
gateway=host1

# Hôtes sur lesquels installer l'apiServer, séparés par des virgules
apiServers=host1,host2,host3

# Hôte sur lequel installer le manager
manager=host2

Copie des fichiers d'installation

Copiez les fichiers d'installation depuis l'hôte host1 vers le même répertoire sur chacune des autres machines, en utilisant un script pour automatiser cette opération :

shell

bash bin/scp-host.sh

Commandes de démarrage

Scripts d'exploitation du cluster

shell

# Démarrer le cluster en un clic
bash bin/start-all.sh

# Arrêter le cluster en un clic
bash bin/stop-all.sh

# Vérifier l'état du cluster en un clic
bash bin/status-all.sh

# Démarrer ou arrêter manuellement un service individuel
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

# Redémarrer manuellement un service individuel
bash bin/dbapi-daemon.sh restart gateway
bash bin/dbapi-daemon.sh restart manager
bash bin/dbapi-daemon.sh restart apiServer

# Démarrer un service individuel en mode interactif (avec affichage des journaux en temps réel)
bash bin/dbapi.sh start gateway
bash bin/dbapi.sh start manager
bash bin/dbapi.sh start apiServer

INFO

Attention : si vous utilisez un système ubuntu/debian, veuillez utiliser la commande bash et non sh.

NOTE

Dans la version cluster, les trois services — gateway, apiServer et manager — disposent chacun de leurs propres fichiers journaux, respectivement nommés logs/dbapi-gateway.log, logs/dbapi-apiServer.log et logs/dbapi-manager.log.

WARNING

Lors du premier démarrage, le système se ferme automatiquement ; il est nécessaire d'effectuer une activation (voir activate). Après l'activation, redémarrez pour pouvoir utiliser le système. N'oubliez pas : activation ! Activation ! Activation ! Il faut demander une licence pour pouvoir utiliser le logiciel !

Accédez à l'interface utilisateur via le navigateur à l'adresse http://192.168.xx.xx:8523. Les API sont accessibles via le gateway à l'adresse http://192.168.xx.xx:8525/api/xx.

TIP

Si vous avez déjà utilisé une version antérieure, veuillez effectuer un rafraîchissement forcé du cache du navigateur en appuyant simultanément sur Ctrl+F5 afin d'éviter tout problème lié au cache du navigateur.

Installation de MCP

Le service MCP est un composant indépendant de DBAPI, pouvant être déployé séparément, hors de la version standalone ou cluster de DBAPI. Même sans utiliser le service MCP, les fonctionnalités essentielles de DBAPI restent pleinement opérationnelles.

Préparation

Assurez-vous que la version standalone ou cluster de DBAPI est déjà installée et fonctionne correctement. Le service MCP ne peut fonctionner que lorsque DBAPI est disponible.

Modification des configurations

Accédez au répertoire d'installation de DBAPI et éditez le fichier mcp/mcp-config.yaml :

yml

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

Description des paramètres :
- base_url : Adresse d'accès à DBAPI. En mode cluster, veuillez indiquer l'adresse du service manager.
- admin_username et admin_password : Identifiants administrateurs de DBAPI.
- mcp_port : Port d'écoute du service MCP.
- refresh_interval : Intervalle de rafraîchissement de l'outil MCP, en secondes ; par défaut, 60 secondes.

Démarrage du service MCP

Une fois dans le répertoire d'installation de DBAPI, exécutez la commande suivante :

shell

# Démarrer en arrière-plan
bash bin/dbapi-mcp.sh start

# Arrêter, vérifier l'état ou redémarrer
bash bin/dbapi-mcp.sh stop
bash bin/dbapi-mcp.sh status
bash bin/dbapi-mcp.sh restart

# Démarrer en mode interactif
bash bin/dbapi-mcp.sh fg

Sous Windows, double-cliquez sur le fichier bin\dbapi-mcp.bat pour lancer le service MCP.

Utilisation du service MCP

Par défaut, le service MCP écoute sur l'adresse http://127.0.0.1:8526, et son point d'accès est http://127.0.0.1:8526/mcp.
Le service MCP utilise par défaut la méthode streamableHttp.
Lors de l'accès à des API privées, un jeton d'autorisation est obligatoire. Lorsque le client MCP effectue une requête, il doit ajouter l'en-tête Authorization avec le format suivant :

text

Authorization: <token>

Ce jeton peut être obtenu via l'API d'obtention de jetons de DBAPI. Prenons Cherry Studio comme exemple ; voici la configuration correspondante :

Annexes

Installation rapide de Nacos via Docker

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

Installation et déploiement ​

Déploiement local en mode mono‑serveur ​

Préparatifs ​

Initialisation de la base de données ​

Configuration des paramètres ​

Commandes de démarrage ​

Linux ​

Windows ​

Déploiement local en mode cluster ​

Description des rôles dans le cluster ​

Préparatifs ​

Configuration SSH sans mot de passe ​

Téléchargement et décompression ​

Initialisation de la base de données ​

Configuration des paramètres ​

Copie des fichiers d'installation ​

Commandes de démarrage ​

Installation de MCP ​

Préparation ​

Modification des configurations ​

Démarrage du service MCP ​

Utilisation du service MCP ​

Annexes ​

Installation et déploiement

Déploiement local en mode mono‑serveur

Préparatifs

Initialisation de la base de données

Configuration des paramètres

Commandes de démarrage

Linux

Windows

Déploiement local en mode cluster

Description des rôles dans le cluster

Préparatifs

Configuration SSH sans mot de passe

Téléchargement et décompression

Initialisation de la base de données

Configuration des paramètres

Copie des fichiers d'installation

Commandes de démarrage

Installation de MCP

Préparation

Modification des configurations

Démarrage du service MCP

Utilisation du service MCP

Annexes