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>

.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 정적 호스팅이다.
 

.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`

.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 경고를 낸다**

.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 에 주입한다)
   - 문제는 하나씩이 아니라 **한 번에 모아서** 보여준다 (재기동 반복 방지)

.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 를 별도 도메인으로 분리하면 그 오리진을 추가해야 요청이 차단되지 않는다.
 
 ## 의존성
 

.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 포트 바인드 불가).

.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]]) |

.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` 타입 사용.
 - [ ] **컴포넌트**: `<script setup lang="ts">` + `<style scoped>` + rem 단위. 인라인 스타일·Options API 금지.
 - [ ] **타입**: Props/Emits 는 인터페이스로 정의.
-- [ ] **라우트**: 페이지는 lazy import, 보호 라우트는 `meta.requiresAuth`.
+- [ ] **라우트**: 페이지는 lazy import, 보호 라우트는 `meta.requiresAuth`. `/api` 로 시작하는 경로는 쓰지 않는다 (백엔드로 간다 — [[api-design]]).
 - [ ] **auth 가드**: `router/index.ts` 가드는 `auth.store.ts` 의 `isLoggedIn` 과 이미 연결되어 있다. 로그인 페이지 추가 시 리다이렉트 대상을 `{ name: 'login' }` 으로 바꾼다.
 - [ ] **lint/test**: 커밋 전 `npm run lint` (`--max-warnings 0`) + `npm run type-check` + `npm run test:unit` 통과. 자동 수정은 `npm run lint:fix`.
 - [ ] **린트로 강제되는 항목**: Options API·인라인 스타일·`console`·`any` 는 빌드가 실패한다.
-- [ ] **env**: `VITE_API_BASE_URL` 은 빌드 시 루트 `BACKEND_API_URL` 에서 주입된다 — `frontend/.env` 에 별도 작성 불필요.
+- [ ] **env**: `VITE_API_BASE_URL` 은 빌드 시 루트 `BACKEND_API_URL`(기본 `/api` — 같은 도메인)에서 주입된다 — `frontend/.env` 에 별도 작성 불필요.
+      절대 URL 로 바꾸면 다른 오리진 호출이 되므로 백엔드 `CORS_ORIGIN` 과 `nginx.conf` 의 CSP `connect-src` 도 함께 바꿔야 한다.
 - [ ] **dev 서버**: 프론트엔드는 호스트에서 `npm run dev` 로 띄운다 (컨테이너는 `--profile frontend` 선택, [[docker]]).
 - [ ] **포트**: `vite.config.ts` 에 포트를 새로 하드코딩하지 않는다 — 루트 `.env.{mode}` 의 `FRONTEND_PORT`/`BACKEND_PORT` 가 SSOT ([[env-structure]]).
 - [ ] **dev 에서 API 가 안 될 때**: 응답이 JSON 이 아니라 HTML 이면 vite 프록시(`server.proxy`) 문제다.

.env.development.example

@@ -12,7 +12,7 @@ BACKEND_DIR=backend
 #
 # 컨테이너 포트 매핑뿐 아니라 **호스트에서 띄우는 vite dev 서버**도 이 값을 따른다.
 # (frontend/vite.config.ts 가 이 파일을 직접 읽는다 — FRONTEND_PORT 로 열고
-#  /api 프록시는 BACKEND_PORT 로 보낸다. 포트를 바꾸면 CORS_ORIGIN 도 함께 고칠 것)
+#  /api 프록시는 BACKEND_PORT 로 보낸다)
 # ==========================================
 FRONTEND_PORT=5173
 BACKEND_PORT=3000
@@ -37,10 +37,17 @@ REDIS_PASSWORD=change-me-in-local-env
 REDIS_DATA_DIR=./data/redis
 
 # ==========================================
