Wdrażanie witryny Hugo na AWS S3 za pomocą AWS CLI

Wdrażanie witryny statycznej Hugo na AWS S3 przy użyciu AWS CLI oferuje solidne, skalowalne rozwiązanie do hostowania Twojej witryny. Niniejszy przewodnik pokrywa pełny proces wdrażania, od początkowego ustawienia po zaawansowane automatyzacje i strategie zarządzania pamięcią podręczną.

Wdrażanie przy użyciu AWS CLI staje się coraz bardziej popularnym podejściem, ponieważ dystrybucja Hugo usunęła polecenie deploy z pakietu standardowego. Zobacz informacje na temat extended i withdeploy w Jak zainstalować Ubuntu 24.04 i przydatne narzędzia jeśli wdrażasz to lokalnie i nadal chcesz wywoływać hugo deploy.

Wymagania wstępne

Przed wdrożeniem swojej witryny Hugo na AWS S3 upewnij się, że masz:

• Gotową do wdrożenia witrynę Hugo (jeśli potrzebujesz pomocy w jej tworzeniu, sprawdź przewodnik szybkiego startu Hugo)
• Konto AWS z odpowiednimi uprawnieniami
• Zainstalowany i skonfigurowany AWS CLI
• Podstawowa wiedza na temat operacji wiersza poleceń

Budowanie swojej witryny Hugo

Pierwszym krokiem wdrażania witryny Hugo jest generowanie plików statycznych. Użyj Kartki z wskazówkami dla Hugo jako odniesienia do dostępnych poleceń i opcji.

Zbuduj swoją witrynę z flagami optymalizacji:

hugo --gc --minify

Flaga --gc usuwa nieużywane pliki cache, a --minify kompresuje Twoje HTML, CSS i JavaScript w celu optymalnej wydajności. To generuje Twoją witrynę statyczną w katalogu public/, który będzie wdrażany na S3.

Konfiguracja AWS CLI

Jeśli jeszcze nie skonfigurowałeś AWS CLI, uruchom:

aws configure

Zostaniesz poproszony o wprowadzenie:

• AWS Access Key ID: Twój klucz dostępu AWS
• AWS Secret Access Key: Twój tajny klucz dostępu AWS
• Domyślny region: Twój preferowany region AWS (np. us-east-1, ap-southeast-2)
• Domyślny format wyjścia: json (zalecany)

Dla dostępu programistycznego upewnij się, że Twój użytkownik IAM ma uprawnienia do:

• s3:PutObject
• s3:GetObject
• s3:DeleteObject
• s3:ListBucket
• cloudfront:CreateInvalidation (jeśli używasz CloudFront)

Tworzenie i konfigurowanie bazy danych S3

Tworzenie bazy danych

Utwórz swoją bazę danych S3 za pomocą AWS CLI:

aws s3 mb s3://your-bucket-name --region us-east-1

Ważne: Wybierz unikalną globalnie nazwę bazy danych. Jeśli planujesz użycie bazy danych do hostowania witryny, nazwa bazy danych musi odpowiadać nazwie swojej domeny, jeśli używasz domeny niestandardowej.

Konfiguracja bazy danych do hostowania witryny statycznej

Włącz hostowanie witryny statycznej:

aws s3 website s3://your-bucket-name \
  --index-document index.html \
  --error-document 404.html

Ustawienie polityki bazy danych

