Nasazení do produkce

Kompletní průvodce nasazením CatCMS do produkce na globální edge platformě Cloudflare.[object Object]

Přehled[object Object]

CatCMS běží na globální edge síti Cloudflare a poskytuje:

• Cloudflare Workers - Serverless běhové prostředí ve více než 300 edge lokalitách
• D1 Database - Distribuovaná databáze založená na SQLite na okraji sítě
• R2 Object Storage - Úložiště kompatibilní s S3 pro mediální soubory
• KV Storage - Klíč-hodnota úložiště s nízkou latencí pro cachování
• Nulové studené starty - Okamžitá doba odezvy po celém světě

Architektura

┌─────────────────────────────────────────────────────────┐
│                   Cloudflare Edge                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   Workers    │  │  D1 Database │  │  R2 Storage  │  │
│  │  (Runtime)   │──│  (SQLite)    │  │   (Media)    │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│         │                                   │            │
│         └───────────── KV Cache ────────────┘            │
└─────────────────────────────────────────────────────────┘

Prostředí nasazení

CatCMS podporuje tři prostředí:

Předpoklady[object Object]

Požadované účty

1. Účet Cloudflare

   • Zaregistrujte se nadash.cloudflare.com/sign-up
   • Placený plán Workers (minimálně 5 $/měsíc)
   • Zadaná platební metoda

2. Název domény (volitelné, ale doporučené)

   • Lze použítworkers.dev subdoménu pro testování
   • Pro produkci se doporučuje vlastní doména

Požadované nástroje

Nainstalujte potřebné nástroje:

# Verify Node.js 18+ is installed
node --version  # Should be v18.0.0 or higher
npm --version

# Install Wrangler globally
npm install -g wrangler@latest
wrangler --version  # Should be v3.0.0 or higher

# Verify Git is installed
git --version

Přihlášení do Cloudflare

Ověřte se u svého účtu Cloudflare:

# Login to Cloudflare
wrangler login

# This will:
# 1. Open browser for authentication
# 2. Save credentials locally
# 3. Verify account access

# Verify login
wrangler whoami

Nastavení databáze[object Object]

Vytvořit produkční databázi

Vytvořte novou D1 databázi pro produkci:

# Create a new D1 database
wrangler d1 create catcms-ai

# Output example:

# ✅ Successfully created DB 'catcms-ai'

#

# [[d1_databases]]

# binding = "DB"

# database_name = "catcms-ai"

# database_id = "583c089c-1a4a-477d-9d58-06c07bf7c1d7"

# Copy the database ID and update wrangler.jsonc:

[[env.production.d1_databases]]
binding = "DB"
database_name = "catcms-ai"
database_id = "YOUR-DATABASE-ID-HERE"

Aplikovat databázové migrace

Aplikujte všechny databázové migrace na produkční prostředí:

# Apply migrations to production
npm run db:migrate:prod

# Manually with wrangler
wrangler d1 migrations apply DB --env production

# This will:
# 1. Read migration files from drizzle/migrations/
# 2. Apply them in order to production D1
# 3. Track applied migrations

Ověřit schéma databáze

Zkontrolujte, že byly vytvořeny všechny tabulky:

# List tables in production database
wrangler d1 execute catcms-ai --env production \
  --command="SELECT name FROM sqlite_master WHERE type='table';"

# Expected tables:
# - users
# - collections
# - content
# - content_versions
# - media
# - api_tokens
# - plugins
# - plugin_routes
# - plugin_hooks

Naplnit počáteční data

Vytvořte administrátorského uživatele a počáteční kolekce:

wrangler d1 execute catcms-ai --env production --command="
INSERT INTO users (id, email, username, first_name, last_name, role, is_active, created_at, updated_at)
VALUES (
  'admin-' || lower(hex(randomblob(16))),
  'admin@yourdomain.com',
  'admin',
  'Admin',
  'User',
  'admin',
  1,
  strftime('%s', 'now') * 1000,
  strftime('%s', 'now') * 1000
);
"

