포트 및 서비스 관리 (운영자 가이드)

이 페이지는 운영 중인 PlantPulse 의 포트 상태를 점검하고 문제를 해결하는 절차를 안내합니다. 전체 포트 카탈로그는 설치 가이드 - 포트 구성 정보 페이지를 참고해 주세요.

일상 점검 체크리스트

1. 서비스 상태 점검

`status.sh` — 스택 전체 상태 (호스트)

먼저 호스트에서 스택 상태를 봅니다. 서비스 목록·컨테이너 상태·health·볼륨을 요약하며, 종료 코드가 계약입니다 — 0 이 정상, 2 가 비정상이라 모니터링 자동화에 그대로 쓸 수 있습니다.

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

원샷의 Exited (0) 은 성공입니다

plantpulse-certs 는 인증서를 굽고 끝나는 원샷이라 Exited (0) 이 정상입니다. compose 가 이 컨테이너의 헬스체크를 명시적으로 꺼 두었으므로(healthcheck: disable) docker ps 의 health 칸도 비어 있습니다 — status.sh 는 종료 코드로 판정합니다.

모듈별 포트 점유 (데이터레이크 컨테이너 안)

인프라 컴포넌트의 포트 점유 / PID / CPU / 메모리(PSS)를 보려면 데이터레이크 컨테이너 안의 status.sh 를 씁니다.

cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd status

출력 예시:

==============================================================================================================
 PLANTPULSE PLATFORM - ALL SERVICE STATUS
==============================================================================================================

<SYSTEM RESOURCE OVERVIEW>
  CPU LOAD (AVG)         :   12.3% (48 cores)
  MEMORY USAGE           :   65.2% (123.1G / 188.7G)
  DATA DISK USAGE        :   45.8% (2.2T / 4.8T)

<SERVICE STATUS BY PORT>
  SERVICE                 | PORT  | STATUS  | PID    | CPU   | MEMORY (PSS)
  PP_MESSAGING[KAFKA]     | 9092  | RUNNING | 12345  |  2.3% |   8.5G ( 4.5%)
  PP_STORAGE[CASSANDRA]   | 9042  | RUNNING | 12567  |  5.1% |  16.2G ( 8.6%)
  PP_SERVER               | 80    | RUNNING | 12890  |  1.2% |   4.8G ( 2.5%)
  ...

<SERVICE SUMMARY>
  TOTAL SERVICES         : 25 RUNNING / 0 STOPPED
  TOTAL CPU (SUM)        :  42.3%
  TOTAL MEMORY (PSS)     :  78.5% (148.0G)

`ops-check.sh` — 헬스 + 최근 critical 로그

./ops-check.sh

다음을 자동으로 수행합니다.

