v1.10.88 품질·보안 개선과 미디어 카탈로그 database 전환을 반영한다.

세션·로그인 제한, ZIP/업로드 스트리밍, CSP 최소 강제와 Report-Only, Playwright 격리 검증을 추가하고 미디어 목록을 reconcile 후 database 모드로 고정한다. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-22 11:05:40 +09:00
parent 9bc0f0a90e
commit de767095ba
116 changed files with 8128 additions and 2933 deletions
--- a/server/routes/admin/api/auth/login.post.js
+++ b/server/routes/admin/api/auth/login.post.js
@@ -6,6 +6,11 @@ import { getAdminUserByEmail, getMemberBootstrapState, touchUserActivity, upsert
 import { setMemberSession } from '../../../../utils/member-auth'
 import { getRuntimeEnvValue } from '../../../../utils/runtime-env'
 import { getClientIp } from '../../../../utils/request-ip'
+import {
+  assertLoginAttemptAllowed,
+  clearLoginAccountFailures,
+  recordLoginFailure
+} from '../../../../utils/login-attempt-limit'

 const loginSchema = z.object({
  email: z.string().email(),
@@ -64,6 +69,15 @@ export default defineEventHandler(async (event) => {
  }

  const body = parsedBody.data
+  const emailNorm = body.email.trim().toLowerCase()
+  const ip = getClientIp(event)
+  const attempt = {
+    scope: 'admin',
+    email: emailNorm,
+    ip
+  }
+
+  assertLoginAttemptAllowed(event, attempt)

  const adminUser = await getAdminUserByEmail(body.email) || await createBootstrapAdminUser(body)
  const passwordMatched = adminUser
@@ -71,23 +85,27 @@ export default defineEventHandler(async (event) => {
    : false

  if (!adminUser || !passwordMatched) {
+    recordLoginFailure(attempt)
    throw createError({
      statusCode: 401,
      message: '이메일 또는 비밀번호가 올바르지 않습니다.'
    })
  }

+  clearLoginAccountFailures(attempt)
  setAdminSession(event, {
    userId: adminUser.id,
-    email: adminUser.email
+    email: adminUser.email,
+    sessionVersion: adminUser.sessionVersion
  })
  setMemberSession(event, {
    userId: adminUser.id,
-    email: adminUser.email
+    email: adminUser.email,
+    sessionVersion: adminUser.sessionVersion
  })
  await touchUserActivity({
    userId: adminUser.id,
-    ip: getClientIp(event)
+    ip
  })

  return {
--- a/server/routes/admin/api/auth/me.get.js
+++ b/server/routes/admin/api/auth/me.get.js
@@ -17,7 +17,9 @@ export default defineEventHandler(async (event) => {
  const member = await getMemberForAdmin(session.userId)

  return {
-    ...session,
+    userId: session.userId,
+    email: session.email,
+    role: session.role,
    roleCode: member?.roleCode || 'admin',
    roleLabel: member?.role || '관리자'
  }
--- a/server/routes/admin/api/media.get.js
+++ b/server/routes/admin/api/media.get.js
@@ -1,5 +1,11 @@
 import { requireAdminSession } from '../../../utils/admin-auth'
 import { listMediaItems } from '../../../utils/media-library'
+import { getMediaCatalogMode } from '../../../utils/media-catalog-mode'
+import {
+  getMediaCatalogReadiness,
+  listMediaCatalogItems,
+  listPagedMediaCatalogItems
+} from '../../../repositories/media-catalog-repository'
 import {
  isPageCoverThumbnailUrl,
  isPostBodyThumbnailUrl,
@@ -172,7 +178,7 @@ const countMediaKinds = (items) => items.reduce((counts, item) => {
 * @param {Record<string, unknown>} query - 요청 쿼리
 * @returns {Object} 페이지 미디어 응답
 */
-const createPagedMediaResponse = (items, query) => {
+export const createPagedMediaResponse = (items, query) => {
  const tab = normalizeMediaTab(query.tab)
  const pageSize = normalizeMediaPageSize(query.pageSize)
  const requestedPage = Math.max(1, Number(query.page) || 1)
@@ -220,6 +226,17 @@ const createPagedMediaResponse = (items, query) => {
  }
 }

+/**
+ * 미디어 목록의 민감정보 없는 비교 수치를 만든다.
+ * @param {Array<Object>} items - 미디어 항목 목록
+ * @returns {{ count: number, bytes: number, kinds: Record<string, number> }} 비교 수치
+ */
+const createMediaComparisonSummary = (items) => ({
+  count: items.length,
+  bytes: items.reduce((total, item) => total + Number(item.size || 0), 0),
+  kinds: countMediaKinds(items)
+})
+
 /**
 * 관리자 미디어 목록 API
 * @param {import('h3').H3Event} event - 요청 이벤트
@@ -228,10 +245,53 @@ const createPagedMediaResponse = (items, query) => {
 export default defineEventHandler(async (event) => {
  requireAdminSession(event)

-  const items = await listMediaItems()
+  const mode = getMediaCatalogMode()
  const query = getQuery(event)
+  const paged = query.paged === '1' || query.paged === 'true'
+  let items

-  if (query.paged === '1' || query.paged === 'true') {
+  if (mode === 'database') {
+    try {
+      const readiness = await getMediaCatalogReadiness()
+
+      if (!readiness.ready) {
+        console.warn('[media-catalog] DB 카탈로그 준비 미완료, 파일시스템으로 대체', {
+          reason: readiness.reason
+        })
+        throw new Error('MEDIA_CATALOG_NOT_READY')
+      }
+
+      if (paged) {
+        return await listPagedMediaCatalogItems(query)
+      }
+
+      items = await listMediaCatalogItems()
+    } catch {
+      console.warn('[media-catalog] DB 목록 조회 실패, 파일시스템으로 대체')
+      items = await listMediaItems()
+    }
+  } else {
+    items = await listMediaItems()
+
+    if (mode === 'shadow') {
+      listMediaCatalogItems().then((catalogItems) => {
+        const filesystem = createMediaComparisonSummary(items)
+        const catalog = createMediaComparisonSummary(catalogItems)
+        console.info('[media-catalog] shadow 차이', {
+          count: catalog.count - filesystem.count,
+          bytes: catalog.bytes - filesystem.bytes,
+          kinds: Object.fromEntries(Object.keys(filesystem.kinds).map((kind) => [
+            kind,
+            Number(catalog.kinds[kind] || 0) - Number(filesystem.kinds[kind] || 0)
+          ]))
+        })
+      }).catch(() => {
+        console.warn('[media-catalog] shadow 비교 실패')
+      })
+    }
+  }
+
+  if (paged) {
    return createPagedMediaResponse(items, query)
  }

--- a/server/routes/admin/api/media/reconcile.post.js
+++ b/server/routes/admin/api/media/reconcile.post.js
@@ -0,0 +1,14 @@
+import { requireAdminSession } from '../../../../utils/admin-auth'
+import { reconcileMediaCatalog } from '../../../../repositories/media-catalog-repository'
+
+/**
+ * 관리자 수동 미디어 카탈로그 재동기화 API
+ * 파일을 삭제하거나 이동하지 않고 발견 파일 upsert와 누락 상태 표시만 수행한다.
+ * @param {import('h3').H3Event} event - 요청 이벤트
+ * @returns {Promise<Object>} 재동기화 비교 보고
+ */
+export default defineEventHandler(async (event) => {
+  requireAdminSession(event)
+
+  return reconcileMediaCatalog()
+})
--- a/server/routes/admin/api/media/thumbnail.post.js
+++ b/server/routes/admin/api/media/thumbnail.post.js
@@ -5,6 +5,7 @@ import {
  createPostBodyThumbnailForImageUrl,
  createPostThumbnailForImageUrl
 } from '../../../../utils/post-thumbnail-image.js'
+import { invalidateMediaItemsCache } from '../../../../utils/media-library.js'

 /**
 * 이미지 파생 파일 재생성 API
@@ -33,6 +34,8 @@ export default defineEventHandler(async (event) => {
    })
  }

+  invalidateMediaItemsCache()
+
  return {
    thumbnailUrl
  }
--- a/server/routes/admin/api/members/[id]/avatar.post.js
+++ b/server/routes/admin/api/members/[id]/avatar.post.js
@@ -4,6 +4,7 @@ import { getMemberForAdmin, updateMemberAvatarByAdmin } from '../../../../../rep
 import { removeManagedAvatarAsset } from '../../../../../utils/member-avatar'
 import { uploadMemberAvatarImage } from '../../../../../utils/member-avatar-upload'
 import { MEDIA_THUMBNAIL_ROOT, upsertMediaMetadataCategory } from '../../../../../utils/media-library'
+import { replaceMediaReferences } from '../../../../../repositories/media-catalog-repository'

 /**
 * 관리자 회원 썸네일 업로드 API
@@ -44,6 +45,13 @@ export default defineEventHandler(async (event) => {
  }

  await upsertMediaMetadataCategory(avatarUrl, MEDIA_THUMBNAIL_ROOT)
+  await replaceMediaReferences('user', memberId, {
+    avatarUrl
+  }, {
+    title: updated.username
+  }).catch(() => {
+    console.warn('[media-catalog] 회원 아바타 참조 갱신 실패')
+  })

  if (member.avatarUrl && member.avatarUrl !== avatarUrl) {
    await removeManagedAvatarAsset(member.avatarUrl)
--- a/server/routes/admin/api/posts/export-jobs/[fileId]/download.get.js
+++ b/server/routes/admin/api/posts/export-jobs/[fileId]/download.get.js
@@ -9,8 +9,9 @@ import {
 } from 'h3'
 import { requireAdminSession } from '../../../../../../utils/admin-auth'
 import { getReadyPostExportFile } from '../../../../../../repositories/post-export-repository'
+import { getUploadRoot } from '../../../../../../utils/upload-root'

-const uploadRoot = join(process.cwd(), 'public', 'uploads')
+const uploadRoot = getUploadRoot()

 /**
 * Export 파일 경로를 안전하게 해석한다.
--- a/server/routes/admin/api/posts/import.post.js
+++ b/server/routes/admin/api/posts/import.post.js
@@ -1,6 +1,10 @@
-import { createError, readMultipartFormData } from 'h3'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createError } from 'h3'
 import { requireAdminSession } from '../../../../utils/admin-auth'
 import { importPostsFromExportZip } from '../../../../repositories/post-import-repository'
+import { saveMultipartFileToDisk } from '../../../../utils/multipart-file-upload'

 const MAX_IMPORT_ZIP_BYTES = 300 * 1024 * 1024

@@ -11,43 +15,53 @@ const MAX_IMPORT_ZIP_BYTES = 300 * 1024 * 1024
 */
 export default defineEventHandler(async (event) => {
  const adminSession = requireAdminSession(event)
-  const formData = await readMultipartFormData(event)
-  const file = (formData || []).find((part) => part.name === 'file' && part.filename)
-
-  if (!file) {
-    throw createError({
-      statusCode: 400,
-      message: 'Import할 ZIP 파일을 선택해 주세요.'
-    })
-  }
-
-  if (!String(file.filename || '').toLowerCase().endsWith('.zip')) {
-    throw createError({
-      statusCode: 400,
-      message: 'ZIP 파일만 Import할 수 있습니다.'
-    })
-  }
-
-  if (!file.data?.length) {
-    throw createError({
-      statusCode: 400,
-      message: '비어 있는 ZIP 파일은 Import할 수 없습니다.'
-    })
-  }
-
-  if (file.data.length > MAX_IMPORT_ZIP_BYTES) {
-    throw createError({
-      statusCode: 413,
-      message: 'Import ZIP 파일은 최대 300MB까지 처리할 수 있습니다.'
-    })
-  }
+  const tempDirectory = await mkdtemp(join(tmpdir(), 'sori-studio-import-'))
+  const zipFilePath = join(tempDirectory, 'upload.zip')

  try {
+    const uploaded = await saveMultipartFileToDisk(event, {
+      fieldName: 'file',
+      filePath: zipFilePath,
+      maxBytes: MAX_IMPORT_ZIP_BYTES
+    })
+
+    if (!String(uploaded.filename || '').toLowerCase().endsWith('.zip')) {
+      throw createError({
+        statusCode: 400,
+        message: 'ZIP 파일만 Import할 수 있습니다.'
+      })
+    }
+
+    if (!uploaded.size) {
+      throw createError({
+        statusCode: 400,
+        message: '비어 있는 ZIP 파일은 Import할 수 없습니다.'
+      })
+    }
+
    return await importPostsFromExportZip({
-      zipBuffer: file.data,
+      zipFilePath,
      authorId: adminSession.userId
    })
  } catch (error) {
+    if (error?.statusCode) {
+      throw error
+    }
+
+    if (error?.code === 'MULTIPART_FILE_TOO_LARGE') {
+      throw createError({
+        statusCode: 413,
+        message: 'Import ZIP 파일은 최대 300MB까지 처리할 수 있습니다.'
+      })
+    }
+
+    if (['MULTIPART_FILE_NOT_FOUND', 'INVALID_MULTIPART_REQUEST'].includes(error?.code)) {
+      throw createError({
+        statusCode: 400,
+        message: 'Import할 ZIP 파일을 선택해 주세요.'
+      })
+    }
+
    if (error?.message === 'IMPORT_MARKDOWN_NOT_FOUND') {
      throw createError({
        statusCode: 400,
@@ -62,6 +76,30 @@ export default defineEventHandler(async (event) => {
      })
    }

+    if ([
+      'ZIP_ENTRY_COUNT_LIMIT_EXCEEDED',
+      'ZIP_ENTRY_SIZE_LIMIT_EXCEEDED',
+      'ZIP_TOTAL_SIZE_LIMIT_EXCEEDED',
+      'ZIP_COMPRESSION_RATIO_LIMIT_EXCEEDED',
+      'IMPORT_MARKDOWN_SIZE_LIMIT_EXCEEDED'
+    ].includes(error?.message)) {
+      throw createError({
+        statusCode: 413,
+        message: 'ZIP 내부 파일의 개수·압축률 또는 압축 해제 크기가 허용 범위를 초과했습니다.'
+      })
+    }
+
+    if ([
+      'INVALID_ZIP_FILE',
+      'UNSAFE_ZIP_ENTRY_PATH',
+      'DUPLICATE_ZIP_ENTRY_PATH'
+    ].includes(error?.message)) {
+      throw createError({
+        statusCode: 400,
+        message: '안전하게 처리할 수 없는 ZIP 파일입니다.'
+      })
+    }
+
    if (error?.code === '23505') {
      throw createError({
        statusCode: 409,
@@ -73,5 +111,10 @@ export default defineEventHandler(async (event) => {
      statusCode: 500,
      message: '게시물 Import를 완료하지 못했습니다.'
    })
+  } finally {
+    await rm(tempDirectory, {
+      recursive: true,
+      force: true
+    })
  }
 })
--- a/server/routes/admin/api/settings.patch.js
+++ b/server/routes/admin/api/settings.patch.js
@@ -0,0 +1,93 @@
+import { createError, readBody } from 'h3'
+import { requireAdminSession } from '../../../utils/admin-auth'
+import { parseAdminSiteSettingsInput } from '../../../utils/admin-site-settings-input'
+import {
+  getSiteSettings,
+  updateSiteSettingsPartial
+} from '../../../repositories/content-repository'
+
+const ALLOWED_SITE_SETTINGS_FIELDS = new Set([
+  'title',
+  'description',
+  'siteUrl',
+  'logoText',
+  'logoUrl',
+  'faviconUrl',
+  'copyrightText',
+  'socialLinks',
+  'showPostUpdatedAt',
+  'postTagLimit',
+  'homeLatestPostLimit',
+  'postListPageSize',
+  'tagPostListPageSize',
+  'featuredPostLimit',
+  'pageSectionItemLimit',
+  'uploadMaxFileCount',
+  'uploadMaxTotalSize',
+  'homeCoverImageUrl',
+  'homeCoverDarkImageUrl',
+  'homeCoverTitle',
+  'homeCoverText',
+  'brandColor',
+  'announcementEnabled',
+  'announcementText',
+  'announcementUrl',
+  'announcementBackgroundColor',
+  'announcementAlignment',
+  'signupBlockedUsernames',
+  'adsTxt',
+  'customHeadCode',
+  'customFooterCode',
+  'adHomeFeedCode',
+  'adHomeInfeedCode',
+  'adSidebarCode',
+  'adPostSidebarCode',
+  'adPostTopCode',
+  'adPostInArticleCode',
+  'adPostBottomCode'
+])
+
+/**
+ * 관리자 사이트 설정의 전달된 필드만 수정한다.
+ * @param {import('h3').H3Event} event - 요청 이벤트
+ * @returns {Promise<Object>} 수정된 사이트 설정
+ */
+export default defineEventHandler(async (event) => {
+  requireAdminSession(event)
+  const body = await readBody(event)
+
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    throw createError({
+      statusCode: 400,
+      message: '사이트 설정 입력 형식이 올바르지 않습니다.'
+    })
+  }
+
+  const fields = Object.keys(body)
+  if (!fields.length || fields.some((field) => !ALLOWED_SITE_SETTINGS_FIELDS.has(field))) {
+    throw createError({
+      statusCode: 400,
+      message: '수정할 수 없는 사이트 설정 필드가 포함되어 있습니다.'
+    })
+  }
+
+  const currentSettings = await getSiteSettings()
+  const parsedBody = parseAdminSiteSettingsInput({
+    ...currentSettings,
+    ...body
+  })
+
+  if (!parsedBody.success) {
+    throw createError({
+      statusCode: 400,
+      message: '사이트 설정 입력 형식이 올바르지 않습니다.'
+    })
+  }
+
+  const validatedPatch = Object.fromEntries(fields.map((field) => [
+    field,
+    parsedBody.data[field]
+  ]))
+
+  return updateSiteSettingsPartial(validatedPatch)
+})
--- a/server/routes/admin/api/settings/home-cover.post.js
+++ b/server/routes/admin/api/settings/home-cover.post.js
@@ -4,6 +4,7 @@ import { createError, readMultipartFormData } from 'h3'
 import sharp from 'sharp'
 import { requireAdminSession } from '../../../../utils/admin-auth'
 import { upsertMediaMetadataCategory } from '../../../../utils/media-library'
+import { getConfiguredUploadRoot } from '../../../../utils/upload-root'

 const allowedImageTypes = new Set(['image/jpeg', 'image/png', 'image/webp'])

@@ -65,7 +66,7 @@ export default defineEventHandler(async (event) => {

  const uploadBaseUrl = String(config.uploadDir || '/uploads').replace(/\/+$/g, '') || '/uploads'
  const publicBasePath = uploadBaseUrl.replace(/^\/+/, '')
-  const directoryPath = join(process.cwd(), 'public', publicBasePath, 'system')
+  const directoryPath = join(getConfiguredUploadRoot(publicBasePath), 'system')
  const assetSuffix = createSystemAssetSuffix()
  const coverFileName = `home-cover-${assetSuffix}.webp`
  const coverPath = join(directoryPath, coverFileName)
--- a/server/routes/admin/api/settings/logo.post.js
+++ b/server/routes/admin/api/settings/logo.post.js
@@ -4,6 +4,7 @@ import { createError, readMultipartFormData } from 'h3'
 import sharp from 'sharp'
 import { requireAdminSession } from '../../../../utils/admin-auth'
 import { upsertMediaMetadataCategory } from '../../../../utils/media-library'
+import { getConfiguredUploadRoot } from '../../../../utils/upload-root'

 const allowedImageTypes = new Set(['image/jpeg', 'image/png', 'image/webp'])

@@ -87,7 +88,7 @@ export default defineEventHandler(async (event) => {

  const uploadBaseUrl = String(config.uploadDir || '/uploads').replace(/\/+$/g, '') || '/uploads'
  const publicBasePath = uploadBaseUrl.replace(/^\/+/, '')
-  const directoryPath = join(process.cwd(), 'public', publicBasePath, 'system')
+  const directoryPath = join(getConfiguredUploadRoot(publicBasePath), 'system')
  const assetSuffix = createSystemAssetSuffix()
  const logoFileName = `logo-${assetSuffix}.webp`
  const faviconFileName = `favicon-${assetSuffix}.png`
--- a/server/routes/admin/api/tags/cover.post.js
+++ b/server/routes/admin/api/tags/cover.post.js
@@ -4,6 +4,7 @@ import { createError, readMultipartFormData } from 'h3'
 import sharp from 'sharp'
 import { requireAdminSession } from '../../../../utils/admin-auth'
 import { upsertMediaMetadataCategory } from '../../../../utils/media-library'
+import { getConfiguredUploadRoot } from '../../../../utils/upload-root'

 const allowedImageTypes = new Set(['image/jpeg', 'image/png', 'image/webp'])
 const tagCoverWidth = 720
@@ -64,7 +65,7 @@ export default defineEventHandler(async (event) => {

  const uploadBaseUrl = String(config.uploadDir || '/uploads').replace(/\/+$/g, '') || '/uploads'
  const publicBasePath = uploadBaseUrl.replace(/^\/+/, '')
-  const directoryPath = join(process.cwd(), 'public', publicBasePath, 'system')
+  const directoryPath = join(getConfiguredUploadRoot(publicBasePath), 'system')
  const assetSuffix = createSystemAssetSuffix()
  const coverFileName = `tag-cover-${assetSuffix}.webp`
  const coverPath = join(directoryPath, coverFileName)
--- a/server/routes/admin/api/uploads.post.js
+++ b/server/routes/admin/api/uploads.post.js
@@ -1,10 +1,9 @@
-import { mkdir, stat, writeFile } from 'node:fs/promises'
+import { link, mkdir, mkdtemp, rm, unlink } from 'node:fs/promises'
 import { extname, join } from 'node:path'
-import { createError, readMultipartFormData } from 'h3'
+import { createError } from 'h3'
 import {
  buildDefaultUploadSizeLimits,
  formatUploadSizeLimit,
-  getUploadFilesTotalSize,
  getMaxUploadBytesForKind,
  getUploadKind,
  getUploadKindLabel,
@@ -14,6 +13,9 @@ import {
 import { requireAdminSession } from '../../../utils/admin-auth'
 import { getRuntimeEnvNumber } from '../../../utils/runtime-env.js'
 import { upsertMediaMetadataCategory } from '../../../utils/media-library'
+import { deleteMediaCatalogEntries } from '../../../repositories/media-catalog-repository'
+import { saveMultipartFilesToDisk } from '../../../utils/multipart-file-upload'
+import { getConfiguredUploadRoot } from '../../../utils/upload-root'
 import { getSiteSettings } from '../../../repositories/content-repository'

 const allowedUploadTypes = new Map([
@@ -72,7 +74,7 @@ const sanitizePathPart = (value) => String(value || '')

 /**
 * 파일 확장자 조회
- * @param {Object} file - multipart 파일 파트
+ * @param {{ filename: string, type: string }} file - multipart 파일 정보
 * @returns {string} 확장자
 */
 const getUploadExtension = (file) => {
@@ -87,20 +89,21 @@ const getUploadExtension = (file) => {

 /**
 * 업로드 허용 파일인지 확인한다.
- * @param {Object} file - multipart 파일 파트
+ * @param {{ filename: string, type: string }} file - multipart 파일 정보
 * @returns {boolean} 허용 여부
 */
 const isAllowedUploadFile = (file) => allowedUploadTypes.has(file.type)
  || allowedUploadExtensions.has(extname(file.filename || '').toLowerCase())

 /**
- * 디렉터리 안에서 비어 있는 저장 파일명을 고른다. 동일 이름이 있으면 `이름-2`, `이름-3` 식으로 넘버링한다.
+ * 임시 파일을 충돌하지 않는 최종 파일명으로 원자적으로 이동한다.
 * @param {string} directoryPath - 저장 디렉터리 절대 경로
 * @param {string} stem - 확장자 제외 파일명
 * @param {string} extension - 확장자(점 포함, 예: `.png`)
+ * @param {string} sourcePath - 임시 파일 절대 경로
 * @returns {Promise<{ fileName: string, filePath: string }>} 선택된 파일명과 절대 경로
 */
-const pickUniqueDiskFileName = async (directoryPath, stem, extension) => {
+const moveToUniqueDiskFileName = async (directoryPath, stem, extension, sourcePath) => {
  let suffix = 1

  while (suffix < 10000) {
@@ -108,13 +111,17 @@ const pickUniqueDiskFileName = async (directoryPath, stem, extension) => {
    const filePath = join(directoryPath, fileName)

    try {
-      await stat(filePath)
-      suffix += 1
-    } catch {
+      await link(sourcePath, filePath)
+      await unlink(sourcePath)
      return {
        fileName,
        filePath
      }
+    } catch (error) {
+      if (error?.code !== 'EEXIST') {
+        throw error
+      }
+      suffix += 1
    }
  }

@@ -142,79 +149,120 @@ export default defineEventHandler(async (event) => {
  const settings = await getSiteSettings()
  const uploadMaxFileCount = normalizeUploadMaxFileCount(settings.uploadMaxFileCount)
  const uploadMaxTotalSize = normalizeUploadMaxTotalSize(settings.uploadMaxTotalSize)
-  const formData = await readMultipartFormData(event)
-  const files = (formData || []).filter((part) => part.name === 'files' && part.filename)
-
-  if (!files.length) {
-    throw createError({
-      statusCode: 400,
-      message: '업로드할 파일이 없습니다.'
-    })
-  }
-
-  if (files.length > uploadMaxFileCount) {
-    throw createError({
-      statusCode: 413,
-      message: `한 번에 업로드할 수 있는 파일은 최대 ${uploadMaxFileCount}개입니다.`
-    })
-  }
-
-  const uploadTotalSize = getUploadFilesTotalSize(files)
-
-  if (uploadTotalSize > uploadMaxTotalSize) {
-    throw createError({
-      statusCode: 413,
-      message: `한 번에 업로드 가능한 전체 용량을 초과했습니다. (최대 ${formatUploadSizeLimit(uploadMaxTotalSize)})`
-    })
-  }
-
  const now = new Date()
  const year = String(now.getFullYear())
  const month = String(now.getMonth() + 1).padStart(2, '0')
  const uploadBaseUrl = String(config.uploadDir || '/uploads').replace(/\/+$/g, '') || '/uploads'
  const publicBasePath = uploadBaseUrl.replace(/^\/+/, '')
-  const directoryPath = join(process.cwd(), 'public', publicBasePath, 'posts', year, month)
+  const directoryPath = join(getConfiguredUploadRoot(publicBasePath), 'posts', year, month)

  await mkdir(directoryPath, { recursive: true })
+  const tempDirectoryPath = await mkdtemp(join(directoryPath, '.upload-'))
+  const movedFilePaths = []
+  const catalogRecordedUrls = []

-  const uploadedFiles = []
+  try {
+    const streamedFiles = await saveMultipartFilesToDisk(event, {
+      fieldName: 'files',
+      maxFiles: uploadMaxFileCount,
+      maxTotalBytes: uploadMaxTotalSize,
+      createFileTarget: async (file, index) => {
+        const uploadFile = {
+          filename: file.filename,
+          type: file.mimeType
+        }

-  for (const file of files) {
-    if (!isAllowedUploadFile(file)) {
-      throw createError({
-        statusCode: 400,
-        message: '지원하지 않는 파일 형식입니다.'
+        if (!isAllowedUploadFile(uploadFile)) {
+          throw createError({
+            statusCode: 400,
+            message: '지원하지 않는 파일 형식입니다.'
+          })
+        }
+
+        const uploadKind = getUploadKind(uploadFile.type, uploadFile.filename)
+        const maxFileSize = getMaxUploadBytesForKind(uploadKind, uploadSizeLimits)
+        const originalStem = sanitizePathPart(uploadFile.filename.replace(/\.[^.]+$/g, '')) || 'file'
+        const extension = getUploadExtension(uploadFile)
+
+        return {
+          filePath: join(tempDirectoryPath, `${index}${extension}`),
+          maxBytes: maxFileSize,
+          metadata: {
+            originalStem,
+            extension,
+            uploadKind
+          }
+        }
+      }
+    })
+
+    const uploadedFiles = []
+
+    for (const file of streamedFiles) {
+      const { fileName, filePath } = await moveToUniqueDiskFileName(
+        directoryPath,
+        file.metadata.originalStem,
+        file.metadata.extension,
+        file.filePath
+      )
+      movedFilePaths.push(filePath)
+
+      const publicUrl = `${uploadBaseUrl}/posts/${year}/${month}/${fileName}`
+      await upsertMediaMetadataCategory(publicUrl, '미분류')
+      catalogRecordedUrls.push(publicUrl)
+
+      uploadedFiles.push({
+        url: publicUrl,
+        name: fileName,
+        size: file.size
      })
    }

-    const uploadKind = getUploadKind(file.type, file.filename)
-    const maxFileSize = getMaxUploadBytesForKind(uploadKind, uploadSizeLimits)
+    return {
+      files: uploadedFiles
+    }
+  } catch (error) {
+    await Promise.all(movedFilePaths.map((filePath) => unlink(filePath).catch(() => {})))
+    await deleteMediaCatalogEntries(catalogRecordedUrls).catch(() => {
+      console.warn('[media-catalog] 업로드 실패 정리 중 카탈로그 갱신 실패')
+    })

-    if (file.data.length > maxFileSize) {
+    if (error?.statusCode) {
+      throw error
+    }
+    if (error?.code === 'MULTIPART_TOO_MANY_FILES') {
      throw createError({
        statusCode: 413,
-        message: `${getUploadKindLabel(uploadKind)} 업로드 가능 크기를 초과했습니다. (최대 ${formatUploadSizeLimit(maxFileSize)})`
+        message: `한 번에 업로드할 수 있는 파일은 최대 ${uploadMaxFileCount}개입니다.`
+      })
+    }
+    if (error?.code === 'MULTIPART_TOTAL_SIZE_TOO_LARGE') {
+      throw createError({
+        statusCode: 413,
+        message: `한 번에 업로드 가능한 전체 용량을 초과했습니다. (최대 ${formatUploadSizeLimit(uploadMaxTotalSize)})`
+      })
+    }
+    if (error?.code === 'MULTIPART_FILE_TOO_LARGE') {
+      throw createError({
+        statusCode: 413,
+        message: `${getUploadKindLabel(error.metadata?.uploadKind)} 업로드 가능 크기를 초과했습니다. (최대 ${formatUploadSizeLimit(error.maxBytes)})`
+      })
+    }
+    if (['MULTIPART_FILE_NOT_FOUND', 'INVALID_MULTIPART_REQUEST', 'MULTIPART_TOO_MANY_PARTS'].includes(error?.code)) {
+      throw createError({
+        statusCode: 400,
+        message: '업로드할 파일이 없거나 요청 형식이 올바르지 않습니다.'
      })
    }

-    const originalStem = sanitizePathPart(file.filename.replace(/\.[^.]+$/g, '')) || 'image'
-    const extension = getUploadExtension(file)
-    const { fileName, filePath } = await pickUniqueDiskFileName(directoryPath, originalStem, extension)
-
-    await writeFile(filePath, file.data)
-
-    const publicUrl = `${uploadBaseUrl}/posts/${year}/${month}/${fileName}`
-
-    await upsertMediaMetadataCategory(publicUrl, '미분류')
-
-    uploadedFiles.push({
-      url: publicUrl,
-      name: fileName,
-      size: file.data.length
+    throw createError({
+      statusCode: 500,
+      message: '파일을 업로드하지 못했습니다.'
+    })
+  } finally {
+    await rm(tempDirectoryPath, {
+      recursive: true,
+      force: true
    })
  }
-
-  return {
-    files: uploadedFiles
-  }
 })