İlk API'nize tekrarlanabilir bir sürüm verin.

Küçük, kontrollü bir ortam hazırlayın

Bu yordam, systemd'li bir Linux sistemi, bir yönetici hesabı, zaten kurulu bir Node.js 24 LTS çalışma zamanı, curl ve Caddy'nin paketlenmiş sistem servisini hedefler. Önce kurulu sürümleri ve paket yollarını doğrulayın; Node'un sürüm sayfası desteklenen sürüm satırlarını tanımlar. Kurulum ve sağlayıcı provizyonu ayrı görevlerdir. Kontrol ettiğiniz bir makine kullanın ve test edilmiş bir SSH oturumu ile kurtarma yolunu hazır bulundurun. Adlar first-api ve /opt/first-api bu örneği oluşturmadan önce kullanılmamış olmalıdır.

HTTPS için ayrıca kontrol ettiğiniz bir alan adına, doğru A/AAAA kayıtlarına ve web trafiğini açığa çıkarma iznine ihtiyacınız vardır. api.example.com aşağıdaki ayrılmış bir örnektir: kendi ana bilgisayar adınızla değiştirin. Bu API kasıtlı olarak veritabanı, kimlik doğrulama veya müşteri verisi içermez. Tam bir ürünü veya test edilmiş bir OffVPS dağıtımını değil, tekrarlanabilir bir süreci gösterir.

Çalışma zamanını doğrulayın ve bir sürüm oluşturun

command -v node &&
readlink -f "$(command -v node)" &&
node --version

Örneğin geri kalanı, doğrulanmış paylaşılan çalıştırılabilir dosyanın şu olduğunu varsayar: /usr/bin/node. Sizinki farklıysa, bu yolu her kontrolde ve ExecStartiçinde değiştirin. Giriş kullanıcınızın özel ev dizini içindeki bir çalışma zamanı, bir sistem servisi için otomatik olarak kullanılabilir değildir. Servis hesabını ve root'a ait bir sürüm dizinini oluşturun; beklenmedik bir mevcut hesap veya yol bulunursa durun.

sudo useradd --system --user-group --home-dir /opt/first-api \
  --shell /usr/sbin/nologin first-api &&
sudo install -d -o root -g root -m 0755 /opt/first-api/releases/001

Yönetici erişimiyle düzenleyicinizi kullanarak aşağıdakini şu adla kaydedin: /opt/first-api/releases/001/server.mjs, root'a ait ve servis kullanıcısı tarafından okunabilir. Sürüm yalnızca bu dosyayı içerir; paket bağımlılıkları veya sırlar yoktur.

import http from 'node:http';

const port = Number(process.env.PORT || 3000);
if (!Number.isInteger(port) || port < 1024 || port > 65535) {
  throw new Error('PORT must be an integer from 1024 to 65535');
}
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') {
    res.writeHead(405, { Allow: 'GET' });
    res.end(JSON.stringify({ error: 'method_not_allowed' }));
    return;
  }
  if (req.url === '/healthz') {
    res.writeHead(200);
    res.end(JSON.stringify({ status: 'ok', release: '001' }));
  } else if (req.url === '/api/message') {
    res.writeHead(200);
    res.end(JSON.stringify({ message: 'A small app, running clearly.' }));
  } else {
    res.writeHead(404);
    res.end(JSON.stringify({ error: 'not_found' }));
  }
});
server.requestTimeout = 10000;
server.headersTimeout = 10000;
server.keepAliveTimeout = 5000;
server.listen(port, '127.0.0.1');
process.on('SIGTERM', () => {
  server.close(() => process.exit(0));
  setTimeout(() => process.exit(1), 10000).unref();
});

Açık loopback adresi, API dinleyicisini sunucunun kendisinde tutar. Caddy onun genel giriş noktası olacaktır. Node HTTP API istek işleme, zaman aşımları ve sunucu kapatmayı belgeler. Dosyayı, gerçekten yürütecek hesap olarak kontrol edin:

sudo -u first-api /usr/bin/node --check /opt/first-api/releases/001/server.mjs

Sürece bir servis tanımı verin

Kaydedin /etc/systemd/system/first-api.service şu içerikle:

[Unit]
Description=First API learning release
After=network.target
StartLimitIntervalSec=60
StartLimitBurst=5

[Service]
Type=simple
User=first-api
Group=first-api
WorkingDirectory=/opt/first-api/releases/001
ExecStart=/usr/bin/node /opt/first-api/releases/001/server.mjs
Environment=NODE_ENV=production
Environment=PORT=3000
Restart=on-failure
RestartSec=5
TimeoutStopSec=15
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true

