ttipo
7897f2de20
템플릿 점검에서 나온 항목을 한 번에 반영한다. 항목별 이유: - Node 20 → 24 LTS (Dockerfile·CI): Node 20 은 2026-04-30 에 지원이 끝나 보안 패치가 없다 - backend·frontend .dockerignore 추가: `COPY . .` 가 호스트 node_modules(Windows 바이너리)·dist· .env*(시크릿)를 이미지에 넣고 있었다 - 업로드 디렉터리 쓰기 검사(fail-fast): Linux 에서 Docker 가 root 소유로 만든 바인드 마운트에 비-root 앱이 쓰지 못해 첫 업로드에서야 SYS_001 로 터졌다. 기동 시 해결 명령을 안내한다 - DB 커넥션 풀 100 → 10 (DB_POOL_MAX): PostgreSQL 기본 max_connections(100)를 앱 하나가 다 잡았다 - Swagger 운영 기본 비활성 (SWAGGER_ENABLED): API 구조 전체가 공개 도메인에 노출됐다 - 헬스체크 운영 응답에서 오류 상세 제거: 드라이버 오류 문구에 내부 주소·DB 계정명이 담긴다. 원인은 error 로그로 남긴다 - nginx: location 의 add_header 때문에 정적 자원에서 보안 헤더가 빠지던 문제와, index.html 이 캐시돼 배포 직후 빈 화면이 날 수 있던 문제를 고친다 - vite allowedHosts: true 제거 (DEV_ALLOWED_HOSTS): DNS rebinding 보호가 꺼져 있었다 - 전역 설정을 configureApp() 으로 분리해 main.ts 와 e2e 가 공유: e2e 가 설정을 복사해 재현해 실제 설정과 어긋나도 통과할 수 있었다. PORT 도 빈 값을 방어하는 파서를 거친다 - 쓰이지 않던 WEBSOCKET_PORT 제거: 별도 포트는 같은 도메인 라우팅과 맞지 않는다 - 예제 useUser 가 메시지 대신 에러 코드를 보관하도록 수정, testing.md 표 깨짐 수정, settings.json 허용 목록에서 npm install 제거 (Windows lock 파일 규칙과 충돌) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.0 KiB
5.0 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 })에 연결되어 있다.- 숫자 항목(
PORT·DB_PORT·DB_POOL_MAX·THROTTLE_*)은 형식 검사 (모든 환경) - 참/거짓 항목(
SWAGGER_ENABLED)은true/false만 허용 (모든 환경) — 오타가 조용히 기본값으로 묻히지 않게 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,SWAGGER_ENABLED,DB_*/DB_DATA_DIR/DB_POOL_MAX,REDIS_*/REDIS_DATA_DIR,THROTTLE_TTL_MS/THROTTLE_LIMIT,DEV_ALLOWED_HOSTS(호스트 vite 전용). 실제 목록은.env.development.example참조. 실행/배포 명령은 docker, 보안 규칙은 security 참조.