Mengonfigurasi aplikasi Node.js untuk Azure App Service
Node.js aplikasi harus disebarkan dengan semua dependensi npm yang diperlukan. Mesin penyebaran App Service secara otomatis berjalan npm install --production
untuk Anda saat Anda menyebarkan repositori Git, atau saat Anda menyebarkan paket Zip dengan otomatisasi build diaktifkan. Namun, jika Anda menyebarkan file menggunakan FTP/S, Anda perlu mengunggah paket yang diperlukan secara manual.
Panduan ini menyediakan instruksi dan konsep utama untuk pengembang Node.js yang menyebarkan ke App Service. Jika Anda belum pernah menggunakan Azure App Service, ikuti mulai cepat Node.js dan tutorial Node.js dengan MongoDB dahulu.
Menampilkan versi Node.js
Untuk menampilkan versi Node.js saat ini, jalankan perintah berikut ini di Cloud Shell:
az webapp config appsettings list --name <app-name> --resource-group <resource-group-name> --query "[?name=='WEBSITE_NODE_DEFAULT_VERSION'].value"
Untuk menampilkan semua versi Node.js yang didukung, navigasikan ke https://<sitename>.scm.azurewebsites.net/api/diagnostics/runtime
atau jalankan perintah berikut di Cloud Shell:
az webapp list-runtimes --os windows | grep NODE
Untuk menampilkan versi Node.js saat ini, jalankan perintah berikut ini di Cloud Shell:
az webapp config show --resource-group <resource-group-name> --name <app-name> --query linuxFxVersion
Untuk menampilkan semua versi Node.js yang didukung, jalankan perintah berikut di Cloud Shell:
az webapp list-runtimes --os linux | grep NODE
Mengatur versi Node.js
Untuk mengatur aplikasi Anda ke versi Node.js yang didukung, jalankan perintah berikut di Cloud Shell untuk mengatur WEBSITE_NODE_DEFAULT_VERSION
ke versi yang didukung:
az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_NODE_DEFAULT_VERSION="~16"
Catatan
Contoh ini menggunakan "sintaks tilde" yang direkomendasikan untuk menargetkan versi terbaru dari runtime Node.js 16 yang tersedia di App Service.
Karena runtime secara teratur di-patch dan diperbarui oleh platform, kami tidak menyarankan Agar Anda menargetkan versi/patch minor tertentu karena ini tidak dijamin tersedia karena potensi risiko keamanan.
Catatan
Anda harus mengatur versi Node.js di package.json
proyek Anda. Mesin penyebaran berjalan dalam proses terpisah yang berisi semua versi Node.js yang didukung.
Untuk mengatur aplikasi Anda ke versi Node.js yang didukung, jalankan perintah berikut di Cloud Shell:
az webapp config set --resource-group <resource-group-name> --name <app-name> --linux-fx-version "NODE|14-lts"
Pengaturan ini menentukan Node.js yang akan digunakan, baik pada runtime maupun selama pemulihan paket otomatis di Kudu.
Catatan
Anda harus mengatur versi Node.js di package.json
proyek Anda. Mesin penyebaran berjalan dalam kontainer terpisah yang berisi semua versi Node.js yang didukung.
Mendapatkan nomor port
Aplikasi Node.js Anda perlu mendengarkan port yang tepat untuk menerima permintaan masuk.
Pada App Service di Windows, aplikasi Node.js dihosting dengan IISNode, dan aplikasi Node.js Anda harus mendengarkan port yang ditentukan dalam variabel process.env.PORT
. Contoh berikut menunjukkan cara melakukannya di aplikasi Express sederhana:
App Service menetapkan PORT
variabel lingkungan di Node.js, dan meneruskan permintaan masuk ke kontainer Anda di nomor port tersebut. Untuk menerima permintaan, aplikasi Anda harus mendengarkan port tersebut menggunakan process.env.PORT
. Contoh berikut menunjukkan cara melakukannya di aplikasi Express sederhana:
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}`)
})
Mengkustomisasi otomatisasi build
Jika Anda menyebarkan aplikasi dengan menggunakan Git, atau dengan menggunakan paket zip dengan otomatisasi build diaktifkan, App Service membuat langkah-langkah otomatisasi melalui urutan berikut:
- Jalankan skrip kustom, jika skrip ditentukan oleh
PRE_BUILD_SCRIPT_PATH
. - Jalankan
npm install
tanpa bendera apa pun, yang mencakup skrip npmpreinstall
danpostinstall
serta menginstaldevDependencies
. - Jalankan
npm run build
jika skrip build ditentukan di package.json Anda. - Jalankan
npm run build:azure
jika skrip build:azure ditentukan di package.json Anda. - Menjalankan skrip kustom jika ditentukan oleh
POST_BUILD_SCRIPT_PATH
.
Catatan
Seperti yang disebutkan dalam dokumen npm, skrip bernama prebuild
dan postbuild
berjalan sebelum dan sesudah build
, masing-masing, jika ditentukan. preinstall
dan postinstall
masing-masing dijalankan sebelum dan sesudah install
.
PRE_BUILD_COMMAND
dan POST_BUILD_COMMAND
merupakan variabel lingkungan yang kosong secara default. Untuk menjalankan perintah pra-build, tentukan PRE_BUILD_COMMAND
. Untuk menjalankan perintah pasca-build, tentukan POST_BUILD_COMMAND
.
Contoh berikut menggunakan dua variabel untuk menentukan serangkaian perintah, dipisahkan oleh koma.
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"
Untuk informasi tentang variabel lingkungan tambahan untuk menyesuaikan otomatisasi build, lihat Konfigurasi Oryx.
Untuk informasi lebih lanjut tentang cara App Service menjalankan dan membangun aplikasi Node.js di Linux, lihat Dokumentasi Oryx: Bagaimana aplikasi Node.js dideteksi dan dibuat.
Mengonfigurasi server Node.js
Kontainer Node.js dilengkapi dengan PM2, manajer proses produksi. Anda dapat mengonfigurasi aplikasi untuk memulai dengan PM2, dengan npm start, atau dengan perintah kustom.
Alat | Tujuan |
---|---|
Menjalankan dengan PM2 | Direkomendasikan - Penggunaan produksi atau pentahapan. PM2 menyediakan platform manajemen aplikasi layanan lengkap. |
Jalankan dengan npm start | Hanya penggunaan pengembangan. |
Jalankan dengan perintah kustom | Baik pengembangan atau penahapan. |
Menjalankan dengan PM2
Kontainer secara otomatis memulai aplikasi Anda dengan PM2 ketika salah satu file Node.js umum ditemukan di proyek Anda:
- bin/www
- server.js
- app.js
- index.js
- hostingstart.js
- Salah satu file PM2 berikut: process.json atau ecosystem.config.js
Anda juga dapat mengonfigurasi file awal kustom dengan ekstensi berikut:
- File .js
- File PM2 dengan ekstensi .json, .config.js, .yaml, atau .yml
Catatan
Mulai dari Node 14 LTS, kontainer tidak secara otomatis memulai aplikasi Anda dengan PM2. Untuk memulai aplikasi Anda dengan PM2, atur perintah mulai ke pm2 start <.js-file-or-PM2-file> --no-daemon
. Pastikan untuk menggunakan argumen --no-daemon
karena PM2 harus dijalankan di latar depan agar kontainer berfungsi dengan baik.
Untuk menambahkan file awal kustom, jalankan perintah berikut di Cloud Shell:
az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename-with-extension>"
Jalankan dengan perintah kustom
App Service dapat memulai aplikasi Anda menggunakan perintah kustom, seperti perintah yang dapat dijalankan seperti run.sh. Misalnya, untuk menjalankan npm run start:prod
, jalankan perintah berikut di Cloud Shell:
az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "npm run start:prod"
Jalankan dengan npm start
Untuk memulai aplikasi Anda menggunakan npm start
, pastikan skrip start
ada di file package.json. Contohnya:
{
...
"scripts": {
"start": "gulp",
...
},
...
}
Untuk menggunakan package.json kustom dalam proyek Anda, jalankan perintah berikut di Cloud Shell:
az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename>.json"
Men-debug dari jarak jauh
Anda dapat men-debug aplikasi Node.js dari jarak jauh di Visual Studio Code jika Anda mengonfigurasinya untuk dijalankan dengan PM2, kecuali jika Anda menjalankannya menggunakan .config.js,.yml, atau .yaml.
Dalam kebanyakan kasus, tidak diperlukan konfigurasi tambahan untuk aplikasi Anda. Jika aplikasi Anda dijalankan dengan file process.json (default atau khusus), aplikasi harus memiliki properti script
di akan JSON. Contohnya:
{
"name" : "worker",
"script" : "./index.js",
...
}
Untuk menyiapkan Visual Studio Code untuk debug jarak jauh, instal ekstensi App Service. Ikuti instruksi pada halaman ekstensi dan masuk ke Azure di Visual Studio Code.
Di penjelajah Azure, temukan aplikasi yang ingin Anda debug, klik kanan dan pilih Mulai Debug Jarak Jauh. Pilih Ya untuk mengaktifkan penelusuran kesalahan jarak jauh untuk aplikasi Anda. App Service memulai proxy terowongan untuk Anda dan melampirkan debugger. Anda kemudian dapat membuat permintaan ke aplikasi dan melihat debugger berhenti di titik pemisah.
Setelah selesai men-debug, hentikan debugger dengan memilih Putuskan sambungan. Saat diminta, Anda harus memilih Ya untuk menonaktifkan penelusuran kesalahan jarak jauh. Untuk menonaktifkannya nanti, klik kanan aplikasi Anda lagi di penjelajah Azure dan pilih Nonaktifkan Debug Jarak Jauh.
Mengakses variabel lingkungan
Di App Service, Anda dapat menyetel pengaturan aplikasi di luar kode aplikasi. Kemudian Anda dapat mengaksesnya menggunakan pola Node.js standar. Misalnya, untuk mengakses pengaturan aplikasi yang disebut NODE_ENV
, gunakan kode berikut:
process.env.NODE_ENV
Menjalankan Grunt/Bower/Gulp
Secara default, otomatisasi build App Service berjalan npm install --production
saat mengenali bahwa aplikasi Node.js disebarkan melalui Git, atau melalui penyebaran Zip dengan otomatisasi build diaktifkan. Jika aplikasi Anda memerlukan salah satu alat automasi populer, seperti Grunt, Bower, atau Gulp, Anda perlu menyediakan skrip penyebaran khusus untuk menjalankannya.
Agar repositori Anda dapat menjalankan alat ini, Anda perlu menambahkannya ke dependensi di package.json. Misalnya:
"dependencies": {
"bower": "^1.7.9",
"grunt": "^1.0.1",
"gulp": "^3.9.1",
...
}
Dari jendela terminal lokal, ubah direktori ke root repositori Anda dan jalankan perintah berikut:
npm install kuduscript -g
kuduscript --node --scriptType bash --suppressPrompt
Akar repositori Anda sekarang memiliki dua file tambahan: .deployment dan deploy.sh.
Buka deploy.sh dan temukan bagian Deployment
, yang terlihat seperti ini:
##################################################################################################################################
# Deployment
# ----------
Bagian ini diakhiri dengan menjalankan npm install --production
. Tambahkan bagian kode yang Anda perlukan untuk menjalankan alat yang diperlukan di akhir bagian Deployment
:
Lihat contoh dalam sampel MEAN.js, tempat skrip penyebaran juga menjalankan perintah npm install
kustom.
Bower
Cuplikan ini menjalankan 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
Cuplikan ini menjalankan 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
Cuplikan ini menjalankan grunt
.
if [ -e "$DEPLOYMENT_TARGET/Gruntfile.js" ]; then
cd "$DEPLOYMENT_TARGET"
eval ./node_modules/.bin/grunt
exitWithMessageOnError "Grunt failed"
cd - > /dev/null
fi
Mendeteksi sesi HTTPS
Dalam App Service, penghentian TLS/SSL terjadi pada load balancer jaringan, sehingga semua permintaan HTTPS mencapai aplikasi Anda sebagai permintaan HTTP yang tidak terenkripsi. Jika logika aplikasi Anda perlu memeriksa apakah permintaan pengguna dienkripsi, periksa X-Forwarded-Proto
header.
Kerangka kerja web populer memungkinkan Anda mengakses informasi X-Forwarded-*
dalam pola aplikasi standar Anda. Di Express, Anda dapat menggunakan proxy kepercayaan. Contohnya:
app.set('trust proxy', 1)
...
if (req.secure) {
// Do something when HTTPS is used
}
Mengakses log diagnostik
Untuk mengakses log konsol yang dihasilkan dari dalam kode aplikasi Anda di App Service, aktifkan pembuatan log diagnostik dengan menjalankan perintah berikut di Cloud Shell:
az webapp log config --resource-group <resource-group-name> --name <app-name> --docker-container-logging filesystem --level Verbose
Nilai yang mungkin untuk --level
adalah: Error
, Warning
, Info
, dan Verbose
. Setiap level berikutnya mencakup level sebelumnya. Misalnya: Error
hanya menyertakan pesan kesalahan, dan Verbose
menyertakan semua pesan.
Setelah pembuatan log diagnostik diaktifkan, jalankan perintah berikut untuk melihat aliran log:
az webapp log tail --resource-group <resource-group-name> --name <app-name>
Jika Anda tidak segera melihat log konsol, periksa lagi dalam 30 detik.
Catatan
Anda juga dapat memeriksa file log dari browser di https://<app-name>.scm.azurewebsites.net/api/logs/docker
.
Untuk menghentikan streaming log kapan saja, ketikkan Ctrl
+C
.
Anda dapat mengakses log konsol yang dihasilkan dari dalam kontainer.
Pertama, aktifkan pengelogan kontainer dengan menjalankan perintah berikut:
az webapp log config --name <app-name> --resource-group <resource-group-name> --docker-container-logging filesystem
Ganti <app-name>
dan <resource-group-name>
dengan nama yang sesuai untuk aplikasi web Anda.
Setelah pengelogan kontainer diaktifkan, jalankan perintah berikut untuk melihat aliran log:
az webapp log tail --name <app-name> --resource-group <resource-group-name>
Jika Anda tidak segera melihat log konsol, periksa lagi dalam 30 detik.
Untuk menghentikan streaming log kapan saja, tekan Ctrl+C.
Anda juga dapat memeriksa file log di browser di https://<app-name>.scm.azurewebsites.net/api/logs/docker
.
Penulisan ulang URL
Saat menyebarkan aplikasi Node.js di Azure App Service untuk Linux, Anda mungkin perlu menangani penulisan ulang URL langsung dalam aplikasi Anda. Ini sangat berguna untuk memastikan pola URL tertentu dialihkan ke titik akhir yang benar tanpa mengandalkan konfigurasi server web. Ada beberapa cara untuk menyelesaikan penulisan ulang URL dalam Node.js. Salah satu contohnya adalah melalui paket express-urlrewrite .
Memantau dengan Application Insights
Application Insights memungkinkan Anda memantau performa, pengecualian, dan penggunaan aplikasi Anda tanpa membuat perubahan kode apa pun. Untuk melampirkan agen Application Insights, buka aplikasi web Anda di portal, pilih Application Insights di bawah Pengaturan, lalu pilih Aktifkan Application Insights. Selanjutnya, pilih sumber daya Application Insights yang sudah ada atau buat sumber daya baru. Terakhir, pilih Terapkan di bagian bawah. Untuk melengkapi aplikasi web Anda menggunakan PowerShell, lihat instruksi ini
Agen ini akan memantau aplikasi Node.js sisi server Anda. Untuk memantau JavaScript sisi klien Anda, tambahkan SDK JavaScript ke proyek Anda.
Untuk informasi lebih lanjut, lihat Catatan rilis ekstensi Application Insights.
Pemecahan Masalah
Saat aplikasi Node.js yang aktif berperilaku berbeda di App Service atau mengalami kesalahan, coba fitur berikut:
- Mengalirkan aliran log.
- Uji aplikasi secara lokal dalam mode produksi. App Service menjalankan aplikasi Node.js Anda dalam mode produksi, jadi Anda perlu memastikan bahwa proyek Anda berfungsi seperti yang diharapkan dalam mode produksi secara lokal. Misalnya:
- Bergantung pada package.json Anda, paket yang berbeda mungkin diinstal untuk mode produksi (
dependencies
vs.devDependencies
). - Kerangka kerja web tertentu mungkin menyebarkan file statis secara berbeda dalam mode produksi.
- Kerangka kerja web tertentu mungkin menggunakan skrip startup kustom saat berjalan dalam mode produksi.
- Bergantung pada package.json Anda, paket yang berbeda mungkin diinstal untuk mode produksi (
- Jalankan aplikasi Anda di App Service dalam mode pengembangan. Misalnya, di MEAN.js, Anda dapat mengatur aplikasi ke mode pengembangan saat runtime dengan mengatur
NODE_ENV
pengaturan aplikasi.
Anda tidak memiliki izin untuk melihat direktori atau halaman ini
Setelah menyebarkan kode Node.js ke aplikasi Windows asli di App Service, Anda mungkin melihat pesan You do not have permission to view this directory or page
di browser saat menavigasi ke URL aplikasi Anda. Ini kemungkinan besar karena Anda tidak memiliki file web.config . (Lihat templat dan contoh.)
Jika Anda menyebarkan file Anda dengan menggunakan Git, atau dengan menggunakan penyebaran ZIP dengan otomatisasi build diaktifkan, mesin penyebaran menghasilkan web.config di akar web aplikasi Anda (%HOME%\site\wwwroot
) secara otomatis jika salah satu kondisi berikut adalah benar:
- Akar proyek Anda memiliki package.json yang mendefinisikan skrip
start
yang berisi jalur file JavaScript. - Akar proyek Anda memiliki server.js atau app.js.
web.config yang dihasilkan disesuaikan dengan skrip awal yang terdeteksi. Untuk metode penyebaran lainnya, tambahkan web.config ini secara manual. Pastikan file diformat dengan benar.
Jika Anda menggunakan penyebaran ZIP (melalui Visual Studio Code, misalnya), pastikan untuk mengaktifkan otomatisasi build. Perlindungan pembersihan tidak diaktifkan secara default. az webapp up
menggunakan penyebaran ZIP dengan otomatisasi build diaktifkan.
robot933456 dalam log
Anda mungkin melihat pesan berikut dalam log kontainer:
2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"
Anda dapat mengabaikan pesan ini dengan aman. /robots933456.txt
adalah jalur URL dummy yang digunakan App Service untuk memeriksa apakah kontainer mampu melayani permintaan. Respons 404 hanya menunjukkan bahwa jalur tersebut tidak ada, tetapi ini memberi tahu App Service bahwa kontainernya sehat dan siap untuk menanggapi permintaan.
Langkah berikutnya
Atau, lihat sumber daya tambahan: