fix(installer): 다운로드 일시 오류 시 자동 재시도(백오프)

메인 간편설치기의 fetchBuffer/downloadFile 은 재시도가 없어, 너무 빠르게/자주
요청해 생기는 일시적 오류(429·5xx·네트워크 끊김·타임아웃, 일부 403)에 곧바로
실패했다. RP 설치기처럼 일시 오류를 지수 백오프(Retry-After 우선)로 최대 3회
재시도하도록 보강(모드 다중 다운로드/서버·맵·리소스팩·매니페스트 모두 적용).
404 등 영구 오류는 그대로 실패. 0.4.12→0.4.13.

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

docs/installer.md

@@ -28,10 +28,14 @@
 
 ### 3-2. JDK 확인
 
-- 각 음악퀴즈(pack)는 사이트 편집기에서 **권장 JDK 버전**(예: Java 25)을 지정합니다. 설치기는 이 권장 버전을 기준으로 동작합니다.
-- 탐색 순서: **① 권장 JDK 자동 설치 위치(`%APPDATA%\jdk\temurin-<권장>`) 를 가장 먼저** 확인 → 없으면 **② 컴퓨터의 JDK(`JAVA_HOME` / `JDK_HOME` / `C:\Program Files\Java`)** 를 확인.
-- 최신 마인크래프트 서버는 특정 자바 버전 이상을 요구합니다(예: 서버 번들러 class file 69.0 = Java 25). 그보다 낮은 자바는 있어도 `UnsupportedClassVersionError` 로 서버가 뜨지 않으므로, 자동 탐색은 **권장 버전 미만을 "없음"으로 처리**해 자동 설치로 유도합니다. 직접 선택/입력한 경로도 "다음" 에서 버전을 검증해 미만이면 진행을 막습니다.
-- **자동 설치** 버튼을 누르면 Adoptium Temurin(권장 버전) Windows x64 zip 을 받아 `%APPDATA%\jdk\temurin-<권장>\` 에 풀어 사용합니다.
+- 각 음악퀴즈(pack)는 사이트 편집기에서 **권장 JDK 버전**(예: Java 25)을 지정합니다. 편집기 목록은 Adoptium(Temurin)에서 실제 배포되는 버전을 불러오며, "자세히 보기"로 비-LTS·스냅샷까지 확인할 수 있습니다. 설치기는 이 권장 버전을 기준으로 동작합니다.
+- 탐색 순서:
+  1. **설치기 자동 설치 위치 `%APPDATA%\.mc_custom\jdk`**(구버전 `%APPDATA%\jdk` 호환)에 JDK 가 있으면 **가장 먼저 사용**합니다(권장 버전이면 그대로, 혹시 다른 버전이면 경고).
+  2. 없으면 **환경변수(`JAVA_HOME` / `JDK_HOME`)** 의 JDK 가 **권장 버전이면** 사용합니다.
+  3. 그래도 없으면 **기본 폴더 `C:\Program Files\Java`** 에서 **권장 버전**을 찾아 사용합니다.
+  4. 권장 버전을 어디서도 못 찾으면 **환경변수 자바(없으면 Program Files 자바)로 폴백**하고, "권장 버전과 달라 서버가 정상 실행되지 않을 수 있다"는 **경고**를 띄웁니다.
+- 직접 선택/입력한 경로도 "다음" 에서 검증해, 권장과 다르면 경고 후 동의(확인) 시에만 진행합니다(무조건 차단이 아니라 경고+동의). 아무 JDK 도 없으면 자동 설치로 유도합니다.
+- **자동 설치** 버튼을 누르면 Adoptium Temurin(권장 버전) Windows x64 zip 을 받아 **`%APPDATA%\.mc_custom\jdk\temurin-<권장>\`** 에 풀어 사용합니다. (`.mc_custom` 안에 두므로 "음악퀴즈 파일제거" 도구로 한 번에 정리됩니다. `MC_CUSTOM_DIR` 로 폴더명을 바꾼 경우 그 폴더 아래 `jdk`.)
 - 설치 중 같은 버튼이 "설치 취소" 로 바뀌고, 누르면 다운로드를 즉시 중단하고 부분 파일을 정리합니다.
 - 서버 zip 의 `run.bat` 이 시스템 PATH 의 `java` 를 그대로 쓰면 낡은 자바로 실행돼 실패할 수 있어, 설치기가 준비/선택한 JDK 의 `java` 를 쓰도록 `run.bat` 을 자동으로 수정합니다(자동 설치 JDK 는 `%APPDATA%` 전개형 경로라 한글 사용자명에도 안전).
 

locales/installer/ko-kr.json

@@ -205,6 +205,7 @@
   },
   "log": {
     "manifestDownload": "manifest 다운로드: {{url}}",
+    "downloadRetry": "다운로드 일시 오류({{reason}}) — {{attempt}}번째 재시도, {{secs}}초 후",
     "packLoadFail": "pack 로드 실패 ({{file}}): {{message}}",
     "packsLoaded": "로드된 음악퀴즈: {{count}}개",
     "selectedPack": "선택: {{key}}",

locales/server/ko-kr.json

@@ -126,7 +126,12 @@
     "clientMinRam": "클라이언트 최소 램 (MB)",
     "clientRecommendedRam": "클라이언트 권장 램 (MB)",
     "recommendedJdk": "권장 JDK (서버 실행용)",
-    "recommendedJdkHint": "설치기가 이 버전을 우선 찾고, 없으면 자동 설치합니다. 서버가 요구하는 자바 버전에 맞춰 고르세요(최신 마인크래프트는 보통 Java 25).",
+    "recommendedJdkHint": "설치기가 이 버전을 우선 찾고, 없으면 자동 설치합니다. 서버가 요구하는 자바 버전에 맞춰 고르세요(최신 마인크래프트는 보통 Java 25). 목록은 Adoptium(Temurin)에서 실제 배포되는 버전을 불러옵니다.",
+    "jdkShowDetails": "자세히 보기 (모든 버전·스냅샷)",
+    "jdkDetailsGa": "정식(GA)",
+    "jdkDetailsEa": "개발 스냅샷(EA)",
+    "jdkDetailsNone": "상세 버전 정보를 불러오지 못했습니다.",
+    "jdkLtsSuffix": " (LTS)",
     "mapPath": "맵 파일 (.zip)",
     "mapPathHint": "/file/maps/ 아래 zip 파일 이름.",
     "serverPath": "서버 파일 (.zip)",

package.json

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

src/installer-rp/main.ts

@@ -77,10 +77,10 @@ function pickMusicConcurrency(): number {
  */
 const MUSIC_START_STAGGER_MS = 2000
 
-/** 사진(썸네일) 다운로드 사이 최소 간격(ms). i.ytimg.com 429(rate limit) 를 유발하지 않도록 순차 요청을 살짝 벌린다. */
-const IMAGE_REQUEST_INTERVAL_MS = 800
-/** 음악(yt-dlp) 단계 직후엔 유튜브가 IP 를 일시 throttle 할 수 있어, 사진 단계 전 잠깐 쉬어 429 를 피한다. */
-const IMAGE_PHASE_COOLDOWN_MS = 4000
+/** 사진(썸네일) 동시 다운로드 상한. 순차 대신 병렬로 받아 속도를 높인다. 429 는 images.ts 의 지수 백오프 재시도가 흡수한다. */
+const IMAGE_CONCURRENCY_CAP = 8
+/** 음악(yt-dlp) 단계 직후 유튜브 IP throttle 이 남아 있을 수 있어, 사진 단계 전 아주 잠깐만 쉰다. */
+const IMAGE_PHASE_COOLDOWN_MS = 1000
 
 const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))
 
@@ -516,21 +516,26 @@ ipcMain.handle('rp:install:start', async (): Promise<{ resourcepackPath: string
       sendLog(t('log.imageCooldown', { secs: Math.round(IMAGE_PHASE_COOLDOWN_MS / 1000) }))
       await sleep(IMAGE_PHASE_COOLDOWN_MS)
     }
-    let imageRequests = 0
-    for (let i = 0; i < imageTotal; i++) {
-      throwIfCancelled()
-      const entry = pack.list.images[i]
+    // 여러 장을 동시에 받아 속도를 높인다(순차+딜레이 대신 워커 풀). 유튜브 429 는
+    // 각 다운로드의 지수 백오프 재시도(images.ts)가 흡수하고, 첫 하드 실패를 만나면
+    // 새 작업 배정을 멈춘 뒤 워커가 모두 끝나면 그 오류를 던진다.
+    const images = pack.list.images
+    let imageNext = 0
+    let imageError: Error | null = null
+    async function imageWorker(): Promise<void> {
+      while (true) {
+        if (state.cancelRequested || imageError) return
+        const i = imageNext++
+        if (i >= imageTotal) return
         const idx = i + 1
-      // 이전 시도에서 이미 정규화해둔 사진은 건너뛴다(이어받기).
+        const entry = images[i]
         const coverPath = path.join(paintingDir, coverFileName(idx))
+        // 이전 시도에서 이미 정규화해둔 사진은 건너뛴다(이어받기).
         if (await fileExists(coverPath)) {
           sendLog(t('log.imageSkip', { idx }))
           sendProgress({ phase: 'item', kind: 'image', index: idx, total: imageTotal, percent: 100, status: 'done' })
           continue
         }
-      // 실제 네트워크 요청을 하는 사진들 사이에만 간격을 둔다(건너뛴 것 사이엔 대기 없음).
-      if (imageRequests > 0) await sleep(IMAGE_REQUEST_INTERVAL_MS + Math.floor(Math.random() * 300))
-      imageRequests++
         sendLog(t('log.imageDownloading', { idx }))
         sendProgress({ phase: 'item', kind: 'image', index: idx, total: imageTotal, percent: 10, status: 'running' })
         let buf: Buffer
@@ -551,22 +556,31 @@ ipcMain.handle('rp:install:start', async (): Promise<{ resourcepackPath: string
           // 이미 받은 사진은 건너뛰고 이어받는다는 안내를 덧붙인다.
           const msg = /429/.test(rawMsg) ? `${rawMsg} — ${t('errors.imageRateLimitHint')}` : rawMsg
           sendProgress({ phase: 'item', kind: 'image', index: idx, total: imageTotal, percent: 0, status: 'error', message: msg })
-        throw new Error(t('errors.imageDownloadFailed', { idx, message: msg }))
+          if (!imageError) imageError = new Error(t('errors.imageDownloadFailed', { idx, message: msg }))
+          return
         }
-      throwIfCancelled()
+        if (state.cancelRequested || imageError) return
         sendProgress({ phase: 'item', kind: 'image', index: idx, total: imageTotal, percent: 60, status: 'running' })
-      const outPath = coverPath
         try {
-        await normalizeToCover(buf, outPath)
+          await normalizeToCover(buf, coverPath)
         } catch (err) {
           // 변환 중 부분 생성된 PNG 제거(이어받기 시 완성본 오인 방지).
           await fsp.rm(coverPath, { force: true }).catch(() => {})
           sendProgress({ phase: 'item', kind: 'image', index: idx, total: imageTotal, percent: 0, status: 'error', message: (err as Error).message })
-        throw new Error(t('errors.imageNormalizeFailed', { idx, message: (err as Error).message }))
+          if (!imageError) imageError = new Error(t('errors.imageNormalizeFailed', { idx, message: (err as Error).message }))
+          return
         }
-      sendLog(t('log.imageDone', { idx, name: path.basename(outPath) }))
+        sendLog(t('log.imageDone', { idx, name: path.basename(coverPath) }))
         sendProgress({ phase: 'item', kind: 'image', index: idx, total: imageTotal, percent: 100, status: 'done' })
       }
+    }
+
+    const imageWorkerCount = Math.min(IMAGE_CONCURRENCY_CAP, Math.max(1, imageTotal), Math.max(concurrency, 4))
+    const imageWorkers: Promise<void>[] = []
+    for (let w = 0; w < imageWorkerCount; w++) imageWorkers.push(imageWorker())
+    await Promise.all(imageWorkers)
+    throwIfCancelled()
+    if (imageError) throw imageError
 
     // 2-4. 베이스 리소스팩 다운로드 (있을 때만)
     throwIfCancelled()
@@ -688,8 +702,37 @@ app.whenReady().then(() => {
   })
 })
 
+// 종료 시 임시 파일(.temp) 정리. 예전엔 window-all-closed 에서 fsp.rm 을 fire-and-forget
+// 으로 호출하고 곧바로 app.quit() 해서, 삭제가 끝나기 전에 프로세스가 죽어 미리 받아둔
+// 내용이 남곤 했다. 또 '재시도 중' 이면 yt-dlp/ffmpeg 자식이 파일을 잠가 삭제가 실패한다.
+// → 자식을 먼저 죽여 잠금을 풀고, 삭제가 끝날 때까지 종료를 미룬 뒤 실제로 종료한다.
+let rpExitCleanupDone = false
+async function cleanupTempOnExit(): Promise<void> {
+  state.cancelRequested = true
+  for (const child of state.activeChildren) {
+    try { if (!child.killed) child.kill() } catch { /* noop */ }
+  }
+  const tempDir = path.join(getMcCustomDir(), '.temp')
+  // 자식 종료로 파일 잠금이 풀릴 시간을 주며 몇 번 재시도.
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await new Promise((r) => setTimeout(r, attempt === 0 ? 200 : 400))
+    try {
+      await fsp.rm(tempDir, { recursive: true, force: true })
+      if (!fs.existsSync(tempDir)) return
+    } catch { /* 잠금 등 — 다음 시도 */ }
+  }
+}
+
+app.on('before-quit', (event) => {
+  if (rpExitCleanupDone) return
+  event.preventDefault()
+  void cleanupTempOnExit().finally(() => {
+    rpExitCleanupDone = true
+    app.quit()
+  })
+})
+
 app.on('window-all-closed', () => {
-  // 강제 종료 시에도 임시 파일은 정리.
-  fsp.rm(path.join(getMcCustomDir(), '.temp'), { recursive: true, force: true }).catch(() => {})
+  // app.quit() → before-quit 에서 임시 파일을 정리한 뒤 실제 종료.
   if (process.platform !== 'darwin') app.quit()
 })

src/installer-rp/music.ts

@@ -38,6 +38,14 @@ export function downloadMusicTrack(opts: DownloadMusicOptions): Promise<string>
       // 단일 파일이 아니라 HLS/DASH fragmented 스트림일 때 청크를 병렬로.
       // 일반 progressive 다운로드에는 영향 없음.
       '--concurrent-fragments', '5',
+      // 유튜브가 미디어 스트림에 간헐적으로 403(Forbidden) 을 준다(특히 두 번째 곡부터
+      // throttle/클라이언트 이슈). yt-dlp 가 스스로 재시도·재추출하도록 해서 한 번의
+      // 403 으로 곡 전체가 실패하지 않게 한다.
+      '--retries', '10',
+      '--fragment-retries', '10',
+      '--extractor-retries', '3',
+      '--retry-sleep', 'http:exp=1:30',
+      '--socket-timeout', '30',
       // 진행률 표시 안정화 (yt-dlp 가 \r 대신 새 줄로 출력).
       '--newline',
       '--extract-audio',

src/installer/main.ts

@@ -109,29 +109,61 @@ process.on('unhandledRejection', (reason) => {
   try { sendLog(t('log.internalError', { message: reason instanceof Error ? reason.message : String(reason) })) } catch {}
 })
 
-function fetchBuffer(url: string): Promise<Buffer> {
+// 너무 빠르게/자주 요청해 생기는 일시적 오류(429 Too Many Requests, 5xx, 네트워크
+// 끊김/타임아웃 등)는 잠깐 쉬고 몇 번 다시 시도한다. 403 도 일부 CDN 이 rate-limit 에
+// 쓰므로 포함. 그 외 4xx(404 등)나 재시도 소진 시에는 그대로 실패.
+const DOWNLOAD_TRANSIENT_CODES = new Set([403, 408, 425, 429, 500, 502, 503, 504])
+const DOWNLOAD_MAX_RETRIES = 3
+const DOWNLOAD_MAX_BACKOFF_MS = 30000
+
+/** Retry-After 헤더(초 또는 HTTP-date) → 대기 ms. 못 읽으면 null. */
+function parseRetryAfterMs(h: string | string[] | undefined): number | null {
+  if (!h) return null
+  const v = Array.isArray(h) ? h[0] : h
+  const secs = Number(v)
+  if (Number.isFinite(secs)) return Math.min(DOWNLOAD_MAX_BACKOFF_MS, Math.max(0, secs * 1000))
+  const date = Date.parse(v)
+  if (!Number.isNaN(date)) return Math.min(DOWNLOAD_MAX_BACKOFF_MS, Math.max(0, date - Date.now()))
+  return null
+}
+
+function fetchBuffer(url: string, redirects = 0, attempt = 0): Promise<Buffer> {
   return new Promise((resolve, reject) => {
     const target = new URL(url)
     const transport = target.protocol === 'https:' ? https : http
+    const retryLater = (headerDelay: number | null, reason: string): void => {
+      const backoff = Math.min(DOWNLOAD_MAX_BACKOFF_MS, 1000 * 2 ** attempt) + Math.floor(Math.random() * 500)
+      const delay = headerDelay ?? backoff
+      sendLog(t('log.downloadRetry', { reason, attempt: attempt + 1, secs: Math.ceil(delay / 1000) }))
+      sleep(delay).then(() => fetchBuffer(url, redirects, attempt + 1).then(resolve, reject))
+    }
     const request = transport.get(target, { timeout: 30000 }, (response) => {
-      if (response.statusCode === 301 || response.statusCode === 302) {
-        const redirect = response.headers.location
-        if (redirect) {
+      const code = response.statusCode ?? 0
+      if ((code === 301 || code === 302 || code === 303 || code === 307 || code === 308) && response.headers.location) {
         response.resume()
-          fetchBuffer(new URL(redirect, target).toString()).then(resolve, reject)
+        if (redirects > 8) { reject(new Error(`HTTP ${code} (too many redirects)`)); return }
+        fetchBuffer(new URL(response.headers.location, target).toString(), redirects + 1, attempt).then(resolve, reject)
         return
       }
-      }
-      if ((response.statusCode ?? 0) >= 400) {
+      if (DOWNLOAD_TRANSIENT_CODES.has(code) && attempt < DOWNLOAD_MAX_RETRIES) {
         response.resume()
-        reject(new Error(`HTTP ${response.statusCode}`))
+        retryLater(parseRetryAfterMs(response.headers['retry-after']), `HTTP ${code}`)
+        return
+      }
+      if (code >= 400) {
+        response.resume()
+        reject(new Error(`HTTP ${code}`))
         return
       }
       const chunks: Buffer[] = []
       response.on('data', (chunk: Buffer) => chunks.push(chunk))
       response.on('end', () => resolve(Buffer.concat(chunks)))
     })
-    request.on('error', reject)
+    request.on('error', (err) => {
+      // 연결 끊김/리셋 등 네트워크 오류도 몇 번은 재시도.
+      if (attempt < DOWNLOAD_MAX_RETRIES) { retryLater(null, (err as Error).message); return }
+      reject(err)
+    })
     request.on('timeout', () => request.destroy(new Error(t('errors.requestTimeout'))))
   })
 }
@@ -334,42 +366,88 @@ function jdkHomesUnder(parent: string): string[] {
   return out
 }
 
-/**
- * 컴퓨터에 설치된 JDK 홈 목록을 우선순위대로 모은다(중복 제거).
- * 순서: ① 기본 자바 설치 위치 C:\Program Files\Java → ② 환경변수(JAVA_HOME/JDK_HOME)
- *       → ③ 설치기 자동 설치 위치(.mc_custom/jdk, 구버전 %APPDATA%/jdk 호환).
- */
-function collectJdkHomes(): string[] {
-  const homes: string[] = []
-  const push = (h: string): void => {
-    if (h && !homes.some((x) => x.toLowerCase() === h.toLowerCase())) homes.push(h)
+interface JdkEntry { home: string; major: number }
+
+/** 홈 목록 → {home, major} 목록(중복/버전0 제거). */
+function homesToEntries(homes: string[]): JdkEntry[] {
+  const javaName = process.platform === 'win32' ? 'java.exe' : 'java'
+  const seen = new Set<string>()
+  const out: JdkEntry[] = []
+  for (const home of homes) {
+    const key = home.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    const major = getJavaMajor(path.join(home, 'bin', javaName))
+    if (major > 0) out.push({ home, major })
   }
-  for (const h of jdkHomesUnder('C:\\Program Files\\Java')) push(h)
-  for (const env of [process.env.JAVA_HOME, process.env.JDK_HOME]) {
-    if (env) push(resolveJdkHome(env))
-  }
-  for (const base of [installerJdkRoot(), path.join(getAppDataDir(), 'jdk')]) {
-    for (const h of jdkHomesUnder(base)) push(h)
-  }
-  return homes
+  return out
 }
 
-// 권장 JDK 를 우선 찾는다. C:\Program Files\Java → 환경변수 → 설치기 자동설치 위치를
-// 훑어, ① 권장 버전과 정확히 일치하는 JDK 가 있으면 그걸 쓰고(match=true),
-// ② 없으면 가장 높은 버전을 대신 고르되 "권장과 다름"(match=false)으로 표시해 렌더러가
-//    경고를 띄우게 한다. ③ 아무 JDK 도 없으면 not found → 자동 설치 유도.
+/** 설치기 자동 설치 위치(.mc_custom/jdk, 구버전 %APPDATA%/jdk 호환)의 JDK 들. */
+function mcCustomJdkEntries(): JdkEntry[] {
+  const homes: string[] = []
+  for (const base of [installerJdkRoot(), path.join(getAppDataDir(), 'jdk')]) {
+    homes.push(...jdkHomesUnder(base))
+  }
+  return homesToEntries(homes)
+}
+
+/** 환경변수(JAVA_HOME/JDK_HOME)에 등록된 JDK 들. */
+function envJdkEntries(): JdkEntry[] {
+  const homes: string[] = []
+  for (const env of [process.env.JAVA_HOME, process.env.JDK_HOME]) {
+    if (env) {
+      const h = resolveJdkHome(env)
+      if (h) homes.push(h)
+    }
+  }
+  return homesToEntries(homes)
+}
+
+/** 기본 자바 설치 위치 C:\Program Files\Java 아래의 JDK 들. */
+function programFilesJdkEntries(): JdkEntry[] {
+  return homesToEntries(jdkHomesUnder('C:\\Program Files\\Java'))
+}
+
+// JDK 탐색 우선순위(요청 사양):
+//   ① .mc_custom/jdk(설치기가 설치해둔 위치)가 있으면 먼저 사용 — 권장 버전이면 그대로,
+//      혹시 다른 버전이면 경고(match=false).
+//   ② 환경변수(JAVA_HOME/JDK_HOME) 가 권장 버전이면 사용.
+//   ③ 기본 폴더 C:\Program Files\Java 에 권장 버전이 있으면 사용.
+//   ④ 없으면 환경변수 자바로 폴백하고 "권장과 다름" 경고(match=false).
+//      (환경변수 자바도 없으면 Program Files 자바로 폴백, 그것도 없으면 not found → 자동 설치 유도.)
 ipcMain.handle('jdk:detect', async (_event, recommendedInput?: number) => {
   const required = normalizeRecommendedJdk(recommendedInput)
-  const javaName = process.platform === 'win32' ? 'java.exe' : 'java'
-  const found = collectJdkHomes()
-    .map((home) => ({ home, major: getJavaMajor(path.join(home, 'bin', javaName)) }))
-    .filter((x) => x.major > 0)
+  const recommended = (entries: JdkEntry[]): JdkEntry | undefined => entries.find((e) => e.major === required)
+  const best = (entries: JdkEntry[]): JdkEntry => entries.slice().sort((a, b) => b.major - a.major)[0]
 
-  const exact = found.find((x) => x.major === required)
-  if (exact) return { found: true, path: exact.home, major: required, match: true }
-  if (found.length > 0) {
-    const best = found.slice().sort((a, b) => b.major - a.major)[0]
-    return { found: true, path: best.home, major: best.major, match: false }
+  // ① .mc_custom/jdk 우선.
+  const mc = mcCustomJdkEntries()
+  if (mc.length > 0) {
+    const rec = recommended(mc)
+    if (rec) return { found: true, path: rec.home, major: required, match: true }
+    const b = best(mc)
+    return { found: true, path: b.home, major: b.major, match: false }
+  }
+
+  // ② 환경변수 JDK 가 권장 버전이면 사용.
+  const env = envJdkEntries()
+  const envRec = recommended(env)
+  if (envRec) return { found: true, path: envRec.home, major: required, match: true }
+
+  // ③ 기본 폴더(Program Files\Java)에 권장 버전이 있으면 사용.
+  const pf = programFilesJdkEntries()
+  const pfRec = recommended(pf)
+  if (pfRec) return { found: true, path: pfRec.home, major: required, match: true }
+
+  // ④ 폴백: 환경변수 자바 → (없으면) Program Files 자바 + 경고.
+  if (env.length > 0) {
+    const b = best(env)
+    return { found: true, path: b.home, major: b.major, match: false }
+  }
+  if (pf.length > 0) {
+    const b = best(pf)
+    return { found: true, path: b.home, major: b.major, match: false }
   }
   return { found: false, path: '', major: required, match: false }
 })

src/server/routes/op.ts

@@ -28,6 +28,7 @@ import {
 } from '../../shared/store.js'
 import { hashPassword, isHashed, verifyPassword } from '../password.js'
 import { fetchReleaseVersions } from '../../shared/mojang.js'
+import { fetchJdkAvailability, fetchJdkReleaseNames } from '../../shared/jdkVersions.js'
 import { fetchPlaylistEntries, fetchVideoMeta, YtDlpUnavailableError } from '../youtube.js'
 import { requireAuth } from '../middleware/auth.js'
 import type { PackDefinition, PackList } from '../../shared/types.js'
@@ -196,6 +197,31 @@ opRouter.get('/op/dashboard/:packName', requireAuth, async (req, res, next) => {
   }
 })
 
+// ─── /op/jdk-versions ───────────────────────────────────────────────────
+// Adoptium(Temurin) 에서 실제 배포되는 JDK 메이저 목록을 프록시(브라우저 직접 호출은
+// CORS 로 막힘). 편집기의 "권장 JDK" 드롭다운을 이 결과로 채운다.
+opRouter.get('/op/jdk-versions', requireAuth, async (_req, res, next) => {
+  try {
+    res.json(await fetchJdkAvailability())
+  } catch (error) {
+    next(error)
+  }
+})
+
+// 특정 메이저의 상세 릴리스 이름(GA + EA 스냅샷). "자세히 보기" 에서 사용.
+opRouter.get('/op/jdk-versions/:major', requireAuth, async (req, res, next) => {
+  try {
+    const major = Number(req.params.major)
+    if (!Number.isInteger(major) || major < 8 || major > 99) {
+      res.status(400).json({ error: 'invalid major' })
+      return
+    }
+    res.json(await fetchJdkReleaseNames(major))
+  } catch (error) {
+    next(error)
+  }
+})
+
 // ─── /op/list ──────────────────────────────────────────────────────────
 // 음악퀴즈를 카드 한 줄로 표시. 카드 클릭 → /op/list/:packName
 opRouter.get('/op/list', requireAuth, async (req, res, next) => {

src/shared/jdkVersions.ts

@@ -0,0 +1,118 @@
+import https from 'node:https'
+
+// Adoptium(Temurin) API 로부터 실제 배포되는 JDK 버전을 가져온다. 설치기가 이 벤더를
+// 쓰므로 사이트의 "권장 JDK" 목록도 같은 소스에서 채운다(하드코딩 금지). 네트워크
+// 실패 시에는 정적 폴백을 돌려줘 편집기가 항상 동작하도록 한다.
+
+const AVAILABLE_URL = 'https://api.adoptium.net/v3/info/available_releases'
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000 // 6시간
+
+const FALLBACK_MAJORS = [8, 11, 17, 21, 25]
+const FALLBACK_LTS = [8, 11, 17, 21, 25]
+
+export interface JdkAvailability {
+  /** 배포되는 모든 메이저(예: 8,11,17,21,25,26). 내림차순. */
+  available: number[]
+  /** LTS 메이저만(예: 8,11,17,21,25). 내림차순. */
+  lts: number[]
+  mostRecentLts: number
+  mostRecentFeature: number
+}
+
+export interface JdkReleaseNames {
+  major: number
+  /** 정식(GA) 릴리스 이름들(예: jdk-25.0.3+9). */
+  ga: string[]
+  /** 개발 스냅샷(EA) 릴리스 이름들(예: jdk-25.0.4+6-ea-beta). */
+  ea: string[]
+}
+
+let availCache: { data: JdkAvailability; at: number } | null = null
+const releaseNamesCache = new Map<number, { data: JdkReleaseNames; at: number }>()
+
+function fetchJson<T>(url: string): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, { timeout: 8000, headers: { accept: 'application/json' } }, (response) => {
+      const code = response.statusCode ?? 0
+      if (code !== 200) {
+        response.resume()
+        reject(new Error(`Adoptium HTTP ${code}`))
+        return
+      }
+      const chunks: Buffer[] = []
+      response.on('data', (c: Buffer) => chunks.push(c))
+      response.on('end', () => {
+        try {
+          resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')) as T)
+        } catch (error) {
+          reject(error as Error)
+        }
+      })
+    })
+    request.on('error', reject)
+    request.on('timeout', () => request.destroy(new Error('Adoptium timeout')))
+  })
+}
+
+const sortDesc = (nums: number[]): number[] => [...new Set(nums)].sort((a, b) => b - a)
+
+export async function fetchJdkAvailability(): Promise<JdkAvailability> {
+  if (availCache && Date.now() - availCache.at < CACHE_TTL_MS) return availCache.data
+  try {
+    const raw = await fetchJson<{
+      available_releases?: number[]
+      available_lts_releases?: number[]
+      most_recent_lts?: number
+      most_recent_feature_release?: number
+    }>(AVAILABLE_URL)
+    const available = sortDesc(
+      (Array.isArray(raw.available_releases) ? raw.available_releases : FALLBACK_MAJORS).filter((n) => Number.isInteger(n))
+    )
+    const lts = sortDesc(
+      (Array.isArray(raw.available_lts_releases) ? raw.available_lts_releases : FALLBACK_LTS).filter((n) => Number.isInteger(n))
+    )
+    const data: JdkAvailability = {
+      available,
+      lts,
+      mostRecentLts: Number(raw.most_recent_lts) || (lts[0] ?? 21),
+      mostRecentFeature: Number(raw.most_recent_feature_release) || (available[0] ?? 25)
+    }
+    availCache = { data, at: Date.now() }
+    return data
+  } catch {
+    return (
+      availCache?.data ?? {
+        available: sortDesc(FALLBACK_MAJORS),
+        lts: sortDesc(FALLBACK_LTS),
+        mostRecentLts: 25,
+        mostRecentFeature: 25
+      }
+    )
+  }
+}
+
+async function fetchReleaseNames(major: number, type: 'ga' | 'ea'): Promise<string[]> {
+  const url =
+    `https://api.adoptium.net/v3/assets/feature_releases/${major}/${type}` +
+    '?architecture=x64&image_type=jdk&os=windows&vendor=eclipse&page_size=10'
+  try {
+    const arr = await fetchJson<Array<{ release_name?: string }>>(url)
+    if (!Array.isArray(arr)) return []
+    const names: string[] = []
+    for (const r of arr) {
+      if (typeof r?.release_name === 'string' && !names.includes(r.release_name)) names.push(r.release_name)
+    }
+    return names
+  } catch {
+    return []
+  }
+}
+
+export async function fetchJdkReleaseNames(major: number): Promise<JdkReleaseNames> {
+  const cached = releaseNamesCache.get(major)
+  if (cached && Date.now() - cached.at < CACHE_TTL_MS) return cached.data
+  const [ga, ea] = await Promise.all([fetchReleaseNames(major, 'ga'), fetchReleaseNames(major, 'ea')])
+  const data: JdkReleaseNames = { major, ga, ea }
+  releaseNamesCache.set(major, { data, at: Date.now() })
+  return data
+}

