Azure App Service 배포 (Node.js)

이 스킬은 Node.js 애플리케이션을 Azure App Service(Linux)에 완벽하게 배포하고 Managed Identity를 통해 Azure AI Foundry 에이전트에 안전하게 연결하는 모범 사례를 설명합니다.

1. 클라우드 인프라 설정

App Service 플랜: 프로덕션에는 항상 전용 계층(예: Basic B1)을 선택하십시오. 무료(F1) 계층은 CPU 할당량이 하루 60분으로 제한되어 애플리케이션이 강제 종료될 수 있습니다(403 Stopped 오류 발생).

코드: Node.js 백엔드에서 @azure/identity의 DefaultAzureCredential을 사용합니다.
ID 활성화: Azure App Service 포털에서 설정 > ID로 이동하여 시스템 할당을 활성화합니다.
IAM 권한: 대상 Azure AI 프로젝트에서 액세스 제어(IAM) 로 이동하여 App Service의 Managed Identity에 Azure AI Developer 역할을 할당합니다. (참고: Cognitive Services OpenAI User는 Azure Foundry Orchestration Agents에 충분하지 않습니다.)

GitHub Actions를 통해 풀스택 앱(React/Vite + Node.js)을 배포할 때 환경 변수는 논리적으로 분할되어야 합니다.

VITE_ 접두사가 붙은 변수(예: Supabase 키)는 빌드 타임에 정적 HTML/JS에 포함됩니다.
설정 위치: GitHub Secrets에 저장하고 .github/workflows 파일의 npm run build 단계 env: 블록에서 명시적으로 매핑해야 합니다.
위험: Azure에만 있고 GitHub Actions에 없으면 Vite는 빈 변수로 프론트엔드를 빌드합니다.

실행 중인 server.js 파일은 런타임에 클라우드 컨테이너에서 환경 변수를 읽습니다.
설정 위치: Azure Portal의 설정 > 환경 변수에서 변수(예: Azure AI 엔드포인트, 백엔드 Supabase 키)를 직접 구성합니다.
위험: Azure App Service 백엔드는 GitHub Actions 시크릿을 상속하지 않습니다. Azure Portal에서 수동으로 설정해야 합니다.
중요: 변수는 Node.js 프로세스가 시작될 때 정확히 한 번 메모리에 로드됩니다. 변수를 추가하거나 변경한 경우 App Service 개요 페이지에서 다시 시작을 명시적으로 클릭해야 합니다.
Azure Load Balancer를 신뢰하려면(express-rate-limit에 필요) Express 앱에 app.set('trust proxy', 1);이 설정되어 있는지 확인합니다.

가장 안전한 배포 전략은 빌드 엔진(GitHub vs. Azure Oryx) 간의 충돌을 피하는 것입니다. GitHub에서 100% 빌드 및 패키징을 수행합니다.

GitHub가 npm install 및 프론트엔드 빌드(npm run build)를 실행합니다.
GitHub가 컴파일된 출력(dist), 백엔드 파일(server.js), 그리고 중요하게 node_modules 폴더를 포함하는 아티팩트를 업로드합니다.
- 이유: node_modules를 생략하면 Azure의 Oryx 엔진이 npm run build를 실행하여 앱을 직접 빌드하려고 시도하며, 원시 소스 파일(index.html)이 업로드되지 않았기 때문에 충돌이 발생합니다.
GitHub Secret에 저장된 게시 프로필과 함께 azure/webapps-deploy@v3를 사용합니다.