> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/admin/modules/utilities.md).

# utilities (유틸리티)

플랫폼 운영을 지원하는 보조 모듈 모음. 상시 실행되지 않고 **필요 시 실행** 하는 방식입니다.

| 모듈                                | 용도                          |
| --------------------------------- | --------------------------- |
| [setup](#setup)                   | 초기 모델 일괄 등록 (CSV)           |
| [backup](#backup)                 | 통합 백업 (PG / Cassandra / 파일) |
| [recovery](#recovery)             | 데이터 복구                      |
| [exporter](#exporter)             | 시계열 CSV 내보내기                |
| [migrator](#migrator)             | Cassandra 데이터 마이그레이션        |
| [mirror-maker](#mirror-maker)     | Redis → REST 실시간 복제         |
| [simulator](#simulator)           | 데이터 시뮬레이터                   |
| [db-performance](#db-performance) | DB 성능 테스트                   |
| [api](#api)                       | REST API 클라이언트 라이브러리        |
| [lab](#lab)                       | Jupyter / Metabase 분석 환경    |

## plantpulse-setup <a href="#setup" id="setup"></a>

CSV 파일 기반의 사이트 / 자산 / OPC / 태그 모델을 일괄 등록.

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-setup/bin
./setup.sh \
  --host ${PP_HOST_IP} --port 7003 \
  --user api --password 'api123!' \
  --dir /opt/kopens/plantpulse-platform/plantpulse-setup/model/_example
```

CSV 파일 순서:

1. `1_SITE_LIST.csv` — 사이트 목록
2. `2_ASSET_TREE.csv` — 에셋 계층
3. `3_OPC_LIST.csv` — OPC 서버 연결
4. `4_TAG_LIST.csv` — 태그 정의

## plantpulse-backup <a href="#backup" id="backup"></a>

PostgreSQL (pgBackRest), Cassandra (Medusa), 파일 (Restic) 통합 백업.

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-backup/bin

./backup.sh --install            # 초기 설정
./backup.sh --postgres           # PG Differential (기본)
./backup.sh --postgres full      # PG Full
./backup.sh --postgres incr      # PG Incremental
./backup.sh --cassandra          # Cassandra Differential
./backup.sh --cassandra full     # Cassandra Full
./backup.sh --purge              # 보관 정책 정리
./backup.sh --cron-install       # 크론 자동 등록
./backup.sh --cron-remove

# 파일 백업
/opt/kopens/plantpulse-platform/plantpulse-backup/etc/run_restic.sh
```

상세는 [백업 및 복구](/plantpulse-platform/admin/backup-recovery.md).

## plantpulse-recovery <a href="#recovery" id="recovery"></a>

특정 에셋의 시계열 데이터를 기간별로 재처리.

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-recovery/bin
./recovery.sh ASSET_01032 20260101 20260530
```

## plantpulse-exporter <a href="#exporter" id="exporter"></a>

시계열 데이터 CSV 내보내기 + 대용량 dsbulk.

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-exporter/bin

# 에셋 단위 CSV 추출
./export.sh ASSET_01032 20260101 20260530 /tmp

# 테이블 전체 벌크 언로드 (dsbulk)
./bulk-unload.sh pp tm_tag_point
# → /data1/pp-backup/cassandra/bulk/tm_tag_point.gz

# 벌크 로드 (복원)
./bulk-load.sh pp tm_tag_point
```

## plantpulse-migrator <a href="#migrator" id="migrator"></a>

Spark 기반 Cassandra 서버 간 마이그레이션 (서버 교체 / 클러스터 이전).

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-migrator/bin
./run.sh 192.168.0.41 192.168.0.237 pp.tm_tag_point
```

## plantpulse-mirror-maker <a href="#mirror-maker" id="mirror-maker"></a>

Redis 의 실시간 데이터를 REST 로 다른 서버에 복제 (HA / DR).

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-mirror-maker/bin
vi run.sh         # SOURCE / TARGET 설정
./run-daemon.sh
```

## plantpulse-simulator <a href="#simulator" id="simulator"></a>

테스트 / 데모용 시계열 데이터 시뮬레이터. RANDOM 또는 CSV 기반, 최대 10,000 MPS.

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-simulator/bin
vi run.sh         # TYPE, MPS, CSV 설정
./run-daemon.sh
./log-viewer.sh
./stop.sh
```

설정 예:

```bash
TYPE="RANDOM"             # RANDOM | CSV
MPS="10000"               # 초당 메시지 수
PROTOCOL="KAFKA"

# CSV 모드
CSV="/home/simul/data/20260530.csv"
SPEED="1.0"               # 1.0 실시간, 2.0 2배속
```

## plantpulse-db-performance <a href="#db-performance" id="db-performance"></a>

Cassandra 테이블별 조회 성능 측정. 튜닝 전후 효과 비교용.

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-db-performance/bin
vi run.sh         # SITE_ID / ASSET_ID / TAG_ID 설정
./run.sh
```

## plantpulse-api <a href="#api" id="api"></a>

PlantPulse REST API 클라이언트 Java 라이브러리.

```
plantpulse-api/
├── lib/                # 의존 jar
└── target/
    ├── plantpulse-api.jar
    ├── plantpulse-buffer.jar
    ├── plantpulse-cassandra-3.0.jar
    ├── plantpulse-cassandra-4.0.jar
    └── plantpulse-cep-api.jar
```

외부 Java 프로젝트의 `pom.xml` / `build.gradle` 에 의존성 추가 후 사용. 자세한 사용법은 [API 사용 매뉴얼](/plantpulse-platform/developer/api-manual.md) 참고.

## plantpulse-lab <a href="#lab" id="lab"></a>

데이터 사이언티스트 / 개발자를 위한 분석 환경.

```
plantpulse-lab/
├── jupyter/             # Jupyter Notebook
│   ├── bin/
│   ├── logs/
│   └── notebook/        # 노트북 저장소
└── metabase/            # Metabase (BI 도구)
    ├── bin/
    └── metabase.jar
```

### Jupyter

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-lab/jupyter/bin
./start.sh
# 기본 포트 8888
```

PySpark / `cassandra-driver` / `psycopg2` 가 미리 설치되어 있어 즉시 분석 가능.

### Metabase

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-lab/metabase/bin
./start.sh
# 기본 포트 3001
```

비개발자를 위한 비주얼 BI 대시보드. PostgreSQL / Kyuubi 직접 연결.

## 관련 문서

* [모듈 인덱스](/plantpulse-platform/admin/modules.md)
* [백업 및 복구](/plantpulse-platform/admin/backup-recovery.md)
* [API 사용 매뉴얼](/plantpulse-platform/developer/api-manual.md)