포트 구성 정보

PlantPulse 는 Docker Compose 스택으로 동작하며, 컨테이너마다 자기 포트를 가집니다. 단일 서버 / 클러스터 모두 동일한 포트 설계를 따릅니다.

「방화벽이 열려 있다」와 「호스트에 실제로 열린다」는 다릅니다

호스트에 바인드되는 포트는 compose/docker-compose.yml 의 ports: 가 정합니다. install.sh 가 여는 방화벽 목록은 그보다 넓습니다. 방화벽에 있다고 해서 그 포트로 응답이 오는 것은 아닙니다.

이 페이지의 첫 표가 실제로 호스트에 열리는 포트 전부입니다. 그 밖의 포트는 컨테이너 안에서만 통합니다.

어느 컨테이너가 무엇을 여나

컨테이너	호스트에 여는 포트
`plantpulse-proxy`	80 · 443 · 1883 · 1884 — 사용자와 설비가 닿는 유일한 입구
`plantpulse-plugin-opcua`	11004 · 11005
`plantpulse-ha`	10210
`plantpulse-datalake`	인프라 계열 전부 (아래 표)
`plantpulse-batch-web`	9500 · 9501 (`PP_BATCH_HTTP_PORT` · `PP_BATCH_TLS_PORT`)
`plantpulse-warehouse-web`	9600 · 9601 (`PP_WAREHOUSE_HTTP_PORT` · `PP_WAREHOUSE_TLS_PORT`)
`plantpulse-server-web` · `plantpulse-plugin-aasx`	없습니다 — 프록시 뒤에서만 동작합니다
`plantpulse-certs`	없습니다 (포트를 열지 않습니다)

포트 토폴로지

외부 노출 권장 (사용자 / 외부 시스템)

포트	컨테이너	프로토콜	용도	권장
80	proxy	HTTP	운영 콘솔 / REST API	리버스 프록시 권장
443	proxy	HTTPS	운영 콘솔 / REST API (TLS)	✓
4950	datalake	HTTPS	모니터 UI + `/api/health`	모니터링 시스템
1883	proxy	TCP	MQTT 평문 — Edge 디바이스 / 센서 수집	사설망 권장
1884	proxy	TCP+TLS	MQTT over TLS (프록시는 passthrough, 브로커가 종단)	TLS 권장
11004 / 11005	opcua-server	OPC-UA	외부 설비가 붙는 엔드포인트	TLS 권장
10210	ha	HTTP	HA 데몬 `/api/health` · `/api/cluster` — 2-클러스터 구성에서 피어가 붙습니다	피어 IP only
9094	datalake	TCP+TLS	Kafka 외부 클라이언트	TLS 필수
5500 / 5501	datalake	HTTP / HTTPS	외부 시스템 데이터 조회	API Key

운영 권고: 80/443 만 외부에 노출하고 나머지는 사설망에만 두는 구성을 권장합니다.

9500 · 9501 · 9600 · 9601 은 호스트에 «열리지만» 외부에 내지 마세요

배치와 웨어하우스 컨테이너가 이 넷을 호스트에 바인드합니다(위 첫 표). 운영자가 그 컨테이너에 직접 물어볼 수 있게 하려는 것이지 외부에 내보이려는 것이 아닙니다. 상위 방화벽에서는 막아 두고, 확인은 호스트 안에서 하세요.

curl -fsS http://127.0.0.1:9500/api/health | jq   # 배치
curl -fsS http://127.0.0.1:9600/api/health | jq   # 웨어하우스

포트를 옮기려면 .env 의 PP_BATCH_HTTP_PORT · PP_BATCH_TLS_PORT · PP_WAREHOUSE_HTTP_PORT · PP_WAREHOUSE_TLS_PORT 를 바꿉니다.

웹 콘솔 실시간 푸시에 별도 포트가 필요하지 않습니다

