Статический сайт на S3 и CDN: от сборки до собственного домена с HTTPS

Статический сайт на S3 можно собрать за вечер, но первые проблемы обычно появляются уже после загрузки файлов. Сборка проходит без ошибок: next build или hugo build кладут готовые файлы в папку, они уезжают в хранилище, а вместо страницы браузер показывает 403. Или сайт открывается, но только по http://, потому что сертификат настроен не на том слое.

В этой статье мы приводим маршрут от сборки Next.js или Hugo до собственного домена с HTTPS. Разберём, как включить хостинг на бакете, не получить 403, залить сборку из GitHub Actions и GitLab CI, подключить CDN и настроить кэш.

Почему S3 подходит для хранения статики

У статического сайта на S3 объектное хранилище берёт на себя роль веб-сервера: браузер запрашивает объект по ключу, бакет отдаёт его по HTTP или HTTPS. Виртуальная машина с Nginx в такой схеме не нужна. Файлы хранятся и раздаются из одного сервиса, а сайт настраивается на уровне бакета.

Хостинг статических сайтов в VK Object Storage — штатная функция бакета. В конфигурации задаются индексная страница, страница ошибки и правила перенаправления. Такой бакет подходит для сайта-визитки, личного блога, лендинга, документации и перенаправления запросов.

Плюсы статики на объектном хранилищ:

• Не нужно обслуживать сервер. Не придётся обновлять пакеты, разбираться с Nginx после сбоя или вручную готовить сервер к каждому релизу. Раздачей занимается хранилище.
• Ёмкость растёт вместе с проектом. Бакет не нужно расширять заранее: оплачивается фактический объём данных, а не выделенный диск.
• Можно выбрать класс хранения под нагрузку. Hotbox подходит для хранения и быстрой раздачи большого количества файлов на высоконагруженных сайтах, в приложениях, медиасервисах и онлайн-СМИ. Один бакет может одновременно хранить статику сайта и файлы мобильного приложения.
• Заливка и вызовы API не тарифицируются. Входящий трафик и вызовы S3 API бесплатны. Платить нужно за объём хранения и исходящий трафик, поэтому частые деплои сами по себе счёт не увеличивают.
• Граница возможностей понятна. В бакете лежит статический контент: HTML, CSS, медиа, PDF- и TXT-документы, а также JS-скрипты без серверной обработки.

Серверной логики в бакете нет, поэтому формы обратной связи, авторизация и работа с базой данных потребуют внешних сервисов. Для статической части сайта достаточно настроить бакет и CDN.

Готовим бакет под статический сайт на S3

Первые проблемы обычно возникают из-за прав доступа, имени бакета и настройки индексного документа. Их нужно проверить до загрузки файлов.

Включаем хостинг и публичный доступ

Заливаем сборку Next.js и Hugo

После настройки бакета нужно загрузить результат сборки. Для S3 сайт должен быть полностью собран в файлы заранее.

Сборка статического экспорта

Next.js

Статический экспорт включается одной строкой в конфигурации. После output: 'export' команда next build создаёт каталог out с HTML-, CSS- и JS-файлами приложения.

// next.config.js
module.exports = {
  output: 'export',
  // /me → /me/ и /me.html → /me/index.html
  trailingSlash: true,
};
npm run build # Под капотом next build, отдельная команда экспорта не нужна

В актуальной документации нет отдельной команды next export, хотя поисковая выдача до сих пор часто предлагает устаревшую последовательность next build && next export. Достаточно одного next build.

trailingSlash: true здесь важен: маршрут превращается в папку с index.html. Например,_ /docs/_ соответствует объекту docs/index.html, который объектное хранилище отдаёт без дополнительного редиректа.

Перед переносом приложения на статический экспорт стоит проверить ограничения. В этом режиме не работают:

• динамические маршруты с dynamicParams: true без generateStaticParams();
• Route Handlers, использующие Request;
• cookies;
• rewrites, redirects и headers;
• Proxy;
• инкрементальная регенерация;
• Draft Mode;
• Server Actions;
• перехватывающие маршруты;
• оптимизация изображений через стандартный загрузчик.

Серверные компоненты остаются: они выполняются во время сборки, а fetch внутри них вызывается на этапе next build. Клиентская догрузка данных и SPA-поведение тоже сохраняются.