-# API 경로 설정
+# API 경로 · CORS — 프론트와 API 는 같은 도메인을 쓴다
+#
+# 브라우저는 /api 상대경로로만 호출하고, 개발에서는 vite dev 프록시가
+# 운영에서는 Nginx Proxy Manager 가 백엔드로 넘긴다 (운영과 같은 구조).
+#
+#   BACKEND_API_URL : 프론트 번들에 박히는 API 경로 (compose 로 프론트 컨테이너를 빌드할 때 쓰인다)
+#   CORS_ORIGIN     : 다른 오리진에서 API 를 호출할 때만 작성 (scheme://host[:port], 콤마 구분)
+#                     같은 출처 요청에는 CORS 가 적용되지 않으므로 기본은 비워 둔다.
 # ==========================================
-BACKEND_API_URL=http://localhost:3000/api
-CORS_ORIGIN=http://localhost:5173
+BACKEND_API_URL=/api
+CORS_ORIGIN=
 
 # ==========================================
 # Rate Limiting (API 남용 방지)

.env.production.example

@@ -9,8 +9,14 @@ BACKEND_DIR=backend
 
 # ==========================================
 # 포트 설정
+#
+# 운영에서는 컨테이너 포트를 호스트에 열지 않는다.
+# Nginx Proxy Manager 가 proxy 네트워크로 컨테이너에 직접 붙는다 (README "운영 배포"):
+#   frontend → ${PROJECT_NAME}-frontend:8080          (nginx-unprivileged 고정 포트)
+#   backend  → ${PROJECT_NAME}-backend:${BACKEND_PORT}
+# FRONTEND_PORT·DB_PORT·REDIS_PORT 는 개발 환경의 호스트 포트 매핑에만 쓰인다.
 # ==========================================
-FRONTEND_PORT=80
+FRONTEND_PORT=5173
 BACKEND_PORT=3000
 WEBSOCKET_PORT=3001
 DB_PORT=5432
@@ -33,21 +39,26 @@ REDIS_PASSWORD=CHANGE-ME-BEFORE-DEPLOY
 REDIS_DATA_DIR=./data/redis
 
 # ==========================================
-# API 경로 설정
+# API 경로 · CORS — 프론트와 API 는 **같은 도메인**을 쓴다 (기본 구성)
 #
-# ⚠️ 운영에서는 **반드시 실제 공개 도메인**으로 교체한다.
-#    - BACKEND_API_URL : 브라우저가 호출할 API 주소 (프론트엔드 번들에 그대로 박힌다)
-#    - CORS_ORIGIN     : 백엔드가 허용할 오리진 (scheme+host[+port], 여러 개면 콤마 구분)
+#   https://<도메인>/        → frontend 컨테이너 (NPM Proxy Host 의 기본 대상)
+#   https://<도메인>/api/... → backend 컨테이너  (같은 Proxy Host 의 Custom location /api)
 #
-#    아래 example.com 이나 localhost 가 남아 있으면 **백엔드가 기동에 실패한다**
-#    (backend/src/shared/config/env.validation.ts — fail-fast).
-#    기동은 되는데 브라우저만 조용히 실패하는 상황을 막기 위한 검사다.
+#   BACKEND_API_URL : 브라우저가 호출할 API 경로 (프론트엔드 번들에 그대로 박힌다)
+#                     /api 그대로 두면 도메인이 바뀌어도 다시 빌드할 필요가 없다.
+#   CORS_ORIGIN     : 다른 오리진에서 API 를 호출할 때만 작성 (scheme://host[:port], 콤마 구분)
+#                     같은 출처 요청에는 CORS 가 적용되지 않으므로 기본은 비워 둔다.
 #
-#    로컬에서 운영 이미지를 검증하느라 일부러 localhost 를 쓰는 경우에만
-#    ALLOW_LOCALHOST_URL=true 로 이 검사를 건너뛴다. 실제 배포에는 설정하지 않는다.
+# API 를 별도 도메인(api.<도메인>)으로 분리할 때만:
+#   BACKEND_API_URL=https://api.<도메인>/api · CORS_ORIGIN=https://<도메인> 로 바꾸고
+#   frontend/nginx.conf 의 CSP connect-src 에 API 오리진을 추가한다.
+#   이때 localhost 나 example.com 이 남아 있으면 **백엔드가 기동에 실패한다**
+#   (backend/src/shared/config/env.validation.ts — fail-fast).
+#   로컬에서 운영 이미지를 검증하느라 일부러 localhost 를 쓰는 경우에만
+#   ALLOW_LOCALHOST_URL=true 로 이 검사를 건너뛴다. 실제 배포에는 설정하지 않는다.
 # ==========================================
-BACKEND_API_URL=https://api.example.com/api
-CORS_ORIGIN=https://app.example.com
+BACKEND_API_URL=/api
+CORS_ORIGIN=
 
 # ==========================================
 # Rate Limiting (API 남용 방지)

README.md

@@ -41,7 +41,8 @@ cd frontend && npm install && npm run dev
 기동 후:
 
 - 웹: <http://localhost:5173>
-- API: <http://localhost:3000/api>
+- API: <http://localhost:5173/api> — 브라우저가 쓰는 경로 (vite 프록시가 백엔드로 넘긴다, 운영과 같은 구조)
+  · 백엔드 직접: <http://localhost:3000/api>
 - Swagger 문서: <http://localhost:3000/api-docs>
 
 > **개발 환경에서 프론트엔드는 컨테이너로 뜨지 않습니다.**
@@ -67,10 +68,76 @@ cd frontend && npm install && npm run dev
 > **포트는 루트 `.env.{env}` 를 따릅니다.** 호스트에서 띄우는 vite 도 `FRONTEND_PORT` 로 열리고,
 > `/api` 프록시 대상은 `BACKEND_PORT` 에서 나옵니다 — `vite.config.ts` 가 루트 env 를 직접 읽습니다.
 > 포트가 이미 사용 중이면 조용히 다른 포트로 옮기지 않고 **실패**합니다
-> (`CORS_ORIGIN` 과 compose 포트 매핑이 그 값에 묶여 있어, 말없이 옮겨가면 원인 모르게 어긋납니다).
+> (대개 다른 vite 가 이미 그 포트에 떠 있다는 뜻이라, 말없이 옮겨가면 브라우저가 엉뚱한 서버를 보게 됩니다).
 
 전체 실행/배포 명령어는 [`.claude/skills/docker/SKILL.md`](./.claude/skills/docker/SKILL.md) 참조.
 
+## 운영 배포 — 프론트·API 를 같은 도메인으로 (Nginx Proxy Manager)
+
+브라우저는 **도메인 하나만** 봅니다. 경로로 프론트와 백엔드를 나눕니다.
+
+```
+https://app.your-domain.com/          → <PROJECT_NAME>-frontend:8080   nginx 정적 호스팅 (Proxy Host 기본 대상)
+https://app.your-domain.com/api/...   → <PROJECT_NAME>-backend:3000    NestJS        (Custom location /api)
+```
+
+- 프론트 번들은 API 를 `/api` **상대경로**로 호출합니다 — 도메인이 바뀌어도 다시 빌드할 필요가 없습니다.
+- 같은 출처 요청이라 **CORS 설정이 필요 없고**, CSP `connect-src 'self'` 가 그대로 동작하며, 인증 쿠키도 같은 사이트로 다룹니다.
+- 개발 환경도 같은 구조입니다 — vite dev 서버가 `/api` 를 백엔드로 프록시합니다.
+
+### 1) 공유 네트워크 (서버당 1회)
+
+NPM 과 앱 컨테이너가 외부 네트워크 `proxy` 를 공유해야 NPM 이 컨테이너 이름으로 찾아갈 수 있습니다.
+이 네트워크가 없으면 compose 가 기동하지 않습니다.
+
+```bash
+docker network create proxy                     # 이미 있으면 생략
+docker network connect proxy <NPM 컨테이너 이름>  # NPM 이 아직 proxy 네트워크에 없다면
+```
+
+> NPM 은 `<PROJECT_NAME>-frontend` 같은 **컨테이너 이름**으로 접근하므로, 같은 서버에 여러 프로젝트를 올린다면 `PROJECT_NAME` 이 겹치지 않게 합니다.
+
+### 2) 앱 기동
+
+```bash
+cp .env.production.example .env.production                 # placeholder 교체 — BACKEND_API_URL=/api 는 그대로 둔다
+cp backend/.env.production.example backend/.env.production
+sudo docker compose --env-file .env.production up -d --build
+```
+
+### 3) NPM 설정 — Proxy Host 하나 + Custom location 하나
+
+| 탭 | 항목 | 값 |
+| --- | --- | --- |
+| Details | Domain Names | `app.your-domain.com` |
+| | Scheme · Forward Hostname · Port | `http` · `<PROJECT_NAME>-frontend` · `8080` |
+| | Cache Assets | **끔** (아래 주의 참조) |
+| | Block Common Exploits | 켬 (선택) |
+| Custom locations | location | `/api` |
+| | Scheme · Forward Hostname · Port | `http` · `<PROJECT_NAME>-backend` · `3000` (`BACKEND_PORT`) |
+| SSL | | 인증서 발급 + Force SSL |
+
+> ⚠️ **Cache Assets 는 끕니다.** 켜면 NPM 이 `.png`·`.js`·`.css` 등으로 끝나는 요청을 custom location 안에서도 가로채
+> **Proxy Host 의 기본 대상(frontend)** 으로 보냅니다. `/api/files/abc.png` 같은 API 가 프론트로 가 버립니다.
+> 프론트 정적 자원의 캐시 헤더는 frontend nginx 가 이미 붙입니다.
+
+> - location 은 `/api` (끝 슬래시 없음) — 접두어 매칭이라 Swagger(`/api-docs`)까지 백엔드로 갑니다. 개발의 vite 프록시와 같은 규칙입니다.
+> - Forward Hostname 에 경로를 붙이지 않습니다. 요청 경로가 그대로 넘어가야 백엔드의 `/api` prefix 와 맞습니다.
+> - **`/api` 로 시작하는 경로는 프론트 라우트로 쓰지 않습니다** (전부 백엔드로 갑니다).
+
+### 4) 확인
+
+```bash
+curl -i https://app.your-domain.com/api/health   # 200 {"status":"ok",...}  ← 백엔드가 응답
+curl -I https://app.your-domain.com/             # 200 text/html           ← 프론트가 응답
+```
+
+`/api/health` 가 **404** 면 custom location 이 빠진 것입니다 —
+frontend nginx 는 자기에게 떨어진 `/api` 요청을 404 로 막아 둡니다 (index.html 로 폴백해 조용히 실패하지 않도록).
+
+> API 를 별도 도메인(`api.your-domain.com`)에 두는 구성이 필요하다면 `.env.production.example` 의 안내대로
+> `BACKEND_API_URL`·`CORS_ORIGIN` 과 `frontend/nginx.conf` 의 CSP `connect-src` 를 함께 바꿉니다.
+
 ## 모바일 앱 실행 (Flutter)
 
 Flutter 는 Docker Compose 대상이 아니므로 로컬에서 직접 실행합니다.
@@ -79,7 +146,8 @@ Flutter 는 Docker Compose 대상이 아니므로 로컬에서 직접 실행합
 cd flutter && cp .env.example .env && flutter pub get && flutter run
 ```
 
-> `flutter/.env` 의 `API_URL` 을 백엔드 주소로 설정합니다. (Android 에뮬레이터는 `http://10.0.2.2:3000/api`)
+> `flutter/.env` 의 `API_URL` 을 백엔드 주소로 설정합니다. (Android 에뮬레이터는 `http://10.0.2.2:3000/api`,
+> 운영은 웹과 같은 도메인의 `https://app.your-domain.com/api`)
 
 ## 환경변수
 
@@ -92,7 +160,7 @@ cd flutter && cp .env.example .env && flutter pub get && flutter run
 | ----------------------------- | ---------------------------------------- | --------------------- |
 | `.env.{env}.example`          | 루트 — 모든 설정의 SSOT (compose 주입)   | ✅ 여기에 작성        |
 | `backend/.env.{env}.example`  | 백엔드 — 고유 시크릿(JWT 등)만           | 최소 (존재 필수)      |
-| `frontend/.env.{env}.example` | 프론트 — 빌드 시 루트 `BACKEND_API_URL` 주입 | 작성 불필요          |
+| `frontend/.env.{env}.example` | 프론트 — 빌드 시 루트 `BACKEND_API_URL`(기본 `/api`) 주입 | 작성 불필요 |
 | `flutter/.env.example`        | 모바일 — `API_URL` (compose 비대상)      | ✅ 독립 관리          |
 
 `{env}` = `development` | `production`