# Use a production seed script
wrangler d1 execute catcms-ai --env production \
  --file=./scripts/seed-production-content.sql

Nastavení úložiště R2[object Object]

Vytvořit R2 Bucket

Vytvořte R2 bucket pro ukládání médií:

# Create R2 bucket for production
wrangler r2 bucket create catcms-media-prod

# Verify creation

wrangler r2 bucket list

# Output:

# catcms-media-dev

# catcms-media-preview

# catcms-media-prod

# Add to wrangler.jsonc
[[env.production.r2_buckets]]
binding = "MEDIA_BUCKET"
bucket_name = "catcms-media-prod"

Konfigurace vlastní domény (volitelné)

Nastavte vlastní doménu pro veřejný přístup k médiím:

# In Cloudflare Dashboard:
# 1. Go to R2 > catcms-media-prod > Settings
# 2. Click "Connect Domain"
# 3. Enter: media.yourdomain.com
# 4. DNS records will be created automatically

# This allows public access to media files via:
# https://media.yourdomain.com/uploads/image.jpg

Organizace bucketu

Doporučená struktura složek:

catcms-media-prod/
├── uploads/          # User uploaded media
├── avatars/          # User avatar images
├── thumbnails/       # Generated thumbnails
├── documents/        # PDF and documents
└── temp/            # Temporary files (auto-cleanup)

Podporované typy souborů

• Obrázky: JPEG, PNG, GIF, WebP, SVG
• Dokumenty: PDF, TXT, DOC, DOCX
• Videa: MP4, WebM, OGG, AVI, MOV
• Audio: MP3, WAV, OGG, M4A
• Maximální velikost souboru: 50 MB

Nastavení KV Cache[object Object]

Vytvořit KV Namespace

Vytvořte KV namespace pro cachování:

# Create KV namespace for cache
wrangler kv:namespace create "CACHE_KV" --env production

# Output:

# ✅ Created namespace with id "7171ca98640e43b6b33dbff516a5a6cf"

# Create preview namespace
wrangler kv:namespace create "CACHE_KV" --env production --preview

# Output:
# ✅ Created preview namespace with id "aed99543752d438b8051a0b6809ced10"

# Add to wrangler.jsonc
[[env.production.kv_namespaces]]
binding = "CACHE_KV"
id = "7171ca98640e43b6b33dbff516a5a6cf"
preview_id = "aed99543752d438b8051a0b6809ced10"

Ověřit přístup ke KV

Otestujte přístup k KV namespace:

# List all KV namespaces
wrangler kv:namespace list

# Test write
wrangler kv:key put --binding CACHE_KV --env production "test" "Hello"

# Test read
wrangler kv:key get --binding CACHE_KV --env production "test"

# Delete test key
wrangler kv:key delete --binding CACHE_KV --env production "test"

Využití cache

Plugin pro cache používá KV pro:

• Cachování odpovědí API (TTL 5 min)
• Cachování metadat kolekcí (TTL 2 hodiny)
• Cachování obsahu (TTL 1 hodina)
• Statistiky administrátorského panelu (TTL 15 min)

Klíče cache se řídí vzorem:

cache:api:collections:all
cache:api:content-list:limit:50
cache:collection-content:blog-posts:limit:50

Proměnné prostředí[object Object]

Požadované tajné klíče (Secrets)

Nastavte požadované tajné klíče pro produkci:

# Generate and set JWT secret (required)
openssl rand -base64 32 | wrangler secret put JWT_SECRET --env production

# Set admin password (optional)
echo "your-secure-admin-password" | \
  wrangler secret put ADMIN_PASSWORD --env production

# Email service credentials (optional)
echo "your-sendgrid-api-key" | \
  wrangler secret put SENDGRID_API_KEY --env production

# Analytics/monitoring tokens (optional)
echo "your-sentry-dsn" | \
  wrangler secret put SENTRY_DSN --env production

Správa tajných klíčů

# List all secrets (names only, not values)
wrangler secret list --env production

