Развертывание сайта Hugo на AWS S3 с помощью AWS CLI

Развертывание статического сайта Hugo на AWS S3 с использованием AWS CLI предоставляет надежное, масштабируемое решение для хостинга вашего веб-сайта. Это руководство охватывает весь процесс развертывания, от начальной настройки до продвинутых стратегий автоматизации и управления кэшем.

Развертывание с помощью AWS CLI становится предпочтительным подходом, так как дистрибутив Hugo удалил команду deploy из стандартного пакета. Узнайте о extended и withdeploy в Как установить Ubuntu 24.04 и полезные инструменты, если вы делаете это локально и все еще хотите вызвать hugo deploy.

Предварительные требования

Перед развертыванием вашего сайта Hugo на AWS S3 убедитесь, что у вас есть:

• Готовый сайт Hugo для развертывания (если вам нужна помощь в создании, ознакомьтесь с быстрым стартом Hugo)
• Учетная запись AWS с соответствующими разрешениями
• Установленный и настроенный AWS CLI
• Основные знания работы с командной строкой

Сборка вашего сайта Hugo

Первый шаг в развертывании вашего сайта Hugo — это генерация статических файлов. Используйте Hugo Cheat Sheet в качестве справочника по доступным командам и опциям.

Соберите свой сайт с флагами оптимизации:

hugo --gc --minify

Флаг --gc удаляет неиспользуемые файлы кэша, а --minify сжимает ваш HTML, CSS и JavaScript для оптимальной производительности. Это генерирует ваш статический сайт в директории public/, которую мы будем развертывать на S3.

Настройка AWS CLI

Если вы еще не настроили AWS CLI, выполните:

aws configure

Вам будет предложено ввести:

• AWS Access Key ID: ваш ключ доступа AWS
• AWS Secret Access Key: ваш секретный ключ
• Регион по умолчанию: ваш предпочтительный регион AWS (например, us-east-1, ap-southeast-2)
• Формат вывода по умолчанию: json (рекомендуется)

Для программного доступа убедитесь, что у вашего пользователя IAM есть разрешения на:

• s3:PutObject
• s3:GetObject
• s3:DeleteObject
• s3:ListBucket
• cloudfront:CreateInvalidation (если используется CloudFront)

Создание и настройка корзины S3

Создание корзины

Создайте свою корзину S3 с помощью AWS CLI:

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

Важно: Выберите глобально уникальное имя корзины. Если вы планируете использовать корзину для хостинга веб-сайтов, имя корзины должно совпадать с вашим доменным именем, если вы используете пользовательский домен.

Настройка корзины для хостинга статических веб-сайтов

Включите хостинг статических веб-сайтов:

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

Установка политики корзины

Для общего доступа на чтение (если не используется CloudFront), создайте политику корзины:

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

Примените политику:

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

Примечание по безопасности: Если вы используете CloudFront (рекомендуется), вы можете ограничить доступ к корзине S3 только для CloudFront, что исключает необходимость в общедоступном доступе на чтение.

Развертывание на S3 с использованием AWS CLI

Основная команда развертывания использует aws s3 sync для загрузки вашего сайта:

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

Пояснение ключевых параметров

• public/: ваша локальная директория вывода Hugo
• s3://your-bucket-name/: ваше назначение корзины S3
• --delete: удаляет файлы в S3, которых нет локально, обеспечивая синхронизацию вашей сборки
• --cache-control max-age=60: устанавливает заголовки кэша (60 секунд в этом примере)

Продвинутые опции синхронизации

Для большего контроля над вашим развертыванием:

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"

Этот пример устанавливает разные сроки кэширования для HTML-файлов (60 секунд) по сравнению со статическими ресурсами, такими как JavaScript (1 год), что является распространенной стратегией оптимизации.

Настройка распределения CloudFront

Хотя S3 может напрямую хостить статические веб-сайты, использование Amazon CloudFront в качестве CDN обеспечивает лучшую производительность, безопасность и глобальное распределение.

Создание распределения CloudFront

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

Базовая конфигурация CloudFront включает:

• Корзину S3 в качестве источника
• Стандартные поведения кэширования
• Сертификат SSL/TLS (из AWS Certificate Manager)
• Настройка пользовательского домена (опционально)

Стратегии управления кэшем

При развертывании через CloudFront рассмотрите следующие стратегии кэширования:

1. Установите максимальный TTL: Настройте максимальный TTL CloudFront для контроля времени кэширования контента в точках доступа
2. Версионирование контента: Используйте идентификаторы версий в именах файлов (например, style-v2.css) для принудительного обновления кэша
3. Заголовки Cache-Control: Устанавливайте соответствующие заголовки во время синхронизации S3 (как показано выше)
4. Селективная инвалидация: Инвалидируйте только измененные пути, а не весь кэш

Инвалидация кэша

После развертывания обновлений инвалидируйте кэш CloudFront для обслуживания свежего контента:

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

Для более целенаправленных инвалидаций:

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

Рассмотрение стоимости: Первые 1,000 путей инвалидации в месяц бесплатны. После этого каждый путь стоит $0.005. Используйте селективную инвалидацию для минимизации затрат.

Автоматизация с CI/CD

Ручное развертывание подходит для небольших проектов, но автоматизация необходима для рабочих процессов производства. Вы можете интегрировать этот процесс развертывания с Gitea Actions для развертывания сайта Hugo на AWS S3 или аналогичными конвейерами CI/CD.

Базовый скрипт развертывания

Создайте простой скрипт развертывания:

#!/bin/bash
set -e

# Сборка сайта Hugo
echo "Сборка сайта Hugo..."
hugo --gc --minify

# Развертывание на S3
echo "Развертывание на S3..."
aws s3 sync public/ s3://your-bucket-name/ \
  --delete \
  --cache-control max-age=60

# Инвалидация кэша CloudFront
echo "Инвалидация кэша CloudFront..."
aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/*"

echo "Развертывание завершено!"

Сделайте его исполняемым и запустите:

chmod +x deploy.sh
./deploy.sh

Пример GitHub Actions

Для репозиториев GitHub создайте .github/workflows/deploy.yml:

name: Развертывание на AWS S3

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Настройка Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'

      - name: Сборка
        run: hugo --gc --minify

      - name: Настройка учетных данных AWS
        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: Развертывание на S3
        run: |
          aws s3 sync public/ s3://your-bucket-name/ \
            --delete \
            --cache-control max-age=60          

      - name: Инвалидация CloudFront
        run: |
          aws cloudfront create-invalidation \
            --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
            --paths "/*"          

Мониторинг и оптимизация

Включение журналирования

Настройте журналирование доступа S3 и CloudFront для отслеживания шаблонов доступа:

# Включение журналирования доступа S3
aws s3api put-bucket-logging \
  --bucket your-bucket-name \
  --bucket-logging-status file://logging.json

Настройка тревог CloudWatch

Мониторьте ваше развертывание с помощью CloudWatch:

aws cloudwatch put-metric-alarm \
  --alarm-name high-error-rate \
  --alarm-description "Алерт на высокий уровень ошибок" \
  --metric-name 4xxError \
  --namespace AWS/CloudFront \
  --statistic Sum \
  --period 300 \
  --threshold 10 \
  --comparison-operator GreaterThanThreshold

Устранение распространенных проблем

Файлы не обновляются

Если изменения не отображаются:

1. Проверьте статус инвалидации кэша CloudFront
2. Убедитесь, что флаг --delete используется в команде синхронизации
3. Очистите кэш браузера или протестируйте в режиме инкогнито
4. Проверьте разрешения корзины S3

Медленные развертывания

Оптимизируйте производительность синхронизации:

• Используйте --exclude и --include для пропуска ненужных файлов
• Рассмотрите использование --size-only для более быстрого сравнения
• Используйте параллельные загрузки с --cli-read-timeout и --cli-write-timeout

Ошибки разрешения

Убедитесь, что у вашего пользователя IAM есть:

• Разрешения доступа к корзине S3
• Разрешения инвалидации CloudFront (если применимо)
• Правильно настроенные политики корзины

Рекомендации по лучшим практикам

1. Всегда используйте --delete для синхронизации S3 с вашей локальной сборкой
2. Устанавливайте соответствующие заголовки кэша в зависимости от типов файлов
3. Используйте CloudFront для развертываний в производственной среде
4. Автоматизируйте развертывания с помощью конвейеров CI/CD
5. Мониторьте затраты - будьте осмотрительны с затратами на инвалидацию CloudFront
6. Версионируйте свои развертывания - помечайте релизы для легкого отката
7. Тестируйте локально сначала - проверяйте сборку Hugo перед развертыванием

Связанные ресурсы

Для более подробной информации о развертывании Hugo ознакомьтесь с всеобъемлющим руководством по развертыванию сайта, сгенерированного Hugo, на AWS S3, которое охватывает дополнительные варианты развертывания и конфигурации.

При написании контента помните использовать правильные блоки кода Markdown для примеров кода и ссылаться на Всеобъемлющий чизшит Markdown для руководств по форматированию.

Полезные ссылки

• Развертывание сайта, сгенерированного Hugo, на AWS S3
• Использование Gitea Actions для развертывания сайта Hugo на AWS S3
• Hugo Cheat Sheet
• Чизшит Markdown
• Использование блоков кода Markdown

Внешние ссылки

• Документация AWS S3 по хостингу статических веб-сайтов
• Справочник команд AWS CLI для S3
• Лучшие практики управления кэшированием CloudFront
• Официальная документация Hugo
• Руководство по инвалидации кэша CloudFront