파일 업로드와 다운로드 완벽 가이드

Node.js와 Express를 사용하여 파일 업로드부터 다운로드까지 안전하게 구현하는 방법을 배웁니다. Multer를 활용한 파일 처리, 썸네일 생성, 권한 검증까지 실무에 필요한 모든 것을 다룹니다.

---

목차

1. Multer 파일 업로드 설정
2. 이미지 업로드 API
3. 이미지 썸네일 생성
4. 파일 다운로드 API
5. 권한 검증 미들웨어
6. MIME 타입 제한
7. 파일 크기 제한

---

1. Multer 파일 업로드 설정

시작하며

여러분이 웹 애플리케이션을 개발할 때 사용자로부터 이미지나 문서를 받아야 하는 상황을 겪어본 적 있나요? 프로필 사진 업로드, 문서 첨부, 게시글 이미지 등록 같은 기능을 구현하려고 할 때 어디서부터 시작해야 할지 막막했던 경험이 있을 겁니다.

파일 업로드는 단순해 보이지만, 실제로는 파일을 어디에 저장할지, 파일명은 어떻게 관리할지, 보안은 어떻게 처리할지 등 고려해야 할 것들이 많습니다. 잘못 구현하면 서버 저장소가 가득 차거나, 악성 파일이 업로드되는 보안 문제가 발생할 수 있습니다.

바로 이럴 때 필요한 것이 Multer입니다. Multer는 Node.js 환경에서 파일 업로드를 쉽고 안전하게 처리할 수 있도록 도와주는 미들웨어로, 복잡한 파일 처리 로직을 간단하게 구현할 수 있게 해줍니다.

개요

간단히 말해서, Multer는 HTML 폼에서 전송된 파일을 서버에서 받아 저장하는 역할을 하는 도구입니다. 마치 우체국 직원이 소포를 받아서 정해진 보관함에 분류해서 넣는 것처럼, Multer도 파일을 받아서 여러분이 지정한 폴더에 저장해줍니다.

왜 이 도구가 필요할까요? 일반적인 텍스트 데이터와 달리 파일은 용량이 크고 바이너리 형태로 전송되기 때문에 특별한 처리가 필요합니다.

예를 들어, 사용자가 10MB 크기의 사진을 업로드할 때, 이 데이터를 적절히 파싱하고 저장 위치를 결정하며 파일명 충돌을 방지해야 합니다. 기존에는 직접 스트림을 읽고 파일 시스템에 쓰는 복잡한 코드를 작성해야 했다면, Multer를 사용하면 몇 줄의 설정만으로 이 모든 것을 자동화할 수 있습니다.

또한 메모리 효율적으로 파일을 처리하여 서버 성능을 유지할 수 있습니다. Multer의 핵심 특징은 첫째, 저장 위치와 파일명을 자유롭게 커스터마이징할 수 있다는 점입니다.

둘째, 파일 크기나 타입을 제한하여 보안을 강화할 수 있습니다. 셋째, 단일 파일부터 다중 파일 업로드까지 다양한 시나리오를 지원합니다.

이러한 특징들이 안정적인 파일 업로드 시스템을 구축하는 데 매우 중요합니다.

코드 예제

// Multer 기본 설정 - 파일 저장소와 파일명 정의
const multer = require('multer');
const path = require('path');

const storage = multer.diskStorage({
  // 파일이 저장될 폴더 지정
  destination: function (req, file, cb) {
    cb(null, 'uploads/');
  },
  // 저장될 파일명 생성 (타임스탬프 + 원본명)
  filename: function (req, file, cb) {
    const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
    cb(null, file.fieldname + '-' + uniqueSuffix + path.extname(file.originalname));
  }
});

// Multer 인스턴스 생성
const upload = multer({ storage: storage });

설명

이것이 하는 일: 위 코드는 파일이 서버에 업로드될 때 어디에 어떤 이름으로 저장될지를 정의하는 Multer 설정입니다. 마치 택배 보관함 시스템을 만드는 것과 같습니다.

첫 번째로, multer.diskStorage()를 사용하여 저장 엔진을 설정합니다. 이는 파일을 서버의 디스크에 저장하겠다는 의미입니다.

destination 함수에서는 파일이 'uploads/' 폴더에 저장되도록 지정합니다. 이 폴더가 없으면 에러가 발생하므로 미리 생성해두어야 합니다.

그 다음으로, filename 함수가 실행되면서 저장될 파일명을 생성합니다. 원본 파일명을 그대로 사용하면 같은 이름의 파일이 업로드될 때 덮어쓰기가 되므로, 현재 타임스탬프와 랜덤 숫자를 조합하여 고유한 파일명을 만듭니다.

path.extname()은 원본 파일의 확장자(.jpg, .png 등)를 추출하여 붙여줍니다. 마지막으로, 설정한 storage를 multer 함수에 전달하여 upload 객체를 생성합니다.

이 객체는 실제 라우트에서 미들웨어로 사용되어 파일 업로드를 처리하게 됩니다. 여러분이 이 코드를 사용하면 파일명 충돌 걱정 없이 안전하게 파일을 저장할 수 있습니다.

또한 업로드된 파일의 정보(경로, 파일명, 크기 등)를 req.file 객체로 쉽게 접근할 수 있어 데이터베이스에 정보를 저장하거나 추가 처리를 할 때 매우 편리합니다.

실전 팁

💡 uploads 폴더는 반드시 사전에 생성해두세요. 폴더가 없으면 업로드 시 에러가 발생합니다. fs.mkdirSync()를 사용해 앱 시작 시 자동으로 생성하도록 하면 편리합니다.

💡 파일명에 타임스탬프를 사용하면 같은 이름의 파일도 구분할 수 있지만, 나중에 파일을 찾기 어려울 수 있습니다. 데이터베이스에 원본 파일명과 저장된 파일명을 함께 기록하는 것이 좋습니다.

💡 diskStorage 대신 memoryStorage를 사용하면 파일을 메모리에 버퍼로 저장할 수 있습니다. 이는 이미지 처리 후 바로 삭제하는 경우에 유용하지만, 대용량 파일은 메모리를 많이 차지하므로 주의하세요.

💡 프로덕션 환경에서는 로컬 디스크 대신 AWS S3, Google Cloud Storage 같은 클라우드 스토리지를 사용하는 것을 권장합니다. multer-s3 같은 플러그인을 활용하면 쉽게 연동할 수 있습니다.

💡 파일 업로드 경로에 날짜별 폴더를 만들면 관리가 편리합니다. 예: uploads/2025/11/22/file.jpg 형태로 저장하면 나중에 특정 날짜의 파일을 찾거나 오래된 파일을 정리하기 쉽습니다.

---

2. 이미지 업로드 API

시작하며

여러분이 프로필 사진 업로드 기능을 만들 때, 설정은 완료했지만 실제로 어떻게 API 엔드포인트를 만들어야 할지 고민해본 적 있나요? 클라이언트에서 보낸 파일을 받아서 저장하고, 그 결과를 어떻게 응답해야 할지 막막할 수 있습니다.

이런 문제는 파일 업로드 기능을 처음 구현하는 개발자들이 자주 겪는 어려움입니다. 단순히 파일만 저장하는 것이 아니라, 업로드 성공 여부를 확인하고, 저장된 파일의 경로를 클라이언트에 알려주고, 에러 상황을 처리해야 합니다.

바로 이럴 때 필요한 것이 Express와 Multer를 결합한 파일 업로드 API입니다. 미들웨어 방식으로 간단하게 라우트를 구성하여 안정적인 파일 업로드 엔드포인트를 만들 수 있습니다.

개요

간단히 말해서, 이미지 업로드 API는 클라이언트가 전송한 이미지 파일을 받아 서버에 저장하고, 저장된 파일의 정보를 JSON 형태로 응답하는 엔드포인트입니다. 마치 사진관에서 사진을 받아 보관하고 영수증을 주는 것처럼, 서버가 파일을 받아 저장하고 저장 위치를 알려주는 것입니다.

왜 이런 API가 필요할까요? 웹 애플리케이션에서 사용자가 이미지를 업로드할 때, 클라이언트는 서버에 파일을 전송하고 결과를 받아야 합니다.

예를 들어, SNS 앱에서 게시글에 사진을 첨부할 때, 사진이 어디에 저장되었는지 알아야 나중에 화면에 표시할 수 있습니다. 기존에는 복잡한 폼 파싱 로직과 파일 저장 코드를 직접 작성해야 했다면, Multer 미들웨어를 사용하면 upload.single()이나 upload.array() 같은 간단한 메서드로 모든 처리를 자동화할 수 있습니다.

이 API의 핵심 특징은 첫째, 미들웨어 체이닝을 통해 파일 처리가 자동으로 이루어진다는 점입니다. 둘째, req.file 객체를 통해 업로드된 파일의 모든 정보에 접근할 수 있습니다.

셋째, 에러 처리를 통해 업로드 실패 시 적절한 응답을 보낼 수 있습니다. 이러한 특징들이 안정적이고 사용하기 쉬운 파일 업로드 시스템의 기반이 됩니다.

코드 예제

// 이미지 업로드 API 엔드포인트
const express = require('express');
const router = express.Router();

// 단일 이미지 업로드 (필드명: 'profileImage')
router.post('/upload', upload.single('profileImage'), (req, res) => {
  // 파일이 업로드되지 않은 경우
  if (!req.file) {
    return res.status(400).json({ error: '파일이 업로드되지 않았습니다.' });
  }

  // 업로드 성공 - 파일 정보 반환
  res.json({
    message: '파일 업로드 성공',
    filename: req.file.filename,
    path: req.file.path,
    size: req.file.size
  });
});

설명

이것이 하는 일: 위 코드는 POST 요청으로 전송된 이미지 파일을 받아 저장하고, 저장된 파일의 정보를 JSON 응답으로 돌려주는 API 엔드포인트입니다. 클라이언트와 서버 간의 파일 전송 통로를 만드는 것입니다.

첫 번째로, router.post() 메서드로 '/upload' 경로에 POST 엔드포인트를 생성합니다. 두 번째 인자로 upload.single('profileImage')를 전달하는데, 이는 'profileImage'라는 필드명으로 전송된 단일 파일을 처리하라는 의미입니다.

이 미들웨어가 먼저 실행되어 파일을 저장하고, 그 다음 우리가 작성한 콜백 함수가 실행됩니다. 그 다음으로, 콜백 함수 안에서 req.file의 존재 여부를 확인합니다.

만약 파일이 없다면 클라이언트가 파일을 보내지 않았거나 필드명이 잘못된 것이므로 400 에러를 반환합니다. 이는 사용자에게 명확한 에러 메시지를 제공하여 문제를 빠르게 파악할 수 있게 합니다.

파일이 정상적으로 업로드되었다면, req.file 객체에서 filename(저장된 파일명), path(파일 경로), size(파일 크기) 등의 정보를 추출하여 JSON으로 응답합니다. 클라이언트는 이 응답을 받아 파일이 성공적으로 업로드되었음을 확인하고, 필요한 경우 파일 경로를 데이터베이스에 저장하거나 화면에 미리보기를 표시할 수 있습니다.

여러분이 이 코드를 사용하면 프론트엔드에서 FormData로 파일을 전송하기만 하면 자동으로 서버에 저장되고 결과를 받을 수 있습니다. 또한 req.file에는 mimetype(파일 타입), originalname(원본 파일명) 등 더 많은 정보가 있어 필요에 따라 활용할 수 있습니다.

실전 팁

💡 클라이언트에서 보낼 때 FormData의 append() 메서드 첫 번째 인자가 'profileImage'와 정확히 일치해야 합니다. 필드명이 다르면 req.file이 undefined가 됩니다.

💡 다중 파일 업로드가 필요하다면 upload.array('images', 5)를 사용하세요. 숫자는 최대 파일 개수이며, 업로드된 파일은 req.files 배열에 담깁니다.

💡 업로드된 파일 경로를 데이터베이스에 저장할 때는 절대 경로가 아닌 상대 경로를 저장하세요. 서버 경로가 바뀌어도 유연하게 대응할 수 있습니다.

💡 에러 처리를 강화하려면 try-catch를 사용하거나, 에러 핸들링 미들웨어를 별도로 만들어 Multer 에러를 구분하여 처리하는 것이 좋습니다.

💡 업로드 성공 후 파일 URL을 클라이언트에 제공할 때는 '/uploads/' + filename 형태로 접근 가능한 URL을 만들어주세요. Express에서 express.static()으로 uploads 폴더를 공개해야 합니다.

---

3. 이미지 썸네일 생성

시작하며

여러분이 이미지를 업로드받았는데, 그 이미지가 10MB가 넘는 고해상도 사진이라면 어떻게 될까요? 게시글 목록이나 프로필 사진처럼 작은 크기로 보여줄 때도 원본 이미지를 그대로 로드하면 페이지 로딩이 매우 느려집니다.

이런 문제는 이미지가 많은 서비스에서 심각한 성능 저하를 일으킵니다. 사용자는 느린 로딩 때문에 사이트를 떠나게 되고, 서버는 불필요하게 큰 파일을 계속 전송하느라 대역폭 비용이 증가합니다.

바로 이럴 때 필요한 것이 썸네일 생성입니다. 업로드된 원본 이미지를 유지하면서 작은 크기의 썸네일 이미지를 자동으로 만들어 두면, 목록 화면에서는 썸네일을, 상세 화면에서는 원본을 보여줄 수 있어 성능과 품질을 모두 확보할 수 있습니다.

개요

간단히 말해서, 썸네일 생성은 업로드된 원본 이미지를 분석하여 크기를 줄인 작은 버전의 이미지를 자동으로 만드는 과정입니다. 마치 사진관에서 여권사진을 찍으면 큰 원본과 함께 작은 증명사진도 함께 인화해주는 것처럼, 하나의 이미지에서 여러 크기의 버전을 생성하는 것입니다.

왜 썸네일이 필요할까요? 웹에서는 같은 이미지를 여러 곳에서 다른 크기로 표시하는 경우가 많습니다.

예를 들어, Instagram처럼 피드에서는 300x300 크기로, 상세보기에서는 원본 크기로 보여줘야 합니다. 매번 원본을 불러와서 CSS로 크기만 줄이면 실제 다운로드되는 데이터는 그대로이므로 비효율적입니다.

기존에는 이미지 편집 도구를 사용해 수동으로 여러 크기를 만들어야 했다면, Sharp 같은 이미지 처리 라이브러리를 사용하면 업로드와 동시에 자동으로 다양한 크기의 썸네일을 생성할 수 있습니다. 썸네일 생성의 핵심 특징은 첫째, 이미지 크기를 줄여 로딩 속도를 대폭 향상시킨다는 점입니다.

둘째, 원본 비율을 유지하거나 특정 비율로 자르는 등 다양한 옵션을 설정할 수 있습니다. 셋째, 이미지 품질과 파일 크기 사이의 균형을 조절할 수 있습니다.

이러한 특징들이 사용자 경험과 서버 효율성을 동시에 개선하는 데 핵심적인 역할을 합니다.

코드 예제

// Sharp를 사용한 썸네일 생성
const sharp = require('sharp');
const fs = require('fs').promises;

async function createThumbnail(filePath, thumbnailPath, width = 300) {
  try {
    // 원본 이미지를 읽어 리사이징 후 저장
    await sharp(filePath)
      .resize(width, width, {
        fit: 'cover', // 비율 유지하며 크롭
        position: 'center' // 중앙 기준으로 자르기
      })
      .jpeg({ quality: 80 }) // JPEG 품질 80%로 압축
      .toFile(thumbnailPath);

    return thumbnailPath;
  } catch (error) {
    console.error('썸네일 생성 실패:', error);
    throw error;
  }
}

설명

이것이 하는 일: 위 코드는 원본 이미지 파일을 읽어서 지정된 크기로 줄이고, 압축하여 새로운 파일로 저장하는 썸네일 생성 함수입니다. 자동화된 이미지 리사이징 시스템을 만드는 것입니다.

첫 번째로, sharp(filePath)로 원본 이미지를 로드합니다. Sharp는 매우 빠른 이미지 처리 라이브러리로, libvips를 기반으로 하여 대용량 이미지도 효율적으로 처리할 수 있습니다.

파일 경로만 전달하면 이미지를 메모리에 불러옵니다. 그 다음으로, resize() 메서드로 크기를 조정합니다.

width와 height를 같은 값으로 주고 fit: 'cover'로 설정하면 정사각형 썸네일이 만들어집니다. position: 'center'는 이미지를 자를 때 중앙 부분을 기준으로 하라는 의미입니다.

예를 들어 가로로 긴 이미지는 양 옆이 잘리고 중앙 부분만 남습니다. 세 번째로, jpeg() 메서드로 출력 형식과 품질을 지정합니다.

quality: 80은 원본의 80% 품질로 압축한다는 의미로, 육안으로는 거의 차이가 없지만 파일 크기는 크게 줄어듭니다. 마지막으로 toFile()로 지정된 경로에 썸네일을 저장합니다.

여러분이 이 함수를 파일 업로드 API에 통합하면, 사용자가 이미지를 올릴 때마다 자동으로 썸네일이 생성됩니다. 원본은 uploads/ 폴더에, 썸네일은 uploads/thumbnails/ 폴더에 저장하는 식으로 관리하면 나중에 필요에 따라 적절한 버전을 제공할 수 있습니다.

이를 통해 목록 화면에서는 로딩이 10배 이상 빨라지고, 모바일 사용자의 데이터도 절약할 수 있습니다.

실전 팁

💡 썸네일 파일명은 원본과 연관되게 만드세요. 예: original.jpg → original-thumb.jpg 형태로 저장하면 관리가 쉽습니다.

💡 여러 크기의 썸네일이 필요하다면 (예: 150px, 300px, 600px) Promise.all()로 병렬 처리하면 빠릅니다. 순차적으로 하나씩 만들면 시간이 오래 걸립니다.

💡 Sharp는 PNG도 지원하지만, 썸네일은 JPEG로 저장하는 것이 보통 더 작은 파일 크기를 만듭니다. 투명도가 필요한 경우에만 PNG를 사용하세요.

💡 fit 옵션은 'cover'(잘라서 꽉 채움), 'contain'(비율 유지하며 전체 보임), 'fill'(비율 무시하고 늘림) 등이 있습니다. 용도에 맞게 선택하세요.

💡 썸네일 생성은 시간이 걸리므로 업로드 응답 후 백그라운드에서 처리하는 것도 좋습니다. 큐 시스템(Bull, BullMQ)을 사용하면 업로드 속도를 유지하면서 썸네일을 비동기로 생성할 수 있습니다.

---

4. 파일 다운로드 API

시작하며

여러분이 서버에 저장된 파일을 사용자에게 다시 제공해야 하는 상황을 생각해보세요. 문서 다운로드, 이미지 보기, PDF 리포트 받기 같은 기능을 구현할 때 단순히 파일 경로를 알려주는 것만으로는 부족한 경우가 많습니다.

파일을 제공할 때는 적절한 헤더 설정, 파일 존재 여부 확인, 다운로드 파일명 지정 등 여러 가지를 신경 써야 합니다. 잘못 구현하면 브라우저에서 파일이 다운로드되지 않고 이상한 텍스트로 표시되거나, 존재하지 않는 파일에 대한 에러 처리가 되지 않을 수 있습니다.

바로 이럴 때 필요한 것이 파일 다운로드 API입니다. Express의 내장 기능을 활용하면 안전하고 편리하게 파일을 제공할 수 있으며, 사용자에게 최적의 다운로드 경험을 제공할 수 있습니다.

개요

간단히 말해서, 파일 다운로드 API는 서버에 저장된 파일을 클라이언트에게 전송하는 엔드포인트입니다. 마치 도서관에서 책을 대출하는 것처럼, 서버에 보관된 파일을 요청받아 사용자에게 전달하는 역할을 합니다.

왜 별도의 다운로드 API가 필요할까요? 직접 파일 경로에 접근하게 하면 보안 문제가 생길 수 있고, 파일명이 한글인 경우 인코딩 문제가 발생하며, 다운로드 진행 상황을 추적하거나 접근 권한을 체크할 수 없습니다.

예를 들어, 유료 콘텐츠는 로그인한 사용자만 다운로드할 수 있어야 하는데, 단순히 파일 경로를 공개하면 누구나 접근할 수 있게 됩니다. 기존에는 파일 스트림을 직접 읽어 응답에 파이프하는 복잡한 코드를 작성해야 했다면, Express의 res.download()나 res.sendFile() 메서드를 사용하면 한 줄로 파일 전송을 구현할 수 있습니다.

파일 다운로드 API의 핵심 특징은 첫째, 적절한 Content-Type과 Content-Disposition 헤더를 자동으로 설정한다는 점입니다. 둘째, 파일을 스트림 방식으로 전송하여 메모리 효율이 좋습니다.

셋째, 에러 처리가 내장되어 있어 파일이 없을 때 자동으로 404 에러를 반환합니다. 이러한 특징들이 안정적인 파일 제공 시스템의 기반이 됩니다.

코드 예제

// 파일 다운로드 API
const path = require('path');

router.get('/download/:filename', async (req, res) => {
  try {
    const filename = req.params.filename;
    const filePath = path.join(__dirname, '../uploads', filename);

    // 파일 존재 여부 확인
    const fs = require('fs').promises;
    await fs.access(filePath);

    // 다운로드 파일명 설정 (한글 인코딩 처리)
    const downloadName = encodeURIComponent('다운로드_' + filename);

    // 파일 전송
    res.download(filePath, downloadName, (err) => {
      if (err) {
        console.error('다운로드 실패:', err);
        res.status(500).json({ error: '파일 다운로드 중 오류가 발생했습니다.' });
      }
    });
  } catch (error) {
    res.status(404).json({ error: '파일을 찾을 수 없습니다.' });
  }
});

설명

이것이 하는 일: 위 코드는 URL 파라미터로 받은 파일명에 해당하는 파일을 서버에서 찾아 클라이언트에게 다운로드 형태로 전송하는 API입니다. 안전하고 효율적인 파일 제공 시스템을 만드는 것입니다.

첫 번째로, req.params.filename으로 다운로드할 파일명을 받아옵니다. 그리고 path.join()을 사용하여 안전한 파일 경로를 생성합니다.

이때 path.join()을 사용하는 이유는 운영체제에 상관없이 올바른 경로 구분자(Windows는 , Linux는 /)를 사용하기 위함입니다. __dirname은 현재 파일이 있는 디렉토리를 의미합니다.

그 다음으로, fs.access()로 파일이 실제로 존재하는지 확인합니다. 이 단계를 건너뛰면 존재하지 않는 파일을 다운로드하려 할 때 적절한 에러 메시지를 보낼 수 없습니다.

파일이 없으면 예외가 발생하여 catch 블록에서 404 에러를 반환합니다. 세 번째로, 다운로드될 파일명을 설정합니다.

encodeURIComponent()를 사용하여 한글이나 특수문자를 URL에 안전한 형태로 인코딩합니다. 이렇게 하지 않으면 한글 파일명이 깨져서 나타날 수 있습니다.

마지막으로, res.download()로 파일을 전송합니다. 이 메서드는 Content-Disposition 헤더를 'attachment'로 설정하여 브라우저가 파일을 화면에 표시하지 않고 다운로드하도록 합니다.

콜백 함수에서 전송 중 에러를 처리하여, 전송 실패 시 적절한 에러 응답을 보냅니다. 여러분이 이 코드를 사용하면 사용자가 '/download/report.pdf' 같은 URL을 요청했을 때 자동으로 파일이 다운로드됩니다.

또한 파일이 없거나 접근할 수 없을 때는 명확한 에러 메시지를 받을 수 있어 디버깅이 쉽습니다.

실전 팁

💡 res.download() 대신 res.sendFile()을 사용하면 브라우저가 파일을 다운로드하지 않고 표시합니다. PDF나 이미지를 새 탭에서 보여주고 싶을 때 유용합니다.

💡 파일명에 사용자 입력이 포함되면 경로 순회 공격(Path Traversal)에 취약할 수 있습니다. path.basename()으로 파일명만 추출하거나, 화이트리스트로 검증하세요.

💡 대용량 파일은 다운로드 시간이 오래 걸립니다. 이럴 때는 스트림을 사용하거나, 청크 단위로 전송하여 타임아웃을 방지하세요.

💡 다운로드 횟수를 추적하고 싶다면 res.download() 호출 전에 데이터베이스에 로그를 남기세요. 어떤 파일이 인기 있는지 분석할 수 있습니다.

💡 클라우드 스토리지(S3 등)를 사용한다면 서버를 거치지 않고 pre-signed URL을 생성하여 직접 다운로드하게 하는 것이 서버 부하를 줄입니다.

---

5. 권한 검증 미들웨어

시작하며

여러분이 파일 업로드 기능을 만들었는데, 아무나 파일을 올릴 수 있다면 어떻게 될까요? 악의적인 사용자가 대용량 파일을 무한정 업로드하거나, 다른 사람의 개인 문서를 다운로드할 수 있다면 심각한 보안 문제가 됩니다.

이런 문제는 실제로 많은 서비스에서 발생하는 보안 취약점입니다. 권한 검증 없이 파일 기능을 공개하면 서버 저장소가 금방 가득 차거나, 민감한 정보가 유출될 수 있으며, 법적 책임까지 질 수 있습니다.

바로 이럴 때 필요한 것이 권한 검증 미들웨어입니다. 파일 업로드나 다운로드 전에 사용자의 인증 상태와 권한을 확인하여, 허가된 사용자만 파일 기능을 사용할 수 있도록 제한하는 것입니다.

개요

간단히 말해서, 권한 검증 미들웨어는 API 엔드포인트에 접근하기 전에 사용자의 로그인 여부와 접근 권한을 확인하는 보안 장치입니다. 마치 건물 출입구의 보안 요원이 출입증을 확인하고 권한이 있는 사람만 들여보내는 것처럼, 서버가 요청을 처리하기 전에 자격을 검증하는 것입니다.

왜 권한 검증이 필요할까요? 파일은 민감한 데이터를 포함할 수 있고, 저장 공간과 대역폭은 유한한 자원이기 때문입니다.

예를 들어, 회사 내부 문서를 외부인이 다운로드하거나, 무료 사용자가 제한 없이 파일을 올려 서버 용량을 소진하는 것을 막아야 합니다. 기존에는 각 라우트마다 권한 체크 코드를 반복해서 작성해야 했다면, 미들웨어 패턴을 사용하면 재사용 가능한 검증 로직을 한 번만 작성하여 필요한 곳에 적용할 수 있습니다.

권한 검증 미들웨어의 핵심 특징은 첫째, 인증(Authentication)과 인가(Authorization)를 명확히 분리한다는 점입니다. 둘째, JWT나 세션 같은 다양한 인증 방식을 지원할 수 있습니다.

셋째, 미들웨어 체이닝으로 여러 단계의 검증을 조합할 수 있습니다. 이러한 특징들이 안전하고 유연한 접근 제어 시스템의 기반이 됩니다.

코드 예제

// JWT 기반 권한 검증 미들웨어
const jwt = require('jsonwebtoken');

