Hugo-Website auf AWS S3 mit AWS CLI bereitstellen

Bereitstellung einer Hugo-Statik-Website auf AWS S3 mit der AWS CLI bietet eine robuste, skalierbare Lösung für die Hosting Ihrer Website. Diese Anleitung behandelt den gesamten Bereitstellungsprozess, von der anfänglichen Einrichtung bis zu fortgeschrittenen Automatisierungs- und Cache-Management-Strategien.

Die Bereitstellung mit der AWS CLI wird zur bevorzugten Methode, seit die Hugo-Distribution den deploy-Befehl aus dem Standardpaket entfernt hat. Siehe den Abschnitt über extended und withdeploy in Anleitung zur Installation von Ubuntu 24.04 & nützliche Tools, wenn Sie dies lokal durchführen und dennoch den Befehl hugo deploy aufrufen möchten.

Voraussetzungen

Bevor Sie Ihre Hugo-Website auf AWS S3 bereitstellen, stellen Sie sicher, dass Sie Folgendes haben:

• Eine Hugo-Website, die zur Bereitstellung bereit ist (falls Sie Hilfe bei der Erstellung benötigen, überprüfen Sie die Hugo Quickstart-Anleitung)
• AWS-Konto mit entsprechenden Berechtigungen
• Installierte und konfigurierte AWS CLI
• Grundkenntnisse in der Befehlszeilenoperation

Erstellen Ihrer Hugo-Website

Der erste Schritt bei der Bereitstellung Ihrer Hugo-Website besteht darin, die statischen Dateien zu generieren. Verwenden Sie die Hugo Cheat Sheet als Referenz für verfügbare Befehle und Optionen.

Erstellen Sie Ihre Website mit Optimierungsflags:

hugo --gc --minify

Der --gc-Flag entfernt nicht verwendete Cache-Dateien, während --minify Ihr HTML, CSS und JavaScript für optimale Leistung komprimiert. Dies generiert Ihre statische Website im Verzeichnis public/, das wir auf S3 bereitstellen werden.

Konfigurieren der AWS CLI

Falls Sie die AWS CLI noch nicht konfiguriert haben, führen Sie Folgendes aus:

aws configure

Sie werden aufgefordert, Folgendes einzugeben:

• AWS Access Key ID: Ihr AWS-Zugriffsschlüssel
• AWS Secret Access Key: Ihr geheimer Zugriffsschlüssel
• Standardregion: Ihre bevorzugte AWS-Region (z. B. us-east-1, ap-southeast-2)
• StandardausgabefORMAT: json (empfohlen)

Für den programmatischen Zugriff stellen Sie sicher, dass Ihr IAM-Benutzer Berechtigungen für Folgendes hat:

• s3:PutObject
• s3:GetObject
• s3:DeleteObject
• s3:ListBucket
• cloudfront:CreateInvalidation (falls CloudFront verwendet wird)

Erstellen und Konfigurieren des S3-Buckets

Erstellen des Buckets

Erstellen Sie Ihren S3-Bucket mit der AWS CLI:

aws s3 mb s3://Ihr-Bucket-Name --region us-east-1

Wichtig: Wählen Sie einen global eindeutigen Bucketsnamen. Wenn Sie den Bucket für die Website-Hosting verwenden möchten, muss der Bucketsname mit Ihrem Domainnamen übereinstimmen, wenn Sie eine benutzerdefinierte Domain verwenden.

Konfigurieren des Buckets für die statische Website-Hosting

Aktivieren Sie die statische Website-Hosting:

aws s3 website s3://Ihr-Bucket-Name \
  --index-document index.html \
  --error-document 404.html

Festlegen der Bucket-Richtlinie

Für öffentlichen Lesezugriff (falls CloudFront nicht verwendet wird), erstellen Sie eine Bucket-Richtlinie:

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

Wenden Sie die Richtlinie an:

aws s3api put-bucket-policy \
  --bucket Ihr-Bucket-Name \
  --policy file://bucket-policy.json

Sicherheitshinweis: Wenn Sie CloudFront verwenden (empfohlen), können Sie den Zugriff auf den S3-Bucket auf CloudFront beschränken und den öffentlichen Lesezugriff eliminieren.

Bereitstellen auf S3 mit der AWS CLI

Der Kernbereitstellungsbefehl verwendet aws s3 sync, um Ihre Website hochzuladen:

aws s3 sync public/ s3://Ihr-Bucket-Name/ \
  --delete \
  --cache-control max-age=60

Wichtige Parameter erklärt

• public/: Ihr lokales Hugo-Ausgabeverzeichnis
• s3://Ihr-Bucket-Name/: Ihr S3-Bucket-Ziel
• --delete: Entfernt Dateien in S3, die lokal nicht vorhanden sind, und stellt sicher, dass Ihr Bucket Ihr Build spiegelt
• --cache-control max-age=60: Setzt Cache-Header (60 Sekunden in diesem Beispiel)

Fortgeschrittene Sync-Optionen

Für mehr Kontrolle über Ihre Bereitstellung:

aws s3 sync public/ s3://Ihr-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"

Dieses Beispiel setzt unterschiedliche Cache-Dauern für HTML-Dateien (60 Sekunden) im Vergleich zu statischen Assets wie JavaScript (1 Jahr), was eine häufige Optimierungsstrategie ist.

Einrichtung der CloudFront-Verteilung

Während S3 statische Websites direkt hosten kann, bietet die Verwendung von Amazon CloudFront als CDN eine bessere Leistung, Sicherheit und globale Verteilung.

Erstellen der CloudFront-Verteilung

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

Eine grundlegende CloudFront-Konfiguration umfasst:

• S3-Bucket als Ursprung
• Standard-Cache-Verhaltensweisen
• SSL/TLS-Zertifikat (von AWS Certificate Manager)
• Konfiguration der benutzerdefinierten Domain (optional)

Cache-Management-Strategien

Bei der Bereitstellung über CloudFront sollten Sie diese Caching-Strategien in Betracht ziehen:

1. Set Maximum TTL: Konfigurieren Sie den Maximum TTL von CloudFront, um zu steuern, wie lange Inhalte an Edge-Standorten zwischengespeichert werden
2. Inhaltsversionierung: Verwenden Sie Versionskennungen in Dateinamen (z. B. style-v2.css), um Cache-Aktualisierungen zu erzwingen
3. Cache-Control-Header: Setzen Sie geeignete Header während des S3-Sync (wie oben gezeigt)
4. Selektive Invalidation: Invalidieren Sie nur geänderte Pfade anstelle des gesamten Caches

Cache-Invalidation

Nach der Bereitstellung von Aktualisierungen invalidieren Sie den CloudFront-Cache, um frische Inhalte zu servieren:

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

Für gezieltere Invalidierungen:

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

Kostenüberlegung: Die ersten 1.000 Invalidation-Pfade pro Monat sind kostenlos. Danach kostet jeder Pfad $0.005. Verwenden Sie selektive Invalidation, um die Kosten zu minimieren.

Automatisierung mit CI/CD

Manuelle Bereitstellungen funktionieren für kleine Projekte, aber die Automatisierung ist für Produktionsworkflows entscheidend. Sie können diesen Bereitstellungsprozess in Gitea Actions zur Bereitstellung einer Hugo-Website auf AWS S3 oder ähnliche CI/CD-Pipelines integrieren.

Grundlegendes Bereitstellungsskript

Erstellen Sie ein einfaches Bereitstellungsskript:

#!/bin/bash
set -e

# Hugo-Website erstellen
echo "Hugo-Website wird erstellt..."
hugo --gc --minify

# Auf S3 bereitstellen
echo "Bereitstellung auf S3..."
aws s3 sync public/ s3://Ihr-Bucket-Name/ \
  --delete \
  --cache-control max-age=60

# CloudFront-Cache invalidieren
echo "CloudFront-Cache wird invalidiert..."
aws cloudfront create-invalidation \
  --distribution-id IHRE_VERTEILUNGS-ID \
  --paths "/*"

echo "Bereitstellung abgeschlossen!"

Machen Sie es ausführbar und führen Sie es aus:

chmod +x deploy.sh
./deploy.sh

GitHub Actions-Beispiel

Für GitHub-Repositorys erstellen Sie .github/workflows/deploy.yml:

name: Bereitstellung auf 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: Bereitstellung auf S3
        run: |
          aws s3 sync public/ s3://Ihr-Bucket-Name/ \
            --delete \
            --cache-control max-age=60          

      - name: Invalidate CloudFront
        run: |
          aws cloudfront create-invalidation \
            --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
            --paths "/*"          

Überwachung und Optimierung

Aktivieren Sie Protokollierung

Konfigurieren Sie die S3- und CloudFront-Protokollierung, um Zugriffsmuster zu verfolgen:

# Aktivieren Sie die S3-Zugriffsprotokollierung
aws s3api put-bucket-logging \
  --bucket Ihr-Bucket-Name \
  --bucket-logging-status file://logging.json

Einrichtung von CloudWatch-Alarmen

Überwachen Sie Ihre Bereitstellung mit CloudWatch:

aws cloudwatch put-metric-alarm \
  --alarm-name high-error-rate \
  --alarm-description "Alert on high error rate" \
  --metric-name 4xxError \
  --namespace AWS/CloudFront \
  --statistic Sum \
  --period 300 \
  --threshold 10 \
  --comparison-operator GreaterThanThreshold

Fehlerbehebung bei häufigen Problemen

Dateien werden nicht aktualisiert

Falls Änderungen nicht angezeigt werden:

1. Überprüfen Sie den Status der CloudFront-Cache-Invalidation
2. Stellen Sie sicher, dass der --delete-Flag im Sync-Befehl verwendet wird
3. Leeren Sie den Browser-Cache oder testen Sie im Inkognito-Modus
4. Überprüfen Sie die S3-Bucket-Berechtigungen

Langsame Bereitstellungen

Optimieren Sie die Sync-Leistung:

• Verwenden Sie --exclude und --include, um unnötige Dateien zu überspringen
• Erwägen Sie die Verwendung von --size-only für schnellere Vergleiche
• Verwenden Sie parallele Uploads mit --cli-read-timeout und --cli-write-timeout

Berechtigungsfehler

Stellen Sie sicher, dass Ihr IAM-Benutzer Folgendes hat:

• S3-Bucket-Zugriffsberechtigungen
• CloudFront-Invalidation-Berechtigungen (falls zutreffend)
• Richtig konfigurierte Bucket-Richtlinien

Zusammenfassung der Best Practices

1. Verwenden Sie immer --delete, um S3 mit Ihrem lokalen Build synchron zu halten
2. Setzen Sie geeignete Cache-Header basierend auf Dateitypen
3. Verwenden Sie CloudFront für Produktionsbereitstellungen
4. Automatisieren Sie Bereitstellungen mit CI/CD-Pipelines
5. Überwachen Sie die Kosten - seien Sie sich der CloudFront-Invalidation-Gebühren bewusst
6. Versionieren Sie Ihre Bereitstellungen - taggen Sie Releases für einfache Rollbacks
7. Testen Sie lokal zuerst - überprüfen Sie Ihren Hugo-Build, bevor Sie bereitstellen

Verwandte Ressourcen

Für weitere detaillierte Informationen zur Hugo-Bereitstellung überprüfen Sie die umfassende Anleitung zur Bereitstellung einer Hugo-generierten Website auf AWS S3, die zusätzliche Bereitstellungsoptionen und Konfigurationen abdeckt.

Wenn Sie Ihre Inhalte schreiben, denken Sie daran, die richtigen Markdown-Code-Blöcke für Code-Beispiele zu verwenden und verweisen Sie auf das Umfassende Markdown-Cheat-Sheet für Formatierungsrichtlinien.

Nützliche Links

• Bereitstellung einer Hugo-generierten Website auf AWS S3
• Verwendung von Gitea Actions zur Bereitstellung einer Hugo-Website auf AWS S3
• Hugo Cheat Sheet
• Markdown Cheatsheet
• Verwendung von Markdown-Code-Blöcken

Externe Referenzen

• AWS S3 Dokumentation zur statischen Website-Hosting
• AWS CLI S3-Befehlsreferenz
• CloudFront Cache-Control-Best Practices
• Offizielle Hugo-Dokumentation
• AWS CloudFront Invalidation Guide