HTTPS 헬스 엔드포인트 (https://127.0.0.1:4950/api/health) 응답 확인
최근 critical / fatal 로그 메시지 수집
모듈별 응답 시간 측정

외부 헬스 체크 (모니터링 시스템 연동)

# 호스트 / 외부에서 — 4950 이 유일하게 publish 되는 헬스 포트입니다
curl -kfsS https://[HOST]:4950/api/health | jq

# 컨테이너 안에서 — 어떤 구성에서도 동작합니다
docker exec plantpulse-datalake curl -kfsS https://127.0.0.1:4950/api/health | jq

4949 와 4950 은 같은 콘솔입니다

콘솔과 헬스 API 는 두 포트 모두에서 서비스됩니다 — 4950(HTTPS)와 4949(평문 HTTP). 같은 콘솔·같은 API 이고 스킴만 다릅니다. 4949 는 더 이상 4950 으로 리다이렉트하지 않습니다.

4949 는 평문입니다 — 로그인 비밀번호와 세션 쿠키가 그대로 흐릅니다. 신뢰할 수 없는 망에서는 4950 을 쓰세요. 4949 는 자체 서명 인증서 경고가 실제로 운영자를 막아 세우는 상자를 위한 선택지입니다.

2. 포트별 빠른 진단

포트	모듈	빠른 점검
80 / 443 / 7443	server	`curl -fsS http://[HOST]/api/v5/ping`
9042	Cassandra	`pd node status` 클러스터 상태
5432	PostgreSQL	`pd node psql` 접속 후 `SELECT 1;`
6379	Valkey	`redis-cli -a $PP_REDIS_PASSWORD ping`
9000	MinIO	`curl -fsS http://[HOST]:9000/minio/health/live`
9092	Kafka	`kafka-broker-api-versions.sh --bootstrap-server [HOST]:9092`
1883	MQTT	`mosquitto_pub -h [HOST] -p 1883 -u mq -P $PP_MQ_PASSWORD -t test -m hi`
7400	CEP	`curl -fsS -H "X-API-Key: $PP_CEP_API_KEY" http://[HOST]:7400/api/v1/status`
5500	Data Gateway	`curl -fsS http://[HOST]:5500/api/health` (익명 readiness — UP 일 때만 200)
7800	TSE	`curl -fsS http://[HOST]:7800/api/health`
7077	Spark Master	`curl -fsS http://[HOST]:4440/json/ \| jq .workers`
10000	Kyuubi	`beeline -u "jdbc:hive2://[HOST]:10000" -e "SELECT 1"`
19001	Gravitino	`curl -fsS -u gravitino:$PP_GRAVITINO_PASSWORD http://[HOST]:19001/api/metalakes`
7233	Temporal	`temporal --address [HOST]:7233 namespace list`
8380	Kestra	`curl -fsS -u admin@plantpulse.io:$PP_KESTRA_ADMIN_PASSWORD http://[HOST]:8380/api/v1/flows`
11004	OPC-UA	UaExpert 등으로 `opc.tcp://[HOST]:11004` 접속
10210	HA 데몬	`curl -fsS http://[HOST]:10210/api/health`
4950	모니터	`curl -kfsS https://[HOST]:4950/api/health \| jq .status`

어느 컨테이너에서 물어보나

80 · 443 · 1883 · 1884 는 plantpulse-proxy 가, 11004 · 11005 는 OPC-UA 플러그인이, 10210 은 HA 컨테이너가, 나머지는 plantpulse-datalake 가 호스트에 publish 합니다. 앱 네 개(server-web · batch-web · warehouse · aasx)는 호스트 포트를 열지 않으므로 ./status.sh · ./logs.sh <컨테이너> 로 확인합니다 → 포트 구성 정보

pd node status · pd node psql 같은 도구는 데이터레이크 컨테이너 안에 있습니다(./shell.sh 로 진입).

3. 포트 충돌 진단

점유 프로세스 확인

# 특정 포트
ss -tlnp | grep ":<포트> "
sudo lsof -i :<포트>

# 일괄 (PlantPulse 모든 핵심 포트)
ss -tlnp | grep -E ':(80|443|1883|1884|3000|4000|4950|5432|5500|6379|7077|7233|7400|7443|7800|8233|8380|9000|9042|9092|10000|10210|11004|19001)\s'

충돌 해결

상황	조치
외부 서비스가 포트 점유	외부 서비스를 다른 포트로 이동
이전 PlantPulse 프로세스 잔존	호스트에 네이티브로 남아 있는 경우 `pkill -ef plantpulse`. 컨테이너 쪽이면 `bin/down.sh` 후 `docker ps -a` 로 잔존 확인
기본 포트가 회사 정책상 사용 불가	호스트에 노출되는 포트는 `compose/docker-compose.yml` 의 `ports:` 가 정합니다. 매핑을 바꾼 뒤 `bin/restart.sh`

4. 방화벽 운영

현재 허용 규칙 조회

# RHEL/Rocky/Oracle (firewalld)
sudo firewall-cmd --list-ports
sudo firewall-cmd --list-rich-rules
sudo firewall-cmd --list-services

# Ubuntu (ufw)
sudo ufw status numbered
sudo ufw status verbose

운영 중 신규 포트 허용

# firewalld
sudo firewall-cmd --permanent --add-port=<포트>/tcp
sudo firewall-cmd --reload

# ufw
sudo ufw allow <포트>/tcp

신규 source IP 만 허용

# firewalld rich rule
sudo firewall-cmd --permanent --add-rich-rule="rule family=ipv4 source address=192.168.10.0/24 port port=9042 protocol=tcp accept"
sudo firewall-cmd --reload

# ufw
sudo ufw allow from 192.168.10.0/24 to any port 9042

5. JMX 포트 운영

JMX 포트(6199~7899) 는 관제 / 모니터링 노드 IP 만 허용해야 합니다. JConsole / VisualVM 로 접속 시:

# SSH 터널로 안전하게 접속 (권장)
ssh -L 7099:127.0.0.1:7099 root@[HOST]

# 로컬에서
jconsole 127.0.0.1:7099

상세 JMX 포트 매핑은 설치: 포트 구성 정보 - JMX 참고.

6. 자주 발생하는 문제

증상	원인	1차 조치
일부 컨테이너 비정상	의존 컨테이너 다운 / 자원 부족	호스트에서 `./status.sh` → 앱이면 `docker compose … restart <서비스>`, 인프라면 컨테이너 안에서 `restart-<module>.sh`
포트는 LISTEN 인데 health 실패	부팅 미완료 / 백엔드 의존성 미준비	`./stack-verify-boot.sh` 로 준비 여부 판정. 클린 설치는 안정까지 15~18분 걸립니다
전체 다운	스택이 내려감	호스트에서 `./up.sh` (준비될 때까지 대기, 0 = 쓸 수 있다)
`address already in use`	외부 프로세스 점유	위 포트 충돌 진단 절차
외부 접속 안 됨 (내부는 됨)	호스트 방화벽 또는 클라우드 SG	`firewall-cmd --list-ports` 및 클라우드 SG 점검
TLS 핸드셰이크 실패 (`TimeoutException` 으로만 보임)	인증서 SAN 불일치	`PP_TLS_SAN_DNS` / `PP_TLS_SAN_IPS` 점검. 인증서는 `plantpulse-certs` 원샷이 굽습니다 → 보안 설정
실시간 갱신 끊김	방화벽·프록시의 idle timeout	앞단 프록시의 `proxy_read_timeout` 상향. 실시간 푸시는 443 을 통해 나갑니다

7. 운영 자동화

헬스 체크 cron

# /etc/cron.d/plantpulse-health  (호스트에서)
*/5 * * * * root /opt/kopens/plantpulse-platform-docker/bin/ops-check.sh >> /var/log/plantpulse-ops.log 2>&1

종료 코드로 판정하려면 status.sh 가 더 낫습니다 — 0 = 정상 / 2 = 비정상 이 계약입니다.

*/5 * * * * root /opt/kopens/plantpulse-platform-docker/bin/status.sh >/dev/null 2>&1 || logger -t plantpulse "status.sh reported unhealthy"

Prometheus / Grafana 연동

plantpulse-monitor 가 노출하는 /metrics 엔드포인트를 Prometheus 가 스크레이프하도록 구성합니다.

# prometheus.yml
scrape_configs:
  - job_name: plantpulse
    scheme: https
    tls_config:
      insecure_skip_verify: true    # 자체 서명 CA 를 쓰는 경우
    static_configs:
      - targets: ['[HOST]:4950']

스크레이프는 4950 을 권장합니다

4949 로도 같은 API 가 나오지만 평문입니다. 사설망 안이고 인증서 검증이 부담이면 4949 를, 그 밖에는 4950 을 쓰세요.

Grafana 대시보드는 plantpulse-timeseries/dashboard/ (포트 3000) 의 사전 구성된 보드를 활용하거나, 외부 Grafana 에 같은 데이터 소스를 연결할 수 있습니다.

일상 점검 체크리스트​

1. 서비스 상태 점검​

status.sh — 스택 전체 상태 (호스트)​

모듈별 포트 점유 (데이터레이크 컨테이너 안)​

ops-check.sh — 헬스 + 최근 critical 로그​

외부 헬스 체크 (모니터링 시스템 연동)​

2. 포트별 빠른 진단​

3. 포트 충돌 진단​

점유 프로세스 확인​

충돌 해결​

4. 방화벽 운영​

현재 허용 규칙 조회​

운영 중 신규 포트 허용​

신규 source IP 만 허용​

5. JMX 포트 운영​

6. 자주 발생하는 문제​

7. 운영 자동화​

헬스 체크 cron​

Prometheus / Grafana 연동​

관련 문서​