При отключённой оптимизации изображения можно хранить в том же бакете и направить компонент Image на них через кастомный загрузчик.

// next.config.js
module.exports = {
  output: 'export',
  images: {
    loader: 'custom',
    loaderFile: './my-loader.ts',
  },
};

Hugo

hugo build публикует сайт в каталог public. Его можно сменить флагом --destination или параметром publishDir.

У Hugo есть одна особенность: перед сборкой он не очищает public. Существующие файлы перезаписываются, но удалённые страницы остаются в каталоге. Если страница исчезла из проекта вчера, старый файл всё равно может попасть в бакет и продолжить открываться.

rm -rf public && hugo build

aws s3 sync ./public s3://my-site-bucket \
  --delete \
  --endpoint-url https://hb.ru-msk.vkcloud-storage.ru

Флаг --delete нужен и на стороне бакета: он удаляет объекты, которых больше нет в новой сборке.

При синхронизации не забудьте про --acl public-read. Предопределённый ACL назначается бакету и объектам отдельно. Если загрузить свежую сборку без публичного ACL, сайт будет отвечать 403.

Hugo умеет деплоить в S3-совместимые хранилища встроенной командой hugo deploy. Она синхронизирует public с бакетом, а матчеры позволяют задать заголовки для объектов во время загрузки.

[[deployment.targets]]
name = 'production'
url = 's3://my-site-bucket?endpoint=https://hb.ru-msk.vkcloud-storage.ru&awssdk=v2&use_path_style=true&disable_https=false'

[[deployment.matchers]]
pattern = '^.+\.(js|css|svg|ttf)$'
cacheControl = 'max-age=31536000, no-transform, public'
gzip = true

[[deployment.matchers]]
pattern = '^.+\.(png|jpg)$'
cacheControl = 'max-age=31536000, no-transform, public'
gzip = false
hugo deploy --target=production

Формат URL с use_path_style=true подходит для S3-совместимых хранилищ, включая MinIO и Ceph. Для команды потребуется версия Hugo с поддержкой deploy: deploy- или extended/deploy-сборка.

Автодеплой из CI

После нескольких релизов загрузку лучше перенести в пайплайн: он синхронизирует сборку с бакетом и очищает кэш CDN.

# .github/workflows/deploy.yml
name: deploy

on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.VK_S3_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.VK_S3_SECRET }}
      S3_ENDPOINT: https://hb.ru-msk.vkcloud-storage.ru

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci && npm run build

      - name: Sync build to bucket
        run: |
          aws s3 sync ./out s3://my-site-bucket --delete \
            --endpoint-url "$S3_ENDPOINT"

      - name: Purge CDN cache
        run: |
          curl -X POST \
            "$CDN_API/projects/$PROJECT_ID/resources/$RESOURCE_ID/purge" \
            -H "X-Auth-Token: $CDN_TOKEN" \
            -H "Content-Type: application/json" \
            -d '{"paths": ["/index.html", "/*.html", "/sitemap.xml"]}'
        env:
          CDN_API: ${{ secrets.VK_CDN_API }}
          CDN_TOKEN: ${{ secrets.VK_CDN_TOKEN }}
          PROJECT_ID: ${{ secrets.VK_PROJECT_ID }}
          RESOURCE_ID: ${{ secrets.VK_CDN_RESOURCE_ID }}

Тот же сценарий в GitLab CI:

build:
  stage: build
  image: node:20
  script:
    - npm ci && npm run build
  artifacts:
    paths: [out]

deploy:
  stage: deploy
  image: python:3.12-slim
  needs: [build]
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    - pip install --quiet awscli
    - aws s3 sync ./out s3://my-site-bucket --delete --endpoint-url "$S3_ENDPOINT"
    - >
      curl -X POST "$CDN_API/projects/$PROJECT_ID/resources/$RESOURCE_ID/purge"
      -H "X-Auth-Token: $CDN_TOKEN"
      -H "Content-Type: application/json"
      -d '{"paths": ["/*.html"]}'

Идентификаторы проекта и CDN-ресурса находятся в личном кабинете на странице ресурса. API включается в настройках проекта и требует двухфакторной аутентификации.

В секретах CI хранятся учётные данные. Keystone-токен лучше запрашивать прямо в job перед очисткой кэша: он действует один час.

