본문으로 건너뛰기

서비스 포트 맵

외부로 열리는 것은 하나뿐입니다​

AI 스택에서 호스트의 80 / 443 을 잡는 것은 plantpulse-proxy(nginx) 하나입니다. 채팅 화면도, 관리 콘솔도, 각 API 도 전부 이 프록시를 거쳐 들어갑니다. 관리 콘솔의 HTTPS 포트(기본 5960)도 이 프록시가 받습니다 — 아래 를 보십시오.

앱 컨테이너는 80 을 발행하지 않습니다

AI Chat Web 은 컨테이너 안에서만(expose: 8080) 열립니다. 밖으로 내는 자리는 프록시 하나뿐입니다 — 노출 지점을 한 군데로 모아 방화벽 · 감사 · TLS 를 거기서 처리합니다.

호스트 이름으로 갈라집니다​

프록시는 Host 헤더를 보고 뒷단을 고릅니다. 그래서 DNS 에 아래 이름들을 프록시 IP 로 걸어 두어야 각 서비스에 닿습니다.

뒷단은 컨테이너 이름 그대로입니다 — 아래 값이 nginx 의 set $upstream 에 들어가는 문자열이고, 컨테이너 안에서 curl 할 때도 이 이름을 씁니다.

호스트뒷단 (컨테이너 이름:포트)무엇
그 외 전부 (기본)plantpulse-copilot-web:8080AI Chat Web — 채팅 화면
admin.*plantpulse-admin-web:8080관리 콘솔
llm.*plantpulse-litellm:4000LLM 게이트웨이 (OpenAI 호환)
rag.*plantpulse-rag-api:7115RAG 검색 API
timeseries.*plantpulse-timeseries-insight-api:8970시계열 인사이트 API
parser.*plantpulse-document-understanding-api:7120문서 파싱 API
vision.*plantpulse-vision-api:7130비전 API

기본 호스트의 경로 — 도메인 하나로 쓸 때​

서브도메인을 더 만들지 않아도 되도록, 기본 호스트(채팅 화면 쪽) 에 아래 경로가 함께 열려 있습니다. 도메인 하나와 인증서 하나로 게이트웨이와 MCP 서버에 닿습니다.

경로뒷단무엇
/mcp/gateway/plantpulse-mcp-gateway-api:7160/mcp/MCP 게이트웨이 — 외부 MCP 클라이언트가 붙는 주소(게이트웨이 키 ppgw_…). 관리 REST /api/v1 는 열지 않습니다
/llm/plantpulse-litellm:4000/LLM 게이트웨이 (OpenAI 호환) — base_url = "https://<호스트>/llm/v1"
/mcp/rag/plantpulse-rag-api:7115/mcp/RAG MCP 서버
/mcp/timeseries/plantpulse-timeseries-insight-api:8970/mcp/시계열 인사이트 MCP 서버
/mcp/parser/plantpulse-document-understanding-api:7120/mcp/문서 파싱 MCP 서버
/mcp/vision/plantpulse-vision-api:7130/mcp/비전 MCP 서버
  • 끝 슬래시까지 적으십시오. 슬래시 없이 오면 308 로 붙여 줍니다(본문이 보존됩니다).
  • MCP 전송은 Streamable HTTP 뿐입니다. /sse 는 없습니다.
  • 인증은 프록시가 아니라 뒷단이 합니다. MCP 넷은 X-API-Key: <PI_INBOUND_API_KEY>(또는 Bearer) 없이는 401 입니다. /llm/ 은 게이트웨이의 마스터 키나 가상 키를 씁니다.
  • 각 뒷단의 지표 /metrics 는 새 포트가 아니라 같은 포트의 경로이고, 역시 인바운드 키 뒤에 있습니다 (2026.10 재릴리즈) → 로그 및 모니터링
LiteLLM 관리 화면은 /llm/ui 로 열리지 않습니다

경로 접두사를 떼고 넘기기 때문에 관리 화면의 자산 링크가 어긋납니다. 관리 화면은 llm.* 호스트나 직접 열린 :4000/ui 로 여십시오.

기본 호스트는 이미 밖에서 닿는 호스트입니다

이 경로들은 인터넷에 공개된 이름으로 곧바로 닿습니다. PI_INBOUND_API_KEY 가 비면 기동 전 판정이 스택을 세우지만, CHANGE_ME_… 자리표시자는 그 검사를 통과합니다. 설치 직후 bin/doctor.sh 로 남은 자리표시자가 없는지 반드시 확인하십시오.