# Update a secret
echo "new-value" | wrangler secret put SECRET_NAME --env production

# Delete a secret
wrangler secret delete SECRET_NAME --env production

Veřejné proměnné

Nakonfigurujte veřejné proměnné vwrangler.jsonc:

[env.production.vars]
ENVIRONMENT = "production"
# CDN_DOMAIN = "media.yourdomain.com"
# IMAGES_ACCOUNT_ID = "your-cloudflare-account-id"
# FEATURE_NEW_EDITOR = "true"

Pracovní postup nasazení[object Object]

Kontroly před nasazením

Před nasazením spusťte tyto kontroly:

# Run all tests
npm test

# Check TypeScript compilation
npm run build

# Verify migrations are up to date
wrangler d1 migrations list DB --env production

Nasadit do produkce

Nasaďte svou aplikaci:

# Option 1: Using predeploy script (runs tests + build)
npm run predeploy && npm run deploy

# Option 2: Direct deployment with Wrangler
wrangler deploy --env production

# Output:
# ✅ Successfully deployed to production
# URL: https://catcms-ai-prod.workers.dev
#
# Deployment details:
# - Version: 2024-01-15-abc123
# - Size: 2.4 MB
# - Upload time: 3.2s

Ověření po nasazení

Ověřte nasazení:

# Check API health
curl https://catcms-ai-prod.workers.dev/api/health

# Expected response:

# {

# "status": "healthy",

# "timestamp": "2024-01-15T12:00:00.000Z",

# "schemas": ["users", "collections", "content", ...]

# }

# Test API endpoints
curl https://catcms-ai-prod.workers.dev/api/collections

# Check admin panel
curl -I https://catcms-ai-prod.workers.dev/admin

Náhledové nasazení

Nejprve otestujte změny v náhledovém prostředí:

# Deploy to preview environment
wrangler deploy --env preview

# Output:
# ✅ Successfully deployed to preview
# URL: https://catcms-ai-preview.workers.dev

# Test the preview deployment
curl https://catcms-ai-preview.workers.dev/api/health

Zobrazit historii nasazení

# List recent deployments
wrangler deployments list --env production

# Output:
# Created       ID                          Version
# 2024-01-15    abc123def456                v1.2.3
# 2024-01-14    def456abc789                v1.2.2
# 2024-01-13    ghi789jkl012                v1.2.1

Vlastní domény[object Object]

Přidat vlastní doménu

Připojte svou vlastní doménu k Workeru:

Přes Cloudflare Dashboard

1. Přejděte naWorkers & Pages > catcms-ai-prod
2. Klikněte naSpouštěče záložku
3. Klikněte naPřidat vlastní doménu
4. Zadejte:yourdomain.com
5. Klikněte naPřidat vlastní doménu

Přes wrangler.jsonc

[env.production]
name = "catcms-ai-prod"
routes = [
  { pattern = "yourdomain.com/*", zone_name = "yourdomain.com" },
  { pattern = "www.yourdomain.com/*", zone_name = "yourdomain.com" }
]

Poté nasaďte:

wrangler deploy --env production

Konfigurace DNS

Cloudflare automaticky vytváří DNS záznamy. Ověřte pomocí:

# Check DNS propagation
dig yourdomain.com

# Or using nslookup
nslookup yourdomain.com

Ruční konfigurace DNS (v případě potřeby):

Type: AAAA
Name: @
Content: 100::
Proxy: Enabled (orange cloud)

SSL certifikát

SSL je s Cloudflare automatické:

1. Universal SSL - Vydává se automaticky
2. Edge certifikáty - Zdarma, automaticky obnovované
3. Full (Strict) - Doporučený režim šifrování

Ověřit SSL:

# Check certificate
curl -vI https://yourdomain.com 2>&1 | grep -i "ssl\|tls"

# Or use SSL checker
# https://www.ssllabs.com/ssltest/analyze.html?d=yourdomain.com

Vynutit HTTPS

Zajistěte, aby veškerý provoz používal HTTPS:

// In src/index.ts
app.use('*', async (c, next) => {
  const url = new URL(c.req.url)
  if (url.protocol === 'http:') {
    url.protocol = 'https:'
    return c.redirect(url.toString(), 301)
  }
  await next()
})

Kontrolní seznam pro produkci[object Object]

Použijte tento kontrolní seznam před spuštěním do ostrého provozu:

Infrastruktura

• [ ] Produkční D1 databáze vytvořena a migrována
• [ ] Produkční R2 bucket vytvořen
• [ ] Produkční KV namespace vytvořen
• [ ] Všechny vazby (bindings) nakonfigurovány v wrangler.jsonc
• [ ] Tajné klíče nahrány (JWT_SECRET atd.)
• [ ] Vlastní doména přidána a DNS nakonfigurováno
• [ ] SSL certifikát je aktivní a platný

Databáze

• [ ] Všechny migrace úspěšně aplikovány
• [ ] Počáteční data naplněna (uživatelé, kolekce)
• [ ] Administrátorský uživatel vytvořen s bezpečným heslem
• [ ] Databázové indexy ověřeny
• [ ] Strategie zálohování je zavedena

Aplikace

• [ ] Endpoint pro kontrolu stavu (health check) odpovídá
• [ ] API endpointy fungují správně
• [ ] Administrátorský panel je přístupný
• [ ] Autentizační systém funguje
• [ ] Funkčnost nahrávání médií otestována
• [ ] Systém cache je funkční

Bezpečnost

• [ ] HTTPS vynuceno (žádný přístup přes HTTP)
• [ ] Silný tajný klíč JWT nakonfigurován
• [ ] CORS správně nakonfigurován
• [ ] Bezpečnostní hlavičky nakonfigurovány
• [ ] Heslo administrátora je silné a jedinečné

Výkon

• [ ] Hlavičky pro cache nakonfigurovány
• [ ] Statické soubory komprimovány
• [ ] Databázové dotazy optimalizovány
• [ ] KV cache funguje správně
• [ ] CDN doména pro R2 nakonfigurována

Monitorování

• [ ] Logování chyb nakonfigurováno
• [ ] Monitorování výkonu povoleno
• [ ] Monitorování dostupnosti nastaveno
• [ ] Notifikace o výstrahách nakonfigurovány
• [ ] Zásady uchovávání logů nastaveny

Monitorování[object Object]

Logy v reálném čase

Zobrazte produkční logy v reálném čase:

# Tail production logs
wrangler tail --env production

# Filter by status
wrangler tail --env production --status error

# Filter by request method
wrangler tail --env production --method POST

# Sample rate (10%)
wrangler tail --env production --sampling-rate 0.1

Analytika Cloudflare

Přístup k analytice v dashboardu:

Workers & Pages > catcms-ai-prod > Analytika

Klíčové metriky:

• Požadavky - Celkový počet požadavků a chyb
• Úspěšnost - % úspěšných požadavků
• Doba trvání - Doby odezvy P50, P95, P99
• Čas CPU - Průměrné využití CPU
• Chyby - Počet a typy chyb

Monitorování kontroly stavu (Health Check)

Nastavte externí monitorování:

# Health check endpoint
GET https://yourdomain.com/api/health

# Expected response:
{
  "status": "healthy",
  "timestamp": "2024-01-15T12:00:00.000Z",
  "schemas": ["users", "collections", "content", "media", "plugins"]
}

Doporučené monitorovací služby:

• UptimeRobot - uptimerobot.com
• Pingdom - pingdom.com
• Better Uptime - betteruptime.com

Monitorování výkonu

Každá odpověď API obsahuje hlavičky výkonu:

X-Cache-Status: HIT
X-Cache-Source: memory
X-Cache-TTL: 278
X-Response-Time: 3ms

Postupy pro rollback[object Object]

Zobrazit historii nasazení

# List recent deployments
wrangler deployments list --env production

# Output:
# Created       ID                Version
# 2024-01-15    abc123            v1.2.3  (current)
# 2024-01-14    def456            v1.2.2
# 2024-01-13    ghi789            v1.2.1

