Azure App Service용 Node.js 앱 구성

아티클
10/17/2024

Node.js 앱을 모든 필수 NPM 종속성과 함께 배포해야 합니다. App Service 배포 엔진은 Git 리포지토리를 배포하거나 빌드 자동화를 사용하도록 설정된 Zip 패키지를 배포할 때 자동으로 npm install --production을(를) 실행합니다. 그러나 FTP/S를 사용하여 파일을 배포하는 경우 필요한 패키지를 수동으로 업로드해야 합니다.

또한 App Service에 배포하는 Node.js 개발자를 위한 주요 개념과 지침을 제공합니다. Azure App Service를 처음 사용하는 경우 먼저 Node.js 빠른 시작 및 MongoDB를 사용하는 Node.js 자습서를 따라하세요.

Node.js 버전 표시

현재 Node.js 버전을 표시하려면 Cloud Shell에서 다음 명령을 실행합니다.

az webapp config appsettings list --name <app-name> --resource-group <resource-group-name> --query "[?name=='WEBSITE_NODE_DEFAULT_VERSION'].value"

지원되는 모든 Node.js 버전을 표시하려면 https://<sitename>.scm.azurewebsites.net/api/diagnostics/runtime로 이동하거나 Cloud Shell에서 다음 명령을 실행합니다.

az webapp list-runtimes --os windows | grep NODE

현재 Node.js 버전을 표시하려면 Cloud Shell에서 다음 명령을 실행합니다.

az webapp config show --resource-group <resource-group-name> --name <app-name> --query linuxFxVersion

지원되는 Node.js 버전을 모두 표시하려면 Cloud Shell에서 다음 명령을 실행합니다.

az webapp list-runtimes --os linux | grep NODE

Node.js 버전 설정

앱을 지원되는 Node.js 버전으로 설정하려면 Cloud Shell에서 다음 명령을 실행하여 WEBSITE_NODE_DEFAULT_VERSION을 지원되는 버전으로 설정합니다.

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_NODE_DEFAULT_VERSION="~16"

참고 항목

이 예제에서는 권장되는 "타일드 구문"을 사용하여 App Service에서 사용 가능한 최신 버전의 Node.js 16 런타임을 대상으로 지정합니다.

런타임은 플랫폼에서 정기적으로 패치 및 업데이트되므로 잠재적인 보안 위험으로 인해 사용 가능하도록 보장되지 않으므로 특정 부 버전/패치를 대상으로 지정하지 않는 것이 좋습니다.

참고 항목

프로젝트의 package.json에서 Node.js 버전을 설정해야 합니다. 배포 엔진은 지원되는 모든 Node.js 버전을 포함하는 별도의 프로세스에서 실행됩니다.

앱을 지원되는 Node.js 버전으로 설정하려면 Cloud Shell에서 다음 명령을 실행합니다.

az webapp config set --resource-group <resource-group-name> --name <app-name> --linux-fx-version "NODE|14-lts"

이 설정은 런타임에 또한 Kudu에서 자동화된 패키지 복원 시에 사용할 Node.js 버전을 지정합니다.

참고 항목

프로젝트의 package.json에서 Node.js 버전을 설정해야 합니다. 배포 엔진은 지원되는 모든 Node.js 버전을 포함하는 별도의 컨테이너에서 실행됩니다.

포트 번호 가져오기

들어오는 요청을 수신하려면 Node.js 앱이 올바른 포트를 수신 대기해야 합니다.

Windows의 App Service에서 Node.js 앱은 IISNode를 사용하여 호스트되고 Node.js 앱은 process.env.PORT 변수에 지정된 포트를 수신 대기해야 합니다. 다음 예제에서는 간단한 Express 앱에서 이 작업을 수행하는 방법을 보여 줍니다.

App Service는 Node.js 컨테이너에 환경 변수 PORT를 설정하고 해당 포트 번호에서 들어오는 요청을 컨테이너에 전달합니다. 요청을 받으려면 앱이 process.env.PORT를 사용하여 해당 포트를 수신 대기해야 합니다. 다음 예제에서는 간단한 Express 앱에서 이 작업을 수행하는 방법을 보여 줍니다.

