Ir para o conteúdo
Acecore

Guia de instalação do Sveltia CMS

by Gui
TecnologiaCMSAstroCloudflareSegurança
Índice
Guia de instalação do Sveltia CMS

Sveltia CMS é útil quando você quer adicionar uma tela de edição a um site estático sem mover conteúdo para um banco externo. Este guia resume como ele foi introduzido no site Astro da Acecore e quais ajustes aprendemos com PRs e commits reais.

Atualizado em 28 de julho de 2026: os salvamentos do CMS agora são validados de forma síncrona e gravados como um único commit cms: direto em main. GitHub OAuth confirma o editor e sua permissão atual; uma GitHub App exclusiva de acecore-net executa as operações do repositório. Schemas JSON/Markdown, assinaturas de imagem, HTML/URLs ativos e o HEAD esperado são verificados antes da gravação.

O título é simples de propósito: Guia de instalação do Sveltia CMS. A meta é ajudar quem quer usar o CMS em outro site, não comparar ferramentas de forma abstrata.

Quando usar Sveltia CMS

Sveltia CMS não controla um banco de dados próprio nem entrega conteúdo por API separada. Ele é um app de administração em SPA que edita arquivos do repositório por meio do GitHub backend.

Ele combina bem quando:

  • o conteúdo vive como Markdown ou JSON no repositório
  • mudanças de artigo, autor, tag e textos de página devem ser revisadas como Git diff
  • você não quer adicionar banco de dados ou serviço administrativo separado
  • uploads podem ficar em public/uploads
  • salvamentos do CMS devem iniciar a publicação imediatamente, enquanto mudanças de código continuam protegidas por Pull Request

Se você precisa de permissões editoriais complexas, publicação agendada avançada, grande DAM ou edição em tempo real, um headless CMS completo pode ser melhor.

Arquitetura geral

public/admin/index.html
  -> carrega @sveltia/cms via CDN

public/admin/config.yml
  -> define GitHub backend, collections e pastas de mídia

workers/sveltia-cms-auth
  -> Cloudflare Worker para GitHub OAuth

main branch
  -> única fonte de verdade para produção

CMS save proxy
  -> valida caminhos e conteúdo e grava um commit cms: com expected HEAD em main

.github/workflows/create-translation-prs.yml
  -> cria tarefas de tradução apenas para commits cms:

Instalar a página de admin é só a primeira etapa. Autenticação, mídia, preview, tradução e merge strategy precisam ser parte do desenho.

1. Colocar o admin em public/admin

No Astro, arquivos em public são servidos como estáticos. A documentação do Sveltia CMS também aponta public como pasta estática para Astro, Next.js, Nuxt, Remix e VitePress.

<!doctype html>
<html lang="pt">
  <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>

Não adicione CSS extra ou type="module" sem motivo. O bundle do Sveltia CMS já inclui os estilos da UI.

Na Acecore usamos inicialização manual para configurar o backend explicitamente. A branch de publicação permanece main em todos os ambientes.

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

2. Configurar GitHub backend

O mínimo é backend.name e backend.repo, mas em produção defina também branch, OAuth e mensagens de 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}}"'

Mantenha main como branch de publicação e encaminhe leituras e salvamentos por um proxy same-origin. Antes de cada save, o proxy revalida a permissão de escrita do usuário GitHub, usa uma GitHub App instalada apenas em acecore-net para acessar o repositório e valida caminhos, conteúdo e o HEAD mais recente de main antes de criar um único commit direto.

Em 20 de julho de 2026, o Editorial Workflow ainda não está implementado no Sveltia CMS. Adicionar a opção do Decap CMS publish_mode: editorial_workflow não faz o Sveltia CMS criar branches temporárias ou PRs automaticamente.

Uma branch permanente como cms-content exige sincronização contínua e aumenta o risco de conflitos ou de configurar a origem de deploy incorretamente. A Acecore mantém main como única fonte de verdade e rejeita atualizações concorrentes com expectedHeadOid.

3. Adicionar OAuth Worker

Personal Access Token é suficiente para teste, mas não é a melhor opção para vários editores. A Acecore usa Sveltia CMS Authenticator em Cloudflare Workers e aponta base_url para esse Worker.

O callback do GitHub OAuth App aponta para /callback no Worker. O Worker recebe GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET e, se necessário, ALLOWED_DOMAINS.

Isso é diferente de Turnstile. OAuth protege login do CMS; Turnstile protege formulários ou APIs contra bots.

4. Definir a pasta de mídia cedo

Sveltia CMS pode salvar mídia dentro do repositório. Em Astro, o caminho prático é:

media_folder: public/uploads
public_folder: /uploads

A Acecore corrigiu esse ponto depois no PR #116. A lição é decidir o caminho no repositório e a URL pública antes dos primeiros uploads.

5. Separar collections

collectionAlvoPolítica
blogsrc/content/blog/*.mdEditar só artigos fonte em japonês
authorssrc/content/authors/*.jsonEditar perfis e nomes localizados
tagssrc/content/tags/*.jsonEditar tags e nomes localizados
page textsrc/i18n/source/ja/**/*.jsonEditar texto fonte japonês de páginas e UI

Não exponha todos os Markdown traduzidos sem necessidade. A Acecore mantém o japonês como fonte canônica e atualiza traduções por Como operar um blog multilíngue com Sveltia CMS.

6. Usar relation e select

Tags devem ser selecionadas por relation, não digitadas livremente.

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

Autores, ícones e tons de aviso seguem a mesma lógica. CMS bom não só permite editar; ele dificulta salvar valores quebrados.

7. Editar JSON fonte em japonês

Textos fixos também podem entrar no CMS. A Acecore centraliza a fonte japonesa em src/i18n/source/ja/**/*.json e expõe por página.

O cuidado é não adicionar todos os campos de uma vez. config.yml cresce rapidamente. Comece por blog, autores, tags, avisos e páginas que mudam com frequência.

8. Manter credenciais de escrita somente em produção

Configure o client ID, installation ID e private key da GitHub App somente no ambiente de produção do Cloudflare Pages. Previews não recebem credenciais de escrita e permanecem sem leitura ou escrita no repositório. O conteúdo é salvo e publicado apenas pelo /admin/ de produção; previews ficam para PRs normais de código ou configuração.

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

9. Validar e publicar diretamente com o proxy

Um proxy same-origin valida de forma síncrona o escopo e o conteúdo permitidos e cria exatamente um commit em main.

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

GitHub OAuth verifica novamente o editor e sua permissão de escrita antes do save. Um token curto da GitHub App exclusiva de acecore-net faz as leituras e gravações. Só conteúdo e imagens permitidos são aceitos; SVG e PDF são rejeitados.

O save usa o HEAD inicial como expectedHeadOid; uma atualização concorrente retorna 409. Se a resposta do GitHub se perder, só há recuperação quando marker da request, SHA pai, todos os paths e SHAs dos blobs coincidem.

O commit direto mantém subjects como cms: create ... e cms: update .... O mesmo push da GitHub App inicia Pages e a tarefa de tradução. Código, schemas, workflows, configuração CMS e traduções continuam passando por PR e CI.

10. Tradução só para commits CMS

O PR #98 adicionou --cms-only, para que tarefas de tradução por push só sejam criadas com commits CMS.

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

cms: é um contrato de workflow, não decoração.

11. CSP próprio para /admin

O admin precisa conectar ao CDN, GitHub API, OAuth Worker e blob URLs. Por isso, a Acecore separa a CSP de /admin/* e marca a área como noindex.

Separar Turnstile

A versão antiga misturava seleção de CMS e Cloudflare Turnstile. Isso confundia o assunto.

Sveltia CMS trata de backend GitHub, OAuth, collections, mídia e PRs. Turnstile trata de reduzir bots em formulários ou APIs. São camadas diferentes.

Lições de PRs e commits

  • Ao mudar o CMS, atualize também artigos e links internos.
  • OAuth deve fazer parte do setup real.
  • Caminhos de mídia devem ser definidos antes de uploads.
  • config.yml deve crescer por etapas.
  • cms: é contrato de automação.
  • As credenciais de escrita ficam somente em produção; preview serve sem acesso ao repositório para PRs normais de código e configuração.

Ponto inicial mínimo

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

Depois adicione relations de autores e tags, imagens, JSON fonte, validação síncrona de direct publish e tarefas de tradução.

Referências

Resumo

Sveltia CMS é simples de colocar em public/admin, mas a instalação de produção exige decidir branch, OAuth, pastas de mídia, política de idioma fonte, workflow de tradução e merge strategy. Com essas regras claras, um site Astro continua estático e leve, mas ganha uma operação de conteúdo muito mais utilizável.

Fluxo de instalação do Sveltia CMS

A área administrativa, autenticação, conteúdo editável, mídia e fluxo de PR devem ser pensados separadamente.

Adicionar o admin

Coloque index.html e config.yml em public/admin e carregue o Sveltia CMS.

Configurar GitHub

Defina repo, branch, OAuth Worker e mensagens de commit antes de começar a editar.

Limitar o escopo editável

Exponha apenas blog, autores, tags e JSON fonte em japonês que devem ser editados pelo CMS.

Automatizar a operação

Use main como branch de publicação e conecte commits diretos validados, deploys do Pages e tarefas de tradução.

Antes e depois do CMS

Markdown editado manualmente

  • Só quem usa GitHub ou editor atualiza com facilidade
  • Caminhos de imagem, IDs de autor e tags são digitados à mão
  • Fonte japonesa e traduções podem ser misturadas
  • O destino de salvamento e os caminhos graváveis podem ficar ambíguos

Edição com Sveltia CMS

  • Markdown e JSON são editados em formulários no navegador
  • relation, image e select reduzem valores inválidos
  • Apenas commits de CMS disparam tarefas de tradução
  • Um proxy same-origin valida o conteúdo permitido e grava um commit direto em main
Checklist de instalação
  • Concluído: Carregar Sveltia CMS em public/admin/index.html
  • Concluído: Definir GitHub backend e collections em public/admin/config.yml
  • Concluído: Usar OAuth Worker para edição por várias pessoas
  • Concluído: Alinhar media_folder e public_folder ao diretório public do Astro
  • Concluído: Decidir como commits de CMS acionam tradução ou publicação
Perguntas frequentes
Para que tipo de site o Sveltia CMS serve?
Ele funciona bem para sites estáticos onde Markdown ou JSON ficam no repositório, como Astro, Hugo e VitePress. Assim é possível adicionar CMS sem banco de dados externo.
Posso usar só um Personal Access Token do GitHub?
Pode, mas para várias pessoas ou editores não técnicos, um OAuth Worker é mais seguro e fácil de explicar. A Acecore usa Cloudflare Worker como cliente OAuth.
Devo editar todos os idiomas no CMS?
Em uma equipe pequena, é mais seguro editar apenas a fonte japonesa e atualizar traduções por PR. Expor todos os idiomas dificulta revisão e detecção de traduções desatualizadas.
CompartilharX(abre em nova aba)B!Adicionar ao Hatena Bookmark(abre em nova aba)

Comentários

Carregando comentários...

Links, e-mails e textos promocionais não podem ser publicados.

G

Gui

CEO da Acecore. Lidera sistemas de negócio, web, bancos de dados e infraestrutura, qualidade e adoção de IA da definição de problemas de negócio ao design, implantação e melhoria após o lançamento. Parte de capacidade prática em C#/.NET e também cobre PHP/JavaScript, SQL Server/PostgreSQL/MySQL e Linux/Windows Server, desenhando requisitos, escolhas tecnológicas, padrões de qualidade e operações de desenvolvimento baseadas em GitHub como um fluxo único. Incorpora IA generativa a processos de desenvolvimento, verificação e organização de informações, como uma base prática para que equipes pequenas entreguem mais rápido e com maior confiabilidade.

Definição de problemas de negócioSeleção tecnológicaDesign de sistemasC#/.NETDesign de bancos de dados/infraestruturaOperações de desenvolvimento no GitHubIA generativaDesign de fluxos de IADesign de qualidadeIntegração em campo

Quer saber mais sobre nossos serviços?

Oferecemos suporte abrangente em desenvolvimento de sistemas, design web, operações de servidores e design gráfico.

Ver serviçosConsulta gratuita

Artigos relacionados

Como projetar um site Astro + Cloudflare que cresce por funcionalidadeComo projetar um site Astro + Cloudflare que cresce por funcionalidade7 de junho de 2026 às 19:00
TecnologiaAstroCloudflare
Como adicionar comentários a um blog Astro usando apenas CloudflareComo adicionar comentários a um blog Astro usando apenas Cloudflare7 de junho de 2026 às 18:00
TecnologiaCloudflareAstro
Renderizar links Markdown com segurança em respostas de chat com IARenderizar links Markdown com segurança em respostas de chat com IA7 de junho de 2026 às 14:30
TecnologiaSiteIA
O que era a antiga opção SSL paga da Cloudflare — de Dedicated SSL para Advanced Certificate ManagerO que era a antiga opção SSL paga da Cloudflare — de Dedicated SSL para Advanced Certificate Manager31 de março de 2026
TecnologiaCloudflareSegurança
Pesquisar no site

Após você inserir pelo menos dois caracteres, Conteúdo relacionado envia automaticamente seus termos de pesquisa ao Cloudflare Workers AI. Não insira informações pessoais ou confidenciais.Como os dados de pesquisa são tratados