목차

    불편함을 코드로 지웁니다.

    개발 공부 노트, 개발 도구와 문제를 해결한 과정, AI 프롬프트와 Obsidian 활용법을 정리합니다.

      📦 Assets

      [무료 배포] Windows 포트 충돌 해결 도구 PortManager (EADDRINUSE 원클릭 해결)

      this.Serena 2026. 3. 26. 10:51

      Windows에서 포트 충돌 에러(EADDRINUSE)를 겪을 때 netstat -ano 명령어 없이 GUI로 포트를 확인하고 프로세스를 종료할 수 있는 무료 데스크톱 앱, PortManager를 소개합니다. 설치 없이 exe 하나로 실행할 수 있으며, Electron 기반으로 직접 개발했습니다.

      더보기

      EADDRINUSE란?

      EADDRINUSE는 "Error: Address Already In Use"의 약자로, 네트워크 프로그래밍에서 발생하는 에러 코드입니다.

      쉽게 말하면

      내가 사용하려는 포트 번호를 다른 프로세스가 이미 점유하고 있을 때 발생하는 에러입니다.

      예를 들어 설명하면 이렇습니다.

      카페에 콘센트 자리가 하나 있는데, 이미 누가 앉아 있으면 내가 거기 앉을 수 없는 것과 같습니다. 포트도 마찬가지로, 하나의 포트를 두 프로그램이 동시에 사용할 수 없습니다.

      실제 에러 메시지

      Node.js로 서버를 실행할 때 가장 흔하게 볼 수 있습니다.

      Error: listen EADDRINUSE: address already in use :::3000

      이 메시지는 "3000번 포트를 이미 누군가 쓰고 있어서 서버를 시작할 수 없다"는 뜻입니다.

      왜 발생하나?

      주요 원인은 다음과 같습니다.

      원인상황
      서버 중복 실행 이전에 실행한 서버를 종료하지 않고 다시 npm start 한 경우
      비정상 종료 Ctrl+C 없이 터미널을 그냥 닫아서 프로세스가 백그라운드에 남아 있는 경우
      다른 앱이 같은 포트 사용 예: 3000번 포트를 Node.js와 다른 앱이 동시에 쓰려는 경우

      해결 방법

      기존에는 아래 명령어를 매번 수동으로 입력해야 했습니다.

      # 1단계: 3000번 포트를 점유 중인 프로세스 PID 확인
netstat -ano | findstr :3000

# 2단계: 해당 PID의 프로세스 종료
taskkill /F /PID 1234

      PortManager가 바로 이 과정을 GUI에서 클릭 한 번으로 해결하기 위해 만들어진 앱입니다. 포트 목록에서 충돌이 발생한 포트를 찾고, Kill 버튼을 누르면 해당 프로세스가 종료되어 포트가 해제됩니다.

      요약

      항목 내용
      정식 명칭 EADDRINUSE (Error: Address Already In Use)
      의미 사용하려는 포트가 이미 다른 프로세스에 의해 점유된 상태
      발생 환경 Node.js, Python, Java 등 네트워크 서버 실행 시 공통
      핵심 해결 해당 포트를 점유 중인 프로세스를 찾아 종료하면 해결

      💾 다운로드: PortManager 릴리즈 페이지
      📂 GitHub: hayohio-bit/PortManager

      왜 만들었나: 포트 충돌, 매번 netstat 치기 귀찮다

      개발하다 보면 이런 에러를 자주 만납니다.

      Error: listen EADDRINUSE: address already in use :::3000

      이 에러가 뜰 때마다 해야 하는 작업은 항상 같습니다.

      1. netstat -ano | findstr :3000 으로 PID 확인
      2. tasklist로 프로세스 이름 확인
      3. taskkill /F /PID xxxx 로 종료

      세 번의 명령어를 매번 반복하는 것이 번거로워서, 이 과정을 클릭 한 번으로 해결하는 GUI 앱을 만들어봤습니다.

      주요 기능

      기능 설명
      실시간 포트 조회 LISTEN 중인 TCP/UDP 포트를 전체 목록으로 표시
      통합 검색 포트 번호, 프로세스 이름, PID, 주소를 한 번에 검색 (디바운싱 200ms)
      프로토콜 필터 전체 / TCP / UDP 탭으로 빠르게 필터링
      컬럼 정렬 프로토콜, 주소, 포트, PID, 프로세스 이름 기준 오름/내림차순
      원클릭 프로세스 종료 Kill 버튼 → 확인 모달 → 강제 종료 (taskkill /F)
      시스템 프로세스 보호 Windows 커널 프로세스(PID 4 등) 종료 차단
      토스트 알림 성공/실패 결과를 화면 우측 하단에 3초간 표시
      포터블 실행 설치 없이 exe 하나로 즉시 실행

      💡 이런 분들에게 추천합니다

      netstat 명령어에 익숙하지 않은 분
      포트 점유 프로세스를 빠르게 확인하고 종료하고 싶은 분

      다운로드 및 실행 방법

      시스템 요구사항

      • Windows 10 / 11 (x64)
      • 일반 사용자 권한으로 실행 가능 (프로세스 종료 시에만 UAC 요청)

      설치 및 실행

      1. 릴리즈 페이지에서 PortManager 1.0.0 Portable.exe 다운로드
      2. 파일을 더블클릭하여 실행
      3. 앱이 열리면 포트 목록이 자동으로 로드됩니다
      4. 프로세스 종료 시 UAC 창이 나타납니다. "예"를 클릭하면 해당 프로세스만 관리자 권한으로 종료됩니다

      ⚠️ Windows SmartScreen 경고가 뜨는 경우:
      코드 서명이 없는 exe에서 발생합니다. "추가 정보" → "실행"을 클릭하면 정상 실행됩니다.

      사용 화면

      앱 레이아웃:

      ⚡ Port Manager [127개 포트] [🔄 새로고침]
