Instalación y despliegue

Este documento es la documentación técnica del producto de software DBAPI, que abarca el desarrollo de APIs, las operaciones con bases de datos, la configuración del middleware y otros ámbitos relacionados con la informática. Utilice terminología informática profesional y mantenga la precisión técnica. Preserve el formato Markdown (bloques de código, código en línea, negritas, enlaces). NO traduzca los bloques de código, el código en línea, los comandos, los nombres de variables, los nombres de archivos ni las etiquetas de componentes de Vue (por ejemplo, <ComponentName />). Preserve los niveles de encabezados y la estructura original del documento.

Por favor, genere una traducción que se ajuste al contexto de este documento técnico sobre el producto de software DBAPI, que cubre el desarrollo de APIs, las operaciones con bases de datos, la configuración del middleware y otros ámbitos relacionados con la informática. Utilice terminología informática profesional y mantenga la precisión técnica. Preserve el formato Markdown (bloques de código, código en línea, negritas, enlaces). NO traduzca los bloques de código, el código en línea, los comandos, los nombres de variables, los nombres de archivos ni las etiquetas de componentes de Vue (por ejemplo, <ComponentName />). Preserve los niveles de encabezados y la estructura original del documento.

---

Instalación y despliegue

Este documento es válido tanto para la versión personal como para la versión empresarial del software; el procedimiento de instalación es idéntico para ambas versiones.

Primero, descargue el paquete de instalación desde descargar. La cuenta predeterminada es admin/admin.

Para facilitar la comprensión de los parámetros que deben configurarse durante la instalación, le recomendamos leer primero la descripción funcional relacionada con la monitorización de logs.

Despliegue local en modo monousuario

Preparativos

• Requiere un entorno Java: instale previamente JDK en el servidor y configure las variables de entorno. Se recomiendan las versiones JDK 8, JDK 11 o JDK 17.
• Descargue el paquete de instalación y extráigalo en el directorio deseado.
• Si utiliza un servidor Linux, instale OpenSSL 3; consulte aquí para obtener instrucciones detalladas.

[!NOTA] En la mayoría de los sistemas Linux modernos ya viene incluido OpenSSL 3; puede verificar la versión con el comando openssl version.

Inicialización de la base de datos

• La base de datos meta admite MySQL, PostgreSQL o SQLite incorporado. Si elige MySQL o PostgreSQL, debe ejecutar previamente el script de inicialización correspondiente (sql/ddl_mysql.sql o sql/ddl_postgres.sql). Si opta por SQLite integrado, no es necesario realizar ninguna inicialización adicional.
• La base de datos de logs admite ClickHouse, MySQL o PostgreSQL. Debe ejecutar previamente el script de inicialización correspondiente en la base de datos seleccionada: sql/access_log_clickhouse.sql, sql/access_log_mysql.sql o sql/access_log_postgres.sql.

[!IMPORTANTE] Si la base de datos de logs es MySQL o PostgreSQL, se recomienda separarla físicamente de la base de datos meta para garantizar la aislación de recursos.

Configuración de parámetros

• Edite el archivo conf/application.properties y ajuste los siguientes parámetros:

# Ruta raíz unificada para el acceso a la API; por ejemplo: http://192.168.xx.xx:8520/api/xxx
# Contexto de la API
dbapi.api.context=api

# Si no modifica la dirección de la base de datos, se utilizará automáticamente la base de datos interna SQLite
# Dirección de la base de datos meta; puede ser MySQL, PostgreSQL o SQLite incorporado
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étodo para escribir los registros de acceso a la API en la base de datos de logs (recomendado: mysql/postgresql/clickhouse/doris); los valores posibles son db, kafka o null
# 'db' significa que DBAPI conectará directamente la base de datos de logs, escribiendo los registros de acceso allí
# 'kafka' indica que DBAPI enviará los registros de acceso a Kafka, y usted deberá recopilarlos posteriormente desde Kafka para cargarlos en la base de datos de logs
# 'null' significa que DBAPI solo guardará los registros de acceso en un archivo local (`logs/dbapi-access.log`), y usted deberá extraer esos registros manualmente para cargarlos en la base de datos de logs
access.log.writer=null

# Dirección de la base de datos de logs; se recomienda MySQL, PostgreSQL, ClickHouse o Doris. Si no necesita usar las funciones de monitorización en la interfaz web, puede omitir esta configuración
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 configura access.log.writer=kafka, también debe especificar la dirección de Kafka y el nombre del tema donde se almacenarán los registros
access.log.kafka.topic=dbapi_access_log
spring.kafka.bootstrap-servers=127.0.0.1:9092

• ( Opcional ) Configure la limpieza automática de logs.

Si utiliza una base de datos de logs, puede configurar la eliminación automática de los registros almacenados en ella. Edite el archivo conf/application.properties y ajuste los siguientes parámetros:

# Habilitar o deshabilitar la limpieza automática de los registros de acceso (true/false)
access.log.autoClean.enable=false

# Horario de ejecución de la tarea de limpieza; por defecto, se ejecuta todos los días a las 3:00 AM
access.log.autoClean.cron=0 0 3 * * ?

# Número máximo de días que se conservarán los registros antes de la limpieza (por defecto, 15 días)
access.log.autoClean.retention.days=15

[!NOTA] Esta configuración solo está disponible en la versión empresarial del software.

• ( Opcional ) Modifique el puerto de escucha.

Edite el archivo conf/application-standalone.properties y ajuste el valor de server.port:

server.port=8520

• ( Opcional ) Configure qué direcciones IP pueden acceder a la interfaz web.

Edite el archivo conf/application-standalone.properties y ajuste el valor de dbapi.ui.allowed.ips:

# En modo monousuario, especifique las direcciones IP autorizadas para acceder a la interfaz web; si no se configura, todas las IPs tendrán acceso
dbapi.ui.allowed.ips=

• ( Opcional ) Ajuste los parámetros de memoria.

Edite el archivo bin/jvm_env.properties y modifique el valor de standalone_opts:

# standalone_opts="-Xms1g -Xmx4g -Xmn2g"

Puede mantener los valores predeterminados sin modificar.

• ( Opcional ) Configure la ruta del comando Java.

Si tiene instaladas varias versiones de JDK, debe especificar la versión que desea utilizar. Si no lo hace, se usará el comando Java definido en las variables de entorno.

Edite el archivo bin/jvm_env.properties y establezca el valor de JAVA_LOCATION con la ruta completa del comando Java, por ejemplo: /usr/bin/java.

JAVA_LOCATION="/usr/bin/java"

Comandos de inicio

Linux

• Use scripts para iniciar y detener el servicio:

# Para sistemas Ubuntu/Debian, utilice bash en lugar de sh
bash bin/dbapi-daemon.sh start standalone
bash bin/dbapi-daemon.sh stop standalone

# Reiniciar
bash bin/dbapi-daemon.sh restart standalone

# Consultar el estado
bash bin/dbapi-daemon.sh status standalone

• Si desea ejecutarlo en primer plano para poder ver los logs, ejecute:

bash bin/dbapi.sh start standalone

Windows

• Haga clic derecho en bin/dbapi.ps1 y seleccione "Ejecutar con PowerShell".
• Para ejecutarlo en segundo plano, use PowerShell para ejecutar bin/start.ps1.
• Para detener el servicio iniciado con bin/start.ps1, use PowerShell para ejecutar bin/stop.ps1.

[!NOTA] Los archivos de log en modo monousuario se guardan en logs/dbapi-standalone.log.

[!NOTA] El sistema Windows solo admite el modo standalone; no soporta el modo clúster.

[!ADVERTENCIA] Tras el primer inicio, el sistema se cerrará automáticamente; debe completar el proceso de activación y reiniciar para poder usarlo.

• Acceda a la interfaz web mediante el navegador en http://192.168.xx.xx:8520.

[!CONSEJO] Si ya ha instalado una versión anterior, presione Ctrl+F5 para forzar la actualización de la caché del navegador y evitar problemas causados por la caché de la página.

Despliegue local en modo clúster

Descripción de los roles en el clúster

• En un clúster existen tres tipos de procesos de servicio: manager, gateway y apiServer.
• manager es el servicio de administración, es decir, la interfaz web. Desde esta interfaz puede crear fuentes de datos, grupos y APIs, así como gestionar operaciones como la depuración en línea, la ejecución, la publicación y la desactivación de APIs. Existe un único proceso de este tipo en todo el clúster.
• gateway es el servicio de puerta de enlace, responsable de distribuir las solicitudes de API entre los distintos apiServer. También existe un único proceso de este tipo en todo el clúster.
• apiServer es el servicio de API, encargado de recibir las solicitudes de API y ejecutar la lógica comercial correspondiente. En el clúster puede haber varios procesos de este tipo.

Preparativos

• El despliegue en clúster requiere nacos, una base de datos (MySQL o PostgreSQL) y redis. Instale primero nacos (se recomienda la versión 1.4.2), la base de datos (MySQL o PostgreSQL) y redis.
• Prepare varios servidores Linux, cada uno con JDK instalado; se recomiendan las versiones JDK 8, JDK 11 o JDK 17.
• Instale OpenSSL 3 en cada servidor Linux; consulte aquí para obtener instrucciones detalladas.

[!NOTA] En la mayoría de los sistemas Linux modernos ya viene incluido OpenSSL 3; puede verificar la versión con el comando openssl version.

[!PRECAUCIÓN] Notas importantes: Asegúrese de sincronizar la hora en todos los servidores.

Si activó el firewall, verifique que manager pueda acceder a gateway y apiServer, y que gateway tenga acceso a apiServer.

Configuración de SSH sin contraseña

• Elija un servidor, llamado host1, como máquina de despliegue y configure la autenticación SSH sin contraseña entre host1 y cada uno de los demás servidores.

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;     # Reemplace aquí host2 y host3 con los nombres de host de los servidores que va a desplegar
do
  ssh-copy-id $ip   # Durante este proceso, deberá ingresar manualmente la contraseña del usuario de despliegue
done

Descarga y extracción

• Descargue el paquete de instalación y extráigalo en el directorio designado en el servidor de despliegue, host1.

Inicialización de la base de datos

• Para el despliegue en clúster, la base de datos meta admite MySQL o PostgreSQL. Ejecute previamente el script de inicialización correspondiente: sql/ddl_mysql.sql o sql/ddl_postgres.sql.
• La base de datos de logs admite ClickHouse, MySQL o PostgreSQL. Ejecute previamente el script de inicialización correspondiente en la base de datos seleccionada: sql/access_log_clickhouse.sql, sql/access_log_mysql.sql o sql/access_log_postgres.sql.

[!IMPORTANTE] Si la base de datos de logs es MySQL o PostgreSQL, se recomienda separarla físicamente de la base de datos meta para garantizar la aislación de recursos.

Configuración de parámetros

• Edite el archivo conf/application.properties y ajuste los siguientes parámetros:

#################################### Por favor configure los siguientes parámetros #####################################
# Ruta raíz unificada para el acceso a la API; por ejemplo: http://192.168.xx.xx:8520/api/xxx
# Contexto de la API
dbapi.api.context=api

# Dirección de la base de datos meta; en modo clúster solo se admiten MySQL o 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

# Método para escribir los registros de acceso a la API en la base de datos de logs; los valores posibles son db, kafka o null
# 'db' significa que DBAPI conectará directamente la base de datos de logs, escribiendo los registros de acceso allí
# 'kafka' indica que DBAPI enviará los registros de acceso a Kafka, y usted deberá recopilarlos posteriormente desde Kafka para cargarlos en la base de datos de logs
# 'null' significa que DBAPI solo guardará los registros de acceso en un archivo local (`logs/dbapi-access.log`), y usted deberá extraer esos registros manualmente para cargarlos en la base de datos de logs
access.log.writer=null

# Dirección de la base de datos de logs; se recomienda ClickHouse, MySQL, PostgreSQL o Doris. Si no necesita usar las funciones de monitorización en la interfaz web, puede omitir esta configuración
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 configura access.log.writer=kafka, también debe especificar la dirección de Kafka y el nombre del tema donde se almacenarán los registros
access.log.kafka.topic=dbapi_access_log
spring.kafka.bootstrap-servers=127.0.0.1:9092

