Next.js Server Actions를 Cloudflare Workers에 배포하기 전, 무엇을 검수해야 할까? 2026
Next.js Server Actions의 Cloudflare Workers 배포 검수는 기능 지원 문구만으로 승인하지 말고, 실제 어댑터와 배포 설정에서 호환성·요청 출처·동작 권한·롤백을 확인한 뒤 진행해야 합니다. 필수 기능이나 보안 검사를 목표 환경에서 검증할 수 없다면, 확인되지 않은 사용자 지정 미들웨어로 메우지 말고 출시를 보류합니다.
이 내용은 Workers로 새 앱을 만들거나 기존 Next.js 앱을 옮기는 전체 스택 엔지니어, 요청 출처와 동작 권한을 확인하는 보안 담당자, 증거를 바탕으로 출시를 승인해야 하는 책임자를 위한 기준입니다.
배포 경로와 앱 구성 확인
먼저 새 프로젝트인지, 기존 앱의 이전인지 구분합니다. 그다음 현재 사용하는 Next.js 버전과 빌드 절차, 앱에서 실제로 사용하는 기능을 선택한 Workers 배포 경로와 대조합니다. Cloudflare의 Next.js 배포 안내에서 현재 제시하는 경로와 지원 정보를 확인하되, 해당 경로가 모든 프로젝트의 기능을 동일하게 지원한다고 간주해서는 안 됩니다.
| 선택 상황 | 먼저 확인할 항목 | 승인에 필요한 증거 |
|---|---|---|
| 새 앱 | 안내된 어댑터와 빌드 절차로 최소 기능을 배포합니다. | 빌드 결과, Server Actions 호출 결과, 배포 설정을 보관합니다. |
| 기존 앱 이전 | 기존 기능과 Node.js API 의존성을 목록으로 만들고 대조합니다. | 실제 사용하는 폼, 인증, 업로드, 서버 기능을 목표 환경에서 시험합니다. |
| 어댑터나 설정 변경 | 변경 전후의 빌드 및 런타임 동작을 검증합니다. | 이전에 승인된 버전과 비교한 회귀 결과, 롤백 절차를 남깁니다. |
React 19.2를 사용한다는 사실은 앱 전체가 Workers에서 문제없이 실행된다는 보증이 아닙니다. React의 Server Functions 설명은 서버 함수의 호출 모델을 이해하는 데 도움이 되지만, 배포 어댑터와 런타임의 지원 범위는 별도로 확인해야 합니다.
프록시와 도메인의 요청 신뢰 경계 점검
브라우저, 프록시, Workers, Next.js 앱 사이를 지나는 요청을 실제 배포 구성에서 따라갑니다. Origin, Host, X-Forwarded-Host가 각 단계에서 어떤 값으로 전달되고 덮어써지는지 기록합니다. 프록시가 헤더를 보존한다고 가정하거나, 전달 헤더를 애플리케이션이 무조건 신뢰하도록 두면 안 됩니다.
Next.js의 Server Actions 설정 문서는 요청의 Origin과 Host 또는 X-Forwarded-Host를 비교하는 동작과 allowedOrigins 설정을 설명합니다. 신뢰가 필요한 출처만 허용 목록에 두고, 그 값이 실제 운영 도메인과 일치하는지 확인합니다. 허용 범위를 넓혀 문제를 우회하는 방식은 승인 근거가 될 수 없습니다.
체크 항목은 다음과 같습니다.
- [ ] 브라우저에서 보낸 요청과 앱이 실제로 받은 Origin, Host, X-Forwarded-Host를 비교해 기록합니다.
- [ ] 정상 도메인 외의 출처, Origin 누락, 예상과 다른 값이 거부되는지 확인합니다.
- [ ] 프록시가 전달 헤더를 설정하거나 덮어쓰는 규칙을 검토합니다.
- [ ] 클라이언트가 보낸 전달 헤더를 신뢰 경계 검증 없이 권한 판단에 사용하지 않습니다.
- [ ] 허용 출처 변경이 필요한 경우 변경 사유와 승인자를 기록합니다.
Next.js의 공식 보안 안내에는 Origin이 null인 상황과 관련된 CSRF 보안 이슈가 기록되어 있습니다. 이 사실을 Cloudflare Workers에서 헤더가 일반적으로 사라진다거나, 모든 엣지 배포가 취약하다는 뜻으로 확대해서는 안 됩니다. 영향 여부는 해당 안내의 범위와 현재 사용 버전을 대조해 확인합니다.
민감한 동작의 인증과 권한 검증
Server Actions는 브라우저 폼이나 클라이언트 코드에서 호출될 수 있는 서버 진입점으로 취급합니다. 버튼을 숨겼거나 화면에서 호출 경로가 보이지 않는다는 이유로 권한 검사를 생략하지 않습니다. React Server Functions 문서와 Next.js 인증 안내를 바탕으로 인증과 서버 측 권한 검사가 어디에서 이루어지는지 추적합니다.
각 동작에서 다음 조건을 확인합니다.
- [ ] 로그인 여부를 동작이 실행될 때 서버에서 확인합니다.
- [ ] 요청 사용자가 변경 대상 자원을 소유하거나 접근할 권한이 있는지 확인합니다.
- [ ] 역할 권한과 테넌트 경계를 각각 확인하며, 사용자 입력값만으로 범위를 정하지 않습니다.
- [ ] 미인증, 낮은 권한, 다른 테넌트에 해당하는 요청을 시험합니다.
- [ ] 거부 결과와 함께 데이터 변경이나 외부 작업 같은 부수 효과가 없음을 기록합니다.
계정, 자금, 권한 변경처럼 영향이 큰 동작은 승인 조건을 더 엄격히 둡니다. 인증에 성공했다는 사실만으로 자원 소유권이나 역할 권한까지 확인된 것은 아닙니다.
FAQ: 배포 전 자주 확인하는 항목
Workers에서 Server Actions가 지원되면 바로 출시해도 되나요?
아닙니다. 배포 안내에 기능이 나와 있어도 프로젝트의 선택 경로, 어댑터, 설정과 런타임에서 필요한 기능이 실제로 맞는지 확인해야 합니다. 권한 거부와 요청 출처 검사를 검증하고, 증거와 롤백 경로를 확보한 뒤 승인합니다.
엣지 배포에서 Origin과 Host 검사는 어떻게 확인하나요?
요청이 브라우저에서 프록시와 Workers를 거쳐 앱에 도착할 때 각 헤더의 값을 관찰합니다. 정상 출처뿐 아니라 허용되지 않는 출처, 누락된 값, 예상과 다른 전달 헤더가 거부되는지 시험하고, 설정한 허용 출처가 필요한 도메인으로 제한되어 있는지 기록합니다.
Server Actions의 인증과 권한은 어떻게 시험하나요?
동작별로 로그인, 자원 소유권, 역할, 테넌트 범위를 구분해 확인합니다. 미인증 사용자와 낮은 권한 사용자, 다른 테넌트 사용자의 요청이 거부되는지 시험하고, 그 과정에서 실제 변경이 일어나지 않았다는 결과를 남깁니다.
기존 앱 이전에서 먼저 살펴볼 부분은 무엇인가요?
현재 빌드 방식과 앱 기능을 목록으로 만든 뒤 선택한 Workers 경로의 공식 지원 안내와 대조합니다. 특히 Node.js API 의존성, 폼, 업로드, 요청 크기와 런타임 동작은 앱별로 확인해야 합니다. 로컬 빌드 성공만으로 운영 환경의 호환성을 판단하지 않습니다.
폼과 업로드의 런타임 제약 검증
폼 제출, 파일 업로드, 큰 요청 본문, Node.js API를 쓰는 동작은 실제 사용 흐름으로 확인합니다. Workers에는 플랫폼 제한이 있으며, 현재 제한 문서의 수치와 조건은 배포 전에 다시 읽어야 합니다. 본문 크기나 실행 제약을 한 경로의 값으로 모든 Workers 배포에 일반화하지 않습니다.
| 기능 또는 의존성 | 확인할 경계 | 검수 방법 |
|---|---|---|
| 폼 제출 | 액션 호출, 검증 오류, 응답 흐름 | 목표 어댑터로 제출하고 정상·거부 결과를 확인합니다. |
| 파일 및 큰 요청 본문 | 요청 전달과 플랫폼 제한 | 사용하는 파일 유형과 실제 요청 흐름으로 제한 동작을 시험합니다. |
| Node.js API | 선택 런타임의 호환성 | Node.js 호환성 안내에서 지원 범위를 확인한 뒤 의존 기능을 실행합니다. |
업그레이드와 어댑터 변경 뒤 회귀 시험
프레임워크 버전, 어댑터 또는 프록시 설정을 바꾸면 이전 승인 결과를 그대로 적용하지 않습니다. 운영과 같은 도메인 및 헤더 전달 규칙을 가진 통제된 시험 환경에서 동작을 다시 확인합니다. Cloudflare의 지원 안내와 Workers 런타임 제약은 바뀔 수 있으므로, 검수 시점의 공식 문서를 기준으로 기록합니다.
- [ ] 같은 출처의 요청이 필요한 동작을 정상 수행합니다.
- [ ] 다른 출처, 출처 누락, 비정상 헤더의 요청이 기대한 방식으로 거부됩니다.
- [ ] 권한이 없는 사용자의 민감 동작이 차단되고 부수 효과가 없습니다.
- [ ] 빌드 버전, 배포 설정, 앱 로그와 엣지 측 관측 결과를 함께 보관합니다.
- [ ] 배포 실패나 보안 검사 이상이 생겼을 때 이전 승인 버전으로 되돌리는 절차를 실행해 봅니다.
CSRF 방어를 보완한다며 임의의 HMAC 서명이나 토큰 미들웨어를 추가하는 것도 자동으로 안전한 대안이 되지는 않습니다. 키 관리, 토큰 발급과 검증, 프록시 경계까지 포함해 목표 환경에서 시험하지 않았다면 그 구현을 승인 근거로 삼지 않습니다. 기준을 정할 때는 OWASP의 CSRF 방어 안내도 함께 확인합니다.
출시 승인과 보류 조건 기록
최종 승인은 지원 문구가 아니라 검증 가능한 증거를 기준으로 내립니다. 적응 경로와 앱 기능, 요청 신뢰 경계, 민감 동작의 권한, 런타임 요구 사항, 롤백 절차가 모두 프로젝트 기준을 충족해야 합니다. 확인하지 못한 동작이나 재현할 수 없는 헤더 문제는 추측으로 결론 내리지 말고, 담당자와 재시험 조건을 지정해 보류 항목으로 남깁니다.
현재의 일반 개발 환경으로 충분한 팀은 그 환경을 유지하면 됩니다. 다만 Apple 플랫폼 브라우저 시험이 필요하다면 일반 실행 환경에는 해당 플랫폼과 실제 브라우저 조합을 재현하기 어렵고, 개발자별 로컬 환경도 설정이 달라질 수 있습니다. 그런 요구가 있을 때만 클라우드 맥을 별도 검증 환경으로 검토하는 편이 적절합니다. KuzCloud의 도움말에서 필요한 시험 방식이 맞는지 먼저 확인하고, 이용을 검토한다면 한국 요금 안내를 살펴보면 됩니다. Apple 플랫폼 시험이 필요하지 않다면 맥 대여는 이 배포 검수의 필수 조건이 아닙니다.
배포 검수에 필요한 원격 맥 환경도 준비하세요
KuzCloud의 전용 맥 미니 엠포로 가상화 계층 없이 빌드와 회귀 시험을 진행할 수 있습니다.
원격 데스크톱이나 터미널로 접속해 팀의 개발과 검수 흐름에 맞게 활용하세요.