Implantação com Docker Compose

Esta página explica como implantar o Hagicode com Docker Compose. Ele é indicado para servidores, NAS, compartilhamento em equipe ou cenários que exigem isolamento de ambiente; para uso pessoal local, considere primeiro a Microsoft Store ou o Desktop.

Por que escolher o Docker Compose

• O isolamento do ambiente reduz conflitos de dependências
• A pilha de serviços do Hagicode compatível atualmente pode ser iniciada de uma só vez
• Configuração, atualização e manutenção seguem um caminho unificado
• O host precisa apenas do Docker, sem necessidade de instalar o Node.js ou o Git separadamente

Sobre o armazenamento de dados padrão

Os modelos de Docker Compose compatíveis atualmente organizam a persistência de dados com base no caminho SQLite local padrão. Na maioria dos casos, você não precisa preparar um serviço de banco de dados independente no host.

Tutorial em vídeo

Se quiser ver primeiro o fluxo completo, comece pelo tutorial em vídeo:

Assista ao tutorial em vídeo no Bilibili

Resumo do conteúdo do vídeo:

• Demonstração do fluxo completo de implantação com Docker Compose
• Explicação sobre a geração e a edição do arquivo de configuração
• Etapas de inicialização e verificação do serviço
• Problemas comuns e soluções

Duração do vídeo: cerca de 15 minutos

Pré-requisitos

Antes de começar, confirme que o Docker e o Docker Compose estão instalados no seu sistema.

Instalar o Docker

Windows

Baixe e instale o Docker Desktop para Windows. Depois da instalação, confirme que o Docker Desktop está em execução.

macOS

Baixe e instale o Docker Desktop para Mac. Depois da instalação, confirme que o Docker Desktop está em execução.

Linux

Siga a documentação oficial do Docker para instalar o Docker Engine e o plugin do Docker Compose na sua distribuição: Install Docker Engine. Os repositórios de software e os nomes dos pacotes variam entre as distribuições, portanto não reutilize diretamente os comandos de outra distribuição.

Depois da instalação, inicie o serviço do Docker e configure-o para iniciar com o sistema:

sudo systemctl start docker
sudo systemctl enable docker

Verificar a instalação

Depois da instalação, execute os comandos abaixo para confirmar que o Docker e o Docker Compose foram instalados corretamente:

docker --version
docker compose version

Início rápido

1. Gerar o arquivo de configuração do Docker Compose

Use o Docker Compose Builder para gerar o docker-compose.yml. Ele é um site independente, e as regras de geração e as atualizações seguem o que esse site define.

O gerador permite:

• Escolher o provedor de API (Zhipu AI, Anthropic oficial ou API personalizada) e configurar a URL da API e o token
• Personalizar portas, nomes de contêineres, diretórios de persistência e diretório de trabalho
• Escolher entre banco de dados integrado ou externo
• Tratar automaticamente as diferenças entre Windows / Linux e os problemas comuns de permissão de arquivos
• Usar a imagem compatível do Docker Hub

Passo a passo:

1. Abra o Docker Compose Builder.
2. Preencha a configuração conforme a sua necessidade: escolha o provedor de API e configure opções como porta, banco de dados e diretório de trabalho.
3. Clique no botão de gerar para obter a configuração do docker-compose.yml.
4. Salve a configuração gerada como um arquivo docker-compose.yml.
5. Se necessário, crie um arquivo .env para guardar informações sensíveis, evitando escrever o token diretamente no arquivo compose.

Origem da imagem

O gerador usa o Docker Hub como origem de imagem compatível:

• Endereço da imagem: newbe36524/hagicode:{tag}
• Cenário indicado: usuários que têm aceleração de imagens do Docker Hub
• Observação: em algumas regiões pode ser necessário configurar um acelerador de imagens

Obter o token de API

A implantação com Docker acessa os modelos por meio do provedor de API configurado no gerador, portanto você precisa preparar antes um token de API válido:

Zhipu AI: Obter token de API →

• Acesso estável na China continental, com respostas mais rápidas
• Ótimo custo-benefício, indicado para o uso diário

Anthropic oficial: Obter token de API →

• Uso direto dos serviços da Anthropic

Você também pode escolher uma API personalizada no gerador.

2. Iniciar os serviços

No diretório em que está o docker-compose.yml, execute o comando abaixo:

docker compose up -d

Esse comando irá:

• Baixar e iniciar o contêiner do Hagicode definido na configuração gerada
• Criar e configurar a rede
• Inicializar o diretório de dados padrão e as dependências de execução

3. Verificar o estado do serviço

Verifique se os contêineres estão em execução:

docker compose ps

Você deve ver os serviços definidos na configuração gerada com o estado “running”.

Veja os logs do serviço:

# Ver os logs de todos os serviços
docker compose logs

# Ver os logs do serviço Hagicode
docker compose logs hagicode

# Acompanhar os logs em tempo real
docker compose logs -f hagicode

Acessar o aplicativo

Depois que os serviços iniciarem com sucesso, acesse pelo navegador:

http://localhost:45000

Se você alterou a porta no gerador, use a porta do host que definiu. Na primeira vez que abrir, você entra no assistente de inicialização; continue lendo a Configuração do assistente de inicialização.

Configuração

Se precisar alterar a configuração (por exemplo, mudar a porta ou trocar o provedor de API), você pode:

1. Gerar uma nova configuração novamente com o Docker Compose Builder
2. Editar manualmente os arquivos docker-compose.yml e .env
3. Recriar os contêineres para que a configuração entre em vigor:

docker compose up -d

O docker compose restart apenas reinicia os contêineres existentes e não aplica alterações feitas no docker-compose.yml ou no .env. Depois de alterar a configuração, use docker compose up -d.

Persistência de dados

O caminho do Docker Compose compatível atualmente usa, por padrão, arquivos de dados SQLite e volumes persistentes. Se precisar conferir onde os dados são montados ou definir uma estratégia de backup, consulte diretamente os mapeamentos de volumes e de diretórios de dados no docker-compose.yml gerado.

Manutenção do dia a dia

Parar e iniciar

# Parar os serviços (mantém os contêineres e os dados)
docker compose stop

# Iniciar novamente
docker compose start

# Parar e remover os contêineres (os volumes de dados continuam preservados)
docker compose down

Não adicione -v ao docker compose down sem necessidade: essa opção também apaga os volumes de dados declarados no arquivo compose.

Atualizar a versão

1. Antes de atualizar, faça backup do diretório de dados (veja abaixo).
2. Altere a tag da imagem newbe36524/hagicode:{tag} no docker-compose.yml para a versão desejada ou gere a configuração novamente com o gerador.
3. Baixe a nova imagem e recrie os contêineres:

docker compose pull
docker compose up -d

Fazer backup dos dados

Execute primeiro docker compose stop para que o serviço pare de gravar; depois faça backup dos diretórios ou volumes de dados correspondentes aos mapeamentos de volumes e de diretórios de dados do docker-compose.yml e, em seguida, execute docker compose start para retomar o serviço.

Próximos passos

Agora você já implantou o Hagicode com sucesso. A seguir:

1. Leia a Configuração do assistente de inicialização para criar o Hagicoder padrão e o primeiro projeto.
2. Em Criar uma sessão de conversa, comece conhecendo o projeto no modo somente leitura e, se precisar, siga para Criar uma sessão de proposta.

Se preferir usar um aplicativo de desktop, consulte o Guia de instalação do Desktop.