Node.js API'yi VPS'te Yayınlama Rehberi

Uygulama portunu internete açmayın

Bu ayrım sertifika yönetimini uygulama kodundan çıkarır. API’nin 3000 portu için UFW kuralı eklemeniz gerekmez; hizmet 127.0.0.1 üzerinde dinler. Uygulama yanlışlıkla 0.0.0.0 adresine bağlanırsa portun erişim kapsamı değişir. Yayın sonrasında ss komutuyla gerçek dinleme adresini kontrol edin.

Node.js için desteklenen bir LTS dalı seçin. Aşağıdaki örnek, inceleme tarihinde resmî 24.x dizinindeki 24.21.0 sürümünü kullanır. Sonraki güvenlik güncellemelerini aynı desteklenen dalda planlı biçimde uygulayın; eski Node 20 sürümünü yeni kurulum varsayılanı olarak almayın.

Sürümü doğrulanmış çalışma ortamını hazırlayın

Bu indirme yalnız x86_64 içindir; uname -m çıktısı aarch64 ise linux-arm64 arşivini ve o dosyanın sağlama toplamını seçmeniz gerekir. SHA256 kontrolü indirilen dosyanın yayınlanan özetle eşleştiğini doğrular. Daha güçlü tedarik zinciri doğrulaması için Node.js’in imzalı SHASUMS yönergesini izleyin.

uname -m
sudo apt update
sudo apt install ca-certificates curl xz-utils nginx
mkdir -p "$HOME/node-install"
cd "$HOME/node-install"
curl -fSLO https://nodejs.org/dist/v24.21.0/node-v24.21.0-linux-x64.tar.xz
curl -fSLO https://nodejs.org/dist/v24.21.0/SHASUMS256.txt
grep ' node-v24.21.0-linux-x64.tar.xz$' SHASUMS256.txt | sha256sum -c -
# Yalnız doğrulama OK döndürdüyse:
sudo tar -xJf node-v24.21.0-linux-x64.tar.xz -C /opt
/opt/node-v24.21.0-linux-x64/bin/node --version

Kurulumu /opt altında sürüm adıyla tutmak kullanılan çalıştırılabilir dosyayı belirgin kılar. Servis dosyası da aynı tam yolu kullanacaktır. Kullanıcı kabuğuna bağlı bir sürüm yöneticisinin PATH ayarları systemd servisinde otomatik yüklenmeyebilir.

sudo useradd --system --home-dir /srv/serverq-api --shell /usr/sbin/nologin serverq-api
sudo install -d -o root -g serverq-api -m 0750 /srv/serverq-api

Küçük ve ölçülebilir bir sağlık uç noktası oluşturun

Aşağıdaki içeriği /srv/serverq-api/server.mjs dosyasına kaydedin. .mjs uzantısı ES modülünü belirtir; bu örnek npm bağımlılığı gerektirmez. Kendi projenizde kilit dosyasıyla npm ci kullanın ve kurulum betiklerinin hangi yetkiyle çalıştığını bilin. Üretim servis kullanıcısına tüm kaynak ağacını yazma izni vermeyin.

import http from "node:http";

const server = http.createServer((req, res) => {
  res.setHeader("Content-Type", "application/json; charset=utf-8");
  res.setHeader("Cache-Control", "no-store");
  if (req.method === "GET" && req.url === "/health") {
    res.writeHead(200);
    res.end(JSON.stringify({ status: "ok" }));
    return;
  }
  res.writeHead(404);
  res.end(JSON.stringify({ error: "not_found" }));
});

server.listen(3000, "127.0.0.1", () => {
  console.log("API ready on 127.0.0.1:3000");
});
process.on("SIGTERM", () => server.close());

sudo chown root:serverq-api /srv/serverq-api/server.mjs
sudo chmod 0640 /srv/serverq-api/server.mjs
sudo -u serverq-api /opt/node-v24.21.0-linux-x64/bin/node --check /srv/serverq-api/server.mjs