// 인증 확인 (로그인 여부)
function authenticateToken(req, res, next) {
  // Authorization 헤더에서 토큰 추출
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1]; // "Bearer TOKEN"

  if (!token) {
    return res.status(401).json({ error: '인증 토큰이 필요합니다.' });
  }

  // 토큰 검증
  jwt.verify(token, process.env.JWT_SECRET, (err, user) => {
    if (err) {
      return res.status(403).json({ error: '유효하지 않은 토큰입니다.' });
    }
    req.user = user; // 사용자 정보를 요청 객체에 저장
    next(); // 다음 미들웨어로 진행
  });
}

// 사용 예시: 업로드 시 인증 필요
router.post('/upload', authenticateToken, upload.single('file'), (req, res) => {
  // req.user로 사용자 정보 접근 가능
  res.json({ message: '업로드 성공', userId: req.user.id });
});

설명

이것이 하는 일: 위 코드는 HTTP 요청 헤더에서 JWT 토큰을 추출하고 검증하여, 유효한 토큰을 가진 사용자만 다음 단계로 진행할 수 있게 하는 인증 미들웨어입니다. 파일 API의 보안 관문을 만드는 것입니다.

첫 번째로, Authorization 헤더에서 토큰을 추출합니다. 일반적으로 "Bearer eyJhbGc..." 형식으로 전송되므로, split(' ')[1]로 실제 토큰 부분만 가져옵니다.

토큰이 없으면 401 Unauthorized 에러를 반환하여, 로그인이 필요하다는 것을 클라이언트에 알립니다. 그 다음으로, jwt.verify()로 토큰의 유효성을 검증합니다.

이 과정에서 토큰이 변조되지 않았는지, 만료되지 않았는지 등을 확인합니다. process.env.JWT_SECRET은 토큰 서명에 사용된 비밀키로, 이것이 일치해야만 토큰을 복호화할 수 있습니다.

검증에 실패하면 403 Forbidden 에러를 반환합니다. 토큰이 유효하면, 토큰에 담긴 사용자 정보(user)를 req.user에 저장합니다.

이렇게 하면 이후의 미들웨어나 라우트 핸들러에서 req.user.id, req.user.email 같은 정보에 접근할 수 있습니다. 마지막으로 next()를 호출하여 다음 미들웨어(여기서는 upload.single())로 제어를 넘깁니다.

여러분이 이 미들웨어를 사용하면 파일 업로드/다운로드 API에 접근하기 위해서는 반드시 유효한 JWT 토큰이 필요하게 됩니다. 로그인하지 않은 사용자는 파일 기능을 사용할 수 없으며, 토큰이 만료된 경우 재로그인을 유도할 수 있습니다.

또한 req.user 정보를 활용하여 업로드한 파일의 소유자를 데이터베이스에 기록할 수 있어, 나중에 "내가 올린 파일" 목록을 보여주거나 삭제 권한을 체크하는 데 활용할 수 있습니다.

실전 팁

💡 401은 "인증 안됨"(로그인 필요), 403은 "권한 없음"(로그인했지만 자격 부족)을 의미합니다. 상황에 맞게 구분하여 사용하세요.

💡 토큰의 만료 시간(exp)을 짧게 설정하고, refresh token으로 갱신하는 패턴을 사용하면 보안이 강화됩니다.

💡 역할 기반 권한(RBAC)이 필요하다면 req.user.role을 확인하는 추가 미들웨어를 만드세요. 예: admin만 특정 파일을 삭제할 수 있게 제한.

💡 토큰을 쿠키에 저장하면 XSS 공격에 취약할 수 있습니다. httpOnly 쿠키를 사용하거나, 로컬스토리지 + HTTPS를 권장합니다.

💡 파일 다운로드 시에는 파일 소유자와 요청자를 비교하는 추가 검증을 넣으세요. 인증된 사용자라도 다른 사람의 파일을 다운로드하지 못하게 해야 합니다.

---

6. MIME 타입 제한

시작하며

여러분이 프로필 사진 업로드 기능을 만들었는데, 사용자가 이미지 대신 실행 파일(.exe)이나 스크립트 파일(.js)을 올린다면 어떻게 될까요? 이런 파일들이 서버에 저장되고 실행되면 심각한 보안 위협이 됩니다.

이런 문제는 파일 업로드의 가장 흔한 보안 취약점 중 하나입니다. 악의적인 사용자가 악성 코드를 업로드하거나, 이미지로 위장한 스크립트를 올려 서버를 공격하거나 다른 사용자에게 피해를 줄 수 있습니다.

바로 이럴 때 필요한 것이 MIME 타입 제한입니다. 업로드되는 파일의 종류를 검증하여 허용된 타입만 받아들이고, 위험한 파일은 업로드 단계에서 차단하는 것입니다.

개요

간단히 말해서, MIME 타입 제한은 파일의 형식을 확인하여 이미지, PDF, 문서 등 허용된 타입만 업로드할 수 있게 하는 보안 기법입니다. 마치 공항 보안 검색대에서 허용된 물품만 기내에 반입할 수 있게 하는 것처럼, 서버가 안전한 파일만 받아들이도록 필터링하는 것입니다.

왜 MIME 타입 제한이 필요할까요? 파일 확장자는 쉽게 변경할 수 있어 신뢰할 수 없기 때문입니다.

예를 들어, virus.exe를 virus.jpg로 이름만 바꿔서 올릴 수 있습니다. MIME 타입은 파일의 실제 내용을 분석하여 결정되므로 더 신뢰할 수 있는 검증 방법입니다.

기존에는 파일을 받은 후 확장자를 확인하는 단순한 방법을 사용했다면, Multer의 fileFilter 옵션을 사용하면 업로드 과정에서 실시간으로 파일 타입을 검증하고 거부할 수 있습니다. MIME 타입 제한의 핵심 특징은 첫째, 파일이 서버에 저장되기 전에 검증한다는 점입니다.

둘째, 화이트리스트 방식으로 허용할 타입만 명시하여 보안을 강화합니다. 셋째, 명확한 에러 메시지를 통해 사용자가 올바른 파일을 선택하도록 유도합니다.

이러한 특징들이 안전한 파일 업로드 시스템의 첫 번째 방어선이 됩니다.

코드 예제

// MIME 타입 검증을 포함한 Multer 설정
const multer = require('multer');

// 허용할 MIME 타입 목록
const allowedMimeTypes = [
  'image/jpeg',
  'image/png',
  'image/gif',
  'image/webp'
];

const upload = multer({
  storage: storage,
  fileFilter: function (req, file, cb) {
    // MIME 타입 확인
    if (allowedMimeTypes.includes(file.mimetype)) {
      cb(null, true); // 허용
    } else {
      // 거부 - 에러 객체 전달
      cb(new Error('이미지 파일(JPEG, PNG, GIF, WebP)만 업로드 가능합니다.'), false);
    }
  }
});

// 에러 처리 미들웨어
router.post('/upload', (req, res, next) => {
  upload.single('image')(req, res, (err) => {
    if (err instanceof multer.MulterError) {
      return res.status(400).json({ error: 'Multer 에러: ' + err.message });
    } else if (err) {
      return res.status(400).json({ error: err.message });
    }
    next();
  });
}, (req, res) => {
  res.json({ message: '업로드 성공' });
});

설명

이것이 하는 일: 위 코드는 파일이 업로드될 때 그 파일의 MIME 타입을 확인하여, 허용된 이미지 파일만 저장하고 나머지는 거부하는 필터링 시스템입니다. 파일 업로드의 첫 번째 보안 관문을 설치하는 것입니다.

첫 번째로, allowedMimeTypes 배열에 허용할 MIME 타입을 명시합니다. 'image/jpeg'는 JPEG 이미지, 'image/png'는 PNG 이미지를 의미합니다.

이렇게 화이트리스트 방식을 사용하면 명시되지 않은 모든 타입은 자동으로 거부됩니다. 블랙리스트(금지 목록) 방식보다 훨씬 안전합니다.

그 다음으로, Multer 설정에 fileFilter 함수를 추가합니다. 이 함수는 각 파일마다 호출되며, file.mimetype으로 파일의 실제 타입을 확인할 수 있습니다.

includes() 메서드로 허용 목록에 있는지 검사하여, 있으면 cb(null, true)로 허용 신호를, 없으면 Error 객체와 함께 cb()를 호출하여 거부합니다. 세 번째로, 라우트에서 에러 처리를 구현합니다.

upload.single()을 직접 미들웨어로 사용하지 않고, 함수로 호출하여 결과를 처리합니다. multer.MulterError는 Multer가 발생시키는 내장 에러(예: 파일 크기 초과)이고, 일반 Error는 우리가 fileFilter에서 발생시킨 커스텀 에러입니다.

각각 다르게 처리할 수 있습니다. 여러분이 이 코드를 사용하면 사용자가 PDF나 실행 파일을 업로드하려고 할 때 즉시 거부되고, 명확한 에러 메시지를 받게 됩니다.

이를 통해 서버에는 이미지 파일만 저장되며, 악성 파일이나 불필요한 파일로 인한 문제를 사전에 방지할 수 있습니다. 프론트엔드에서도 accept="image/*" 속성으로 파일 선택을 제한할 수 있지만, 이는 쉽게 우회할 수 있으므로 서버 측 검증이 필수입니다.

실전 팁

💡 MIME 타입은 파일 내용의 시그니처(매직 넘버)를 읽어 확인하는 file-type 라이브러리를 추가로 사용하면 더 안전합니다. 확장자 변경으로는 속일 수 없습니다.

💡 문서 업로드 시에는 'application/pdf', 'application/msword', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'(docx) 등을 허용하세요.

💡 에러 메시지에 허용되는 파일 타입을 명시하면 사용자가 무엇을 올려야 하는지 명확히 알 수 있습니다.

💡 SVG 이미지('image/svg+xml')는 스크립트를 포함할 수 있어 보안 위험이 있습니다. 반드시 필요한 경우에만 허용하고, 추가 검증을 하세요.

💡 프론트엔드와 백엔드에서 동일한 MIME 타입 목록을 사용하면 일관성 있는 검증이 가능합니다. 설정 파일로 공유하거나 API로 제공하세요.

---

7. 파일 크기 제한

시작하며

여러분이 파일 업로드 기능을 만들었는데, 사용자가 10GB 크기의 동영상을 올리려고 한다면 어떻게 될까요? 서버 메모리가 부족해지고, 업로드에 오랜 시간이 걸리며, 다른 사용자들의 요청까지 느려지는 심각한 문제가 발생합니다.

이런 문제는 파일 업로드를 제공하는 모든 서비스에서 반드시 해결해야 하는 과제입니다. 무제한으로 파일을 받으면 서버 저장소가 금방 가득 차고, 대용량 파일 전송으로 인해 네트워크 대역폭이 소진되며, 서비스 품질이 저하됩니다.

바로 이럴 때 필요한 것이 파일 크기 제한입니다. 업로드할 수 있는 파일의 최대 크기를 설정하여 서버 리소스를 보호하고, 적절한 파일 크기 내에서 안정적인 업로드 경험을 제공하는 것입니다.

개요

간단히 말해서, 파일 크기 제한은 업로드되는 파일의 최대 크기를 지정하여, 설정된 크기를 초과하는 파일은 업로드를 거부하는 기능입니다. 마치 엘리베이터의 최대 중량 제한처럼, 서버가 감당할 수 있는 범위 내의 파일만 받아들이도록 하는 것입니다.

왜 파일 크기 제한이 필요할까요? 서버의 메모리, 저장 공간, 네트워크 대역폭은 모두 유한한 자원이기 때문입니다.

예를 들어, 프로필 사진은 보통 1-2MB면 충분한데, 100MB 원본 사진을 받으면 불필요하게 공간을 낭비하고 로딩도 느려집니다. 또한 악의적인 사용자가 대용량 파일로 서버를 공격(DoS)하는 것을 막을 수 있습니다.

기존에는 파일을 모두 받은 후 크기를 확인하고 삭제하는 비효율적인 방법을 사용했다면, Multer의 limits 옵션을 사용하면 업로드 도중 크기를 초과하면 즉시 중단하여 자원 낭비를 막을 수 있습니다. 파일 크기 제한의 핵심 특징은 첫째, 업로드가 완료되기 전에 실시간으로 크기를 체크한다는 점입니다.

둘째, 다양한 단위(KB, MB)로 유연하게 설정할 수 있습니다. 셋째, 명확한 에러 메시지로 사용자가 적절한 크기의 파일을 준비하도록 안내합니다.

이러한 특징들이 서버 리소스를 효율적으로 관리하고 서비스 안정성을 유지하는 데 필수적입니다.

코드 예제

// 파일 크기 제한 설정
const multer = require('multer');

const upload = multer({
  storage: storage,
  limits: {
    fileSize: 5 * 1024 * 1024, // 5MB (바이트 단위)
    files: 10 // 최대 파일 개수
  },
  fileFilter: function (req, file, cb) {
    if (allowedMimeTypes.includes(file.mimetype)) {
      cb(null, true);
    } else {
      cb(new Error('허용되지 않는 파일 형식입니다.'), false);
    }
  }
});

// 크기 초과 에러 처리
router.post('/upload', (req, res) => {
  upload.single('file')(req, res, (err) => {
    if (err instanceof multer.MulterError) {
      if (err.code === 'LIMIT_FILE_SIZE') {
        return res.status(400).json({
          error: '파일 크기는 5MB를 초과할 수 없습니다.'
        });
      }
      return res.status(400).json({ error: err.message });
    } else if (err) {
      return res.status(400).json({ error: err.message });
    }

    res.json({
      message: '업로드 성공',
      file: req.file
    });
  });
});

설명

이것이 하는 일: 위 코드는 업로드되는 파일의 크기를 실시간으로 모니터링하여, 5MB를 초과하면 즉시 업로드를 중단하고 에러를 반환하는 크기 제한 시스템입니다. 서버의 건강을 지키는 안전장치를 설치하는 것입니다.

첫 번째로, Multer 설정에 limits 객체를 추가합니다. fileSize는 바이트 단위로 지정하므로, 5MB는 5 * 1024 * 1024로 계산합니다.

1KB = 1024바이트, 1MB = 1024KB임을 기억하세요. files 옵션은 한 번에 업로드할 수 있는 최대 파일 개수를 제한합니다.

다중 파일 업로드(upload.array()) 사용 시 유용합니다. 그 다음으로, 라우트에서 에러를 세밀하게 처리합니다.

multer.MulterError 타입인지 확인하고, err.code가 'LIMIT_FILE_SIZE'인 경우 파일 크기 초과 에러임을 알 수 있습니다. 이외에도 'LIMIT_FILE_COUNT'(파일 개수 초과), 'LIMIT_UNEXPECTED_FILE'(예상치 못한 필드명) 등 다양한 에러 코드가 있습니다.

크기 초과 에러가 발생하면, 사용자 친화적인 메시지("파일 크기는 5MB를 초과할 수 없습니다")를 반환합니다. 단순히 "파일이 너무 큽니다"보다는 구체적인 제한을 명시하는 것이 좋습니다.

사용자는 이 메시지를 보고 파일을 압축하거나 작은 버전을 준비할 수 있습니다. 여러분이 이 코드를 사용하면 대용량 파일로 인한 서버 부하를 방지할 수 있습니다.

5MB 이상의 파일은 업로드 도중 즉시 차단되므로, 불필요한 네트워크 전송과 서버 처리 시간을 절약할 수 있습니다. 또한 limits에 fieldNameSize(필드명 최대 길이), fieldSize(필드 값 최대 크기) 등 다른 제한도 설정할 수 있어 전반적인 보안을 강화할 수 있습니다.

실전 팁

💡 용도에 따라 크기 제한을 다르게 설정하세요. 프로필 사진은 2MB, 문서는 10MB, 동영상은 100MB처럼 각 엔드포인트마다 적절한 제한을 둡니다.

💡 프론트엔드에서도 파일 크기를 미리 체크하여 사용자 경험을 개선하세요. File API의 file.size로 확인 후 경고를 표시할 수 있습니다.

💡 업로드 진행률을 표시하면 큰 파일 업로드 시 사용자가 기다릴 수 있습니다. multer-progress나 직접 스트림 이벤트를 사용하세요.

💡 클라우드 스토리지 사용 시 무료 티어의 용량 제한을 고려하여 파일 크기를 설정하세요. 예상치 못한 요금 폭탄을 방지할 수 있습니다.

💡 limits.fieldSize는 텍스트 필드의 크기도 제한합니다. 파일과 함께 전송되는 메타데이터가 너무 크면 거부되므로, 필요에 따라 조정하세요.

---