project-base/frontend/nginx.conf

server {
    # 비-root(nginx-unprivileged) 구동이라 1024 미만 포트를 쓸 수 없다
    listen       8080;
    server_name  localhost;

    # 빌드 산출물 위치 — 모든 location 이 공유한다
    root   /usr/share/nginx/html;

    # ----------------------------------------
    # 보안 헤더
    #
    # ⚠️ nginx 는 location 안에 add_header 가 하나라도 있으면 여기(server)의 add_header 를
    #    **하나도 상속하지 않는다.** 그래서 아래 location 들은 캐시 정책을 add_header 대신
    #    expires 로 지정한다 — location 에 add_header 를 넣으면 그 응답에서 보안 헤더가 전부 사라진다.
    # ----------------------------------------
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Permissions-Policy "geolocation=(), microphone=(), camera=()" always;

    # Content-Security-Policy — XSS 방어의 핵심 헤더
    #
    # ⚠️ 프로젝트에 맞게 조정이 필요한 설정이다. 기본값 설명:
    #   - default-src 'self'  : 기본적으로 같은 출처만 허용
    #   - style-src 'unsafe-inline' : Vue 의 동적 스타일 바인딩(:style)이 인라인 스타일을 생성하므로 필요
    #   - 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 의 최신 대체재)
    #
    # 외부 폰트·분석 스크립트·이미지 CDN 을 도입하면 해당 도메인을 명시적으로 추가한다.
    # script-src 에 'unsafe-inline'/'unsafe-eval' 을 추가하면 CSP 의 의미가 사라지므로 피할 것.
    add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'" always;

    # ----------------------------------------
    # 압축 (Gzip)
    # ----------------------------------------
    gzip on;
    gzip_vary on;
    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;
    }

    # ----------------------------------------
    # 캐시 정책 — add_header 대신 expires 를 쓴다 (위 보안 헤더 주의 참조)
    # ----------------------------------------

    # SPA 진입점 — 매번 재검증한다 (Cache-Control: no-cache).
    # 배포 직후 옛 index.html 이 캐시에 남으면 이미 지워진 해시 파일을 요청해 빈 화면이 된다.
    # (/ 접속과 SPA 폴백도 내부적으로 /index.html 로 넘어오므로 모두 여기에 걸린다)
    location = /index.html {
        expires -1;
    }

    # 빌드 산출물(vite 의 assets 디렉터리) — 파일명에 내용 해시가 붙어 내용이 바뀌면 이름도 바뀌므로 오래 캐시해도 안전하다.
    # 없는 파일은 index.html 로 폴백하지 않고 404 — HTML 을 JS 로 받아 생기는 MIME 오류를 막는다.
    # (public/ 에서 복사되는 favicon 등은 해시가 없으므로 여기에 넣지 않는다)
    location /assets/ {
        expires 1y;
        try_files $uri =404;
    }

    # ----------------------------------------
    # SPA 라우팅
    # ----------------------------------------
    location / {
        index  index.html index.htm;
        try_files $uri $uri/ /index.html;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }

    # 숨김 파일 접근 차단
    location ~ /\. {
        deny all;
        access_log off;
        log_not_found off;
    }
}