포트/방화벽/프로토콜

FlowKat 시스템의 전체 포트 매핑, 방화벽 개방 규칙, 프로토콜을 정의한다.

---

1. 포트 매트릭스

포트	프로토콜	서비스	방향	방화벽 개방	설명
6100	TCP	collect-server	인바운드	필수	에이전트 → 수집 서버 데이터 전송 (V3 프로토콜). 모든 에이전트가 이 포트로 연결한다.
6300	TCP	ui-server	인바운드	필수	브라우저 → 웹 UI 접속. HTTP/WebSocket.
6180	TCP	collect-server	내부	불필요	Collect Server HTTP 관리 API (내부 전용).
6188	TCP	api-server	내부	불필요	API Server REST (컨테이너 간 통신).
6600	TCP	dashboard-server	내부	불필요	Dashboard Server (ui-server에서 프록시).
8090	TCP	tx-mining-api	선택	선택	TX-Mining REST API. 직접 접근 필요 시만 개방.
6380	TCP	valkey	내부	불필요 (권장)	Valkey(Redis-compatible) 캐시. 외부 접근 금지 권장.
5433	TCP	postgres	내부	불필요 (권장)	PostgreSQL TX-Mining DB. 외부 접근 금지 권장.

---

2. 필수 방화벽 규칙

최소 개방 (필수 2개)

# 에이전트 → 수집 서버 (모든 모니터링 대상 서버에서)
TCP 6100  인바운드  소스: 에이전트 서버 IP 대역

# 브라우저 → 웹 UI (사용자 네트워크에서)
TCP 6300  인바운드  소스: 사용자 접속 네트워크

선택 개방

# TX-Mining API 직접 접근 (필요 시)
TCP 8090  인바운드  소스: 접근 필요 IP

# Nginx 리버스 프록시 사용 시
TCP 443   인바운드  소스: 전체 (HTTPS)
# 이 경우 6300 직접 개방 불필요

---

3. 네트워크 모드별 차이

bridge 모드 (Development/Demo)

에이전트 → Docker 호스트 IP:6100 → collect-server 컨테이너
                                    └→ XLog Plugin: 172.17.0.1:5433 (Docker 게이트웨이)

• 네트워크 격리됨. 포트 매핑으로 외부 노출.
• XLog Plugin이 PostgreSQL에 접속할 때 Docker 게이트웨이 IP 사용.

host 모드 (Production/Aircap)

에이전트 → 호스트 IP:6100 → collect-server (호스트 네트워크 직접 사용)
                             └→ XLog Plugin: 127.0.0.1:5433

• Collect Server가 호스트 네트워크를 직접 사용. 라이선스 검증용 호스트 IP 필요.
• XLog Plugin은 localhost로 PostgreSQL 접속.

---

4. 에이전트-서버 통신 프로토콜

V3 TCP 프로토콜 (현재 사용)

단계	설명
1. 연결	에이전트가 net_collector_ip:net_collector_tcp_port로 TCP 연결 수립.
2. 핸드셰이크	V3 프로토콜 핸드셰이크 (타임아웃: net_nio_handshake_timeout_ms).
3. 데이터 전송	배치 전송 (net_tcp_batch_max_bytes 단위).
4. Keep-Alive	서버가 net_tcp_agent_keepalive_interval_ms 간격으로 KEEP_ALIVE 전송.
5. 재연결	연결 끊김 시 Exponential Backoff로 재연결 (initial_delay → max_delay → periodic_retry).

재연결 시퀀스

연결 끊김
  → 1초 대기 (initial_delay)
  → 2초, 4초, 8초... (exponential backoff)
  → 30초 상한 (max_delay)
  → 30회 재시도 후 (max_retry)
  → 5분마다 주기적 재시도 (periodic_retry)

UDP 미지원

V3부터 UDP는 지원하지 않는다. net_udp_listen_ip/net_udp_listen_port 파라미터는 코드에서 제거되었다. 에이전트-서버 통신은 TCP 전용이다.

---

5. 내부 서비스 통신

ui-server (:8080)
  → HTTP Proxy → dashboard-server (:6600)
  → REST API  → tx-mining-api (:8090)

dashboard-server (:6600)
  → REST API  → api-server (:6188)
  → REST API  → tx-mining-api (:8090)

api-server (:6188)
  → 내장 DB 조회 → collect-server

tx-mining-api (:8090)
  → JDBC     → postgres (:5432)
  → Cache    → valkey (:6379)

collect-server
  → XLog Plugin JDBC → postgres (:5432)

모든 내부 통신은 Docker 네트워크 내에서 서비스명으로 해결된다. 외부 노출이 필요한 포트는 6100과 6300만 해당한다.

---

6. 주의사항

상황	주의 내용
6188/6600 외부 노출	API Server와 Dashboard Server를 외부에 직접 노출하면 보안 위험. 반드시 UI Server(6300)를 통해 접근.
Valkey/PostgreSQL 외부 접근	6380, 5433 포트는 내부 전용 권장. 외부 접근 시 반드시 인증 및 방화벽 제한.
host 모드 방화벽	NETWORK_MODE_COLLECT=host 시 Collect Server가 호스트의 모든 인터페이스에 바인딩. net_tcp_listen_ip로 바인딩 IP 제한 가능.
포트 충돌	host 모드에서 6100 포트가 다른 서비스와 충돌하면 net_tcp_listen_port 변경. 모든 에이전트의 net_collector_tcp_port도 동일 변경 필수.

---

7. 관련 문서

• 수집 서버 파라미터: 14.collect-server.md
• Docker Compose: 16.docker-compose.md
• 아키텍처 초안: architecture-draft.md