Azure App Service에서 ZIP 패키지의 앱 직접 실행하기

2025-04-30

참고

패키지에서 실행은 Python 앱에서 지원되지 않습니다. Python 코드의 ZIP 파일을 배포할 때 Azure의 빌드 자동화를 사용하도록 플래그를 설정해야 합니다. 빌드 자동화는 앱에 대한 Python 가상 환경을 만들고 필요한 요구 사항 및 패키지를 설치합니다. 자세한 내용은 빌드 자동화 를 참조하세요.

Azure App Service에서 배포 ZIP 패키지 파일에서 직접 앱을 실행할 수 있습니다. 이 문서에서는 앱에서 해당 기능을 사용하도록 설정하는 방법을 설명합니다.

App Service의 다른 모든 배포 방법에는 공통적인 점이 있습니다. 압축 해제 파일은 앱의 D:\home\site\wwwroot 에 배포됩니다(또는 Linux 앱의 경우 /home/site/wwwroot ). 런타임에 앱에서 동일한 디렉터리를 사용하므로 파일 잠금 충돌로 인해 배포가 실패할 수 있으며 일부 파일이 아직 업데이트되지 않았기 때문에 앱이 예상과 다르게 동작할 수 있습니다. 이 설정을 사용하려면 변수에 값을 WEBSITE_RUN_FROM_PACKAGE 할당할 필요가 없거나 완전히 제거할 수 있습니다.

반면 ZIP 패키지에서 직접 실행하는 경우 패키지의 파일은 wwwroot 디렉터리에 복사되지 않습니다. 대신 ZIP 패키지 자체는 읽기 전용 wwwroot 디렉터리로 직접 탑재됩니다. 이 설정을 활성화하려면 WEBSITE_RUN_FROM_PACKAGE=1로 설정하거나 ZIP 파일의 URL을 제공하세요. 다음은 패키지에서 직접 실행할 경우 누릴 수 있는 여러 이점입니다.

배포와 런타임 간의 파일 잠금 충돌을 제거합니다.
언제든지 완전히 배포된 앱만 실행되도록 보장합니다.
(다시 시작으로) 프로덕션 앱에 배포될 수 있습니다.
Azure Resource Manager 배포의 성능을 향상시킵니다.
특히 대규모 npm 패키지 트리가 있는 JavaScript 함수의 경우 콜드 부팅 시간을 줄일 수 있습니다.

참고

현재는 ZIP 패키지 파일만 지원됩니다.

프로젝트 ZIP 패키지 만들기

중요

배포용 ZIP 패키지를 만들 때 루트 디렉터리를 포함하지 마세요. 루트 디렉터리에 파일 및 디렉터리만 포함합니다. GitHub 리포지토리를 ZIP 파일로 다운로드하는 경우 App Service에 해당 파일을 있는 그대로 배포할 수 없습니다. GitHub는 App Service에서 작동하지 않는 최상위 수준에 중첩된 디렉터리를 추가합니다.

로컬 터미널 창에서 앱 프로젝트의 루트 디렉터리로 이동합니다.

이 디렉터리에는 웹앱에 대한 항목 파일(예: index.html, index.php및 app.js)이 포함되어야 합니다. 패키지 관리 파일(예: project.json, composer.json, package.jsonbower.json및 requirements.txt)도 포함할 수 있습니다.

App Service에서 배포 자동화를 실행하지 않으려면 모든 빌드 작업을 실행합니다. 예: npm, , bowergulp, composer및 pip. 앱을 실행하는 데 필요한 모든 파일이 있는지 확인합니다. 패키지를 직접 실행하려면 이 단계가 필요합니다.

프로젝트의 모든 것에 대한 ZIP 아카이브를 만듭니다. dotnet 프로젝트의 경우 출력 디렉터리 자체를 제외한 dotnet publish 명령의 출력 디렉터리에 모든 항목을 추가합니다. 예를 들어 터미널에서 다음 명령을 입력하여 현재 디렉터리의 내용을 포함하는 ZIP 패키지를 만듭니다.

