Mengonfigurasi aplikasi Node.js untuk Azure App Service

2024-10-16

Aplikasi Node.js harus disebarkan dengan semua dependensi npm yang dibutuhkan. Mesin penyebaran App Service secara otomatis dijalankan npm install --production untuk Anda saat Anda menyebarkan Git repositori, atau saat Anda menyebarkan paket Zip saat 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, 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 keberadaannya tidak dijamin disebabkan oleh 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.

Apa yang terjadi terhadap runtime yang kedaluwarsa di App Service?

Runtime yang ketinggalan jaman tidak digunakan lagi oleh organisasi yang memelihara atau ditemukan memiliki kerentanan yang signifikan. Dengan demikian, halaman tersebut dihapus dari halaman buat dan konfigurasikan di portal. Saat runtime yang kedaluarsa disembunyikan dari portal, aplikasi apa pun yang masih menggunakan runtime tersebut terus berjalan.

Jika Anda ingin membuat aplikasi dengan versi runtime usang yang tidak lagi ditampilkan di portal, gunakan Azure CLI, templat ARM, atau Bicep. Alternatif penyebaran ini memungkinkan Anda membuat runtime yang tidak digunakan lagi yang telah dihapus di portal, tetapi masih didukung.

Jika runtime sepenuhnya dihapus dari platform App Service, pemilik langganan Azure Anda menerima pemberitahuan email sebelum penghapusan.

Dapatkan 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}`)
})

Sesuaikan 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 ada yang ditentukan oleh PRE_BUILD_SCRIPT_PATH.
Jalankan npm install tanpa bendera apa pun, yang mencakup skrip npm preinstall dan postinstall serta menginstal devDependencies.
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 dokumentasi npm, skrip bernama prebuild dan postbuild berjalan masing-masing sebelum dan sesudah build, 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 untuk pengujian. PM2 menyediakan platform manajemen aplikasi layanan lengkap.
Jalankan dengan npm start	Hanya untuk penggunaan pengembangan.
Jalankan dengan perintah kustom	Entah pengembangan atau penahapan.

Jalankan 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:

Sebuah 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), itu harus memiliki properti script di root 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 debugging jarak jauh aplikasi Anda. App Service memulai proxy terowongan untuk Anda dan menghubungkan 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 debugging 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:

Bower
Glek
Mendengus

Lihat contoh dalam sampel MEAN.js, tempat skrip penyebaran juga menjalankan perintah npm install kustom.

Bower

Kode 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

Teguk

Kode 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

Gerutu

Kode 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 tepercaya. 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. Verbose menyertakan semua pesan.

Setelah Anda mengaktifkan pembuatan log diagnostik, jalankan perintah berikut untuk melihat aliran log:

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

Jika log konsol tidak segera muncul, periksa lagi dalam 30 detik.

Untuk menghentikan streaming log kapan saja, pilih Ctrl+C.

Anda dapat mengakses log konsol yang dihasilkan dari dalam kontainer.

Untuk mengaktifkan pengelogan kontainer, jalankan 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 Anda mengaktifkan pengelogan kontainer, jalankan perintah berikut untuk melihat aliran log:

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

Jika log konsol tidak segera muncul, periksa lagi dalam 30 detik.

Untuk menghentikan streaming log kapan saja, pilih Ctrl+C.

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
- 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.
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 penerapan ZIP (melalui Visual Studio Code, misalnya), pastikan untuk mengaktifkan otomatisasi build. Ini tidak diaktifkan secara default. az webapp up menggunakan penyebaran ZIP dengan otomatisasi build yang diaktifkan.

Abaikan pesan robots933456 dalam log

Anda mungkin melihat pesan berikut di 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 menunjukkan bahwa jalur tidak ada, dan memberi sinyal ke App Service bahwa kontainer sehat dan siap merespons permintaan.

Langkah berikutnya

Tutorial: Aplikasi Node.js dengan MongoDB

FAQ tentang Azure App Service pada Linux

Atau, lihat sumber daya tambahan:

Variabel lingkungan dan referensi pengaturan aplikasi

Bagikan melalui

Mengonfigurasi aplikasi Node.js untuk Azure App Service

Menampilkan versi Node.js

Mengatur versi Node.js

Apa yang terjadi terhadap runtime yang kedaluwarsa di App Service?

Dapatkan nomor port

Sesuaikan otomatisasi build

Mengonfigurasi server Node.js

Jalankan dengan PM2

Jalankan dengan perintah kustom

Jalankan dengan npm start

Men-debug dari jarak jauh

Mengakses variabel lingkungan

Menjalankan Grunt/Bower/Gulp

Bower

Teguk

Gerutu

Mendeteksi sesi HTTPS

Mengakses log diagnostik

Penulisan ulang URL

Memantau dengan Application Insights

Pemecahan Masalah

Anda tidak memiliki izin untuk melihat direktori atau halaman ini

Abaikan pesan robots933456 dalam log

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: