데이터베이스 관리

개요

이 페이지에서는 설치된 플랜트펄스 플랫폼이 사용하는 데이터 저장소의 구성, 접속 방법, 상태 확인, 기본 튜닝 정책을 안내합니다.

플랫폼은 용도별로 4종의 데이터 저장소를 내장하여 운영합니다.

저장소	용도	기본 포트	비고
Cassandra	시계열 / 대용량 데이터 (태그 포인트, 이벤트)	9042 (CQL)	키스페이스 pp. 플랫폼의 단일 대용량 DB 엔진
PostgreSQL	메타스토어 (마스터 / 설정 데이터)	5432	데이터베이스 pp, 스키마 pp
Valkey (Redis 호환)	캐시 / 세션 / 실시간 상태	6379	redis-cli 로 접속 가능
MinIO	오브젝트 스토리지 (S3 호환)	9000 (S3) / 9001 (콘솔)	파일 / 대용량 산출물 저장

이 외에 분석 계층(Spark / Kyuubi)이 사용하는 Hive Metastore + Iceberg 테이블 포맷이 있으며, 이는 플랫폼이 내부적으로 관리하므로 별도 운영 작업이 필요하지 않습니다.

참고: Cassandra 의 7000(클러스터 gossip), 7199(JMX) 포트는 내부 통신 전용입니다. 외부에 노출하지 마세요.

접속 방법

아래 명령은 모두 데이터레이크 컨테이너 내부 기준입니다. 네 저장소는 모두 plantpulse-datalake 한 컨테이너 안에서 동작하므로, 인자 없이 셸을 열면 바로 그 컨테이너로 들어갑니다.

cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh

접속 계정과 비밀번호는 환경 변수(PP_CASSANDRA_USER/PASSWORD, PP_PG_USER/PASSWORD, PP_REDIS_PASSWORD 등)로 관리됩니다.

항목	위치
실제 적용된 값	호스트의 시크릿 사이드카 /etc/kopens/plantpulse-platform.env (권한 0600)
값을 바꾸는 방법	bin/passwd.sh — 파일을 직접 고치면 반영되지 않습니다 → 비밀번호 회전

경로 확인 — 시크릿 사이드카의 정본은 /etc/kopens/plantpulse-platform.env 하나입니다(권한 0600). 옛 설치에서 /opt/kopens/ 밑에 같은 이름이 남아 있을 수 있지만 읽지 않으며, 설치 스크립트가 정본으로 되돌립니다 → 환경 변수 레퍼런스

Cassandra (cqlsh)

cd /opt/kopens/plantpulse-platform/plantpulse-storage/db/cassandra/bin
./cqlsh -u <PP_CASSANDRA_USER> 127.0.0.1 9042

-- 키스페이스 / 테이블 확인
DESCRIBE KEYSPACE pp;
SELECT table_name FROM system_schema.tables WHERE keyspace_name = 'pp';

PostgreSQL (psql)

PostgreSQL 18 이 사용되며, 클라이언트 바이너리는 /usr/pgsql-18/bin 에 있습니다.

/usr/pgsql-18/bin/psql -h 127.0.0.1 -U <PP_PG_USER> -d pp

-- 메타스토어 스키마 확인 (기본 search_path 는 pp 스키마)
\dn
\dt pp.*

Valkey (redis-cli)

redis-cli -h 127.0.0.1 -p 6379 -a '<PP_REDIS_PASSWORD>' ping

주의: 조회(SELECT / DESCRIBE / ping) 용도로만 사용해 주세요. 데이터 수정이나 스키마 변경은 주의사항을 참고하시기 바랍니다.

상태 확인

Cassandra 노드 상태

pd node 동사가 nodetool 을 감싸서 제공합니다.

cd /opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin
./pd node status

정상 상태에서는 노드가 UN(Up / Normal) 으로 표시됩니다. DN(Down) 노드가 보이면 스토리지 재시작 또는 로그 확인이 필요합니다.

PostgreSQL 상태

/usr/pgsql-18/bin/pg_isready -h 127.0.0.1 -p 5432
/usr/pgsql-18/bin/psql -h 127.0.0.1 -U <PP_PG_USER> -d pp -c "SELECT version();"

통합 상태 대시보드 / 헬스 API

# 포트별 서비스 상태 + CPU / 메모리 / 디스크 요약
cd /opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin
./status.sh

# 헬스 API — cassandra / postgres 컴포넌트 상태 포함
curl -kfsS https://127.0.0.1:4950/api/health | jq

헬스 API 응답의 cassandra, postgres 컴포넌트가 정상(UP)인지 확인해 주세요.

스키마 / 데이터 배치

항목	위치	내용
Cassandra 키스페이스	pp	시계열 데이터 테이블 (tm_*)
PostgreSQL 스키마	데이터베이스 pp / 스키마 pp	마스터 / 설정 테이블 (mm_*)
데이터 파일 경로	/data1/pp-data	Docker 볼륨 pp-data 로 마운트

