Руководство по внедрению Sveltia CMS

7 июня 2026 г. в 16:00by Gui

Технологии CMS Astro Cloudflare Безопасность

Содержание

Когда Sveltia CMS подходит
Общая архитектура
1. Разместить админку в public/admin
2. Настроить GitHub backend
3. Добавить OAuth Worker
4. Заранее определить папку медиа
5. Разделить collections
6. Использовать relation и select
7. Редактировать японские source JSON
8. Сохранять main веткой публикации и в preview
9. Создавать временные ветки через save proxy
10. Перевод только для CMS commits
11. Отдельный CSP для /admin
Turnstile отдельно
Уроки из PR и commit
Минимальная отправная точка
Ссылки
Итог

Sveltia CMS полезна, когда статическому сайту нужна удобная админка, но переносить контент во внешнюю базу данных не хочется. В этой статье описано, как мы внедрили Sveltia CMS на Astro-сайте Acecore и какие проблемы исправили позже по итогам PR и commit.

Заголовок намеренно простой: Руководство по внедрению Sveltia CMS. Это не сравнение CMS, а практический ориентир для внедрения на другом сайте.

Когда Sveltia CMS подходит

Sveltia CMS не владеет отдельной базой данных и не отдаёт контент через отдельный API. Это SPA в браузере, которое редактирует файлы репозитория через GitHub backend.

Она хорошо подходит, если:

контент хранится как Markdown или JSON в репозитории
изменения статей, авторов, тегов и текстов страниц нужно ревьюить как Git diff
не хочется добавлять базу данных или отдельный сервис администрирования
изображения можно хранить в public/uploads
CMS-изменения должны проходить через Pull Request перед production

Если нужны сложные права, развитое планирование публикаций, большая медиатека или редактирование realtime-данных, лучше рассмотреть полноценную headless CMS.

Общая архитектура

public/admin/index.html
  -> загружает @sveltia/cms из CDN

public/admin/config.yml
  -> описывает GitHub backend, collections и media folders

workers/sveltia-cms-auth
  -> Cloudflare Worker для GitHub OAuth

main branch
  -> единственный источник для production

CMS save proxy
  -> проверяет разрешённые пути и создаёт временную ветку и PR для каждого изменения

.github/workflows/create-translation-prs.yml
  -> создаёт задачи перевода только для cms: commits

Админская страница — только начало. Аутентификация, пути медиа, preview branches, переводы и стратегия merge тоже становятся частью CMS-дизайна.

1. Разместить админку в `public/admin`

В Astro каталог public публикуется как статические файлы. Документация Sveltia CMS также указывает public как static folder для Astro, Next.js, Nuxt, Remix и VitePress.

<!doctype html>
<html lang="ru">
  <head>
    <meta charset="utf-8" />
    <meta name="robots" content="noindex,nofollow" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>CMS</title>
  </head>
  <body>
    <script src="https://unpkg.com/@sveltia/cms@0.172.4/dist/sveltia-cms.js"></script>
  </body>
</html>

Не стоит добавлять лишний CSS или type="module" без причины. Стили интерфейса уже включены в JavaScript bundle.

Acecore использует ручную инициализацию для явной настройки backend. Ветка публикации остаётся main во всех окружениях.

CMS.init({
  config: {
    backend: {
      branch: 'main',
    },
  },
})

2. Настроить GitHub backend

Минимум — backend.name и backend.repo. Для production также стоит заранее определить branch, OAuth и сообщения commit.

backend:
  name: github
  repo: owner/repository
  branch: main
  base_url: https://your-sveltia-cms-auth-worker.example.workers.dev
  api_root: /admin/api/github
  graphql_api_root: /admin/api/graphql
  auth_methods: [oauth]
  commit_messages:
    create: 'cms: create {{collection}} "{{slug}}"'
    update: 'cms: update {{collection}} "{{slug}}"'
    delete: 'cms: delete {{collection}} "{{slug}}"'
    uploadMedia: 'cms: upload "{{path}}"'
    deleteMedia: 'cms: delete media "{{path}}"'

Оставьте main веткой публикации и направляйте чтение и сохранение через same-origin proxy. Перед созданием временной ветки и PR proxy проверяет репозиторий, право GitHub-пользователя на запись, изменённые пути и последний HEAD main.

По состоянию на 20 июля 2026 года Editorial Workflow не реализован в Sveltia CMS. Настройка Decap CMS publish_mode: editorial_workflow не заставляет Sveltia CMS автоматически создавать временные ветки или PR.

Постоянная ветка вроде cms-content требует непрерывной синхронизации и повышает риск конфликтов или неверной настройки источника deploy. Временные ветки сохраняют main единственным источником истины.

3. Добавить OAuth Worker

Personal Access Token подходит для теста, но не для нескольких редакторов. Acecore использует Sveltia CMS Authenticator на Cloudflare Workers и указывает его как base_url.

Callback URL в GitHub OAuth App указывает на /callback Worker. В Worker задаются GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET и при необходимости ALLOWED_DOMAINS.

Это не то же самое, что Turnstile. OAuth защищает вход в CMS, а Turnstile защищает формы или API комментариев от ботов.

4. Заранее определить папку медиа

Sveltia CMS может сохранять медиа в репозитории. Для Astro практичная настройка такая:

media_folder: public/uploads
public_folder: /uploads

Acecore позже исправила этот момент в PR #116. Путь в репозитории и публичный URL нужно выбирать одновременно при внедрении CMS.

5. Разделить collections

collection	Цель	Правило
`blog`	`src/content/blog/*.md`	Редактировать только японские source-статьи
`authors`	`src/content/authors/*.json`	Редактировать профили и локализованные имена
`tags`	`src/content/tags/*.json`	Редактировать теги и локализованные имена
page text	`src/i18n/source/ja/*/.json`	Редактировать японские source-тексты страниц и UI

Не обязательно открывать в CMS все переведённые Markdown-файлы. Acecore считает японский source каноническим, а переводы обновляет через Как вести многоязычный блог с Sveltia CMS.

6. Использовать relation и select

Теги лучше выбирать через relation, а не вводить свободным текстом.

- name: tags
  label: Теги
  widget: relation
  collection: tags
  value_field: name
  display_fields: ['{{name}} ({{id}})']
  search_fields: [name, id]
  multiple: true
  required: false

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

7. Редактировать японские source JSON

Тексты фиксированных страниц тоже можно отдать в CMS. Acecore хранит японский source в src/i18n/source/ja/**/*.json.

Урок простой: не добавлять все поля сразу. config.yml быстро растёт. Начните с блога, авторов, тегов, объявлений и часто меняющихся страниц.

8. Сохранять `main` веткой публикации и в preview

Proxy создаёт каждую временную ветку от последнего main. Поэтому preview Cloudflare Pages не должен подменять backend branch своей PR-веткой. Результат проверяется в Pages preview созданного CMS PR.

CMS.init({
  config: {
    backend: {
      branch: 'main',
    },
  },
})

9. Создавать временные ветки через save proxy

Same-origin save proxy создаёт временную ветку и PR в main для каждого изменения.

backend:
  name: github
  repo: owner/repository
  branch: main
  api_root: /admin/api/github
  graphql_api_root: /admin/api/graphql

Proxy не пишет напрямую в main. Он объединяет разрешённый контент и медиа в один commit, создаёт cms/acecore/* от последнего main и открывает PR. После ревью и merge временная ветка удаляется автоматически.

При GitHub OAuth token редактора задаёт личность и выступает актором записи. При Cloudflare Access актором может быть отдельная GitHub App сайта. Ограничения путей, временные ветки, PR и CI одинаковы в обеих схемах.

Способ merge важен. Задачи перевода зависят от commit subjects вроде cms: create .... Если squash merge их удалит, автоматизация может не увидеть изменение source. Для CMS PR лучше merge commit или rebase merge.

10. Перевод только для CMS commits

PR #98 добавил --cms-only, чтобы push-triggered задачи перевода создавались только для CMS commits.

function isCmsCommitSubject(subject) {
  return /^cms: (create|update|delete) /.test(subject || '')
}

cms: — это контракт workflow, а не декоративный префикс.

11. Отдельный CSP для `/admin`

Админка подключается к CDN, GitHub API, OAuth Worker и blob URL. Поэтому Acecore задаёт отдельный CSP для /admin/* и помечает эту область как noindex.

Turnstile отдельно

Старая версия статьи смешивала CMS и Cloudflare Turnstile. Это размывало тему.

Sveltia CMS — про GitHub backend, OAuth, collections, медиа и PR. Turnstile — про защиту форм или API от ботов. Это разные уровни.

Уроки из PR и commit

При смене CMS нужно обновлять статьи и внутренние ссылки.
OAuth должен быть частью реального setup, а не задачей на потом.
Пути медиа нужно зафиксировать до загрузок.
config.yml лучше расширять постепенно.
cms: — контракт автоматизации.
Ветка публикации не меняется между окружениями; preview проверяет результат CMS PR.

Минимальная отправная точка

public/admin/index.html
public/admin/config.yml
public/admin/init.js
public/admin/runtime-config.js

Затем добавляйте relation для авторов и тегов, изображения, source JSON, автоматические CMS PR и задачи перевода.

Ссылки

Итог

Sveltia CMS легко положить в public/admin, но production-внедрение требует решений о branch, OAuth, media folders, source language, workflow переводов и merge strategy. Когда эти правила понятны, Astro-сайт остаётся статическим и лёгким, но получает рабочий процесс обновления контента.

Поток внедрения Sveltia CMS

Админку, аутентификацию, редактируемый контент, медиа и PR-процесс стоит проектировать отдельно.

Добавить админку

Разместить index.html и config.yml в public/admin и загрузить Sveltia CMS.

Настроить GitHub

Заранее определить repo, branch, OAuth Worker и сообщения commit для CMS.

Ограничить область редактирования

Открыть в CMS только блог, авторов, теги и японские source JSON, которые действительно нужно редактировать.

Автоматизировать эксплуатацию

Использовать main как ветку публикации и связать временные ветки проверяющего save proxy, CMS PR и задачи перевода.

До и после CMS

Ручное редактирование Markdown

Обновлять удобно только тем, кто уверенно пользуется GitHub или редактором
Пути изображений, ID авторов и теги вводятся вручную
Изменения японского source и переводов легко смешать
Цель сохранения и доступные для записи пути могут быть неясны

Редактирование в Sveltia CMS

Markdown и JSON редактируются через формы в браузере
relation, image и select уменьшают число некорректных значений
Только CMS commits запускают задачи перевода
Same-origin proxy пишет только разрешённые пути во временную ветку и PR

Чеклист внедрения

Выполнено: Загрузить Sveltia CMS из public/admin/index.html
Выполнено: Описать GitHub backend и collections в public/admin/config.yml
Выполнено: Использовать OAuth Worker для нескольких редакторов
Выполнено: Согласовать media_folder и public_folder с каталогом public в Astro
Выполнено: Определить, как CMS commits запускают перевод или публикацию

Частые вопросы

Для каких сайтов подходит Sveltia CMS?

Для статических сайтов, где Markdown или JSON находятся в репозитории, например Astro, Hugo или VitePress. CMS можно добавить без внешней базы данных.

Можно ли использовать только GitHub Personal Access Token?

Для теста можно. Но для нескольких редакторов или нетехнических пользователей OAuth Worker безопаснее и понятнее.

Нужно ли редактировать все языки в CMS?

Для небольшой команды безопаснее редактировать в CMS только японский source, а переводы обновлять через PR.

ПоделитьсяX B!Добавить в Hatena Bookmarks

Генеральный директор Acecore. Руководит бизнес-системами, вебом, базами данных и инфраструктурой, качеством и внедрением ИИ от формулирования бизнес-задач до проектирования, запуска и дальнейшего улучшения. Опирается на практическую экспертизу C#/.NET и также учитывает PHP/JavaScript, SQL Server/PostgreSQL/MySQL и Linux/Windows Server, проектируя требования, технологический выбор, стандарты качества и GitHub-ориентированные процессы разработки как единую систему. Встраивает генеративный ИИ в процессы разработки, проверки и организации информации как практическую основу, помогающую небольшим командам быстрее и надежнее достигать результата.

Формулирование бизнес-задачТехнологический выборПроектирование системC#/.NETПроектирование БД/инфраструктурыGitHub-процессы разработкиГенеративный ИИПроектирование ИИ-процессовПроектирование качестваИнтеграция на местах

Хотите узнать больше о наших услугах?

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

Смотреть услуги Бесплатная консультация

Руководство по внедрению Sveltia CMS

Когда Sveltia CMS подходит

Общая архитектура

1. Разместить админку в `public/admin`

2. Настроить GitHub backend

3. Добавить OAuth Worker

4. Заранее определить папку медиа

5. Разделить collections

6. Использовать relation и select

7. Редактировать японские source JSON

8. Сохранять `main` веткой публикации и в preview

9. Создавать временные ветки через save proxy

10. Перевод только для CMS commits

11. Отдельный CSP для `/admin`

Turnstile отдельно

Уроки из PR и commit

Минимальная отправная точка

Ссылки

Итог

Комментарии

Gui

Похожие статьи

Спросить ИИ

Связанные материалы

Руководство по внедрению Sveltia CMS

Когда Sveltia CMS подходит

Общая архитектура

1. Разместить админку в public/admin

2. Настроить GitHub backend

3. Добавить OAuth Worker

4. Заранее определить папку медиа

5. Разделить collections

6. Использовать relation и select

7. Редактировать японские source JSON

8. Сохранять main веткой публикации и в preview

9. Создавать временные ветки через save proxy

10. Перевод только для CMS commits

11. Отдельный CSP для /admin

Turnstile отдельно

Уроки из PR и commit

Минимальная отправная точка

Ссылки

Итог

Комментарии

Gui

Похожие статьи

1. Разместить админку в `public/admin`

8. Сохранять `main` веткой публикации и в preview

11. Отдельный CSP для `/admin`