backend/src/main.ts

@@ -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)로 응답된다.

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

@@ -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);
+  });
+});

backend/src/shared/config/cors.config.ts

@@ -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,
+  };
+}

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

@@ -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 가 설정되지 않았습니다/,

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

@@ -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';
 

docker-compose.yml

@@ -1,6 +1,16 @@
+# ==========================================
+# 운영 라우팅 — 프론트와 API 는 같은 도메인을 쓴다
+#
+#   https://<도메인>/        → frontend:8080             (Nginx Proxy Manager Proxy Host 의 기본 대상)
+#   https://<도메인>/api/... → backend:${BACKEND_PORT}   (같은 Proxy Host 의 Custom location /api)
+#
+# 브라우저는 /api 상대경로로만 호출하므로 CORS 가 필요 없다.
+# NPM 은 아래 proxy 외부 네트워크로 컨테이너 이름(${PROJECT_NAME}-frontend / -backend)에 접근한다.
+# 설정 절차는 README "운영 배포" 참조.
+# ==========================================
 services:
   # ----------------------------------------
-  # 1. Frontend (Nginx 정적 호스팅)
+  # 1. Frontend (Nginx 정적 호스팅) — NPM Proxy Host 의 기본 대상(/)
   # ----------------------------------------
   frontend:
     container_name: ${PROJECT_NAME}-frontend
@@ -9,7 +19,8 @@ services:
       dockerfile: Dockerfile
       args:
         - BUILD_MODE=${BUILD_MODE}
-        - VITE_API_BASE_URL=${BACKEND_API_URL}
+        # 같은 도메인 구성이면 /api 그대로 — 도메인이 바뀌어도 이미지를 다시 빌드할 필요가 없다
+        - VITE_API_BASE_URL=${BACKEND_API_URL:-/api}
     expose:
       - "8080"
     environment:
@@ -34,7 +45,7 @@ services:
           memory: 512m
 
   # ----------------------------------------
-  # 2. Backend (HTTP API & WebSocket 통합)
+  # 2. Backend (HTTP API & WebSocket 통합) — NPM Custom location /api 의 대상
   # ----------------------------------------
   backend:
     container_name: ${PROJECT_NAME}-backend
@@ -54,10 +65,11 @@ services:
       - NODE_ENV=${APP_ENV}
       - PORT=${BACKEND_PORT}
       - WEBSOCKET_PORT=${WEBSOCKET_PORT}
-      - CORS_ORIGIN=${CORS_ORIGIN}
-      # 앱이 직접 쓰지는 않는다. 로컬 주소가 남은 채 운영에 배포되는 것을
-      # 기동 시점에 잡기 위해 검증용으로 주입한다 (shared/config/env.validation.ts)
-      - BACKEND_API_URL=${BACKEND_API_URL}
+      # 같은 도메인 구성에서는 비어 있다 — 다른 오리진에서 호출할 때만 콤마로 나열
+      - CORS_ORIGIN=${CORS_ORIGIN:-}
+      # 앱이 직접 쓰지는 않는다. API 를 별도 도메인으로 분리했을 때 로컬 주소가 남은 채
+      # 운영에 배포되는 것을 기동 시점에 잡기 위해 검증용으로 주입한다 (shared/config/env.validation.ts)
+      - BACKEND_API_URL=${BACKEND_API_URL:-/api}
       # 위 공개 주소 검사를 건너뛰는 탈출구 — 로컬에서 운영 이미지를 검증할 때만 true
       - ALLOW_LOCALHOST_URL=${ALLOW_LOCALHOST_URL:-}
       - THROTTLE_TTL_MS=${THROTTLE_TTL_MS:-60000}
@@ -167,5 +179,8 @@ services:
 networks:
   app-network:
     driver: bridge
