SeaTunnel Web 로컬 설치: 아키텍처 이해와 운영 최적화 전략

1. 시스템 구성 요소와 통신 구조 분석

SeaTunnel Web은 Apache SeaTunnel 프로젝트의 중앙 제어 인터페이스로, 다중 계층의 분산 아키텍처를 기반으로 동작한다. 핵심 구성 요소는 다음과 같다:

데이터 처리 엔진(Zeta): 실시간 데이터 파이프라인 실행 및 작업 스케줄링 담당
백엔드 서비스: 사용자 요청을 처리하고 엔진과 상태를 동기화하는 API 서버
프론트엔드 애플리케이션: 작업 정의, 모니터링, 알림 관리를 위한 웹 UI

각 컴포넌트 간의 통신 방식은 다음과 같다:

백엔드 ↔ Zeta: Hazelcast 기반 분산 메시징 (멀티캐스트 또는 TCP/IP 클러스터링)
프론트엔드 ↔ 백엔드: RESTful HTTP + WebSocket 실시간 업데이트

아래 호환성 표는 안정적인 운영을 위한 조합을 제안한다:

Web 버전	지원되는 엔진 버전	주의사항
1.0.0	2.3.3	공식 문서 기준 조합
1.0.1	2.3.4	수동 의존성 조정 필요

2. 개발 환경 설정 및 라이브러리 관리

2.1 필수 소프트웨어 요구사항

로컬 설치를 위해 아래 환경을 사전 준비해야 한다:

Java 11 (OpenJDK 권장)
Maven 3.6 이상
관계형 DB: MySQL 5.7+ 또는 PostgreSQL 10+
Node.js 16+ (UI 수정 시 필요)

JAVA_HOME 및 MAVEN 경로 설정 예시:

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export MAVEN_HOME=/opt/maven
export PATH=$JAVA_HOME/bin:$MAVEN_HOME/bin:$PATH

2.2 의존성 해석 최적화

SeaTunnel은 플러그인 기반 아키텍처로, 의존성은 다음 세 가지 유형으로 나뉜다:

코어 라이브러리: 기본 배포본에 포함
커넥터 모듈: on-demand 로딩
빌드 타임 의존성: Maven을 통해 다운로드

의존성 다운로드 속도 향상을 위해 settings.xml에 미러 저장소 추가:

<mirrors>
  <mirror>
    <id>huaweicloud</id>
    <url>https://repo.huaweicloud.com/repository/maven/</url>
    <mirrorOf>central</mirrorOf>
  </mirror>
</mirrors>

3. 백엔드 서비스 구축 절차

3.1 소스 코드 기반 빌드

맞춤형 배포를 위해서는 소스에서 직접 빌드하는 것이 바람직하다:

git clone https://github.com/apache/seatunnel.git
cd seatunnel
git checkout tags/v2.3.3 -b build-2.3.3

# 병렬 빌드 수행 (CPU 코어 수 활용)
mvn clean package -DskipTests -T 4 -B

3.2 엔진 설정 및 실행

압축 해제 후 생성되는 디렉터리 구조:

seatunnel-dist/
├── bin/
│   └── seatunnel-cluster.sh
├── config/
│   └── application.conf
├── connectors/
├── lib/
└── logs/

성능 튜닝을 위한 주요 설정 항목:

seatunnel.engine {
  worker-thread-count = 12
  job-checkpoint-interval = 300s
  task-timeout = 7200s
}

백그라운드 실행 명령:

nohup ./bin/seatunnel-cluster.sh -d --config config/application.conf > engine.out 2>&1 &

4. 웹 콘솔 배포 및 보안 강화

4.1 데이터베이스 초기화

MySQL 기준 스키마 생성:

CREATE DATABASE IF NOT EXISTS st_web_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE USER 'st_admin'@'localhost' IDENTIFIED BY 'SecurePass!2024';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE ON st_web_db.* TO 'st_admin'@'%';
FLUSH PRIVILEGES;

4.2 애플리케이션 설정

application.yml 내 핵심 설정:

server:
  port: 8801

spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/st_web_db?useSSL=false&serverTimezone=Asia/Seoul
    username: st_admin
    password: SecurePass!2024

