> 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/database.md).

# 운영 관리

## 개요

이 페이지에서는 원라인 설치로 구축된 플랜트펄스 플랫폼의 일상적인 운영 관리 방법을 안내합니다. 모든 운영 스크립트는 호스트의 `/home/kopens/plantpulse-platform-docker/bin/` 디렉토리에 있으며, 컨테이너 라이프사이클, 로그 관리, 백업, 업데이트, 제거 등의 작업을 다룹니다.

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

## 일상 운영 명령

### 플랫폼 시작 / 정지 / 재시작

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

./start.sh           # 정지된 컨테이너 시작
./platform-stop.sh   # 컨테이너 정지 (데이터 볼륨 보존)
./restart.sh         # graceful 재시작 (drain → stop → start → health 대기)
```

전체 부팅에는 약 **3 \~ 5분** (Cassandra 스키마 마이그레이션 + JVM warm-up) 이 소요됩니다.

> **데이터 안전**: `./platform-stop.sh` 는 컨테이너만 정지하며, Docker 볼륨(`pp-data`, `pp-temp`, `pp-backup`, `pp-security`, `pp-template`)에 저장된 데이터는 그대로 보존됩니다. 직접 `docker kill` 이나 호스트 강제 종료는 사용하지 마세요.

### 상태 확인

```bash
./status.sh                                        # 컨테이너 / health / 볼륨 요약
./ops-check.sh                                     # 운영 health + 최근 critical log 점검
curl -kfsS https://127.0.0.1:4950/api/health | jq  # 헬스 엔드포인트 직접 호출
docker ps                                          # STATUS = (healthy) 확인
docker stats plantpulse-platform                   # CPU / 메모리 실시간
```

자세한 시작/재시작 절차는 [시작 가이드](/plantpulse-platform/installation/startup-guide.md) 페이지를 참고해 주세요.

## 로그 관리

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

```bash
docker logs plantpulse-platform --tail 200
docker logs plantpulse-platform -f                 # 실시간 follow
docker logs plantpulse-platform --since 1h         # 최근 1시간
```

### 컨테이너 내부 모듈별 로그

`./platform-bash.sh` 로 컨테이너에 진입하면 `/home/kopens/plantpulse-*/` 하위에서 모듈별 로그를 확인할 수 있습니다. 주요 경로는 [시작 가이드 - 로그 관리](https://kopens.gitbook.io/plantpulse-platform/installation/pages/ZVrRa1Exw1Tw5VM3cNUl#로그-관리) 표를 참고해 주세요.

### 로그를 호스트로 일괄 복사

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

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

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

* `plantpulse-messaging/` — Kafka, MQTT 등 메시징 로그
* `plantpulse-storage/` — Cassandra, PostgreSQL, Valkey, MinIO 로그
* `plantpulse-server/` — 웹 서버 로그
* `plantpulse-batch/` — 배치 처리 로그

### 진단 tarball 생성

장애 상황에서 컨테이너 상태, 설정, 호스트 환경, 로그를 한 번에 수집합니다. 비밀번호 등 민감 정보는 자동 마스킹됩니다.

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

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

## 컴포넌트 개별 재시작

전체 컨테이너를 재시작하지 않고 내부의 특정 컴포넌트만 재시작하려면 컨테이너에 진입해서 작업합니다.

```bash
# 호스트에서 컨테이너 진입
cd /home/kopens/plantpulse-platform-docker/bin
./platform-bash.sh

# 컨테이너 내부에서 컴포넌트별 재시작
/opt/kopens/plantpulse-platform/plantpulse-startup/restart-server.sh
exit
```

| 분류     | 스크립트 (컨테이너 내부)            | 설명                            |
| ------ | ------------------------- | ----------------------------- |
| 애플리케이션 | `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              |

> **참고**: 인프라 모듈(스토리지, 분석, 메시징)을 재시작한 경우, 해당 모듈에 의존하는 애플리케이션(서버, 에이전트, 배치 등)도 함께 재시작해 주시는 것이 좋습니다. 인프라 모듈이 재시작되면 연결이 끊어질 수 있기 때문입니다.
>
> **권장**: 일반적인 운영에서는 호스트의 `./restart.sh` 로 전체 컨테이너를 재시작하는 것이 가장 안전합니다. 컴포넌트 단위 재시작은 특정 모듈만 격리해서 검증하거나 긴급 조치가 필요한 경우에 사용해 주세요.

## 환경 변수 조정

운영 환경에 맞춰 자원 / 외부 IP / 다국어 등을 조정해야 할 때:

```bash
cd /home/kopens/plantpulse-platform-docker/bin
vi env.sh
./restart.sh    # 변경 사항은 재시작 후 반영
```

자주 조정하는 항목:

| 변수                      | 설명                    | 기본값               |
| ----------------------- | --------------------- | ----------------- |
| `DOCKER_PP_EXTERNAL_IP` | 외부 노출 IP              | `111.222.333.444` |
| `DOCKER_PP_CPUS`        | 컨테이너 vCPU 수           | `32`              |
| `DOCKER_PP_MEMORY`      | 컨테이너 메모리 상한           | `200G`            |
| `PP_LANG`               | 플랫폼 로케일 (`ko` / `en`) | `ko`              |
| `PP_TZ`                 | 플랫폼 타임존               | `Asia/Seoul`      |

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

### 메모리 제한 실시간 변경

컨테이너를 재생성하지 않고 현재 실행 중인 컨테이너의 메모리 제한을 `env.sh` 값으로 갱신할 수 있습니다.

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

## 백업과 복구

### 볼륨 백업

Docker 볼륨 단위로 데이터를 tar.gz 파일로 백업합니다. 정기적으로 수행하시는 것을 권장합니다.

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

./backup-volume.sh pp-data 7 /data1/pp-backup/docker-volume
./backup-volume.sh pp-security 30 /data1/pp-backup/docker-volume
```

| 인자   | 설명                           | 기본값                              |
| ---- | ---------------------------- | -------------------------------- |
| 첫 번째 | 백업할 볼륨 이름 (필수)               | -                                |
| 두 번째 | 백업 보관 일수 (이보다 오래된 백업은 자동 삭제) | 7일                               |
| 세 번째 | 백업 저장 경로                     | `/data1/pp-backup/docker-volume` |

권장 백업 주기:

| 볼륨            | 권장 주기              | 보관 일수     |
| ------------- | ------------------ | --------- |
| `pp-data`     | 일 1회               | 7 \~ 14일  |
| `pp-security` | 변경 시 또는 월 1회       | 30 \~ 90일 |
| `pp-template` | 변경 시               | 7일        |
| `pp-backup`   | 별도 백업 불필요 (자체가 백업) | -         |
| `pp-temp`     | 백업 대상 아님           | -         |

> **상세 절차**: 시점 복구, 부분 복구, 외부 스토리지 동기화 등 상세 백업/복구 절차는 [관리자 가이드 - 백업 및 복구](/plantpulse-platform/admin/backup-recovery.md) 페이지를 참고해 주세요.

### 복구

백업 파일을 풀어 볼륨에 다시 적재합니다.

```bash
# 1. 플랫폼 정지
cd /home/kopens/plantpulse-platform-docker/bin
./platform-stop.sh

# 2. 볼륨 데이터 복구 (예: pp-data 볼륨)
docker run --rm -v pp-data:/restore -v /data1/pp-backup/docker-volume:/backup \
  alpine sh -c "cd /restore && tar xzf /backup/pp-data-YYYYMMDD.tar.gz"

# 3. 플랫폼 시작
./start.sh
./status.sh
```

## 플랫폼 업데이트

새 이미지가 릴리즈되면 아래 명령으로 무중단 업데이트할 수 있습니다.

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

자동 수행 순서:

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

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

```bash
# 현재 이미지 버전 확인
./platform-version.sh
```

## 워커 운영 (클러스터 환경)

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

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

./worker-run.sh           # 워커 추가 (프롬프트에서 워커 번호 입력)
./worker-stop.sh          # 워커 정지
./worker-update.sh        # 워커 이미지 갱신
./worker-remove.sh        # 워커 제거
./worker-bash.sh          # 워커 컨테이너 셸 진입
./worker-verify-boot.sh   # 워커 부팅 후 컴포넌트 로그 검증
```

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

## 플랫폼 제거

### 컨테이너만 제거 (데이터는 보존)

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

확인 프롬프트에서 `YES` 를 입력해야만 제거가 진행됩니다 (`YES=1 ./platform-remove.sh` 로 프롬프트 건너뛰기 가능).