const express = require('express')
const app = express()
const port = process.env.PORT || 3000

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`)
})

빌드 자동화 사용자 지정

Git을 사용하거나 빌드 자동화가 활성화된 zip 패키지를 사용하여 앱을 배포하는 경우 App Service는 다음 시퀀스를 통해 자동화 단계를 빌드합니다.

PRE_BUILD_SCRIPT_PATH(으)로 지정된 경우 사용자 지정 스크립트를 실행합니다.
npm preinstall 및 postinstall 스크립트를 포함하여 npm install을 플래그 없이 실행하고 devDependencies도 설치합니다.
빌드 스크립트가 package.json에 지정된 경우 npm run build를 실행합니다.
build:azure 스트립트가 package.json에 지정된 경우 npm run build:azure를 실행합니다.
POST_BUILD_SCRIPT_PATH에 지정된 경우 사용자 지정 스크립트를 실행합니다.

참고 항목

npm docs에 설명된 것처럼 prebuild 및 postbuild라는 스크립트가 지정된 경우 각각 build 전후에 실행됩니다. preinstall 및 postinstall은 각각 install 전후에 실행됩니다.

PRE_BUILD_COMMAND 및 POST_BUILD_COMMAND는 기본적으로 비어 있는 환경 변수입니다. 빌드 전 명령을 실행하려면 PRE_BUILD_COMMAND를 정의합니다. 빌드 후 명령을 실행하려면 POST_BUILD_COMMAND를 정의합니다.

다음 예제에서는 두 변수를 사용하여 쉼표로 구분된 일련의 명령을 지정합니다.

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PRE_BUILD_COMMAND="echo foo, scripts/prebuild.sh"
az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings POST_BUILD_COMMAND="echo foo, scripts/postbuild.sh"

빌드 자동화를 사용자 지정하는 추가 환경 변수에 대한 자세한 내용은 Oryx 구성을 참조하세요.

App Service를 실행하고 Linux에서 Node.js 앱을 빌드하는 방법에 대한 자세한 내용은 Oryx 설명서: Node.js 앱을 인식하고 구축하는 방법을 참조하세요.

Node.js 서버 구성

Node.js 컨테이너는 프로덕션 프로세스 관리자인 PM2와 함께 제공됩니다. npm start 또는 사용자 지정 명령을 사용하여 PM2로 시작하도록 앱을 구성할 수 있습니다.

도구	목적
PM2를 사용하여 실행	권장 - 프로덕션 또는 스테이징 사용. PM2는 전체 서비스 앱 관리 플랫폼을 제공합니다.
npm start로 실행	개발 용도로만 사용합니다.
사용자 지정 명령으로 실행	개발 또는 스테이징 중 하나.

PM2를 사용하여 실행

이 컨테이너는 일반적인 Node.js 파일 중 하나가 프로젝트에 있는 경우 PM2를 사용하여 앱을 자동으로 시작합니다.

bin/www
server.js
app.js
index.js
hostingstart.js
다음 PM2 파일 중 하나: process.json 또는 ecosystem.config.js

다음 확장명을 사용하여 사용자 지정 시작 파일을 구성할 수도 있습니다.

.js 파일
.json, .config.js, .yaml, 또는 .yml 확장명의 PM2 파일

참고 항목

노드 14 LTS부터 컨테이너는 PM2로 앱을 자동으로 시작하지 않습니다. PM2로 앱을 시작하려면 시작 명령을 pm2 start <.js-file-or-PM2-file> --no-daemon(으)로 설정합니다. 컨테이너가 제대로 작동하려면 PM2가 전경에서 실행되어야 하므로 --no-daemon 인수를 사용해야 합니다.

사용자 지정 시작 파일을 추가하려면 Cloud Shell에서 다음 명령을 실행합니다.

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename-with-extension>"

사용자 지정 명령을 사용하여 실행

App Service는 사용자 지정 명령(예: run.sh와 같은 실행 파일)을 사용하여 앱을 시작할 수 있습니다. 예를 들어 npm run start:prod를 실행하려면 Cloud Shell에서 다음 명령을 실행합니다.

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "npm run start:prod"

npm start로 실행

npm start를 사용하여 앱을 시작하려면 start 스크립트가 package.json 파일에 있어야 합니다. 예시:

{
  ...
  "scripts": {
    "start": "gulp",
    ...
  },
  ...
}

프로젝트에서 사용자 지정 package.json을 사용하려면 Cloud Shell에서 다음 명령을 실행합니다.

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename>.json"

원격 디버깅

PM2를 사용하여 실행하도록 구성하는 경우 .config.js,.yml, 또는 .yaml을 사용하여 실행하는 경우를 제외하고 Visual Studio Code에서 원격으로 Node.js 앱을 디버그할 수 있습니다.

대부분의 경우 앱에 대한 추가 구성이 필요하지 않습니다. 앱이 process.json 파일(기본 또는 사용자 지정)을 사용하여 실행되는 경우 JSON 루트에 script 속성이 있어야 합니다. 예시:

{
  "name"        : "worker",
  "script"      : "./index.js",
  ...
}

Visual Studio Code에서 원격 디버깅을 설정하려면 App Service 확장을 설치합니다. 확장 페이지의 지침에 따라 Visual Studio Code에서 Azure에 로그인합니다.

Azure 탐색기에서 디버그할 앱을 찾아 마우스 오른쪽 단추로 클릭하고 원격 디버깅 시작을 선택합니다. 예를 선택하여 앱에 대한 원격 디버깅을 사용하도록 설정합니다. App Service가 터널 프록시를 시작하고 디버거를 연결합니다. 그런 다음 앱에 대한 요청을 수행하면 디버거가 중단점에서 일시 중지되는 것을 볼 수 있습니다.

디버깅이 완료되면 연결 끊기를 선택하여 디버거를 중지합니다. 메시지가 표시되면 예를 선택하여 원격 디버깅을 사용하지 않도록 설정해야 합니다. 나중에 사용하지 않도록 설정하려면 Azure 탐색기에서 앱을 다시 마우스 오른쪽 단추로 클릭하고 원격 디버깅 사용 안 함을 선택합니다.

환경 변수에 액세스

App Service에서, 앱 코드 외부에서 앱 설정을 지정할 수 있습니다. 그런 다음 표준 Node.js 패턴을 사용하여 액세스할 수 있습니다. 예를 들어 앱 설정 NODE_ENV에 액세스하려면 다음 코드를 사용합니다.

process.env.NODE_ENV

Grunt/Bower/Gulp 실행

기본적으로 App Service 빌드 자동화는 Node.js 앱이 Git을 통해 또는 빌드 자동화가 활성화된 Zip 배포를 통해 배포되었음을 인식할 때 npm install --production을 실행합니다. 앱이 Grunt, Bower 또는 Gulp와 같은 인기 있는 자동화 도구를 필요로 하는 경우 이를 실행하려면 사용자 지정 배포 스크립트를 제공하여 실행해야 합니다.

리포지토리에서 이러한 도구를 실행할 수 있도록 하려면 package.json.의 종속성에 추가해야 합니다. 예를 들어:

"dependencies": {
  "bower": "^1.7.9",
  "grunt": "^1.0.1",
  "gulp": "^3.9.1",
  ...
}

로컬 터미널 창에서 디렉터리를 리포지토리 루트로 변경하고 다음 명령을 실행합니다.

npm install kuduscript -g
kuduscript --node --scriptType bash --suppressPrompt

이제 리포지토리 루트에 .deployment 및 deploy.sh라는 두 개의 추가 파일이 있습니다.

deploy.sh를 열고 다음과 같은 Deployment 섹션을 찾습니다.

##################################################################################################################################
# Deployment
# ----------

이 섹션은 npm install --production 실행으로 끝납니다. 필요한 도구를 실행하는 데 필요한 코드 섹션을 Deployment 섹션의 '끝'에 추가합니다.

Bower
Gulp
Grunt

배포 스크립트가 사용자 지정 npm install 명령도 실행하는 MEAN.js 샘플의 예제를 참조하세요.

Bower

이 코드 조각은 bower install를 실행합니다.

if [ -e "$DEPLOYMENT_TARGET/bower.json" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/bower install
  exitWithMessageOnError "bower failed"
  cd - > /dev/null
fi

Gulp

이 코드 조각은 gulp imagemin를 실행합니다.

if [ -e "$DEPLOYMENT_TARGET/gulpfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/gulp imagemin
  exitWithMessageOnError "gulp failed"
  cd - > /dev/null
fi

Grunt

이 코드 조각은 grunt를 실행합니다.

if [ -e "$DEPLOYMENT_TARGET/Gruntfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/grunt
  exitWithMessageOnError "Grunt failed"
  cd - > /dev/null
fi

HTTPS 세션 검색

App Service에서는 네트워크 부하 분산기에서 TLS/SSL 종료가 발생하므로 모든 HTTPS 요청은 암호화되지 않은 HTTP 요청으로 앱에 도달합니다. 앱 논리에서 사용자 요청의 암호화를 확인해야 하는 경우 X-Forwarded-Proto 헤더를 검사합니다.

인기 있는 웹 프레임워크를 사용하여 표준 앱 패턴의 X-Forwarded-* 정보에 액세스할 수 있습니다. Express에서는 신뢰 프록시를 사용할 수 있습니다. 예시:

app.set('trust proxy', 1)
...
if (req.secure) {
  // Do something when HTTPS is used
}

진단 로그 액세스

App Service의 애플리케이션 코드 내부에서 생성된 콘솔 로그에 액세스하려면 Cloud Shell에서 다음 명령을 실행하여 진단 로깅을 켭니다.

az webapp log config --resource-group <resource-group-name> --name <app-name> --docker-container-logging filesystem --level Verbose

--level에 대한 가능한 값은 Error, Warning, Info 및 Verbose입니다. 각 후속 수준에는 이전 수준이 포함됩니다. 예를 들어 Error에는 오류 메시지만 포함하고 Verbose에는 모든 메시지를 포함합니다.

진단 로깅이 설정되면 다음 명령을 실행하여 로그 스트림을 확인합니다.

az webapp log tail --resource-group <resource-group-name> --name <app-name>

콘솔 로그가 즉시 표시되지 않으면 30초 후에 다시 확인합니다.

참고 항목

https://<app-name>.scm.azurewebsites.net/api/logs/docker의 브라우저에서 로그 파일을 검사할 수도 있습니다.

언제든지 로그 스트리밍을 중지하려면 Ctrl+C를 입력합니다.

컨테이너 내부에서 생성된 콘솔 로그에 액세스할 수 있습니다.

먼저 다음 명령을 실행하여 컨테이너 로깅을 설정합니다.

az webapp log config --name <app-name> --resource-group <resource-group-name> --docker-container-logging filesystem

<app-name> 및 <resource-group-name>을 웹앱에 적합한 이름으로 바꿉니다.

컨테이너 로깅이 설정되면 다음 명령을 실행하여 로그 스트림을 확인합니다.

az webapp log tail --name <app-name> --resource-group <resource-group-name>

콘솔 로그가 즉시 표시되지 않으면 30초 후에 다시 확인합니다.

언제든지 로그 스트리밍을 중지하려면 Ctrl+C를 입력합니다.

https://<app-name>.scm.azurewebsites.net/api/logs/docker의 브라우저에서 로그 파일을 검사할 수도 있습니다.

URL 다시 쓰기

Linux용 Azure App Service에 Node.js 앱을 배포할 때 애플리케이션 내에서 직접 URL 다시 쓰기를 처리해야 할 수 있습니다. 이 기능은 웹 서버 구성에 의존하지 않고 특정 URL 패턴이 올바른 엔드포인트로 리디렉션되도록 하는 데 특히 유용합니다. Node.js에서 URL 다시 쓰기를 수행하는 방법에는 여러 가지가 있습니다. 한 가지 예는 express-urlrewrite 패키지를 사용하는 것입니다.

Application Insights로 모니터링

Application Insights를 사용하면 코드를 변경하지 않고도 애플리케이션의 성능, 예외 및 사용 현황을 모니터링할 수 있습니다. Application Insights 에이전트를 연결하려면 포털에서 웹앱으로 이동하고 설정 아래에서 Application Insights를 선택한 다음 Application Insights 켜기를 선택합니다. 다음으로, 기존 Application Insights 리소스를 선택하거나 새 리소스를 만듭니다. 마지막으로 아래쪽에서 적용을 선택합니다. PowerShell을 사용하여 웹앱을 계측하려면 이 지침을 참조하세요.

이 에이전트는 서버 쪽 Node.js 애플리케이션을 모니터링합니다. 클라이언트 쪽 JavaScript를 모니터링하려면 JavaScript SDK를 프로젝트에 추가합니다.

자세한 내용은 Application Insights 확장 릴리스 정보를 참조하세요.

문제 해결

작동하는 Node.js 앱이 App Servce에서 다르게 동작하거나 오류가 발생할 경우 다음의 방법을 시도해보세요.

로그 스트림에 액세스합니다.
프로덕션 모드에서 로컬 상태로 앱을 테스트합니다. App Service가 프로덕션 모드에서 Node.js 앱을 실행하므로 프로젝트가 프로덕션 모드에서 로컬 상태로 예상과 같이 작동하는지 확인해야 합니다. 예:
- package.json에 따라, 프로덕션 모드에서 다른 패키지가 설치될 수 있습니다(dependencies vs. devDependencies).
- 특정 웹 프레임워크는 프로덕션 모드에서 다른 고정 파일을 배포할 수 있습니다.
- 특정 웹 프레임워크는 프로덕션 모드에서 실행될 때 사용자 지정 시작 스크립트를 사용합니다.
App Service에서 앱을 개발 모드로 실행합니다. 예를 들어 MEAN.js에서는 NODE_ENV 앱 설정을 설정하여 런타임 시 앱을 개발 모드로 설정할 수 있습니다.

이 디렉터리 또는 페이지를 볼 수 있는 권한이 없습니다

App Service의 원시 Windows 앱에 Node.js 코드를 배포한 후 앱의 URL로 이동할 때 브라우저에 메시지 You do not have permission to view this directory or page이(가) 표시될 수 있습니다. web.config 파일이 없기 때문일 수 있습니다. (템플릿 및 예제를 참조하세요.)

Git을 사용하거나 빌드 자동화를 사용하도록 설정된 ZIP 배포를 사용하여 파일을 배포하는 경우 다음 조건 중 하나가 충족되는 경우 배포 엔진은 앱의 웹 루트(%HOME%\site\wwwroot)에 자동으로 web.config를 생성합니다.

프로젝트 루트에는 JavaScript 파일의 경로가 포함된 start 스크립트를 정의하는 package.json이 있습니다.
프로젝트 루트에 server.js 또는 app.js있습니다.

생성된 web.config는 검색된 시작 스크립트에 맞게 조정됩니다. 다른 배포 방법의 경우 이 web.config를 수동으로 추가합니다. 파일의 형식이 올바르게 지정되었는지 확인합니다.

예를 들어 Visual Studio Code를 통해 ZIP 배포를 사용하는 경우 빌드 자동화를 사용하도록 설정해야 합니다. 기본적으로 사용하지 않도록 설정됩니다. az webapp up은(는) 빌드 자동화를 사용하도록 설정된 ZIP 배포를 사용합니다.

로그의 robots933456

컨테이너 로그에 다음 메시지가 표시될 수 있습니다.

2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"

이 메시지는 무시해도 괜찮습니다. /robots933456.txt는 App Service에서 컨테이너가 요청을 처리할 수 있는지 확인하기 위해 사용하는 더미 URL 경로입니다. 404 응답은 단순히 경로가 존재하지 않는다는 것을 나타내지만 컨테이너가 정상 상태이고 요청에 응답할 준비가 되었음을 App Service에 알려줍니다.

다음 단계

자습서: MongoDB를 사용하는 Linux Node.js 앱

Linux의 Azure App Service에 대한 FAQ.

또는 다음 추가 리소스를 참조하세요.

환경 변수 및 앱 설정 참조

다음을 통해 공유

Azure App Service용 Node.js 앱 구성

Node.js 버전 표시

Node.js 버전 설정

포트 번호 가져오기

빌드 자동화 사용자 지정

Node.js 서버 구성

PM2를 사용하여 실행

사용자 지정 명령을 사용하여 실행

npm start로 실행

원격 디버깅

환경 변수에 액세스

Grunt/Bower/Gulp 실행

Bower

Gulp

Grunt

HTTPS 세션 검색

진단 로그 액세스

URL 다시 쓰기

Application Insights로 모니터링

문제 해결

이 디렉터리 또는 페이지를 볼 수 있는 권한이 없습니다

로그의 robots933456

다음 단계

피드백

추가 리소스