src/shared/store.ts

@@ -80,17 +80,21 @@ function sanitizeFolderName(input: unknown): string {
 const ALLOWED_LOADERS: LoaderType[] = ['vanilla', 'forge', 'fabric', 'neoforge']
 
 /**
- * 사이트에서 고를 수 있고 설치기가 자동 설치할 수 있는 JDK 메이저 버전 목록(LTS).
+ * 편집기 드롭다운의 정적 폴백 목록(LTS). 실제 목록은 Adoptium API 에서 가져오며,
+ * 네트워크 실패 시에만 이 값을 쓴다.
  * 마인크래프트 버전대별: 8(구버전) / 11(1.17) / 17(1.18~1.20.4) / 21(1.20.5~) / 25(최신).
  */
 export const SUPPORTED_JDK_MAJORS: number[] = [8, 11, 17, 21, 25]
 /** recommendedJdk 미지정/이상값일 때의 기본 권장 버전. */
 export const DEFAULT_JDK_MAJOR = 25
 
-/** 입력값을 허용된 JDK 메이저로 보정. 목록 밖이면 기본값. */
+/**
+ * 입력값을 JDK 메이저로 보정. 특정 목록에 얽매이지 않고 실제 배포되는 자바 메이저
+ * 범위(8~99)면 허용하고, 벗어나면 기본값. (목록은 Adoptium 에서 동적으로 온다.)
+ */
 export function normalizeRecommendedJdk(input: unknown): number {
   const n = Math.floor(Number(input))
-  return SUPPORTED_JDK_MAJORS.includes(n) ? n : DEFAULT_JDK_MAJOR
+  return Number.isFinite(n) && n >= 8 && n <= 99 ? n : DEFAULT_JDK_MAJOR
 }
 
 export function normalizePackDefinition(input: Partial<PackDefinition> & Record<string, unknown>): PackDefinition {

views/op/editor.ejs

@@ -82,11 +82,13 @@
         </label>
         <label>
           <span><%= t('editor.recommendedJdk') %></span>
-          <select name="recommendedJdk" required>
-            <% jdkOptions.forEach(function (major) { %>
-              <option value="<%= major %>" <%= major === pack.recommendedJdk ? 'selected' : '' %>>Java <%= major %></option>
-            <% }) %>
+          <select name="recommendedJdk" id="recommendedJdk" data-current="<%= pack.recommendedJdk %>" required>
+            <option value="<%= pack.recommendedJdk %>" selected>Java <%= pack.recommendedJdk %></option>
           </select>
+          <label class="muted" style="font-weight:normal;display:flex;align-items:center;gap:6px;margin-top:4px;">
+            <input type="checkbox" id="jdkShowDetails" style="width:auto;" /> <%= t('editor.jdkShowDetails') %>
+          </label>
+          <div id="jdkDetails" class="muted" hidden style="margin-top:4px;font-size:12px;line-height:1.6;word-break:break-all;"></div>
           <small class="muted"><%= t('editor.recommendedJdkHint') %></small>
         </label>
         <label>
@@ -135,6 +137,83 @@
     function formatLoaderLoadFailed(message) {
       return I18N.loaderLoadFailedPrefix.replace('__M__', message)
     }
+    var JDK = {
+      current: <%= pack.recommendedJdk %>,
+      fallback: <%- JSON.stringify(jdkOptions) %>,
+      detailsGa: <%- JSON.stringify(t('editor.jdkDetailsGa')) %>,
+      detailsEa: <%- JSON.stringify(t('editor.jdkDetailsEa')) %>,
+      detailsLoading: <%- JSON.stringify(t('common.loading')) %>,
+      detailsNone: <%- JSON.stringify(t('editor.jdkDetailsNone')) %>,
+      ltsSuffix: <%- JSON.stringify(t('editor.jdkLtsSuffix')) %>
+    }
+  </script>
+  <script>
+    (function () {
+      var sel = document.getElementById('recommendedJdk')
+      var details = document.getElementById('jdkDetails')
+      var toggle = document.getElementById('jdkShowDetails')
+      if (!sel || !toggle) return
+      var current = Number(sel.getAttribute('data-current')) || JDK.current
+      var avail = null // { available:[], lts:[] }
+
+      function rebuild() {
+        var availList, ltsList
+        if (avail) { availList = avail.available; ltsList = avail.lts }
+        else { availList = JDK.fallback.slice().sort(function (a, b) { return b - a }); ltsList = availList }
+        var ltsSet = {}
+        ltsList.forEach(function (m) { ltsSet[m] = true })
+        var list = toggle.checked ? availList.slice() : ltsList.slice()
+        if (list.indexOf(current) < 0) list = [current].concat(list)
+        var seen = {}, html = ''
+        list.forEach(function (m) {
+          if (seen[m]) return
+          seen[m] = true
+          var label = 'Java ' + m + (ltsSet[m] ? JDK.ltsSuffix : '')
+          html += '<option value="' + m + '"' + (m === current ? ' selected' : '') + '>' + label + '</option>'
+        })
+        sel.innerHTML = html
+        sel.value = String(current)
+      }
+
+      function escHtml(s) {
+        return String(s).replace(/[&<>"']/g, function (c) {
+          return c === '&' ? '&amp;' : c === '<' ? '&lt;' : c === '>' ? '&gt;' : c === '"' ? '&quot;' : '&#39;'
+        })
+      }
+      function detailRow(label, names) {
+        return '<div><strong>' + escHtml(label) + ':</strong> ' +
+          names.slice(0, 6).map(escHtml).join(', ') + '</div>'
+      }
+      function loadDetails(major) {
+        details.hidden = false
+        details.textContent = JDK.detailsLoading
+        fetch('/op/jdk-versions/' + major)
+          .then(function (r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.json() })
+          .then(function (d) {
+            // release_name 은 외부 API 값이라 반드시 escape 후 삽입(관리 페이지 XSS 방지).
+            var html = ''
+            if (d.ga && d.ga.length) html += detailRow(JDK.detailsGa, d.ga)
+            if (d.ea && d.ea.length) html += detailRow(JDK.detailsEa, d.ea)
+            details.innerHTML = html || escHtml(JDK.detailsNone)
+          })
+          .catch(function () { details.textContent = JDK.detailsNone })
+      }
+
+      sel.addEventListener('change', function () {
+        current = Number(sel.value)
+        if (toggle.checked) loadDetails(current)
+      })
+      toggle.addEventListener('change', function () {
+        rebuild()
+        if (toggle.checked) loadDetails(current)
+        else { details.hidden = true; details.innerHTML = '' }
+      })
+
+      fetch('/op/jdk-versions')
+        .then(function (r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.json() })
+        .then(function (d) { avail = d; rebuild() })
+        .catch(function () { rebuild() })
+    })()
   </script>
   <script>
     (function () {