설치 및 배포

이 문서는 개인용 버전과 기업용 버전 소프트웨어의 설치에 모두 적용되며, 두 버전 간 설치 방법은 동일합니다!!!

먼저 다운로드를 통해 설치 패키지를 받으시기 바랍니다. 기본 계정은 admin/admin입니다.

설치 시 구성해야 하는 파라미터들을 이해하기 쉽게 돕기 위해, 먼저 로그 모니터링 관련 기능 설계를 학습하시기 바랍니다.

로컬 단독 설치

준비 작업

Java 환경이 필요하므로 서버에 JDK를 먼저 설치하고 환경 변수를 설정해 주세요. 권장 버전은 JDK8, JDK11, JDK17입니다.
설치 패키지를 다운로드한 뒤, 설치할 디렉토리에 압축을 해제합니다.
Linux 서버인 경우 OpenSSL 3을 설치해야 하며, 자세한 내용은 여기를 참고하세요.

NOTE

일반적으로 최신 버전의 Linux 시스템에는 이미 OpenSSL 3이 포함되어 있으므로, openssl version 명령어로 OpenSSL 버전을 확인하실 수 있습니다.

데이터베이스 초기화

메타데이터 베이스는 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 파일의 다음 설정을 수정합니다.

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'는 DBAPI가 로그 데이터베이스에 직접 연결하여 API 접근 로그를 기록하는 방식입니다.
# 'kafka'는 DBAPI가 Kafka에 API 접근 로그를 전송한 뒤, 사용자가 Kafka로부터 로그를 수집하여 데이터베이스에 저장하는 방식입니다.
# 'null'은 DBAPI가 로그를 로컬 디스크 파일(`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=kafka로 설정된 경우, Kafka 주소와 로그 기록 대상 토픽을 추가로 설정해야 합니다.
access.log.kafka.topic=dbapi_access_log
spring.kafka.bootstrap-servers=127.0.0.1:9092

( 선택 사항 ) 로그 자동 정리 설정

로그 데이터베이스를 사용하는 경우, 데이터베이스 내 로그를 자동으로 정리하도록 설정할 수 있습니다. conf/application.properties 파일의 다음 설정을 수정합니다.

properties

# 로그 자동 정리 활성화 여부(기본값: 비활성화)
# Access log 자동 정리 활성화 여부(true/false)
access.log.autoClean.enable=false

# 정리 작업 스케줄링 시간(기본값: 매일 새벽 3시)
# Access log 정리 작업 스케줄링 크론 표현식(기본값: 매일 오전 3시)
access.log.autoClean.cron=0 0 3 * * ?

# 로그 데이터 보관 일수(기본값: 15일)
# Access log를 정리하기 전 보관 가능한 일수(기본값: 15일)
access.log.autoClean.retention.days=15

NOTE

이 설정은 기업용 버전 소프트웨어에서만 지원됩니다.

( 선택 사항 ) 포트 번호 수정

conf/applicaton-standalone.properties 파일의 server.port 값을 수정합니다.

properties

server.port=8520

( 선택 사항 ) UI 웹페이지의 접속 IP 제한 설정

conf/applicaton-standalone.properties 파일의 dbapi.ui.allowed.ips 값을 수정합니다.

properties

# 단독 모드에서는 어떤 IP가 UI 웹페이지에 접속할 수 있는지 설정합니다. 설정하지 않으면 모든 IP가 접속 가능합니다.
dbapi.ui.allowed.ips=

( 선택 사항 ) 메모리 파라미터 수정

bin/jvm_env.properties 파일의 standalone_opts 값을 수정합니다.

properties

# standalone_opts="-Xms1g -Xmx4g -Xmn2g"

기본값 그대로 유지해도 무방합니다.

( 선택 사항 ) Java 명령어 경로 설정

여러 버전의 JDK를 설치하신 경우, 특정 버전의 JDK를 사용하려면 이 항목을 설정해야 합니다. 설정하지 않아도 기본 환경변수의 Java 명령어가 사용됩니다.

bin/jvm_env.properties 파일의 JAVA_LOCATION 값을 수정합니다. Java 명령어가 위치한 전체 경로를 입력합니다. 예: /usr/bin/java

