ttipo/rup

Files

T

ttipo 5331362215 docs(rules): 서버화에 맞춰 규칙·스킬 문서 갱신

구현한 구조를 규칙 SSOT 에 반영한다 — 다음 작업이 같은 패턴을 쓰도록.

- security: 모바일 리프레시 토큰은 secure storage(쿠키 저장소가 없다) — 대신 해시 저장·회전·재사용 탐지.
  소셜 토큰은 서버가 제공자에게 확인, 개발용 로그인은 운영에서 코드로 닫힘, 업로드 매직 바이트 검사·소유자 확인
- nestjs 스킬: 인증·회원·도메인 모듈·커서 헬퍼·공통 검증·snake_case 이름 규칙·아이 삭제 정리 리스너,
  새 라우트는 기본 로그인 필요(@Public 예외)·새 엔티티는 소유자 조건 조회
- flutter 스킬: DATA_MODE, 세션·토큰 갱신, 실패 알림·succeeded(), 서버 사진, 저장소 계약(Local·Api) 패턴
- env·응답 형식·에러 코드·테스트·체크리스트: DATA_MODE·소셜 키, keysetPaginate·fetchAllPages,
  도메인 코드 목록, 앱의 AUTH_002 흐름, 가짜 서버·라이브 점검 테스트
- vue3 스킬: 웹 로그인 연동 시 필요한 것 (지금 인증은 모바일용)

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

2026-10-11 18:43:48 +09:00

4.9 KiB

Raw Blame History

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 → 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·DATA_MODE 를 독립적으로 관리한다. DATA_MODE=api(기본)는 서버에 저장하고, local 은 서버 없이 기기에 저장한다(화면 확인용). .env 를 읽지 않는 테스트는 local 로 돈다.
백엔드 소셜 로그인 값(KAKAO_APP_ID·NAVER_CLIENT_ID·GOOGLE_CLIENT_IDS·APPLE_CLIENT_IDS)과 AUTH_DEV_LOGIN 은 루트에서 내려주지 않는 백엔드 고유 값이라 backend/.env.{APP_ENV} 에 둔다.
모든 env 파일은 커밋 금지, *.example 만 커밋한다. (.gitignore 의 !*.example 재포함 규칙)
설정이 잘못되면 서버가 뜨지 않아야 한다(fail-fast). 조용히 기본값으로 굴러가다 운영에서 터지는 것이 더 위험하다. 검증은 backend/src/shared/config/env.validation.ts 가 담당하며 ConfigModule.forRoot({ validate }) 에 연결되어 있다.
- 숫자 항목은 형식 검사 (모든 환경)
- 운영 환경: DB_HOST/DB_USER/DB_PASSWORD/DB_NAME/JWT_SECRET(32자 이상) 필수
- 토큰 만료 기간(JWT_ACCESS_EXPIRES_IN·JWT_REFRESH_EXPIRES_IN)은 15m·1h·14d 형식 (모든 환경)
- 운영 환경: change-me·password 같은 예시 값이 그대로 배포되는 것을 차단
- 운영 환경: CORS_ORIGIN·BACKEND_API_URL 에 로컬 주소(localhost·127.0.0.1 등)나 예시 도메인(example.com)이 남아 있으면 차단 — 기동은 되는데 브라우저만 조용히 실패하는 조합을 막는다. 로컬에서 운영 이미지를 검증하느라 일부러 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 참조.

4.9 KiB Raw Blame History

환경변수 구조 (단일 진실 공급원: 루트 .env)

4.9 KiB

Raw Blame History

환경변수 구조 (단일 진실 공급원: 루트 `.env`)