Pronto para contribuir para abrir o webui? Vamos começar! 🚀

Animado para mergulhar no desenvolvimento aberto da Webui? Este guia abrangente o levará a configurar seuambiente de desenvolvimento localrápido e facilmente. Seja você um desenvolvedor experiente ou apenas começando, vamos preparar -se para ajustar o front -end, aprimorar o back -end e contribuir para o futuro do Nullcore! Vamos colocar seu ambiente de desenvolvimento em funcionamento e execução em etapas simples e detalhadas!

Pré -requisitos

Antes de começar, verifique se seu sistema atende a esses requisitos mínimos:

Sistema operacional:Linux (ou WSL no Windows), Windows 11 ou MacOS.(Recomendado para a melhor compatibilidade)
Python:Versão3.11 ou superior(Necessário para serviços de back -end)
Node.js:Versão22.10 ou superior(Necessário para o desenvolvimento do front -end)
IDE (recomendado):Recomendamos usar um IDE comoVscodepara edição de código, depuração e acesso ao terminal integrado. Sinta -se à vontade para usar seu IDE favorito, se você tiver um!
[Opcional] Github Desktop:Para facilitar o gerenciamento do repositório Git, especialmente se você estiver menos familiarizado com o GIT da linha de comando, considere instalarDesktop do Github

Configurando seu ambiente local

Configuraremos o front -end (interface do usuário) e o back -end (lógica da API e do servidor) do Webui aberto.

1. Clone o repositório

Primeiro, usegit clonePara baixar o repositório Nullcore para sua máquina local. Isso criará uma cópia local do projeto no seu computador.

Abra seu terminal(ou Bash Git se você estiver no Windows e usando o Git Bash).
Navegue até o diretórioOnde você deseja armazenar o projeto Nullcore.
Clone o repositório:Execute o seguinte comando:

Git clone https://doc.nullcore.com.br.git
CD Open-Webui

Ogit clonecomando baixar os arquivos do projeto do github. Ocd open-webuiO comando então navega no diretório do projeto recém -criado.

2. Configuração do front -end (interface do usuário)

Vamos colocar a interface do usuário (o que você vê no seu navegador) em funcionamento primeiro:

Configurar variáveis de ambiente:
- Copie o arquivo de ambiente de exemplo para.env
```
cp -rpp .env.example .env
```
  Este comando copia o.env.examplearquivo para um novo arquivo nomeado.env. O.envO arquivo é onde você configura variáveis de ambiente para o front -end.
- Personalizar.env: Abra o.envArquivo no seu editor de código (como o VSCode). Este arquivo contém variáveis de configuração para o front -end, como pontos de extremidade da API e outras configurações. Para o desenvolvimento local, as configurações padrão em.env.examplegeralmente são suficientes para começar. No entanto, você pode personalizá -los, se necessário.

Importante:Não cometê informações confidenciais para.envSe você estiver contribuindo de volta para o repositório.

Instale as dependências do front -end:
- Navegue até o diretório de front -end:Se você ainda não está na raiz do projeto (open-webuidiretório), verifique se você está lá.
```
# Se você não estiver na raiz do projeto, execute:
CD Open-Webui
```
- Instale os pacotes JavaScript necessários:
```
NPM Instale
```
  Isso instalará todas as dependências de front -end listadas empackage.json
  
  NOTA: Dependendo da sua versão Nullcore, você pode ver avisos ou erros de compatibilidade. Se sim, basta correr:
```
NPM Instale -Force
```
  Algumas configurações precisam disso para contornar os problemas da versão.
Inicie o servidor de desenvolvimento de front -end:
```
NPM Run Dev
```
Este comando inicia o servidor de desenvolvimento de front -end. Se as etapas foram seguidas com sucesso, geralmente indicará que o servidor está em execução e fornece um URL local.

Acesse o front -end:Abra seu navegador da web e vá parahttp: // localhost: 5173. Você deve ver uma mensagem indicando que o front -end do Nullcore está em execução e está esperando o back -end estar disponível. Não se preocupe com essa mensagem ainda! Vamos configurar o back -end a seguir.Mantenha este terminal funcionando- Está servindo seu front -end!

2.5: Construa o front -end (recomendado)

Depois de verificar se o servidor de desenvolvimento de front -end (npm run dev) está funcionando corretamente e você pode ver o Nullcore emhttp: // localhost: 5173, é umBoa prática para também construir os ativos de front -end. Esta etapa simula o ambiente de produção e pode ajudar a capturar erros de tempo de construção que não aparecem durante o desenvolvimento.

No mesmo terminal de front -end:

NPM Run Build

Este comando gera uma construção otimizada e pronta para produção do front-end e coloca os arquivos estáticos nobuilddiretório.
Se a construção concluir com sucesso (sem erros), você estará pronto! Se houver erros, aborde -os antes de prosseguir.
Você não precisa fazer mais nada combuildPara o desenvolvimento local, mas a construção garante que seu código não seja dividido na produção ou durante a implantação.

3. Configuração de back -end (API e servidor)

NósexigirVocê usa instâncias de terminais separadas para seus processos de front -end e back -end. Isso mantém seus fluxos de trabalho organizados e facilitam o gerenciamento de cada parte do aplicativo de forma independente.

Usando terminais integrados do VSCode:

O recurso de terminal integrado do VSCODE torna incrivelmente fácil o gerenciamento de vários terminais. Veja como alavancá -lo para separação de front -end e back -end:

Terminal front -end (você provavelmente já tem isso):Se você seguiu as etapas de instalação do front -end, provavelmente já terá um terminal aberto em vscode na raiz do projeto (open-webuidiretório). É aqui que você executará seus comandos de front -end (npm run dev, etc.). Certifique -se de que você está noopen-webuiDiretório para as próximas etapas, se você ainda não estiver.
Terminal de back -end (abra um novo):
- Em vscode, vá paraTerminal> Novo terminal(ou use o atalhoCtrl+Shift+no Windows/Linux ouCmd+Shift+no macOS). Isso abrirá um novo painel de terminal integrado.
- Navegue até obackenddiretório:NestanovoTerminal, use ocd backendcomando para alterar o diretório para obackendpasta dentro do seu projeto. Isso garante que todos os comandos relacionados ao back-end sejam executados no contexto correto.
Agora você temduas instâncias terminais separadas dentro do vscode: um para o front -end (provavelmente noopen-webuidiretório) e um especificamente para o back -end (dentro dobackenddiretório). Você pode alternar facilmente entre esses terminais no VSCode para gerenciar seus processos de front -end e back -end de forma independente. Essa configuração é altamente recomendada para um fluxo de trabalho de desenvolvimento mais limpo e eficiente.

Etapas de configuração de back -end (em seuback -endterminal):

Navegue até o diretório de back -end:(Você já deveria estar nobackenddiretório em seunovoterminal da etapa anterior). Caso contrário, corra:
```
back -end de CD
```
Crie e ative um ambiente de conda (recomendado):
- É altamente recomendável usar o CONDA para gerenciar dependências do Python e isolar o seu ambiente de projeto. Isso evita conflitos com outros projetos Python em seu sistema e garante que você tenha a versão e as bibliotecas corretas do Python.
```
conda crie-nome-name webui python = 3.11
O CONDA Ativa a Webui Open
```
  - conda create --name open-webui python=3.11: Este comando cria um novo ambiente de conda nomeadoopen-webuiUsando o Python versão 3.11. Se você escolheu uma versão diferente do Python 3.11.x, tudo bem.
  - conda activate open-webui: Este comando ativa o recém -criado ambiente do conda. Uma vez ativado, seu prompt de terminal geralmente muda para indicar que você está noopen-webuiambiente (por exemplo, pode mostrar(open-webui)no início da linha).
Certifique -se de ativar o ambiente no seu terminal de back -end antes de prosseguir.

(O uso do CONDA é opcional, mas recomendado fortemente para gerenciar dependências do Python e evitar conflitos.)Se você optar por não usar o CONDA, verifique se está usando o Python 3.11 ou superior e prossiga para a próxima etapa, mas esteja ciente dos possíveis conflitos de dependência.
Instale dependências de back -end:
- Em seuback -endTerminal (e com o ambiente CONDA ativado se você estiver usando o CONDA), execute:
```
pip install -r requisitos.txt -u
```
Este comando usapip(Instalador do pacote python) para ler orequirements.txtarquivo nobackenddiretório.requirements.txtListe todas as bibliotecas do Python que o back -end precisa executar.pip installDownloads e instala essas bibliotecas em seu ambiente ativo do Python (seu ambiente CONDA, se você o estiver usando ou seu ambiente Python em todo o sistema). O-UA bandeira garante que você obtenha as mais recentes versões compatíveis das bibliotecas.
Inicie o servidor de desenvolvimento de back -end:
- Em seuback -endTerminal, Run:
```
sh dev.sh
```
Este comando executa odev.shscript. Esse script provavelmente contém o comando para iniciar o servidor de desenvolvimento de back -end.(Você pode abrir e examinar odev.shArquivo no seu editor de código para ver o comando exato sendo executado, se você estiver curioso.)O servidor de back -end geralmente inicia e imprimirá alguma saída para o terminal.