Süreci systemd ile yönetin

Aşağıdaki dosyayı /etc/systemd/system/serverq-api.service konumuna kaydedin. ProtectSystem=strict uygulamanın dosya sistemine yazmasını sınırlar; bu örneğin diske yazması gerekmez. Gerçek uygulamada dosya yükleme veya SQLite varsa yalnız gerekli veri dizinine açık izin verin. Tüm korumaları kaldırmak yerine uygulamanın yazma ihtiyacını tanımlayın.

[Unit]
Description=Node.js API
After=network.target

[Service]
Type=simple
User=serverq-api
Group=serverq-api
WorkingDirectory=/srv/serverq-api
ExecStart=/opt/node-v24.21.0-linux-x64/bin/node /srv/serverq-api/server.mjs
Environment=NODE_ENV=production
Restart=on-failure
RestartSec=5
TimeoutStopSec=20
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
UMask=0027

[Install]
WantedBy=multi-user.target

sudo systemd-analyze verify /etc/systemd/system/serverq-api.service
sudo systemctl daemon-reload
sudo systemctl enable --now serverq-api
sudo systemctl status serverq-api --no-pager
curl -i http://127.0.0.1:3000/health
sudo ss -ltnp | grep ":3000"

Beklenen sonuç /health için HTTP 200, başka bir yol için 404 ve 127.0.0.1:3000 dinleme adresidir. Sürekli yeniden başlatma varsa journalctl -u serverq-api -n 50 --no-pager ile ilk hatayı bulun. Dosya yolu, çalışma dizini veya izin hatası genellikle uygulama hatasıyla karıştırılır.

Nginx üzerinden HTTPS’e bağlayın

example.com için etkin HTTP site dosyanızdaki ilgili location bloğunu aşağıdakiyle değiştirin; aynı server_name ile ikinci bir çakışan site oluşturmayın. Henüz site kurmadıysanız Nginx/HTTPS rehberindeki server bloğunu temel alın. HTTP yanıtını doğruladıktan sonra Certbot adımlarını uygulayın.

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_connect_timeout 5s;
    proxy_read_timeout 30s;
}

sudo nginx -t
# Test başarılıysa:
sudo systemctl reload nginx
curl -i -H "Host: example.com" http://127.0.0.1/health
# HTTPS sertifikası kurulduktan sonra:
curl -i https://example.com/health

Bu örnek normal HTTP isteği içindir. WebSocket veya uzun süren akışlar için bağlantı başlıkları, zaman aşımı ve proxy buffering davranışı ayrıca ayarlanır. Express gibi bir framework kullanıyorsanız trust proxy ayarını gerçek proxy zincirine göre sınırlandırın; istemciden gelen X-Forwarded-* başlıklarına koşulsuz güvenmeyin.

Dağıtım, hata teşhisi ve kaynak planlaması

Yeni sürümü ayrı bir yayın dizinine hazırlayıp test etmek, çalışan dosyaların üzerine parça parça yazmaktan daha yönetilebilirdir. Bu basit tek süreçli modelde systemctl restart kısa kesinti yaratabilir. Veritabanı şeması değişikliklerinde eski uygulamaya dönüşün de uyumlu olduğunu doğrulayın; yalnız kodu geri almak her zaman yeterli değildir.

• Yayın öncesi uygulama ve veri yedeklerini alın; geri yüklemeyi ayrı ortamda deneyin.
• Kodda veya herkese açık depoda sır saklamayın. Gerçek uygulamada sır yönetimini servis yetkileriyle birlikte planlayın.
• Günlük boyutunu, hata oranını, RAM ve disk kullanımını izleyin. SSH oturumunun açık olması servis sağlığını kanıtlamaz.
• Paket seçerken API ile aynı VPS’de çalışan veritabanını ve eşzamanlı işleri hesaba katın.
• Bellek yetersizliğinde önce yükü ve sızıntı ihtimalini inceleyin; daha büyük paket her uygulama hatasını çözmez.