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

# 포트 구성 정보

PlantPulse 의 모든 모듈은 고유 포트를 사용해 독립적으로 통신합니다. 단일 서버 / 클러스터 모두 동일한 포트 설계를 따릅니다.

## 포트 토폴로지

```mermaid
graph TB
  subgraph EXT["외부 (사용자 / 디바이스)"]
    USER[운영자]
    EDGE[IoT 디바이스]
    EXT_API[외부 시스템]
  end

  subgraph DMZ["외부 노출 (리버스 프록시 권장)"]
    P80[":80 :443<br/>웹 콘솔"]
    P7443[":7443<br/>관리 콘솔"]
    P4949[":4949<br/>헬스체크"]
    P1884[":1884 / :18884<br/>MQTT TLS"]
    P9094[":9094<br/>Kafka TLS"]
    P5500[":5500<br/>Data Gateway"]
  end

  subgraph PRIV["사설망 (서비스 간 통신)"]
    P9092[":9092 Kafka"]
    P1883[":1883 MQTT"]
    P61000[":61000 STOMP"]
    P9042[":9042 Cassandra"]
    P5432[":5432 PostgreSQL"]
    P6379[":6379 Valkey"]
    P9000[":9000 MinIO"]
    P7077[":7077 Spark"]
    P10000[":10000 Kyuubi"]
    P7800[":7800 TSE"]
    P7233[":7233 Temporal"]
    P8380[":8380 Kestra"]
  end

  USER --> P80
  USER --> P7443
  EDGE --> P1884
  EXT_API --> P5500
  EXT_API --> P9094
```

## 외부 노출 포트 (방화벽 허용)

| 포트                | 모듈           | 프로토콜         | 용도                     | 권장            |
| ----------------- | ------------ | ------------ | ---------------------- | ------------- |
| **80**            | server       | HTTP         | 운영 콘솔 / REST API       | 리버스 프록시 권장    |
| **443**           | server       | HTTPS        | 운영 콘솔 / REST API (TLS) | ✓             |
| **7443**          | server       | HTTPS        | 관리 콘솔 (별도)             | ✓             |
| **4949**          | monitor      | HTTP         | 헬스체크 / Prometheus      | 모니터링 시스템 only |
| **4950**          | monitor      | HTTPS        | 헬스체크 (TLS)             | ✓             |
| **1884 / 18884**  | messaging    | TCP+TLS      | MQTT 외부 디바이스           | TLS 권장        |
| **9094**          | messaging    | TCP+TLS      | Kafka 외부 클라이언트         | TLS 필수        |
| **5500 / 5501**   | data-gateway | HTTP / HTTPS | 외부 시스템 데이터 조회          | API Key       |
| **3000**          | timeseries   | HTTP         | Grafana 대시보드 (선택)      | 인증 활성화        |
| **8233**          | workflow     | HTTP         | Temporal Web UI (선택)   | 인증 활성화        |
| **8380**          | workflow     | HTTP         | Kestra Web UI (선택)     | 인증 활성화        |
| **19001**         | analytics    | HTTP         | Gravitino 카탈로그 (선택)    | 인증 활성화        |
| **11004 / 11005** | plugin       | OPC-UA       | OPC-UA 외부 클라이언트        | TLS 권장        |
| **8007 / 8090**   | plugin       | HTTP         | AAS V2 / V3 (선택)       | 인증 활성화        |

## 메시징

| 포트                | 모듈        | 프로토콜      | 용도                         |
| ----------------- | --------- | --------- | -------------------------- |
| **9092**          | messaging | TCP       | Kafka PLAINTEXT (사설망 only) |
| **9093**          | messaging | TCP       | Kafka KRaft 컨트롤러           |
| **9094**          | messaging | TCP+TLS   | Kafka SASL\_SSL            |
| **1883**          | messaging | TCP       | MQTT (HiveMQ) PLAINTEXT    |
| **1884**          | messaging | TCP+TLS   | MQTT TLS                   |
| **18883 / 18884** | messaging | TCP / TLS | MQTT 외부 노출                 |
| **61000**         | messaging | TCP       | STOMP (ActiveMQ)           |
| **61004**         | messaging | TCP+TLS   | STOMP TLS                  |
| **8161**          | messaging | HTTP      | ActiveMQ 관리 콘솔             |

## 스토리지 (사설망 only)

| 포트              | 모듈      | 프로토콜 | 용도                     |
| --------------- | ------- | ---- | ---------------------- |
| **9042**        | storage | CQL  | Cassandra              |
| **7000 / 7001** | storage | TCP  | Cassandra Gossip / SSL |
| **7199**        | storage | JMX  | Cassandra JMX          |
| **5432**        | storage | TCP  | PostgreSQL             |
| **6379**        | storage | TCP  | Valkey (Redis 호환)      |
| **9000**        | storage | HTTP | MinIO API              |
| **9001**        | storage | HTTP | MinIO Console          |

## 분석 / SQL

| 포트              | 모듈        | 프로토콜   | 용도                       |
| --------------- | --------- | ------ | ------------------------ |
| **7077**        | analytics | TCP    | Spark Master             |
| **4440 / 4441** | analytics | HTTP   | Spark Master / Worker UI |
| **8081**        | analytics | HTTP   | Spark Worker UI          |
| **10000**       | analytics | Thrift | Kyuubi SQL Gateway       |
| **10099**       | analytics | HTTP   | Kyuubi Web UI            |
| **19001**       | analytics | HTTP   | Gravitino 통합 카탈로그        |
| **9083**        | analytics | Thrift | Hive Metastore           |
| **4000**        | sql       | HTTP   | SQL 쿼리 서비스               |

## 처리 / 시계열

| 포트       | 모듈           | 프로토콜  | 용도            |
| -------- | ------------ | ----- | ------------- |
| **7400** | cep          | HTTP  | CEP (Esper)   |
| **7401** | cep          | HTTPS | CEP TLS       |
| **7800** | timeseries   | HTTP  | 시계열 엔진        |
| **7801** | timeseries   | HTTPS | 시계열 엔진 TLS    |
| **3000** | timeseries   | HTTP  | Grafana UI    |
| **5500** | data-gateway | HTTP  | 데이터 게이트웨이     |
| **5501** | data-gateway | HTTPS | 데이터 게이트웨이 TLS |

## 워크플로우

| 포트       | 모듈       | 프로토콜 | 용도                |
| -------- | -------- | ---- | ----------------- |
| **7233** | workflow | gRPC | Temporal Frontend |
| **7234** | workflow | gRPC | Temporal History  |
| **7235** | workflow | gRPC | Temporal Matching |
| **8233** | workflow | HTTP | Temporal Web UI   |
| **8380** | workflow | HTTP | Kestra (UI + API) |
| **7936** | workflow | HTTP | Temporal pprof    |

## 산업 플러그인

| 포트        | 모듈     | 프로토콜         | 용도                      |
| --------- | ------ | ------------ | ----------------------- |
| **11004** | plugin | OPC-UA       | OPC-UA Server PLAINTEXT |
| **11005** | plugin | OPC-UA + TLS | OPC-UA Server TLS       |
| **8007**  | plugin | HTTP         | AAS V2 BaSyx            |
| **8090**  | plugin | HTTP         | AAS V3 BaSyx            |

## 애플리케이션

| 포트              | 모듈        | 프로토콜         | 용도                         |
| --------------- | --------- | ------------ | -------------------------- |
| **80 / 443**    | server    | HTTP / HTTPS | 웹 콘솔                       |
| **7443**        | server    | HTTPS        | 관리 콘솔                      |
| **7000**        | server    | TCP          | Tomcat shutdown (사설망 only) |
| **8000 / 8004** | server    | WebSocket    | 실시간 푸시 (PLAINTEXT / TLS)   |
| **9500 / 9501** | batch     | HTTP / HTTPS | 배치 처리                      |
| **9600**        | warehouse | HTTP         | 데이터 웨어하우스                  |
| **4000 / 4001** | sql       | HTTP / HTTPS | SQL 쿼리                     |
| **4949 / 4950** | monitor   | HTTP / HTTPS | 모니터링                       |
| **7003**        | server    | HTTP         | 진단 콘솔 (사설망 only)           |

## JMX / 관리 포트 (관제 노드 only)

플랫폼 내부 JMX 메트릭 포트입니다. **관제 시스템 IP 만** 허용해 주세요.

| 포트                               | 대상             |
| -------------------------------- | -------------- |
| 6199 / 6299 / 6399 / 6499        | 애플리케이션 모듈 JMX  |
| 6599 / 6933 \~ 6939              | 인프라 모듈 JMX     |
| 7099 / 7199 / 7279 / 7289 / 7299 | 스토리지 / 메시징 JMX |
| 7399 / 7499 / 7599 / 7899        | 분석 / 워크플로우 JMX |

## 설치 전 포트 충돌 확인

```bash
# 핵심 포트 점유 확인
ss -tlnp | grep -E ':(80|443|1883|3000|4000|4949|5432|5500|6379|7077|7233|7400|7800|8233|8380|9000|9042|9092|9500|9600|10000|11004|19001|61000)\s'
```

출력이 없으면 충돌 없음. 출력이 있다면:

```bash
# 점유 프로세스 확인
sudo lsof -i :<포트>
sudo ss -tlnp | grep ":<포트>"
```

> **자주 충돌하는 포트**: 80 (Apache/Nginx), 5432 (외부 PostgreSQL), 3000 (Grafana/Node.js), 9092 (외부 Kafka), 6379 (외부 Redis). 외부 서비스를 사용 중이라면 PlantPulse 의 포트를 `env.sh` 에서 변경하거나 외부 서비스 포트를 옮겨주세요.

## 방화벽 설정 예시

### firewalld (RHEL/Rocky/Oracle)

```bash
# 외부 노출 (모든 IP)
for port in 80 443 7443 4949; do
  firewall-cmd --permanent --add-port=${port}/tcp
done

# 외부 노출 (TLS 메시징)
for port in 1884 18884 9094; do
  firewall-cmd --permanent --add-port=${port}/tcp
done

# 사설망 only (RFC 1918 + Tailscale CGN 허용)
for src in 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 100.64.0.0/10; do
  for port in 9092 1883 61000 5432 9042 6379 9000 9001 7077 10000 19001 7800 8233 8380; do
    firewall-cmd --permanent --add-rich-rule="rule family=ipv4 source address=${src} port port=${port} protocol=tcp accept"
  done
done

firewall-cmd --reload
```

### ufw (Ubuntu)

```bash
# 외부 노출
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 7443/tcp
ufw allow 4949/tcp
ufw allow 1884/tcp
ufw allow 9094/tcp

# 사설망 only
for port in 9092 1883 61000 5432 9042 6379 9000 7077 10000 19001 7800 8233 8380; do
  ufw allow from 10.0.0.0/8 to any port $port
  ufw allow from 172.16.0.0/12 to any port $port
  ufw allow from 192.168.0.0/16 to any port $port
  ufw allow from 100.64.0.0/10 to any port $port
done

ufw enable
```

## 클라우드 보안 그룹 (예: AWS / GCP / Azure)

호스트 방화벽 외에 클라우드 보안 그룹도 동일하게 설정해야 합니다.

| 인바운드 규칙   | 소스                   | 포트                                             |
| --------- | -------------------- | ---------------------------------------------- |
| 운영 콘솔     | 0.0.0.0/0 (또는 회사 IP) | 80, 443, 7443                                  |
| 헬스체크      | 모니터링 노드              | 4949, 4950                                     |
| MQTT TLS  | 디바이스 / 외부            | 1884, 18884                                    |
| Kafka TLS | 외부 클라이언트             | 9094                                           |
| 사설망       | VPC CIDR             | 1883, 5432, 6379, 7077, 9042, 9092, 10000, ... |

## 관련 문서

* [시스템 요구사항](/plantpulse-platform/installation/requirements.md) — 하드웨어 / OS / 튜닝
* [원라인 설치 (권장)](/plantpulse-platform/installation/one-line-install.md) — 자동 방화벽 설정
* [Docker 설치](/plantpulse-platform/installation/docker.md) — 컨테이너 환경 포트 매핑
* [모듈 인덱스](/plantpulse-platform/admin/modules.md) — 모듈별 포트 상세
* [관리자: 포트 및 서비스 관리](/plantpulse-platform/admin/ports.md) — 운영 점검 절차