properties

JAVA_LOCATION="/usr/bin/java"

시작 명령어

Linux

스크립트를 이용한 시작 및 종료

shell

# Ubuntu/Debian 시스템에서는 sh가 아닌 bash를 사용해 주세요.
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

로그를 확인하기 위해 프런트엔드에서 실행하려면 다음과 같이 실행합니다.

shell

bash bin/dbapi.sh start standalone

Windows

bin/dbapi.ps1 파일을 마우스 오른쪽 버튼으로 클릭한 뒤, PowerShell로 실행합니다.
백그라운드에서 실행하려면 PowerShell로 bin/start.ps1을 실행합니다.
bin/start.ps1로 시작한 서비스를 중지하려면 PowerShell로 bin/stop.ps1을 실행합니다.

NOTE

단독 모드의 로그 파일은 logs/dbapi-standalone.log입니다.

NOTE

Windows 시스템에서는 클러스터 모드를 지원하지 않으며, 단독 모드만 가능합니다.

WARNING

처음 시작 후 시스템이 자동으로 종료되므로, 활성화를 완료한 뒤 재시작해야만 정상적으로 사용할 수 있습니다.

브라우저에서 http://192.168.xx.xx:8520에 접속하여 UI에 진입합니다.

TIP

이전에 구버전을 설치하셨다면, 페이지 캐시로 인한 문제를 방지하기 위해 Ctrl+F5를 눌러 브라우저 캐시를 강제로 새로 고침해 주세요.

로컬 클러스터 설치

클러스터 역할 설명

클러스터에는 세 가지 서비스 프로세스가 존재합니다: manager, gateway, apiServer.
manager는 관리 서비스로, 웹 UI 서비스입니다. 이 UI를 통해 데이터 소스, 그룹, API를 생성하고, API의 온라인 디버깅, 실행, 배포, 오프라인 처리 등을 관리할 수 있습니다. 클러스터 내에서 이 서비스 프로세스는 단 하나만 존재합니다.
gateway는 게이트웨이 서비스로, API 요청을 각각의 apiServer로 분산하는 역할을 합니다. 클러스터 내에서 이 서비스 프로세스 역시 단 하나만 존재합니다.
apiServer는 API 서비스로, API 요청을 수신하고 해당 API의 비즈니스 로직을 수행합니다. 클러스터 내에서 이 서비스 프로세스는 여러 개 존재할 수 있습니다.

준비 작업

클러스터 배포에는 nacos, 데이터베이스(MySQL 또는 PostgreSQL), redis가 필요합니다. 먼저 nacos(권장 버전 1.4.2), 데이터베이스(MySQL 또는 PostgreSQL), redis를 설치해 주세요.
여러 대의 Linux 서버를 준비하고, 각 서버에 JDK를 설치합니다. 권장 버전은 JDK8, JDK11, JDK17입니다.
각 Linux 서버에 OpenSSL 3을 설치합니다. 자세한 내용은 여기를 참고하세요.

NOTE

일반적으로 최신 버전의 Linux 시스템에는 이미 OpenSSL 3이 포함되어 있으므로, openssl version 명령어로 OpenSSL 버전을 확인하실 수 있습니다.

주의사항

모든 서버의 시간이 반드시 동기화되어야 합니다.

방화벽을 활성화하신 경우, manager가 gateway와 apiServer에 접근할 수 있도록, 그리고 gateway가 apiServer에 접근할 수 있도록 설정해 주시기 바랍니다.

SSH 비밀번호 없이 로그인 설정

배포용 서버로 host1을 선택한 뒤, host1에서 다른 모든 서버로 SSH 비밀번호 없이 로그인할 수 있도록 설정합니다.

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;     # 여기서 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

구성 파라미터

conf/application.properties 파일의 다음 설정을 수정합니다.

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'는 DBAPI가 로그 데이터베이스에 직접 연결하여 API 접근 로그를 기록하는 방식입니다.
# 'kafka'는 DBAPI가 Kafka에 API 접근 로그를 전송한 뒤, 사용자가 Kafka로부터 로그를 수집하여 데이터베이스에 저장하는 방식입니다.
# 'null'은 DBAPI가 로그를 로컬 디스크 파일(`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=

