Instalação e implantação

Este documento aplica-se tanto à instalação da versão pessoal quanto à versão corporativa do software; os procedimentos de instalação são idênticos para ambas as versões!!!

Primeiro, faça o download do pacote de instalação. A conta padrão é admin/admin.

Para facilitar a compreensão dos parâmetros que precisam ser configurados durante a instalação, recomendamos que você primeiro estude os recursos relacionados ao monitoramento de logs.

Implantação local — versão standalone

Preparativos

• Dependência do ambiente Java: instale previamente o JDK no servidor e configure as variáveis de ambiente. São recomendadas as versões JDK8, JDK11 ou JDK17.
• Baixe o pacote de instalação e extraia-o para o diretório desejado.
• Em servidores Linux, é necessário instalar o OpenSSL 3; consulte este link para instruções.

NOTE

Geralmente, sistemas Linux mais recentes já vêm com o OpenSSL 3 instalado; verifique a versão com o comando openssl version.

Inicialização do banco de dados

• O banco de dados metadados suporta MySQL, PostgreSQL ou SQLite incorporado. Se optar por MySQL ou PostgreSQL, execute previamente o script de inicialização sql/ddl_mysql.sql ou sql/ddl_postgres.sql; caso escolha o SQLite interno, não será necessário realizar nenhuma inicialização adicional.
• O banco de dados de logs suporta ClickHouse, MySQL ou PostgreSQL. Execute previamente o script de inicialização correspondente: sql/access_log_clickhouse.sql, sql/access_log_mysql.sql ou sql/access_log_postgres.sql.

[!IMPORTANTE] Caso utilize MySQL ou PostgreSQL como banco de dados de logs, recomenda-se separá‑los fisicamente do banco de dados metadados, garantindo assim isolamento de recursos.

Configuração de parâmetros

• Edite o arquivo conf/application.properties e ajuste as seguintes configurações:

# Caminho raiz unificado para acesso à API, por exemplo: http://192.168.xx.xx:8520/api/xxx
# Contexto da API
dbapi.api.context=api

# Se não alterar o endereço do banco de dados, será utilizado o SQLite embutido
# Endereço do banco de dados metadados; pode ser MySQL, PostgreSQL ou o SQLite nativo
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 de gravação dos logs de acesso na base de dados de logs (recomendado: mysql/postgresql/clickhouse/doris); valores possíveis: db/kafka/null
# "db" significa que o DBAPI conecta diretamente ao banco de dados de logs, escrevendo os registros de acesso nele
# "kafka" indica que o DBAPI envia os logs para o Kafka, cabendo ao usuário coletar esses logs e armazená‑los no banco de dados
# "null" significa que os logs serão gravados apenas em um arquivo local (logs/dbapi-access.log), sendo responsabilidade do usuário coletar esses arquivos e importá‑los para o banco de dados
access.log.writer=null

# Endereço do banco de dados de logs; recomendamos MySQL, PostgreSQL, ClickHouse ou Doris. Se não for necessário utilizar os recursos de monitoramento da interface, o endereço pode ser omitido
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

# Caso seja configurado access.log.writer=kafka, também será necessário definir o endereço do Kafka e o tópico onde os logs serão enviados
access.log.kafka.topic=dbapi_access_log
spring.kafka.bootstrap-servers=127.0.0.1:9092

• ( Opcional ) Configure a limpeza automática dos logs

Se você utiliza um banco de dados de logs, pode configurar a limpeza automática dos registros armazenados nele. Edite o arquivo conf/application.properties e ajuste as seguintes configurações:

# Ativar ou desativar a limpeza automática dos logs de acesso (true/false)
access.log.autoClean.enable=false

# Horário de execução da tarefa de limpeza, padrão: 3h da manhã todos os dias
# Expressão Cron para agendar a tarefa de limpeza dos logs (padrão: 3h da manhã diariamente)
access.log.autoClean.cron=0 0 3 * * ?

# Número de dias máximos para manter os logs antes da limpeza (padrão: 15 dias)
access.log.autoClean.retention.days=15

[!NOTA] Esta configuração está disponível apenas na versão corporativa do software.

• ( Opcional ) Altere a porta de escuta

Edite o arquivo conf/applicaton-standalone.properties e ajuste o valor de server.port:

server.port=8520

• ( Opcional ) Defina quais IPs podem acessar a interface web

Edite o arquivo conf/applicaton-standalone.properties e ajuste o valor de dbapi.ui.allowed.ips:

# No modo standalone, defina quais IPs podem acessar a interface web; se não for especificado, todos os IPs terão acesso
dbapi.ui.allowed.ips=

• ( Opcional ) Ajuste os parâmetros de memória

Edite o arquivo bin/jvm_env.properties e ajuste o valor de standalone_opts:

#standalone_opts="-Xms1g -Xmx4g -Xmn2g"

Pode-se manter a configuração padrão sem alterações.

• ( Opcional ) Configure o caminho do comando Java

Caso tenha instalado várias versões do JDK, é necessário especificar qual delas deve ser utilizada. Se não for feita essa configuração, o sistema usará automaticamente o comando Java definido nas variáveis de ambiente.

Edite o arquivo bin/jvm_env.properties e ajuste o valor de JAVA_LOCATION, informando o caminho completo do comando Java, por exemplo: /usr/bin/java.

JAVA_LOCATION="/usr/bin/java"

Comandos de inicialização

Linux

• Use scripts para iniciar e parar o serviço

# Em sistemas Ubuntu/Debian, utilize bash em vez de sh
bash bin/dbapi-daemon.sh start standalone
bash bin/dbapi-daemon.sh stop standalone

# Reinicie o serviço
bash bin/dbapi-daemon.sh restart standalone

# Verifique o status
bash bin/dbapi-daemon.sh status standalone

• Para executar o serviço em primeiro plano e visualizar os logs, use o seguinte comando:

bash bin/dbapi.sh start standalone

Windows

• Clique com o botão direito em bin/dbapi.ps1 e selecione "Executar com PowerShell".
• Para rodar em segundo plano, execute bin/start.ps1 via PowerShell.
• Para parar o serviço iniciado por bin/start.ps1, utilize bin/stop.ps1 também via PowerShell.

[!NOTA] Os arquivos de log da versão standalone ficam em logs/dbapi-standalone.log.

[!NOTA] O sistema Windows só oferece suporte ao modo standalone; o modo cluster não é compatível.

[!ATENÇÃO] Após a primeira inicialização, o sistema encerra automaticamente; é necessário concluir a ativação e reiniciar para continuar utilizando o serviço.

• Acesse a interface web pelo navegador em http://192.168.xx.xx:8520.

[!DICA] Se já houve uma instalação anterior de uma versão mais antiga, pressione Ctrl+F5 para forçar a atualização do cache do navegador e evitar problemas causados por caches antigos.

Implantação local — versão cluster

Descrição das funções do cluster

• O cluster possui três tipos de processos de serviço: manager, gateway e apiServer.
• O manager é o serviço de gerenciamento, responsável pela interface web. Por meio dessa interface, é possível criar fontes de dados, grupos e APIs, além de gerenciar operações como depuração online, execução, publicação e desativação de APIs. Existe apenas um processo deste tipo em todo o cluster.
• O gateway é o serviço de gateway, responsável por distribuir as requisições de API entre diferentes apiServers. Também existe apenas um processo deste tipo em todo o cluster.
• O apiServer é o serviço de API, responsável por receber as requisições, executar a lógica de negócios e responder às solicitações. Podem existir múltiplos processos deste tipo em todo o cluster.

Preparativos

• A implantação em cluster depende de nacos, de um banco de dados (mysql ou postgresql) e de redis. Instale previamente o nacos (recomendamos a versão 1.4.2), o banco de dados (mysql ou postgresql) e o redis.
• Prepare vários servidores Linux, cada um com o JDK instalado; recomendamos as versões JDK8, JDK11 ou JDK17.
• Em cada servidor Linux, instale o OpenSSL 3; consulte este link para instruções.

[!NOTA] Geralmente, sistemas Linux mais recentes já vêm com o OpenSSL 3 instalado; verifique a versão com o comando openssl version.

[!ATENÇÃO] Observações importantes: É imprescindível sincronizar o horário de todos os servidores.

Se você ativou o firewall, certifique-se de que o manager consiga acessar o gateway e o apiServer, e que o gateway consiga acessar o apiServer.

Configuração de SSH sem senha

• Escolha um servidor, denominado host1, como máquina de implantação e configure o SSH sem senha entre o host1 e todos os demais 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;     # Substitua host2 e host3 pelos nomes dos servidores onde deseja implantar
do
  ssh-copy-id $ip   # Durante este processo, será necessário digitar manualmente a senha do usuário de implantação
done

Download e extração

• Baixe o pacote de instalação e extraia‑o para o diretório desejado na máquina de implantação, host1.

Inicialização do banco de dados

• Para implantação em cluster, o banco de dados metadados suporta MySQL ou PostgreSQL. Execute previamente o script de inicialização sql/ddl_mysql.sql ou sql/ddl_postgres.sql.
• O banco de dados de logs suporta ClickHouse, MySQL ou PostgreSQL. Execute previamente o script de inicialização correspondente: sql/access_log_clickhouse.sql, sql/access_log_mysql.sql ou sql/access_log_postgres.sql.