seatunnel:
  home: /opt/seatunnel/current
  cluster:
    name: production-cluster
    members:
      - 192.168.1.10:5701
      - 192.168.1.11:5701

4.3 JWT 인증 키 생성

보안 강화를 위해 고강도 토큰 키 생성:

// Java 기반 키 생성 예시
KeyGenerator gen = KeyGenerator.getInstance("HmacSHA256");
gen.init(256);
byte[] key = gen.generateKey().getEncoded();
System.out.println(Base64.getEncoder().encodeToString(key));
// 출력 예: Xa9LmNpQrStUvWxYzAbCdEfGhJkLmNoPqRsTuVwXyZ1==

4.4 프론트엔드 빌드 및 배포

UI 컴파일 및 환경 변수 설정:

cd seatunnel-ui
npm install
echo "VITE_API_ROOT=https://api.example.com" > .env.production
npm run build

5. 프로덕션 환경 적용 전략

5.1 고가용성 설계

운영 환경에서는 다음 아키텍처를 권장:

                   [ Nginx LB ]
                       |
         ---------------------------
         |                         |
  [Web Instance A]           [Web Instance B]
         |                         |
  [Shared Database] ←------→ [Hazelcast Cluster]

Nginx를 통한 HTTPS 종료 및 부하 분산
Hazelcast 멤버 간 멀티캐스트 기반 자동 발견
DB 마스터-슬레이브 복제 구성

5.2 JVM 및 리소스 튜닝

메모리 최적화를 위한 JVM 옵션 설정:

# seatunnel-env.sh
export SEATUNNEL_JVM_OPTS="-Xms6g -Xmx12g -XX:+UseZGC -XX:MaxTenuringThreshold=6"

5.3 로깅 및 모니터링

중앙 집중식 로그 수집을 위한 Log4j2 설정:

<Appenders>
  <Kafka name="KafkaLog" topic="seatunnel-logs">
    <PatternLayout pattern="%d{ISO8601} %-5p [%t] %c{1} - %m%n"/>
    <Property name="bootstrap.servers">kafka1:9092,kafka2:9092</Property>
  </Kafka>
</Appenders>

6. 문제 진단 가이드

6.1 대표 오류 유형 및 해결책

데이터베이스 연결 실패:

MySQL 원격 접근 설정 확인 (bind-address)
타임존 매칭 여부 검토 (서버 ↔ 애플리케이션)
방화벽 포트 3306 허용 여부 점검

커넥터 인식 오류:

ls $SEATUNNEL_HOME/connectors/seatunnel/
# 출력 예: spark-connector-kafka-2.3.3.jar

grep "kafka" $SEATUNNEL_HOME/connectors/plugin-mapping.properties

6.2 로그 기반 분석 패턴

주요 로그 파일 위치:

엔진 로그: logs/seatunnel-engine.log
웹 서비스 로그: logs/web-backend.log
프론트엔드 에러: 브라우저 콘솔 또는 Sentry 연동

대표적인 오류 식별 패턴:

ERROR o.a.s.e.JobExecution - Source initialization failed
→ 커넥터 클래스 로딩 실패 또는 네트워크 차단

WARN c.h.nio.tcp.TcpServerConnection - Connection attempt from unauthorized endpoint
→ Hazelcast 보안 정책 위반

7. 확장성 및 맞춤 개발

7.1 커스텀 커넥터 개발

새로운 데이터 소스/싱크를 추가하는 단계:

BaseSource<T> 또는 BaseSink<T> 상속 구현
@AutoService(Connector.class) 어노테이션 추가
JAR 패키징 후 connectors/seatunnel/ 디렉터리에 배치

7.2 외부 시스템 연동

REST API를 통한 자동화 예시:

curl -X POST http://localhost:8801/api/v1/jobs/start \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily_sync_job",
    "config": { "engine": "zeta", "mode": "client" }
  }'

실제 운영 사례에서, 자주 사용하는 커넥터를 사전 로딩하여 초기화 지연을 60% 이상 감소시켰으며, 정기적인 의존성 충돌 검사를 통해 런타임 오류를 사전 방지하는 것이 안정적인 운영에 핵심적이다.

태그: SeaTunnel Hazelcast Spring Boot Log4j2 kafka

8월 30일 21:13에 게시됨

괴물 클럽