redis 세이프가드 모드

redis를 세이프가드 모드로 사용하는 경우, 아래와 같이 redis 관련 설정을 수정해야 합니다:

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

( 선택 사항 ) 로그 자동 정리 설정

로그 데이터베이스를 사용하는 경우, 로그 데이터베이스의 로그를 자동으로 정리하도록 설정할 수 있습니다. conf/application.properties 파일에서 다음 설정을 수정하세요.

properties

# 접근 로그 자동 정리를 활성화할지 여부 (기본값은 비활성화)
access.log.autoClean.enable=false

# 정리 작업 스케줄링 시간 (기본값은 매일 새벽 3시)
access.log.autoClean.cron=0 0 3 * * ?

# 정리 전 유지되는 로그 최대 일수 (기본값은 15일)
access.log.autoClean.retention.days=15

NOTE

이 설정은 엔터프라이즈 에디션 소프트웨어에서만 지원됩니다.

( 선택 사항 ) 포트 번호 변경

gateway의 포트 번호는 conf/applicaton-gateway.yml 파일의 server.port에서 수정합니다.

yml

server:
  port: 8525

manager의 포트 번호는 conf/applicaton-manager.properties 파일의 server.port에서 수정합니다.

properties

server.port=8523

apiServer의 포트 번호는 conf/applicaton-apiServer.properties 파일의 server.port에서 수정합니다.

properties

server.port=8524

CAUTION

방화벽을 활성화한 경우, 포트를 변경한 후 방화벽 설정을 반드시 확인하여 manager가 gateway와 apiServer에 접근할 수 있도록 하고, gateway가 apiServer에 접근할 수 있도록 해야 합니다.

( 선택 사항 ) 메모리 파라미터 수정

bin/jvm_env.properties 파일의 manager_opts, apiServer_opts, gateway_opts 값을 수정합니다.

properties

# 클러스터 배포 시 manager JVM 파라미터 설정
#manager_opts="-Xms512m -Xmx1g -Xmn512m"

# 클러스터 배포 시 apiServer JVM 파라미터 설정
#apiServer_opts="-Xms1g -Xmx4g -Xmn2g"

# 클러스터 배포 시 gateway JVM 파라미터 설정
#gateway_opts="-Xms1g -Xmx4g -Xmn2g"

기본값 그대로 두어도 무방합니다.

( 선택 사항 ) Java 명령어 경로 설정

여러 버전의 JDK를 설치한 경우, 특정 버전의 JDK를 사용하려면 이 항목을 설정해야 합니다. 설정하지 않아도 기본적으로 환경변수에 지정된 Java 명령어가 사용됩니다.

bin/jvm_env.properties 파일의 JAVA_LOCATION 값을 수정하여 Java 명령어가 위치한 전체 경로를 입력합니다. 예를 들어 /usr/bin/java와 같이 설정합니다.

properties

JAVA_LOCATION="/usr/bin/java"

WARNING

클러스터 버전을 배포하는 경우, 이 설정을 반드시 수행하시기 바랍니다. 클러스터 시작 스크립트는 SSH를 통해 원격으로 Java 명령어를 실행하는데, SSH에서는 기본적으로 환경변수 설정이 적용되지 않아 시스템의 Java 명령어를 인식하지 못할 수 있기 때문입니다.

conf/install_config.conf 파일을 수정하여 설치할 노드 정보를 구성합니다.

shell

# DBApi를 설치할 모든 호스트의 IP 또는 호스트명을 쉼표로 구분하여 입력
ips=host1,host2,host3

sshPort=22

# gateway를 설치할 호스트
gateway=host1

# apiServer를 설치할 호스트들 (여러 대인 경우 쉼표로 구분)
apiServers=host1,host2,host3

# manager를 설치할 호스트
manager=host2

설치 파일 복사

host1의 설치 파일을 다른 각 노드의 같은 디렉토리로 복사합니다. 스크립트를 이용하면 한 번에 복사 가능합니다.

shell

bash bin/scp-host.sh

