Границы headless-библиотеки и локальное окружение

Оглавление серии

Headless CMS хранит содержание и предоставляет его через API. Она не определяет единственный обязательный способ показа этого содержания. В обычном движке шаблон страницы тесно связан с записью; в нашем проекте редактор создаёт статью в Strapi, а отдельный сайт решает, как превратить полученный документ в HTML. Это разделение удобно изучать на небольшой библиотеке «Редакционный дом», где есть статьи, авторы, разделы и обложки.

Результат первого урока — понятные границы проекта и подготовленная локальная конфигурация. Мы не подключаем существующую редакцию и не переносим опубликованные материалы ProfessorWeb. Все имена и тексты вымышлены. Исходники курса подготовлены без запуска; описанные ниже окна и ответы являются ожидаемыми состояниями, которые читатель сможет проверить в собственной лаборатории.

Три участника запроса

Представим посещение страницы «Сетка карточек CSS Grid». Браузер обращается к серверу сайта. Сервер запрашивает опубликованный документ в CMS, получает название, краткое описание и текст, подставляет их в шаблон и отвечает браузеру. Редакторская панель не участвует в этом запросе. Её задача — дать человеку возможность изменять содержание, проверять связи и принимать решение о публикации.

Участники используют разные полномочия. Редактор входит в административную панель по своей учётной записи. Сервер сайта получает отдельный Content API token. Читатель не получает ни пароль редактора, ни этот token. Даже если HTML страницы доступен всем, источник данных может оставаться закрытым. В дальнейшем мы воспользуемся именно такой схемой: у анонимной Public role не будет права читать коллекции.

Разделение процессов помогает объяснить распространённое недоразумение. Если панель открывается, это ещё не подтверждает, что сайт умеет читать статьи. Панель может работать, а серверный token — истечь. И наоборот: временная недоступность редакторского интерфейса не обязательно означает отсутствие опубликованных документов. Каждую связь проверяют отдельно, связывая результат с конкретным участником и конкретным адресом.

В лаборатории CMS слушает 127.0.0.1:1337, сайт — 127.0.0.1:4178. Эти адреса относятся к вашему компьютеру. Привязка к loopback нужна, чтобы учебная панель не появилась в локальной сети случайно. Она не заменяет пароль, права доступа или будущую настройку HTTPS при внешнем размещении.

Версия и состав папки

На 11 октября 2026 года официальный релиз выбранной линии — Strapi 5.57.0. Для курса выбираем Node 24 LTS из поддерживаемых документацией версий. В нашем наборе нет установленного дерева зависимостей и package-lock.json; эти файлы появятся только после вашей установки. Список поддерживаемых платформ и выпуск уточняются по инструкции CLI и релизу 5.57.0.

Если создаёте лабораторию самостоятельно, подготовьте Node выбранной линии, npm и пустую рабочую папку. Затем используйте официальный генератор с фиксированной версией. Следующая команда предназначена для читателя; в подготовке курса она не выполнялась.

npx create-strapi@5.57.0 editorial-house \
  --js \
  --skip-cloud \
  --no-run \
  --no-example \
  --no-git-init

Параметр --skip-cloud оставляет работу локальной; аккаунт Strapi Cloud не нужен. --no-example исключает посторонние демонстрационные записи. --no-run позволяет сначала разобраться с файлами и секретами. Выберите SQLite для небольшой лаборатории. Это не обещание, что такой же выбор подойдёт редакции с большим количеством пользователей и конкурентных изменений.

В архиве курса папки config/ и src/ содержат авторские настройки и модели. Они дополняют проект, созданный генератором той же версии. Не удаляйте остальные служебные файлы генератора: наша цель — изучить контролируемые изменения, а не переписать всю структуру CMS. Отдельная папка site/ содержит потребителя и не должна оказаться внутри публичной папки загрузок CMS.

Различайте три вида содержимого. Схемы коллекций — исходный код проекта. Статьи и связи — записи базы данных. Обложки — файлы хранилища. Копирование одной папки src/ не переносит редакционный текст. Копирование SQLite-файла не обязательно переносит изображения. Это различие позже определит состав резервной копии.

Конфигурация и собственные секреты

Полный config/server.js из учебного набора задаёт локальный адрес и общий заголовок будущих webhooks. Последнюю настройку пока оставим без созданного webhook: она пригодится в тринадцатом уроке.

module.exports = ({ env }) => ({
  host: env('HOST', '127.0.0.1'),
  port: env.int('PORT', 1337),
  app: { keys: env.array('APP_KEYS') },
  webhooks: {
    defaultHeaders: {
      Authorization: `Bearer ${env('WEBHOOK_TOKEN')}`,
    },
  },
});

Функция получает env от Strapi и читает настройки окружения при запуске. Параметр app.keys относится к служебным ключам приложения. WEBHOOK_TOKEN относится к связи с нашим получателем событий. Ни один из них не является паролем администратора. Разные назначения требуют разных случайных значений: иначе отзыв одного доступа затронет несколько независимых механизмов.

Скопируйте .env.example в .env и замените каждое значение replace-with собственным случайным значением. Шаблон показывает названия переменных, но не содержит пригодных секретов. .env хранится отдельно от общего архива; не вставляйте его содержимое в статью, комментарий или снимок экрана. Пароль первого администратора также выбирается локально и не повторяет значения из конфигурации.

После вашего будущего запуска в панели можно ожидать создание первой административной учётной записи. Пустая библиотека на этом этапе нормальна: генератор не получил примерные статьи, а модель Article ещё не определена. Не включайте Public permissions ради устранения пустого каталога. Отсутствие модели, отсутствие опубликованных данных и отсутствие права читать — разные причины, которые нельзя исправлять одной общей настройкой доступа.

Есть и ещё одна граница: код клиента можно передать без базы редакции. Такой набор показывает устройство сайта, но не воспроизводит содержание автоматически. Наш fixtures решает задачу исходных вымышленных записей, а export позже решит задачу состояния конкретного экземпляра. Сначала выберите, что требуется другому человеку: изучить механизм или восстановить вашу заполненную лабораторию. От этого зависит комплект файлов.

По той же причине не называйте папку site резервной копией CMS. Она содержит renderer и запросы, но не статьи, роли и физические обложки. Если потерять базу, одинаковый HTML-шаблон не восстановит редакционный текст. Это простое сравнение уже на первом шаге помогает увидеть, зачем headless-проекту нужен общий документ о составе, хотя процессы могут разрабатываться независимо.

Для самостоятельной проверки границ нарисуйте стрелки «редактор → панель», «сайт → Content API» и «читатель → сайт». Под каждой подпишите, какие credentials используются. Если под стрелкой браузера оказался серверный token, схема требует исправления до наполнения библиотеки. В следующем уроке появится первая коллекция, и у каждой записи будут поля, смысл которых не зависит от оформления страницы.