ttipo
6dcbb45eb9
브라우저가 프론트와 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>
4.7 KiB
4.7 KiB
name, description
| name | description |
|---|---|
| env-structure | 환경변수 단일 진실 공급원(SSOT) 구조 — 루트 .env.{APP_ENV} 가 모든 설정의 SSOT, docker-compose 가 서비스에 주입. 새 설정값 추가/서비스 env 작성 규칙. |
환경변수 구조 (단일 진실 공급원: 루트 .env)
이 템플릿은 루트 .env.{APP_ENV} 가 모든 설정의 단일 진실 공급원(SSOT) 이다.
값을 한 곳에서만 관리하기 위해, 서비스(backend/frontend)는 자체 env에 값을 중복 작성하지 않고 루트 → docker-compose 가 주입한 값을 그대로 사용한다.
루트 .env.{APP_ENV}
│ (docker compose --env-file 로 로드)
├─▶ backend : env_file + environment 로 DB/Redis/CORS/포트 주입
│ (backend/.env.{APP_ENV} 는 "존재"만 하면 됨, 내용 최소)
├─▶ 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 볼륨
└─▶ redis : REDIS_PASSWORD, REDIS_DATA_DIR 볼륨
규칙:
- 새 설정값은 루트
.env.{APP_ENV}에 먼저 추가하고, 필요한 서비스에docker-compose.yml의environment/args로 전달한다. - 서비스 자체 env 파일에는 루트에서 내려주지 않는 고유 값만 작성한다. (예: 백엔드
JWT_SECRET) - compose 는 정의되지 않은 변수를 빈 문자열로 주입한다. 코드에서
??기본값만 쓰면Number('')===0같은 함정에 빠진다 — 숫자 설정값은shared/utils/env.ts의parsePositiveInt()처럼 빈 문자열까지 방어하는 파서를 거친다. (기존.env를 쓰는 사람이 새 키를 추가하지 않아도 안전해야 한다) docker-compose.yml의env_file지시자 때문에backend/.env.{APP_ENV}파일은 비어 있어도 존재해야 한다.- 프론트엔드 dev 서버는 compose 를 거치지 않는다 — 호스트에서 직접 띄우므로(docker)
vite.config.ts가 루트.env.{mode}를loadEnv로 읽어 포트·프록시 대상을 정한다. 포트를frontend/.env나vite.config.ts에 중복 작성하지 말 것 — 루트가 SSOT 다. (읽은 값은 dev 서버 설정에만 쓰고 클라이언트 번들에는 넣지 않는다 —VITE_없는 값의 번들 노출 금지, security) - Flutter 는 예외 — docker-compose 대상이 아니므로
flutter/.env에서API_URL을 독립적으로 관리한다. - 모든 env 파일은 커밋 금지,
*.example만 커밋한다. (.gitignore의!*.example재포함 규칙) - 설정이 잘못되면 서버가 뜨지 않아야 한다(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 에 주입한다) - 문제는 하나씩이 아니라 한 번에 모아서 보여준다 (재기동 반복 방지)
- 새 필수 설정을 추가하면 이 파일의 목록과 테스트도 함께 갱신한다
루트 env의 대표 키:
PROJECT_NAME,APP_ENV,BUILD_MODE, 각종*_PORT,BACKEND_API_URL,CORS_ORIGIN,DB_*/DB_DATA_DIR,REDIS_*/REDIS_DATA_DIR,THROTTLE_TTL_MS/THROTTLE_LIMIT. 실제 목록은.env.development.example참조. 실행/배포 명령은 docker, 보안 규칙은 security 참조.