Explore a documentação da API:Depois que o back -end estiver em execução, você pode acessar a documentação da API gerada automaticamente em seu navegador da web emhttp: // localhost: 8080/docs. Esta documentação é incrivelmente valiosa para entender os pontos de extremidade da API de back -end, como interagir com o back -end e quais dados ele espera e retorna. Mantenha esta documentação à medida que você desenvolve!

Parabéns!Se você seguiu todas as etapas, agora deve ter os servidores de desenvolvimento de front -end e back -end em execução localmente. Volte para a guia do navegador, onde você acessou o front -end (geralmentehttp: // localhost: 5173Atualize a página.Agora você deve ver o aplicativo Webui aberto completo em execução no seu navegador, conectado ao back -end local!

Solucionar problemas comuns

Aqui estão as soluções para alguns problemas comuns que você pode encontrar durante a configuração ou desenvolvimento:

💥 "Erro fatal: limite de heap alcançado" (front -end)

Esse erro, frequentemente visto durante o desenvolvimento do front -end, indica que o Node.js está ficando sem memória durante o processo de construção, especialmente ao trabalhar com grandes aplicações de front -end.

Solução:Aumente o tamanho da pilha Node.js. Isso dá ao Node.js mais memória para trabalhar. Você tem algumas opções:

UsandoNODE_OPTIONSVariável de ambiente (recomendado para desenvolvimento):
- Esta é uma maneira temporária de aumentar o limite de memória para a sessão do terminal atual. Antes de corrernpm run devounpm run buildem seufront-endTerminal, defina oNODE_OPTIONSVariável de ambiente:
```
exportar node_options = "-Max-Old-Space-tamanho = 4096" # para Linux/MacOS (Bash, Zsh)
# Definir node_options =-Max-Old-Space-Size = 4096 # para Windows (prompt de comando)
ass
NPM Run Dev
```
  Escolha o comando apropriado para o seu sistema operacional e terminal.4096representa 4 GB de memória. Você pode tentar aumentar ainda mais esse valor, se necessário (por exemplo,,8192para 8 GB). Essa configuração se aplicará apenas aos comandos executados na sessão atual do terminal.
ModificaçãoDockerfile(Para ambientes dockerizados):
- Se você estiver trabalhando com o Docker, pode definir permanentemente oNODE_OPTIONSVariável de ambiente em seuDockerfile. Isso é útil para alocação de memória consistente em ambientes dockerizados, como mostrado no exemplo do guia original:
```
Env Node_Options =-Max-Old-Space-Size = 4096
```
- Alocar RAM suficiente:Independentemente do método, verifique se o seu sistema ou contêiner do Docker possui RAM suficientes disponíveis para o Node.js usar.Recomenda -se pelo menos 4 GB de RAM, e mais pode ser necessário para projetos maiores ou compilações complexas. Feche os aplicativos desnecessários para liberar RAM.

⚠️ Conflitos de porta (front -end e back -end)

Se você vir erros relacionados às portas, como "endereço já em uso" ou "porta já encadernada", significa que outro aplicativo em seu sistema já está usando a porta5173(padrão para o frontend) ou8080(Padrão para o back -end). Apenas um aplicativo pode usar uma porta específica por vez.

Solução:

Identifique o processo conflitante:Você precisa descobrir qual aplicativo está usando a porta que você precisa.
- Linux/MacOS:Abra um novo terminal e use olsofounetstatcomandos:
  - lsof -i :5173(ou:8080para a porta de back -end)
  - netstat -tulnp | grep 5173(ou8080) Esses comandos listarão o ID do processo (PID) e o nome do processo usando a porta especificada.
- Windows:Prompt de comando aberto ou PowerShell como administrador e usenetstatouGet-NetTCPConnection
  - netstat -ano | findstr :5173(ou:8080) (Prompt de comando)
  - Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess(PowerShell) Esses comandos também mostrarão o PID do processo usando a porta.
Encerrar o processo conflitante:Depois de identificar o ID do processo (PID), você pode interromper o aplicativo usando essa porta.Tenha cuidado ao encerrar os processos, especialmente se você não tiver certeza do que eles são.
- Linux/MacOS:Use okillcomando:kill <PID>(substituir<PID>com o ID do processo real). Se o processo não terminar comkill, você pode usarkill -9 <PID>(Força matar), mas use isso com cautela.
- Windows:Use otaskkillcomando no prompt de comando ou PowerShell como administrador:taskkill /PID <PID> /F(substituir<PID>com o ID do processo). O/FBandeira Força o término.
Como alternativa, altere as portas (avançadas):
- Se você não puder encerrar o processo conflitante (por exemplo, é um serviço de sistema que você precisa), pode configurar o Nullcore para usar portas diferentes para o front -end e/ou back -end. Isso geralmente envolve a modificação de arquivos de configuração.
  - Porta de front -end:Verifique os arquivos de documentação ou configuração do front -end (geralmente emvite.config.jsou similar) para como alterar a porta do servidor de desenvolvimento. Pode ser necessário ajustar o.envArquivo também se o front -end usar variáveis de ambiente para a porta.
  - Porta de back -end:Examine odev.shArquivos de configuração de script ou back -end para ver como a porta de back -end está definida. Pode ser necessário modificar o comando de inicialização ou um arquivo de configuração para alterar a porta de back -end. Se você alterar a porta de back -end, provavelmente precisará atualizar o front -end.envarquivo para apontar para o novo URL de back -end.

🔄 Reload quente não está funcionando

Recarregar a quente (ou substituição do módulo quente - HMR) é um recurso de desenvolvimento fantástico que atualiza automaticamente o navegador quando você faz alterações no código. Se não estiver funcionando, pode diminuir significativamente o seu fluxo de trabalho de desenvolvimento.

Solução de problemas de etapas:

Verifique se os servidores de desenvolvimento estão em execução:Verifique duas vezes issonpm run dev(front -end) esh dev.sh(back -end) estão em execução em seus respectivos terminais e não encontraram erros. Procure mensagens na saída do terminal, indicando que estão em execução e no "modo de relógio" ou "modo de desenvolvimento". Se houver erros, aborde -os primeiro.
Verifique se há mensagens de modo de relógio/HMR:Quando os servidores de desenvolvimento começam, geralmente devem imprimir mensagens no terminal, indicando que o modo de recarga ou observação a quente está ativado. Procure frases como "HMR ativado", "assistindo a alterações de arquivo" ou similar. Se você não vir essas mensagens, pode haver um problema de configuração.
Cache do navegador:Às vezes, o cache do seu navegador pode impedir que você veja as mudanças mais recentes, mesmo que a recarga a quente esteja funcionando. Tente umAtualização difícilem seu navegador:
- Windows/Linux:Ctrl+Shift+R.
- macos:Cmd+shift+r
- Como alternativa, você pode tentar limpar o cache do navegador ou abrir o front -end em uma janela de navegador privada/incógnita.
Problemas de dependência (front -end):Às vezes, as dependências de front -end desatualizadas ou corrompidas podem interferir na recarga a quente. Tente refrescar as dependências do front -end:
- Em seufront-endTerminal, Run:
```
rm -rf node_modules && npm instalação
```
  Este comando exclui onode_modulesdiretório (onde as dependências são armazenadas) e depois as reinstala do zero. Isso pode resolver problemas causados por pacotes corrompidos ou desatualizados.
Reinicialização de back -end necessária (para alterações de back -end):O Recaroad a quente normalmente funciona melhor para alterações de código de front -end (interface do usuário, estilo, componentes). Para alterações significativas de código de back -end (especialmente alterações na lógica do servidor, terminais da API ou dependências), pode ser necessárioReinicie manualmente o servidor de back -end(Parandosh dev.shno seu terminal de back -end e executando -o novamente). Recarregar a quente para alterações de back -end geralmente é menos confiável ou não é configurado automaticamente em muitas configurações de desenvolvimento de back -end.
IDE/editor problemas:Em casos raros, os problemas com seu IDE ou editor de código podem impedir que as alterações de arquivo sejam detectadas adequadamente pelos servidores de desenvolvimento. Tente reiniciar seu IDE ou garantir que os arquivos estejam sendo salvos corretamente.
Problemas de configuração (avançado):Se nenhuma das etapas acima funcionar, pode haver um problema de configuração mais complexo com a configuração do front -end ou Backend Development Server. Consulte a documentação do projeto, arquivos de configuração (por exemplo,,vite.config.jsPara os arquivos de configuração do Frontend, Backend Server) ou procure ajuda da comunidade Nullcore ou dos mantenedores.

Contribuindo para abrir webui

Agradecemos calorosamente suas contribuições para o Nullcore! Sua ajuda é valiosa para tornar este projeto ainda melhor. Aqui está um guia rápido para um fluxo de trabalho de contribuição suave e eficaz:

Entenda a estrutura do projeto:Reserve um tempo para se familiarizar com a estrutura de diretório do projeto, especialmente ofrontendebackendpastas. Veja o código, os arquivos de configuração e a documentação para ter uma idéia de como as coisas estão organizadas.
Comece com pequenas contribuições:Se você é novo no projeto, considere começar com contribuições menores como:
- Melhorias de documentação:Corrija erros de digitação, esclareça explicações, adicione mais detalhes à documentação.
- Correções de bug:Abordar bugs ou problemas relatados.
- Pequenos aprimoramentos da interface do usuário:Melhore o estilo, corrija pequenos problemas de layout. Essas contribuições menores são uma ótima maneira de se familiarizar com a base de código e o processo de contribuição.
Discuta mudanças maiores primeiro:Se você planeja implementar um novo recurso significativo ou fazer mudanças substanciais, é altamente recomendávelDiscuta suas idéias com os mantenedores ou comunidade do projeto primeiro.Você pode fazer isso por:
- Abrindo um problemano repositório do GitHub para propor seu recurso ou alteração.
- Juntando -se aos canais da comunidade Nullcore(Se disponível, verifique o readme ou o site do projeto para obter links) e discutir suas idéias lá. Isso ajuda a garantir que sua contribuição se alinhe aos objetivos do projeto e evite esforços desperdiçados em recursos que podem não ser mesclados.
Crie uma filial separada para o seu trabalho: Nunca se comprometa diretamente com odevfilial.Sempre crie uma nova ramificação para cada recurso ou correção de bug em que você está trabalhando. Isso mantém suas alterações isoladas e facilita o gerenciamento e o envio de solicitações de tração.
- Para criar uma nova filial (por exemplo, nomeadamy-feature-branch) com base nodevfilial:
```
Git checkout Dev
Git Pull Origin Dev # Verifique se sua filial de dev local está atualizada
checkout git -B-rastreamento de meu recurso
```
Compromete as alterações com frequência e escreva mensagens de compromisso claro:Faça pequenos compromissos lógicos ao desenvolver recursos ou corrigir bugs.Escreva mensagens de confirmação claras e concisasIsso explica quais mudanças você fez e por quê. Boas mensagens de compromisso facilitam a compreensão da história das mudanças e são essenciais para a colaboração.
- Exemplo de uma boa mensagem de confirmação:Fix: Corrected typo in documentation for backend setup
- Exemplo de uma boa mensagem de confirmação:Feat: Implemented user profile page with basic information display
Fique sincronizado com odevFilial regularmente:Enquanto trabalhava em sua filial, sincronize periodicamente sua filial com as últimas alterações dodevramo para minimizar conflitos de mesclagem mais tarde:
```
Git checkout Dev
Git Pull Origin Dev
Git Checkout My-Rumure Franch
Git Merge Dev
```
Resolva qualquer conflito de mesclagem que surjam durante ogit mergeetapa.
Executar testes (se disponível) antes de pressionar:Embora este guia não detalhe os procedimentos de teste específicos para o Nullcore, é uma boa prática executar os testes disponíveis antes de pressionar seu código. Verifique a documentação do projeto oupackage.json(para arquivos de front-end) e back-end para comandos relacionados a testes (por exemplo,,npm run test, Assim,pytest, etc.). A execução dos testes ajuda a garantir que suas alterações não introduzissem regressões ou funcionalidade existente quebrada.
Envie uma solicitação de tração (PR):Depois de concluir seu trabalho, testei -o (se aplicável) e estiver pronto para contribuir com suas alterações, envie uma solicitação de tração (PR) aodevFilial do repositório Nullcore no Github.
- Vá para o repositório Nullcore no Github.
- Navegue até o seu ramo.
- Clique no botão "Contribuir" ou "Pull Solicy"(geralmente verde).
- Preencha o formulário de relações públicas:
  - Título:Dê ao seu PR um título claro e descritivo que resume suas alterações (por exemplo, "Correção: Problema resolvido com a validação do formulário de login").
  - Descrição:Forneça uma descrição mais detalhada de suas alterações, o problema que você está resolvendo (se aplicável) e qualquer contexto relevante. Link para quaisquer problemas relacionados, se houver.
- Envie o pr.
Os mantenedores do projeto revisarão sua solicitação de tração, fornecerão feedback e potencialmente mesclarão suas alterações. Responte ao feedback e esteja preparado para fazer revisões se solicitado.

Obrigado por ler este guia abrangente e pelo seu interesse em contribuir para o Nullcore! Estamos empolgados em ver suas contribuições e ajudá -lo a se tornar parte da comunidade aberta da Webui!🎉 Codificação feliz!