############################## Si está en modo clúster, por favor configure los siguientes parámetros ##############################

# Dirección de Nacos; necesaria si se utiliza el modo clúster
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

# Dirección de Redis; necesaria si se utiliza el modo clúster
spring.redis.host=localhost
spring.redis.port=6379
spring.redis.database=0
spring.redis.password=

Modo de sentinela de Redis

Si Redis utiliza el modo de sentinela, es necesario modificar la configuración correspondiente a Redis de la siguiente manera:

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

• ( Opcional ) Configuración de la limpieza automática de registros

Si utiliza una base de datos de registros, puede configurar la limpieza automática de los registros almacenados en dicha base de datos. Modifique la siguiente configuración en el archivo conf/application.properties:

# Habilitar o deshabilitar la limpieza automática de los registros de acceso (true/false)
access.log.autoClean.enable=false

# Expresión cron para programar la tarea de limpieza de registros de acceso (por defecto se ejecuta diariamente a las 3:00 AM)
access.log.autoClean.cron=0 0 3 * * ?

# Número de días máximos que se conservarán los registros antes de la limpieza (por defecto 15 días)
access.log.autoClean.retention.days=15

NOTE

Esta configuración solo está disponible en la versión empresarial del software.

• ( Opcional ) Modificación del puerto

Modifique el puerto del gateway en el archivo conf/applicaton-gateway.yml, dentro de la sección server.port:

server:
  port: 8525

Modifique el puerto del manager en el archivo conf/applicaton-manager.properties, dentro de la sección server.port:

server.port=8523

Modifique el puerto del apiServer en el archivo conf/applicaton-apiServer.properties, dentro de la sección server.port:

server.port=8524

CAUTION

Si tiene habilitado un firewall, después de modificar los puertos asegúrese de configurarlo correctamente para permitir que el manager acceda al gateway y al apiServer, y que el gateway pueda acceder al apiServer.

• ( Opcional ) Modificación de los parámetros de memoria

Modifique los valores de manager_opts, apiServer_opts y gateway_opts en el archivo bin/jvm_env.properties:

# Configuración de los parámetros JVM para el manager en despliegue en clúster
#manager_opts="-Xms512m -Xmx1g -Xmn512m"

# Configuración de los parámetros JVM para el apiServer en despliegue en clúster
#apiServer_opts="-Xms1g -Xmx4g -Xmn2g"

# Configuración de los parámetros JVM para el gateway en despliegue en clúster
#gateway_opts="-Xms1g -Xmx4g -Xmn2g"

Puede mantener los valores por defecto sin realizar cambios.

• ( Opcional ) Configuración de la ruta del comando Java

Si tiene instaladas varias versiones de JDK y desea utilizar una versión específica, configure este parámetro. Si no lo configura, se utilizará por defecto el comando Java definido en las variables de entorno.

Modifique el valor de JAVA_LOCATION en el archivo bin/jvm_env.properties, indicando la ruta completa del comando Java, por ejemplo: /usr/bin/java.

JAVA_LOCATION="/usr/bin/java"

WARNING

En caso de despliegue en clúster, recomendamos encarecidamente configurar este parámetro, ya que los scripts de inicio del clúster utilizan SSH para ejecutar comandos Java de forma remota; sin embargo, al ejecutar comandos mediante SSH, por defecto no se cargan las configuraciones de las variables de entorno, lo que podría impedir que el sistema reconozca correctamente el comando Java.

• Modifique el archivo conf/install_config.conf para configurar los nodos donde se instalará el software.

# IP o nombre de host de todos los equipos donde se instalará DBApi, separados por comas
ips=host1,host2,host3

sshPort=22

# Host donde se instalará el gateway
gateway=host1

# Hosts donde se instalará el apiServer, separados por comas
apiServers=host1,host2,host3

# Host donde se instalará el manager
manager=host2

Copia de los archivos de instalación

• Copie los archivos de instalación desde el equipo host1 a la misma carpeta en cada uno de los demás equipos; puede usar un script para realizar esta operación de forma rápida.

bash bin/scp-host.sh

Comandos de inicio

• Scripts para operaciones en clúster

# Iniciar el clúster con un solo comando
bash bin/start-all.sh

# Detener el clúster con un solo comando
bash bin/stop-all.sh

# Verificar el estado del clúster con un solo comando
bash bin/status-all.sh

# Iniciar o detener manualmente un servicio individual
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

# Reiniciar manualmente un servicio individual
bash bin/dbapi-daemon.sh restart gateway
bash bin/dbapi-daemon.sh restart manager
bash bin/dbapi-daemon.sh restart apiServer

# Iniciar manualmente un servicio individual en primer plano (permite ver los registros en la consola)
bash bin/dbapi.sh start gateway
bash bin/dbapi.sh start manager
bash bin/dbapi.sh start apiServer

INFO

Tenga en cuenta que si utiliza sistemas ubuntu/debian, debe emplear comandos bash y no sh.

NOTE

En la versión en clúster, los procesos de gateway, apiServer y manager generan sus propios archivos de registro, ubicados en logs/dbapi-gateway.log, logs/dbapi-apiServer.log y logs/dbapi-manager.log, respectivamente.

WARNING

Al iniciar el sistema por primera vez, este saldrá automáticamente; es necesario activar el sistema y reiniciarlo para poder utilizarlo. ¡Es imprescindible activar el sistema! ¡Debe solicitar una licencia para poder usarlo! ¡Debe solicitar una licencia para poder usarlo!

• Acceda a la interfaz web mediante http://192.168.xx.xx:8523. Los servicios API se acceden a través del gateway en la dirección http://192.168.xx.xx:8525/api/xx.

TIP

Si ha utilizado previamente versiones anteriores, para evitar posibles cachés del navegador, recuerde realizar una actualización forzosa presionando Ctrl+F5.

Instalación de MCP

El servicio MCP es un componente independiente de DBAPI y puede desplegarse por separado, fuera de la versión monousuario o en clúster de DBAPI. Si no utiliza el servicio MCP, las funciones principales de DBAPI seguirán funcionando normalmente.

Preparativos

• Asegúrese de que la versión monousuario o en clúster de DBAPI esté instalada y en funcionamiento. El servicio MCP solo funciona cuando DBAPI está disponible.

Modificación de la configuración

• Acceda al directorio de instalación de DBAPI y edite el archivo mcp/mcp-config.yaml:

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

• Descripción de los parámetros:
  • base_url: Dirección de acceso a DBAPI. En caso de despliegue en clúster, indique la dirección del servicio manager.
  • admin_username y admin_password: Credenciales del administrador de DBAPI.
  • mcp_port: Puerto de escucha del servicio MCP.
  • refresh_interval: Intervalo de actualización de las herramientas MCP, en segundos; por defecto 60 segundos.

Inicio del servicio MCP

• Una vez dentro del directorio de instalación de DBAPI, ejecute el siguiente comando:

# Iniciar en segundo plano
bash bin/dbapi-mcp.sh start

# Detener, verificar el estado o reiniciar
bash bin/dbapi-mcp.sh stop
bash bin/dbapi-mcp.sh status
bash bin/dbapi-mcp.sh restart

# Iniciar en primer plano
bash bin/dbapi-mcp.sh fg

• En sistemas Windows, puede iniciar el servicio MCP haciendo doble clic en el archivo bin\dbapi-mcp.bat.

Uso del servicio MCP

• Por defecto, el servicio MCP escucha en la dirección http://127.0.0.1:8526, y su punto de acceso es http://127.0.0.1:8526/mcp.
• El servicio MCP utiliza por defecto el método streamableHttp.
• Dado que el acceso a APIs privadas requiere un token, el cliente de MCP debe incluir en la cabecera de la solicitud el campo Authorization, con el siguiente formato:

Authorization: <token>

• Este token puede obtenerse mediante la API de solicitud de tokens de DBAPI. Tomemos como ejemplo Cherry Studio; la configuración sería la siguiente:

Apéndice

• Instalación rápida de Nacos mediante Docker

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