실시간 푸시는 프록시(443)를 통해 나갑니다. 별도의 WebSocket 포트를 호스트에 열지 않습니다.

메시징

포트	컨테이너	프로토콜	용도
1883 / 1884	proxy	TCP / TLS	MQTT (HiveMQ). 프록시가 publish 합니다
18883 / 18884	datalake	TCP / TLS	예약. 현재 이 포트를 여는 리스너는 없습니다
9092	datalake	TCP	Kafka PLAINTEXT (사설망 only)
9093	datalake	TCP	Kafka KRaft 컨트롤러
9094	datalake	TCP+TLS	Kafka SASL_SSL

Kafka 는 프록시를 거치지 않습니다

Kafka 클라이언트는 부트스트랩 후 advertised.listeners 가 알려 준 주소로 다시 접속합니다. 앞에 프록시를 두면 그 주소까지 함께 바꿔야 하고, 틀리면 부트스트랩만 성공한 뒤 조용히 실패합니다. 그래서 Kafka 포트는 데이터레이크가 직접 publish 합니다.

STOMP(ActiveMQ)는 은퇴했습니다

브라우저 실시간 푸시가 SSE 로 바뀌면서 STOMP 브로커가 데이터레이크 이미지에서 제외되었습니다. 61000 / 61004 는 더 이상 서비스되지 않습니다. 옛 방화벽 규칙에 남아 있다면 정리해 주세요.

스토리지 (사설망 only)

포트	프로토콜	용도
9042	CQL	Aster TSDB
7000 / 7001	TCP	Aster TSDB Gossip / SSL
5432	TCP	PostgreSQL
6379	TCP	Valkey (Redis 호환)
6380	TCP+TLS	Valkey TLS 리스너
9000	HTTP	RustFS API
9001	HTTP	RustFS Console

분석 / SQL (사설망 only)

포트	프로토콜	용도
7077	TCP	Spark Master RPC
4440	HTTP	Spark Master UI — 8080 이 아닙니다
8081	HTTP	Spark Worker UI
10000	Thrift	Kyuubi SQL Gateway
10099	HTTP	Kyuubi REST API
19001	HTTP	Gravitino 통합 카탈로그
9083	Thrift	Hive Metastore
3500 / 3600	HTTP	Lab 분석 환경
4000 / 4001	HTTP / HTTPS	SQL 쿼리 서비스

처리 / 시계열 (사설망 only)

포트	프로토콜	용도
7400 / 7401	HTTP / HTTPS	CEP (Aster CEP)
7800 / 7801	HTTP / HTTPS	시계열 엔진(TSE)
3000	HTTP	PlantPulse Dashboard
5500 / 5501	HTTP / HTTPS	데이터 게이트웨이

워크플로우 (사설망 only)

포트	프로토콜	용도
7233	gRPC	Temporal Frontend
8233	HTTP	Temporal Web UI
8380	HTTP	Kestra (UI + API)
8381	HTTP	Kestra 관리(management) 포트

그 밖의 데이터레이크 포트

포트	용도
7003	진단 콘솔 (사설망 only)
60000 / 60001	OPC Agent 데이터 수집 (사설망 only)
6199 / 6299 / 6399 / 6499 / 7099	JMX agent — 관제 노드 IP 만 허용해 주세요

9500 · 9501 · 9600 · 9601 은 «앱 컨테이너가» 엽니다 — 데이터레이크가 아닙니다

네 포트는 앱 티어입니다 — 9500 · 9501 은 plantpulse-batch-web 의 Tomcat 커넥터 둘, 9600 · 9601 은 plantpulse-warehouse-web 의 것입니다. 둘 다 HTTP 와 HTTPS 커넥터이고, 9501 · 9601 은 리다이렉트용이 아니라 각자 SSLHostConfig 를 가진 온전한 커넥터입니다.

