qingliao-backend
Servidor backend en Python minimalista para automatización doméstica, IA local/híbrida y gestión de infraestructura (Docker/HA).
Ficha actualizada 22 sept 2026, 14:47 · upstream 22 sept 2026, 14:08 · release sin release detectada
Qué es qingliao-backend
Descripción editorial construida a partir del repositorio, su documentación y sus señales de mantenimiento.
Qingliao Backend es un servidor de API diseñado para funcionar como núcleo de una suite de asistente inteligente y automatización en entornos NAS. Su arquitectura se basa en Python estándar sin frameworks web, lo que reduce la complejidad y facilita el despliegue en recursos limitados. El servicio expone múltiples endpoints por puerto (ej: 9123 para LLM, 9149 para Ollama local, 9127 para Home Assistant), permitiendo una gestión granular de funciones como control de dispositivos IoT, procesamiento de archivos PDF y monitorización de hardware.
El proyecto destaca por su capacidad de hibridación: puede ejecutar modelos locales vía Ollama para privacidad y funcionamiento offline, o conectarse a APIs externas (DeepSeek/OpenAI) cuando hay red. Incluye módulos específicos para gestión de contenedores Docker, enrutamiento Clash, integración con X-Push para notificaciones y almacenamiento local de sesiones y memoria del modelo. La instalación es sencilla mediante un script `install.sh` que configura variables de entorno, crea volúmenes y verifica la salud del sistema.
Sin embargo, el despliegue requiere atención a la configuración del proxy inverso (Nginx), ya que cada módulo necesita una ruta específica para evitar errores 404. Además, la seguridad depende de una contraseña global (`QL_PASSWORD`) que protege todos los endpoints; si se compromete, se expone acceso total al sistema y a dispositivos externos como Home Assistant o routers.
- Núcleo backend para asistente IA personal con soporte nativo para modelos locales (Ollama) y APIs externas.
- Controlador centralizado de automatización del hogar mediante integración directa con Home Assistant.
- Gestor de infraestructura local para administrar contenedores Docker, rutas de red y monitorizar hardware.
- Plataforma RAG simple que procesa archivos PDF locales para inyectar contexto en respuestas del modelo.
- Arquitectura sin frameworks web (solo Python estándar) facilita el despliegue en NAS con recursos limitados.
- Soporte nativo para Ollama permite funcionamiento offline y procesamiento de datos localmente.
- Módulos independientes por puerto permiten depuración granular y configuración flexible con Nginx.
- Procesamiento de PDFs integrado mediante PyMuPDF para RAG sin dependencias externas complejas.
- Requiere Python 3.11 o 3.12; no es compatible con 3.13 debido al uso del módulo `cgi` en `files_api`.
- Configuración manual de rutas Nginx obligatoria para cada módulo, aumentando la complejidad inicial.
- Seguridad centralizada: una contraseña única protege todos los endpoints, incluyendo acceso a Docker y HA.
- Dependencia de SSH externo para gestión de routers o dispositivos remotos (requiere credenciales válidas).
Perfil de infraestructura
Estimación inicial derivada del repositorio y de los servicios detectados.
Despliegue detectado
Qué señales reales de instalación hemos encontrado.
Recomendado usar `install.sh` para automatizar configuración. Es imperativo configurar Nginx con rutas específicas (`location /api/xxx`) para cada módulo, ya que el servidor interno devuelve 404 si no se intercepta correctamente. Asegurar `QL_PASSWORD` fuerte y sincronizar tokens de servicio (`QL_INBOX_TOKEN`, `QL_PUSH_TOKEN`). Para modelos locales, verificar que Ollama esté corriendo y configurado en `QL_AGENT_MODEL`.
Stack y dependencias
Componentes inferidos a partir de manifests, configuración y documentación.
Puede sustituir a
Relaciones detectadas por el análisis del repositorio y su categoría.
Experiencia real de la comunidad
Ayuda a contrastar la estimación automática con instalaciones reales.
Todavía no hay datos comunitarios para este proyecto.