Implementación con Docker Compose

Esta página explica cómo implementar Hagicode con Docker Compose. Es adecuada para servidores, NAS, uso compartido en equipo o escenarios que requieren aislamiento del entorno; para uso local personal, considere primero Microsoft Store o Desktop.

Por qué elegir Docker Compose

• Aislamiento del entorno, con menos conflictos de dependencias
• Permite iniciar de una vez la pila de servicios de Hagicode actualmente admitida
• Ruta unificada de configuración, actualización y mantenimiento
• El host solo necesita Docker; no hace falta instalar aparte Node.js ni Git

Sobre el almacenamiento de datos predeterminado

Las plantillas de Docker Compose actualmente admitidas organizan los datos persistentes con la ruta de datos SQLite local predeterminada. En la mayoría de los casos, no necesita preparar un servicio de base de datos independiente en el host.

Vídeo tutorial

Si primero quiere ver el flujo completo, empiece por el vídeo tutorial:

Ver el vídeo tutorial en Bilibili

Contenido del vídeo:

• Demostración del proceso completo de implementación con Docker Compose
• Instrucciones para generar y modificar el archivo de configuración
• Pasos para iniciar y verificar el servicio
• Problemas habituales y sus soluciones

Duración del vídeo: aproximadamente 15 minutos

Requisitos previos

Antes de empezar, asegúrese de que su sistema tiene instalados Docker y Docker Compose.

Instalar Docker

Windows

Descargue e instale Docker Desktop for Windows. Cuando termine la instalación, asegúrese de que Docker Desktop se está ejecutando.

macOS

Descargue e instale Docker Desktop for Mac. Cuando termine la instalación, asegúrese de que Docker Desktop se está ejecutando.

Linux

Siga la documentación oficial de Docker para instalar Docker Engine y el plugin de Docker Compose en su distribución: Install Docker Engine. Los repositorios de software y los nombres de los paquetes varían según la distribución, así que no aplique directamente los comandos de otra distribución.

Cuando termine la instalación, inicie el servicio de Docker y configúrelo para que arranque con el sistema:

sudo systemctl start docker
sudo systemctl enable docker

Verificar la instalación

Cuando termine la instalación, ejecute los siguientes comandos para comprobar que Docker y Docker Compose están correctamente instalados:

docker --version
docker compose version

Inicio rápido

1. Generar el archivo de configuración de Docker Compose

Use Docker Compose Builder para generar docker-compose.yml. Es un sitio independiente, y sus reglas de generación y actualizaciones se rigen por ese sitio.

El generador permite:

• Elegir el proveedor de API (Zhipu AI, Anthropic oficial o una API personalizada) y configurar la URL de la API y el Token
• Personalizar los puertos, el nombre del contenedor, el directorio de persistencia y el directorio de trabajo
• Elegir entre base de datos integrada o externa
• Gestionar automáticamente las diferencias de plataforma entre Windows y Linux y los problemas habituales de permisos de archivos
• Usar la imagen de Docker Hub admitida

Pasos:

1. Abra Docker Compose Builder.
2. Rellene la configuración según sus necesidades: elija el proveedor de API y configure el puerto, la base de datos, el directorio de trabajo y otras opciones.
3. Haga clic en el botón de generar para obtener la configuración de docker-compose.yml.
4. Guarde la configuración generada como el archivo docker-compose.yml.
5. Si es necesario, cree un archivo .env para la información sensible, de modo que no escriba el Token directamente en el archivo compose.

Origen de la imagen

El generador usa Docker Hub como origen de imágenes admitido:

• Dirección de la imagen: newbe36524/hagicode:{tag}
• Escenario aplicable: adecuado para usuarios que disponen de aceleración de imágenes de Docker Hub
• Aviso: en algunas regiones puede ser necesario configurar un acelerador de imágenes

Obtener un API Token

La implementación con Docker accede a los modelos a través del proveedor de API configurado en el generador, por lo que primero debe preparar un API Token válido:

Zhipu AI: Obtener API Token →

• Acceso estable desde China y respuesta más rápida
• Buena relación calidad-precio, adecuado para el uso diario

Anthropic oficial: Obtener API Token →

• Uso directo de los servicios de Anthropic

También puede elegir una API personalizada en el generador.

2. Iniciar los servicios

En el directorio donde se encuentra docker-compose.yml, ejecute el siguiente comando:

docker compose up -d

Este comando:

• Descarga e inicia los contenedores de Hagicode definidos en la configuración generada
• Crea y configura la red
• Inicializa el directorio de datos predeterminado y las dependencias de ejecución

3. Verificar el estado del servicio

Compruebe si los contenedores se están ejecutando:

docker compose ps

Debería ver que los servicios definidos en la configuración generada están en estado “running”.

Consulte los registros del servicio:

# Ver los registros de todos los servicios
docker compose logs

# Ver los registros del servicio Hagicode
docker compose logs hagicode

# Seguir los registros en tiempo real
docker compose logs -f hagicode

Acceder a la aplicación

Cuando el servicio se haya iniciado correctamente, acceda desde el navegador a:

http://localhost:45000

Si cambió el puerto en el generador, use el puerto del host que haya configurado. La primera vez que lo abra, accederá al asistente de inicialización; continúe con Configuración del asistente.

Configuración

Si necesita modificar la configuración (por ejemplo, cambiar el puerto o el proveedor de API), puede:

1. Volver a generar una nueva configuración con Docker Compose Builder
2. Editar a mano los archivos docker-compose.yml y .env
3. Volver a crear los contenedores para que la configuración surta efecto:

docker compose up -d

docker compose restart solo reinicia los contenedores existentes y no aplica los cambios hechos en docker-compose.yml ni en .env. Después de modificar la configuración, use docker compose up -d.

Persistencia de datos

La ruta de Docker Compose actualmente admitida usa por defecto archivos de datos SQLite y volúmenes persistentes. Si necesita revisar dónde se montan los datos o su estrategia de copias de seguridad, consulte directamente la configuración de volúmenes y la asignación de directorios de datos del docker-compose.yml generado.

Mantenimiento diario

Detener y volver a iniciar

# Detener los servicios (conserva los contenedores y los datos)
docker compose stop

# Volver a iniciarlos
docker compose start

# Detener y eliminar los contenedores (los volúmenes de datos se conservan)
docker compose down

No añada -v a docker compose down sin necesidad: eliminaría también los volúmenes de datos declarados en el archivo compose.

Actualizar la versión

1. Antes de actualizar, haga una copia de seguridad del directorio de datos (consulte más abajo).
2. En docker-compose.yml, cambie la etiqueta de la imagen newbe36524/hagicode:{tag} por la versión de destino, o vuelva a generar la configuración con el generador.
3. Descargue la nueva imagen y vuelva a crear los contenedores:

docker compose pull
docker compose up -d

Copia de seguridad de los datos

Ejecute primero docker compose stop para que el servicio deje de escribir; después, haga una copia de seguridad de los directorios o volúmenes de datos que correspondan a la configuración de volúmenes y a la asignación de directorios de datos de docker-compose.yml, y por último ejecute docker compose start para reanudar el servicio.

Próximos pasos

Ya ha implementado Hagicode correctamente. A continuación:

1. Lea Configuración del asistente para crear el Hagicoder predeterminado y su primer proyecto.
2. En Crear una sesión de conversación, conozca primero el proyecto en modo de solo lectura y, si lo necesita, continúe con Crear una sesión de propuesta.

Si prefiere usar la aplicación de escritorio, consulte la Guía de instalación de Desktop.