> **데이터 보호**: 기본 동작은 컨테이너만 제거하며 볼륨(데이터)은 그대로 보존됩니다. 다시 `./install.sh` 또는 `platform-run.sh` 를 실행하면 이전 데이터로 복구됩니다.

### 이미지 / 네트워크 함께 제거

```bash
# 이미지까지 제거
RM_IMAGE=1 ./platform-remove.sh

# Docker 네트워크까지 제거
RM_NETWORK=1 ./platform-remove.sh

# 모두 제거
RM_IMAGE=1 RM_NETWORK=1 ./platform-remove.sh
```

### 데이터(볼륨)까지 완전 제거

> **주의**: 이 명령은 모든 데이터를 영구적으로 삭제합니다. 실행 전에 반드시 [볼륨 백업](#볼륨-백업)을 완료하셨는지 확인해 주세요. 삭제된 데이터는 복구할 수 없습니다.

```bash
cd /home/kopens/plantpulse-platform-docker/bin/util
./remove-all-volumes.sh
```

확인 프롬프트에서 `YES` 를 입력해야만 삭제가 진행됩니다.

### 설치 디렉토리까지 제거

```bash
# 1. 플랫폼 완전 제거
cd /home/kopens/plantpulse-platform-docker/bin
RM_IMAGE=1 RM_NETWORK=1 ./platform-remove.sh

# 2. 볼륨 제거 (위 단계 수행 후)
./util/remove-all-volumes.sh

# 3. 설치 디렉토리 삭제
rm -rf /home/kopens/plantpulse-platform-docker
```

## 자주 쓰는 명령 요약

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

# 라이프사이클
./start.sh                 # 시작
./platform-stop.sh         # 정지
./restart.sh               # 재시작
./platform-update.sh       # 이미지 갱신 + rollback

# 상태 / 진단
./status.sh                # 상태 요약
./ops-check.sh             # 운영 health + critical log
./platform-verify-boot.sh  # 부팅 로그 검증
./doctor.sh                # 진단 tarball 생성

# 컨테이너 접근
./platform-bash.sh         # 컨테이너 bash 진입
./platform-version.sh      # 이미지 버전 확인

# 유틸리티
./util/backup-volume.sh    # 볼륨 백업
./util/copy-log-to-local.sh   # 로그 호스트로 복사
./util/update-memory.sh    # 메모리 제한 변경
./util/stats.sh            # 리소스 모니터링

# 제거 (DESTRUCTIVE)
./platform-remove.sh           # 컨테이너 제거 (볼륨 보존)
./util/remove-all-volumes.sh   # 볼륨까지 제거
```

## FAQ

| 질문                                | 답변                                                                                                                                                                         |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 컨테이너가 `unhealthy` 상태에서 회복되지 않습니다. | `docker logs plantpulse-platform --tail 200` 으로 에러를 확인하고 `./doctor.sh` 로 진단 tarball 을 생성한 뒤 기술 지원팀에 문의해 주세요. Cassandra 스키마 마이그레이션 실패 또는 `/data1/pp-data` 권한 문제일 가능성이 높습니다. |
| 브라우저에서 콘솔에 접속이 안 됩니다.             | `env.sh` 의 `DOCKER_PP_EXTERNAL_IP` 가 서버의 실제 IP 와 일치하는지 확인해 주세요. 변경 후에는 `./restart.sh` 로 적용해야 합니다. 호스트 방화벽도 함께 확인해 주세요 (`firewall-cmd --list-ports`).                       |
| 디스크 공간이 부족합니다.                    | 오래된 백업 파일을 정리하거나 `./util/system.sh` 로 Docker 이미지 / 빌드 캐시 사용량을 확인해 주세요. 필요 시 `docker system prune` 으로 미사용 이미지를 정리할 수 있습니다.                                                  |
| 업데이트 후 문제가 발생했습니다.                | `./platform-update.sh` 는 health 검증에 실패하면 자동으로 이전 이미지로 rollback 됩니다. 수동 rollback 이 필요한 경우 `DOCKER_PP_VERSION` 을 이전 태그로 지정하고 `./platform-update.sh` 를 다시 실행해 주세요.            |

## 기술 지원

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

| 담당    | 연락처                    |
| ----- | ---------------------- |
| 영업 지원 | <webmaster@kopens.com> |
| 기술 지원 | <webmaster@kopens.com> |