시작 명령어

클러스터 운영 스크립트

shell

# 클러스터 일괄 시작
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 시스템에서는 sh 명령어 대신 bash 명령어를 사용하시기 바랍니다.

NOTE

클러스터 버전의 gateway, apiServer, manager 세 가지 서비스 프로세스는 각각 고유의 로그 파일을 가지고 있으며, 로그 파일 경로는 각각 logs/dbapi-gateway.log, logs/dbapi-apiServer.log, logs/dbapi-manager.log입니다.

WARNING

처음 시스템을 시작하면 자동으로 종료되므로, 반드시 활성화를 진행한 뒤 재부팅해야 정상적으로 사용할 수 있습니다. 꼭 활성화하세요! 활성화! 활성화! 라이선스 신청 없이는 사용할 수 없습니다! 라이선스 신청 없이는 사용할 수 없습니다!

브라우저에서 http://192.168.xx.xx:8523에 접속하면 UI에 진입할 수 있으며, API는 gateway를 통해 http://192.168.xx.xx:8525/api/xx로 접근합니다.

TIP

이전 버전을 사용해 본 적이 있다면, 이전 버전의 브라우저 캐시로 인해 문제가 발생할 수 있으니 브라우저에서 Ctrl+F5를 눌러 캐시를 강제로 새로고침해 주시기 바랍니다.

MCP 설치

MCP 서비스는 DBAPI의 독립적인 구성 요소로서, DBAPI의 단독 버전이나 클러스터 버전 외에도 별도로 배포할 수 있습니다. MCP 서비스를 사용하지 않더라도 DBAPI의 핵심 기능은 정상적으로 작동합니다.

준비

DBAPI의 단독 버전 또는 클러스터 버전이 이미 설치되어 있고 정상적으로 실행되고 있는지 확인합니다. MCP는 DBAPI가 가용할 때만 정상적으로 작동합니다.

설정 수정

DBAPI 설치 디렉토리로 이동한 뒤 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

파라미터 설명:
- base_url: DBAPI의 접근 주소. 클러스터 배포 시에는 manager 서비스의 주소를 입력합니다.
- admin_username, admin_password: DBAPI 관리자 계정.
- mcp_port: MCP 서비스의 리스닝 포트.
- refresh_interval: MCP 도구의 갱신 간격(단위: 초), 기본값은 60초.

MCP 서비스 시작

DBAPI 설치 디렉토리로 이동한 뒤 다음 명령어를 실행합니다.

shell

# 백그라운드로 시작
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에 접근할 때는 반드시 Token이 필요합니다. MCP 클라이언트가 서비스를 호출할 때는 요청 헤더에 다음과 같은 형식으로 Authorization을 추가해야 합니다:

text

Authorization: <token>

해당 Token은 DBAPI의 Token 발급 API를 통해 얻을 수 있습니다. Cherry Studio를 예로 들면, 다음과 같이 설정합니다:

그림 7

부록

docker를 이용한 Nacos 빠른 설치

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

설치 및 배포 ​

로컬 단독 설치 ​

준비 작업 ​

데이터베이스 초기화 ​

구성 파라미터 ​

시작 명령어 ​

Linux ​

Windows ​

로컬 클러스터 설치 ​

클러스터 역할 설명 ​

준비 작업 ​

SSH 비밀번호 없이 로그인 설정 ​

다운로드 및 압축 해제 ​

데이터베이스 초기화 ​

구성 파라미터 ​

설치 파일 복사 ​

시작 명령어 ​

MCP 설치 ​

준비 ​

설정 수정 ​

MCP 서비스 시작 ​

MCP 서비스 사용 ​

부록 ​

설치 및 배포

로컬 단독 설치

준비 작업

데이터베이스 초기화

구성 파라미터

시작 명령어

Linux

Windows

로컬 클러스터 설치

클러스터 역할 설명

준비 작업

SSH 비밀번호 없이 로그인 설정

다운로드 및 압축 해제

데이터베이스 초기화

구성 파라미터

설치 파일 복사

시작 명령어

MCP 설치

준비

설정 수정

MCP 서비스 시작

MCP 서비스 사용

부록