+  # 리버스 프록시(Nginx Proxy Manager)와 공유하는 외부 네트워크 — frontend·backend 만 붙는다 (db·redis 는 내부 전용)
+  # compose 가 만들지 않으므로 서버에서 한 번 만들어 두어야 기동한다:  docker network create proxy
+  # NPM 은 컨테이너 이름으로 찾아오므로 같은 서버의 프로젝트끼리 PROJECT_NAME 이 겹치면 안 된다.
   proxy:
     external: true

flutter/.env.example

@@ -9,4 +9,5 @@
 
 # 백엔드 API 베이스 URL (백엔드 글로벌 prefix /api 포함)
 # 안드로이드 에뮬레이터에서 호스트 접근 시: http://10.0.2.2:3000/api
+# 운영: 웹과 같은 도메인의 /api — 예) https://app.your-domain.com/api
 API_URL=http://localhost:3000/api

frontend/.env.development.example

@@ -1,15 +1,17 @@
 # ==========================================
 # 프론트엔드 환경변수 (development)
 #
-# ⚠️ VITE_API_BASE_URL 은 루트 .env.development 의 BACKEND_API_URL 이
-#    docker-compose build arg 로 주입된다 — 여기에 작성할 필요가 없다.
+# ⚠️ 보통은 이 파일이 필요 없다.
+#    API 는 같은 도메인의 /api 로 호출하고(useApi.ts 기본값), vite dev 프록시가 백엔드로 넘긴다.
+#    컨테이너 빌드 때는 루트 .env.development 의 BACKEND_API_URL 이 build arg 로 주입된다.
 #    (SSOT: 루트 .env — .claude/rules/env-structure.md)
 #
-# Docker 없이 vite dev 서버를 직접 띄울 때만 아래 값을 사용한다.
+# 백엔드를 프록시 없이 직접 호출해야 하는 특수한 경우에만 복사해 쓴다.
 #   cp .env.development.example .env.development
+#   → 절대 URL 로 바꾸면 다른 오리진 호출이 되므로 루트 CORS_ORIGIN 에 이 프론트 주소를 추가해야 한다.
 #
 # 모든 키는 VITE_ 접두어가 있어야 클라이언트 번들에 포함된다.
 # ⚠️ 번들에 그대로 노출되므로 시크릿을 넣지 말 것.
 # ==========================================
 
-# VITE_API_BASE_URL=http://localhost:3000/api
+# VITE_API_BASE_URL=/api

frontend/.env.production.example

@@ -1,15 +1,16 @@
 # ==========================================
 # 프론트엔드 환경변수 (production)
 #
-# ⚠️ VITE_API_BASE_URL 은 루트 .env.production 의 BACKEND_API_URL 이
-#    docker-compose build arg 로 주입된다 — 여기에 작성할 필요가 없다.
-#    (SSOT: 루트 .env — .claude/rules/env-structure.md)
+# ⚠️ 보통은 이 파일이 필요 없다.
+#    API 는 같은 도메인의 /api 로 호출하고(useApi.ts 기본값), 리버스 프록시(Nginx Proxy Manager 의
+#    Custom location)가 백엔드로 넘긴다. 컨테이너 빌드 때는 루트 .env.production 의 BACKEND_API_URL 이
+#    build arg 로 주입된다. (SSOT: 루트 .env — .claude/rules/env-structure.md)
 #
-# Docker 없이 vite dev 서버를 직접 띄울 때만 아래 값을 사용한다.
+# compose 를 거치지 않고 호스트에서 직접 빌드할 때만 복사해 쓴다.
 #   cp .env.production.example .env.production
 #
 # 모든 키는 VITE_ 접두어가 있어야 클라이언트 번들에 포함된다.
 # ⚠️ 번들에 그대로 노출되므로 시크릿을 넣지 말 것.
 # ==========================================
 
-# VITE_API_BASE_URL=http://localhost:3000/api
+# VITE_API_BASE_URL=/api

frontend/Dockerfile

@@ -16,7 +16,9 @@ RUN npm ci
 COPY --chown=node:node . .
 
 ARG BUILD_MODE=production