copliot 은 저장소 이름이고 컨테이너는 copilot 입니다

저장소는 plantpulse-ai-copliot-web(오타가 그대로 굳었습니다)이지만 컨테이너 이름은 plantpulse-copilot-web 입니다. 저장소 철자로 docker logs 를 치면 찾지 못합니다.

TLS 를 누가 끊는지 확인하세요

프록시는 443 도 듣지만, 앞단에 별도 로드밸런서·리버스 프록시를 두는 배포에서는 거기서 TLS 가 끊기고 프록시에는 평문으로 들어옵니다. 앞단 종료를 무시하도록 설정하면 무한 리다이렉트가 납니다. 어느 형태인지 먼저 확인하십시오.

관리 콘솔은 포트로도 열립니다​

IP 로 붙는 사내 사용자는 호스트 이름이 없어서 443 에서 관리 콘솔을 고를 수 없습니다. 그래서 2026.10 부터 관리 콘솔에는 포트로 가르는 입구가 둘 있습니다.

주소받는 쪽키 (기본값)
http://<AI_SERVER_IP>:5959plantpulse-admin-web:8080 직결 (평문)PI_ADMIN_WEB_PORT (5959)
https://<AI_SERVER_IP>:5960프록시가 TLS 를 끊고 plantpulse-admin-web:8080 으로PI_ADMIN_WEB_TLS_PORT (5960)
  • 둘 다 열립니다. 평문 입구를 HTTPS 로 되돌리지 않습니다.
  • HTTPS 인증서는 443 과 같은 한 벌(프록시의 인증서)입니다. 콘솔이 인증서를 따로 들지 않습니다.
  • 포트를 바꾸려면 호스트 env(/etc/kopens/plantpulse-ai.env)의 위 두 키를 고치고 다시 올립니다.
2026.09 이하의 9080 은 없어졌습니다

예전 판은 관리 콘솔을 :9080 에 냈습니다. 2026.10 에서 5959(HTTP) · 5960(HTTPS) 로 바뀌었고, 콘솔 컨테이너도 비root nginx 라 안쪽 포트가 80 에서 8080 으로 바뀌었습니다. 북마크와 방화벽 규칙을 함께 고치십시오.

프록시도 비root 입니다 — 바깥 포트는 그대로, 안쪽 포트만 바뀌었습니다​

2026.10 의 plantpulse-proxy 는 root 가 아니라 uid 10001, gid 0 으로 돌고, 컨테이너 안쪽에서는 1024 아래 포트를 열지 않습니다. 호스트(바깥)에서 보이는 포트는 바뀌지 않았습니다.

호스트(바깥)프록시 안쪽무엇
808080HTTP (평문)
4439443HTTPS — 채팅 화면 · admin.* 등 이름 라우팅
PI_ADMIN_WEB_TLS_PORT (5960)8443관리 콘솔 HTTPS

방화벽 · 앞단 로드밸런서 · DNS 는 예전처럼 80 · 443 · 5960 을 보면 됩니다. 안쪽 포트는 compose 와 프록시 이미지가 같은 릴리즈로 함께 바뀌므로, 프록시 이미지만 옛 판으로 되돌리면 연결이 거부됩니다 — 되돌릴 때는 스택 전체를 같은 판으로 맞추십시오.

인증서 볼륨(pp-proxy-certs)은 root 시절에 만들어졌다면 키가 root 전용이라 비root 프록시가 읽지 못합니다. bin/up.sh · restart.sh · update.sh 가 기동 전에 소유권을 한 번 맞춥니다 → 서비스 운영

LAN 에 직접 열리는 포트​

프록시를 거치지 않고 호스트에 그대로 발행되는 포트입니다. 127.0.0.1 바인딩이 아니라 모든 인터페이스에 열립니다 — 사내망 밖에서 닿지 않도록 방화벽으로 막으십시오.