# Bash
zip -r <file-name>.zip .

# PowerShell
Compress-Archive -Path * -DestinationPath <file-name>.zip

ZIP 패키지에서 실행 가능하게 설정

WEBSITE_RUN_FROM_PACKAGE 앱 설정을 사용하면 ZIP 패키지에서 실행할 수 있습니다. 이를 설정하려면 Azure CLI를 사용하여 다음 명령을 실행합니다.

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings WEBSITE_RUN_FROM_PACKAGE="1"

WEBSITE_RUN_FROM_PACKAGE="1"를 사용하면 앱에 로컬로 있는 ZIP 패키지에서 앱을 실행할 수 있습니다. 원격 패키지에서 실행할 수도 있습니다.

ZIP 패키지 실행

App Service에서 ZIP 패키지를 실행하는 가장 쉬운 방법은 Azure CLI az webapp deployment source config-zip 명령을 사용하는 것입니다. 예를 들면 다음과 같습니다.

az webapp deploy --resource-group <group-name> --name <app-name> --src-path <filename>.zip

앱 설정이 WEBSITE_RUN_FROM_PACKAGE 설정되므로 이 명령은 ZIP 패키지 콘텐츠를 앱의 D:\home\site\wwwroot 디렉터리로 추출하지 않습니다. 대신 D :\home\data\SitePackages에 as-is ZIP 파일을 업로드하고 런타임에 로드할 ZIP 패키지의 이름을 포함하는 packagename.txt 동일한 디렉터리에 만듭니다. 다른 방식으로(예: FTP) ZIP 패키지를 업로드하는 경우 D:\home\data\SitePackages 디렉터리와 packagename.txt 파일을 수동으로 만들어야 합니다.

또한 해당 명령은 앱을 다시 시작합니다. 설정되었으므로 WEBSITE_RUN_FROM_PACKAGE App Service는 업로드된 패키지를 읽기 전용 wwwroot 디렉터리로 탑재하고 탑재된 디렉터리에서 직접 앱을 실행합니다.

외부 URL에서 실행

Azure Blob Storage와 같은 외부 URL에서 ZIP 패키지를 실행할 수도 있습니다. Azure Storage Explorer를 사용하여 Blob Storage 계정에 ZIP 패키지 파일을 업로드할 수 있습니다. SAS(공유 액세스 서명)가 있는 프라이빗 스토리지 컨테이너를 사용하거나 관리 ID를 사용하여 App Service 런타임이 ZIP 패키지에 안전하게 액세스할 수 있도록 해야 합니다.

참고

현재 로컬 ZIP 패키지를 실행하는 기존 App Service 리소스는 원격 ZIP 패키지에서 실행되도록 마이그레이션할 수 없습니다. 외부 URL에서 실행되도록 구성된 새 App Service 리소스를 만들어야 합니다.

Blob 스토리지에 파일을 업로드하고 파일에 대한 SAS URL이 있는 경우 WEBSITE_RUN_FROM_PACKAGE 앱 설정을 URL로 설정합니다. URL이 .로 .zip끝나는지 확인합니다. 다음 예에서는 Azure CLI를 사용하여 해당 작업을 수행합니다.

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_RUN_FROM_PACKAGE="https://myblobstorage.blob.core.windows.net/content/SampleCoreMVCApp.zip?st=2018-02-13T09%3A48%3A00Z&se=2044-06-14T09%3A48%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=bNrVrEFzRHQB17GFJ7boEanetyJ9DGwBSV8OM3Mdh%2FM%3D"

Blob 스토리지에 동일한 이름의 업데이트된 패키지를 게시하는 경우 업데이트된 패키지가 App Service에 로드되도록 앱을 다시 시작해야 합니다.

관리 ID를 사용하여 Azure Blob Storage의 패키지에 액세스

Microsoft Entra ID를 사용하여 요청에 권한을 부여하도록 Azure Blob Storage를 구성할 수 있습니다. 이 구성은 만료가 있는 SAS 키를 생성하는 대신 애플리케이션의 관리 ID를 사용할 수 있음을 의미합니다. 기본적으로 앱의 시스템 할당 ID가 사용됩니다. 사용자 할당 ID를 지정하려는 경우 WEBSITE_RUN_FROM_PACKAGE_BLOB_MI_RESOURCE_ID 앱 설정을 해당 ID의 리소스 ID로 설정할 수 있습니다. 설정은 SystemAssigned를 값으로 허용할 수도 있으며 이는 설정을 생략하는 것과 동등합니다.

ID를 사용하여 패키지를 가져올 수 있도록 설정하려면 다음을 수행합니다.

Blob이 프라이빗 액세스를 위해 구성되었는지 확인합니다.
ID에 패키지 Blob에 대한 범위가 있는 Storage Blob 데이터 읽기 권한자 역할을 부여합니다. Blob 데이터에 액세스하기 위한 Azure 역할 할당 만들기에 대한 자세한 내용은 참조하세요.
WEBSITE_RUN_FROM_PACKAGE 애플리케이션 설정을 패키지의 Blob URL로 설정합니다. 이 URL은 일반적으로 https://{storage-account-name}.blob.core.windows.net/{container-name}/{path-to-package} 또는 이와 유사한 형식입니다.
사용자 할당 ID를 지정하려는 경우 WEBSITE_RUN_FROM_PACKAGE_BLOB_MI_RESOURCE_ID 앱 설정을 해당 ID의 리소스 ID로 설정할 수 있습니다. 이 설정은 "SystemAssigned"를 값으로 수락할 수 있지만 이는 설정을 완전히 생략하는 것과 동일합니다. 리소스 ID는 Azure의 리소스에 대한 표준 표현입니다. 사용자가 할당한 관리 ID의 경우 /subscriptions/subid/resourcegroups/rg-name/providers/Microsoft.ManagedIdentity/userAssignedIdentities/identity-name이(가) 됩니다. 사용자 할당 관리 ID의 리소스 ID는 사용자가 할당한 관리 ID의 > -> -ID에서 가져올 수 있습니다.

패키지에서 실행할 때 WebJob 파일 배포

패키지에서 앱을 실행하도록 설정할 때 WebJob 파일을 배포하는 방법에는 두 가지가 있습니다.

앱과 동일한 ZIP 패키지로 배포합니다. <project-root>\app_data\jobs\...에 일반적으로 포함하듯이 포함하며, 이는 \site\wwwroot\app_data\jobs\...에서 지정한 배포 경로 에 매핑됩니다.
앱의 ZIP 패키지와 별도로 배포: 이제 일반 배포 경로 \site\wwwroot\app_data\jobs\...가 읽기 전용이므로 여기에 WebJob 파일을 배포할 수 없습니다. 대신 읽기 전용이 아닌 \site\jobs\...에 WebJob 파일을 배포합니다. \site\wwwroot\app_data\jobs\... 및 \site\jobs\...에 배포된 WebJob이 모두 실행됩니다.

참고

\site\wwwroot 읽기 전용이 되면 disable.job 만들기와 같은 작업이 실패합니다.

문제 해결

앱을 패키지에서 직접 실행하면 wwwroot가 읽기 전용으로 설정됩니다. 앱에서 해당 디렉터리에 파일을 쓰려고 하면 오류가 발생합니다.
TAR 및 GZIP 형식은 지원되지 않습니다.
ZIP 파일은 최대 1GB까지 지원됩니다.
이 기능은 로컬 캐시와 호환되지 않습니다.
콜드 부팅 성능을 개선하려면 로컬 Zip 옵션(WEBSITE_RUN_FROM_PACKAGE=1)을 사용합니다.