미사용 이미지 자산 정리 배치 추가

backend/src/db.js

@@ -28,6 +28,14 @@ function serializeJson(value) {
   return JSON.stringify(value || [])
 }
 
+function collectUploadSrcsFromItems(items, bucket) {
+  for (const item of items || []) {
+    if (typeof item?.src === 'string' && item.src.startsWith('/uploads/')) {
+      bucket.add(item.src)
+    }
+  }
+}
+
 function mapUserRow(row) {
   if (!row) return null
   return {
@@ -64,6 +72,37 @@ function mapGameItemRow(row) {
   }
 }
 
+function mapImageAssetRow(row) {
+  if (!row) return null
+  return {
+    id: row.id,
+    contentHash: row.content_hash,
+    src: row.src || '',
+    mimeType: row.mime_type || 'image/webp',
+    byteSize: Number(row.byte_size || 0),
+    originalByteSize: Number(row.original_byte_size || 0),
+    width: Number(row.width || 0),
+    height: Number(row.height || 0),
+    createdAt: Number(row.created_at || 0),
+  }
+}
+
+function mapImageOptimizationJobRow(row) {
+  if (!row) return null
+  return {
+    id: row.id,
+    status: row.status,
+    sourceCategory: row.source_category || '',
+    targetDirectory: row.target_directory || '',
+    originalByteSize: Number(row.original_byte_size || 0),
+    optimizedByteSize: Number(row.optimized_byte_size || 0),
+    reusedAsset: !!row.reused_asset,
+    errorMessage: row.error_message || '',
+    queuedAt: Number(row.queued_at || 0),
+    startedAt: Number(row.started_at || 0),
+    finishedAt: Number(row.finished_at || 0),
+  }
+}
 function mapTierListRow(row) {
   if (!row) return null
   return {
@@ -270,6 +309,38 @@ async function ensureSchema() {
       ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
     `)
 
+    await query(`
+      CREATE TABLE IF NOT EXISTS image_assets (
+        id VARCHAR(64) PRIMARY KEY,
+        content_hash CHAR(64) NOT NULL UNIQUE,
+        src VARCHAR(255) NOT NULL UNIQUE,
+        mime_type VARCHAR(32) NOT NULL DEFAULT 'image/webp',
+        byte_size INT UNSIGNED NOT NULL,
+        original_byte_size INT UNSIGNED NOT NULL,
+        width INT UNSIGNED NOT NULL DEFAULT 0,
+        height INT UNSIGNED NOT NULL DEFAULT 0,
+        created_at BIGINT NOT NULL,
+        INDEX idx_image_assets_created_at (created_at)
+      ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+    `)
+
+    await query(`
+      CREATE TABLE IF NOT EXISTS image_optimization_jobs (
+        id VARCHAR(64) PRIMARY KEY,
+        status VARCHAR(20) NOT NULL DEFAULT 'queued',
+        source_category VARCHAR(40) NOT NULL DEFAULT '',
+        target_directory VARCHAR(40) NOT NULL DEFAULT '',
+        original_byte_size INT UNSIGNED NOT NULL DEFAULT 0,
+        optimized_byte_size INT UNSIGNED NOT NULL DEFAULT 0,
+        reused_asset TINYINT(1) NOT NULL DEFAULT 0,
+        error_message VARCHAR(255) NOT NULL DEFAULT '',
+        queued_at BIGINT NOT NULL,
+        started_at BIGINT NOT NULL DEFAULT 0,
+        finished_at BIGINT NOT NULL DEFAULT 0,
+        INDEX idx_image_optimization_jobs_status_queued (status, queued_at),
+        INDEX idx_image_optimization_jobs_finished_at (finished_at)
+      ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+    `)
     await query(`
       CREATE TABLE IF NOT EXISTS template_requests (
         id VARCHAR(64) PRIMARY KEY,
@@ -522,6 +593,118 @@ async function updateGameThumbnail(gameId, thumbnailSrc) {
   return findGameById(gameId)
 }
 
+async function findImageAssetByHash(contentHash) {
+  const rows = await query(
+    'SELECT id, content_hash, src, mime_type, byte_size, original_byte_size, width, height, created_at FROM image_assets WHERE content_hash = ? LIMIT 1',
+    [contentHash]
+  )
+  return mapImageAssetRow(rows[0])
+}
+
+async function createImageAsset({ id, contentHash, src, mimeType = "image/webp", byteSize, originalByteSize, width, height }) {
+  const createdAt = now()
+  await query(
+    'INSERT INTO image_assets (id, content_hash, src, mime_type, byte_size, original_byte_size, width, height, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    [id, contentHash, src, mimeType, byteSize, originalByteSize, width, height, createdAt]
+  )
+  return findImageAssetByHash(contentHash)
+}
+
+async function createImageOptimizationJob({ id, sourceCategory, targetDirectory, originalByteSize }) {
+  const queuedAt = now()
+  await query(
+    'INSERT INTO image_optimization_jobs (id, status, source_category, target_directory, original_byte_size, optimized_byte_size, reused_asset, error_message, queued_at, started_at, finished_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    [id, 'queued', sourceCategory || '', targetDirectory || '', originalByteSize || 0, 0, 0, '', queuedAt, 0, 0]
+  )
+  return findImageOptimizationJobById(id)
+}
+
+async function findImageOptimizationJobById(id) {
+  const rows = await query(
+    'SELECT id, status, source_category, target_directory, original_byte_size, optimized_byte_size, reused_asset, error_message, queued_at, started_at, finished_at FROM image_optimization_jobs WHERE id = ? LIMIT 1',
+    [id]
+  )
+  return mapImageOptimizationJobRow(rows[0])
+}
+
+async function updateImageOptimizationJobStatus({ id, status, optimizedByteSize = 0, reusedAsset = false, errorMessage = '', startedAt, finishedAt }) {
+  const fields = ['status = ?', 'optimized_byte_size = ?', 'reused_asset = ?', 'error_message = ?']
+  const params = [status, optimizedByteSize, reusedAsset ? 1 : 0, errorMessage.slice(0, 255)]
+
+  if (typeof startedAt === 'number') {
+    fields.push('started_at = ?')
+    params.push(startedAt)
+  }
+  if (typeof finishedAt === 'number') {
+    fields.push('finished_at = ?')
+    params.push(finishedAt)
+  }
+
+  params.push(id)
+  await query(`UPDATE image_optimization_jobs SET ${fields.join(', ')} WHERE id = ?`, params)
+  return findImageOptimizationJobById(id)
+}
+
+async function listRecentImageOptimizationJobs(limit = 20) {
+  const safeLimit = Math.max(1, Math.min(100, Number(limit) || 20))
+  const rows = await query(
+    `SELECT id, status, source_category, target_directory, original_byte_size, optimized_byte_size, reused_asset, error_message, queued_at, started_at, finished_at FROM image_optimization_jobs ORDER BY queued_at DESC LIMIT ${safeLimit}`
+  )
+  return rows.map(mapImageOptimizationJobRow)
+}
+
+async function listUnusedImageAssets({ limit = 100, minAgeHours = 24 } = {}) {
+  const safeLimit = Math.max(1, Math.min(500, Number(limit) || 100))
+  const safeMinAgeHours = Math.max(0, Number(minAgeHours) || 24)
+  const cutoff = now() - safeMinAgeHours * 60 * 60 * 1000
+
+  const assets = (await query(
+    `SELECT id, content_hash, src, mime_type, byte_size, original_byte_size, width, height, created_at FROM image_assets WHERE created_at <= ? ORDER BY created_at ASC LIMIT ${safeLimit}`,
+    [cutoff]
+  )).map(mapImageAssetRow)
+
+  if (!assets.length) return []
+
+  const referencedSrcs = new Set()
+
+  const [userRows, gameRows, gameItemRows, customItemRows, tierListRows, templateRequestRows] = await Promise.all([
+    query("SELECT avatar_src FROM users WHERE avatar_src <> ''"),
+    query("SELECT thumbnail_src FROM games WHERE thumbnail_src <> ''"),
+    query("SELECT src FROM game_items WHERE src <> ''"),
+    query("SELECT src FROM custom_items WHERE src <> ''"),
+    query("SELECT thumbnail_src, pool_json FROM tierlists"),
+    query("SELECT thumbnail_src_snapshot, items_json FROM template_requests"),
+  ])
+
+  for (const row of userRows) if (row.avatar_src) referencedSrcs.add(row.avatar_src)
+  for (const row of gameRows) if (row.thumbnail_src) referencedSrcs.add(row.thumbnail_src)
+  for (const row of gameItemRows) if (row.src) referencedSrcs.add(row.src)
+  for (const row of customItemRows) if (row.src) referencedSrcs.add(row.src)
+
+  for (const row of tierListRows) {
+    if (row.thumbnail_src) referencedSrcs.add(row.thumbnail_src)
+    collectUploadSrcsFromItems(parseJson(row.pool_json, []), referencedSrcs)
+  }
+
+  for (const row of templateRequestRows) {
+    if (row.thumbnail_src_snapshot) referencedSrcs.add(row.thumbnail_src_snapshot)
+    collectUploadSrcsFromItems(parseJson(row.items_json, []), referencedSrcs)
+  }
+
+  return assets.filter((asset) => !referencedSrcs.has(asset.src))
+}
+
+async function deleteImageAssets(ids) {
+  const uniqueIds = Array.from(new Set((ids || []).filter(Boolean)))
+  if (!uniqueIds.length) return []
+  const placeholders = uniqueIds.map(() => '?').join(', ')
+  const rows = await query(
+    `SELECT id, content_hash, src, mime_type, byte_size, original_byte_size, width, height, created_at FROM image_assets WHERE id IN (${placeholders})`,
+    uniqueIds
+  )
+  await query(`DELETE FROM image_assets WHERE id IN (${placeholders})`, uniqueIds)
+  return rows.map(mapImageAssetRow)
+}
 async function createGameItem({ id, gameId, src, label }) {
   const createdAt = now()
   await query('INSERT INTO game_items (id, game_id, src, label, created_at) VALUES (?, ?, ?, ?, ?)', [
@@ -1404,6 +1587,14 @@ module.exports = {
   getGameDetail,
   createGame,
   updateGameThumbnail,
+  findImageAssetByHash,
+  createImageAsset,
+  createImageOptimizationJob,
+  findImageOptimizationJobById,
+  updateImageOptimizationJobStatus,
+  listRecentImageOptimizationJobs,
+  listUnusedImageAssets,
+  deleteImageAssets,
   createGameItem,
   updateGameItemLabel,
   deleteGameItem,

backend/src/lib/image-storage.js

@@ -1,9 +1,21 @@
 const fs = require('fs/promises')
 const path = require('path')
+const crypto = require('crypto')
 const sharp = require('sharp')
 const { nanoid } = require('nanoid')
+const {
+  findImageAssetByHash,
+  createImageAsset,
+  createImageOptimizationJob,
+  updateImageOptimizationJobStatus,
+} = require('../db')
 
 const UPLOAD_ROOT = path.join(__dirname, '..', '..', 'uploads')
+const OPTIMIZED_DIR = 'assets'
+const OPTIMIZATION_CONCURRENCY = Math.max(1, Number(process.env.IMAGE_OPTIMIZATION_CONCURRENCY || 1))
+
+let activeCount = 0
+const pendingJobs = []
 
 function ensureImageMimeType(file) {
   return typeof file?.mimetype === 'string' && file.mimetype.startsWith('image/')
@@ -23,6 +35,129 @@ function createMemoryUpload(multer, { fileSize = 6 * 1024 * 1024, maxCount } = {
   })
 }
 
+function scheduleQueue() {
+  while (activeCount < OPTIMIZATION_CONCURRENCY && pendingJobs.length) {
+    const job = pendingJobs.shift()
+    activeCount += 1
+    processQueuedJob(job)
+      .then(job.resolve)
+      .catch(job.reject)
+      .finally(() => {
+        activeCount = Math.max(0, activeCount - 1)
+        scheduleQueue()
+      })
+  }
+}
+
+async function optimizeAndPersist({ file, width, height, fit, quality }) {
+  const { data, info } = await sharp(file.buffer, { failOn: 'none' })
+    .rotate()
+    .resize({
+      width,
+      height,
+      fit,
+      withoutEnlargement: true,
+    })
+    .webp({ quality })
+    .toBuffer({ resolveWithObject: true })
+
+  const contentHash = crypto.createHash('sha256').update(data).digest('hex')
+  const existing = await findImageAssetByHash(contentHash)
+  if (existing) {
+    return {
+      src: existing.src,
+      size: existing.byteSize,
+      originalSize: existing.originalByteSize,
+      width: existing.width,
+      height: existing.height,
+      contentHash: existing.contentHash,
+      reused: true,
+    }
+  }
+
+  const filename = String(Date.now()) + '-' + nanoid() + '.webp'
+  const absoluteDir = path.join(UPLOAD_ROOT, OPTIMIZED_DIR)
+  const absolutePath = path.join(absoluteDir, filename)
+  const src = '/uploads/' + OPTIMIZED_DIR + '/' + filename
+
+  await fs.mkdir(absoluteDir, { recursive: true })
+  await fs.writeFile(absolutePath, data)
+
+  try {
+    const asset = await createImageAsset({
+      id: nanoid(),
+      contentHash,
+      src,
+      mimeType: 'image/webp',
+      byteSize: data.length,
+      originalByteSize: file.size || file.buffer.length,
+      width: info.width || 0,
+      height: info.height || 0,
+    })
+
+    return {
+      src: asset.src,
+      size: asset.byteSize,
+      originalSize: asset.originalByteSize,
+      width: asset.width,
+      height: asset.height,
+      contentHash: asset.contentHash,
+      reused: false,
+    }
+  } catch (error) {
+    try {
+      await fs.unlink(absolutePath)
+    } catch (unlinkError) {
+      if (unlinkError?.code !== 'ENOENT') throw unlinkError
+    }
+
+    if (error?.code === 'ER_DUP_ENTRY') {
+      const asset = await findImageAssetByHash(contentHash)
+      if (asset) {
+        return {
+          src: asset.src,
+          size: asset.byteSize,
+          originalSize: asset.originalByteSize,
+          width: asset.width,
+          height: asset.height,
+          contentHash: asset.contentHash,
+          reused: true,
+        }
+      }
+    }
+
+    throw error
+  }
+}
+
+async function processQueuedJob(job) {
+  await updateImageOptimizationJobStatus({
+    id: job.jobId,
+    status: 'processing',
+    startedAt: Date.now(),
+  })
+
+  try {
+    const result = await optimizeAndPersist(job)
+    await updateImageOptimizationJobStatus({
+      id: job.jobId,
+      status: 'completed',
+      optimizedByteSize: result.size,
+      reusedAsset: result.reused,
+      finishedAt: Date.now(),
+    })
+    return result
+  } catch (error) {
+    await updateImageOptimizationJobStatus({
+      id: job.jobId,
+      status: 'failed',
+      errorMessage: error?.message || 'optimization_failed',
+      finishedAt: Date.now(),
+    })
+    throw error
+  }
+}
+
 async function writeOptimizedImage({
   file,
   directory,
@@ -43,29 +178,35 @@ async function writeOptimizedImage({
     throw error
   }
 
-  const { data, info } = await sharp(file.buffer, { failOn: 'none' })
-    .rotate()
-    .resize({
+  const jobId = nanoid()
+  await createImageOptimizationJob({
+    id: jobId,
+    sourceCategory: directory,
+    targetDirectory: OPTIMIZED_DIR,
+    originalByteSize: file.size || file.buffer.length,
+  })
+
+  return new Promise((resolve, reject) => {
+    pendingJobs.push({
+      jobId,
+      file,
+      directory,
       width,
       height,
       fit,
-      withoutEnlargement: true,
+      quality,
+      resolve: (result) => resolve({ ...result, directory }),
+      reject,
     })
-    .webp({ quality })
-    .toBuffer({ resolveWithObject: true })
-
-  const filename = String(Date.now()) + '-' + nanoid() + '.webp'
-  const absoluteDir = path.join(UPLOAD_ROOT, directory)
-  const absolutePath = path.join(absoluteDir, filename)
-  await fs.mkdir(absoluteDir, { recursive: true })
-  await fs.writeFile(absolutePath, data)
+    scheduleQueue()
+  })
+}
 
+function getImageOptimizationQueueState() {
   return {
-    src: '/uploads/' + directory + '/' + filename,
-    size: data.length,
-    originalSize: file.size || file.buffer.length,
-    width: info.width || 0,
-    height: info.height || 0,
+    concurrency: OPTIMIZATION_CONCURRENCY,
+    activeCount,
+    pendingCount: pendingJobs.length,
   }
 }
 
@@ -73,4 +214,5 @@ module.exports = {
   createMemoryUpload,
   ensureImageMimeType,
   writeOptimizedImage,
+  getImageOptimizationQueueState,
 }

backend/src/routes/admin.js

@@ -30,6 +30,8 @@ const {
   adminUpdateUser,
   adminUpdateUserPassword,
   adminDeleteUser,
+  listUnusedImageAssets,
+  deleteImageAssets,
 } = require('../db')
 const { requireAdmin } = require('../middleware/auth')
 const { createMemoryUpload, writeOptimizedImage } = require('../lib/image-storage')
@@ -206,6 +208,46 @@ router.get('/template-requests', requireAdmin, async (req, res) => {
   res.json({ requests })
 })
 
+router.get('/image-assets/orphans', requireAdmin, async (req, res) => {
+  const schema = z.object({
+    limit: z.coerce.number().int().min(1).max(500).optional().default(100),
+    minAgeHours: z.coerce.number().min(0).max(24 * 365).optional().default(24),
+  })
+  const parsed = schema.safeParse(req.query)
+  if (!parsed.success) return res.status(400).json({ error: 'bad_request' })
+
+  const assets = await listUnusedImageAssets(parsed.data)
+  res.json({ assets })
+})
+
+async function removeImageAssetFiles(assets) {
+  await Promise.all(
+    (assets || []).map(async (asset) => {
+      if (!asset?.src || !asset.src.startsWith('/uploads/')) return
+      const absolutePath = path.join(__dirname, '..', '..', asset.src.replace(/^\//, ''))
+      try {
+        await fs.unlink(absolutePath)
+      } catch (error) {
+        if (error?.code !== 'ENOENT') throw error
+      }
+    })
+  )
+}
+
+router.post('/image-assets/cleanup', requireAdmin, async (req, res) => {
+  const schema = z.object({
+    limit: z.coerce.number().int().min(1).max(500).optional().default(100),
+    minAgeHours: z.coerce.number().min(0).max(24 * 365).optional().default(24),
+  })
+  const parsed = schema.safeParse(req.body)
+  if (!parsed.success) return res.status(400).json({ error: 'bad_request' })
+
+  const assets = await listUnusedImageAssets(parsed.data)
+  const deleted = await deleteImageAssets(assets.map((asset) => asset.id))
+  await removeImageAssetFiles(deleted)
+  res.json({ deletedCount: deleted.length, assets: deleted })
+})
+
 async function removeCustomItemFiles(items) {
   await Promise.all(
     items.map(async (item) => {
@@ -221,33 +263,18 @@ async function removeCustomItemFiles(items) {
 }
 
 async function promoteCustomItemToGameItem({ customItem, gameId }) {
-  const originalName = path.basename(customItem.src || '')
-  const nextFilename = buildUploadFilename({ originalname: originalName })
-  const sourcePath = path.join(__dirname, '..', '..', customItem.src.replace(/^\//, ''))
-  const targetRelativePath = path.join('uploads', 'games', nextFilename)
-  const targetPath = path.join(__dirname, '..', '..', targetRelativePath)
-
-  await fs.copyFile(sourcePath, targetPath)
-
   return createGameItem({
     id: nanoid(),
     gameId,
-    src: `/${targetRelativePath.replace(/\\/g, '/')}`,
+    src: customItem.src || '',
     label: customItem.label,
   })
 }
 
 async function copyUploadIntoGameAsset(src) {
   if (typeof src !== 'string' || !src.startsWith('/uploads/')) return src || ''
-
-  const originalName = path.basename(src)
-  const nextFilename = buildUploadFilename({ originalname: originalName })
-  const sourcePath = path.join(__dirname, '..', '..', src.replace(/^\//, ''))
-  const targetRelativePath = path.join('uploads', 'games', nextFilename)
-  const targetPath = path.join(__dirname, '..', '..', targetRelativePath)
-
-  await fs.copyFile(sourcePath, targetPath)
-  return `/${targetRelativePath.replace(/\\/g, '/')}`
+  if (src.startsWith('/uploads/assets/')) return src
+  return src
 }
 
 function uniqueTierListPoolItems(tierList) {

docs/update.md

@@ -1,5 +1,20 @@
 # 업데이트 로그
 
+## 2026-03-31 v1.3.3
+- `image_assets` 참조를 전수 점검해 아무 곳에서도 사용하지 않는 최적화 이미지 자산만 추려내는 정리 배치 로직을 추가함.
+- 관리자용 미사용 자산 조회/정리 API를 추가해 오래된 고아 이미지 자산을 미리 확인하거나 실제로 삭제할 수 있도록 확장함.
+- 관리자 승격/템플릿 생성 과정은 기존 `/uploads/assets/` 자산을 그대로 재사용하도록 바꿔, 불필요한 복제 파일이 다시 생기지 않게 정리함.
+
+## 2026-03-31 v1.3.2
+- 업로드 최적화는 이제 백엔드 내부 대기열을 통해 처리되어, 다수 이미지가 한 번에 들어와도 설정된 동시성 안에서 순차적으로 안정적으로 변환되도록 정리함.
+- `image_optimization_jobs` 작업 기록 테이블을 추가해 queued/processing/completed/failed 상태와 원본·최적화 용량, 재사용 여부, 시작/종료 시각을 저장하도록 확장함.
+- 현재 라우트 응답 방식은 유지하면서도 내부적으로는 큐를 타도록 구조를 바꿔, 이후 관리자 대시보드와 작업 통계 화면을 바로 얹을 수 있는 기반을 마련함.
+
+## 2026-03-31 v1.3.1
+- 최적화된 WebP 결과물 기준으로 SHA-256 해시를 계산해, 같은 이미지가 다시 업로드되면 새 파일을 저장하지 않고 기존 자산을 재사용하도록 중복 이미지 해시 검사를 추가함.
+- 이미지 자산 메타데이터를 저장하는 `image_assets` 테이블을 도입해 파일 경로, 해시, 원본 대비 최적화 용량, 해상도를 함께 기록하도록 확장함.
+- 중복 업로드 경쟁 상황에서도 고유 해시 충돌을 안전하게 처리하고, 새 파일 저장에 실패하면 즉시 정리하도록 업로드 헬퍼를 보강함.
+
 ## 2026-03-31 v1.3.0
 - 백엔드 업로드 파이프라인을 메모리 기반으로 전환하고, 대표 썸네일·게임 썸네일·커스텀 아이템·게임 기본 아이템·아바타를 서버에서 즉시 WebP로 변환해 저장하도록 정리함.
 - 아이템 이미지는 최대 512px 규격으로 리사이즈하고, 티어표/게임 썸네일은 긴 변 기준 1280px 안쪽으로 최적화해 원본 이미지를 별도로 보관하지 않는 흐름으로 전환함.