본문으로 건너뛰기

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

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

일상 점검 체크리스트​

1. 서비스 상태 점검​

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

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

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh
아홉 개를 같은 기준으로 봅니다

plantpulse-certs 도 상시 동작하며 (healthy) 가 정상입니다. 인증서를 한 번 굽고 나면 만료를 계속 감시합니다.

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

인프라 컴포넌트의 포트 점유 / 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 / 443servercurl -fsS http://[HOST]/api/v5/ping
9042Aster TSDBpd node status 클러스터 상태
5432PostgreSQLpd node psql 접속 후 SELECT 1;
6379Valkeyredis-cli -a $PP_REDIS_PASSWORD ping
9000RustFSpd status storage — RustFS 에는 헬스 엔드포인트가 없습니다
9092Kafkakafka-broker-api-versions.sh --bootstrap-server [HOST]:9092
1883MQTTmosquitto_pub -h [HOST] -p 1883 -u mq -P $PP_MQ_PASSWORD -t test -m hi
7400CEPcurl -fsS -H "X-API-Key: $PP_CEP_API_KEY" http://[HOST]:7400/api/v1/status
5500Data Gatewaycurl -fsS http://[HOST]:5500/api/health (익명 readiness — UP 일 때만 200)
7800TSEcurl -fsS http://[HOST]:7800/api/health
7077Spark Mastercurl -fsS http://[HOST]:4440/json/ | jq .workers
10000Kyuubibeeline -u "jdbc:hive2://[HOST]:10000" -e "SELECT 1"
19001Gravitinocurl -fsS -u gravitino:$PP_GRAVITINO_PASSWORD http://[HOST]:19001/api/metalakes
7233Temporaltemporal --address [HOST]:7233 namespace list
8380Kestracurl -fsS -u admin@plantpulse.io:$PP_KESTRA_ADMIN_PASSWORD http://[HOST]:8380/api/v1/flows
11004OPC-UAUaExpert 등으로 opc.tcp://[HOST]:11004 접속
10210HA 데몬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|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외부 프로세스 점유위 포트 충돌 진단 절차
외부 접속 안 됨 (내부는 됨)호스트 방화벽 또는 클라우드 SGfirewall-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 연동​

관리 콘솔 API(plantpulse-datalake-admin-api)가 노출하는 /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 을 쓰세요.

여기는 «스택이 살아 있나» 입니다 — 설비 데이터가 아닙니다

4950/metrics 가 내주는 것은 컨테이너·포트·헬스 같은 스택 자신의 상태입니다. 설비에서 올라온 값이나 시스템 지표를 PromQL 로 보려는 것이라면 자리가 다릅니다.

보려는 것어디로
스택이 살아 있나 (컨테이너·포트)여기 — 4950/metrics
시스템 지표를 PromQL 로 (JMX·엣지 카운터)Prometheus 연동 — TSE 의 호환 어댑터
시스템 지표를 대시보드로PlantPulse Dashboard 로 대시보드 만들기 — 번들 PlantPulse Dashboard(3000)
설비 센서 값시계열 데이터베이스 — CQL

관련 문서​