Implantação do Docker Compose

Este guia aborda a implantação do HagiCode com Docker Compose. Para a maioria dos usuários, esse é o caminho de implantação padrão em ambientes de desenvolvimento, teste e produção.

Tutorial em vídeo

Se você quiser ver o fluxo completo primeiro, comece com o tutorial em vídeo:

Assista ao vídeo tutorial sobre Bilibili

Conteúdo de vídeo inclui:

Demonstração completa do processo de implantação do Docker Compose
Instruções de geração e modificação do arquivo de configuração
Etapas de inicialização e verificação do serviço
Problemas e soluções comuns

Duração do vídeo: aproximadamente 15 minutos

Docker Compose Builder

Docker Compose Builder agora está disponível como uma ferramenta independente em https://builder.hagicode.com/. Use esse site como fonte principal para gerar a mesma classe de arquivos de configuração.

Usar Gerador de Configuração

Você pode usar Docker Compose Builder (site independente) gerar docker-compose.yml diretamente.

O gerador suporta:

portas personalizadas, nomes de contêineres e outras configurações básicas
seleção de banco de dados interno ou externo
diferenças automáticas de plataforma Windows/Linux
manipulação comum de permissão de arquivo
seleção da fonte da imagem com base no seu ambiente de rede

Abra o gerador →

Método recomendado

Docker Compose é o caminho de implantação padrão na maioria dos casos porque:

o isolamento do ambiente reduz conflitos de dependência
a pilha de serviços HagiCode suportada pode começar junto
configuração, atualizações e manutenção são mais fáceis de manter consistentes
funciona bem para testes locais, testes e implantação de equipe

Pré-requisitos

Antes de começar, certifique-se de que seu sistema tenha Docker e Docker Compose instalados.

Instale o Docker

Janelas

Baixe e instale Docker Desktop para Windows

Após a instalação, certifique-se de que o Docker Desktop esteja em execução.

macOS

Baixe e instale Docker Desktop para Mac

Após a instalação, certifique-se de que o Docker Desktop esteja em execução.

Linux

Instale o Docker usando seu gerenciador de pacotes:

sudo apt-get update
sudo apt-get install docker.io docker-compose-plugin

Após a instalação, inicie o serviço Docker:

sudo systemctl start docker
sudo systemctl enable docker

Verifique a instalação

Após a instalação, execute os seguintes comandos para verificar se o Docker e o Docker Compose estão instalados corretamente:

docker --version
docker compose version

Início rápido

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

Usar Gerador de Configuração

Recomende usar Docker Compose Builder (site independente) para gerar seu arquivo de configuração.

O gerador suporta:

Múltiplas opções de provedores de API (Zhipu AI, Anthropic Official, API personalizada)
Configuração automática de URL e token da API
Portas personalizadas, nomes de contêineres e outras configurações básicas
Configurar dados persistentes e caminhos de diretório de trabalho
Configurar automaticamente diferenças de plataforma Windows/Linux
Lide de forma inteligente com problemas de permissão de arquivos
Seleção da fonte de imagem: com base no seu ambiente de rede, selecione a fonte de imagem apropriada

🚀 Use o gerador imediatamente →

Abrir Docker Compose Builder (site independente)
Preencha a configuração de acordo com sua necessidade:
- Selecione o provedor de API (Zhipu AI, Anthropic Official ou API personalizada)
- Configure portas, banco de dados, diretório de trabalho e outras opções
- Selecione a origem da imagem: escolha a origem da imagem apropriada com base no seu ambiente de rede
Clique no botão gerar para obter o docker-compose.yml configuração
Salve a configuração gerada como um docker-compose.yml arquivo
Se necessário, crie um .env arquivo para configurar informações confidenciais

Seleção da fonte da imagem

O gerador oferece suporte a três opções de fonte de imagem:

DockerHub

Endereço da imagem: newbe36524/hagicode:{tag}
Cenários aplicáveis: Adequado para usuários com aceleração de espelho Docker Hub
Vantagens: Fonte de imagem oficial, atualizações oportunas, acesso estável
Observações: A aceleração de espelho pode precisar ser configurada em algumas regiões

Registro de Contêiner do Azure (ACR)

Endereço da imagem: hagicode.azurecr.io/hagicode:{tag}
Cenários aplicáveis: Adequado para usuários que não conseguem acessar o Docker Hub localmente
Vantagens: Fornece fonte de imagem alternativa e resolve problemas de acesso à rede
Observações: As imagens permanecem sincronizadas com o Docker Hub, mas podem sofrer breves atrasos

Alibaba Cloud Container Registry (ACR)

Endereço da imagem: registry.cn-hangzhou.aliyuncs.com/hagicode/hagicode:{tag}
Cenários aplicáveis: Adequado para usuários domésticos, acesso à rede estável e rápido
Vantagens: Nós domésticos Alibaba Cloud, velocidade de acesso rápida, alta estabilidade
Observações: As imagens Alibaba ACR permanecem sincronizadas com o Docker Hub, geralmente em 30 minutos

Recomendações para seleção da fonte da imagem

Usuários domésticos recomendam Alibaba Cloud ACR: Se você for um usuário doméstico, é recomendado priorizar o uso da fonte de imagem Alibaba Cloud ACR para acesso rápido e estável
** Docker Hub alternativo **: se o seu ambiente de rede puder acessar o Docker Hub, você também poderá escolher o Docker Hub como fonte de imagem
ACR alternativo do Azure: escolha apenas a fonte de imagem do Azure ACR se outras fontes de imagem tiverem dificuldades de acesso
Sincronização de imagens: as imagens Alibaba Cloud ACR permanecem sincronizadas com o Docker Hub, geralmente em 30 minutos
Consistência de versão: as tags de imagem são consistentes em todas as três fontes de imagem, não há necessidade de se preocupar com problemas de versão

Obter token de API

Você precisa configurar o Claude API Token para usar o HagiCode:

Zhipu AI (recomendado): Obtenha o token da API →

Acesso doméstico estável, resposta mais rápida
Alto custo-desempenho, adequado para uso diário

Oficial Antrópico: Obtenha o token da API →

Uso direto dos serviços da Antrópico

2. Inicie os serviços

Execute o seguinte comando no diretório onde seu docker-compose.yml está localizado:

docker compose up -d

Este comando irá:

Baixe e inicie os containers HagiCode definidos pelo template gerado
Criar e configurar a rede
Inicialize o diretório de dados padrão e as dependências de tempo de execução

3. Verifique o status do serviço

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

docker compose ps

Você deverá ver os serviços definidos no modelo gerado no status “em execução”.

Ver registros de serviço

Para visualizar todos os logs de serviço:

# View all service logs
docker compose logs

# View HagiCode service logs
docker compose logs hagicode

# Real-time log following
docker compose logs -f hagicode

Instruções de configuração

Se precisar modificar a configuração (como alterar portas, trocar de provedor de API etc.), você pode:

Gere novamente a nova configuração usando Docker Compose Builder (site independente)
Editar manualmente docker-compose.yml e .env arquivos
Reinicie os serviços para que a configuração tenha efeito:

docker compose restart

Aplicativo de acesso

Interface Web

Após a inicialização bem-sucedida do serviço, acesse pelo seu navegador:

http://localhost:45000

Persistência de dados

O caminho Docker Compose compatível usa arquivos de dados SQLite com volumes persistentes por padrão. Se você precisar inspecionar pontos de montagem ou planejar backups, revise os mapeamentos de volume e diretório de dados no arquivo gerado docker-compose.yml.

Próximas etapas

Agora você implantou o HagiCode com sucesso. Em seguida, conecte um projeto real na interface web e continue com Configuração do assistente ou Criar sessão de proposta.

Se você preferir o método de implantação de aplicativos de desktop, consulte Guia de instalação de desktop.