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

# 포트 및 서비스 관리

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

## 일상 점검 체크리스트

```mermaid
flowchart LR
  A[status.sh<br/>RUNNING 확인] --> B{모두 RUNNING?}
  B -->|네| C[ops-check.sh<br/>health · critical log]
  B -->|아니오| D[해당 모듈 restart-*.sh]
  C --> E{health · log 정상?}
  E -->|네| F[일상 점검 완료]
  E -->|아니오| G[log-viewer.sh<br/>원인 분석]
  D --> A
  G --> H[doctor.sh<br/>진단 tarball]
```

## 1. 서비스 상태 점검

### `status.sh` — 포트 기반 전체 상태

`plantpulse-startup/status.sh` 가 모든 모듈의 포트 점유 / PID / CPU / 메모리(PSS) 를 한 번에 보여줍니다.

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-startup
./status.sh
```

출력 예시:

```
==============================================================================================================
 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 로그

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

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

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

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

```bash
# 단순 ping
curl -fsS http://127.0.0.1:4949/health

# TLS health (외부 노출 권장)
curl -kfsS https://[HOST]:4950/api/health | jq

# Prometheus 메트릭 (스크레이프 엔드포인트)
curl -fsS http://127.0.0.1:4949/metrics
```

## 2. 포트별 빠른 진단

| 포트              | 모듈           | 빠른 점검                                                                                        |
| --------------- | ------------ | -------------------------------------------------------------------------------------------- |
| 80 / 443 / 7443 | server       | `curl -fsS http://[HOST]/api/v5/ping`                                                        |
| 9042            | Cassandra    | `node-status.sh` 클러스터 상태                                                                     |
| 5432            | PostgreSQL   | `node-psql.sh` 접속 후 `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`                     |
| 61000           | STOMP        | `nc -zv [HOST] 61000`                                                                        |
| 7400            | CEP          | `curl -fsS -H "X-API-Key: $PP_CEP_API_KEY" http://[HOST]:7400/api/v1/status`                 |
| 5500            | Data Gateway | `curl -fsS -H "X-API-Key: $PP_DATA_GATEWAY_API_KEY" http://[HOST]:5500/api/health`           |
| 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` 접속                                                     |

## 3. 포트 충돌 진단

### 점유 프로세스 확인

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

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

### 충돌 해결

| 상황                    | 조치                                                           |
| --------------------- | ------------------------------------------------------------ |
| 외부 서비스가 포트 점유         | 외부 서비스를 다른 포트로 이동                                            |
| 이전 PlantPulse 프로세스 잔존 | `pkill -ef plantpulse` 또는 `./kill.sh`                        |
| 기본 포트가 회사 정책상 사용 불가   | `env.sh` 의 해당 `PP_*_PORT` 변경 → `configure.sh` → `restart.sh` |

## 4. 방화벽 운영

### 현재 허용 규칙 조회

```bash
# 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
```

### 운영 중 신규 포트 허용

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

# ufw
sudo ufw allow <포트>/tcp
```

### 신규 source IP 만 허용

```bash
# 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 로 접속 시:

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

# 로컬에서
jconsole 127.0.0.1:7099
```

상세 JMX 포트 매핑은 [설치: 포트 구성 정보 - JMX](/plantpulse-platform/installation/ports.md#jmx) 참고.

## 6. 자주 발생하는 문제

| 증상                       | 원인                           | 1차 조치                                                                |
| ------------------------ | ---------------------------- | -------------------------------------------------------------------- |
| 일부 모듈 STOPPED            | 의존 모듈 다운 / 자원 부족             | `./status.sh` → `./restart-<module>.sh`                              |
| 포트는 LISTEN 인데 health 실패  | 부팅 미완료 / 백엔드 의존성 미준비         | 3\~5분 대기 후 `./ops-check.sh` 재실행                                      |
| 모든 모듈 STOPPED            | 전체 다운                        | `./start-daemon.sh` 또는 `./restart.sh`                                |
| `address already in use` | 외부 프로세스 점유                   | 위 [포트 충돌 진단](#3-포트-충돌-진단) 절차                                         |
| 외부 접속 안 됨 (내부는 됨)        | 호스트 방화벽 또는 클라우드 SG           | `firewall-cmd --list-ports` 및 클라우드 SG 점검                             |
| TLS 핸드셰이크 실패             | 인증서 SAN 불일치                  | `prepare-ssl.sh` 재실행 + `PP_TLS_SAN_*` 점검                             |
| WebSocket 끊김             | 방화벽 idle timeout / Tomcat 한계 | proxy `proxy_read_timeout` 상향, `tomcat.websocket.session.timeout` 점검 |

## 7. 운영 자동화

### 헬스 체크 cron

```bash
# /etc/cron.d/plantpulse-health
*/5 * * * * root /opt/kopens/plantpulse-platform/plantpulse-startup/ops-check.sh >> /var/log/plantpulse-ops.log 2>&1
```

### Prometheus / Grafana 연동

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

```yaml
# prometheus.yml
scrape_configs:
  - job_name: plantpulse
    static_configs:
      - targets: ['[HOST]:4949']
```

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

## 관련 문서

* [설치: 포트 구성 정보](/plantpulse-platform/installation/ports.md) — 전체 포트 카탈로그
* [모니터링](/plantpulse-platform/admin/monitoring.md) — Prometheus / Grafana / 알림
* [문제 해결](/plantpulse-platform/admin/troubleshooting.md)
* [모듈: monitor](/plantpulse-platform/admin/modules/monitor.md)
* [모듈: startup](/plantpulse-platform/admin/modules/startup.md)