PORT_REGISTRY 템플릿

여러 프로젝트를 동시에 띄우는 로컬 개발 환경에서 **앱 포트와 DB 포트를 프로젝트별로 영구 고정 할당**하기 위한 중앙 레지스트리.

사용법: 이 파일을 ~/.claude/projects/PORT_REGISTRY.md 로 복사한 뒤 로컬 프로젝트 현황에 맞게 편집한다. 관련 규칙: core/08-local-env.md, core/07-db.md 배경: docs/guide/LOCAL_PORT_POLICY.md

---

목적

여러 프로젝트를 동시에 띄우는 로컬 개발 환경에서 앱 포트와 DB 포트를 프로젝트별로 영구 고정 할당하기 위한 중앙 레지스트리.

신규 프로젝트 세팅 시 에이전트는 이 파일을 먼저 읽어 다음 비어 있는 번호를 할당하고, 할당 완료 후 행을 추가해야 한다.

할당 규칙

역할	기본 시작	증가 단위
Frontend	3000	+10
Backend API (Node)	4000	+10
Backend (Python/FastAPI)	8000	+10
DB (PostgreSQL)	5432	+1
DB (MySQL)	3306	+1
DB (MongoDB)	27017	+1
Redis	6379	+1
Admin / Storybook	6000	+10
DB GUI (Prisma Studio)	5555	+10

• 한번 할당된 포트는 프로젝트 삭제 전까지 재사용 금지 (외부 도구 설정 보존)
• 각 프로젝트 .env의 DATABASE_URL 포트 = docker-compose.yml ports 호스트 포트 = 아래 표 DB 포트 — 3자 일치 필수

프로젝트 할당표

아래 표는 예시 할당이다. 실제 포트는 사용자가 로컬 환경 스캔 후 확정해야 한다. 특히 5432는 2026-04-14 meetflow 사건의 원인 포트로, 이미 다른 컨테이너가 점유 중이면 피한다.

#	프로젝트	Frontend	Backend	DB (Postgres)	기타	비고
1	meetflow	3000	4000	5436	—	2026-04-14 사건 이후 5432 → 5436
2	ax-studio-plan	3010	4010	5433	—	—
3	aitem	3020	4020	5434	—	—
4	prompt-store	3030	4030	5435	—	—
5	ai-rules	3040	—	—	—	앱 없음, 문서/규칙 저장소
6	{새 프로젝트}	3050	4050	5437	—	—

사용 중인 포트 (스캐시용 참고)

아래는 매번 새로 스캔해서 갱신하는 영역 — 에이전트가 신규 세팅 시 확인.

복사# Windows (cmd / PowerShell / Git Bash)
netstat -ano | findstr "LISTENING"

# macOS / Linux — 전체 LISTEN 포트
lsof -iTCP -sTCP:LISTEN -P -n

# macOS / Linux — 특정 포트만 필터
lsof -iTCP -sTCP:LISTEN -P -n | grep -E ':(3000|3010|4000|4010|5432|5433|5434|5436|3306|27017|6379)\b'

행 추가 시 체크리스트

신규 프로젝트를 추가할 때 에이전트는 다음을 모두 확인한다:

• 다음 비어 있는 번호를 표에서 확인
• netstat/lsof로 해당 포트가 실제 비어 있는지 확인
• docker ps -a로 같은 포트를 노리는 컨테이너 없는지 확인
• 프로젝트 .env에 할당 번호 적용
• 프로젝트 docker-compose.yml ports에 할당 번호 명시
• 프로젝트 .env에 EXPECTED_DB_NAME 추가
• 이 표에 행 추가 + 커밋 (사용자 확인 후)

이력 로그 (선택)

대규모 변경 시 이력을 여기에 남긴다.

• 2026-04-15: 초기 템플릿 생성. meetflow 데이터 소실 사례(2026-04-14) 대응으로 1-B 프로젝트별 고정 포트 정책 도입.