installer: port page = check-only (no auto-open), big open/notOpen message

요청 반영: 간편설치기 포트포워딩 페이지가 포트를 직접 열지 않고 "열려 있는지"만
확인한다.
- server:portForward 를 UPnP 자동 개방/재점검 없이 외부 도달 점검만 하도록 변경,
  결과를 open/notOpen 으로 반환(PortForwardResult status 타입도 변경).
- 열려 있으면 외부 접속 주소를 크게, 안 열려 있으면 "직접 포트포워딩 해주세요"
  를 크게 표시.
- 페이지 체크에서만 쓰이던 openPortViaUpnp/removeUpnpMapping 제거(고아 코드).
- 참고: 서버 기동 시 run.bat 의 UPnP 자동 개방 주입(injectUpnpToRunBat)은 이번엔
  유지. v0.3.19.

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

installer-pf/renderer.js

@@ -112,9 +112,12 @@ function renderMain() {
     // 실패/확인불가일 때 다음 조치 안내: CGNAT 경고 + 수동 포워딩 방법.
     var extra = ''
     if (outcome.reachable !== true) {
-      if (outcome.cgnat) {
+      if (outcome.cgnat === 'yes') {
         extra += '<p class="formMessage error" style="margin-top:8px;">' +
-          escapeHtml(tt('main.cgnatWarn', { ip: outcome.externalIp || '?' })) + '</p>'
+          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 })

installer/renderer.js

@@ -820,16 +820,20 @@ function renderSubStep35(host, back, done) {
       var result = await installerApi.checkPortForward(port)
       state.serverInstall.portStatus = result
       var address = formatServerAddress(result.externalIp, result.port)
-      if (result.status === 'preForwarded') {
-        resultMsg.innerHTML = tt('step3.sub35.preForwarded', { address: address })
-        resultMsg.classList.add('success')
-      } else if (result.status === 'upnpOk') {
-        resultMsg.innerHTML = tt('step3.sub35.upnpOk', { address: address })
-        resultMsg.classList.add('success')
+      if (result.status === 'open') {
+        // 열려 있으면 외부 접속 주소를 크게 표시.
+        resultMsg.innerHTML =
+          '<div style="margin-top:12px;padding:18px;border:1px solid var(--success);border-radius:10px;background:rgba(63,185,80,0.12);text-align:center;">' +
+          '<div style="font-size:14px;color:var(--text-muted);">' + escapeHtml(tt('step3.sub35.openTitle')) + '</div>' +
+          '<div style="font-size:30px;font-weight:800;margin-top:8px;user-select:all;word-break:break-all;">' + escapeHtml(address) + '</div>' +
+          '</div>'
       } else {
-        resultMsg.innerHTML = (result.message || tt('step3.sub35.manualHint')) +
-          tt('step3.sub35.manualDetail', { address: address })
-        resultMsg.classList.add('warn')
+        // 안 열려 있으면 "직접 포트포워딩 해주세요" 를 크게 표시.
+        resultMsg.innerHTML =
+          '<div style="margin-top:12px;padding:18px;border:1px solid var(--danger);border-radius:10px;background:rgba(248,81,73,0.10);text-align:center;">' +
+          '<div style="font-size:26px;font-weight:800;">' + escapeHtml(tt('step3.sub35.notOpenBig')) + '</div>' +
+          '<div style="font-size:13px;color:var(--text-muted);margin-top:10px;">' + escapeHtml(tt('step3.sub35.notOpenHint', { address: address, port: result.port })) + '</div>' +
+          '</div>'
       }
       nextBtn.disabled = false
     } catch (err) {

locales/installer-pf/ko-kr.json

@@ -27,7 +27,8 @@
     "unknownMsg": "외부 도달 여부를 확정하지 못했습니다(외부 점검 서비스 응답 없음). 포트 매핑은 등록되었을 수 있습니다. 잠시 후 다시 시도하거나, 실제 접속으로 확인하세요.",
     "manualForward": "자동(UPnP) 개방이 안 되면 라우터 관리페이지에서 수동 포워딩: 외부 TCP {{port}} → 이 PC({{localIp}}) : {{port}}. 그리고 Windows 방화벽에서 TCP {{port}} 인바운드를 허용하세요.",
     "manualForwardNoIp": "이 PC 의 LAN IP 를 확인하지 못했습니다. 라우터에서 이 PC 로 외부 TCP {{port}} 포워딩과 Windows 방화벽 인바운드 허용을 설정하세요.",
-    "cgnatWarn": "주의: 외부 IP({{ip}})가 CGNAT(이중 NAT) 대역입니다. 이 경우 공유기 포트포워딩만으로는 외부 접속이 불가능하며, ISP 에 공인 IP 를 요청하거나 별도 터널링이 필요합니다.",
+    "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}} 매핑을 제거했습니다."
@@ -35,7 +36,10 @@
   "log": {
     "start": "포트포워딩 시작: TCP {{port}}",
     "localIp": "이 PC LAN IP: {{ip}}",
-    "cgnatDetected": "CGNAT(이중 NAT) 감지: 외부 IP {{ip}} 는 100.64~100.127 대역. 공유기 포워딩만으론 외부 접속 불가.",
+    "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}}",
@@ -54,6 +58,7 @@
     "closeTry": "UPnP 매핑 제거 시도: TCP {{port}}",
     "upnpRemoveAttempt": "UPnP 매핑 제거 시도: {{message}}",
     "upnpRemoveDone": "UPnP 매핑 제거 완료: TCP {{port}}",
+    "internalError": "내부 오류(무시하고 계속): {{message}}",
     "upnpClientFail": "UPnP 클라이언트 생성 실패: {{message}}",
     "portInUse": "포트 {{port}}이(가) 이미 사용 중 → 임시 리스너 없이 외부 서비스 응답만으로 판정.",
     "listenerBindFail": "임시 리스너 바인딩 실패: {{message}}",

locales/installer/ko-kr.json

@@ -124,14 +124,13 @@
     },
     "sub35": {
       "heading": "포트포워딩",
-      "description": "UPNP를 개방해 외부 접속을 허용합니다.",
+      "description": "포트가 외부에서 열려 있는지 확인합니다. (설치기가 직접 열지는 않습니다)",
       "portLabel": "포트",
       "recheck": "재점검",
       "checking": "확인 중...",
-      "preForwarded": "포트포워딩 성공! 친구는 <strong>{{address}}</strong> 주소로 서버에 접속할 수 있습니다. (이미 외부 개방되어 있음)",
-      "upnpOk": "포트포워딩 성공! 친구는 <strong>{{address}}</strong> 주소로 서버에 접속할 수 있습니다. (UPnP로 자동 개방 완료)",
-      "manualHint": "직접 포트포워딩을 해주세요.",
-      "manualDetail": "<br><small>외부 주소: {{address}}</small>",
+      "openTitle": "포트가 열려 있습니다! 친구 접속 주소",
+      "notOpenBig": "직접 포트포워딩 해주세요.",
+      "notOpenHint": "공유기에서 외부 TCP {{port}} 를 이 PC 로 포워딩하세요. (외부 주소: {{address}})",
       "checkFailed": "점검 실패: {{message}}",
       "ipUnknown": "확인 불가"
     }

package.json

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

src/installer-pf/main.ts

@@ -38,6 +38,16 @@ 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 안내에 쓴다. */
@@ -55,7 +65,7 @@ function detectLocalIpv4(): string {
   return priv || candidates[0] || ''
 }
 
-/** CGNAT(이중 NAT) 대역 100.64.0.0/10 인지. 이 경우 공유기 포워딩만으론 외부 접속 불가. */
+/** CGNAT(이중 NAT) 대역 100.64.0.0/10 인지. */
 function isCgnat(ip: string): boolean {
   const m = ip.match(/^100\.(\d+)\./)
   if (!m) return false
@@ -63,6 +73,29 @@ function isCgnat(ip: string): boolean {
   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)
@@ -117,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 {}
@@ -305,7 +338,8 @@ async function probePortFromOutside(
 interface PortForwardOutcome {
   externalIp: string
   localIp: string
-  cgnat: boolean
+  wanIp: string
+  cgnat: 'yes' | 'no' | 'unknown'
   port: number
   reachable: boolean | null
   preForwarded: boolean
@@ -327,16 +361,17 @@ ipcMain.handle('pf:open', async (_event, portInput: number): Promise<PortForward
 
   let externalIp = await detectExternalIpHttp()
   if (externalIp) sendLog(t('log.externalIpHttp', { ip: externalIp }))
-  else {
-    sendLog(t('log.externalIpHttpFail'))
-    externalIp = await detectExternalIpUpnp()
-    if (externalIp) sendLog(t('log.externalIpUpnp', { ip: externalIp }))
-    else sendLog(t('log.externalIpFail'))
-  }
-  const cgnat = isCgnat(externalIp)
-  if (cgnat) sendLog(t('log.cgnatDetected', { ip: externalIp }))
+  else sendLog(t('log.externalIpHttpFail'))
+  // 라우터 WAN(IGD 외부) IP 를 UPnP 로 조회해 HTTP 공인 IP 와 비교 → CGNAT/이중 NAT 판별.
+  const wanIp = await detectExternalIpUpnp()
+  if (wanIp) sendLog(t('log.routerWan', { ip: wanIp }))
+  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, cgnat, port, reachable, preForwarded, detail })
+    ({ externalIp, localIp, wanIp, cgnat, port, reachable, preForwarded, detail })
 
   // 1차 점검: 이미 외부에서 닿는지.
   sendLog(t('log.probeStart'))

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

src/installer/main.ts

@@ -860,12 +860,7 @@ ipcMain.handle('server:portForward', async (_event, port: number): Promise<PortF
   const targetPort = Number.isFinite(port) && port > 0 ? port : 25565
   sendLog(t('log.portCheckStart', { port: targetPort }))
 
-  // 1차 점검 전에 우리가 이전 실행에서 만든 UPnP 매핑이 남아 있으면 먼저 제거한다.
-  // 이렇게 해야 "사용자 라우터 규칙이 활성화돼서 외부 접근이 가능한 상태" 와 "UPnP 매핑 덕분에 접근 가능한 상태" 가 구별된다.
-  // 사용자 규칙이 비활성/없으면 1차 점검은 false 가 되어 UPnP 시도 단계로 자연스럽게 넘어간다.
-  sendLog(t('log.upnpCleanup'))
-  await removeUpnpMapping(targetPort)
-
+  // 설치기는 포트를 직접 열지 않는다. 외부에서 이미 열려 있는지만 확인한다.
   // 외부 IP 확보: 공용 API → 실패 시 UPnP 게이트웨이의 외부 IP로 폴백.
   let externalIp = await detectExternalIpHttp()
   if (externalIp) {
@@ -877,9 +872,9 @@ ipcMain.handle('server:portForward', async (_event, port: number): Promise<PortF
     else sendLog(t('log.externalIpUpnpFail'))
   }
 
-  // 1차 점검: 외부에서 이미 접근 가능한지 (서버가 떠 있거나, 우리가 임시 리스너 띄워서 검증).
+  // 외부에서 포트가 닿는지 점검(서버가 떠 있거나, 임시 리스너로 검증).
   sendLog(t('log.probeStart'))
-  let probe = await probePortFromOutside(targetPort, externalIp)
+  const probe = await probePortFromOutside(targetPort, externalIp)
   if (!externalIp && probe.detectedIp) externalIp = probe.detectedIp
   const verdict = probe.reachable === true
     ? t('log.probeVerdictSuccess')
@@ -888,47 +883,9 @@ ipcMain.handle('server:portForward', async (_event, port: number): Promise<PortF
 
   if (probe.reachable === true) {
     sendLog(t('log.probePreForwarded', { addr: externalIp || t('log.ipUnknown'), port: targetPort }))
-    return { status: 'preForwarded', externalIp, port: targetPort }
+    return { status: 'open', externalIp, port: targetPort }
   }
-
-  // UPnP 시도.
-  sendLog(t('log.upnpTryOpen', { port: targetPort }))
-  try {
-    await openPortViaUpnp(targetPort)
-    sendLog(t('log.upnpReqOk'))
-  } catch (error) {
-    const msg = (error as Error).message || String(error)
-    sendLog(t('log.upnpTryFail', { message: msg }))
-    return {
-      status: 'upnpFailed',
-      externalIp,
-      port: targetPort,
-      message: t('log.upnpFailDetail', { message: msg })
-    }
-  }
-
-  // NAT 반영 지연을 고려해 최대 3회 재점검.
-  for (let attempt = 1; attempt <= 3; attempt++) {
-    await sleep(1500)
-    sendLog(t('log.upnpRecheck', { attempt }))
-    probe = await probePortFromOutside(targetPort, externalIp)
-    if (!externalIp && probe.detectedIp) externalIp = probe.detectedIp
-    if (probe.reachable === true) {
-      sendLog(t('log.upnpDone', { port: targetPort }))
-      await removeUpnpMapping(targetPort)
-      return { status: 'upnpOk', externalIp, port: targetPort }
-    }
-  }
-
-  // 테스트 목적으로 만든 매핑 정리. 실제 개방은 run.bat 이 담당.
-  sendLog(t('log.upnpCleanupTest'))
-  await removeUpnpMapping(targetPort)
-
-  const reason = probe.reachable === false
-    ? t('log.upnpFailReason1')
-    : t('log.upnpFailReason2', { detail: probe.detail })
-  sendLog(reason)
-  return { status: 'upnpFailed', externalIp, port: targetPort, message: reason }
+  return { status: 'notOpen', externalIp, port: targetPort }
 })
 
 async function detectExternalIpHttp(): Promise<string> {
@@ -1124,64 +1081,6 @@ function fetchIfconfigCoPortOnce(port: number): Promise<IfconfigPortResult> {
   })
 }
 
-function removeUpnpMapping(port: number): Promise<void> {
-  return new Promise((resolve) => {
-    let settled = false
-    const done = () => { if (!settled) { settled = true; resolve() } }
-    let client: ReturnType<typeof natUpnp.createClient> | null = null
-    try {
-      client = natUpnp.createClient()
-    } catch (err) {
-      sendLog(t('log.upnpClientFailRemove', { message: (err as Error).message }))
-      done()
-      return
-    }
-    const timer = setTimeout(() => {
-      try { client && client.close() } catch {}
-      sendLog(t('log.upnpRemoveTimeout'))
-      done()
-    }, 8000)
-    client.portUnmapping({ public: port, protocol: 'tcp' }, (err: Error | null) => {
-      clearTimeout(timer)
-      try { client && client.close() } catch {}
-      if (err) sendLog(t('log.upnpRemoveAttempt', { message: err.message }))
-      else sendLog(t('log.upnpRemoveDone', { port }))
-      done()
-    })
-  })
-}
-
-function openPortViaUpnp(port: number): Promise<void> {
-  return new Promise((resolve, reject) => {
-    let settled = false
-    const done = (err?: Error) => {
-      if (settled) return
-      settled = true
-      if (err) reject(err)
-      else resolve()
-    }
-    let client: ReturnType<typeof natUpnp.createClient> | null = null
-    try {
-      client = natUpnp.createClient()
-    } catch (err) {
-      done(err as Error)
-      return
-    }
-    const timer = setTimeout(() => {
-      try { client && client.close() } catch {}
-      done(new Error(t('errors.upnpTimeout')))
-    }, 15000)
-    client.portMapping(
-      { public: port, private: port, ttl: 0, description: 'MusicQuiz Server', protocol: 'tcp' },
-      (error: Error | null) => {
-        clearTimeout(timer)
-        try { client && client.close() } catch {}
-        done(error || undefined)
-      }
-    )
-  })
-}
-
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }

src/installer/types.ts

@@ -36,7 +36,8 @@ export interface RamCheckResult {
 }
 
 export interface PortForwardResult {
-  status: 'preForwarded' | 'upnpOk' | 'upnpFailed'
+  // 설치기는 포트를 직접 열지 않고 "열려 있는지"만 확인한다.
+  status: 'open' | 'notOpen'
   externalIp?: string
   port: number
   message?: string