배치·웨어하우스가 데이터레이크와 한 컨테이너에 있던 시절의 정의가 데이터레이크 쪽에 남아 있었고, 그때는 호스트 포트를 붙잡은 채 뒤에 아무것도 없어 연결이 리셋됐습니다 (2026-09-02 발견). 그 정의는 정리됐습니다.

그리고 2026-09-07 에 앱 컨테이너가 스스로 열기 시작했습니다(사용자 결정). 즉 「앱 컨테이너는 아무것도 publish 하지 않는다」 는 이제 사실이 아닙니다. 데이터레이크 쪽 목록에서 이 포트들을 빼 두는 것이 그래서 더 중요합니다 — 둘이 같은 포트를 잡으면 나중에 뜨는 컨테이너가 «포트 이름만 적힌» 오류로 기동에 실패합니다.

컨테이너 내부 전용 (호스트 미공개)

아래는 컨테이너 안에서만 통하는 포트입니다. 호스트에서 curl 로 물어보면 응답이 없습니다.

포트	대상	대신 확인할 방법
8090 · 4800 / 4801	AAS(BaSyx) V3 API · V2 Registry/AAS	외부 접근이 필요하면 리버스 프록시를 별도로 검토
7199 · 7279	Aster TSDB · HiveMQ JMX	`bin/shell.sh` 로 데이터레이크 진입 후 확인
`plantpulse-server-web` 의 앱 포트	그 컨테이너 내부	`bin/status.sh` / `bin/logs.sh <컨테이너>`

4949 는 평문입니다

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

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

# 호스트 / 외부에서
curl -kfsS https://<서버IP>:4950/api/health | jq

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

설치 전 포트 충돌 확인

# 핵심 포트 점유 확인
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'

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

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

자주 충돌하는 포트: 80 (Apache/Nginx), 5432 (외부 PostgreSQL), 3000 (Grafana/Node.js), 9092 (외부 Kafka), 6379 (외부 Redis). 외부 서비스를 사용 중이라면 그 서비스의 포트를 옮기는 편이 간단합니다.

bin/preflight.sh 가 설치 전에 주요 포트(80 · 443 · 4949 · 4950)를 비파괴로 점검합니다.

위 ss 한 줄에는 9500 · 9501 · 9600 · 9601 이 빠져 있습니다. 배치·웨어하우스가 그 포트를 쓰므로, 그 넷도 함께 비어 있는지 보려면 정규식에 넣어 주세요.

방화벽 설정 예시

install.sh 가 호스트 방화벽(firewalld / ufw)을 자동으로 설정합니다. 아래는 상위 방화벽(회사 네트워크, 클라우드 보안 그룹, 라우터)에서 직접 허용해야 할 때의 예시입니다.

firewalld (RHEL/Rocky/Oracle)

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

# 외부 노출 (TLS 메시징 / 설비)
for port in 1884 9094 11004 11005; 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 1883 5432 6379 7077 7233 7800 8233 8380 9000 9001 9042 9092 10000 10210 19001; 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)

# 외부 노출
for port in 80 443 4950 1884 9094 11004 11005; do
  ufw allow ${port}/tcp
done

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

ufw enable

자동 설정 확인

# RHEL/Rocky/Oracle
sudo firewall-cmd --list-ports
sudo firewall-cmd --list-rich-rules

# Ubuntu
sudo ufw status numbered

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

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

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

어느 컨테이너가 무엇을 여나​

포트 토폴로지​

외부 노출 권장 (사용자 / 외부 시스템)​

메시징​

스토리지 (사설망 only)​

분석 / SQL (사설망 only)​

처리 / 시계열 (사설망 only)​

워크플로우 (사설망 only)​

그 밖의 데이터레이크 포트​

컨테이너 내부 전용 (호스트 미공개)​

설치 전 포트 충돌 확인​

방화벽 설정 예시​

firewalld (RHEL/Rocky/Oracle)​

ufw (Ubuntu)​

자동 설정 확인​

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

관련 문서​