포트서비스왜 열려 있나
80 / 443plantpulse-proxy유일한 사용자 접점
4000LiteLLMLLM 게이트웨이 직결 (llm.* 로도 접근 가능)
7115RAG APIMCP 클라이언트(Claude Desktop 등) 직결용
8970시계열 인사이트 APIMCP 클라이언트 직결용
5959관리 콘솔 (plantpulse-admin-web) — HTTP운영자용. admin.* 로도 접근 가능
5960관리 콘솔 — HTTPS (plantpulse-proxy 가 받음)운영자용. 인증서는 443 과 같은 것
7474Neo4j Browser그래프 DB 관리 UI (plantpulse-neo4j — RAG 지식 그래프)
7687Neo4j Bolt그래프 DB 쿼리 프로토콜 (같은 인스턴스)
Neo4j 가 둘입니다 — 디지털 스레드 쪽은 열리지 않습니다

2026.10 부터 디지털 스레드 전용 Neo4j(plantpulse-digital-thread-neo4j)가 하나 더 뜹니다. 이쪽은 포트를 발행하지 않습니다 — plantpulse-digital-thread-api 만 compose 네트워크 안에서 붙습니다. 위 7474 · 7687 은 예전부터 있던 plantpulse-neo4j(LightRAG 의 지식 그래프)입니다 → 디지털 스레드

4000 에는 사람이 로그인하는 관리 화면이 있습니다

:4000/ui 는 LiteLLM 관리 화면이고, PI_LITELLM_UI_USERNAME · PI_LITELLM_UI_PASSWORD(기본 admin / admin123!)로 들어갑니다. LAN 에 열려 있으므로 커미셔닝 때 비밀번호를 바꾸십시오 → 초기 비밀번호 변경

프로필을 켜야 뜨는 것​

기본 기동에는 포함되지 않고, 해당 compose 프로필로 올릴 때만 뜹니다.

포트서비스프로필
5000로컬 이미지 레지스트리registry
LOCAL_REGISTRY_UI_PORT(기본 5080)레지스트리 관리 UIregistry
(발행 안 함 — 안쪽 8000)녹취 vLLM plantpulse-asrmedia
(네트워크 없음)녹취 오디오 라이브러리 plantpulse-asr-audio — 일회성media

registry 는 폐쇄망에서 이미지를 내부에서 받게 할 때 씁니다 → 폐쇄망 설치. media 는 영상 · 음성 녹취용입니다. 프로필 이름을 손으로 주지 않고 호스트 env 의 PI_MEDIA_ENABLED=true 한 줄로 켭니다 — 운영 스크립트가 그 값을 보고 프로필을 붙입니다 → 영상 · 음성 수집

Phoenix 는 뜨지만 호스트에 열지 않습니다

Arize Phoenix(트레이스 UI · OTLP 수집, 6006)는 기본으로 뜹니다 — 프로필을 켤 필요가 없습니다. 다만 2026.09 부터 호스트 포트를 발행하지 않습니다. Phoenix 에는 인증이 없고, 담는 것은 질문과 답의 본문(도구 인자의 설비 id · 태그 포함)이기 때문입니다. 관리 콘솔의 상태 검사는 컨테이너 내부 주소로 가므로 영향이 없습니다. 진단에 필요하면 아래 「진단용 포트」로 잠시 엽니다.

2026-07 개편 때 빠진 Langflow(7860) · Jupyter(3500) 는 정말 제거되어 되살릴 수 없습니다.

진단용 포트 — PP_DEBUG_PORTS=1​

평소에는 닫혀 있는 포트를 진단할 때만 예전 그대로 엽니다(compose/docker-compose.debug.yml 오버레이).

cd /opt/kopens/plantpulse-ai-docker
PP_DEBUG_PORTS=1 bin/compose-up.sh
포트서비스
9081관리 콘솔 백엔드(admin-api)
8000 · 8003 · 8004vLLM 생성 · 임베딩 · 재순위
8005녹취 vLLM(media 프로필을 켰을 때만)
5001docling
8980시계열 추론 서버
9400DCGM Exporter
6333Qdrant
6006Phoenix
이 포트들에는 인증이 없습니다

진단이 끝나면 PP_DEBUG_PORTS 없이 다시 올려 닫으십시오.

내부 전용 (발행하지 않음)​

compose 네트워크 안에서 서비스 이름으로만 닿습니다. 호스트에서 nc -z 로 찔러도 응답이 없는 것이 정상입니다.