[!IMPORTANTE] Caso utilize MySQL ou PostgreSQL como banco de dados de logs, recomenda-se separá‑los fisicamente do banco de dados metadados, garantindo assim isolamento de recursos.

Configuração de parâmetros

• Edite o arquivo conf/application.properties e ajuste as seguintes configurações:

#################################### Por favor, configure os parâmetros abaixo #####################################
# Caminho raiz unificado para acesso à API, por exemplo: http://192.168.xx.xx:8520/api/xxx
# Contexto da API
dbapi.api.context=api

# Endereço do banco de dados metadados; na versão cluster, somente MySQL ou PostgreSQL são permitidos
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 de gravação dos logs de acesso na base de dados de logs; valores possíveis: db/kafka/null
# "db" significa que o DBAPI conecta diretamente ao banco de dados de logs, escrevendo os registros de acesso nele
# "kafka" indica que o DBAPI envia os logs para o Kafka, cabendo ao usuário coletar esses logs e armazená‑los no banco de dados
# "null" significa que os logs serão gravados apenas em um arquivo local (logs/dbapi-access.log), sendo responsabilidade do usuário coletar esses arquivos e importá‑los para o banco de dados
access.log.writer=null

# Endereço do banco de dados de logs; recomendamos ClickHouse, MySQL, PostgreSQL ou Doris. Se não for necessário utilizar os recursos de monitoramento da interface, o endereço pode ser omitido
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

# Caso seja configurado access.log.writer=kafka, também será necessário definir o endereço do Kafka e o tópico onde os logs serão enviados
access.log.kafka.topic=dbapi_access_log
spring.kafka.bootstrap-servers=127.0.0.1:9092

############################## Se for cluster, por favor, configure os parâmetros abaixo ##############################

# Endereço do Nacos; necessário caso seja utilizado o modo 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

# Endereço do Redis; necessário caso seja utilizado o modo cluster
spring.redis.host=localhost
spring.redis.port=6379
spring.redis.database=0
spring.redis.password=

[!DICA] Modo Sentinel do Redis Se o Redis estiver em modo Sentinel, é necessário modificar as configurações relacionadas ao Redis da seguinte forma:

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 ) Configurar a limpeza automática de logs

Se você estiver utilizando um banco de dados de logs, pode configurar a limpeza automática dos registros armazenados nele. Edite o arquivo conf/application.properties com as seguintes configurações:

# Habilitar ou desabilitar a limpeza automática dos logs de acesso (true/false)
access.log.autoClean.enable=false

# Cron expression para agendar a tarefa de limpeza dos logs de acesso (executa diariamente às 3h da manhã por padrão)
access.log.autoClean.cron=0 0 3 * * ?

# Número de dias que os logs de acesso serão mantidos antes da limpeza (padrão: 15 dias)
access.log.autoClean.retention.days=15

[!NOTA] Apenas a versão empresarial do software suporta esta configuração.

• ( Opcional ) Alterar a porta de comunicação

Altere a porta do gateway no arquivo conf/applicaton-gateway.yml, na chave server.port:

server:
  port: 8525

Altere a porta do manager no arquivo conf/applicaton-manager.properties, na chave server.port:

server.port=8523

Altere a porta do apiServer no arquivo conf/applicaton-apiServer.properties, na chave server.port:

server.port=8524

[!ATENÇÃO] Se você ativou um firewall, após alterar as portas, certifique-se de configurá-lo adequadamente para permitir que o manager acesse o gateway e o apiServer, e que o gateway consiga acessar o apiServer.

• ( Opcional ) Modificar os parâmetros de memória

Edite o arquivo bin/jvm_env.properties e ajuste os valores das variáveis manager_opts, apiServer_opts e gateway_opts:

# Configuração dos parâmetros JVM do manager em implantação em cluster
#manager_opts="-Xms512m -Xmx1g -Xmn512m"

# Configuração dos parâmetros JVM do apiServer em implantação em cluster
#apiServer_opts="-Xms1g -Xmx4g -Xmn2g"

# Configuração dos parâmetros JVM do gateway em implantação em cluster
#gateway_opts="-Xms1g -Xmx4g -Xmn2g"

É possível manter as configurações padrão sem alterações.

• ( Opcional ) Configurar o caminho do comando Java

Se você instalou várias versões do JDK e deseja utilizar uma versão específica, configure este item. Caso contrário, será utilizado o comando Java definido nas variáveis de ambiente.

Edite o arquivo bin/jvm_env.properties e defina o valor da variável JAVA_LOCATION com o caminho completo do comando Java, por exemplo: /usr/bin/java.

JAVA_LOCATION="/usr/bin/java"