[Install]
WantedBy=multi-user.target

Birim, tek bir özel kullanıcı, açık bir çalıştırılabilir dosya ve sürümlenmiş bir çalışma dizini kullanır. Otomatik kurtarma hız sınırlıdır; kasıtlı bir servis durdurması Restart=on-failuretetiklemez. Bkz. systemd.service. Dosya sistemi kısıtlamaları bu salt okunur API'ye uygundur; veri yazan bir uygulama kasıtlı olarak kapsamlandırılmış yazılabilir depolamaya ihtiyaç duyar. Sırlar bu ortam satırlarına ait değildir. Bkz. systemd yürütme ayarları.

sudo systemd-analyze verify /etc/systemd/system/first-api.service &&
sudo systemctl daemon-reload &&
sudo systemctl start first-api.service &&
sudo systemctl status first-api.service --no-pager &&
curl --fail --show-error http://127.0.0.1:3000/healthz

Bu && korumaları, bir komut başarısız olduğunda yapıştırılan diziyi durdurur. Başlatmadan önce doğrulama uyarılarını çözün ve başarısız bir kontrolden sonra bir sonraki bloğa geçmeyin. Birim doğrulaması söz dizimi ve çalıştırılabilir dosya sorunlarını yakalayabilir, ancak başarılı bir kontrol çalışan bir uygulamanın kanıtı değildir. Beklenen sağlık yanıtı {"status":"ok","release":"001"}. Başarısız olursa, tekrar tekrar yeniden başlatmadan önce sudo journalctl -u first-api.service -n 50 --no-pager inceleyin.

Yerel kontrolün ardından HTTPS rotasını ekleyin

Mevcut Caddy yapılandırmasını kullanılmayan bir dosya adı altında yedekleyin. İlgili olmayan siteleri değiştirmeden şu bloğu ekleyin /etc/caddy/Caddyfile şuraya:

api.example.com {
    reverse_proxy 127.0.0.1:3000
}

Standart genel alan adı akışı için ana bilgisayar adı sunucuya çözümlenmelidir, 80/443 numaralı bağlantı noktaları Caddy'ye ulaşmalıdır ve Caddy'nin sertifika depolaması yazılabilir ve kalıcı kalmalıdır. Yayınlanan her A/AAAA rotasını kontrol edin. SSH erişimini bozmayın ve 3000 numaralı bağlantı noktasını özel tutun. Bu gereksinimler Caddy otomatik HTTPSkaynağından gelir; upstream söz dizimi şurada belgelenmiştir: reverse_proxy.

sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile &&
sudo systemctl reload caddy.service

Yalnızca başarılı doğrulamadan sonra yeniden yükleyin; caddy validate uyarlanmış yapılandırmayı kontrol eder. Paketlenmiş servis iş akışı şurada açıklanmıştır: Caddy'nin servis kılavuzu. Ayrı bir istemciden, gerçek ana bilgisayar adınızı kullanarak https://api.example.com/healthz isteyin. Sertifika kontrollerini atlamadan güvenilir bir TLS bağlantısı ve aynı sürüm yanıtını bekleyin. Ardından /api/message mesajını döndürdüğünü ve bilinmeyen bir yolun 404 döndürdüğünü doğrulayın.

Bilinen bir sürümü ve güvenli bir durma noktasını saklayın

Her iki kontrol de çalıştıktan sonra, API'yi gelecekteki açılışlar için şununla etkinleştirin: sudo systemctl enable first-api.service. Çalışma zamanı sürümünü, kaynak dosyayı, birimi ve Caddy yapılandırmasını kaydedin. Sonraki sürüm için yeni numaralı bir dizin oluşturun, servis kullanıcısı olarak söz dizimini kontrol edin, her iki birim yolunu güncelleyin, systemd'yi yeniden yükleyin ve API'yi yeniden başlatın. Yeni sürüm kabul edilene kadar önceki dizini koruyun.

Bu örneği durdurmak için şunu kullanın: sudo systemctl stop first-api.service. Bu rota yapılandırılmış kaldığı sürece Caddy bir upstream hatası bildirir; devre dışı bırakırken yalnızca bu rotayı kaldırın ve Caddy'yi doğrulayın/yeniden yükleyin. Başarısız bir kod sürümünü, önceki birim yollarını seçip kontrolleri yineleyerek geri alın. Daha sonraki bir veritabanı geçişi kendi kurtarma planına ihtiyaç duyar. Şununla devam edin: DNS'ten uygulamaya istek yolu veya bir uygulamanın neden durduğunu bulma.