-ARG VITE_API_BASE_URL
+# 브라우저가 호출할 API 경로 — 기본은 같은 도메인의 /api (리버스 프록시가 백엔드로 넘긴다).
+# compose 가 루트 BACKEND_API_URL 을 넘긴다. API 를 별도 도메인에 둘 때만 절대 URL 이 들어온다.
+ARG VITE_API_BASE_URL=/api
 ENV VITE_API_BASE_URL=$VITE_API_BASE_URL
 
 RUN npm run build-only -- --mode ${BUILD_MODE}

frontend/env.d.ts

@@ -2,7 +2,8 @@
 
 // Vite 환경변수 타입 정의 — VITE_ prefix 만 클라이언트 번들에 포함됨
 interface ImportMetaEnv {
-  readonly VITE_API_BASE_URL: string
+  /** API baseURL — 비어 있으면 같은 도메인의 /api (useApi.ts). 별도 도메인에 API 를 둘 때만 절대 URL */
+  readonly VITE_API_BASE_URL?: string
 }
 
 interface ImportMeta {

frontend/nginx.conf

@@ -16,7 +16,8 @@ server {
     # ⚠️ 프로젝트에 맞게 조정이 필요한 설정이다. 기본값 설명:
     #   - default-src 'self'  : 기본적으로 같은 출처만 허용
     #   - style-src 'unsafe-inline' : Vue 의 동적 스타일 바인딩(:style)이 인라인 스타일을 생성하므로 필요
-    #   - connect-src 'self'  : API 가 다른 도메인이면 그 origin 을 반드시 추가할 것
+    #   - connect-src 'self'  : API 는 같은 도메인의 /api 로 호출하므로 'self' 로 충분하다.
+    #                           API 를 별도 도메인에 둘 때만 그 origin 을 추가한다
     #                           (예: connect-src 'self' https://api.example.com)
     #   - img-src data: blob: : 인라인 아이콘·캔버스/파일 미리보기 대응
     #   - frame-ancestors 'none' : 클릭재킹 차단 (X-Frame-Options 의 최신 대체재)
@@ -33,6 +34,18 @@ server {
     gzip_min_length 1024;
     gzip_types text/plain text/css text/javascript application/javascript application/json application/xml image/svg+xml;
 
+    # ----------------------------------------
+    # /api 는 백엔드 전용 경로 — 여기까지 왔다면 리버스 프록시 설정이 빠진 것이다
+    #
+    # 운영에서는 Nginx Proxy Manager 의 Custom location(/api)이 이 경로를 backend 로 보내므로
+    # 이 컨테이너에는 도달하지 않는다. 그 설정이 빠지면 아래 SPA 폴백이 index.html 을 200 으로 돌려줘
+    # API 호출이 **조용히** HTML 을 받아 실패한다 — 404 로 막아 문제가 바로 드러나게 한다.
+    # (/api 로 시작하는 경로는 프론트엔드 라우트로 쓰지 않는다 — .claude/rules/api-design.md)
+    # ----------------------------------------
+    location ^~ /api {
+        return 404;
+    }
+
     # ----------------------------------------
     # SPA 라우팅
     # ----------------------------------------

frontend/src/composables/useApi.spec.ts

@@ -4,7 +4,22 @@ import {
   ERROR_CODE_MESSAGES,
   FALLBACK_ERROR_CODE,
 } from '@/shared/constants/error-codes.generated'
-import { getErrorMessage } from './useApi'
+import { getErrorMessage, resolveApiBaseUrl } from './useApi'
+
+describe('API 기본 경로', () => {
+  it('설정이 없으면 같은 도메인의 /api 로 호출한다 (리버스 프록시가 백엔드로 넘긴다)', () => {
+    expect(resolveApiBaseUrl(undefined)).toBe('/api')
+    // compose 는 정의되지 않은 변수를 빈 문자열로 넘긴다
+    expect(resolveApiBaseUrl('')).toBe('/api')
+    expect(resolveApiBaseUrl('  ')).toBe('/api')
+  })
+
+  it('API 를 별도 도메인에 둔 경우에만 절대 URL 을 그대로 쓴다', () => {
+    expect(resolveApiBaseUrl('https://api.myservice.io/api')).toBe(
+      'https://api.myservice.io/api',
+    )
+  })
+})
 
 describe('에러 코드 사전', () => {
   it('등록된 코드는 해당 한국어 메시지를 반환한다', () => {

frontend/src/composables/useApi.ts

@@ -35,6 +35,23 @@ const API_TIMEOUT_MS = 10000
 /** 동일 코드의 알림이 짧은 시간에 중복 노출되는 것을 막는 간격 */
 const DUPLICATE_ALERT_WINDOW_MS = 3000
 
+/**
+ * API 기본 경로 — 프론트와 같은 도메인의 /api.
+ * 운영은 리버스 프록시(Nginx Proxy Manager 의 Custom location)가, 개발은 vite dev 프록시가
+ * 이 경로를 백엔드로 넘긴다. 같은 출처라 CORS 가 필요 없고, 도메인이 바뀌어도 다시 빌드하지 않는다.
+ */
+export const DEFAULT_API_BASE_URL = '/api'
+
+/**
+ * 빌드 시 주입된 baseURL 을 확정한다.
+ * 비어 있으면(compose 가 빈 문자열을 넘기는 경우 포함) 같은 도메인의 /api 를 쓴다.
+ * API 를 별도 도메인에 둘 때만 절대 URL 이 들어온다 — 그때는 백엔드 CORS_ORIGIN 과 nginx CSP 도 함께 바꾼다.
+ */
+export function resolveApiBaseUrl(configured: string | undefined): string {
+  const trimmed = configured?.trim()
+  return trimmed ? trimmed : DEFAULT_API_BASE_URL
+}
+
 function isErrorCode(code: string): code is ErrorCode {
   return code in ERROR_CODE_MESSAGES
 }
@@ -59,7 +76,7 @@ const showErrorUI = (code: ErrorCode, message: string) => {
 
 // 중앙 Axios 인스턴스
 const api: AxiosInstance = axios.create({
-  baseURL: import.meta.env.VITE_API_BASE_URL || '/api',
+  baseURL: resolveApiBaseUrl(import.meta.env.VITE_API_BASE_URL),
   timeout: API_TIMEOUT_MS,
   // HttpOnly/Secure 쿠키 인증 시 자격 증명을 함께 전송
   withCredentials: true,

frontend/vite.config.ts

@@ -59,12 +59,15 @@ export default defineConfig(({ mode }) => {
       // 컨테이너로 띄울 때는 compose 의 `--port`(컨테이너 내부 고정 포트)가 이 값을 덮어쓴다.
       port: frontendPort,
       // 포트가 이미 사용 중이면 조용히 다음 포트로 옮기지 않고 실패한다.
-      // 루트 .env 의 CORS_ORIGIN 과 compose 포트 매핑이 이 포트에 묶여 있어,
-      // 말없이 5174 로 옮겨가면 API 요청이 원인 모르게 막힌다 (fail-fast).
+      // 대개 다른 vite(컨테이너 vite 포함 — compose 가 같은 FRONTEND_PORT 를 매핑한다)가 이미 떠 있다는 뜻이라,
+      // 말없이 5174 로 옮겨가면 브라우저는 여전히 5173 의 엉뚱한 서버를 보게 된다 (fail-fast).
       strictPort: true,
       // 도커 바인드 마운트에서는 inotify 가 호스트 쪽 변경을 잡지 못해 폴링이 필요하다
       watch: usePolling ? { usePolling: true } : undefined,
-      // 개발 서버 API 프록시.
+      // 개발 서버 API 프록시 — 운영 리버스 프록시(Nginx Proxy Manager 의 Custom location /api)와 같은 역할.
+      // 브라우저는 개발·운영 모두 같은 출처의 /api 로만 호출하므로 CORS 가 끼어들지 않는다.
+      // 접두어 매칭이라 /api-docs(Swagger)도 백엔드로 간다 — 운영의 location /api 와 같은 규칙이다.
+      //
       // useApi 의 baseURL 은 '/api'(상대경로)라 프록시가 없으면 vite 가 SPA 폴백으로
       // index.html 을 200 으로 돌려준다 — 요청이 조용히 HTML 을 받아 실패한다.
       //