From 6dcbb45eb9611c106273b546659fa3a36cc6f36d Mon Sep 17 00:00:00 2001 From: TtiPo Date: Sun, 8 Nov 2026 00:04:03 +0900 Subject: [PATCH] =?UTF-8?q?refactor:=20=ED=94=84=EB=A1=A0=ED=8A=B8=C2=B7AP?= =?UTF-8?q?I=20=EB=A5=BC=20=EA=B0=99=EC=9D=80=20=EB=8F=84=EB=A9=94?= =?UTF-8?q?=EC=9D=B8(/api)=EC=9C=BC=EB=A1=9C=20=ED=86=B5=ED=95=A9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 브라우저가 프론트와 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 --- .claude/agents/release-ops.md | 5 +- .claude/rules/api-design.md | 4 + .claude/rules/checklist.md | 5 +- .claude/rules/env-structure.md | 5 +- .claude/rules/security.md | 5 +- .claude/skills/docker/SKILL.md | 25 ++++-- .claude/skills/nestjs/SKILL.md | 2 +- .claude/skills/vue3/SKILL.md | 12 +-- .env.development.example | 15 +++- .env.production.example | 35 +++++--- README.md | 76 +++++++++++++++- backend/src/main.ts | 31 ++----- backend/src/shared/config/cors.config.spec.ts | 88 +++++++++++++++++++ backend/src/shared/config/cors.config.ts | 59 +++++++++++++ .../src/shared/config/env.validation.spec.ts | 36 ++++++++ backend/src/shared/config/env.validation.ts | 25 ++++-- docker-compose.yml | 29 ++++-- flutter/.env.example | 1 + frontend/.env.development.example | 10 ++- frontend/.env.production.example | 11 +-- frontend/Dockerfile | 4 +- frontend/env.d.ts | 3 +- frontend/nginx.conf | 15 +++- frontend/src/composables/useApi.spec.ts | 17 +++- frontend/src/composables/useApi.ts | 19 +++- frontend/vite.config.ts | 9 +- 26 files changed, 456 insertions(+), 90 deletions(-) create mode 100644 backend/src/shared/config/cors.config.spec.ts create mode 100644 backend/src/shared/config/cors.config.ts diff --git a/.claude/agents/release-ops.md b/.claude/agents/release-ops.md index 7dd4901..39a754e 100644 --- a/.claude/agents/release-ops.md +++ b/.claude/agents/release-ops.md @@ -29,7 +29,10 @@ tools: Read, Grep, Glob, Edit, Write, Bash, Skill - **포트 노출**: DB·Redis 호스트 포트는 dev 에서만, 반드시 `127.0.0.1` 로 한정 ([[security]]). - **비-root 구동**: dev 오버라이드를 포함해 모든 컨테이너가 비-root 여야 한다. - **env 파일 존재**: 루트 `.env.{APP_ENV}` 와 `backend/.env.{APP_ENV}` 가 둘 다 있어야 기동한다. -- **운영 배포 전**: `BACKEND_API_URL`·`CORS_ORIGIN` 이 실제 도메인인지 확인한다. +- **운영 배포 전**: 프론트와 API 는 같은 도메인을 쓴다. 외부 네트워크 `proxy` 가 있는지, NPM Proxy Host 에 + Custom location `/api` → `${PROJECT_NAME}-backend:${BACKEND_PORT}` 가 있고 **Cache Assets 가 꺼져 있는지** 확인한다 (README "운영 배포"). + `https://<도메인>/api/health` 가 404 면 custom location 이 빠진 것이다. + API 를 별도 도메인으로 분리한 구성이라면 `BACKEND_API_URL`·`CORS_ORIGIN` 이 실제 도메인인지 확인한다 — `localhost`·`example.com` 이 남아 있으면 백엔드가 기동에 실패한다 ([[env-structure]]). - **프론트엔드**: 개발에서는 컨테이너로 띄우지 않는다(profile `frontend` 뒤에 있다). 운영만 nginx 정적 호스팅이다. diff --git a/.claude/rules/api-design.md b/.claude/rules/api-design.md index 32df3d5..6ce7139 100644 --- a/.claude/rules/api-design.md +++ b/.claude/rules/api-design.md @@ -5,6 +5,10 @@ ## 경로 · 메서드 - 모든 라우트는 글로벌 prefix `/api` 아래에 놓인다 (`main.ts`). 클라이언트 baseURL 도 `/api` 를 포함한다. +- 웹은 프론트와 **같은 도메인**의 `/api` 상대경로로 호출한다. 리버스 프록시(운영: Nginx Proxy Manager 의 + Custom location, 개발: vite dev 프록시)가 `/api` 로 **시작하는** 요청을 경로 그대로 백엔드에 넘긴다. + - 그래서 **`/api` 로 시작하는 경로는 프론트엔드 라우트로 쓰지 않는다** (`/api-keys` 같은 화면도 백엔드로 간다). + - 모바일 앱은 같은 주소를 절대 URL 로 쓴다 (`https://<도메인>/api`). - 리소스는 **복수형 명사**, 소문자 kebab-case: `/users`, `/order-items` - 동사를 경로에 넣지 않는다. 상태 변경이 필요하면 하위 리소스로 표현한다. - ❌ `POST /users/1/doDeactivate` diff --git a/.claude/rules/checklist.md b/.claude/rules/checklist.md index 154a73e..ebe8454 100644 --- a/.claude/rules/checklist.md +++ b/.claude/rules/checklist.md @@ -8,7 +8,10 @@ ## 1. 신규 프로젝트 셋업 (클론 직후 1회) - [ ] 루트 `.env.{env}.example` → `.env.{env}` 복사 후 **placeholder 값 교체** (`change-me-*` 가 남아 있으면 안 된다, [[env-structure]]) - 운영은 `BACKEND_API_URL`·`CORS_ORIGIN` 을 **실제 도메인**으로 — `localhost`/`example.com` 이 남으면 기동 실패한다 + `BACKEND_API_URL=/api`·`CORS_ORIGIN` 비움은 그대로 둔다 — 프론트와 API 는 같은 도메인을 쓴다. + API 를 별도 도메인으로 분리할 때만 실제 도메인을 적는다 (`localhost`/`example.com` 이 남으면 기동 실패) +- [ ] 운영 서버: NPM 과 공유하는 외부 네트워크 생성 `docker network create proxy` (없으면 compose 가 기동하지 않는다) + → NPM 에 Proxy Host(`/` → frontend:8080) + Custom location(`/api` → backend:3000) 설정, **Cache Assets 끔** (README "운영 배포") - [ ] `backend/.env.{env}.example` → `backend/.env.{env}` 복사 후 `JWT_SECRET` 등 고유 시크릿 작성 (compose `env_file` 로 로드 — 파일이 없으면 기동 실패) - [ ] `flutter/.env.example` → `flutter/.env` 복사 후 `API_URL` 확인 (Android 에뮬레이터: `10.0.2.2`) — **이 파일이 없으면 `flutter analyze` 가 asset 경고를 낸다** diff --git a/.claude/rules/env-structure.md b/.claude/rules/env-structure.md index 6318e7f..82ff059 100644 --- a/.claude/rules/env-structure.md +++ b/.claude/rules/env-structure.md @@ -13,7 +13,7 @@ description: 환경변수 단일 진실 공급원(SSOT) 구조 — 루트 .env.{ │ (docker compose --env-file 로 로드) ├─▶ backend : env_file + environment 로 DB/Redis/CORS/포트 주입 │ (backend/.env.{APP_ENV} 는 "존재"만 하면 됨, 내용 최소) - ├─▶ frontend : BACKEND_API_URL → build arg(VITE_API_BASE_URL) 로 주입 + ├─▶ frontend : BACKEND_API_URL(기본 /api — 같은 도메인) → build arg(VITE_API_BASE_URL) 로 주입 │ (호스트에서 `npm run dev` 로 띄울 때는 compose 를 거치지 않으므로 │ vite.config.ts 가 이 파일을 `loadEnv` 로 직접 읽어 FRONTEND_PORT/BACKEND_PORT 사용) ├─▶ db : DB_USER/DB_PASSWORD/DB_NAME, DB_DATA_DIR 볼륨 @@ -37,10 +37,13 @@ description: 환경변수 단일 진실 공급원(SSOT) 구조 — 루트 .env.{ - **설정이 잘못되면 서버가 뜨지 않아야 한다(fail-fast).** 조용히 기본값으로 굴러가다 운영에서 터지는 것이 더 위험하다. 검증은 `backend/src/shared/config/env.validation.ts` 가 담당하며 `ConfigModule.forRoot({ validate })` 에 연결되어 있다. - 숫자 항목은 형식 검사 (모든 환경) + - `CORS_ORIGIN` 은 각 항목이 오리진 형식(`scheme://host[:port]`, 경로 없음)이어야 한다 (모든 환경) + — 경로가 붙으면 브라우저 Origin 헤더와 절대 일치하지 않아 조용히 막힌다 - 운영 환경: `DB_HOST`/`DB_USER`/`DB_PASSWORD`/`DB_NAME` 필수 - 운영 환경: `change-me`·`password` 같은 **예시 값이 그대로 배포되는 것을 차단** - 운영 환경: `CORS_ORIGIN`·`BACKEND_API_URL` 에 **로컬 주소(`localhost`·`127.0.0.1` 등)나 예시 도메인(`example.com`)이 남아 있으면 차단** — 기동은 되는데 브라우저만 조용히 실패하는 조합을 막는다. + 같은 도메인 기본 구성(`/api`·CORS 비움)은 걸릴 값이 없고, API 를 별도 도메인으로 분리했을 때의 실수를 잡는다. 로컬에서 운영 이미지를 검증하느라 일부러 localhost 를 쓸 때만 `ALLOW_LOCALHOST_URL=true` 로 건너뛴다 (`BACKEND_API_URL` 은 앱이 쓰지 않지만 이 검사를 위해 compose 가 backend 에 주입한다) - 문제는 하나씩이 아니라 **한 번에 모아서** 보여준다 (재기동 반복 방지) diff --git a/.claude/rules/security.md b/.claude/rules/security.md index 60b5646..22ad3f7 100644 --- a/.claude/rules/security.md +++ b/.claude/rules/security.md @@ -45,6 +45,9 @@ - 보안 헤더(`helmet`) 적용 - CORS 는 화이트리스트 방식. 차단 시 `callback(null, false)` 로 **헤더를 부여하지 않아** 브라우저가 막게 한다 (`callback(new Error(...))` 를 쓰면 500(SYS_001)이 되어 원인 파악이 어려워진다) + - 프론트와 API 가 **같은 도메인**이 기본이라 화이트리스트는 비어 있다 (같은 출처 요청에는 CORS 가 적용되지 않는다). + 다른 오리진이 필요할 때만 루트 `CORS_ORIGIN` 에 콤마로 나열한다 (`shared/config/cors.config.ts`) + - 개발용 `localhost` 를 코드에 기본 허용으로 박지 않는다 — 운영에서도 그대로 열린다 - Rate Limiting: **`@nestjs/throttler` 하나로 일원화**되어 있다 (`app.module.ts` 의 `APP_GUARD`). 초과 시 429 → 전역 필터가 **`REQ_001`** 로 매핑한다. - 기본 정책은 루트 `.env` 의 `THROTTLE_TTL_MS`/`THROTTLE_LIMIT` (미설정 시 60초/100회) @@ -65,7 +68,7 @@ ``` - **보안 헤더는 CSP 까지** 설정한다 (`frontend/nginx.conf`). 외부 CDN·폰트·분석 스크립트를 추가하면 해당 도메인을 CSP 에 명시한다. `script-src` 에 `'unsafe-inline'`/`'unsafe-eval'` 을 넣으면 CSP 의 의미가 사라진다. - API 도메인이 다르면 `connect-src` 에 추가해야 요청이 차단되지 않는다. + API 는 같은 도메인의 `/api` 라 `connect-src 'self'` 로 충분하다. API 를 별도 도메인으로 분리하면 그 오리진을 추가해야 요청이 차단되지 않는다. ## 의존성 diff --git a/.claude/skills/docker/SKILL.md b/.claude/skills/docker/SKILL.md index d6c0256..f8cbfc7 100644 --- a/.claude/skills/docker/SKILL.md +++ b/.claude/skills/docker/SKILL.md @@ -29,9 +29,19 @@ docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.d ## 운영 환경 -> ⚠️ `.env.production` 의 `BACKEND_API_URL`·`CORS_ORIGIN` 을 **실제 도메인으로 교체**해야 한다. -> `localhost` 나 예시 도메인(`example.com`)이 남아 있으면 백엔드가 기동에 실패한다 ([[env-structure]]). -> 로컬에서 운영 이미지를 검증하느라 일부러 localhost 를 쓰는 경우에만 `ALLOW_LOCALHOST_URL=true` 를 함께 준다. +> **프론트와 API 는 같은 도메인을 쓴다.** 브라우저는 `/api` 상대경로로만 호출하고, +> 리버스 프록시(Nginx Proxy Manager)가 경로로 나눠 보낸다. 설정 절차는 README "운영 배포" 참조. +> +> | 경로 | 대상 (proxy 네트워크) | NPM 설정 | +> | --- | --- | --- | +> | `/` | `${PROJECT_NAME}-frontend:8080` | Proxy Host 의 기본 대상 | +> | `/api` | `${PROJECT_NAME}-backend:${BACKEND_PORT}` | 같은 Proxy Host 의 Custom location | +> +> - NPM 과 공유하는 외부 네트워크 `proxy` 가 있어야 기동한다 — 서버당 한 번 `docker network create proxy`. +> - Proxy Host 의 **Cache Assets 는 끈다.** 켜면 `/api/…png` 처럼 정적 확장자로 끝나는 요청이 custom location 대신 frontend 로 간다. +> - location 은 `/api`(끝 슬래시 없음), Forward Hostname 에는 경로를 붙이지 않는다 — 경로가 그대로 넘어가야 백엔드 prefix 와 맞는다. +> - `BACKEND_API_URL=/api`·`CORS_ORIGIN` 비움이 기본이다. API 를 별도 도메인으로 분리할 때만 실제 도메인을 적는다 — +> 그때 `localhost` 나 예시 도메인(`example.com`)이 남아 있으면 백엔드가 기동에 실패한다 ([[env-structure]]). ```bash # 운영 환경 배포 @@ -54,8 +64,10 @@ cd frontend && npm install && npm run dev # → http://localhost:5173 호스트에 노출한 포트)로 잡는다. 포트를 바꿀 때 루트 env 한 줄만 고치면 된다. 백엔드를 아예 다른 주소에 띄웠다면 `VITE_DEV_API_PROXY` 로 대상을 덮어쓴다. - `strictPort: true` 라 포트가 이미 사용 중이면 **다음 포트로 옮기지 않고 실패**한다. - `CORS_ORIGIN` 과 compose 포트 매핑이 그 포트에 묶여 있어, 조용히 5174 로 옮겨가면 - API 요청이 원인 모르게 막힌다 (fail-fast). + 대개 다른 vite(컨테이너 vite 포함)가 이미 그 포트를 쓰고 있다는 뜻이라, 조용히 5174 로 옮겨가면 + 브라우저는 여전히 5173 의 엉뚱한 서버를 보게 된다 (fail-fast). +- 브라우저는 vite 와 **같은 출처**의 `/api` 를 호출하고 vite 프록시가 백엔드로 넘긴다 — + 운영의 NPM Custom location 과 같은 구조라 개발에서도 CORS 설정이 필요 없다. - 폴링 감시(`watch.usePolling`)는 **컨테이너에서만** 켜진다 (`CHOKIDAR_USEPOLLING` 로 판별). 호스트에서는 OS 파일 감시 이벤트로 충분하며, 폴링을 켜면 기동이 느려지고 CPU 만 쓴다. - 의존성 설치는 호스트에서 해도 된다 — 프론트엔드 dev 는 컨테이너를 쓰지 않으므로 @@ -183,7 +195,8 @@ dc --profile redis up -d - 정상 종료 시 컨테이너 **종료 코드는 143**(=128+SIGTERM)이다. 오류가 아니라 시그널에 의한 정상 종료다. - ⚠️ dev 오버라이드는 PID 1 이 `npm` 이라 SIGTERM 이 앱까지 전달되지 않는다(개발 편의상 허용). graceful shutdown 동작 확인은 **운영 이미지**(`--target production`)로 해야 한다. - 이때 로컬 주소를 쓰게 되므로 `ALLOW_LOCALHOST_URL=true` 로 공개 주소 검사를 건너뛴다 ([[env-structure]]). + 같은 도메인 기본 구성(`BACKEND_API_URL=/api`·`CORS_ORIGIN` 비움)이면 공개 주소 검사에 걸릴 값이 없다. + 별도 도메인 구성을 localhost 로 검증할 때만 `ALLOW_LOCALHOST_URL=true` 로 그 검사를 건너뛴다 ([[env-structure]]). - **컨테이너 비-root 구동**: 모든 서비스 컨테이너는 비-root 로 실행한다 — **dev 오버라이드도 포함** ([[security]] 참조). - 프론트엔드 운영 컨테이너는 `nginx-unprivileged` 라 **8080** 포트를 쓴다 (`expose`·healthcheck·nginx.conf 가 모두 8080). - 프론트엔드 dev 컨테이너는 vite 를 **5173** 으로 띄운다 (비-root 는 80 포트 바인드 불가). diff --git a/.claude/skills/nestjs/SKILL.md b/.claude/skills/nestjs/SKILL.md index 82200e2..499df70 100644 --- a/.claude/skills/nestjs/SKILL.md +++ b/.claude/skills/nestjs/SKILL.md @@ -24,7 +24,7 @@ description: NestJS 백엔드(backend/) 개발 규칙 — 컨트롤러/서비스 | 페이지네이션 DTO | `src/common/dto/pagination.dto.ts` | 커서/오프셋 쿼리 + `PageInfoDto` + `toPaginatedResult()` | | 전역 ValidationPipe | `main.ts` | `whitelist/forbidNonWhitelisted/transform` | | Swagger | `main.ts` → `/api-docs` | 모든 엔드포인트 데코레이터 | -| 보안 미들웨어 | `main.ts` | helmet · CORS 화이트리스트 | +| 보안 미들웨어 | `main.ts` | helmet · CORS 화이트리스트(`shared/config/cors.config.ts` — 같은 도메인 구성이 기본이라 비어 있다. 다른 오리진만 `CORS_ORIGIN` 에 콤마로) | | Rate Limiting | `app.module.ts` 의 `ThrottlerGuard`(APP_GUARD) | 초과 시 429 → `REQ_001`. 루트 `.env` 의 `THROTTLE_*` 로 조정 | | 로깅 | `shared/logger/winston.config.ts` | `console.log` 대신 사용 ([[logging]]) | | env 검증 | `shared/config/env.validation.ts` | 잘못된 설정이면 **기동 실패**(fail-fast) ([[env-structure]]) | diff --git a/.claude/skills/vue3/SKILL.md b/.claude/skills/vue3/SKILL.md index d80e4ce..b917fce 100644 --- a/.claude/skills/vue3/SKILL.md +++ b/.claude/skills/vue3/SKILL.md @@ -15,7 +15,7 @@ description: Vue 3 프론트엔드(frontend/) 개발 규칙 — Composition API | 제공 항목 | 위치 | 비고 | | --- | --- | --- | -| 중앙 Axios 인스턴스 | `src/composables/useApi.ts` | baseURL=`VITE_API_BASE_URL`, `withCredentials` | +| 중앙 Axios 인스턴스 | `src/composables/useApi.ts` | baseURL=`VITE_API_BASE_URL`(비면 같은 도메인의 `/api`), `withCredentials` | | 응답 언래핑 인터셉터 | `useApi.ts` | `{success,data}→data`, 에러 코드 정규화(`ApiError`), 중복 알림 억제 | | 에러 코드 사전 | `src/shared/constants/error-codes.generated.ts` | **자동 생성 파일 — 직접 수정 금지** ([[error-codes]]) | | 세션 만료 처리 | `useApi.ts` 의 `toAuthCode()` | 로그인 상태에서 401 → `AUTH_002` 승격 + `authStore.clearAuth()` | @@ -27,7 +27,7 @@ description: Vue 3 프론트엔드(frontend/) 개발 규칙 — Composition API | 공통 컴포넌트 예제 | `src/components/BaseButton.vue` | 재사용 컴포넌트 기준 패턴(타입 Props/Emits·scoped·rem·a11y) | | 라우터 | `src/router/index.ts` | lazy import + `auth.store` 연동 `requiresAuth` 가드 | | env 타입 선언 | `frontend/env.d.ts` | `VITE_API_BASE_URL` | -| dev API 프록시 | `vite.config.ts` 의 `server.proxy` | `/api` → 백엔드. 없으면 vite 가 SPA 폴백으로 **HTML 을 200 으로** 돌려줘 조용히 실패한다 | +| dev API 프록시 | `vite.config.ts` 의 `server.proxy` | `/api` → 백엔드 (운영 NPM Custom location 과 같은 역할). 없으면 vite 가 SPA 폴백으로 **HTML 을 200 으로** 돌려줘 조용히 실패한다 | | dev 서버 포트 | `vite.config.ts` 의 `loadEnv` | 루트 `.env.{mode}` 의 `FRONTEND_PORT`/`BACKEND_PORT` 를 읽는다. `strictPort` 로 포트 충돌 시 fail-fast ([[env-structure]]) | > **개발 서버는 호스트에서 띄운다** — `cd frontend && npm run dev` (→ `http://localhost:${FRONTEND_PORT}`). @@ -123,7 +123,8 @@ export const useUserStore = defineStore('user', () => { ```typescript // composables/useApi.ts — 중앙 Axios 인스턴스 (구조 요약) const api = axios.create({ - baseURL: import.meta.env.VITE_API_BASE_URL || '/api', // env.d.ts 에 타입 선언 + // 비어 있으면 같은 도메인의 /api — 운영은 NPM Custom location, 개발은 vite 프록시가 백엔드로 넘긴다 + baseURL: resolveApiBaseUrl(import.meta.env.VITE_API_BASE_URL), withCredentials: true, // HttpOnly 쿠키 전송 }) @@ -218,11 +219,12 @@ router.beforeEach((to) => { - [ ] **목록 화면**: 응답은 `{items, pageInfo}` — `shared/types/pagination.ts` 타입 사용. - [ ] **컴포넌트**: `