refactor: 프론트·API 를 같은 도메인(/api)으로 통합
브라우저가 프론트와 API 를 서로 다른 도메인으로 호출하던 구조를 같은 도메인의 /api 경로로 통합한다. 운영은 Nginx Proxy Manager 의 Proxy Host(/ → frontend:8080)와 Custom location(/api → backend:3000)이, 개발은 vite dev 프록시가 같은 규칙으로 백엔드에 넘긴다. - 같은 출처 호출이라 CORS 설정이 필요 없고 CSP connect-src 'self' 가 그대로 동작한다 (기존 예시대로 별도 도메인에 배포하면 CSP 에 막혀 API 호출이 실패했다) - 프론트 번들의 baseURL 이 /api 상대경로라 도메인이 바뀌어도 다시 빌드할 필요가 없다 - NPM 설정 절차와 주의점(Cache Assets 끄기, proxy 네트워크 생성)을 README "운영 배포"에 정리했다 - 프록시 설정이 빠지면 frontend nginx 가 /api 를 404 로 막는다 — index.html(200)로 조용히 실패하지 않게 함께 고친 CORS 문제: - CORS_ORIGIN 에 콤마로 여러 오리진을 적으면 문자열 전체를 하나로 비교해 모두 막히던 버그 - 운영에서도 localhost:5173·localhost:3000 이 credentials 포함으로 항상 허용되던 문제 - 형식이 잘못된 오리진(경로 포함 등)은 기동 시점에 실패하도록 검증 추가 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
+7
-24
@@ -14,6 +14,7 @@ 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 { winstonConfig } from '@/shared/logger/winston.config';
|
||||
|
||||
async function bootstrap() {
|
||||
@@ -21,11 +22,13 @@ async function bootstrap() {
|
||||
logger: WinstonModule.createLogger(winstonConfig),
|
||||
});
|
||||
|
||||
// 리버스 프록시(Nginx, Docker 배포 환경 등) 뒤에서 올바른 클라이언트 IP 식별 지원을 위해 설정합니다.
|
||||
// 리버스 프록시 뒤에서 실제 클라이언트 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('api', {
|
||||
// 헬스체크 / 루트 상태 엔드포인트는 prefix 미적용
|
||||
exclude: [{ path: '/', method: RequestMethod.GET }],
|
||||
@@ -39,29 +42,9 @@ async function bootstrap() {
|
||||
// 1. 보안 헤더 (Helmet) - XSS 방지 및 기본 웹 보안
|
||||
app.use(helmet());
|
||||
|
||||
// 2. 화이트리스트 기반 CORS 정책
|
||||
const frontendUrl = process.env.FRONTEND_URL || 'http://localhost:5173';
|
||||
const corsOriginEnv = process.env.CORS_ORIGIN;
|
||||
|
||||
app.enableCors({
|
||||
origin: (
|
||||
origin: string | undefined,
|
||||
callback: (err: Error | null, allow?: boolean) => void,
|
||||
) => {
|
||||
// 서버간의 통신(origin이 undefined)이거나 명시된 리스트일 때만 허용
|
||||
const whitelist = [frontendUrl, 'http://localhost:3000'];
|
||||
if (corsOriginEnv) whitelist.push(corsOriginEnv);
|
||||
|
||||
if (!origin || whitelist.indexOf(origin) !== -1) {
|
||||
callback(null, true);
|
||||
} else {
|
||||
// Error 를 넘기면 500(SYS_001)이 되어 원인 파악이 어려우므로,
|
||||
// CORS 헤더를 부여하지 않아 브라우저가 차단하도록 한다.
|
||||
callback(null, false);
|
||||
}
|
||||
},
|
||||
credentials: true, // 쿠키 교환 허용
|
||||
});
|
||||
// 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)로 응답된다.
|
||||
|
||||
@@ -0,0 +1,88 @@
|
||||
import {
|
||||
buildCorsOptions,
|
||||
isValidOrigin,
|
||||
parseCorsOrigins,
|
||||
} from './cors.config';
|
||||
|
||||
/**
|
||||
* enableCors 의 origin 콜백을 실행해 CORS 헤더를 부여하는지 돌려받는다.
|
||||
* 차단할 때도 에러를 넘기지 않아야 한다 (에러는 500 이 되어 원인을 가린다).
|
||||
*/
|
||||
function isAllowed(
|
||||
corsOrigin: string | undefined,
|
||||
requestOrigin: string | undefined,
|
||||
): boolean {
|
||||
const { origin } = buildCorsOptions(corsOrigin);
|
||||
if (typeof origin !== 'function') {
|
||||
throw new Error('origin 은 콜백이어야 한다');
|
||||
}
|
||||
|
||||
let allowed: unknown;
|
||||
origin(requestOrigin, (error, result) => {
|
||||
expect(error).toBeNull();
|
||||
allowed = result;
|
||||
});
|
||||
return allowed === true;
|
||||
}
|
||||
|
||||
describe('parseCorsOrigins', () => {
|
||||
it('비어 있으면 빈 목록이다 (같은 도메인 기본 구성)', () => {
|
||||
expect(parseCorsOrigins(undefined)).toEqual([]);
|
||||
expect(parseCorsOrigins('')).toEqual([]);
|
||||
expect(parseCorsOrigins(' , ')).toEqual([]);
|
||||
});
|
||||
|
||||
it('콤마로 나누고 공백·끝 슬래시를 제거한다', () => {
|
||||
expect(
|
||||
parseCorsOrigins('https://a.myservice.io, https://b.myservice.io/ ,'),
|
||||
).toEqual(['https://a.myservice.io', 'https://b.myservice.io']);
|
||||
});
|
||||
|
||||
it('브라우저 Origin 헤더처럼 소문자로 맞춘다', () => {
|
||||
expect(parseCorsOrigins('https://App.MyService.io')).toEqual([
|
||||
'https://app.myservice.io',
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('isValidOrigin', () => {
|
||||
it('scheme://host[:port] 만 오리진으로 인정한다', () => {
|
||||
expect(isValidOrigin('https://app.myservice.io')).toBe(true);
|
||||
expect(isValidOrigin('http://localhost:5173')).toBe(true);
|
||||
});
|
||||
|
||||
it('경로가 붙거나 scheme 이 없거나 와일드카드면 오리진이 아니다', () => {
|
||||
expect(isValidOrigin('https://app.myservice.io/api')).toBe(false);
|
||||
expect(isValidOrigin('app.myservice.io')).toBe(false);
|
||||
expect(isValidOrigin('*')).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('buildCorsOptions', () => {
|
||||
it('화이트리스트가 비어 있으면 다른 오리진에 CORS 헤더를 주지 않는다', () => {
|
||||
expect(isAllowed(undefined, 'https://other.io')).toBe(false);
|
||||
expect(isAllowed('', 'https://other.io')).toBe(false);
|
||||
});
|
||||
|
||||
it('Origin 헤더가 없는 요청(서버 간 통신)은 허용한다', () => {
|
||||
expect(isAllowed(undefined, undefined)).toBe(true);
|
||||
});
|
||||
|
||||
it('콤마로 나열한 오리진을 각각 허용한다', () => {
|
||||
const corsOrigin = 'https://app.myservice.io, https://admin.myservice.io';
|
||||
|
||||
expect(isAllowed(corsOrigin, 'https://app.myservice.io')).toBe(true);
|
||||
expect(isAllowed(corsOrigin, 'https://admin.myservice.io')).toBe(true);
|
||||
expect(isAllowed(corsOrigin, 'https://other.io')).toBe(false);
|
||||
});
|
||||
|
||||
it('개발용 localhost 를 암묵적으로 허용하지 않는다 (운영에서도 열려 버린다)', () => {
|
||||
expect(isAllowed('https://app.myservice.io', 'http://localhost:5173')).toBe(
|
||||
false,
|
||||
);
|
||||
});
|
||||
|
||||
it('인증 쿠키를 주고받을 수 있게 credentials 를 켠다', () => {
|
||||
expect(buildCorsOptions('').credentials).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,59 @@
|
||||
import type { CorsOptions } from '@nestjs/common/interfaces/external/cors-options.interface';
|
||||
|
||||
/**
|
||||
* CORS 설정 — main.ts(런타임)와 env.validation.ts(기동 검증)가 같은 파서를 공유한다.
|
||||
*
|
||||
* 기본 구성은 프론트와 API 가 **같은 도메인**이다. 브라우저는 `/api` 상대경로로만 호출하고
|
||||
* 리버스 프록시(운영: Nginx Proxy Manager 의 Custom location, 개발: vite dev 프록시)가 백엔드로 넘긴다.
|
||||
* 같은 출처 요청에는 CORS 가 적용되지 않으므로 **화이트리스트가 비어 있는 것이 정상**이다.
|
||||
*
|
||||
* 다른 오리진(별도 도메인의 프론트, Flutter Web 등)에서 호출해야 할 때만
|
||||
* 루트 .env 의 CORS_ORIGIN 에 콤마로 나열한다.
|
||||
*/
|
||||
|
||||
/** 오리진 형식 — `scheme://host[:port]`. 경로·쿼리가 붙으면 브라우저의 Origin 헤더와 절대 일치하지 않는다 */
|
||||
const ORIGIN_PATTERN = /^https?:\/\/[^\s/?#]+$/;
|
||||
|
||||
/**
|
||||
* CORS_ORIGIN 을 오리진 목록으로 파싱한다.
|
||||
* 콤마로 나누고 공백·끝 슬래시를 제거한다. 브라우저는 Origin 을 소문자로 보내므로 소문자로 맞춘다.
|
||||
*/
|
||||
export function parseCorsOrigins(value: string | undefined): string[] {
|
||||
if (value === undefined) return [];
|
||||
|
||||
return value
|
||||
.split(',')
|
||||
.map((entry) => entry.trim().replace(/\/+$/, '').toLowerCase())
|
||||
.filter((entry) => entry !== '');
|
||||
}
|
||||
|
||||
/** 브라우저가 보내는 Origin 헤더와 비교할 수 있는 형식인지 검사한다 */
|
||||
export function isValidOrigin(origin: string): boolean {
|
||||
return ORIGIN_PATTERN.test(origin);
|
||||
}
|
||||
|
||||
/**
|
||||
* `app.enableCors()` 옵션을 만든다.
|
||||
*
|
||||
* - Origin 헤더가 없는 요청(서버 간 통신·헬스체크)은 CORS 대상이 아니므로 허용한다.
|
||||
* - 화이트리스트 밖이면 Error 대신 `false` 를 넘긴다. Error 는 500(SYS_001)이 되어 원인을 가리고,
|
||||
* `false` 는 CORS 헤더만 빼서 **브라우저가** 막게 한다.
|
||||
* 같은 출처 요청은 이 헤더 없이도 통과하므로 기본 구성(같은 도메인)에는 영향이 없다.
|
||||
* - 개발용 localhost 를 여기에 하드코딩하지 않는다 — 운영에서도 그대로 열려 버린다.
|
||||
*/
|
||||
export function buildCorsOptions(
|
||||
corsOrigin: string | undefined = process.env.CORS_ORIGIN,
|
||||
): CorsOptions {
|
||||
const allowedOrigins = new Set(parseCorsOrigins(corsOrigin));
|
||||
|
||||
return {
|
||||
origin: (requestOrigin, callback) => {
|
||||
callback(
|
||||
null,
|
||||
requestOrigin === undefined || allowedOrigins.has(requestOrigin),
|
||||
);
|
||||
},
|
||||
// 다른 오리진을 허용한 경우에도 인증 쿠키를 주고받을 수 있게 한다
|
||||
credentials: true,
|
||||
};
|
||||
}
|
||||
@@ -34,11 +34,47 @@ describe('validateEnv', () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe('CORS_ORIGIN 형식 (모든 환경)', () => {
|
||||
const dev = (corsOrigin: string) => ({
|
||||
NODE_ENV: 'development',
|
||||
CORS_ORIGIN: corsOrigin,
|
||||
});
|
||||
|
||||
it('비어 있으면 통과한다 (같은 도메인 기본 구성)', () => {
|
||||
expect(() => validateEnv(dev(''))).not.toThrow();
|
||||
});
|
||||
|
||||
it('콤마로 여러 오리진을 적을 수 있다 (끝 슬래시는 허용)', () => {
|
||||
expect(() =>
|
||||
validateEnv(dev('http://localhost:5173, https://admin.myservice.io/')),
|
||||
).not.toThrow();
|
||||
});
|
||||
|
||||
it('경로가 붙은 값은 Origin 헤더와 일치할 수 없으므로 실패한다', () => {
|
||||
expect(() => validateEnv(dev('https://app.myservice.io/api'))).toThrow(
|
||||
/CORS_ORIGIN 의 "https:\/\/app\.myservice\.io\/api" 는 오리진 형식이 아닙니다/,
|
||||
);
|
||||
});
|
||||
|
||||
it('scheme 이 없거나 와일드카드면 실패한다', () => {
|
||||
expect(() => validateEnv(dev('app.myservice.io'))).toThrow(
|
||||
/오리진 형식이 아닙니다/,
|
||||
);
|
||||
expect(() => validateEnv(dev('*'))).toThrow(/오리진 형식이 아닙니다/);
|
||||
});
|
||||
});
|
||||
|
||||
describe('운영 환경', () => {
|
||||
it('정상 설정이면 통과한다', () => {
|
||||
expect(() => validateEnv(prod())).not.toThrow();
|
||||
});
|
||||
|
||||
it('같은 도메인 기본 구성(BACKEND_API_URL=/api, CORS_ORIGIN 비움)은 통과한다', () => {
|
||||
expect(() =>
|
||||
validateEnv(prod({ BACKEND_API_URL: '/api', CORS_ORIGIN: '' })),
|
||||
).not.toThrow();
|
||||
});
|
||||
|
||||
it('필수 DB 설정이 없으면 실패한다', () => {
|
||||
expect(() => validateEnv(omit(prod(), 'DB_PASSWORD'))).toThrow(
|
||||
/DB_PASSWORD 가 설정되지 않았습니다/,
|
||||
|
||||
@@ -7,6 +7,8 @@
|
||||
* `ConfigModule.forRoot({ validate })` 에 연결되어 있다 (app.module.ts).
|
||||
*/
|
||||
|
||||
import { isValidOrigin, parseCorsOrigins } from './cors.config';
|
||||
|
||||
/** 운영 배포 전에 반드시 교체해야 하는 예시 값들 — `*.example` 에서 복사한 흔적 */
|
||||
const PLACEHOLDER_PATTERNS = [/change[-_]?me/i, /^password$/i, /^secret$/i];
|
||||
|
||||
@@ -34,9 +36,11 @@ const NO_PLACEHOLDER_IN_PRODUCTION = [
|
||||
] as const;
|
||||
|
||||
/**
|
||||
* 운영에서 **공개 주소**여야 하는 키.
|
||||
* 로컬 주소가 남은 채 배포되면 서버는 정상 기동하지만
|
||||
* 브라우저가 API 에 닿지 못하거나 CORS 화이트리스트가 실제 도메인을 막아 **조용히** 실패한다.
|
||||
* 운영에서 **공개 주소**여야 하는 키 (값이 있을 때만 검사한다).
|
||||
*
|
||||
* 기본 구성(같은 도메인)은 BACKEND_API_URL=/api · CORS_ORIGIN 비움이라 걸릴 값이 없다.
|
||||
* API 를 별도 도메인으로 분리한 뒤 로컬 주소가 남은 채 배포되면 서버는 정상 기동하지만
|
||||
* 브라우저가 API 에 닿지 못하거나 CORS 화이트리스트가 실제 도메인을 막아 **조용히** 실패한다 — 그 실수를 잡는다.
|
||||
*/
|
||||
const PUBLIC_URL_IN_PRODUCTION = ['CORS_ORIGIN', 'BACKEND_API_URL'] as const;
|
||||
|
||||
@@ -95,15 +99,24 @@ export function validateEnv(
|
||||
}
|
||||
}
|
||||
|
||||
// 2. CORS 오리진 형식 — 브라우저 Origin 헤더와 모양이 다르면 절대 일치하지 않아 **조용히** 막힌다
|
||||
for (const origin of parseCorsOrigins(readString(config, 'CORS_ORIGIN'))) {
|
||||
if (!isValidOrigin(origin)) {
|
||||
errors.push(
|
||||
`CORS_ORIGIN 의 "${origin}" 는 오리진 형식이 아닙니다. scheme://host[:port] 형태로 경로 없이 적어 주세요. (여러 개면 콤마로 구분)`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (isProduction) {
|
||||
// 2. 운영 필수값 — 없으면 기동 실패
|
||||
// 3. 운영 필수값 — 없으면 기동 실패
|
||||
for (const key of REQUIRED_IN_PRODUCTION) {
|
||||
if (readString(config, key) === undefined) {
|
||||
errors.push(`${key} 가 설정되지 않았습니다. (운영 환경 필수)`);
|
||||
}
|
||||
}
|
||||
|
||||
// 3. 예시 파일의 placeholder 가 그대로 배포되는 것을 막는다
|
||||
// 4. 예시 파일의 placeholder 가 그대로 배포되는 것을 막는다
|
||||
for (const key of NO_PLACEHOLDER_IN_PRODUCTION) {
|
||||
const value = readString(config, key);
|
||||
if (value !== undefined && looksLikePlaceholder(value)) {
|
||||
@@ -113,7 +126,7 @@ export function validateEnv(
|
||||
}
|
||||
}
|
||||
|
||||
// 4. 공개 주소가 로컬 주소·예시 도메인으로 남은 채 배포되는 것을 막는다
|
||||
// 5. 공개 주소가 로컬 주소·예시 도메인으로 남은 채 배포되는 것을 막는다
|
||||
const allowLocalhostUrl =
|
||||
readString(config, ALLOW_LOCALHOST_URL_KEY) === 'true';
|
||||
|
||||
|
||||
Reference in New Issue
Block a user