🔍 [포트 번호 또는 프로세스 이름으로 검색...]
[전체] [TCP] [UDP]

프로토콜 | 주소      | 포트 | PID  | 프로세스   | 작업
TCP      | 0.0.0.0  | 3000 | 1234 | node.exe  | [종료]
TCP      | 0.0.0.0  | 5432 | 5678 | postgres  | [종료]
UDP      | 0.0.0.0  | 5353 | 912  | svchost   | [종료]

      기술 스택

      항목 내용
      프레임워크 Electron 33
      언어 JavaScript (Node.js 20+)
      포트 조회 netstat -ano + tasklist (UTF-8 강제)
      프로세스 종료 PowerShell Start-Process -Verb RunAs + taskkill
      빌드 도구 electron-builder 25
      배포 형태 Portable EXE (설치 불필요)

      핵심 구현 설명

      포트 조회: netstat + tasklist 병렬 실행

      netstat -ano와 tasklist를 Promise.all로 병렬 실행한 뒤, PID를 기준으로 매핑합니다. chcp 65001을 선행 실행하여 한글 Windows(CP949)에서도 UTF-8 출력을 보장합니다.

      const [netstatResult, processMap] = await Promise.all([
  execAsync('chcp 65001 >nul 2>&1 && netstat -ano', { shell: true }),
  getProcessMap(),
]);

      권한 모델: Hybrid Elevation

      앱 자체는 asInvoker로 실행되어 UAC 차단 없이 즉시 시작됩니다. 프로세스 종료 시에만 PowerShell RunAs 동사로 해당 명령에 한해 관리자 권한을 요청합니다.

      const command = `powershell -Command "Start-Process cmd -ArgumentList '/c taskkill /F /PID ${safePid}' -Verb RunAs -WindowStyle Hidden -Wait"`;
await execAsync(command);

      보안 설계

      • 렌더러 격리: contextIsolation: true, nodeIntegration: false, sandbox: true
      • IPC 화이트리스트: contextBridge를 통해 getPorts(), killProcess() 두 개 API만 노출
      • 커맨드 인젝션 방지: PID 입력값을 정수로 검증 후 사용
      • 시스템 프로세스 보호: PID 4(Windows 커널) 등 보호 목록에 포함된 프로세스 종료 차단
      • CSP 적용: 인라인 스크립트, 외부 리소스 로딩 차단

      프로젝트 구조

      PortManager/
├── main.js                # Electron 메인 프로세스 (윈도우 생성, IPC 핸들러)
├── preload.js             # contextBridge IPC 브릿지
├── src/
│   └── services/
│       └── portService.js # netstat / tasklist 파싱, 프로세스 종료
└── renderer/
    ├── index.html         # 앱 레이아웃
    ├── css/style.css      # 스타일
    ├── js/app.js          # 검색/필터/정렬/모달/토스트 로직
    └── fonts/             # @fontsource/inter 오프라인 폰트

      FAQ

      Q. netstat로 직접 확인하는 것과 뭐가 다른가요?
      A. netstat은 텍스트 출력이라 PID를 찾고, tasklist로 프로세스 이름을 다시 확인하고, taskkill로 종료하는 세 단계를 거쳐야 합니다. PortManager는 이 과정을 하나의 화면에서 검색, 확인, 종료까지 원클릭으로 처리합니다.

      Q. 관리자 권한 없이도 사용할 수 있나요?
      A. 포트 목록 조회는 일반 사용자 권한으로 가능합니다. 프로세스 종료 시에만 UAC 확인 창이 나타납니다.

      Q. SmartScreen 경고는 왜 뜨나요?
      A. 코드 서명이 없는 exe 파일에서 발생하는 일반적인 경고입니다. "추가 정보" → "실행"을 클릭하면 됩니다.

      Q. 시스템 프로세스를 실수로 종료할 위험은 없나요?
      A. Windows 커널 프로세스(PID 4 등)는 앱 내부에서 종료가 차단되며, 모든 종료 작업에 확인 모달이 표시됩니다.

      마무리

      포트 충돌은 개발 중 자주 마주치는 문제입니다. 기존에는 커맨드라인에서 여러 명령어를 조합해야 했지만, PortManager를 사용하면 GUI에서 클릭 한 번으로 해결할 수 있습니다. 버그 리포트, 기능 제안, PR 모두 환영합니다.

      📥 다운로드: PortManager v1.0.0
      🔗 GitHub: hayohio-bit/PortManager

       

       

      저작자표시 비영리 변경금지 (새창열림)

      티스토리툴바