Implementación de Docker Compose

Esta guía cubre la implementación de HagiCode con Docker Compose. Para la mayoría de los usuarios, esta es la ruta de implementación predeterminada en los entornos de desarrollo, prueba y producción.

Vídeotutorial

Si primero quieres ver el flujo completo, comienza con el vídeo tutorial:

Mira el vídeo tutorial sobre Bilibili

El contenido del vídeo incluye:

• Demostración completa del proceso de implementación de Docker Compose
• Instrucciones de generación y modificación del archivo de configuración.
• Pasos de verificación e inicio del servicio
• Problemas comunes y soluciones

Duración del vídeo: aproximadamente 15 minutos.

Constructor de composición de Docker

Docker Compose Builder ahora está disponible como herramienta independiente en https://builder.hagicode.com/. Utilice ese sitio como fuente principal para generar la misma clase de archivos de configuración.

Usar generador de configuración

puedes usar Docker Compose Builder (sitio independiente) generar docker-compose.yml directamente.

El generador soporta:

• puertos personalizados, nombres de contenedores y otras configuraciones básicas
• selección de base de datos incorporada o externa
• diferencias automáticas de plataforma Windows / Linux
• manejo común de permisos de archivos
• Selección de fuente de imagen según su entorno de red.

Abrir el generador →

Método recomendado

Docker Compose es la ruta de implementación predeterminada en la mayoría de los casos porque:

• el aislamiento del entorno reduce los conflictos de dependencia
• la pila de servicios HagiCode compatible puede comenzar junta
• La configuración, las actualizaciones y el mantenimiento son más fáciles de mantener consistentes.
• Funciona bien para pruebas locales, pruebas e implementación en equipo.

Acerca del almacenamiento de datos predeterminado

Las plantillas de Docker Compose actualmente admitidas conservan los datos a través de la ruta SQLite local predeterminada. En la mayoría de los casos, no es necesario aprovisionar un servicio de base de datos independiente en la máquina host.

Requisitos previos

Antes de comenzar, asegúrese de que su sistema tenga instalado Docker y Docker Compose.

Instalar ventana acoplable

ventanas

Descargar e instalar Escritorio Docker para Windows

Después de la instalación, asegúrese de que Docker Desktop se esté ejecutando.

macos

Descargar e instalar Escritorio Docker para Mac

Después de la instalación, asegúrese de que Docker Desktop se esté ejecutando.

linux

Instale Docker usando su administrador de paquetes:

Install Docker on Ubuntu/Debian

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

Después de la instalación, inicie el servicio Docker:

sudo systemctl start docker
sudo systemctl enable docker

Verificar la instalación

Después de la instalación, ejecute los siguientes comandos para verificar que Docker y Docker Compose estén instalados correctamente:

docker --version
docker compose version

Inicio rápido

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

Usar generador de configuración

Recomendar usar Docker Compose Builder (sitio independiente) para generar su archivo de configuración.

El generador soporta:

• Múltiples opciones de proveedores de API (Zhipu AI, Anthropic Official, API personalizada)
• Configuración automática de API URL y Token
• Puertos personalizados, nombres de contenedores y otras configuraciones básicas
• Configurar datos persistentes y rutas de directorio de trabajo
• Configurar automáticamente las diferencias de plataforma Windows/Linux
• Maneje de manera inteligente los problemas de permisos de archivos
• Selección de fuente de imagen: según su entorno de red, seleccione la fuente de imagen adecuada

🚀 Usa el generador inmediatamente →

1. Abierto Docker Compose Builder (sitio independiente)
2. Complete la configuración según sus necesidades:
   • Seleccione el proveedor de API (Zhipu AI, Anthropic Official o API personalizada)
   • Configurar puertos, base de datos, directorio de trabajo y otras opciones
   • Seleccione fuente de imagen: elija la fuente de imagen adecuada según su entorno de red
3. Haga clic en el botón generar para obtener el docker-compose.yml configuración
4. Guarde la configuración generada como docker-compose.yml archivo
5. Si es necesario, cree un .env archivo para configurar información sensible

Selección de fuente de imagen

El generador admite tres opciones de fuente de imagen:

Centro acoplable

• Dirección de la imagen: newbe36524/hagicode:{tag}
• Escenarios aplicables: Adecuado para usuarios con aceleración de espejo Docker Hub
• Ventajas: Fuente de imagen oficial, actualizaciones oportunas, acceso estable
• Notas: Es posible que sea necesario configurar la aceleración del espejo en algunas regiones

Registro de contenedores de Azure (ACR)

• Dirección de la imagen: hagicode.azurecr.io/hagicode:{tag}
• Escenarios aplicables: Adecuado para usuarios que no pueden acceder a Docker Hub localmente
• Ventajas: Proporciona una fuente de imagen alternativa y resuelve problemas de acceso a la red
• Notas: Las imágenes permanecen sincronizadas con Docker Hub, pero pueden tener breves retrasos

Registro de contenedores en la nube de Alibaba (ACR)

• Dirección de la imagen: registry.cn-hangzhou.aliyuncs.com/hagicode/hagicode:{tag}
• Escenarios aplicables: Adecuado para usuarios domésticos, acceso a red estable y rápido
• Ventajas: Nodos domésticos de Alibaba Cloud, velocidad de acceso rápida, alta estabilidad
• Notas: Las imágenes ACR de Alibaba permanecen sincronizadas con Docker Hub, normalmente en 30 minutos

Recomendaciones para la selección de fuentes de imágenes

• Los usuarios nacionales recomiendan Alibaba Cloud ACR: si es un usuario nacional, se recomienda priorizar el uso de la fuente de imágenes Alibaba Cloud ACR para un acceso rápido y estable.
• Docker Hub alternativo: si su entorno de red puede acceder a Docker Hub, también puede elegir Docker Hub como fuente de imagen.
• Azure ACR alternativo: elija la fuente de imagen de Azure ACR solo si otras fuentes de imágenes tienen dificultades de acceso.
• Sincronización de imágenes: las imágenes ACR de Alibaba Cloud permanecen sincronizadas con Docker Hub, generalmente en 30 minutos
• Coherencia de la versión: las etiquetas de las imágenes son consistentes en las tres fuentes de imágenes, no hay necesidad de preocuparse por problemas de versión.

Obtener token API

Debe configurar Claude API Token para usar HagiCode:

Zhipu AI (recomendado): Obtener token API →

• Acceso nacional estable, respuesta más rápida
• Alto costo-rendimiento, adecuado para uso diario

Oficial Antrópico: Obtener token API →

• Uso directo de los servicios de Anthropic

2. Iniciar servicios

Ejecute el siguiente comando en el directorio donde está su docker-compose.yml se encuentra:

docker compose up -d

Este comando:

• Descargue e inicie los contenedores HagiCode definidos por la plantilla generada
• Crear y configurar la red.
• Inicialice el directorio de datos predeterminado y las dependencias del tiempo de ejecución

3. Verificar el estado del servicio

Compruebe si los contenedores se están ejecutando:

docker compose ps

Debería ver los servicios definidos en su plantilla generada en estado “en ejecución”.

Ver registros de servicio

Para ver todos los registros de servicio:

# View all service logs
docker compose logs

# View HagiCode service logs
docker compose logs hagicode

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

Instrucciones de configuración

Si necesita modificar la configuración (como cambiar puertos, cambiar de proveedor de API, etc.), puede:

1. Regenerar nueva configuración usando Docker Compose Builder (sitio independiente)
2. editar manualmente docker-compose.yml y .env archivos
3. Reinicie los servicios para que la configuración surta efecto:

docker compose restart

Solicitud de acceso

Interfaz Web

Después del inicio exitoso del servicio, acceda a través de su navegador:

http://localhost:45000

Persistencia de datos

La ruta de Docker Compose admitida utiliza archivos de datos SQLite con volúmenes persistentes de forma predeterminada. Si necesita inspeccionar puntos de montaje o planificar copias de seguridad, revise las asignaciones de volúmenes y directorios de datos en el archivo generado. docker-compose.yml.

Próximos pasos

Ahora ha implementado HagiCode con éxito. A continuación, conecte un proyecto real en la interfaz web y luego continúe con Configuración del asistente o Crear sesión de propuesta.

Si prefiere el método de implementación de la aplicación de escritorio, consulte Guía de instalación de escritorio.