Azure App Service için Node.js uygulamasını yapılandırma
Node.js uygulamaların tüm gerekli NPM bağımlılıklarıyla dağıtılması gerekir. App Service dağıtım altyapısı, git deposu veya derleme otomasyonu etkinleştirilmiş bir Zip paketi dağıttığınızda sizin için otomatik olarak çalışırnpm install --production
. Ancak dosyalarınızı FTP/S kullanarak dağıtırsanız gerekli paketleri el ile yüklemeniz gerekir.
Bu kılavuz, App Service dağıtan Node.js geliştiricileri için temel kavramlar ve yönergeler sağlar. Azure App Service hiç kullanmadıysanız önce Node.js hızlı başlangıcı izleyin ve MongoDB ileNode.js öğreticisini izleyin.
Node.js sürümünü göster
Geçerli Node.js sürümünü göstermek için Cloud Shell aşağıdaki komutu çalıştırın:
az webapp config appsettings list --name <app-name> --resource-group <resource-group-name> --query "[?name=='WEBSITE_NODE_DEFAULT_VERSION'].value"
Desteklenen tüm Node.js sürümlerini göstermek için Cloud Shell aşağıdaki komuta gidin https://<sitename>.scm.azurewebsites.net/api/diagnostics/runtime
veya komutunu çalıştırın:
az webapp list-runtimes --os windows | grep NODE
Geçerli Node.js sürümünü göstermek için Cloud Shell aşağıdaki komutu çalıştırın:
az webapp config show --resource-group <resource-group-name> --name <app-name> --query linuxFxVersion
Desteklenen tüm Node.js sürümlerini göstermek için Cloud Shell aşağıdaki komutu çalıştırın:
az webapp list-runtimes --os linux | grep NODE
Node.js sürümünü ayarlama
Uygulamanızı desteklenen bir Node.js sürümüne ayarlamak için Cloud Shell aşağıdaki komutu çalıştırarak desteklenen bir sürüme ayarlayınWEBSITE_NODE_DEFAULT_VERSION
:
az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_NODE_DEFAULT_VERSION="~16"
Not
Bu örnekte, App Service'de Node.js 16 çalışma zamanının en son kullanılabilir sürümünü hedeflemek için önerilen "tilde söz dizimi" kullanılır.
Çalışma zamanı platform tarafından düzenli olarak düzeltme eki uygulandığından ve güncelleştirildiğinden, olası güvenlik risklerine bağlı olarak bunların kullanılabilir olması garanti edilmediğinden belirli bir ikincil sürümü/düzeltme ekini hedeflemeniz önerilmez.
Not
projenizin package.json
sürümünde Node.js sürümünü ayarlamanız gerekir. Dağıtım altyapısı, desteklenen tüm Node.js sürümlerini içeren ayrı bir işlemde çalışır.
Uygulamanızı desteklenen bir Node.js sürümüne ayarlamak için Cloud Shell aşağıdaki komutu çalıştırın:
az webapp config set --resource-group <resource-group-name> --name <app-name> --linux-fx-version "NODE|14-lts"
Bu ayar, hem çalışma zamanında hem de Kudu'da otomatik paket geri yükleme sırasında kullanılacak Node.js sürümünü belirtir.
Not
projenizin package.json
sürümünde Node.js sürümünü ayarlamanız gerekir. Dağıtım altyapısı, desteklenen tüm Node.js sürümlerini içeren ayrı bir kapsayıcıda çalışır.
Bağlantı noktası numarasını alma
Node.js uygulamanızın gelen istekleri almak için doğru bağlantı noktasını dinlemesi gerekir.
Windows'da App Service'da Node.js uygulamalar IISNode ile barındırılır ve Node.js uygulamanız değişkende process.env.PORT
belirtilen bağlantı noktasını dinlemelidir. Aşağıdaki örnek, basit bir Express uygulamasında bunu nasıl yapacağınızı gösterir:
App Service Node.js kapsayıcısında ortam değişkenini PORT
ayarlar ve gelen istekleri kapsayıcınıza bu bağlantı noktası numarasıyla iletir. İstekleri almak için uygulamanızın kullanarak process.env.PORT
bu bağlantı noktasını dinlemesi gerekir. Aşağıdaki örnek, basit bir Express uygulamasında bunu nasıl yapacağınızı gösterir:
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}`)
})
Derleme otomasyonlarını özelleştirme
Uygulamanızı Git kullanarak veya derleme otomasyonu etkinleştirilmiş zip paketleri kullanarak dağıtırsanız, App Service derleme otomasyonu aşağıdaki sırayla ilerler:
- tarafından
PRE_BUILD_SCRIPT_PATH
belirtilirse özel betik çalıştırın. - npm
preinstall
ve betikler içeren vepostinstall
ayrıca 'yi yükleyen bayraklardevDependencies
olmadan çalıştırınnpm install
. - package.json dosyasında bir derleme betiği belirtilirse komutunu çalıştırın
npm run build
. - package.json dosyasında build:azure betiği belirtilirse komutunu çalıştırın
npm run build:azure
. - tarafından
POST_BUILD_SCRIPT_PATH
belirtilirse özel betik çalıştırın.
Not
npm belgelerinde açıklandığı gibi, betikler belirtilirse sırasıyla önce ve sonrasında build
adlı prebuild
ve postbuild
çalıştırılır. preinstall
ve postinstall
önce ve sonra install
sırasıyla çalıştırın.
PRE_BUILD_COMMAND
ve POST_BUILD_COMMAND
varsayılan olarak boş olan ortam değişkenleridir. Derleme öncesi komutları çalıştırmak için öğesini tanımlayın PRE_BUILD_COMMAND
. Derleme sonrası komutları çalıştırmak için öğesini tanımlayın POST_BUILD_COMMAND
.
Aşağıdaki örnek, virgülle ayrılmış bir dizi komut için iki değişkeni belirtir.
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"
Derleme otomasyonlarını özelleştirmeye yönelik ek ortam değişkenleri için bkz. Oryx yapılandırması.
App Service'nin Linux'ta Node.js uygulamaları nasıl çalıştırıp oluşturduğu hakkında daha fazla bilgi için oryx belgelerine bakın: Node.js uygulamaları algılama ve oluşturma.
Node.js sunucusunu yapılandırma
Node.js kapsayıcıları, bir üretim süreci yöneticisi olan PM2 ile birlikte gelir. Uygulamanızı PM2 veya NPM ile ya da özel bir komutla başlayacak şekilde yapılandırabilirsiniz.
Araç | Amaç |
---|---|
PM2 ile çalıştırma | Önerilen - Üretim veya hazırlama kullanımı. PM2, tam hizmet uygulama yönetimi platformu sağlar. |
npm start komutunu çalıştırın | Yalnızca geliştirme kullanımı. |
Özel komut çalıştır | Geliştirme veya hazırlama. |
PM2 ile çalıştırma
Kapsayıcı, projenizde yaygın Node.js dosyalarından biri bulunduğunda uygulamanızı otomatik olarak PM2 ile başlatır:
- bin/www
- server.js
- app.js
- index.js
- hostingstart.js
- Aşağıdaki PM2 dosyalarından biri: process.json ve ecosystem.config.js
Aşağıdaki uzantılarla özel bir başlangıç dosyası da yapılandırabilirsiniz:
- .js dosyası
- .json, .config.js, .yaml veya .yml uzantılı bir PM2 dosyası
Not
Node 14 LTS'den başlayarak kapsayıcı, uygulamanızı PM2 ile otomatik olarak başlatmaz. Uygulamanızı PM2 ile başlatmak için başlangıç komutunu olarak pm2 start <.js-file-or-PM2-file> --no-daemon
ayarlayın. Kapsayıcının --no-daemon
düzgün çalışması için PM2'nin ön planda çalışması gerektiğinden bağımsız değişkenini kullandığınızdan emin olun.
Özel bir başlangıç dosyası eklemek için Cloud Shell aşağıdaki komutu çalıştırın:
az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename-with-extension>"
Özel komut çalıştır
App Service uygulamanızı run.sh gibi bir yürütülebilir dosya gibi özel bir komut kullanarak başlatabilirsiniz. Örneğin, komutunu çalıştırmak npm run start:prod
için Cloud Shell aşağıdaki komutu çalıştırın:
az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "npm run start:prod"
npm start komutunu çalıştırın
Uygulamanızı kullanarak npm start
başlatmak için package.json dosyasında bir start
betik olduğundan emin olun. Örnek:
{
...
"scripts": {
"start": "gulp",
...
},
...
}
Projenizde özel bir package.json kullanmak için Cloud Shell aşağıdaki komutu çalıştırın:
az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename>.json"
Uzaktan hata ayıklama
Not
Uzaktan hata ayıklama şu anda Önizleme aşamasındadır.
Node.js uygulamanızı PM2 ile çalışacak şekilde yapılandırdığınızda Visual Studio Code'da uzaktan hata ayıklayabilirsiniz; bunu .config.js,.yml veya .yaml kullanarak çalıştırmanız dışında.
Çoğu durumda uygulamanız için ek yapılandırma gerekmez. Uygulamanız bir process.json dosyasıyla (varsayılan veya özel) çalıştırılıyorsa, JSON kökünde bir script
özelliği olmalıdır. Örnek:
{
"name" : "worker",
"script" : "./index.js",
...
}
Uzaktan hata ayıklama için Visual Studio Code ayarlamak için App Service uzantısını yükleyin. Uzantı sayfasındaki yönergeleri izleyin ve Visual Studio Code'da Azure'da oturum açın.
Azure gezgininde, hata ayıklamak istediğiniz uygulamayı bulun, sağ tıklayın ve Uzaktan Hata Ayıklamayı Başlat'ı seçin. Uygulamanız için etkinleştirmek için Evet'e tıklayın. App Service sizin için bir tünel ara sunucusu başlatır ve hata ayıklayıcısını ekler. Daha sonra uygulamaya istekte bulunabilir ve hata ayıklayıcının kesme noktalarında duraklamasını görebilirsiniz.
Hata ayıklamayı tamamladıktan sonra Bağlantıyı Kes'i seçerek hata ayıklayıcıyı durdurun. İstendiğinde, uzaktan hata ayıklamayı devre dışı bırakmak için Evet'e tıklamanız gerekir. Daha sonra devre dışı bırakmak için Azure gezgininde uygulamanıza yeniden sağ tıklayın ve Uzaktan Hata Ayıklamayı Devre Dışı Bırak'ı seçin.
Ortam değişkenlerine erişme
App Service'te uygulama kodunuzun dışında uygulama ayarlarını düzenleyebilirsiniz. Ardından standart Node.js desenini kullanarak bunlara erişebilirsiniz. Örneğin NODE_ENV
adlı bir uygulama ayarına erişmek için şu kodu kullanabilirsiniz:
process.env.NODE_ENV
Grunt/Bower/Gulp komutunu çalıştırın
Varsayılan olarak, App Service derleme otomasyonu bir Node.js uygulamasını tanıdığında Git aracılığıyla veya derleme otomasyonu etkin zip dağıtımı aracılığıyla dağıtıldığında çalışırnpm install --production
. Uygulamanız Grunt, Bower veya Gulp gibi popüler otomasyon araçlarından herhangi birini gerektiriyorsa, uygulamayı çalıştırmak için özel bir dağıtım betiği sağlamanız gerekir.
Deponuzun bu araçları çalıştırmasını sağlamak için bunları package.json dosyasındaki bağımlılıklara eklemeniz gerekir. Örneğin:
"dependencies": {
"bower": "^1.7.9",
"grunt": "^1.0.1",
"gulp": "^3.9.1",
...
}
Yerel terminal penceresinden dizini depo kök dizininizle değiştirin ve aşağıdaki komutları çalıştırın:
npm install kuduscript -g
kuduscript --node --scriptType bash --suppressPrompt
Depo kökünüzün artık iki ek dosyası vardır: .deployment ve deploy.sh.
deploy.sh açın ve şu şekilde görünen bölümü bulunDeployment
:
##################################################################################################################################
# Deployment
# ----------
Bu bölüm çalıştırma npm install --production
ile sona erer. Bölümün sonundaDeployment
gerekli aracı çalıştırmak için ihtiyacınız olan kod bölümünü ekleyin:
MEAN.js örneğinde dağıtım betiğinin de özel npm install
bir komut çalıştırdığı bir örne bakın.
Bower
Bu kod parçacığı çalıştırır 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
Bu kod parçacığı çalıştırır 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
Bu kod parçacığı çalıştırır grunt
.
if [ -e "$DEPLOYMENT_TARGET/Gruntfile.js" ]; then
cd "$DEPLOYMENT_TARGET"
eval ./node_modules/.bin/grunt
exitWithMessageOnError "Grunt failed"
cd - > /dev/null
fi
HTTPS oturumlarını algılama
App Service'da TLS/SSL sonlandırma ağ yük dengeleyicilerinde gerçekleşir, bu nedenle tüm HTTPS istekleri uygulamanıza şifrelenmemiş HTTP istekleri olarak ulaşır. Uygulama mantığınızın kullanıcı isteklerinin şifrelenip şifrelenmediğini denetlemesi gerekiyorsa üst bilgiyi inceleyin X-Forwarded-Proto
.
Popüler web çerçeveleri, standart uygulama düzeninizdeki bilgilere erişmenizi X-Forwarded-*
sağlar. Express'tegüven proxy'lerini kullanabilirsiniz. Örnek:
app.set('trust proxy', 1)
...
if (req.secure) {
// Do something when HTTPS is used
}
Tanılama günlüklerine erişim
App Service’te uygulama kodunuzun içinden oluşturulan konsol günlüklerine erişmek için şu komutu Cloud Shell’de çalıştırarak tanılama günlüğüne kaydetmeyi açın:
az webapp log config --resource-group <resource-group-name> --name <app-name> --docker-container-logging filesystem --level Verbose
--level
için olası değerler: Error
, Warning
, Info
ve Verbose
. Her düzey kendisinden önceki düzeyi içerir. Örneğin: Error
yalnızca hata iletilerini içerir, Verbose
ise tüm iletileri içerir.
Tanılama günlüğüne kaydetme açıldıktan sonra günlük akışını görmek için şu komutu çalıştırın:
az webapp log tail --resource-group <resource-group-name> --name <app-name>
Konsol günlüklerini hemen görmüyorsanız, 30 saniye içinde yeniden kontrol edin.
Not
Ayrıca, tarayıcıdan https://<app-name>.scm.azurewebsites.net/api/logs/docker
adresine giderek günlük dosyalarını inceleyebilirsiniz.
Günlük akışını dilediğiniz zaman durdurmak için Ctrl
+C
yazın.
Kapsayıcının içinden oluşturulan konsol günlüklerine erişebilirsiniz.
İlk olarak, aşağıdaki komutu çalıştırarak kapsayıcı günlüğünü açın:
az webapp log config --name <app-name> --resource-group <resource-group-name> --docker-container-logging filesystem
ve <resource-group-name>
değerini web uygulamanız için uygun adlarla değiştirin<app-name>
.
Kapsayıcı günlüğü açıldıktan sonra günlük akışını görmek için aşağıdaki komutu çalıştırın:
az webapp log tail --name <app-name> --resource-group <resource-group-name>
Konsol günlüklerini hemen görmüyorsanız, 30 saniye içinde yeniden kontrol edin.
Günlük akışını istediğiniz zaman durdurmak için Ctrl+C yazın.
Ayrıca, tarayıcıdaki günlük dosyalarını da inceleyebilirsiniz https://<app-name>.scm.azurewebsites.net/api/logs/docker
.
Application Insights ile izleme
Application Insights, kod değişikliği yapmadan uygulamanızın performansını, özel durumlarını ve kullanımını izlemenize olanak tanır. App Insights aracısını eklemek için Portalda web uygulamanıza gidin ve Ayarlar'ın altında Application Insights'ı ve ardından Application Insights'ı aç'ı seçin. Ardından mevcut bir App Insights kaynağını seçin veya yeni bir kaynak oluşturun. Son olarak, en alttaki Uygula'yı seçin. Web uygulamanızı PowerShell kullanarak işaretlemek için lütfen şu yönergelere bakın
Bu aracı, sunucu tarafı Node.js uygulamanızı izler. İstemci tarafı JavaScript'inizi izlemek için projenize JavaScript SDK'sını ekleyin.
Daha fazla bilgi için bkz. Application Insights uzantısı sürüm notları.
Sorun giderme
Çalışan bir Node.js uygulaması App Service farklı davrandığında veya hataları olduğunda aşağıdakileri deneyin:
- Günlük akışına erişin.
- Uygulamayı üretim modunda yerel olarak test edin. App Service Node.js uygulamalarınızı üretim modunda çalıştırdığından, projenizin yerel olarak üretim modunda beklendiği gibi çalıştığından emin olmanız gerekir. Örnek:
- package.json dosyanıza bağlı olarak, üretim modu (
dependencies
ile ) için farklı paketler yüklenebilir.devDependencies
- Bazı web çerçeveleri üretim modunda statik dosyaları farklı şekilde dağıtabilir.
- Bazı web çerçeveleri üretim modunda çalışırken özel başlangıç betikleri kullanabilir.
- package.json dosyanıza bağlı olarak, üretim modu (
- Uygulamanızı geliştirme modunda App Service çalıştırın. Örneğin, MEAN.jsiçinde, uygulama ayarını ayarlayarak
NODE_ENV
uygulamanızı çalışma zamanında geliştirme moduna ayarlayabilirsiniz.
Bu dizini veya sayfayı görüntüleme izniniz yok
App Service'da Node.js kodunuzu yerel bir Windows uygulamasına dağıttığınızda, uygulamanızın URL'sine gittiğinizde iletiyi You do not have permission to view this directory or page.
tarayıcıda görebilirsiniz. Bunun nedeni büyük olasılıkla web.config dosyanız olmadığındandır ( şablona ve örne bakın).
Dosyalarınızı Git kullanarak veya derleme otomasyonu etkinken ZIP dağıtımı kullanarak dağıtırsanız, aşağıdaki koşullardan biri doğruysa dağıtım altyapısı uygulamanızın (%HOME%\site\wwwroot
) web kökünde otomatik olarak bir web.config oluşturur:
- Proje kökünüzün, JavaScript dosyasının yolunu içeren bir
start
betiği tanımlayan bir package.json dosyası vardır. - Proje kökünüzün server.js veya app.jsvardır.
Oluşturulan web.config algılanan başlangıç betiğine uyarlanmıştır. Diğer dağıtım yöntemleri için bu web.config el ile ekleyin. Dosyanın düzgün biçimlendirildiğinden emin olun.
ZIP dağıtımını kullanıyorsanız (örneğin, Visual Studio Code aracılığıyla), varsayılan olarak etkinleştirilmediğinden derleme otomasyonını etkinleştirdiğinizden emin olun. az webapp up
derleme otomasyonu etkin olarak ZIP dağıtımını kullanır.
Günlüklerde robots933456
Kapsayıcı günlüklerinde şu iletiyi görebilirsiniz:
2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"
Bu iletiyi güvenle yoksayabilirsiniz. /robots933456.txt
, App Service hizmetinin kapsayıcının istek sunmak için uygun olup olmadığını denetlemek için kullandığı işlevsiz bir URL'dir. 404 yanıtı, yolun var olmadığını belirtir ancak App Service bu sayede iyi ve isteklere yanıt vermeye uygun durumda olan kapsayıcıları belirler.
Sonraki adımlar
Veya ek kaynaklara bakın: