Astro izvietošana VPS ar Nginx (Node.js adapteris)

Šī rokasgrāmata apraksta Astro vietnes izvietošanu VPS (Ubuntu 22.04 / 24.04), izmantojot oficiālo @astrojs/node standalone adapteru. Nginx darbojas kā reversā prokša serveris Node.js procesam, kuru PM2 uztur aktīvu pāri restartiem.

Priekšnosacījumi

• VPS ar Ubuntu 22.04 vai 24.04
• Domēna vārds, kas norāda uz servera IP
• Node.js 18.17 vai jaunāka versija instalēta serverī
• npm vai pnpm pieejams

---

1. Node.js adaptera konfigurēšana

Instalē adapteru Astro projektā:

npm install @astrojs/node

Atjauniniet astro.config.mjs, lai to izmantotu standalone režīmā:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',       // vai 'hybrid', ja tikai dažas lapas izmanto SSR
  adapter: node({
    mode: 'standalone',   // iekļauj Node.js HTTP serveri būvē
  }),
});

Tikai statiskas vietnes: Ja Astro projektam nav serverpuses maršrutu, API galapunktu vai SSR lapu, vari izmantot output: 'static' un izlaist adapteru. Tādā gadījumā pārlec uz statisko sadaļu šīs rokasgrāmatas beigās.

---

2. Astro lietotnes būvēšana

Būvē lokāli pirms pārsūtīšanas uz serveri:

# Instalē atkarības
npm install

# Būvē ražošanai
npm run build

Būves rezultāts satur divas mapes:

• dist/client/ — statiskie resursi (JS, CSS, attēli)
• dist/server/ — Node.js servera pakotne un entry.mjs

---

3. Failu pārsūtīšana uz serveri

# No lokālā datora
scp -r dist package.json package-lock.json lietotajvards@servera-ip:/var/www/tava-astro-lietotne

Vispirms izveido mērķa mapi serverī, ja tā vēl nepastāv:

sudo mkdir -p /var/www/tava-astro-lietotne
sudo chown -R $USER:$USER /var/www/tava-astro-lietotne

---

4. Ražošanas atkarību instalēšana serverī

Pieslēdzies serverim ar SSH un instalē atkarības:

cd /var/www/tava-astro-lietotne
npm install --omit=dev

Pārbaudi, vai serveris pareizi startē:

node dist/server/entry.mjs

Vajadzētu redzēt izvadi Server listening on http://0.0.0.0:4321. Apstādini ar Ctrl+C — no šī brīža PM2 pārvaldīs procesu.

---

5. Nginx konfigurēšana kā reversā prokša serveri

Instalē Nginx, ja vēl nav izdarīts:

sudo apt update
sudo apt install nginx

Izveido vietnes konfigurāciju:

sudo nano /etc/nginx/sites-available/astro

Pievieno sekojošo (aizstāj yourdomain.com un portu, ja mainīts):

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;

    # Gzip saspiešana
    gzip on;
    gzip_comp_level 5;
    gzip_min_length 256;
    gzip_proxied any;
    gzip_vary on;
    gzip_types
        application/javascript
        application/json
        application/x-javascript
        application/xml
        image/svg+xml
        text/css
        text/javascript
        text/plain
        text/xml;

    # Ilgtermiņa kešatmiņa Astro hešotiem statiskiem resursiem
    location /_astro/ {
        proxy_pass http://localhost:4321/_astro/;
        expires 365d;
        access_log off;
        add_header Cache-Control "public, max-age=31536000, immutable";
    }

    # Visu pārējo nodod Node.js serverim
    location / {
        proxy_pass http://localhost:4321;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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_cache_bypass $http_upgrade;
    }
}

Aktivizē vietni, pārbaudi konfigurāciju un pārlādē Nginx:

sudo ln -s /etc/nginx/sites-available/astro /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

---

6. Lietotnes palaišana ar PM2

PM2 uztur Node.js procesu aktīvu un restartē to pēc servera pārstartēšanas:

# Instalē PM2 globāli
sudo npm install -g pm2

# Palaid Astro serveri
cd /var/www/tava-astro-lietotne
pm2 start dist/server/entry.mjs --name "astro-app"

# Saglabā procesu sarakstu un iestata startēšanas skriptu
pm2 startup
pm2 save

pm2 startup izvada komandu — nokopē un izpildi to, lai reģistrētu PM2 ar systemd.

Noderīgas PM2 komandas:

pm2 status           # Uzskaitīt visus darbojošos procesus
pm2 logs astro-app   # Straumēt žurnālus
pm2 restart astro-app
pm2 stop astro-app

---

7. SSL iestatīšana ar Let’s Encrypt

Instalē Certbot un iegūsti sertifikātu:

sudo apt install certbot python3-certbot-nginx

sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

Certbot automātiski modificēs Nginx konfigurāciju, lai novirzītu HTTP uz HTTPS un konfigurētu sertifikātu. Pārbaudi automātiskās atjaunošanas statusu:

sudo systemctl status certbot.timer

---

Porta maiņa

Pēc noklusējuma Node.js adapteris klausās uz porta 4321. Lai mainītu, iestati PORT un HOST vides mainīgos pirms procesa palaišanas:

# Caur PM2
pm2 start dist/server/entry.mjs --name "astro-app" -- --env PORT=8080,HOST=127.0.0.1

# Vai caur PM2 ekosistēmas konfigurāciju (sīkāk PM2 rokasgrāmatā)

Atjaunini proxy_pass portu Nginx konfigurācijā, lai tas atbilstu.

---

Statiska izvietošana (bez SSR)

Ja Astro projekts izmanto output: 'static', būve rada tikai dist/ mapi ar statiskiem failiem. Izlaid Node.js adapteru un apkalpo failus tieši no Nginx:

# Pārsūti tikai dist mapi
scp -r dist/* lietotajvards@servera-ip:/var/www/yourdomain.com/html/

Nginx konfigurācija statiskiem failiem:

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    root /var/www/yourdomain.com/html;
    index index.html;

    gzip on;
    gzip_types text/css application/javascript image/svg+xml text/plain;

    location /_astro/ {
        expires 365d;
        add_header Cache-Control "public, max-age=31536000, immutable";
    }

    location / {
        try_files $uri $uri.html $uri/ =404;
    }

    error_page 404 /404.html;
}

Pēc tam palaid Certbot kā parasti. PM2 nav nepieciešams.

---

Svarīgas piezīmes

• Node.js versija: Serverī jābūt instalētam Node.js 18.17 vai jaunākai versijai.
• Vides mainīgie: Ražošanas noslēpumus iestati serverī, nevis repozitorijā. Eksportē tos pirms PM2 palaišanas vai izmanto .env failu, ko lasa lietotne.
• output: 'hybrid': Hibrīda režīms ļauj atsevišķas lapas atzīmēt ar prerender = true, kamēr citas paliek serverpusē renderētas. Adapteris un Nginx konfigurācija darbojas identiski kā pilnā server režīmā.
• Failu atļaujas: Pārliecinies, ka PM2 lietotājs var lasīt /var/www/tava-astro-lietotne.
• Ugunsmūris: Publiski jābūt pieejamiem tikai portiem 80 un 443. Ports 4321 nedrīkst būt tieši atklāts.

---

Bieži uzdotie jautājumi

Kāda ir atšķirība starp standalone un middleware adaptera režīmiem?

standalone režīmā tiek iekļauts pilns Node.js HTTP serveris — to palaižat tieši ar node dist/server/entry.mjs. middleware režīmā tiek eksportēts Express/Connect saderīgs apstrādātājs, ko iegulstat savā serverī. Lielākajai daļai VPS izvietojumu standalone ir vienkāršāks.

Vai man jāpārsūta node_modules uz serveri?

Nē. Pārsūti package.json, package-lock.json un dist/ mapi, pēc tam serverī palaid npm install --omit=dev. Tas saglabā pārsūtīšanas izmēru mazu un nodrošina, ka natīvie moduļi tiek kompilēti servera arhitektūrai.

Kā atjaunināt izvietojumu pēc koda izmaiņām?

Būvē lokāli, pārsūti jauno dist/ mapi uz serveri, pēc tam restartē PM2 procesu:

pm2 restart astro-app

Vai Astro un Next.js var darbināt vienā serverī?

Jā. Katrai lietotnei piešķir atšķirīgu portu (piemēram, 4321 un 3000) un katram domēnam izveido atsevišķu Nginx servera bloku. PM2 pārvalda abus procesus neatkarīgi.

Mani API galapunkti nedarbojas. Ko pārbaudīt?

Pārliecinies, ka output ir iestatīts uz 'server' vai 'hybrid' (ne 'static'), adapteris ir instalēts un atsauces uz to ir astro.config.mjs, un Nginx location / bloks novirza uz pareizo portu. Pārbaudi arī pm2 logs astro-app ražošanas kļūdas.