> 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/installation/startup-guide.md).

# 시작 가이드

## 개요

원라인 설치 또는 Docker 설치로 플랜트펄스 플랫폼을 설치하셨다면, 모든 운영 스크립트는 `/home/kopens/plantpulse-platform-docker/bin/` 디렉토리에 있습니다. 이 페이지에서는 컨테이너로 동작하는 플랫폼을 시작하고 운영하는 방법을 안내합니다.

> **바이너리 설치를 사용하시는 경우**: 운영 스크립트는 `/opt/kopens/plantpulse-platform/plantpulse-startup/` 디렉토리에 있으며, 명령 체계가 다릅니다. 이 페이지 하단의 [바이너리 설치 환경](#binary) 섹션을 참고해 주세요.

## 환경 변수 설정

플랫폼 시작 전에 환경 변수를 확인해 주세요. 원라인 설치 시 기본값으로 자동 설정되며, 운영 환경에 맞춰 일부 변수만 조정하시면 됩니다.

```bash
vi /home/kopens/plantpulse-platform-docker/bin/env.sh
```

### 자주 조정하는 항목

| 변수                         | 설명                           | 기본값               | 예시              |
| -------------------------- | ---------------------------- | ----------------- | --------------- |
| `DOCKER_PP_EXTERNAL_IP`    | 외부 노출 IP (브라우저 접속 IP)        | `111.222.333.444` | `192.168.0.110` |
| `DOCKER_PP_CPUS`           | 컨테이너 vCPU 수                  | `32`              | `16`            |
| `DOCKER_PP_MEMORY`         | 컨테이너 메모리 상한                  | `200G`            | `128G`          |
| `DOCKER_PP_DATA_DISK_NAME` | 데이터 디스크 이름 (`lsblk` 명령으로 확인) | `sda`             | `sda`           |
| `PP_LANG`                  | 플랫폼 로케일 (`ko` / `en`)        | `ko`              | `ko`            |
| `PP_TZ`                    | 플랫폼 타임존                      | `Asia/Seoul`      | `Asia/Seoul`    |

환경 변수 전체 목록은 [Docker 설치](/plantpulse-platform/installation/docker.md) 페이지를 참고해 주세요.

> **변경 적용**: `env.sh` 를 수정한 뒤에는 반드시 `./restart.sh` 로 재시작해야 새 설정이 반영됩니다.

## 플랫폼 시작

### 최초 설치 후 시작

원라인 설치 (`install.sh`) 가 완료되면 컨테이너가 이미 실행 중입니다. 별도로 시작 명령을 실행할 필요는 없습니다. 상태만 확인해 주세요.

```bash
cd /home/kopens/plantpulse-platform-docker/bin
./status.sh
./ops-check.sh
```

### 정지된 컨테이너 시작

`./platform-stop.sh` 또는 호스트 재부팅 등으로 컨테이너가 정지된 경우 다시 시작합니다.

```bash
cd /home/kopens/plantpulse-platform-docker/bin
./start.sh
```

내부적으로 `docker start` 가 호출되며 볼륨(`pp-data`, `pp-temp`, `pp-backup`, `pp-security`, `pp-template`) 의 데이터는 그대로 유지됩니다.

### 시작 순서

컨테이너가 기동되면 내부의 컴포넌트가 아래 순서로 하나씩 시작됩니다. 전체 부팅에는 약 **3 \~ 5분** (Cassandra 스키마 마이그레이션 + JVM warm-up) 이 소요됩니다.

| 순서 | 카테고리   | 컴포넌트                                        | 역할            |
| -- | ------ | ------------------------------------------- | ------------- |
| 1  | 스토리지   | Valkey(Redis), PostgreSQL, Cassandra, MinIO | 데이터 저장소       |
| 2  | 분석     | Spark, Hadoop, Hive, Kyuubi, Gravitino      | 데이터 분석 엔진     |
| 3  | 시계열    | 시계열 엔진, 시계열 UI                              | 시계열 데이터 처리    |
| 4  | 메시징    | Kafka, MQTT, STOMP                          | 메시지 전달        |
| 5  | 워크플로우  | Temporal, Kestra                            | 작업 스케줄링       |
| 6  | 처리     | CEP, Data Gateway, SQL, Monitor             | 이벤트 처리 및 모니터링 |
| 7  | 플러그인   | OPC-UA Plugin                               | 외부 장비 연결      |
| 8  | 애플리케이션 | Warehouse, Agent, Batch, Server             | 핵심 서비스        |

### 부팅 검증

전체 컴포넌트의 부팅 로그를 검증하려면 아래 명령을 사용합니다.

```bash
cd /home/kopens/plantpulse-platform-docker/bin
./platform-verify-boot.sh
```

### 정상 시작 확인

```bash
# 컨테이너 / 헬스 / 볼륨 요약
./status.sh

# 운영 health + 최근 critical log 점검
./ops-check.sh

# 헬스체크 엔드포인트 직접 호출
curl -kfsS https://127.0.0.1:4950/api/health | jq

# Docker 상태 (STATUS = healthy)
docker ps
```

`STATUS = (healthy)` 가 표시되고 `ops-check.sh` 결과에 critical 메시지가 없으면 플랫폼이 정상적으로 시작된 것입니다.

## 플랫폼 중지

```bash
cd /home/kopens/plantpulse-platform-docker/bin
./platform-stop.sh
```

컨테이너를 안전하게 정지합니다 (`docker stop`). 데이터는 Docker 볼륨에 그대로 보존되므로 `./start.sh` 로 다시 시작하면 이전 상태가 유지됩니다.

> **주의**: `docker kill` 이나 호스트 강제 종료는 데이터 일관성을 깨뜨릴 수 있습니다. 반드시 `./platform-stop.sh` 를 사용해 주세요.

## 플랫폼 재시작

내부 컴포넌트를 graceful 하게 종료한 뒤 컨테이너를 재기동하고 health 가 정상으로 돌아올 때까지 대기합니다.

```bash
cd /home/kopens/plantpulse-platform-docker/bin
./restart.sh
```

`env.sh` 변경, 운영 중 발생한 일시적 문제 해소, 정기 재시작 시에 사용합니다.

## 서비스 상태 확인

### 전체 요약

```bash
./status.sh
```

컨테이너 상태, health 결과, 마운트된 볼륨 정보를 한 번에 보여줍니다.

### 운영 점검

```bash
./ops-check.sh
```

HTTPS 헬스 엔드포인트(4950) 호출 결과와 최근 critical 로그를 검사합니다. 모니터링 시스템 연동에도 동일한 명령을 사용할 수 있습니다.

### 호스트 측 리소스 확인

```bash
docker stats plantpulse-platform   # CPU / 메모리 / 네트워크 실시간
docker ps                          # 컨테이너 상태
```

## 컨테이너 내부 접속

문제 진단이나 컴포넌트 단위 작업이 필요할 때는 컨테이너 내부 셸로 접속합니다.

```bash
cd /home/kopens/plantpulse-platform-docker/bin
./platform-bash.sh
```

컨테이너 내부의 `/opt/kopens/plantpulse-platform/plantpulse-startup/` 디렉토리에 컴포넌트별 운영 스크립트가 있습니다. 예를 들어 컨테이너를 재시작하지 않고 서버 컴포넌트만 재시작하려면:

```bash
# 호스트에서 컨테이너 진입
./platform-bash.sh

# 컨테이너 내부에서
/opt/kopens/plantpulse-platform/plantpulse-startup/restart-server.sh
exit
```

> **권장**: 가능하면 컨테이너 전체 재시작 (`./restart.sh`) 을 사용하시고, 컴포넌트 단위 재시작은 특정 모듈만 격리해서 검증할 때만 사용해 주세요.

### 컴포넌트 단위 재시작 스크립트 (컨테이너 내부)

`./platform-bash.sh` 로 진입한 후 사용할 수 있는 스크립트 목록입니다.

| 분류     | 스크립트                      | 설명                            |
| ------ | ------------------------- | ----------------------------- |
| 애플리케이션 | `restart-server.sh`       | 웹 서버 및 관리 콘솔                  |
|        | `restart-agent.sh`        | 데이터 수집 에이전트                   |
|        | `restart-batch.sh`        | 배치 처리 서버                      |
|        | `restart-cep.sh`          | 복합 이벤트 처리 엔진                  |
|        | `restart-data-gateway.sh` | 데이터 조회 게이트웨이                  |
|        | `restart-sql.sh`          | SQL 쿼리 도구                     |
|        | `restart-monitor.sh`      | 시스템 모니터링                      |
|        | `restart-warehouse.sh`    | 데이터 웨어하우스                     |
|        | `restart-plugin.sh`       | OPC-UA 등 플러그인                 |
| 인프라    | `restart-messaging.sh`    | Kafka, MQTT, STOMP            |
|        | `restart-storage.sh`      | Cassandra, PostgreSQL, Valkey |
|        | `restart-analytics.sh`    | Spark, Kyuubi, Gravitino      |
|        | `restart-timeseries.sh`   | 시계열 엔진 및 UI                   |
|        | `restart-workflow.sh`     | Temporal, Kestra              |

> **참고**: 인프라 모듈(스토리지, 분석, 메시징)을 재시작한 경우, 해당 모듈에 의존하는 애플리케이션도 함께 재시작해 주시는 것이 좋습니다.

## 플랫폼 업데이트

새 이미지가 릴리즈되면 아래 명령으로 업데이트합니다.

```bash
cd /home/kopens/plantpulse-platform-docker/bin
./platform-update.sh
```

자동 수행 순서:

1. 새 이미지 `docker pull`
2. 기존 컨테이너 graceful 종료
3. 새 이미지로 컨테이너 재생성
4. health 검증 — 실패 시 이전 이미지로 자동 rollback

데이터는 볼륨에 별도 저장되므로 업데이트 중에도 안전하게 보존됩니다.

## 로그 관리

### 호스트에서 컨테이너 로그 조회

```bash
docker logs plantpulse-platform --tail 200
docker logs plantpulse-platform -f               # 실시간 follow
```

### 컨테이너 내부 로그 디렉토리

`./platform-bash.sh` 로 진입한 후 모듈별 로그를 직접 확인할 수 있습니다.

| 모듈           | 로그 경로                                             | 확인 포인트        |
| ------------ | ------------------------------------------------- | ------------- |
| 시작 로그        | `/var/log/plantpulse-startup.log`                 | 시작 시 에러 확인    |
| Valkey       | `plantpulse-storage/cache/valkey/logs/system.log` | 캐시 연결 상태      |
| PostgreSQL   | `plantpulse-storage/db/postgres/logs/system.log`  | 메타DB 상태       |
| Cassandra    | `plantpulse-storage/db/cassandra/logs/system.log` | 시계열DB 상태      |
| MinIO        | `plantpulse-storage/object/minio/logs/system.log` | 오브젝트 스토리지     |
| Gravitino    | `plantpulse-analytics/gravitino/logs/system.log`  | 데이터 카탈로그      |
| Hive         | `plantpulse-analytics/hive/logs/system.log`       | 쿼리 엔진         |
| Spark        | `plantpulse-analytics/spark/logs/system.log`      | 분석 엔진         |
| Kyuubi       | `plantpulse-analytics/kyuubi/logs/system.log`     | SQL 게이트웨이     |
| 시계열 엔진       | `plantpulse-timeseries/engine/logs/system.log`    | 시계열 처리        |
| Kafka        | `plantpulse-messaging/kafka/logs/server.log`      | 메시지 스트리밍      |
| MQTT         | `plantpulse-messaging/mqtt/logs/hivemq.log`       | IoT 메시징       |
| STOMP        | `plantpulse-messaging/stomp/logs/activemq.log`    | WebSocket 메시징 |
| Temporal     | `plantpulse-workflow/temporal/logs/system.log`    | 워크플로우         |
| Kestra       | `plantpulse-workflow/kestra/logs/system.log`      | 워크플로우         |
| CEP          | `plantpulse-cep/logs/system.log`                  | 이벤트 처리        |
| Data Gateway | `plantpulse-data-gateway/logs/system.log`         | 데이터 조회        |
| SQL          | `plantpulse-sql/logs/system.log`                  | SQL 도구        |
| Monitor      | `plantpulse-monitor/logs/system.log`              | 모니터링          |
| Warehouse    | `plantpulse-warehouse/logs/system.log`            | 웨어하우스         |
| Agent        | `plantpulse-agent/logs/system.log`                | 데이터 수집        |
| Batch        | `plantpulse-batch/logs/system.log`                | 배치 처리         |
| Server       | `plantpulse-server/logs/system.log`               | 웹 서버          |

### 로그 호스트로 복사

문제 분석이나 기술 지원 요청 시 컨테이너 내부 로그를 호스트로 일괄 복사합니다.

```bash
cd /home/kopens/plantpulse-platform-docker/bin/util
./copy-log-to-local.sh
```

로그는 `/tmp/plantpulse-log/` 경로에 모듈별로 분류되어 저장됩니다.

## 장애 진단

문제가 발생했을 때 진단용 tarball 을 생성합니다. 컨테이너 상태, 설정, 호스트 환경, 로그를 모두 포함하며, 비밀번호 등 민감 정보는 자동으로 마스킹됩니다.

```bash
cd /home/kopens/plantpulse-platform-docker/bin
./doctor.sh
```

생성된 tarball 을 KOPENS 기술 지원팀에 전달하시면 신속한 분석이 가능합니다.

## 워커 관리 (클러스터 환경)

마스터 노드 하나로 운영하다가 처리량 확장이 필요한 경우 워커 컨테이너를 추가합니다.

```bash
cd /home/kopens/plantpulse-platform-docker/bin

./worker-run.sh        # 워커 추가 (워커 번호 입력)
./worker-stop.sh       # 워커 정지
./worker-update.sh     # 워커 이미지 갱신
./worker-remove.sh     # 워커 제거
./worker-bash.sh       # 워커 컨테이너 셸 진입
```

워커 IP 배열은 `env.sh` 의 `DOCKER_PW_IP_ARRAY` 에 설정합니다. 자세한 내용은 [클러스터 설치](/plantpulse-platform/installation/build-deploy.md) 페이지를 참고해 주세요.

## 설치 후 초기 접속

플랫폼 시작이 완료되면 웹 브라우저에서 관리 콘솔에 접속해 주세요.

| 항목        | 값                    |
| --------- | -------------------- |
| URL       | `http://[서버IP]:7500` |
| 기본 관리자 ID | admin                |
| 기본 비밀번호   | admin123!            |

`[서버IP]` 는 `env.sh` 의 `DOCKER_PP_EXTERNAL_IP` 값입니다.

> **보안 안내**: 최초 로그인 후에는 보안을 위해 기본 비밀번호를 변경해 주시는 것을 권장합니다. 상단 오른쪽의 사용자 아이콘 > 비밀번호 변경 메뉴를 이용하시면 됩니다.

## 바이너리 설치 환경 <a href="#binary" id="binary"></a>

바이너리 설치 방식에서는 운영 스크립트가 `/opt/kopens/plantpulse-platform/plantpulse-startup/` 디렉토리에 있으며, 명령은 다음과 같습니다.

```bash
# 시작 (포그라운드)
/opt/kopens/plantpulse-platform/plantpulse-startup/start.sh

# 시작 (백그라운드 / 데몬)
/opt/kopens/plantpulse-platform/plantpulse-startup/start-daemon.sh

# 정지
/opt/kopens/plantpulse-platform/plantpulse-startup/stop.sh

# 재시작
/opt/kopens/plantpulse-platform/plantpulse-startup/restart.sh

# 상태 확인
/opt/kopens/plantpulse-platform/plantpulse-startup/status.sh

# 로그 통합 뷰어
/opt/kopens/plantpulse-platform/plantpulse-startup/log-viewer.sh

# 로그 삭제
/opt/kopens/plantpulse-platform/plantpulse-startup/log-delete.sh

# 임시 파일 및 로그 전체 삭제 (플랫폼 정지 상태에서만 실행)
/opt/kopens/plantpulse-platform/plantpulse-startup/clean.sh
```

환경 변수는 `vi /opt/kopens/plantpulse-platform/plantpulse-startup/env.sh` 로 편집하며, 변수 체계는 컨테이너 환경(`DOCKER_PP_*`)과 다른 `PP_*` 접두어를 사용합니다 (`PP_HOST_IP`, `PP_DATA_DIR`, `PP_CLUSTER_CORES` 등). 자세한 내용은 [바이너리 설치](/plantpulse-platform/installation/java-tomcat.md) 페이지를 참고해 주세요.

컨테이너 환경의 컴포넌트 단위 재시작 스크립트(`restart-server.sh` 등)는 바이너리 환경에서도 동일한 이름으로 `/opt/kopens/plantpulse-platform/plantpulse-startup/` 에 존재합니다.

## 노드 관리 스크립트 (컨테이너 내부 / 바이너리 공통)

Cassandra 및 데이터베이스 관리 스크립트는 컨테이너 내부 또는 바이너리 설치의 `/opt/kopens/plantpulse-platform/plantpulse-startup/` 에서 공통적으로 제공됩니다.

### Cassandra 관리

| 스크립트                       | 설명                   | 사용 시기          |
| -------------------------- | -------------------- | -------------- |
| `node-status.sh`           | 클러스터 상태 확인           | 정기 점검, 문제 확인 시 |
| `node-cql.sh`              | CQL 셸 접속             | 데이터 직접 조회 시    |
| `node-info.sh`             | 노드 상세 정보             | 노드 설정 확인 시     |
| `node-compact.sh`          | 수동 컴팩션 실행            | 디스크 공간 확보 시    |
| `node-compactionstats.sh`  | 컴팩션 진행 상태 확인         | 성능 점검 시        |
| `node-flush.sh`            | Memtable 플러시         | 메모리 정리 시       |
| `node-drain.sh`            | 노드 Drain (안전한 종료 준비) | 노드 종료 전        |
| `node-repair.sh`           | 노드 데이터 복구/동기화        | 데이터 불일치 시      |
| `node-repair-table.sh`     | 특정 테이블 복구            | 테이블 단위 복구      |
| `node-cleanup.sh`          | 노드 정리 (불필요 데이터 삭제)   | 노드 변경 후        |
| `node-remove.sh`           | 클러스터에서 노드 제거         | 노드 해제 시        |
| `node-added.sh`            | 클러스터에 노드 추가          | 확장 시           |
| `node-upgrade.sh`          | 노드 업그레이드             | 버전 업그레이드 시     |
| `node-tpstats.sh`          | 스레드풀 통계              | 성능 분석 시        |
| `node-proxyhistograms.sh`  | 프록시 히스토그램            | 지연 분석 시        |
| `node-table-histograms.sh` | 테이블 히스토그램            | 테이블 성능 분석      |
| `node-table-stats.sh`      | 테이블 통계               | 데이터 크기/건수 확인   |
| `node-sstable-size.sh`     | SSTable 크기 확인        | 디스크 사용량 확인     |
| `node-cache-clear.sh`      | 캐시 초기화               | 캐시 문제 시        |
| `node-topic.sh`            | Kafka 토픽 관리          | 메시징 점검 시       |
| `node-disk.sh`             | 디스크 사용량 확인           | 용량 점검 시        |
| `node-error.sh`            | 에러 로그 확인             | 에러 진단 시        |
| `node-train-zstd.sh`       | ZStandard 압축 학습      | 압축 최적화 시       |
| `node-init-cms.sh`         | CMS 초기화              | 초기 설정 시        |

### 데이터베이스 접속

| 스크립트           | 설명                          |
| -------------- | --------------------------- |
| `node-psql.sh` | PostgreSQL 셸 접속 (메타데이터 DB)  |
| `node-cql.sh`  | Cassandra CQL 셸 접속 (시계열 DB) |

### 설정 스크립트

| 스크립트           | 설명                                       |
| -------------- | ---------------------------------------- |
| `configure.sh` | 플랫폼 설정 스크립트 (env.sh 기반으로 각 서비스 설정 자동 생성) |
| `prepared.sh`  | 시작 전 환경 검증 및 준비 (필수 디렉토리, 권한 등 확인)       |

> **컨테이너 환경에서 실행**: 노드 관리 스크립트는 컨테이너 내부에서 실행해야 합니다. `./platform-bash.sh` 로 진입 후 `/opt/kopens/plantpulse-platform/plantpulse-startup/` 에서 사용해 주세요.

## 자주 쓰는 명령 요약

```bash
cd /home/kopens/plantpulse-platform-docker/bin

./preflight.sh             # 설치 전 비파괴 사전 점검
./install.sh               # 최초 설치 (OS+Docker+방화벽+컨테이너)
./start.sh                 # 정지된 컨테이너 시작
./platform-stop.sh         # 컨테이너 정지 (state 보존)
./restart.sh               # graceful 재시작 (drain + health 대기)
./platform-remove.sh       # 컨테이너 제거 (DESTRUCTIVE, 볼륨은 보존)
./status.sh                # 컨테이너 / health / 볼륨 요약
./ops-check.sh             # 운영 health + critical log 점검
./doctor.sh                # 장애 진단 tarball 생성
./platform-bash.sh         # 컨테이너 bash 진입
./platform-update.sh       # 이미지 갱신 (pull + recreate + rollback)
./platform-verify-boot.sh  # 부팅 후 전체 컴포넌트 로그 검증
```