Для очистки используется метод:

POST /projects/{project_id}/resources/{resources_id}/purge

В теле передаётся массив paths. Пустой массив очищает весь кэш и создаёт лишнюю нагрузку на серверы-источники, поэтому пути лучше перечислять явно.

Подключаем CDN VK Cloud

Сайт уже открывается по адресу бакета, но бакет находится в конкретном регионе. Без CDN пользователь из Хабаровска и пользователь из Москвы получают файлы из одной точки. CDN кэширует контент на пограничных серверах и отдаёт его с ближайшего узла.

В сети VK Cloud более 46 точек присутствия в Европе, СНГ, Северной и Южной Америке, более 200 кэширующих серверов, более 700 пиринговых партнёров и ёмкость свыше 12 Тбит/с. В России точки присутствия работают в 16 городах — от Петрозаводска и Пскова до Красноярска и Хабаровска.

CDN можно подключить прямо из интерфейса бакета. CDN-ресурс и SSL-сертификаты при этом создаются автоматически. Ручная настройка через интерфейс CDN нужна, если источник находится не в Object Storage или сертификат нужно добавить вручную.

Порядок действий:

1. Проверить, что у бакета включён ACL public-read, и загружать объекты с тем же ACL. Иначе бакет не сможет работать источником CDN.
2. Открыть вкладку CDN в настройках бакета и включить CDN.
3. Указать персональный домен как FQDN без завершающей точки: cdn.example.com, но не cdn.example.com.
4. Сохранить оригинальное доменное имя, которое выдаст платформа. Его нужно использовать в CNAME-записи.
5. Выбрать TTL кэша.
6. После создания ресурса указать заголовок Host в формате <ИМЯ_БАКЕТА>.<ДОМЕН_СЕРВИСА>. Без этого CDN будет обращаться к источнику с неправильным Host.

Есть два ограничения:

• По умолчанию CDN обращается к источнику и по HTTP, и по HTTPS. Для каждого протокола в кэше хранится отдельная версия файла.
• На тестовых стендах CDN-ресурс могут приостановить из-за низкого трафика: если ресурсу меньше 30 дней и через него прошло меньше 1 МБ с момента создания или если за последние 14 дней он передал меньше 1 МБ.

Единого показателя задержки в документации CDN нет. Для сайта полезнее измерять время до первого байта из регионов, где находится аудитория.

Кастомный домен и HTTPS

На этом этапе чаще всего путают настройку домена с настройкой сертификата. В связке статического сайта на S3 и собственного домена это разные настройки на разных уровнях.

Свой домен и SSL

Домен на бакете

В настройках бакета есть вкладка «Домен». Нажмите «Привязать домен», скопируйте значение вида mybucket.hb.ru-msk.vkcloud-storage.ru, добавьте CNAME-запись у DNS-провайдера, дождитесь распространения DNS и укажите домен в поле.

Распространение обычно занимает 15–20 минут.

Привязать можно только домен третьего уровня и выше: mysite.example.com подойдёт, а корневой example.com — нет. После привязки бакет будет доступен по адресу:

http://<ИМЯ_БАКЕТА>.<ИМЯ_ДОМЕНА>

Привязка домена к бакету сама по себе не включает HTTPS. Сертификат для бакета выпускают по заявке в техническую поддержку: можно выбрать Let's Encrypt или загрузить собственный, но для каждого домена понадобится отдельный сертификат.

Обычно HTTPS настраивают через CDN, где сертификат выпускается автоматически. Если в имени бакета есть точка, без сертификата он и в этой схеме останется доступен только по HTTP.

Сертификат на CDN-ресурсе

У CDN-ресурса есть три варианта шифрования:

Let's Encrypt создаётся после того, как станут доступны серверы-источники и распространятся DNS-изменения для CNAME-записей персональных доменов. Обычно это занимает до 30 минут.

Для выпуска сертификата должна быть включена опция «Доступ к контенту конечным пользователям».

Через API настройки выглядят так:

• "sslEnabled": false — только HTTP;
• "sslEnabled": true и "ssl_automated": true — Let's Encrypt с автопродлением;
• "sslEnabled": true и "ssl_automated": false — Let's Encrypt без автопродления;
• "sslEnabled": true и "sslData": — собственный сертификат.

