Configuração da marca da empresa#
A marca permite adaptar o Sherpa AI Server ao estilo da empresa e escolher a navegação para seus Usuários.
Configurando branding.json no Sherpa AI Server#
O arquivo branding.json permite alterar a aparência e a navegação sem modificar o código-fonte.
Finalidade#
Este artigo é destinado ao administrador que altera a aparência de uma instalação do Sherpa AI Server. A configuração é feita por um arquivo no servidor. Os comandos Docker fazem o servidor web carregar esse arquivo em vez da configuração padrão. A interface não possui um editor de branding.json.
O arquivo branding.json altera a aparência e parte do comportamento sem recompilar a interface web:
- nome e logotipos;
- cores principais, raio dos cantos e fonte;
- plano de fundo das mensagens do usuário e do Assistente;
- idioma padrão e idiomas disponíveis;
- exibição do botão de login com OpenID;
- exibição do seletor de Chats compartilhados e pessoais no painel lateral;
- links adicionais no menu lateral;
- um botão de informação na página de login.
As configurações são aplicadas no navegador quando a aplicação é carregada.
Onde o arquivo fica#
A localização do arquivo permite identificar a configuração correta para o desenvolvimento ou o sistema instalado.
No código-fonte#
O caminho no código-fonte permite preparar a marca durante o desenvolvimento.
Arquivo principal:
frontend/src/assets/branding/branding.json
Ele faz parte da build do frontend e é usado como o conjunto padrão de configurações para a distribuição.
Na distribuição do cliente#
O arquivo da distribuição do cliente permite alterar a marca da aplicação instalada.
Ao preparar o pacote do cliente, o arquivo é copiado para este local:
frontend/config/branding.json
Para usar a configuração do cliente, é necessário conectar frontend/config/branding.json ao contêiner aiserver-nginx com esta entrada em docker-compose.yml:
services:
aiserver-nginx:
volumes:
- ./frontend/config/branding.json:/opt/SherpaAIServer/frontend/dist/assets/branding/branding.json:ro
No docker-compose.yml distribuído, essa linha pode estar comentada. Depois de habilitar a montagem pela primeira vez, recrie o contêiner:
docker compose up -d --force-recreate aiserver-nginx
Após alterar um arquivo já conectado, é necessário atualizar a página e verificar se o servidor fornece a nova configuração. Se ele ainda fornecer o arquivo antigo, é necessário recriar aiserver-nginx com o mesmo comando.
Como a configuração é carregada#
A ordem de carregamento permite verificar qual configuração o navegador recebe após a alteração do arquivo.
Quando o frontend inicia, ele solicita:
/assets/branding/branding.json
As configurações são carregadas antes de abrir a interface. O idioma, os logotipos, as cores e a fonte selecionados são aplicados desde o início.
Regras de carregamento:
- Os valores embutidos do Sherpa AI Server são usados como base.
- Os campos de
branding.jsonsubstituem os valores embutidos correspondentes. - Se o arquivo não estiver disponível ou contiver JSON inválido, a aplicação continua funcionando com os valores embutidos.
- Os campos de nível superior ausentes não precisam ser informados: os valores embutidos são mantidos para eles.
- Objetos aninhados e itens de arrays devem ser definidos por completo. Exceção: os campos de primeiro nível de
chat_model_picker_textsão completados com os valores padrão.
O campo _comments dentro do branding.json padrão contém descrições de referência. É um campo auxiliar normal de JSON. A interface não o utiliza.
As configurações pessoais de aparência salvas no navegador têm prioridade sobre cores, fontes, logotipos e fundos de mensagens do arquivo do servidor. Para verificar as configurações do servidor sem essas alterações, é necessário abrir o Sherpa AI Server em outro perfil do navegador.
Início rápido#
O início rápido permite aplicar seu próprio nome e estilo à aplicação instalada.
Para aplicar a configuração, é necessário realizar as seguintes etapas:
Faça uma cópia de
frontend/config/branding.jsone depois prepare ou edite o arquivo de trabalho.Verifique se o bind mount está habilitado em
docker-compose.yml.Confira a sintaxe do JSON:
jq empty frontend/config/branding.jsonAo conectar o arquivo pela primeira vez, recrie o
aiserver-nginx:docker compose up -d --force-recreate aiserver-nginxVerifique qual arquivo o servidor está fornecendo:
Substitua
ai.example.orgpelo endereço da sua instalação.curl -fsS https://ai.example.org/assets/branding/branding.json | jq .Recarregue a página do Sherpa AI Server. Se o navegador mostrar recursos antigos, faça uma atualização completa.
Exemplo completo#
O exemplo define o nome "Корпоративный AI", logotipos para os temas claro e escuro, botões azuis e a fonte Inter. Antes de aplicar, é necessário preparar os logotipos e substituir o endereço de suporte pelo da sua organização. Os parâmetros são adicionados ao arquivo de trabalho preservando os demais ajustes em uso.
{
"app_name": "Корпоративный AI",
"logo_url": "assets/branding/logo-light-v1.svg",
"logo_url_light": "assets/branding/logo-light-v1.svg",
"logo_url_dark": "assets/branding/logo-dark-v1.svg",
"favicon_url": "favicon.ico",
"disable_openid": false,
"hide_chat_scope_switch": false,
"hide_language_selector": false,
"hide_unavailable_menu_items": false,
"auto_expand_sidebar_sections": false,
"default_language": "ru",
"available_languages": ["ru", "en"],
"additional_menu_items": [
{
"button_name": {
"ru": "Поддержка",
"en": "Support"
},
"url": "https://support.example.org",
"icon": "question-mark-circle-outline"
},
{
"button_name": {
"ru": "Инструкции",
"en": "Documentation"
},
"url": "/main/documents",
"icon": "book-open-outline"
}
],
"additional_login_button": {
"button_name": {
"ru": "Как получить доступ?",
"en": "How do I get access?"
},
"message": {
"ru": "Для получения доступа обратитесь в службу поддержки.",
"en": "Contact the support team to request access."
}
},
"primary_color": "#2563eb",
"primary_dark_color": "#1d4ed8",
"primary_light_color": "#60a5fa",
"primary_rgb": "37, 99, 235",
"secondary_color": "#1f2937",
"border_radius": "8px",
"font_family": "Inter, sans-serif",
"font_url": "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap",
"chat_user_bg": "#eff6ff",
"chat_assistant_bg": "#ffffff"
}
Descrição dos parâmetros#
Esta tabela de referência descreve os principais parâmetros do arquivo, não campos de formulário. Ela complementa os exemplos de comandos e JSON deste artigo.
| Parâmetro | Formato | Finalidade |
|---|---|---|
app_name |
string | Nome no menu lateral, texto alt do logotipo e título da aba (<title>). |
logo_url |
string de URL | Logotipo de fallback por compatibilidade. Usado se um logotipo separado para o tema necessário não estiver definido. |
logo_url_light |
string de URL | Logotipo para o tema claro. |
logo_url_dark |
string de URL | Logotipo para o tema escuro. |
favicon_url |
string de URL | Ícone da aba do navegador. Caminho relativo no frontend ou URL absoluta. Padrão favicon.ico. |
disable_openid |
true ou false |
Quando true, oculta o botão "Login with OpenID" na página de login. O parâmetro controla a interface e, por si só, não desativa o OpenID no backend. |
hide_chat_scope_switch |
true / false |
Com true, oculta o seletor de chats Compartilhados / Pessoais na barra lateral normal e compacta. Padrão false. O tipo de login continua determinando a lista. |
hide_language_selector |
true / false |
Com true, oculta o seletor de idioma na página de login e no cabeçalho. Padrão false. |
hide_unavailable_menu_items |
true / false |
Com true, oculta itens de menu indisponíveis para a função do Usuário. Padrão false, que os exibe desativados. |
auto_expand_sidebar_sections |
true / false |
Com false, as seções Chat, Assistentes e API não se expandem automaticamente ao entrar nem ao navegar entre telas. É possível expandi-las manualmente. O padrão é true: as seções são expandidas automaticamente. |
default_language |
ru ou en |
Idioma padrão. O valor deve estar presente em available_languages. |
available_languages |
array de ru e/ou en |
Idiomas disponíveis para o usuário. Outros valores são descartados. |
additional_menu_items |
array de objetos | Itens permanentes adicionais no menu lateral antes da seção Chat. |
additional_login_button |
objeto ou null |
Botão de informação na página de login. Ao clicar, abre uma caixa de diálogo com texto localizado. null oculta o botão. |
primary_color |
#RRGGBB |
Cor principal para botões, links, elementos ativos, tabelas e controles de formulário. |
primary_dark_color |
#RRGGBB |
Tom mais escuro da cor principal para estados de hover e pressionado e alguns seletores. |
primary_light_color |
#RRGGBB |
Tom mais claro para realces e estados secundários. |
primary_rgb |
string R, G, B |
Componentes RGB de primary_color para fundos translúcidos, sombras e realces. |
secondary_color |
cor CSS | Cor secundária. Também é usada nas superfícies dos cartões no tema escuro e na tela de abertura. |
border_radius |
tamanho CSS | Arredondamento dos elementos, por exemplo 0px, 6px ou 16px. |
font_family |
font-family CSS |
Família de fonte aplicada à interface. |
font_url |
URL de arquivo CSS | Folha de estilo da qual o navegador carrega a fonte. Uma string vazia desativa o download adicional. |
chat_user_bg |
cor CSS | Fundo das mensagens do usuário na tela Chat. |
chat_assistant_bg |
cor CSS | Fundo das respostas do Assistente na tela Chat. |
home_featured_cards |
array de objetos | Cartões principais do Início. O formato e os valores padrão estão descritos em Cartões do Início. |
Ocultar o seletor de tipo de chat#
Para ocultar o seletor de chats Compartilhados / Pessoais na barra lateral, configure no branding.json:
{
"hide_chat_scope_switch": true
}
Isso altera apenas a visibilidade do seletor. O login de um Usuário continua abrindo os chats pessoais. O login de uma Conta abre os chats compartilhados. Para restaurar o seletor, defina false ou remova o parâmetro e recarregue a página.
Configuração dos logotipos#
Logotipos separados permitem manter a marca legível nos temas claro e escuro.
Prioridade de seleção do logotipo para cada tema:
logo_url_light или logo_url_dark → logo_url → встроенный логотип
Os logotipos dos dois temas já são definidos por padrão. Para substituí-los, é necessário definir logo_url_light e logo_url_dark. Alterar apenas logo_url não substitui os logotipos de cada tema.
É possível usar:
- um caminho relativo dentro do frontend, por exemplo
assets/branding/logo-light-v1.svg; - um caminho absoluto a partir da raiz do site, por exemplo
/assets/branding/logo-light-v1.svg; - uma URL absoluta, por exemplo
https://static.example.org/logo-light-v1.svg.
Se o logotipo estiver armazenado junto com a configuração do cliente, monte-o separadamente em docker-compose.yml:
services:
aiserver-nginx:
volumes:
- ./frontend/config/branding.json:/opt/SherpaAIServer/frontend/dist/assets/branding/branding.json:ro
- ./frontend/config/logo-light-v1.svg:/opt/SherpaAIServer/frontend/dist/assets/branding/logo-light-v1.svg:ro
- ./frontend/config/logo-dark-v1.svg:/opt/SherpaAIServer/frontend/dist/assets/branding/logo-dark-v1.svg:ro
O navegador pode manter imagens e fontes anteriores em cache. Quando o conteúdo do logotipo mudar, use um novo nome, por exemplo logo-light-v2.svg, e atualize o caminho em branding.json.
Defina favicon_url para o ícone da aba do navegador. Se usar um arquivo próprio, garanta que sua URL seja acessível pelos navegadores e, se necessário, monte-o no contêiner nginx como os logotipos. Use um novo nome de arquivo ao alterar o ícone para evitar versões em cache.
Configuração das cores#
As cores permitem adaptar os botões e outros destaques da interface ao estilo da empresa.
primary_color e primary_rgb descrevem a mesma cor em formatos diferentes. Eles não são sincronizados automaticamente.
Exemplo:
{
"primary_color": "#2563eb",
"primary_rgb": "37, 99, 235"
}
Para primary_color, primary_dark_color e primary_light_color, use o formato HEX completo #RRGGBB. O serviço calcula o contraste da cor principal para o texto e os ícones, portanto não se deve usar HEX abreviado nem valores rgb(...) ou rgba(...) para esses três campos.
Para secondary_color, chat_user_bg e chat_assistant_bg, cores CSS normais, como HEX ou rgba(...), são permitidas.
Depois de alterar as cores, verifique os dois temas, tabelas, campos de formulário, botões e a legibilidade das mensagens no chat.
Configuração da fonte#
As configurações de fonte permitem usar a tipografia corporativa na interface.
font_url deve apontar para um arquivo CSS com a fonte, e font_family deve apontar para o nome da família nesse arquivo CSS:
{
"font_family": "Inter, sans-serif",
"font_url": "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
}
Para uma fonte personalizada, é possível montar o CSS e os arquivos da fonte no diretório frontend e usar uma URL relativa. Certifique-se de que a URL esteja acessível nos navegadores dos usuários, e não apenas no backend do Sherpa AI Server.
Para não carregar um arquivo CSS adicional, deixe font_url vazio:
{
"font_family": "Roboto, 'Helvetica Neue', sans-serif",
"font_url": ""
}
Idiomas da interface#
As configurações de idioma permitem escolher as traduções disponíveis aos Usuários e o idioma padrão.
Somente os valores ru e en são suportados.
Se available_languages estiver vazio, tiver um formato inválido ou não contiver valores suportados, o Sherpa AI Server habilita os dois idiomas. Se default_language não estiver presente na lista de idiomas disponíveis, o primeiro item de available_languages se torna o idioma padrão.
Exemplo de uma interface somente em russo:
{
"default_language": "ru",
"available_languages": ["ru"]
}
O botão do idioma atual continua visível, mas o menu de troca não é aberto.
O idioma real é selecionado na seguinte ordem:
- o parâmetro
langoulocalena URL; - o idioma escolhido anteriormente no navegador;
default_languagedebranding.json.
O valor da URL ou do navegador só é aplicado quando o idioma está presente em available_languages.
Para ocultar o botão de idioma na página de login e no cabeçalho, defina "hide_language_selector": true. Mantenha false se os Usuários precisarem alternar o idioma.
Exibição de seções indisponíveis#
A visibilidade dos itens indisponíveis permite concentrar a navegação nas telas às quais o Usuário tem acesso.
O parâmetro hide_unavailable_menu_items altera a visibilidade do menu esquerdo, não as permissões da Função. Com true, as seções indisponíveis ficam ocultas. Com false, permanecem visíveis, mas inativas.
Itens adicionais do menu#
Os itens adicionais do menu oferecem links permanentes para suporte e outros recursos úteis junto à navegação principal.
O parâmetro additional_menu_items adiciona links permanentes ao menu lateral. No exemplo, "Поддержка" abre o site de suporte. Cada item utiliza estes parâmetros:
{
"button_name": {
"ru": "Поддержка",
"en": "Support"
},
"url": "https://support.example.org",
"icon": "question-mark-circle-outline"
}
Regras:
- pelo menos uma tradução não vazia do nome é necessária;
urldeve ser um caminho interno com apenas uma/inicial ou uma URL com o protocolohttpouhttps;- valores com outros protocolos e URLs inválidas são ignorados;
- links internos são abertos pelo roteador do Sherpa AI Server;
- links externos são abertos na aba atual;
- os itens são exibidos na mesma ordem em que aparecem no array;
- para um ícone padrão, informe um nome de Eva Icons, por exemplo
book-open-outline; - uma string que contenha
/ou termine em.svgé interpretada como um caminho para um ícone SVG personalizado.
Se faltar uma tradução, primeiro é usado o russo e depois o inglês.
Botão de informação na página de login#
Um botão informativo na página de acesso indica ao Usuário onde obter ajuda antes de entrar no Sherpa AI Server.
O parâmetro additional_login_button adiciona um botão informativo à página de login. No exemplo, "Forgot your password?" exibe uma mensagem para entrar em contato com o suporte. Ele não altera a senha nem inicia sua recuperação.
{
"additional_login_button": {
"button_name": {
"ru": "Забыли пароль?",
"en": "Forgot your password?"
},
"message": {
"ru": "Обратитесь в службу поддержки.",
"en": "Contact the support team."
}
}
}
O botão é exibido se houver pelo menos um nome e pelo menos um texto de mensagem preenchidos. O texto é exibido como texto simples, não como HTML. Para traduções ausentes do botão, a interface usa a versão russa e, depois, a inglesa.
Para ocultar o botão informativo, é necessário definir additional_login_button como null:
{
"additional_login_button": null
}
Cartões da página inicial#
Os cartões da página inicial permitem colocar as seções necessárias aos Usuários na tela inicial.
O parâmetro home_featured_cards define os cartões de "Get started" no Início. A ordem segue o array e não é limitada a quatro cartões. Para adicionar, excluir ou renomear um cartão, é necessário editar o array no branding.json do cliente e atualizar a página.
O exemplo define um cartão de chat. Adicione este campo à configuração existente, mantendo as outras opções:
{
"home_featured_cards": [
{
"id": "chat",
"title": { "ru": "Чат", "en": "Chat" },
"description": { "ru": "Новый диалог", "en": "New conversation" },
"icon": "message-circle-outline",
"action": { "type": "route", "url": "/main/new-chat" }
}
]
}
Para cada cartão, informe um id exclusivo, title e description não vazios em ru e en, um nome de icon e uma ação action. A ação route abre uma rota interna acessível. A ação assistant com assistant_guid abre um novo chat com esse Assistente. Obtenha o GUID de um Assistente existente e acessível.
Um array válido substitui completamente o conjunto padrão. Se o campo estiver ausente, for null, contiver um array vazio ou cartões inválidos, serão usados os cartões integrados ao aplicativo. Um array vazio não oculta todos os cartões. As seções indisponíveis pelas permissões são filtradas. Um cartão com a ação assistant aparece apenas com permissão de leitura para Chat e Assistentes. Essa opção não altera as permissões do perfil nem o acesso aos Assistentes.
Os Assistentes fixados são adicionados automaticamente após os cartões de home_featured_cards. Esse parâmetro não controla quais Assistentes estão fixados. Se um Assistente já estiver na configuração, um segundo cartão não será exibido.
Se as alterações não aparecerem, verifique a sintaxe JSON, o arquivo carregado e as permissões da conta. Se o GUID de um Assistente for inválido, corrija-o na configuração. Não há um editor de cartões separado na interface.
Página HTML do cliente no lugar da página inicial#
Um administrador pode substituir o conteúdo da página inicial protegida por um único arquivo HTML. O cabeçalho, o menu lateral, a saída e as permissões da Função permanecem. A página fica visível para todos que podem abrir a página inicial. Não inclua segredos nem dados pessoais no arquivo.
Prepare um arquivo
frontend/config/custom-home/index.html. Coloque o conteúdo visível embodye os estilos em um elementostyleemheadou em atributosstyle. Exemplo:<!doctype html> <html lang="pt-BR"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <style>.client-home { max-width: 1200px; margin: auto; padding: 24px; }</style> </head> <body> <main class="client-home"> <h1>Boas-vindas</h1> <a href="/main/new-chat">Abrir o Chat</a> </main> </body> </html>Em
docker-compose.yml, adicione uma montagem somente leitura ao serviçoaiserver-nginx:services: aiserver-nginx: volumes: - ./frontend/config/custom-home/index.html:/opt/SherpaAIServer/frontend/dist/assets/custom-home/index.html:roAdicione o campo ao arquivo
frontend/config/branding.jsonexistente, mantendo as outras configurações:{ "home_html_path": "/assets/custom-home/index.html" }Ao ativar a montagem pela primeira vez, recrie o contêiner nginx com
docker compose up -d --force-recreate aiserver-nginx. Entre no sistema e abra/main/home. Depois de substituir o conteúdo do arquivo, atualize a página. O HTML é servido sem cache.

Exemplo de página HTML do cliente na página inicial. Interface em russo.
O caminho deve começar com /assets/custom-home/ e terminar com um nome de arquivo HTML, sem subdiretórios. URLs externas, parâmetros de consulta e .. não são aceitos. A página do cliente não deve usar JavaScript, formulários, iframe, estilos, fontes ou imagens externas, nem requisições de rede em CSS. Se precisar de ilustrações, incorpore SVG ou imagens pequenas data:image/png, data:image/jpeg ou data:image/webp no mesmo HTML. Os elementos e estilos incorporados são sanitizados. O arquivo deve se adaptar à área de conteúdo em celulares, tablets e computadores, sem rolagem horizontal.
Use links comuns /main/... para as seções do Sherpa AI Server. Eles abrem no aplicativo com as verificações de permissão habituais. Se a configuração estiver ausente, o caminho for inválido ou o arquivo estiver indisponível, a página inicial padrão será exibida. Para reverter, remova home_html_path ou defina null e atualize a página. Depois, a montagem pode ser removida.