Vrátit se k předchozí verzi

# Rollback to previous deployment
wrangler rollback --env production

# This will rollback to: v1.2.2

# Rollback to specific version
wrangler rollback \
  --message "Rolling back to v1.2.1" \
  --env production \
  --deployment-id ghi789

# Verify rollback
curl https://yourdomain.com/api/health

Rollback s databází

Pokud verze zahrnovala databázové migrace:

# 1. Export current database
wrangler d1 export catcms-ai --env production \
  --output backup-before-rollback.sql

# 2. Rollback Worker deployment
wrangler rollback --env production

# 3. Check which migrations to revert
wrangler d1 migrations list DB --env production

# Note: D1 doesn't have automatic down migrations
# Manual SQL required for schema changes

Nouzový skript pro rollback

#!/bin/bash
# emergency-rollback.sh

echo "Starting emergency rollback..."

# 1. Backup current state
echo "Creating backup..."
wrangler d1 export catcms-ai --env production \
  --output "emergency-backup-$(date +%Y%m%d-%H%M%S).sql"

# 2. Rollback deployment
echo "Rolling back deployment..."
wrangler rollback --env production

# 3. Verify health
echo "Verifying health..."
curl -f https://yourdomain.com/api/health || echo "❌ Health check failed"

echo "Rollback complete"

Řešení problémů[object Object]

Chyby připojení k databázi

# Error: D1_ERROR: no such table: users

# Apply migrations
wrangler d1 migrations apply DB --env production

# Verify tables exist
wrangler d1 execute catcms-ai --env production \
  --command="SELECT name FROM sqlite_master WHERE type='table';"

Tajné klíče (Secrets) nebyly nalezeny

# Error: Uncaught ReferenceError: JWT_SECRET is not defined

# List secrets
wrangler secret list --env production

# Add missing secret
echo "your-secret-value" | wrangler secret put JWT_SECRET --env production

Přístup k R2 bucketu odepřen

# Error: R2 bucket 'catcms-media-prod' not found

# Verify bucket exists
wrangler r2 bucket list

# Create if missing
wrangler r2 bucket create catcms-media-prod

# Verify binding in wrangler.jsonc
[[env.production.r2_buckets]]
binding = "MEDIA_BUCKET"
bucket_name = "catcms-media-prod"

Problémy s výkonem

Pomalé databázové dotazy

-- Add missing indexes
CREATE INDEX idx_content_status ON content (status);

CREATE INDEX idx_content_collection ON content (collection_id);

-- Analyze query performance
EXPLAIN QUERY PLAN
SELECT
  *
FROM
  content
WHERE
  status = 'published';

Cache nefunguje

# Verify cache headers
curl -I https://yourdomain.com/api/collections | grep -i cache

# Expected headers:
# X-Cache-Status: HIT
# X-Cache-Source: memory
# X-Cache-TTL: 278

Problémy s doménou a SSL

Chyby SSL certifikátu

# Check SSL status
curl -vI https://yourdomain.com 2>&1 | grep -i ssl

# Solutions:
# 1. Wait for certificate issuance (up to 24 hours)
# 2. Verify domain is proxied (orange cloud)
# 3. Check SSL/TLS mode is "Full (strict)"

Doména nesměruje provoz

# Verify DNS
dig yourdomain.com

# Check Worker routes
wrangler routes list

# Verify route in wrangler.jsonc

Získání pomoci

• Komunita Cloudflare - community.cloudflare.com
• Discord - discord.gg/cloudflaredev
• Dokumentace Cloudflare - developers.cloudflare.com/workers
• Problémy s CatCMS - github.com/catcms-app/catcms-app/issues

Další kroky

• Průvodce testováním - Otestujte své nasazení
• Dokumentace databáze - Pokročilé funkce databáze
• API reference - Reference API endpointů
• Cachování - Optimalizujte konfiguraci cache

Pro trvalou podporu navštivte našiKomunitní stránku.