Корпоративный сертификат добавляется в хранилище сертификатов CDN. Нужны имя, публичная часть в PEM и приватный ключ в PEM. У готовой записи можно изменить только имя, поэтому при замене сертификата создаётся новая запись. Напоминание о сроке истечения лучше поставить сразу.

Для домена_ example.com_ последовательность будет такой:

• Создать CDN-ресурс из бакета.
• Указать FQDN.
• Направить CNAME на имя, выданное платформой.
• Дождаться выпуска Let's Encrypt.
• Проверить, что сайт открывается по https://.

Кэш и инвалидация

Если после деплоя на сайте остаётся старая версия, проверьте кэш. На раздачу влияют четыре уровня кэширования.

Управление кэшем

Инвалидация

Очистка бывает полной и выборочной. Полная очистка заставляет CDN-серверы снова запрашивать контент у источников, увеличивает нагрузку и может дестабилизировать сервис. Для больших объёмов лучше очищать только нужные пути.

Выборочная очистка работает по пути или шаблону:

• /;
• * в начале пути;
• * вместо произвольного числа символов;
• "/static/*";
• "*.png";
• "/images/".

В API пустой массив paths очищает весь кэш. Непустой массив очищает только указанные пути.

Рабочая схема деплоя выглядит так:

• Ассеты собираются с хэшем в имени: app.4f2c1a.js.
• Ассеты загружаются с max-age=31536000. Чистить их не нужно: каждая новая сборка приносит файлы с новыми именами.
• HTML-файлы получают короткий max-age, потому что меняются с каждым релизом.
• После aws s3 sync pipeline очищает только HTML и служебные файлы: "/index.html", "/*.html", "/sitemap.xml".
• Полный purge остаётся аварийным инструментом, а не частью обычного релиза.

Крупные файлы можно заранее загрузить в CDN-кэш через POST .../prefetch, не дожидаясь первого запроса пользователя. Это имеет смысл для файлов больше 200 МБ. Сначала очистите старую версию из кэша, затем запустите предзагрузку.

Во что обходится статический сайт на S3

Стоимость сайта складывается из трёх платных и двух бесплатных пунктов.

Месячный счёт можно представить так:

Счёт = Объём_ГБ × ставка_класса + Исходящий_трафик_S3_ГБ × ставка_трафика_S3 + Трафик_CDN_ГБ × ставка_трафика_CDN

Для оценки заранее важны несколько моментов:

• Класс хранения выбирают по профилю доступа, а не только по цене за гигабайт. Hotbox рассчитан на высоконагруженные сайты, приложения и медиасервисы. Icebox — на редко используемые данные.
• Для раздачи сайта обычно подходит Hotbox. Архив старых сборок лучше держать в отдельном бакете.
• В документации есть два пользовательских класса, Hotbox и Icebox, а также служебный BackupBucket для резервных копий инстансов. Класса глубокого архива в расчёт не закладываем.
• С CDN исходящий трафик S3 уменьшается: пограничные серверы забирают файл с источника один раз на TTL, а затем раздают его из кэша. Основная часть трафика переходит в строку CDN.
• Если нужно раздавать больше 100 ТБ в месяц, стоит обратиться в техническую поддержку.

Для типового лендинга статика вместе с изображениями обычно занимает единицы гигабайт и почти не влияет на итоговую сумму. Основные расходы даёт трафик. Оптимизация картинок и шрифтов обычно экономит больше, чем выбор класса хранения.

Заключение

Для статического сайта достаточно собрать файлы, загрузить их в бакет и открыть к ним публичный доступ. S3 будет раздавать HTML, стили, скрипты и медиа, а CDN возьмёт на себя кэширование, доставку контента из ближайших точек и HTTPS на собственном домене.

Next.js в таком сценарии собирается командой next build с output: 'export', Hugo — командой hugo build. Перед сборкой Hugo каталог public нужно очищать, иначе в следующую загрузку могут попасть удалённые файлы.

Перед первым релизом проверьте ACL бакета, его имя и конфигурацию индексной страницы. При загрузке задайте Cache-Control, а в pipeline добавьте выборочную очистку CDN-кэша для HTML и служебных файлов. После этого останется создать бакет, загрузить сборку, включить CDN и направить домен на выданный адрес.