[!AVISO] Ao implantar a versão em cluster, recomendamos fortemente a configuração deste item, pois os scripts de inicialização do cluster utilizam o SSH para executar comandos Java remotamente; entretanto, durante essa execução remota, as variáveis de ambiente não são carregadas por padrão, o que pode impedir a detecção correta do comando Java do sistema.

• Edite o arquivo conf/install_config.conf para configurar os nós onde o DBApi será instalado:

# IPs ou nomes de host de todos os servidores onde o DBApi será instalado, separados por vírgulas
ips=host1,host2,host3

sshPort=22

# Host onde será instalado o gateway
gateway=host1

# Hosts onde serão instalados os apiServers, separados por vírgulas
apiServers=host1,host2,host3

# Host onde será instalado o manager
manager=host2

Copiar os arquivos de instalação

• Copie os arquivos de instalação do host1 para o mesmo diretório em todos os outros servidores; isso pode ser feito com um script que realiza a cópia em lote:

bash bin/scp-host.sh

Comandos de inicialização

• Scripts de operação em cluster

# Iniciar o cluster com um único comando
bash bin/start-all.sh

# Parar o cluster com um único comando
bash bin/stop-all.sh

# Verificar o status do cluster com um único comando
bash bin/status-all.sh

# Iniciar ou parar manualmente serviços individuais
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 serviços individuais
bash bin/dbapi-daemon.sh restart gateway
bash bin/dbapi-daemon.sh restart manager
bash bin/dbapi-daemon.sh restart apiServer

# Iniciar manualmente um serviço em modo foreground (permite visualizar os logs diretamente no terminal)
bash bin/dbapi.sh start gateway
bash bin/dbapi.sh start manager
bash bin/dbapi.sh start apiServer

[!INFORMAÇÃO] Observe que, em sistemas Ubuntu/Debian, utilize o comando bash e não sh.

[!NOTA] No caso da versão em cluster, os processos dos serviços gateway, apiServer e manager possuem seus próprios arquivos de log, respectivamente: logs/dbapi-gateway.log, logs/dbapi-apiServer.log e logs/dbapi-manager.log.

[!AVISO] Ao iniciar o sistema pela primeira vez, ele poderá encerrar automaticamente; nesse caso, é necessário realizar a ativação. Após a ativação, reinicie o sistema para continuar usando-o. Ative sempre! Ative sempre! Ative sempre! É necessário solicitar uma licença para usar o produto!

• Acesse o painel via navegador em http://192.168.xx.xx:8523. Os APIs são acessados pelo gateway em http://192.168.xx.xx:8525/api/xx.

[!DICA] Se você já utilizou versões anteriores do produto, para evitar possíveis caches do navegador, use o atalho Ctrl+F5 para forçar a atualização do cache.

Instalação do MCP

O serviço MCP é um componente independente do DBAPI e pode ser implantado separadamente, tanto na versão standalone quanto na versão em cluster. Mesmo sem utilizar o serviço MCP, as funcionalidades principais do DBAPI continuam funcionando normalmente.

Preparativos

• Certifique-se de que a versão standalone ou em cluster do DBAPI já esteja instalada e em execução. O MCP só funciona quando o DBAPI está disponível.

Modificação das configurações

• Acesse o diretório de instalação do DBAPI e edite o arquivo mcp/mcp-config.yaml:

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

• Explicação dos parâmetros:
  • base_url: Endereço de acesso do DBAPI. Em implantação em cluster, insira o endereço do serviço manager.
  • admin_username e admin_password: Credenciais do administrador do DBAPI.
  • mcp_port: Porta de escuta do serviço MCP.
  • refresh_interval: Intervalo de atualização da ferramenta MCP, em segundos; padrão: 60 segundos.

Iniciar o serviço MCP

• Após entrar no diretório de instalação do DBAPI, execute o seguinte comando:

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

# Parar, verificar o status ou reiniciar
bash bin/dbapi-mcp.sh stop
bash bin/dbapi-mcp.sh status
bash bin/dbapi-mcp.sh restart

# Iniciar em foreground
bash bin/dbapi-mcp.sh fg

• No Windows, basta dar um duplo clique no arquivo bin\dbapi-mcp.bat para iniciar o serviço MCP.

Utilizando o serviço MCP

• Por padrão, o serviço MCP escuta em http://127.0.0.1:8526, e seu ponto de acesso é http://127.0.0.1:8526/mcp.
• O serviço MCP utiliza, por padrão, o método streamableHttp.
• Como o acesso a APIs privadas exige o uso de Token, o cliente MCP deve incluir o cabeçalho Authorization na requisição, no formato:

Authorization: <token>

• Esse Token pode ser obtido através da API de solicitação de Token do DBAPI. Tomando o Cherry Studio como exemplo, a configuração seria a seguinte:

Apêndice

• Instalação rápida do Nacos via Docker

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