Dla dostępu do odczytu przez wszystkich (jeśli nie używasz CloudFront), utwórz politykę bazy danych:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::your-bucket-name/*"
    }
  ]
}

Zastosuj politykę:

aws s3api put-bucket-policy \
  --bucket your-bucket-name \
  --policy file://bucket-policy.json

Uwaga bezpieczeństwa: Jeśli używasz CloudFront (zalecane), możesz ograniczyć dostęp do bazy danych S3 tylko do CloudFront, eliminując potrzebę dostępu do odczytu przez wszystkich.

Wdrażanie na S3 przy użyciu AWS CLI

Głównym poleceniem wdrażania jest użycie aws s3 sync do przekazania Twojej witryny:

aws s3 sync public/ s3://your-bucket-name/ \
  --delete \
  --cache-control max-age=60

Wyjaśnienie kluczowych parametrów

• public/: Lokalny katalog wyjściowy Hugo
• s3://your-bucket-name/: Cel wdrażania na S3
• --delete: Usuwa pliki na S3, które nie istnieją lokalnie, zapewniając, że Twój koszyna będzie lustrzane odbicie Twojego buildu
• --cache-control max-age=60: Ustawia nagłówki pamięci podręcznej (60 sekund w tym przykładzie)

Zaawansowane opcje synchronizacji

Dla większego kontroli nad wdrażaniem:

aws s3 sync public/ s3://your-bucket-name/ \
  --delete \
  --cache-control "public, max-age=31536000, immutable" \
  --exclude "*.html" \
  --cache-control "public, max-age=60" \
  --include "*.html" \
  --exclude "*.js" \
  --cache-control "public, max-age=31536000, immutable" \
  --include "*.js"

Ten przykład ustawia różne trwałości pamięci podręcznej dla plików HTML (60 sekund) w porównaniu do statycznych zasobów takich jak JavaScript (1 rok), co jest typową strategią optymalizacji.

Konfiguracja dystrybucji CloudFront

Choć S3 może hostować witryny statyczne bezpośrednio, użycie Amazon CloudFront jako CDN oferuje lepszą wydajność, bezpieczeństwo i globalne rozdysponowanie.

Tworzenie dystrybucji CloudFront

aws cloudfront create-distribution \
  --distribution-config file://cloudfront-config.json

Podstawowa konfiguracja CloudFront zawiera:

• Bazę danych S3 jako źródło
• Domyślne zachowania pamięci podręcznej
• Certyfikat SSL/TLS (z AWS Certificate Manager)
• Konfiguracja domeny niestandardowej (opcjonalnie)

Strategie zarządzania pamięcią podręczną

Podczas wdrażania przez CloudFront rozważ następujące strategie pamięci podręcznej:

1. Ustaw maksymalny TTL: Skonfiguruj maksymalny TTL CloudFront, aby kontrolować, jak długo zawartość jest przechowywana w lokalizacjach krawędzi
2. Wersjonowanie zawartości: Użyj identyfikatorów wersji w nazwach plików (np. style-v2.css), aby wymusić aktualizację pamięci podręcznej
3. Nagłówki Cache-Control: Ustaw odpowiednie nagłówki podczas synchronizacji S3 (jak pokazano powyżej)
4. Wybiórcze usuwanie pamięci podręcznej: Usuń tylko zmienione ścieżki zamiast całej pamięci podręcznej

Usuwanie pamięci podręcznej (invalidation)

Po wdrożeniu aktualizacji usuń pamięć podręczną CloudFront, aby dostarczyć świeżą zawartość:

aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/*"

Dla bardziej celowego usuwania pamięci podręcznej:

aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/index.html" "/blog/*"

Uwaga dotycząca kosztów: Pierwsze 1000 ścieżek usuwania pamięci podręcznej na miesiąc są darmowe. Po tym koszt każdej ścieżki wynosi 0,005 dolarów. Używaj wybiórczego usuwania pamięci podręcznej, aby minimalizować koszty.

Automatyzacja przy użyciu CI/CD

Ręczne wdrażanie działa dla małych projektów, ale automatyzacja jest kluczowa dla produkcji. Możesz zintegrować ten proces wdrażania z Gitea Actions do wdrażania witryny Hugo na AWS S3 lub podobnymi potokami CI/CD.

Prosty skrypt wdrażania

Utwórz prosty skrypt wdrażania:

#!/bin/bash
set -e

# Budowanie witryny Hugo
echo "Budowanie witryny Hugo..."
hugo --gc --minify

# Wdrażanie na S3
echo "Wdrażanie na S3..."
aws s3 sync public/ s3://your-bucket-name/ \
  --delete \
  --cache-control max-age=60

# Usuwanie pamięci podręcznej CloudFront
echo "Usuwanie pamięci podręcznej CloudFront..."
aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/*"

echo "Wdrażanie zakończone!"

Zrób go wykonywalnym i uruchom:

chmod +x deploy.sh
./deploy.sh

Przykład działania GitHub Actions

Dla repozytoriów GitHub, utwórz .github/workflows/deploy.yml:

name: Deploy to AWS S3

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
      
      - name: Build
        run: hugo --gc --minify
      
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1
      
      - name: Deploy to S3
        run: |
          aws s3 sync public/ s3://your-bucket-name/ \
            --delete \
            --cache-control max-age=60          
      
      - name: Invalidate CloudFront
        run: |
          aws cloudfront create-invalidation \
            --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
            --paths "/*"          

Monitorowanie i optymalizacja

Włączanie dzienników

Skonfiguruj dzienniki S3 i CloudFront, aby śledzić wzorce dostępu:

# Włączanie dzienników dostępu do S3
aws s3api put-bucket-logging \
  --bucket your-bucket-name \
  --bucket-logging-status file://logging.json

Ustawianie alarmów CloudWatch

Monitoruj swoje wdrażanie przy użyciu CloudWatch:

aws cloudwatch put-metric-alarm \
  --alarm-name high-error-rate \
  --alarm-description "Ostrzeżenie o wysokim poziomie błędów" \
  --metric-name 4xxError \
  --namespace AWS/CloudFront \
  --statistic Sum \
  --period 300 \
  --threshold 10 \
  --comparison-operator GreaterThanThreshold

Rozwiązywanie typowych problemów

Pliki nie aktualizują się

Jeśli zmiany nie pojawiają się:

1. Sprawdź status usuwania pamięci podręcznej CloudFront
2. Zweryfikuj, czy użyto flagi --delete w poleceniu synchronizacji
3. Wyczyść pamięć podręczną przeglądarki lub przetestuj w trybie incognito
4. Sprawdź uprawnienia do bazy danych S3

Wolne wdrażanie

Optymalizuj wydajność synchronizacji:

• Użyj --exclude i --include, aby pominąć niepotrzebne pliki
• Rozważ użycie --size-only do szybszych porównań
• Użyj równoległych przesyłania plików z --cli-read-timeout i --cli-write-timeout

Błędy uprawnień

Upewnij się, że Twój użytkownik IAM ma:

• Uprawnienia do dostępu do bazy danych S3
• Uprawnienia do usuwania pamięci podręcznej CloudFront (jeśli stosowne)
• Poprawnie skonfigurowane polityki bazy danych

Podsumowanie najlepszych praktyk

1. Zawsze używaj --delete, aby utrzymać S3 zsynchronizowany z lokalnym buildem
2. Ustaw odpowiednie nagłówki pamięci podręcznej na podstawie typów plików
3. Używaj CloudFront do wdrażania w środowisku produkcyjnym
4. Automatyzuj wdrażanie przy użyciu potoków CI/CD
5. Monitoruj koszty – zwróć uwagę na opłaty za usuwanie pamięci podręcznej CloudFront
6. Wersjonuj wdrażania – dodawaj tagi do wersji dla łatwego powrotu do poprzedniej wersji
7. Testuj lokalnie najpierw – potwierdź swoje wdrażanie Hugo przed publikacją

Powiązane zasoby

Aby uzyskać więcej szczegółowych informacji na temat wdrażania Hugo, sprawdź komprehensywny przewodnik dotyczący wdrażania witryny wygenerowanej przez Hugo na AWS S3, który obejmuje dodatkowe opcje i konfiguracje wdrażania.

Pamiętaj, aby używać odpowiednich bloków kodu Markdown do przykładów kodu i odnosić się do Kompleksowego arkusza z wskazówkami dla Markdown dla wytycznych formatowania.

Przydatne linki

• Wdrażanie witryny wygenerowanej przez Hugo na AWS S3
• Użycie Gitea Actions do wdrażania witryny Hugo na AWS S3
• Kartka z wskazówkami dla Hugo
• Kompleksowy arkusz z wskazówkami dla Markdown
• Użycie bloków kodu Markdown

Zewnętrzne odniesienia

• Dokumentacja AWS S3 Static Website Hosting
• AWS CLI S3 Command Reference
• Najlepsze praktyki dotyczące kontroli pamięci podręcznej CloudFront
• Oficjalna dokumentacja Hugo
• Przewodnik po usuwaniu pamięci podręcznej CloudFront