Kurs NestJS · Moduł 9: Deployment i infrastruktura
Blue-Green Deployment i Zero-Downtime - sztuka bezprzerwowej zmiany warty
W tej lekcji6
Mistrzu strategii! Senator Cicero powiada: „Imperium nigdy nie śpi, a drogi muszą być zawsze otwarte”. Tymczasem każde wdrożenie oznacza pół minuty błędów 502, bo stary proces już zgasł, a nowy jeszcze nie wstał. Rzymskie legiony zmieniały wartę bez pozostawiania murów bez obrony - aplikacje też muszą aktualizować się bez przerw w działaniu.
Blue-Green Deployment to technika, w której utrzymujemy dwa identyczne środowiska produkcyjne (blue i green). W danym momencie tylko jedno obsługuje ruch, a drugie przyjmuje nową wersję. Przełączenie następuje natychmiast, bez przestojów.
Koncepcja Blue-Green Deployment
Wyobraź sobie dwie bramy miasta. Blue jest otwarta i obsługuje podróżnych, a w green strażnicy montują nowe fortyfikacje. Gdy green jest gotowa, ruch przechodzi na nią. Konfigurację obu slotów opisują dwa interfejsy:
// src/deployment/blue-green.config.ts
interface DeploymentSlot {
name: 'blue' | 'green';
port: number;
version: string;
status: 'active' | 'standby' | 'deploying';
healthCheckUrl: string;
startedAt: Date;
}
interface BlueGreenConfig {
activeSlot: 'blue' | 'green';
slots: {
blue: DeploymentSlot;
green: DeploymentSlot;
};
loadBalancerUrl: string;
healthCheckInterval: number; // ms
healthCheckRetries: number;
rollbackTimeout: number; // ms
}
const deploymentConfig: BlueGreenConfig = {
activeSlot: 'blue',
slots: {
blue: {
name: 'blue',
port: 3001,
version: '2.3.0',
status: 'active',
healthCheckUrl: 'http://blue.imperium.internal:3001/health',
startedAt: new Date(),
},
green: {
name: 'green',
port: 3002,
version: '2.4.0',
status: 'standby',
healthCheckUrl: 'http://green.imperium.internal:3002/health',
startedAt: new Date(),
},
},
loadBalancerUrl: 'http://lb.imperium.internal',
healthCheckInterval: 5000,
healthCheckRetries: 3,
rollbackTimeout: 30000,
};activeSlot wskazuje bramę z ruchem, a przełączenie to zmiana celu w load balancerze. Rollback polega na przełączeniu z powrotem, bo stara wersja wciąż działa. Ceną są podwójne zasoby, a długie połączenia, np. WebSocket, trzeba świadomie przenieść.
Rolling Updates
Rolling update stopniowo zastępuje stare instancje nowymi, jak zmiana warty centurionów, dzięki czemu część instancji zawsze obsługuje ruch:
// src/deployment/rolling-update.service.ts
import { Injectable, Logger } from '@nestjs/common';
interface Instance {
id: string;
version: string;
status: 'running' | 'updating' | 'ready' | 'failed';
port: number;
}
@Injectable()
export class RollingUpdateService {
private readonly logger = new Logger(RollingUpdateService.name);
async performRollingUpdate(
instances: Instance[],
newVersion: string,
maxUnavailable: number = 1,
): Promise<void> {
this.logger.log(
`Rozpoczynam rolling update do wersji ${newVersion}`
);
this.logger.log(
`Instancje: ${instances.length}, max niedostępnych: ${maxUnavailable}`
);
// Aktualizuj instancje partiami - cała partia naraz
for (let i = 0; i < instances.length; i += maxUnavailable) {
const batch = instances.slice(i, i + maxUnavailable);
const results = await Promise.all(
batch.map((instance) => this.updateInstance(instance, newVersion)),
);
// Nieudana instancja zatrzymuje cały rollout
if (results.includes(false)) {
throw new Error(`Rolling update do wersji ${newVersion} zatrzymany`);
}
}
}Promise.all aktualizuje całą partię naraz. Pierwsza wersja miała pętlę z await wewnątrz partii, więc mimo parametru maxUnavailable zawsze wyłączała jedną instancję. Nieudana instancja zatrzymuje teraz cały rollout, zamiast psuć kolejne - w teście z sześcioma instancjami dwie ostatnie zostały nietknięte.
Każda instancja przechodzi pięć kroków w stałej kolejności:
private async updateInstance(instance: Instance, newVersion: string): Promise<boolean> {
instance.status = 'updating';
this.logger.log(`Aktualizuję instancję ${instance.id}...`);
// 1. Wyłącz instancję z load balancera
await this.removeFromLoadBalancer(instance);
// 2. Poczekaj aż bieżące requesty się zakończą
await this.drainConnections(instance);
// 3. Zaktualizuj do nowej wersji
await this.deployNewVersion(instance, newVersion);
// 4. Sprawdź health check
const healthy = await this.waitForHealthy(instance);
if (healthy) {
instance.status = 'running';
instance.version = newVersion;
// 5. Dodaj instancję z powrotem do load balancera
await this.addToLoadBalancer(instance);
this.logger.log(`Instancja ${instance.id} zaktualizowana`);
return true;
}
instance.status = 'failed';
this.logger.error(
`Instancja ${instance.id} - rollback!`
);
await this.rollback(instance);
return false;
}Instancja znika z load balancera, oddaje trwające żądania, dostaje nową wersję, przechodzi health check i dopiero wtedy wraca do puli.
Metody pomocnicze to szkielet do podłączenia pod Twoją infrastrukturę:
private async removeFromLoadBalancer(instance: Instance) {
// Usuń instancję z puli load balancera
}
private async drainConnections(instance: Instance) {
// Poczekaj aż aktywne połączenia się zakończą (graceful)
}
private async deployNewVersion(
instance: Instance, version: string
) {
// Wdrożenie nowej wersji na instancji
}
private async waitForHealthy(instance: Instance): Promise<boolean> {
const maxRetries = 10;
for (let i = 0; i < maxRetries; i++) {
try {
// Sprawdź endpoint /health/ready nowej wersji
const response = await fetch(`http://localhost:${instance.port}/health/ready`, {
signal: AbortSignal.timeout(2000),
});
if (response.ok) return true;
} catch {
// Instancja jeszcze nie odpowiada
}
await new Promise(r => setTimeout(r, 2000)); // przerwa po każdej próbie
}
return false;
}
private async addToLoadBalancer(instance: Instance) {
// Dodaj instancję z powrotem do puli
}
private async rollback(instance: Instance) {
// Przywróć poprzednią wersję i dodaj instancję z powrotem do puli
}
}waitForHealthy() odpytuje /health/ready z limitem czasu i czeka po każdej próbie. Pierwsza wersja czekała tylko po wyjątku, więc dziesięć nieudanych odpowiedzi mijało w ułamku sekundy.
Health Check-based Deployment
Health checki to zwiadowcy Imperium - sprawdzają, czy nowa fortyfikacja jest gotowa, zanim otworzymy bramy:
// src/health/deployment-health.controller.ts
import { Controller, Get } from '@nestjs/common';
import {
HealthCheck, HealthCheckService,
MongooseHealthIndicator, MemoryHealthIndicator,
DiskHealthIndicator,
} from '@nestjs/terminus';
@Controller('health')
export class DeploymentHealthController {
constructor(
private health: HealthCheckService,
private mongoose: MongooseHealthIndicator,
private memory: MemoryHealthIndicator,
private disk: DiskHealthIndicator,
) {}
// Liveness - czy aplikacja żyje?
@Get('live')
@HealthCheck()
checkLiveness() {
return this.health.check([
() => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024),
]);
}
// Readiness - czy gotowa na ruch?
@Get('ready')
@HealthCheck()
checkReadiness() {
return this.health.check([
() => this.mongoose.pingCheck('mongodb'),
() => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024),
() => this.disk.checkStorage('disk', {
thresholdPercent: 0.9, path: '/',
}),
]);
}
// Startup - czy aplikacja wystartowała poprawnie?
@Get('startup')
@HealthCheck()
checkStartup() {
return this.health.check([
() => this.mongoose.pingCheck('mongodb'),
]);
}
}Liveness mówi, czy proces żyje, readiness - czy może przyjmować ruch, a startup - czy aplikacja poprawnie wstała. TerminusModule.forRoot({ gracefulShutdownTimeoutMs: 10000 }) domyka zero-downtime: po SIGTERM readiness zwraca 503 ze statusem shutting_down, a aplikacja jeszcze przez 10 sekund obsługuje ruch. W teście zwykłe endpointy odpowiadały w tym czasie 200, więc Kubernetes zdąży zabrać pod z puli.
Migracje bazy danych - zero-downtime
Migracje to najtrudniejszy element zero-downtime deployment, bo stary i nowy kod współistnieją z tą samą bazą. Zasada: migracja musi być kompatybilna wstecz. ALTER TABLE legions RENAME COLUMN name TO legion_name powoduje downtime, bo stary kod szuka name i pada. Bezpieczna zmiana nazwy pola to trzy wdrożenia. Pierwsze dodaje nowe pole:
// Migracja 1 (wdrożenie 1): dodaj nowe pole legion_name
import { Db } from 'mongodb';
export async function up(db: Db) {
await db.collection('legions').updateMany(
{},
[{ $set: { legion_name: '$name' } }]
);
// Stary kod dalej czyta 'name' - działa!
}Aktualizacja z potokiem kopiuje wartość name do legion_name w każdym dokumencie MongoDB, a stary kod niczego nie zauważa.
Drugie wdrożenie zmienia kod:
// Kod v2 (wdrożenie 2): zapisuj do obu pól
async updateLegion(id: string, name: string) {
await this.model.updateOne(
{ _id: id },
{ $set: { name, legion_name: name } }
);
}
// Czytaj z nowego pola
async getLegion(id: string) {
const doc = await this.model.findById(id);
return doc?.legion_name ?? doc?.name; // Fallback
}Kod v2 pisze do obu pól i czyta nowe, z powrotem do starego dla dokumentów, których migracja nie objęła.
Trzecie sprząta:
// Migracja 3 (po pełnym wdrożeniu v2): usuń stare pole
import { Db } from 'mongodb';
export async function up(db: Db) {
// Najpierw uzupełnij dokumenty zapisane przez stary kod w trakcie wdrożenia
await db.collection('legions').updateMany(
{ legion_name: { $exists: false } },
[{ $set: { legion_name: '$name' } }]
);
await db.collection('legions').updateMany(
{},
{ $unset: { name: '' } }
);
}Najpierw uzupełniamy dokumenty zapisane przez stary kod już po pierwszej migracji. Pierwsza wersja od razu usuwała name i w teście dokument dodany w trakcie wdrożenia stracił nazwę.
Feature Flags
Feature flagi to tajne rozkazy cesarza - włączają i wyłączają funkcje bez wdrażania nowego kodu:
// src/features/feature-flag.service.ts
import { Injectable } from '@nestjs/common';
interface FeatureFlag {
name: string;
enabled: boolean;
rolloutPercentage: number; // 0-100
allowedUsers: string[];
}
@Injectable()
export class FeatureFlagService {
private flags: Map<string, FeatureFlag> = new Map();
setFlag(flag: FeatureFlag) {
this.flags.set(flag.name, flag);
}
isEnabled(flagName: string, userId?: string): boolean {
const flag = this.flags.get(flagName);
if (!flag) return false;
// Flaga całkowicie wyłączona
if (!flag.enabled) return false;
// Użytkownik na liście dozwolonych (np. testerzy)
if (userId && flag.allowedUsers.includes(userId)) {
return true;
}
// Stopniowe wdrażanie (procentowy rollout)
if (flag.rolloutPercentage < 100) {
// Nazwa flagi w hashu - każda flaga losuje innych użytkowników
const hash = this.hashUserId(`${flagName}:${userId || 'anonymous'}`);
return (hash % 100) < flag.rolloutPercentage;
}
return true;
}
private hashUserId(userId: string): number {
let hash = 0;
for (let i = 0; i < userId.length; i++) {
hash = ((hash << 5) - hash) + userId.charCodeAt(i);
hash |= 0;
}
return Math.abs(hash);
}
}setFlag() dodałem, bo wcześniej mapy nic nie wypełniało. Nazwa flagi w hashu sprawia, że każda flaga wybiera innych użytkowników: bez niej w teście ci sami 20% użytkowników trafiało do każdego rolloutu. W produkcji flagi trzyma się w bazie albo w usłudze, np. Unleash.
Kontroler pyta serwis przy każdym żądaniu:
// Użycie w kontrolerze
@Controller('legions')
class LegionsController {
constructor(private features: FeatureFlagService) {}
@Get()
async getLegions(@Req() req) {
if (this.features.isEnabled('new-ranking-system', req.user?.id)) {
return this.getNewRanking();
}
return this.getOldRanking();
}
}Metody rankingów pominąłem, a req.user ustawia strażnik JWT.
PM2 Cluster Mode
PM2 w trybie cluster to jak rozmieszczenie wielu garnizonów - wykorzystuje wszystkie rdzenie CPU, restartuje procesy i przeładowuje je bez przestoju:
// ecosystem.config.cjs - konfiguracja PM2 (.cjs, bo projekt NestJS 12 to moduł ES)
module.exports = {
apps: [{
name: 'imperium-api',
script: 'dist/main.js',
instances: 'max', // Użyj wszystkich rdzeni CPU
exec_mode: 'cluster', // Tryb klastrowy
autorestart: true,
watch: false,
max_memory_restart: '500M',
// Zero-downtime reload
wait_ready: true, // Czekaj na process.send('ready')
listen_timeout: 10000, // Max czas na gotowość
kill_timeout: 5000, // Czas na graceful shutdown
env_production: {
NODE_ENV: 'production',
PORT: 3000,
},
}],
};Plik ma rozszerzenie .cjs, bo module.exports nie zadziała w projekcie z "type": "module". wait_ready każe czekać na sygnał gotowości (domyślnie 3 s, tu listen_timeout 10 s), a kill_timeout zastępuje domyślne 1,6 s na zamknięcie.
Sygnał gotowości wysyła main.ts:
// W main.ts - sygnalizacja gotowości
async function bootstrap() {
const app = await NestFactory.create(AppModule);
app.enableShutdownHooks(); // PM2 zatrzymuje proces sygnałem SIGINT
await app.listen(3000);
// Powiadom PM2 że aplikacja jest gotowa
if (process.send) {
process.send('ready');
}
}PM2 zatrzymuje procesy sygnałem SIGINT, który enableShutdownHooks() zamienia w porządny odwrót. process.send istnieje tylko wtedy, gdy proces ma kanał IPC do PM2.
Komendy PM2 dla zero-downtime:
# Start z pliku konfiguracyjnego (.cjs trzeba podać wprost)
pm2 start ecosystem.config.cjs --env production
# Reload bez downtime (graceful)
pm2 reload imperium-api
# Status instancji
pm2 status
# Monitorowanie w czasie rzeczywistym
pm2 monitpm2 reload w trybie cluster restartuje procesy po kolei, więc zawsze któryś obsługuje ruch.
Blue-green, rolling updates i feature flagi to potężne narzędzia w arsenale każdego architekta Imperium. Polecam Ci zaczynać od rolling update z dobrymi sondami, a blue-green zostawić dla systemów, w których rollback musi być natychmiastowy.
Pamiętaj: wartę zmienia się tak, żeby mur ani przez chwilę nie stał pusty.
Kod do tej lekcji: src/blue-green-deployment.ts
// Blue-Green Deployment i Zero-Downtime
// Strategie wdrazania bez przestojow
// 1. Konfiguracja Blue-Green
interface DeploymentSlot {
name: 'blue' | 'green';
port: number;
version: string;
status: 'active' | 'standby' | 'deploying';
}
const slots: Record<string, DeploymentSlot> = {
blue: {
name: 'blue',
port: 3001,
version: '2.3.0',
status: 'active',
},
green: {
name: 'green',
port: 3002,
version: '2.4.0',
status: 'standby',
},
};
// 2. Health Check Controller
// @Controller('health')
// class HealthController {
// @Get('live')
// liveness() { return { status: 'ok' }; }
//
// @Get('ready')
// readiness() {
// // TODO: Sprawdz MongoDB, pamiec, dysk
// }
// }
// 3. Feature Flag Service
class FeatureFlagService {
private flags = new Map<string, { enabled: boolean; rollout: number }>();
isEnabled(flag: string, userId?: string): boolean {
const f = this.flags.get(flag);
if (!f || !f.enabled) return false;
if (f.rollout < 100 && userId) {
// TODO: Implementuj canary release
// Uzyj hash userId % 100 < rollout
}
return true;
}
}
// 4. PM2 Cluster Config
// ecosystem.config.js:
// {
// name: 'imperium-api',
// script: 'dist/main.js',
// instances: 'max',
// exec_mode: 'cluster',
// wait_ready: true,
// listen_timeout: 10000,
// }
// TODO: Zaimplementuj pelny serwis rolling update
// TODO: Dodaj strategie migracji bazy danych (3 kroki)
// TODO: Skonfiguruj PM2 z graceful shutdown
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Blue-Green Deployment polega na:
Zadania praktyczne w grze
- Edytor kodu
Stwórz FeatureFlagService z metodą isEnabled obsługującą rolloutPercentage oraz interfejs DeploymentSlot dla blue-green
- Układanie w pionie
Uporządkuj kroki rolling update dla pojedynczej instancji:
- Edytor kodu
Stwórz plik .github/workflows/deploy.yml z jobami: test, build, deploy uruchamianymi na push do main
- Klikanie w kolejności
Ułóż poprawną kolejność kroków w kompletnym CI/CD pipeline:
- Układanie w pionie
Ułóż poprawny dekorator health check w kontrolerze NestJS:
- Edytor kodu
Stwórz konfigurację z Joi schema walidującą DATABASE_URL, PORT, NODE_ENV i JWT_SECRET
- Klikanie w kolejności
Ułóż middleware bezpieczeństwa w zalecanej kolejności dodawania do main.ts:
Zadania po tej lekcji
- PytanieKoncepcja Blue-Green Deployment
- Zadanie z kodemPraktyka: Blue-Green i Feature Flags
- Ułóż w kolejnościEtapy rolling update
- Zadanie z kodemPraktyka: Kompletny deployment pipeline
- Kliknij w kolejnościKroki deployment pipeline
- Ułóż w kolejnościHealth check w konfiguracji produkcyjnej
- Zadanie z kodemPraktyka: Environment validation
- Kliknij w kolejnościKolejność hardening middleware NestJS
- Projekt do wysłaniaProjekt: Infrastruktura produkcyjna Imperium
- WideoPodsumowanie modułu