fix: 템플릿 점검 결과 반영 — Node 24·이미지 위생·운영 노출 최소화

템플릿 점검에서 나온 항목을 한 번에 반영한다. 항목별 이유:

- Node 20 → 24 LTS (Dockerfile·CI): Node 20 은 2026-04-30 에 지원이 끝나 보안 패치가 없다
- backend·frontend .dockerignore 추가: `COPY . .` 가 호스트 node_modules(Windows 바이너리)·dist·
  .env*(시크릿)를 이미지에 넣고 있었다
- 업로드 디렉터리 쓰기 검사(fail-fast): Linux 에서 Docker 가 root 소유로 만든 바인드 마운트에
  비-root 앱이 쓰지 못해 첫 업로드에서야 SYS_001 로 터졌다. 기동 시 해결 명령을 안내한다
- DB 커넥션 풀 100 → 10 (DB_POOL_MAX): PostgreSQL 기본 max_connections(100)를 앱 하나가 다 잡았다
- Swagger 운영 기본 비활성 (SWAGGER_ENABLED): API 구조 전체가 공개 도메인에 노출됐다
- 헬스체크 운영 응답에서 오류 상세 제거: 드라이버 오류 문구에 내부 주소·DB 계정명이 담긴다.
  원인은 error 로그로 남긴다
- nginx: location 의 add_header 때문에 정적 자원에서 보안 헤더가 빠지던 문제와,
  index.html 이 캐시돼 배포 직후 빈 화면이 날 수 있던 문제를 고친다
- vite allowedHosts: true 제거 (DEV_ALLOWED_HOSTS): DNS rebinding 보호가 꺼져 있었다
- 전역 설정을 configureApp() 으로 분리해 main.ts 와 e2e 가 공유: e2e 가 설정을 복사해 재현해
  실제 설정과 어긋나도 통과할 수 있었다. PORT 도 빈 값을 방어하는 파서를 거친다
- 쓰이지 않던 WEBSOCKET_PORT 제거: 별도 포트는 같은 도메인 라우팅과 맞지 않는다
- 예제 useUser 가 메시지 대신 에러 코드를 보관하도록 수정, testing.md 표 깨짐 수정,
  settings.json 허용 목록에서 npm install 제거 (Windows lock 파일 규칙과 충돌)

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

backend/.dockerignore

@@ -0,0 +1,25 @@
+# ==========================================
+# 빌드 컨텍스트에서 제외할 파일
+#
+# Dockerfile 의 `COPY . .` 가 아래 항목까지 이미지에 넣지 않도록 막는다.
+# ==========================================
+
+# 의존성·빌드 산출물 — 컨테이너 안에서 npm ci·빌드를 다시 한다.
+# 호스트(Windows) node_modules 가 섞이면 네이티브 바이너리가 리눅스용을 덮어써 컨테이너가 깨진다.
+node_modules
+dist
+coverage
+
+# 시크릿 — 이미지에 굽지 않는다. 실행 시 compose 의 env_file/environment 로 주입된다.
+.env
+.env.*
+
+# 런타임 데이터·로그
+uploads
+logs
+*.log
+
+# 에디터·OS
+.vscode
+.idea
+.DS_Store

backend/Dockerfile

@@ -1,8 +1,8 @@
-FROM node:20-alpine AS builder
+FROM node:24-alpine AS builder
 WORKDIR /app
 
-# 호스트의 npm 11 이 작성한 package-lock.json 형식과 호환되도록 npm 을 11 로 업그레이드
-# (전역 설치는 root 권한이 필요하므로 USER 전환 전에 수행)
+# 호스트의 npm 11 이 작성한 package-lock.json 형식과 호환되도록 npm 을 11 로 고정
+# (베이스 이미지의 번들 npm 이 바뀌어도 lock 형식이 어긋나지 않게 한다. 전역 설치는 root 권한이 필요하므로 USER 전환 전에 수행)
 RUN npm install -g npm@11
 
 # 개발 환경(docker-compose.dev.yml)은 이 스테이지를 그대로 구동하므로 비-root 로 전환한다.
@@ -14,10 +14,11 @@ USER node
 COPY --chown=node:node package*.json ./
 RUN npm ci
 
+# 호스트의 node_modules·dist·.env 는 .dockerignore 로 제외된다
 COPY --chown=node:node . .
 RUN npm run build
 
-FROM node:20-alpine AS production
+FROM node:24-alpine AS production
 WORKDIR /app
 
 ENV NODE_ENV=production
@@ -31,9 +32,13 @@ RUN npm ci --omit=dev && npm cache clean --force
 
 COPY --from=builder /app/dist ./dist
 
+# 업로드 디렉터리를 node 소유로 미리 만든다 — 볼륨 없이 띄우거나 named volume 을 붙여도 비-root 앱이 쓸 수 있다.
+# 호스트 디렉터리를 바인드 마운트하면 호스트 쪽 소유권을 따른다 (README "운영 배포" 의 chown 참조)
+RUN mkdir -p /app/uploads && chown node:node /app/uploads
+
 EXPOSE 3000
 
 # 비-root 실행 (보안 규칙)
 USER node
 
-CMD ["node", "dist/main"]
+CMD ["node", "dist/main"]

backend/src/app.setup.spec.ts

@@ -0,0 +1,88 @@
+import { Controller, Get, INestApplication, Logger } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+import request from 'supertest';
+import type { Response } from 'supertest';
+import { App } from 'supertest/types';
+
+import { configureApp } from '@/app.setup';
+import { BusinessException } from '@/common/errors/business.exception';
+
+/** 전역 설정만 검증하기 위한 최소 컨트롤러 — DB 가 필요 없다 */
+@Controller('ping')
+class PingController {
+  @Get()
+  ping(): { pong: boolean } {
+    return { pong: true };
+  }
+
+  @Get('missing')
+  missing(): never {
+    throw new BusinessException('RES_001');
+  }
+}
+
+/** supertest 의 body 는 any 이므로 계약 형태로 좁혀서 읽는다 */
+interface ContractBody {
+  success?: boolean;
+  data?: unknown;
+  error?: { code?: string };
+}
+
+const body = (res: Response): ContractBody => res.body as ContractBody;
+
+describe('configureApp (main.ts·e2e 공유 전역 설정)', () => {
+  let app: INestApplication<App>;
+
+  beforeAll(async () => {
+    // 의도된 실패 응답의 경고 로그가 테스트 출력을 오염시키지 않도록 억제
+    jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+
+    const moduleRef = await Test.createTestingModule({
+      controllers: [PingController],
+    }).compile();
+
+    app = moduleRef.createNestApplication();
+    configureApp(app);
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app.close();
+    jest.restoreAllMocks();
+  });
+
+  it('라우트는 /api 아래에 놓이고 성공 응답은 { success, data } 로 감싸진다', async () => {
+    const res = await request(app.getHttpServer()).get('/api/ping').expect(200);
+
+    expect(body(res)).toEqual({ success: true, data: { pong: true } });
+  });
+
+  it('prefix 밖의 루트(/)는 상태 확인 텍스트를 돌려준다 (docker healthcheck)', async () => {
+    const res = await request(app.getHttpServer()).get('/').expect(200);
+
+    expect(res.text).toContain('정상 구동');
+  });
+
+  it('실패는 전역 필터가 에러 코드 응답으로 바꾼다', async () => {
+    const res = await request(app.getHttpServer())
+      .get('/api/ping/missing')
+      .expect(404);
+
+    expect(body(res).success).toBe(false);
+    expect(body(res).error?.code).toBe('RES_001');
+  });
+
+  it('보안 헤더(helmet)가 붙는다', async () => {
+    const res = await request(app.getHttpServer()).get('/api/ping');
+
+    expect(res.headers['x-content-type-options']).toBe('nosniff');
+  });
+
+  it('화이트리스트 밖 오리진에는 CORS 헤더를 주지 않는다', async () => {
+    const res = await request(app.getHttpServer())
+      .get('/api/ping')
+      .set('Origin', 'https://other.io');
+
+    expect(res.headers['access-control-allow-origin']).toBeUndefined();
+  });
+});

backend/src/app.setup.ts

@@ -0,0 +1,67 @@
+import {
+  INestApplication,
+  RequestMethod,
+  ValidationPipe,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import helmet from 'helmet';
+import type {
+  Express,
+  Request as ExpressRequest,
+  Response as ExpressResponse,
+} from 'express';
+
+import { HttpExceptionFilter } from '@/common/filters/http-exception.filter';
+import { TransformInterceptor } from '@/common/interceptors/transform.interceptor';
+import { buildCorsOptions } from '@/shared/config/cors.config';
+
+/** 모든 라우트의 공통 prefix — Flutter·Web 의 baseURL, 리버스 프록시의 location /api 와 맞물려 있다 */
+export const GLOBAL_PREFIX = 'api';
+
+/**
+ * 앱 전역 설정 — main.ts 와 e2e 테스트가 **같은 함수**를 쓴다.
+ * 테스트가 설정을 따로 흉내 내면 둘이 어긋나도 테스트는 통과해 버린다.
+ * 리스닝·Swagger·종료 훅처럼 실행 환경에만 필요한 것은 main.ts 에 둔다.
+ */
+export function configureApp(app: INestApplication): void {
+  // 리버스 프록시 뒤에서 실제 클라이언트 IP 를 식별한다 (rate limit 이 IP 기준이다).
+  // 운영은 Nginx Proxy Manager → backend 로 한 번 거친다 (Custom location 이 X-Forwarded-For 에 클라이언트 IP 를 싣는다).
+  const expressApp = app.getHttpAdapter().getInstance() as Express;
+  expressApp.set('trust proxy', 1);
+
+  // 글로벌 prefix — 모든 라우트가 /api/* 로 정규화됨 (Flutter, Web 양쪽 baseURL과 일치)
+  // 리버스 프록시(운영 NPM · 개발 vite)는 /api 로 시작하는 요청을 경로 그대로 넘기므로 이 prefix 와 맞물려 있다.
+  app.setGlobalPrefix(GLOBAL_PREFIX, {
+    // 헬스체크 / 루트 상태 엔드포인트는 prefix 미적용
+    exclude: [{ path: '/', method: RequestMethod.GET }],
+  });
+
+  // 기본 주소('/') 접속 시 상태 확인용 텍스트 응답 — docker healthcheck 가 사용한다
+  expressApp.get('/', (_req: ExpressRequest, res: ExpressResponse) => {
+    res.send('Backend API Server is running 정상 구동 중입니다.');
+  });
+
+  // 1. 보안 헤더 (Helmet) - XSS 방지 및 기본 웹 보안
+  app.use(helmet());
+
+  // 2. CORS — 기본 구성은 프론트와 API 가 같은 도메인이라(브라우저는 /api 상대경로로 호출) 필요 없다.
+  //    다른 오리진에서 호출해야 할 때만 루트 .env 의 CORS_ORIGIN 에 콤마로 나열한다 (shared/config/cors.config.ts)
+  app.enableCors(buildCorsOptions());
+
+  // 3. Rate Limiting 은 AppModule 의 ThrottlerGuard(APP_GUARD)로 일원화되어 있다.
+  //    라우트 단위 제어(@Throttle / @SkipThrottle)가 가능하고, 한도 초과는 REQ_001(429)로 응답된다.
+  //    (전역 예외 필터가 429 → REQ_001 로 매핑한다 — .claude/rules/error-codes.md)
+
+  // 4. 전역 DTO 유효성 파이프 (강력한 검증 단계)
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true, // DTO에 불필요한 값이 오면 삭제
+      forbidNonWhitelisted: true, // DTO에 없는 필드가 주입되면 400 에러 발생
+      transform: true, // 네트워크 데이터를 DTO나 기본 타입으로 자동 변환
+    }),
+  );
+
+  // 5. 프론트엔드 연동을 위한 규격화된 에러 & 성공 페이로드 인터셉터 적용
+  app.useGlobalFilters(new HttpExceptionFilter());
+  app.useGlobalInterceptors(new TransformInterceptor(app.get(Reflector)));
+}

backend/src/main.ts

@@ -1,92 +1,52 @@
 import { NestFactory } from '@nestjs/core';
 import { AppModule } from './app.module';
-import { Logger, RequestMethod, ValidationPipe } from '@nestjs/common';
-import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { Logger } from '@nestjs/common';
 import { WinstonModule } from 'nest-winston';
-import helmet from 'helmet';
-import type {
-  Express,
-  Request as ExpressRequest,
-  Response as ExpressResponse,
-} from 'express';
 
-import { Reflector } from '@nestjs/core';
-
-import { HttpExceptionFilter } from '@/common/filters/http-exception.filter';
-import { TransformInterceptor } from '@/common/interceptors/transform.interceptor';
-import { buildCorsOptions } from '@/shared/config/cors.config';
+import { configureApp, GLOBAL_PREFIX } from '@/app.setup';
+import {
+  isSwaggerEnabled,
+  setupSwagger,
+  SWAGGER_PATH,
+} from '@/shared/config/swagger.config';
 import { winstonConfig } from '@/shared/logger/winston.config';
+import { parsePositiveInt } from '@/shared/utils/env';
+
+/** 루트 .env 에 BACKEND_PORT 가 없을 때만 쓰는 기본 포트 */
+const DEFAULT_PORT = 3000;
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule, {
     logger: WinstonModule.createLogger(winstonConfig),
   });
 
-  // 리버스 프록시 뒤에서 실제 클라이언트 IP 를 식별한다 (rate limit 이 IP 기준이다).
-  // 운영은 Nginx Proxy Manager → backend 로 한 번 거친다 (Custom location 이 X-Forwarded-For 에 클라이언트 IP 를 싣는다).
-  const expressApp = app.getHttpAdapter().getInstance() as Express;
-  expressApp.set('trust proxy', 1);
+  // 보안 헤더·CORS·prefix·검증 파이프·응답 래퍼 등 전역 설정 — e2e 테스트와 같은 함수를 쓴다 (app.setup.ts)
+  configureApp(app);
 
-  // 글로벌 prefix — 모든 라우트가 /api/* 로 정규화됨 (Flutter, Web 양쪽 baseURL과 일치)
-  // 리버스 프록시(운영 NPM · 개발 vite)는 /api 로 시작하는 요청을 경로 그대로 넘기므로 이 prefix 와 맞물려 있다.
-  app.setGlobalPrefix('api', {
-    // 헬스체크 / 루트 상태 엔드포인트는 prefix 미적용
-    exclude: [{ path: '/', method: RequestMethod.GET }],
-  });
+  // Swagger API 문서 — 운영에서는 기본으로 끈다 (shared/config/swagger.config.ts)
+  const swaggerEnabled = isSwaggerEnabled();
+  if (swaggerEnabled) setupSwagger(app);
 
-  // 기본 주소('/') 접속 시 상태 확인용 텍스트 응답 추가
-  expressApp.get('/', (_req: ExpressRequest, res: ExpressResponse) => {
-    res.send('Backend API Server is running 정상 구동 중입니다.');
-  });
-
-  // 1. 보안 헤더 (Helmet) - XSS 방지 및 기본 웹 보안
-  app.use(helmet());
-
-  // 2. CORS — 기본 구성은 프론트와 API 가 같은 도메인이라(브라우저는 /api 상대경로로 호출) 필요 없다.
-  //    다른 오리진에서 호출해야 할 때만 루트 .env 의 CORS_ORIGIN 에 콤마로 나열한다 (shared/config/cors.config.ts)
-  app.enableCors(buildCorsOptions());
-
-  // 3. Rate Limiting 은 AppModule 의 ThrottlerGuard(APP_GUARD)로 일원화되어 있다.
-  //    라우트 단위 제어(@Throttle / @SkipThrottle)가 가능하고, 한도 초과는 REQ_001(429)로 응답된다.
-  //    (전역 예외 필터가 429 → REQ_001 로 매핑한다 — .claude/rules/error-codes.md)
-
-  // 4. 전역 DTO 유효성 파이프 (강력한 검증 단계)
-  app.useGlobalPipes(
-    new ValidationPipe({
-      whitelist: true, // DTO에 불필요한 값이 오면 삭제
-      forbidNonWhitelisted: true, // DTO에 없는 필드가 주입되면 400 에러 발생
-      transform: true, // 네트워크 데이터를 DTO나 기본 타입으로 자동 변환
-    }),
-  );
-
-  // 5. 프론트엔드 연동을 위한 규격화된 에러 & 성공 페이로드 인터셉터 적용
-  app.useGlobalFilters(new HttpExceptionFilter());
-  app.useGlobalInterceptors(new TransformInterceptor(app.get(Reflector)));
-
-  // 6. Swagger API 문서 설정
-  const config = new DocumentBuilder()
-    .setTitle('Backend API Documentation')
-    .setDescription('The API documentation conforming to the global guidelines')
-    .setVersion('1.0')
-    .addBearerAuth()
-    .build();
-  const document = SwaggerModule.createDocument(app, config);
-  SwaggerModule.setup('api-docs', app, document);
-
-  // 7. Graceful shutdown — SIGTERM 수신 시 새 요청을 받지 않고
-  //    처리 중인 요청을 마친 뒤 DB/Redis 커넥션을 정리하고 종료한다.
-  //    (이 설정이 없으면 배포·재시작 때 처리 중이던 요청이 그대로 끊긴다)
+  // Graceful shutdown — SIGTERM 수신 시 새 요청을 받지 않고
+  // 처리 중인 요청을 마친 뒤 DB/Redis 커넥션을 정리하고 종료한다.
+  // (이 설정이 없으면 배포·재시작 때 처리 중이던 요청이 그대로 끊긴다)
   app.enableShutdownHooks();
 
-  //    종료 로그는 ShutdownLogger(OnApplicationShutdown)가 남긴다.
+  // 종료 로그는 ShutdownLogger(OnApplicationShutdown)가 남긴다.
 
-  const port = Number(process.env.PORT ?? 3000);
+  // compose 가 미정의 변수를 빈 문자열로 주입하므로 parsePositiveInt 로 방어한다 (Number('') 는 0 → 임의 포트)
+  const port = parsePositiveInt(process.env.PORT, DEFAULT_PORT);
   await app.listen(port, '0.0.0.0');
-  Logger.log(`🚀 Backend running on http://localhost:${port}/api`, 'Bootstrap');
   Logger.log(
-    `📘 Swagger docs at  http://localhost:${port}/api-docs`,
+    `🚀 Backend running on http://localhost:${port}/${GLOBAL_PREFIX}`,
     'Bootstrap',
   );
+  if (swaggerEnabled) {
+    Logger.log(
+      `📘 Swagger docs at  http://localhost:${port}/${SWAGGER_PATH}`,
+      'Bootstrap',
+    );
+  }
 }
 
 void bootstrap();

backend/src/modules/health/health.controller.spec.ts

@@ -1,4 +1,8 @@
-import { HttpStatus, ServiceUnavailableException } from '@nestjs/common';
+import {
+  HttpStatus,
+  Logger,
+  ServiceUnavailableException,
+} from '@nestjs/common';
 import { Test, TestingModule } from '@nestjs/testing';
 import {
   HealthCheckResult,
@@ -29,6 +33,15 @@ describe('HealthController', () => {
   let check: jest.Mock;
   let res: { status: jest.Mock };
 
+  beforeAll(() => {
+    // 의도된 실패의 error 로그가 테스트 출력을 오염시키지 않도록 억제
+    jest.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined);
+  });
+
+  afterAll(() => {
+    jest.restoreAllMocks();
+  });
+
   beforeEach(async () => {
     check = jest.fn();
     res = { status: jest.fn() };
@@ -74,6 +87,28 @@ describe('HealthController', () => {
     expect(JSON.stringify(result)).toContain('database');
   });
 
+  it('운영에서는 구성요소별 status 만 노출한다 (오류 문구에 내부 주소·계정이 담길 수 있다)', async () => {
+    const originalEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'production';
+    check.mockRejectedValue(new ServiceUnavailableException(downResult));
+
+    try {
+      const result = await controller.check(res as unknown as Response);
+
+      expect(res.status).toHaveBeenCalledWith(HttpStatus.SERVICE_UNAVAILABLE);
+      // 어느 구성요소가 죽었는지는 그대로 보인다
+      expect(result).toEqual({
+        status: 'error',
+        info: {},
+        error: { database: { status: 'down' } },
+        details: { database: { status: 'down' } },
+      });
+      expect(JSON.stringify(result)).not.toContain('timeout');
+    } finally {
+      process.env.NODE_ENV = originalEnv;
+    }
+  });
+
   it('terminus 예외가 아닌 오류는 전역 필터로 넘긴다', async () => {
     check.mockRejectedValue(new Error('예상치 못한 오류'));
 

backend/src/modules/health/health.controller.ts

@@ -2,6 +2,7 @@ import {
   Controller,
   Get,
   HttpStatus,
+  Logger,
   Res,
   ServiceUnavailableException,
 } from '@nestjs/common';
@@ -11,17 +12,46 @@ import {
   HealthCheck,
   HealthCheckResult,
   HealthCheckService,
+  HealthIndicatorResult,
   TypeOrmHealthIndicator,
 } from '@nestjs/terminus';
 import type { Response } from 'express';
 
 import { SkipTransform } from '@/common/decorators/skip-transform.decorator';
+import { isProductionEnv } from '@/shared/utils/env';
 
 // DB ping 타임아웃 — 기본값 1000ms 는 너무 짧다.
 // 커넥션 풀의 유휴 커넥션이 정리된 뒤(idleTimeoutMillis) 재연결하는 경우 1초를 넘겨
 // 정상인 DB 를 down 으로 오판하고 헬스체크가 간헐적으로 실패한다.
 const DB_PING_TIMEOUT_MS = 5_000;
 
+/** 구성요소별 결과에서 status 만 남긴다 */
+function keepStatusOnly(
+  section: Partial<HealthIndicatorResult> | undefined,
+): HealthIndicatorResult {
+  return Object.fromEntries(
+    Object.entries(section ?? {}).flatMap(([key, value]) =>
+      value ? [[key, { status: value.status }]] : [],
+    ),
+  );
+}
+
+/**
+ * 실패 결과에서 구성요소별 status 만 남기고 오류 문구(message 등)는 뺀다.
+ * 드라이버 오류 문구에는 내부 주소·DB 계정명이 담길 수 있다 ("connect ECONNREFUSED 172.18.0.2:5432").
+ * 어느 구성요소가 죽었는지는 그대로 보이므로 모니터링에는 지장이 없다. 원인은 서버 로그에 남는다.
+ */
+export function hideFailureDetails(
+  result: HealthCheckResult,
+): HealthCheckResult {
+  return {
+    status: result.status,
+    info: keepStatusOnly(result.info),
+    error: keepStatusOnly(result.error),
+    details: keepStatusOnly(result.details),
+  };
+}
+
 /**
  * 헬스체크 엔드포인트 — Docker healthcheck, 모니터링 시스템이 읽는다.
  *
@@ -30,6 +60,7 @@ const DB_PING_TIMEOUT_MS = 5_000;
  *
  * - 성공 200: `{ status: 'ok', info: { database: { status: 'up' } }, ... }`
  * - 실패 503: `{ status: 'error', error: { database: { status: 'down', message } }, ... }`
+ *   (운영에서는 message 같은 상세를 빼고 구성요소별 status 만 노출한다 — 원인은 error 로그로 남긴다)
  *
  * 주기적으로 호출되므로 rate limit 대상에서도 제외한다 (한도를 소진시켜 실제 요청을 막으면 안 된다).
  */
@@ -38,6 +69,8 @@ const DB_PING_TIMEOUT_MS = 5_000;
 @ApiTags('Health')
 @Controller('health')
 export class HealthController {
+  private readonly logger = new Logger(HealthController.name);
+
   constructor(
     private readonly health: HealthCheckService,
     private readonly db: TypeOrmHealthIndicator,
@@ -64,8 +97,13 @@ export class HealthController {
       // terminus 는 실패 시 ServiceUnavailableException 을 던지며 본문에 상세 결과를 담는다.
       // 전역 필터가 SYS_001 로 덮어쓰지 않도록 여기서 직접 503 과 원본 본문을 반환한다.
       if (error instanceof ServiceUnavailableException) {
+        const result = error.getResponse() as HealthCheckResult;
+
+        // 서버 책임 장애(DB 접속 실패 등)이므로 error 레벨 — 운영에서 응답에서 뺀 원인을 여기서 추적한다
+        this.logger.error(`헬스체크 실패: ${JSON.stringify(result.error)}`);
+
         res.status(HttpStatus.SERVICE_UNAVAILABLE);
-        return error.getResponse() as HealthCheckResult;
+        return isProductionEnv() ? hideFailureDetails(result) : result;
       }
       throw error;
     }

backend/src/modules/upload/upload.config.spec.ts

@@ -1,4 +1,42 @@
-import { allowedExtensionList, isAllowedFile } from './upload.config';
+import fs, { existsSync, mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import {
+  allowedExtensionList,
+  ensureUploadDir,
+  isAllowedFile,
+} from './upload.config';
+
+describe('업로드 디렉터리 준비', () => {
+  let base: string;
+
+  beforeEach(() => {
+    base = mkdtempSync(join(tmpdir(), 'upload-dir-'));
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  it('없는 디렉터리는 하위 경로까지 만든다', () => {
+    const dir = join(base, 'nested', 'uploads');
+
+    ensureUploadDir(dir);
+
+    expect(existsSync(dir)).toBe(true);
+  });
+
+  it('쓸 수 없으면 소유권을 맞추는 방법과 함께 기동을 멈춘다', () => {
+    // Linux 에서 root 소유로 만들어진 바인드 마운트를 흉내 낸다 (Windows 는 디렉터리 권한을 재현할 수 없다)
+    jest.spyOn(fs, 'accessSync').mockImplementation(() => {
+      throw new Error('EACCES: permission denied');
+    });
+
+    expect(() => ensureUploadDir(base)).toThrow(/sudo chown -R 1000:1000/);
+  });
+});
 
 describe('파일 업로드 검증', () => {
   it('확장자와 MIME 이 모두 맞으면 통과한다', () => {

backend/src/modules/upload/upload.config.ts

@@ -1,3 +1,4 @@
+import { accessSync, constants, mkdirSync } from 'fs';
 import { extname } from 'path';
 
 import { parsePositiveInt } from '@/shared/utils/env';
@@ -12,6 +13,29 @@ import { parsePositiveInt } from '@/shared/utils/env';
 /** 업로드 파일 저장 디렉터리 — 컨테이너에서는 compose 볼륨이 연결된다 */
 export const UPLOAD_DIR = process.env.UPLOAD_DIR ?? './uploads';
 
+/**
+ * 업로드 디렉터리를 만들고 **쓰기 가능한지** 확인한다 — 안 되면 기동을 멈춘다 (fail-fast).
+ *
+ * 컨테이너의 앱은 비-root(node, uid 1000)로 실행된다. Linux 서버에서 compose 가
+ * 없는 호스트 디렉터리를 바인드 마운트하면 root 소유로 만들어지므로,
+ * 그대로 두면 서버는 뜨지만 첫 업로드에서야 SYS_001 로 터진다.
+ */
+export function ensureUploadDir(dir: string): void {
+  try {
+    mkdirSync(dir, { recursive: true });
+    accessSync(dir, constants.W_OK);
+  } catch (error) {
+    throw new Error(
+      [
+        `업로드 디렉터리에 쓸 수 없어 서버를 시작할 수 없습니다: ${dir}`,
+        `  (${error instanceof Error ? error.message : String(error)})`,
+        '컨테이너의 앱은 node(uid 1000)로 실행됩니다. 호스트의 업로드 디렉터리 소유자를 맞춰 주세요:',
+        '  sudo chown -R 1000:1000 ./data/uploads   # UPLOAD_DATA_DIR 을 바꿨다면 그 경로',
+      ].join('\n'),
+    );
+  }
+}
+
 const MEGABYTE = 1024 * 1024;
 
 /** 파일 1개 최대 크기 (기본 5MB) */

backend/src/modules/upload/upload.module.ts

@@ -2,20 +2,20 @@ import { Module } from '@nestjs/common';
 import { MulterModule } from '@nestjs/platform-express';
 import { randomUUID } from 'crypto';
 import { diskStorage } from 'multer';
-import { mkdirSync } from 'fs';
 import { extname } from 'path';
 
 import { BusinessException } from '@/common/errors/business.exception';
 import {
   MAX_FILE_SIZE_BYTES,
   UPLOAD_DIR,
+  ensureUploadDir,
   isAllowedFile,
 } from './upload.config';
 import { UploadController } from './upload.controller';
 import { UploadService } from './upload.service';
 
-// 저장 디렉터리는 기동 시 한 번 보장한다 (없으면 multer 가 매 요청 실패한다)
-mkdirSync(UPLOAD_DIR, { recursive: true });
+// 저장 디렉터리는 기동 시 한 번 보장한다 (없거나 쓸 수 없으면 multer 가 매 요청 실패한다)
+ensureUploadDir(UPLOAD_DIR);
 
 @Module({
   imports: [

backend/src/shared/config/database.config.spec.ts

@@ -0,0 +1,32 @@
+import { buildDatabaseOptions } from './database.config';
+
+/** 풀 설정은 드라이버 옵션(extra)으로 넘어간다 */
+const poolMax = (): number =>
+  (buildDatabaseOptions().extra as { max: number }).max;
+
+describe('buildDatabaseOptions — 커넥션 풀 크기', () => {
+  const original = process.env.DB_POOL_MAX;
+
+  afterEach(() => {
+    if (original === undefined) {
+      delete process.env.DB_POOL_MAX;
+    } else {
+      process.env.DB_POOL_MAX = original;
+    }
+  });
+
+  it('기본값은 10 이다 (PostgreSQL 기본 max_connections 100 을 앱 하나가 다 잡지 않게)', () => {
+    delete process.env.DB_POOL_MAX;
+    expect(poolMax()).toBe(10);
+  });
+
+  it('DB_POOL_MAX 로 조정할 수 있다', () => {
+    process.env.DB_POOL_MAX = '25';
+    expect(poolMax()).toBe(25);
+  });
+
+  it('빈 값이면 기본값을 쓴다 (compose 가 미정의 변수를 빈 문자열로 넘긴다)', () => {
+    process.env.DB_POOL_MAX = '';
+    expect(poolMax()).toBe(10);
+  });
+});

backend/src/shared/config/database.config.ts

@@ -1,7 +1,7 @@
 import { join } from 'path';
 import { DataSourceOptions } from 'typeorm';
 
-import { parsePositiveInt } from '@/shared/utils/env';
+import { isProductionEnv, parsePositiveInt } from '@/shared/utils/env';
 
 /**
  * DB 접속 설정 — 앱(TypeOrmModule)과 CLI(data-source.ts)가 **같은 설정을 공유**한다.
@@ -19,17 +19,21 @@ const DEV_DB_DEFAULTS = {
   database: 'project_db',
 } as const;
 
-/** 커넥션 풀 설정 */
-const POOL_OPTIONS = {
-  max: 100,
+/**
+ * 커넥션 풀 크기 기본값 — node-postgres 의 기본값과 같다.
+ *
+ * PostgreSQL 의 기본 max_connections 는 100 이다. 풀을 100 으로 두면 앱 하나가 접속을 다 잡아
+ * 마이그레이션 CLI·psql·두 번째 인스턴스가 "too many clients" 로 붙지 못한다.
+ * 인스턴스 수 × DB_POOL_MAX 에 여유분을 더한 값이 max_connections 를 넘지 않게 루트 .env 에서 조정한다.
+ */
+const DEFAULT_POOL_MAX = 10;
+
+/** 커넥션 풀 타임아웃 */
+const POOL_TIMEOUTS = {
   connectionTimeoutMillis: 5000,
   idleTimeoutMillis: 30000,
 } as const;
 
-export function isProductionEnv(): boolean {
-  return process.env.NODE_ENV === 'production';
-}
-
 /**
  * 스키마 자동 동기화 사용 여부.
  *
@@ -72,7 +76,11 @@ export function buildDatabaseOptions(): DataSourceOptions {
     // 운영 배포 시 미적용 마이그레이션을 자동 실행한다
     migrationsRun: isProduction,
     logging: !isProduction,
-    extra: { ...POOL_OPTIONS },
+    extra: {
+      ...POOL_TIMEOUTS,
+      // compose 가 미정의 변수를 빈 문자열로 주입하므로 parsePositiveInt 로 방어한다
+      max: parsePositiveInt(process.env.DB_POOL_MAX, DEFAULT_POOL_MAX),
+    },
     entities: paths.entities,
     migrations: paths.migrations,
   };

backend/src/shared/config/env.validation.spec.ts

@@ -32,6 +32,22 @@ describe('validateEnv', () => {
         validateEnv({ NODE_ENV: 'development', THROTTLE_LIMIT: '' }),
       ).not.toThrow();
     });
+
+    it('DB 커넥션 풀 크기도 양의 정수여야 한다', () => {
+      expect(() =>
+        validateEnv({ NODE_ENV: 'development', DB_POOL_MAX: '0' }),
+      ).toThrow(/DB_POOL_MAX 는 양의 정수/);
+    });
+
+    it('SWAGGER_ENABLED 는 true/false 만 받는다 (오타가 기본값으로 묻히지 않게)', () => {
+      expect(() =>
+        validateEnv({ NODE_ENV: 'development', SWAGGER_ENABLED: 'ture' }),
+      ).toThrow(/SWAGGER_ENABLED 는 true 또는 false/);
+
+      expect(() =>
+        validateEnv({ NODE_ENV: 'development', SWAGGER_ENABLED: '' }),
+      ).not.toThrow();
+    });
   });
 
   describe('CORS_ORIGIN 형식 (모든 환경)', () => {

backend/src/shared/config/env.validation.ts

@@ -24,10 +24,14 @@ const REQUIRED_IN_PRODUCTION = [
 const POSITIVE_INT_KEYS = [
   'PORT',
   'DB_PORT',
+  'DB_POOL_MAX',
   'THROTTLE_TTL_MS',
   'THROTTLE_LIMIT',
 ] as const;
 
+/** 값이 있다면 true/false 여야 하는 키 — 오타(ture 등)가 조용히 기본값으로 처리되지 않게 한다 */
+const BOOLEAN_KEYS = ['SWAGGER_ENABLED'] as const;
+
 /** 운영 환경에서 placeholder 로 남아 있으면 안 되는 키 */
 const NO_PLACEHOLDER_IN_PRODUCTION = [
   'DB_PASSWORD',
@@ -99,7 +103,17 @@ export function validateEnv(
     }
   }
 
-  // 2. CORS 오리진 형식 — 브라우저 Origin 헤더와 모양이 다르면 절대 일치하지 않아 **조용히** 막힌다
+  // 2. 참/거짓 값 — 비어 있으면 코드의 기본 동작을 따른다
+  for (const key of BOOLEAN_KEYS) {
+    const value = readString(config, key);
+    if (value !== undefined && value !== 'true' && value !== 'false') {
+      errors.push(
+        `${key} 는 true 또는 false 여야 합니다. (현재 값: "${value}")`,
+      );
+    }
+  }
+
+  // 3. CORS 오리진 형식 — 브라우저 Origin 헤더와 모양이 다르면 절대 일치하지 않아 **조용히** 막힌다
   for (const origin of parseCorsOrigins(readString(config, 'CORS_ORIGIN'))) {
     if (!isValidOrigin(origin)) {
       errors.push(
@@ -109,14 +123,14 @@ export function validateEnv(
   }
 
   if (isProduction) {
-    // 3. 운영 필수값 — 없으면 기동 실패
+    // 4. 운영 필수값 — 없으면 기동 실패
     for (const key of REQUIRED_IN_PRODUCTION) {
       if (readString(config, key) === undefined) {
         errors.push(`${key} 가 설정되지 않았습니다. (운영 환경 필수)`);
       }
     }
 
-    // 4. 예시 파일의 placeholder 가 그대로 배포되는 것을 막는다
+    // 5. 예시 파일의 placeholder 가 그대로 배포되는 것을 막는다
     for (const key of NO_PLACEHOLDER_IN_PRODUCTION) {
       const value = readString(config, key);
       if (value !== undefined && looksLikePlaceholder(value)) {
@@ -126,7 +140,7 @@ export function validateEnv(
       }
     }
 
-    // 5. 공개 주소가 로컬 주소·예시 도메인으로 남은 채 배포되는 것을 막는다
+    // 6. 공개 주소가 로컬 주소·예시 도메인으로 남은 채 배포되는 것을 막는다
     const allowLocalhostUrl =
       readString(config, ALLOW_LOCALHOST_URL_KEY) === 'true';
 

backend/src/shared/config/swagger.config.spec.ts

@@ -0,0 +1,24 @@
+import { isSwaggerEnabled } from './swagger.config';
+
+describe('isSwaggerEnabled', () => {
+  it('운영에서는 기본으로 끈다 (API 구조 전체가 공개되므로)', () => {
+    expect(isSwaggerEnabled({ NODE_ENV: 'production' })).toBe(false);
+    expect(
+      isSwaggerEnabled({ NODE_ENV: 'production', SWAGGER_ENABLED: '' }),
+    ).toBe(false);
+  });
+
+  it('운영이 아니면 기본으로 켠다', () => {
+    expect(isSwaggerEnabled({ NODE_ENV: 'development' })).toBe(true);
+    expect(isSwaggerEnabled({})).toBe(true);
+  });
+
+  it('SWAGGER_ENABLED 를 명시하면 환경과 무관하게 따른다', () => {
+    expect(
+      isSwaggerEnabled({ NODE_ENV: 'production', SWAGGER_ENABLED: 'true' }),
+    ).toBe(true);
+    expect(
+      isSwaggerEnabled({ NODE_ENV: 'development', SWAGGER_ENABLED: 'false' }),
+    ).toBe(false);
+  });
+});

backend/src/shared/config/swagger.config.ts

@@ -0,0 +1,41 @@
+import { INestApplication } from '@nestjs/common';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+
+import { isProductionEnv } from '@/shared/utils/env';
+
+/**
+ * Swagger UI 경로.
+ * 같은 도메인 구성에서는 리버스 프록시의 location /api 접두어 매칭에 함께 걸려 백엔드로 간다.
+ */
+export const SWAGGER_PATH = 'api-docs';
+
+/**
+ * Swagger 문서 노출 여부.
+ * 문서는 API 구조 전체(경로·파라미터·스키마)를 보여주므로 **운영에서는 기본으로 끈다.**
+ *
+ * - SWAGGER_ENABLED=true  → 항상 켠다 (운영에서 켤 때는 NPM Access List 등으로 접근을 제한한다)
+ * - SWAGGER_ENABLED=false → 항상 끈다
+ * - 비어 있음             → 운영이 아니면 켠다
+ */
+export function isSwaggerEnabled(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  const flag = env.SWAGGER_ENABLED?.trim();
+  if (flag === 'true') return true;
+  if (flag === 'false') return false;
+
+  return !isProductionEnv(env);
+}
+
+/** Swagger 문서를 SWAGGER_PATH 에 붙인다 */
+export function setupSwagger(app: INestApplication): void {
+  const config = new DocumentBuilder()
+    .setTitle('Backend API Documentation')
+    .setDescription('The API documentation conforming to the global guidelines')
+    .setVersion('1.0')
+    .addBearerAuth()
+    .build();
+
+  const document = SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup(SWAGGER_PATH, app, document);
+}

backend/src/shared/utils/env.ts

@@ -20,3 +20,11 @@ export function parsePositiveInt(
 
   return parsed;
 }
+
+/**
+ * 운영 환경인지 확인한다.
+ * NODE_ENV 는 compose 가 루트 APP_ENV 로 주입한다 (development | production).
+ */
+export function isProductionEnv(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.NODE_ENV === 'production';
+}

backend/test/app.e2e-spec.ts

@@ -1,14 +1,11 @@
-import { INestApplication, ValidationPipe } from '@nestjs/common';
-import { Reflector } from '@nestjs/core';
+import { INestApplication } from '@nestjs/common';
 import { Test, TestingModule } from '@nestjs/testing';
 import request from 'supertest';
 import type { Response } from 'supertest';
 import { App } from 'supertest/types';
 
 import { AppModule } from '@/app.module';
-import { HttpExceptionFilter } from '@/common/filters/http-exception.filter';
-import { TransformInterceptor } from '@/common/interceptors/transform.interceptor';
-import { RequestIdMiddleware } from '@/common/middleware/request-id.middleware';
+import { configureApp } from '@/app.setup';
 
 /**
  * 세 플랫폼이 공유하는 응답 계약을 실제 HTTP 요청으로 검증한다.
@@ -44,18 +41,10 @@ describe('응답 계약 (e2e)', () => {
 
     app = moduleFixture.createNestApplication();
 
-    // main.ts 와 동일한 전역 설정을 적용해야 실제 응답과 같아진다
-    app.setGlobalPrefix('api');
-    app.use(new RequestIdMiddleware().use.bind(new RequestIdMiddleware()));
-    app.useGlobalPipes(
-      new ValidationPipe({
-        whitelist: true,
-        forbidNonWhitelisted: true,
-        transform: true,
-      }),
-    );
-    app.useGlobalFilters(new HttpExceptionFilter());
-    app.useGlobalInterceptors(new TransformInterceptor(app.get(Reflector)));
+    // main.ts 와 같은 전역 설정 함수를 그대로 쓴다 (app.setup.ts).
+    // 여기서 설정을 따로 흉내 내면 둘이 어긋나도 테스트는 통과해 버린다.
+    // 추적 ID 는 AppModule 의 RequestIdMiddleware 가 붙인다 — 운영과 같은 경로다.
+    configureApp(app);
 
     await app.init();
   });