> 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/faq.md).
# FAQ
PlantPulse 플랫폼을 운영하시는 분들이 자주 묻는 질문과 답변을 모아 놓았습니다. 더 자세한 절차가 필요한 경우 [문제 해결](/plantpulse-platform/admin/troubleshooting.md) 페이지를 참고해 주세요.
## 설치 / 라이선스
### Q. Docker 설치와 바이너리 설치 중 어떤 것을 선택해야 하나요?
A. 특별한 사유가 없다면 **원라인 설치(Docker 기반)** 를 권장합니다. 원라인 명령 한 줄로 OS 셋업부터 방화벽, 컨테이너 기동까지 자동 처리되며 업데이트와 롤백도 간편합니다. 바이너리 설치는 Docker 를 사용할 수 없는 환경에서만 권장합니다.
### Q. 폐쇄망에서도 설치할 수 있나요?
A. 가능합니다. 인터넷이 연결된 노드에서 `./airgap-bundle.sh` 로 번들을 생성한 뒤, USB 또는 내부 파일 서버로 폐쇄망에 옮긴 후 `./airgap-load.sh` 를 실행하면 됩니다. 자세한 절차는 [Docker 설치 - 폐쇄망(Airgap) 설치](/plantpulse-platform/installation/docker.md) 섹션을 참고해 주세요.
### Q. 라이선스는 어떻게 발급받나요?
A. 이미지 registry 자격증명과 라이선스는 KOPENS 운영팀에서 발급해 드립니다. **** 으로 문의해 주세요.
### Q. 최소 / 권장 사양은 어떻게 되나요?
A. 단일 노드 기준:
| 구분 | 최소 | 권장 |
| --- | ---------------------------------------------------------- | --------------- |
| CPU | 16 vCPU | 32 vCPU |
| 메모리 | 64GB | 200GB |
| 디스크 | 200GB | 1TB+ (데이터량에 따라) |
| OS | Oracle Linux 8 / RHEL 9 / Ubuntu 22.04 / Amazon Linux 2023 | 동일 |
상세 사양은 [시스템 요구사항](/plantpulse-platform/installation/requirements.md) 페이지를 참고해 주세요.
### Q. 어떤 OS 를 지원하나요?
A. 다음 OS 에서 원라인 설치를 지원합니다.
* Oracle Linux 8.x
* RHEL / Rocky Linux 8.x, 9.x
* Ubuntu 22.04+
* Amazon Linux 2, 2023
검증되지 않은 OS 에서는 `SKIP_OS=1` 옵션으로 OS 셋업을 건너뛰고 수동 셋업할 수 있습니다.
### Q. Podman 으로도 운영할 수 있나요?
A. 가능합니다. `bin/env.sh` 의 `DOCKER_CMD="docker"` 를 `DOCKER_CMD="podman"` 으로 변경하시면 모든 스크립트가 Podman 으로 동작합니다.
## 설치 / 기동
### Q. 설치는 얼마나 걸리나요?
A. 원라인 설치 기준 **OS 셋업 + Docker 설치 + 이미지 다운로드 + 컨테이너 기동** 까지 약 10\~20분 (네트워크 속도에 따라 다름) 이 소요됩니다. 이후 컨테이너 내부 부팅은 추가로 **3\~5분** 정도 걸립니다 (Cassandra 스키마 마이그레이션 + JVM warm-up).
### Q. 설치 후 어디로 접속하면 되나요?
A. 브라우저에서 다음 주소로 접속해 주세요.
```
http://[서버IP]:7500
```
* `[서버IP]` 는 `env.sh` 의 `DOCKER_PP_EXTERNAL_IP` 값입니다.
* 기본 관리자 계정: `admin` / `admin123!`
* 로그인 후 반드시 비밀번호를 변경해 주세요.
### Q. 시작했는데 health 가 unhealthy 로 표시됩니다.
A. 부팅에 3\~5분이 소요됩니다. 5분이 지나도 unhealthy 상태라면 [문제 해결 - 컨테이너 기동 문제](/plantpulse-platform/admin/troubleshooting.md#container-startup) 를 참고해 주세요.
### Q. `env.sh` 를 변경했는데 적용되지 않습니다.
A. `env.sh` 변경은 부팅 시점에만 반영됩니다. 반드시 다음 명령으로 재시작해야 적용됩니다.
```bash
cd /home/kopens/plantpulse-platform-docker/bin
./restart.sh
```
### Q. 서버 재부팅 후 자동으로 시작되게 하려면?
A. 컨테이너는 `--restart unless-stopped` 정책으로 실행되므로 Docker 데몬이 시작되면 자동으로 함께 시작됩니다. Docker 데몬 자체는 `systemctl enable docker` 로 부팅 시 자동 시작되도록 설정되어 있습니다.
## 운영 / 관리
### Q. 플랫폼을 어떻게 시작 / 중지 / 재시작하나요?
A. 호스트의 `/home/kopens/plantpulse-platform-docker/bin/` 에서:
```bash
./start.sh # 시작
./platform-stop.sh # 중지 (데이터 보존)
./restart.sh # 재시작 (graceful drain + health 대기)
```
자세한 내용은 [시작 가이드](/plantpulse-platform/installation/startup-guide.md) 페이지를 참고해 주세요.
### Q. 전체를 재시작하지 않고 일부 컴포넌트만 재시작할 수 있나요?
A. 가능합니다. `./platform-bash.sh` 로 컨테이너에 진입한 뒤 `/opt/kopens/plantpulse-platform/plantpulse-startup/restart-*.sh` 를 실행하면 됩니다.
```bash
./platform-bash.sh
/opt/kopens/plantpulse-platform/plantpulse-startup/restart-server.sh # 웹 서버만 재시작
exit
```
자세한 스크립트 목록은 [운영 관리 - 컴포넌트 개별 재시작](https://kopens.gitbook.io/plantpulse-platform/admin/pages/MaBYfVKuySzSQbQqHNKI#컴포넌트-개별-재시작) 을 참고해 주세요.
### Q. 로그는 어디서 볼 수 있나요?
A. 호스트에서 컨테이너 표준 로그를 볼 수 있고, 컨테이너 내부에서 모듈별 상세 로그를 볼 수 있습니다.
```bash
# 호스트에서 컨테이너 로그
docker logs plantpulse-platform --tail 200
docker logs plantpulse-platform -f # 실시간 follow
# 모듈별 상세 로그 — 컨테이너 내부 접속 후
./platform-bash.sh
tail -f /opt/kopens/plantpulse-platform/plantpulse-server/logs/system.log
# 모듈별 로그를 호스트로 한 번에 복사
./util/copy-log-to-local.sh
```
### Q. 백업은 어떻게 하나요?
A. Docker 볼륨 단위로 tar.gz 백업이 가능합니다.
```bash
cd /home/kopens/plantpulse-platform-docker/bin/util
./backup-volume.sh pp-data 7 /data1/pp-backup/docker-volume
```
권장 백업 주기는 [운영 관리 - 백업과 복구](https://kopens.gitbook.io/plantpulse-platform/admin/pages/MaBYfVKuySzSQbQqHNKI#백업과-복구) 를 참고해 주세요.
### Q. 새 버전이 나오면 어떻게 업데이트하나요?
A. 무중단 업데이트 명령으로 처리됩니다.
```bash
cd /home/kopens/plantpulse-platform-docker/bin
./platform-update.sh
```
자동 수행: `docker pull` → graceful 종료 → 새 이미지로 재생성 → health 검증 → 실패 시 자동 rollback. 데이터는 볼륨에 별도 저장되므로 안전합니다.
### Q. 업데이트 후 문제가 생기면 어떻게 롤백하나요?
A. `./platform-update.sh` 는 health 검증 실패 시 자동 rollback 됩니다. 자동 rollback 이후에도 문제가 있거나 수동 rollback 이 필요하면 `env.sh` 의 `DOCKER_PP_VERSION` 을 이전 안정 버전으로 지정 후 `./platform-update.sh` 를 다시 실행하면 됩니다.
### Q. 워커 노드를 추가해서 클러스터를 구성할 수 있나요?
A. 가능합니다. `env.sh` 의 `DOCKER_PW_IP_ARRAY` 에 워커 IP 를 지정한 뒤:
```bash
cd /home/kopens/plantpulse-platform-docker/bin
./worker-run.sh # 워커 번호 입력
```
자세한 내용은 [클러스터 설치](/plantpulse-platform/installation/build-deploy.md) 페이지를 참고해 주세요.
### Q. 컨테이너 메모리를 늘리려면?
A. `env.sh` 의 `DOCKER_PP_MEMORY` 를 수정 후 다음 중 하나를 실행하세요.
```bash
# 방법 1 — 재시작 (재시작 다운타임 발생)
./restart.sh
# 방법 2 — 컨테이너 재생성 없이 메모리만 실시간 갱신
./util/update-memory.sh
```
## 데이터 / 성능
### Q. 데이터는 어디에 저장되나요?
A. 호스트의 Docker 볼륨에 저장됩니다.
| 볼륨 | 용도 |
| ------------- | ------------------------------------- |
| `pp-data` | 메인 데이터 (Cassandra, PostgreSQL, MinIO) |
| `pp-temp` | 임시 처리 파일 |
| `pp-backup` | 자체 백업 |
| `pp-security` | 인증서 / 키 |
| `pp-template` | 템플릿 데이터 |
실제 호스트 경로는 `/data1/docker-data/volumes/` 입니다 (`env.sh` 의 `DOCKER_DATA_DIR` 로 변경 가능).
### Q. 컨테이너를 제거해도 데이터는 남나요?
A. 네, `./platform-remove.sh` 는 컨테이너만 제거하며 볼륨은 그대로 보존됩니다. 다시 설치하면 이전 데이터를 그대로 사용할 수 있습니다. 볼륨까지 완전히 제거하려면 `./util/remove-all-volumes.sh` 를 실행해야 합니다.
### Q. 데이터 보관 기간을 조정할 수 있나요?
A. Cassandra TTL 설정으로 시계열 데이터의 보관 기간을 조정할 수 있습니다. 콘솔의 시스템 설정 또는 properties 에서 변경 가능합니다. 자세한 내용은 [성능 튜닝](/plantpulse-platform/admin/performance-tuning.md) 및 [프로퍼티 레퍼런스](/plantpulse-platform/admin/properties-reference.md) 를 참고해 주세요.
### Q. 응답이 느려졌습니다. 어떻게 진단하나요?
A. 다음 순서로 점검해 주세요.
```bash
# 1. 컨테이너 자원 사용량
docker stats plantpulse-platform
# 2. 호스트 부하
top
df -h
# 3. critical 로그 확인
./ops-check.sh
# 4. Cassandra 컴팩션 / 디스크 I/O
./platform-bash.sh
/opt/kopens/plantpulse-platform/plantpulse-startup/node-compactionstats.sh
```
자세한 튜닝은 [성능 튜닝](/plantpulse-platform/admin/performance-tuning.md) 페이지를 참고해 주세요.
### Q. Cassandra 디스크 사용량이 너무 큽니다.
A. 다음 명령으로 정리할 수 있습니다.
```bash
./platform-bash.sh
/opt/kopens/plantpulse-platform/plantpulse-startup/node-cleanup.sh # 불필요 데이터 정리
/opt/kopens/plantpulse-platform/plantpulse-startup/node-compact.sh # 수동 컴팩션
```
장기적으로는 보관 기간(TTL) 조정 또는 디스크 확장을 검토해 주세요.
## 보안 / 사용자
### Q. 기본 비밀번호는 무엇이고, 어디서 변경하나요?
A. 기본 관리자 계정은 `admin / admin123!` 입니다. 로그인 후 우측 상단 사용자 아이콘 > 비밀번호 변경 메뉴에서 즉시 변경해 주세요.
데이터베이스 / 메시징 등의 서비스 계정 비밀번호는 `bin/env.sh` 의 `PP_*_PASSWORD` 변수로 관리되며, 첫 설치 시 `/etc/kopens/platform.env.generated` 에 저장됩니다 (mode 0600).
### Q. 사용자 / 권한 관리는 어떻게 하나요?
A. 콘솔의 **보안 관리** 메뉴에서 사용자, 역할(role), 권한을 관리할 수 있습니다. 자세한 내용은 [사용자 관리](/plantpulse-platform/admin/user-management.md) 및 [보안 설정](/plantpulse-platform/admin/security.md) 페이지를 참고해 주세요.
### Q. HTTPS 인증서를 변경하려면?
A. 인증서는 `pp-security` 볼륨에 저장됩니다. 정기적인 교체가 권장됩니다. 자세한 절차는 [보안 설정](/plantpulse-platform/admin/security.md) 페이지를 참고해 주세요.
### Q. 외부에 노출해야 하는 포트는 어떻게 되나요?
A. 사용자 / 외부 시스템 접근용으로는 **80, 443, 7443, 4949** 만 노출하는 것을 권장합니다. 나머지 포트 (DB, Kafka, 클러스터, JMX) 는 사설망에서만 접근 가능하도록 제한해 주세요. 자세한 포트 목록은 [Docker 설치](/plantpulse-platform/installation/docker.md) 페이지의 방화벽 / 포트 섹션을 참고해 주세요.
### Q. 다중 노드 환경에서 노드 간 통신은 어떻게 보호되나요?
A. JGroups, Cassandra, Kafka 등 클러스터 내부 통신은 RFC 1918 사설망 (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) 및 Tailscale CGN 대역(`100.64.0.0/10`) 에서만 접근 가능하도록 source 제한이 자동 적용됩니다.
## 다국어 / 타임존
### Q. 영문 UI 로 운영할 수 있나요?
A. 가능합니다. `env.sh` 에서:
```bash
export PP_LANG=en
export PP_TZ=America/New_York # 운영 지역 타임존
```
수정 후 `./restart.sh`. 단, **Cassandra 시계열 데이터가 KST epoch 로 적재되므로 한국 운영 시에는 반드시 `PP_TZ=Asia/Seoul` 을 유지**해야 합니다.
### Q. PlantPulse 는 사용자별로 한국어 / 영문 UI 를 전환할 수 있나요?
A. 아니요. 플랫폼은 **서버 인스턴스 당 단일 로케일** 모델을 사용합니다. JVM 부트 타임에 환경 변수로 고정되며 사용자별 토글은 지원하지 않습니다. 한국 박스 = `ko`, 글로벌 박스 = `en` 으로 운영해 주세요.
## 외부 시스템 연동
### Q. OPC-UA 서버와 어떻게 연결하나요?
A. 콘솔의 **연결 관리** 메뉴에서 OPC-UA 서버 정보(URL, 인증, 보안 정책) 를 등록하고, 수집할 태그를 매핑합니다. 자세한 절차는 [연결 관리](/plantpulse-platform/user/connection.md) 페이지를 참고해 주세요.
### Q. MQTT 디바이스에서 데이터를 보내려면?
A. 호스트 IP 의 1883 (PLAINTEXT) 또는 18883 (TLS) 포트로 MQTT 브로커(HiveMQ) 에 접속하면 됩니다. 인증 정보는 `env.sh` 의 `PP_MQ_USER` / `PP_MQ_PASSWORD` 입니다.
### Q. API 로 외부 시스템과 연동하려면?
A. 모든 기능은 REST API 로도 제공됩니다. [개발자 가이드 - API 사용 매뉴얼](/plantpulse-platform/developer/api-manual.md) 을 참고해 주세요.
## 모니터링 / 알람
### Q. 플랫폼 상태를 외부 모니터링 시스템에 연동하려면?
A. 헬스 엔드포인트와 ops-check 결과를 모니터링 시스템에서 polling 할 수 있습니다.
```bash
# Healthcheck 엔드포인트 (모니터링용)
curl -kfsS https://[서버IP]:4950/api/health
# 운영 health + critical log (스크립트 호출)
ssh root@[서버IP] /home/kopens/plantpulse-platform-docker/bin/ops-check.sh
```
자세한 내용은 [시스템 모니터링](/plantpulse-platform/admin/monitoring.md) 페이지를 참고해 주세요.
### Q. 알람을 이메일이나 SMS 로 받을 수 있나요?
A. 이메일은 SMTP 설정을 통해 지원됩니다. 콘솔의 **알람** > 알림 설정에서 구성할 수 있습니다. SMS / 메신저(Slack 등) 연동은 외부 webhook 또는 Flow 엔진을 통해 구성 가능합니다.
## 지원 / 문의
### Q. 어디서 도움을 받을 수 있나요?
A. 다음 자료를 우선 확인해 주세요.
* [문제 해결](/plantpulse-platform/admin/troubleshooting.md) — 증상별 진단과 해결 절차
* [운영 관리](/plantpulse-platform/installation/database.md) — 일상 운영 명령
* [시스템 모니터링](/plantpulse-platform/admin/monitoring.md) — 상태 점검
* 진단 tarball: `./doctor.sh` 실행 후 생성되는 파일
위 자료로도 해결되지 않으면 **** 으로 진단 tarball 과 함께 문의해 주세요.
### Q. 어떤 정보를 함께 보내야 하나요?
A. [문제 해결 - 지원 요청 시 필요한 정보](/plantpulse-platform/admin/troubleshooting.md#support) 섹션을 참고해 주세요. `./doctor.sh` 가 생성하는 진단 tarball 에는 필요한 대부분의 정보가 포함되어 있습니다 (비밀번호 등 민감 정보는 자동 마스킹).
### Q. 어디서 최신 문서를 볼 수 있나요?
A. 에서 항상 최신 문서를 확인하실 수 있습니다.