installer-pf: prevent app from dying on nat-upnp async errors

라우터가 UPnP 를 거부(ECONNREFUSED)하는 환경에서 nat-upnp 가 콜백 밖에서
비동기 소켓 오류를 내면 Electron 메인이 종료돼 창이 갑자기 닫히는("오류나면서
끝남") 현상이 생길 수 있다. v0.3.17 에서 CGNAT 판별용으로 externalIp() 를 항상
호출하게 되면서 이 경로가 새로 노출됨. process 전역 uncaughtException/
unhandledRejection 가드로 잡아 로그만 남기고 앱은 계속 살려 둔다(각 UPnP 호출은
타임아웃으로 진행되므로 멈추지 않음). v0.3.18.

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>

installer-pf/renderer.js

@@ -108,11 +108,29 @@ function renderMain() {
       cls = 'warn'; badge = tt('verdict.unknown')
       msg = tt('main.unknownMsg')
     }
+
+    // 실패/확인불가일 때 다음 조치 안내: CGNAT 경고 + 수동 포워딩 방법.
+    var extra = ''
+    if (outcome.reachable !== true) {
+      if (outcome.cgnat === 'yes') {
+        extra += '<p class="formMessage error" style="margin-top:8px;">' +
+          escapeHtml(tt('main.cgnatWarn', { public: outcome.externalIp || '?', wan: outcome.wanIp || '?' })) + '</p>'
+      } else if (outcome.cgnat === 'unknown') {
+        extra += '<p class="formMessage" style="margin-top:8px;">' +
+          escapeHtml(tt('main.cgnatUnknown', { ip: outcome.externalIp || '?' })) + '</p>'
+      }
+      var manual = outcome.localIp
+        ? tt('main.manualForward', { port: outcome.port, localIp: outcome.localIp })
+        : tt('main.manualForwardNoIp', { port: outcome.port })
+      extra += '<p class="formMessage" style="margin-top:8px;">' + escapeHtml(manual) + '</p>'
+    }
+
     resultEl.innerHTML =
       '<div class="progressCard ' + (cls === 'ok' ? 'done' : cls === 'fail' ? 'error' : 'running') + '" style="margin-top:14px;">' +
       '  <div class="cardTop"><span class="statusBadge ' + cls + '">' + escapeHtml(badge) + '</span> ' +
       '  <span class="label">' + escapeHtml(addr) + '</span></div>' +
       '  <p class="formMessage" style="margin-top:8px;">' + escapeHtml(msg) + '</p>' +
+      extra +
       '  <p class="formMessage"><small>' + escapeHtml(tt('main.detailLabel', { detail: outcome.detail || '' })) + '</small></p>' +
       '</div>'
   }

locales/installer-pf/ko-kr.json

@@ -25,12 +25,22 @@
     "alreadyOpen": "(이미 열려 있던 상태입니다)",
     "failMsg": "외부에서 포트에 닿지 않습니다. 라우터 UPnP 설정, 이중 NAT(CGNAT), Windows 방화벽, 또는 포워딩 대상 IP 를 확인하세요.",
     "unknownMsg": "외부 도달 여부를 확정하지 못했습니다(외부 점검 서비스 응답 없음). 포트 매핑은 등록되었을 수 있습니다. 잠시 후 다시 시도하거나, 실제 접속으로 확인하세요.",
+    "manualForward": "자동(UPnP) 개방이 안 되면 라우터 관리페이지에서 수동 포워딩: 외부 TCP {{port}} → 이 PC({{localIp}}) : {{port}}. 그리고 Windows 방화벽에서 TCP {{port}} 인바운드를 허용하세요.",
+    "manualForwardNoIp": "이 PC 의 LAN IP 를 확인하지 못했습니다. 라우터에서 이 PC 로 외부 TCP {{port}} 포워딩과 Windows 방화벽 인바운드 허용을 설정하세요.",
+    "cgnatWarn": "주의: CGNAT/이중 NAT 로 보입니다(공인 IP {{public}} ≠ 라우터 WAN {{wan}}, 또는 WAN 이 사설/CGNAT 대역). 이 경우 공유기 포트포워딩만으로는 외부 접속이 불가능하며, ISP 에 공인 IP 를 요청하거나 별도 터널링이 필요합니다.",
+    "cgnatUnknown": "참고: 외부 IP({{ip}})만으로는 CGNAT(이중 NAT) 를 확정하거나 배제할 수 없습니다(라우터 UPnP 미응답으로 WAN IP 미확인). 라우터 관리페이지의 WAN(인터넷) IP 가 100.64~100.127 이거나 10.x / 192.168.x / 172.16~31 대역이면 이중 NAT 라 공유기 포워딩만으론 외부 접속이 안 됩니다.",
     "detailLabel": "점검 상세: {{detail}}",
     "error": "오류: {{message}}",
     "closed": "포트 {{port}} 매핑을 제거했습니다."
   },
   "log": {
     "start": "포트포워딩 시작: TCP {{port}}",
+    "localIp": "이 PC LAN IP: {{ip}}",
+    "routerWan": "라우터 WAN(UPnP) IP: {{ip}}",
+    "routerWanUnknown": "라우터 WAN IP 확인 불가(UPnP 미응답/거부) → 외부 IP 만으로는 CGNAT 확정/배제 불가",
+    "cgnatDetected": "CGNAT/이중 NAT 감지: 공인 IP {{public}} vs 라우터 WAN {{wan}}. 공유기 포워딩만으론 외부 접속 불가.",
+    "cgnatUnknown": "CGNAT 여부 확정 불가(라우터 WAN IP 미확인). 라우터 관리페이지에서 WAN IP 를 확인하세요.",
+    "upnpUnavailable": "라우터가 UPnP 제어 연결을 거부/미지원(ECONNREFUSED/타임아웃). 라우터에서 UPnP 를 켜거나 수동 포워딩이 필요합니다.",
     "cleanup": "이전 UPnP 매핑 정리 중…",
     "externalIpHttp": "외부 IP(HTTP): {{ip}}",
     "externalIpHttpFail": "외부 IP HTTP 조회 실패 → UPnP 게이트웨이로 폴백",
@@ -48,6 +58,7 @@
     "closeTry": "UPnP 매핑 제거 시도: TCP {{port}}",
     "upnpRemoveAttempt": "UPnP 매핑 제거 시도: {{message}}",
     "upnpRemoveDone": "UPnP 매핑 제거 완료: TCP {{port}}",
+    "internalError": "내부 오류(무시하고 계속): {{message}}",
     "upnpClientFail": "UPnP 클라이언트 생성 실패: {{message}}",
     "portInUse": "포트 {{port}}이(가) 이미 사용 중 → 임시 리스너 없이 외부 서비스 응답만으로 판정.",
     "listenerBindFail": "임시 리스너 바인딩 실패: {{message}}",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-music-quiz-installer",
-  "version": "0.3.15",
+  "version": "0.3.18",
   "description": "마인크래프트 음악퀴즈 간편설치기 + 관리 사이트",
   "main": "dist/installer/main.js",
   "scripts": {

src/installer-pf/main.ts

@@ -2,6 +2,7 @@ import { app, BrowserWindow, ipcMain } from 'electron'
 import http from 'node:http'
 import https from 'node:https'
 import net from 'node:net'
+import os from 'node:os'
 import path from 'node:path'
 import { URL } from 'node:url'
 import natUpnp from 'nat-upnp'
@@ -37,8 +38,64 @@ function sendLog(line: string): void {
   mainWindow.webContents.send('log', stamped)
 }
 
+// nat-upnp 는 라우터가 UPnP 를 거부/미지원할 때 콜백 밖에서 비동기 소켓 오류를
+// 낼 수 있다. 처리되지 않으면 Electron 메인 프로세스가 그대로 종료되어 창이 갑자기
+// 닫힌다("오류나면서 끝남"). 전역 가드로 잡아 로그만 남기고 앱은 계속 살려 둔다.
+process.on('uncaughtException', (err) => {
+  try { sendLog(t('log.internalError', { message: (err as Error)?.message || String(err) })) } catch {}
+})
+process.on('unhandledRejection', (reason) => {
+  try { sendLog(t('log.internalError', { message: reason instanceof Error ? reason.message : String(reason) })) } catch {}
+})
+
 const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
 
+/** 이 PC 의 LAN IPv4(사설 대역 우선). 수동 포워딩 대상 IP 안내에 쓴다. */
+function detectLocalIpv4(): string {
+  const ifaces = os.networkInterfaces()
+  const candidates: string[] = []
+  for (const name of Object.keys(ifaces)) {
+    for (const info of ifaces[name] || []) {
+      if (info.family === 'IPv4' && !info.internal && !info.address.startsWith('169.254.')) {
+        candidates.push(info.address)
+      }
+    }
+  }
+  const priv = candidates.find((a) => /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(a))
+  return priv || candidates[0] || ''
+}
+
+/** CGNAT(이중 NAT) 대역 100.64.0.0/10 인지. */
+function isCgnat(ip: string): boolean {
+  const m = ip.match(/^100\.(\d+)\./)
+  if (!m) return false
+  const octet = Number(m[1])
+  return octet >= 64 && octet <= 127
+}
+
+/** 사설(RFC1918) IPv4 인지. 라우터 WAN 이 사설이면 앞단에 NAT 이 또 있다는 뜻(이중 NAT). */
+function isPrivateIpv4(ip: string): boolean {
+  return /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(ip)
+}
+
+/**
+ * CGNAT/이중 NAT 여부 판별. HTTP 로 본 공인 egress IP 하나만으로는 배제할 수 없다
+ * (전형적 CGNAT 은 egress 는 ISP 공인 IP, 라우터 WAN 만 100.64/10 이라 egress 검사로는 놓침).
+ * 그래서 라우터 WAN(IGD 외부) IP 를 함께 보고 비교한다.
+ *   - 'yes'     : 공인 IP 가 CGNAT 대역이거나, 라우터 WAN 이 사설/CGNAT 이거나 공인 IP 와 다름.
+ *   - 'no'      : 라우터 WAN 이 HTTP 공인 IP 와 동일 → 단일 NAT 확정.
+ *   - 'unknown' : 라우터 WAN 을 못 읽음(UPnP 미응답/거부) → 외부 IP 만으로는 확정/배제 불가.
+ */
+function classifyCgnat(publicIp: string, wanIp: string): 'yes' | 'no' | 'unknown' {
+  if (publicIp && isCgnat(publicIp)) return 'yes'
+  if (wanIp) {
+    if (isCgnat(wanIp) || isPrivateIpv4(wanIp)) return 'yes'
+    if (publicIp && wanIp !== publicIp) return 'yes'
+    if (publicIp && wanIp === publicIp) return 'no'
+  }
+  return 'unknown'
+}
+
 function fetchBuffer(url: string): Promise<Buffer> {
   return new Promise((resolve, reject) => {
     const target = new URL(url)
@@ -93,7 +150,7 @@ function detectExternalIpUpnp(): Promise<string> {
     const timer = setTimeout(() => {
       try { client && client.close() } catch {}
       finish('')
-    }, 8000)
+    }, 6000)
     client.externalIp((err: Error | null, ip?: string) => {
       clearTimeout(timer)
       try { client && client.close() } catch {}
@@ -280,6 +337,9 @@ async function probePortFromOutside(
 
 interface PortForwardOutcome {
   externalIp: string
+  localIp: string
+  wanIp: string
+  cgnat: 'yes' | 'no' | 'unknown'
   port: number
   reachable: boolean | null
   preForwarded: boolean
@@ -292,18 +352,26 @@ ipcMain.handle('pf:open', async (_event, portInput: number): Promise<PortForward
   const port = Number.isFinite(portInput) && portInput > 0 && portInput < 65536 ? Math.floor(portInput) : 25565
   sendLog(t('log.start', { port }))
 
+  const localIp = detectLocalIpv4()
+  if (localIp) sendLog(t('log.localIp', { ip: localIp }))
+
   // 이전에 남은 매핑을 먼저 제거해 "사용자 라우터 규칙으로 이미 열린 상태" 와 구별.
   sendLog(t('log.cleanup'))
   await removeUpnpMapping(port)
 
   let externalIp = await detectExternalIpHttp()
   if (externalIp) sendLog(t('log.externalIpHttp', { ip: externalIp }))
-  else {
+  else sendLog(t('log.externalIpHttpFail'))
-    sendLog(t('log.externalIpHttpFail'))
+  // 라우터 WAN(IGD 외부) IP 를 UPnP 로 조회해 HTTP 공인 IP 와 비교 → CGNAT/이중 NAT 판별.
-    externalIp = await detectExternalIpUpnp()
+  const wanIp = await detectExternalIpUpnp()
-    if (externalIp) sendLog(t('log.externalIpUpnp', { ip: externalIp }))
+  if (wanIp) sendLog(t('log.routerWan', { ip: wanIp }))
-    else sendLog(t('log.externalIpFail'))
+  else sendLog(t('log.routerWanUnknown'))
-  }
+  if (!externalIp && wanIp) externalIp = wanIp
+  const cgnat = classifyCgnat(externalIp, wanIp)
+  if (cgnat === 'yes') sendLog(t('log.cgnatDetected', { public: externalIp || '?', wan: wanIp || '?' }))
+  else if (cgnat === 'unknown') sendLog(t('log.cgnatUnknown'))
+  const wrap = (reachable: boolean | null, preForwarded: boolean, detail: string): PortForwardOutcome =>
+    ({ externalIp, localIp, wanIp, cgnat, port, reachable, preForwarded, detail })
 
   // 1차 점검: 이미 외부에서 닿는지.
   sendLog(t('log.probeStart'))
@@ -312,7 +380,7 @@ ipcMain.handle('pf:open', async (_event, portInput: number): Promise<PortForward
   sendLog(t('log.probeResult', { verdict: verdictText(probe.reachable), detail: probe.detail }))
   if (probe.reachable === true) {
     sendLog(t('log.preForwarded'))
-    return { externalIp, port, reachable: true, preForwarded: true, detail: probe.detail }
+    return wrap(true, true, probe.detail)
   }
 
   // UPnP 개방 시도.
@@ -321,8 +389,11 @@ ipcMain.handle('pf:open', async (_event, portInput: number): Promise<PortForward
     await openPortViaUpnp(port)
     sendLog(t('log.upnpReqOk'))
   } catch (error) {
-    sendLog(t('log.upnpTryFail', { message: (error as Error).message }))
+    const msg = (error as Error).message
-    return { externalIp, port, reachable: probe.reachable, preForwarded: false, detail: probe.detail }
+    sendLog(t('log.upnpTryFail', { message: msg }))
+    // ECONNREFUSED/타임아웃 = 라우터가 UPnP 제어를 거부/미지원. 수동 포워딩 안내로 유도.
+    if (/ECONNREFUSED|ETIMEDOUT|timed out|시간 초과/i.test(msg)) sendLog(t('log.upnpUnavailable'))
+    return wrap(probe.reachable, false, probe.detail)
   }
 
   // NAT 반영 지연 고려 재점검.
@@ -333,11 +404,11 @@ ipcMain.handle('pf:open', async (_event, portInput: number): Promise<PortForward
     if (!externalIp && probe.detectedIp) externalIp = probe.detectedIp
     if (probe.reachable === true) {
       sendLog(t('log.upnpDone', { port }))
-      return { externalIp, port, reachable: true, preForwarded: false, detail: probe.detail }
+      return wrap(true, false, probe.detail)
     }
   }
   sendLog(t('log.upnpUnconfirmed'))
-  return { externalIp, port, reachable: probe.reachable, preForwarded: false, detail: probe.detail }
+  return wrap(probe.reachable, false, probe.detail)
 })
 
 ipcMain.handle('pf:close', async (_event, portInput: number): Promise<void> => {

src/installer-pf/preload.ts

@@ -2,6 +2,9 @@ import { contextBridge, ipcRenderer } from 'electron'
 
 interface PortForwardOutcome {
   externalIp: string
+  localIp: string
+  wanIp: string
+  cgnat: 'yes' | 'no' | 'unknown'
   port: number
   reachable: boolean | null
   preForwarded: boolean