PostgreSQL 메타스토어 스키마는 이미지 빌드 시점에 사전 시드되어 있으므로, 설치 후 별도의 스키마 생성 작업이 필요하지 않습니다. 접속 시 search_path 가 pp 스키마로 설정되어 있어 테이블 이름만으로 조회할 수 있습니다.

데이터는 모두 /data1/pp-data(볼륨 pp-data) 아래에 저장되므로, 컨테이너를 제거하거나 이미지를 업데이트해도 데이터는 보존됩니다.

튜닝 기본값 (출하 설정)

Cassandra 는 플랫폼 워크로드에 맞춰 아래 기본값으로 출하됩니다.

항목	출하 기본값	설명
JVM 힙	-Xms16G -Xmx16G	초기 / 최대 힙 동일 (동적 리사이징 방지)
GC	ZGC (Generational)	저지연 가비지 컬렉터
파일 캐시	file_cache_enabled: false	OS 페이지 캐시 활용, off-heap 상한 제거
Direct 메모리	-XX:MaxDirectMemorySize=6G	memtable off-heap + IO 버퍼 용도

중요 — 설정 변경 경로: 각 서비스 경로에 배포된 설정 파일(예: Cassandra 의 cassandra.yaml, jvm-server.options)은 plantpulse-datalake-cli/config/templates/ 의 템플릿에서 렌더링된 산출물입니다. 이 파일을 직접 수정하면 다음 재기동 / 재설정(configure) 시 템플릿 값으로 덮어써져 변경이 유실됩니다.

튜닝 값을 변경해야 하는 경우 반드시 아래 경로로 진행해 주세요.

1. 호스트의 /etc/kopens/conf 에 있는 템플릿(컨테이너의 plantpulse-datalake-cli/config/templates 로 바인드 마운트됩니다) 또는 bin/env.sh 의 PP_* 변수 수정
2. 데이터레이크 컨테이너 안에서 ./configure.sh 실행 — 템플릿을 다시 렌더링하여 각 서비스 경로에 배포
3. 해당 서비스 재시작 (예: pd restart storage)

템플릿이 호스트 디렉토리라서 운영자가 호스트에서 바로 편집할 수 있고, 재설치해도 편집 내용이 보존됩니다.

기본값 변경이 필요한 상황이라면 먼저 기술 지원팀과 상의하시는 것을 권장합니다.

백업 개요

데이터베이스를 포함한 모든 데이터는 pp-data 볼륨에 저장되므로, 볼륨 단위 백업이 가장 간단하고 안전한 방법입니다.

cd /opt/kopens/plantpulse-platform-docker/bin

# 기본 세트 (pp-data · pp-security) 를 한 번에
./backup.sh

# 볼륨 하나만 — <볼륨명> [보관일수] [백업경로]
./tools/backup-volume.sh pp-data 7 /data1/pp-backup/docker-volume

backup.sh 의 기본 세트에서 pp-backup 은 백업의 목적지라서, pp-temp 는 복구에 쓸모가 없어서 빠져 있습니다. 필요하면 인자로 지정해 백업할 수 있습니다.

시점 복구, DB 별 개별 백업, 외부 스토리지 동기화 등 상세 절차는 관리자 가이드 - 백업 및 복구 페이지를 참고해 주세요.

주의사항

• 운영 DB 에 직접 DDL 금지 — 테이블 생성 / 변경 / 삭제(CREATE / ALTER / DROP / TRUNCATE)를 직접 실행하지 마세요. 스키마는 플랫폼이 버전별 마이그레이션으로 관리하며, 임의 변경 시 업데이트가 실패하거나 데이터가 유실될 수 있습니다.
• 데이터 직접 수정 지양 — 마스터 데이터(mm_*)는 관리 콘솔 화면을 통해 변경해 주세요. DB 직접 UPDATE 는 캐시 / 연동 서비스와 불일치를 일으킬 수 있습니다.
• 임베디드 / 대체 DB 사용 금지 — 내장 Cassandra / PostgreSQL 을 다른 DB 제품이나 임베디드 DB 로 교체하는 구성은 지원하지 않습니다.
• 데이터 파일 직접 삭제 금지 — 디스크 공간 확보를 위해 /data1/pp-data 아래 파일을 직접 삭제하지 마세요. 데이터 정리가 필요한 경우 기술 지원팀에 문의해 주세요.
• 계정 / 포트 변경은 환경 변수로 — DB 계정이나 포트를 변경해야 하는 경우 설정 파일 직접 수정이 아니라 환경 변수(PP_*) 오버라이드 방식으로 진행해 주세요.

기술 지원

데이터베이스 운영 관련 문의가 있으시면 언제든 연락해 주세요.

담당	연락처
기술 지원	webmaster@kopens.com