서비스내부 주소 (컨테이너 이름:포트)역할
AI Chat Webplantpulse-copilot-web:8080채팅 화면 (프록시 기본 뒷단)
관리 콘솔 백엔드plantpulse-admin-api인증 정본. plantpulse-admin-web 의 nginx 가 넘긴다
문서 파싱 APIplantpulse-document-understanding-api:7120parser.* 뒷단
비전 APIplantpulse-vision-api:7130vision.* 뒷단
LightRAGplantpulse-lightrag:9621RAG 엔진. 문서 관리 WebUI(/webui)
Qdrantplantpulse-qdrant:6333벡터 DB
Doclingplantpulse-docling-serve:5001문서 변환
vLLM (생성)plantpulse-llm:8000로컬 LLM 추론
vLLM (임베딩)plantpulse-emb:8000임베딩
vLLM (리랭크)plantpulse-rerank:8000리랭킹
시계열 추론plantpulse-timeseries-insight-server:8980인사이트 모델 서빙
녹취 vLLMplantpulse-asr:8000음성 → 글. media 프로필일 때만 뜹니다
DCGM Exporterplantpulse-dcgm:9400GPU 메트릭
Phoenixplantpulse-phoenix:6006트레이스 UI · OTLP 수집 (기본 기동, 발행 안 함)
디지털 스레드 APIplantpulse-digital-thread-api:7140커넥터 등록부 · 공장 그래프 거울 · 채팅용 thread_ 도구. 관리 콘솔과 MCP 게이트웨이가 부른다
디지털 스레드 Neo4jplantpulse-digital-thread-neo4j:7474공장 그래프 거울 저장소. 디지털 스레드 API 만 붙는다
공학 계산 APIplantpulse-engcalc-api:7150채팅용 eng_ 도구(MCP /mcp/). MCP 게이트웨이만 부른다
MCP 게이트웨이plantpulse-mcp-gateway-api:7160플랫폼 · 내장 · 외부 MCP 서버를 모은 주소 하나(/mcp/)와 관리 REST(/api/v1). 코파일럿과 관리 콘솔이 부른다. 저장소는 플랫폼 PG pi 의 gw 스키마 (2026.10 재릴리즈(2026-10-20))
구 서비스 두 종은 아카이브되었습니다

plantpulse-mcp-server(50000)와 plantpulse-ontology(8888)는 독립 서비스로 존재하지 않습니다. MCP·온톨로지 도구는 플랫폼 server-web 통합 MCP(/api/v5/mcp, api_key 인증)가 제공합니다.

플랫폼에서 빌려 쓰는 것​

PostgreSQL(5432) · Aster TSDB(9042) · Redis/Valkey(6379) · RustFS(9000/9001)는 AI 스택이 띄우지 않습니다. PlantPulse 플랫폼 설치본을 공용으로 씁니다. 이 포트들의 방화벽·계정은 플랫폼 쪽 보안 설정을 따릅니다.

포트 상태 확인​

전체 상태 확인​

cd /opt/kopens/plantpulse-ai-docker/bin
./status.sh

health.sh 는 각 서비스의 헬스 엔드포인트까지 찔러 봅니다. 컨테이너가 떠 있는 것과 실제로 응답하는 것은 다르므로, 장애 조사에서는 이쪽을 쓰십시오.

개별 포트 확인​

# 특정 포트 리스닝 확인
nc -z 127.0.0.1 <포트> && echo "OK" || echo "DOWN"

# 포트 사용 프로세스 확인
ss -tlnp | grep <포트>

방화벽에 열 것​

대상열 포트
전체 사용자80 / 443 (프록시)
운영자 (사내망)5959 · 5960 관리 콘솔, 7474 Neo4j Browser
MCP 클라이언트 (사내망)7115 RAG, 8970 TimeSeries

설치기(install.sh)는 방화벽을 연 뒤 이 포트 중 이 스택 밖의 프로세스가 이미 쥔 것을 경고로 찍습니다 — 그대로 두면 첫 bin/up.sh 가 스택을 반쯤 띄운 뒤 «address already in use» 로 멈춥니다. 그 포트를 비우거나, 옮길 수 있는 세 키(PI_LITELLM_PORT · PI_ADMIN_WEB_PORT · PI_ADMIN_WEB_TLS_PORT)를 호스트 env 에서 바꾸십시오. 나머지 포트는 compose 에 고정돼 있습니다.

그 밖의 포트는 사내망 안에서도 열 이유가 없습니다. 데이터베이스 포트(5432 · 9042 · 6333 6379 · 7687 · 9000)는 어떤 경우에도 외부에 노출하지 마십시오.