diff --git a/.github/copilot-instructions.ca.md b/.github/copilot-instructions.ca.md index ff30251..d4cbc7e 100644 --- a/.github/copilot-instructions.ca.md +++ b/.github/copilot-instructions.ca.md @@ -1,28 +1,28 @@ -# Cognito Stack - Instrucciones para GitHub Copilot -[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/Axlfc/connect-core/blob/master/.github/copilot-instructions.ca.md) -[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/Axlfc/connect-core/blob/master/.github/copilot-instructions.en.md) -[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/Axlfc/connect-core/blob/master/.github/copilot-instructions.md) -[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/Axlfc/connect-core/blob/master/.github/copilot-instructions.zh-cn.md) +# connect-core - Instruccions per a GitHub Copilot +[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/.github/copilot-instructions.ca.md) +[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/.github/copilot-instructions.en.md) +[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/.github/copilot-instructions.md) +[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/.github/copilot-instructions.zh-cn.md) -## Resumen del Proyecto +## Resum del Projecte -**cognito-stack** es una plataforma de automatización con IA que integra: -- **n8n**: Orquestador de workflows -- **Ollama**: Modelos LLM locales +**connect-core** és una plataforma d'automatització amb IA que integra: +- **n8n**: Orquestrador de workflows +- **Ollama**: Models LLM locals - **Whisper**: Speech-to-Text - **Kokoro**: Text-to-Speech - **Qdrant**: Vector database -- **Matrix**: Mensajería federada +- **Matrix**: Missatgeria federada - **Forgejo**: Git hosting -## Arquitectura de Servicios +## Arquitectura de Serveis -### Servicios Core (Siempre activos) +### Serveis Core (Sempre actius) ``` -PostgreSQL → Base de datos principal +PostgreSQL → Base de dades principal ↓ -Redis → Cache y sesiones +Redis → Memòria cau (cache) i sessions ↓ Qdrant → Vector embeddings ↓ @@ -31,7 +31,7 @@ Ollama → LLM inference n8n → Workflow orchestration ``` -### Servicios de Voz (Profile: voice) +### Serveis de Veu (Profile: voice) ``` Whisper STT ← Audio input ↓ @@ -40,90 +40,90 @@ n8n workflows Kokoro TTS → Audio output ``` -### Servicios Opcionales +### Serveis Opcionals - **Monitoring**: Prometheus + Grafana + Loki -- **Zrok**: Túnel público seguro -- **ComfyUI**: Generación de imágenes +- **Zrok**: Túnel públic segur +- **ComfyUI**: Generació d'imatges --- -## Comandos Críticos +## Comandes Crítiques -### Primera Inicialización (OBLIGATORIO) +### Primera Inicialització (OBLIGATORI) ```bash -# 1. Generar secrets (una sola vez) +# 1. Generar secrets (una sola vegada) ./scripts/generate-secrets.sh -# 2. Construir imágenes personalizadas (SIEMPRE PRIMERO) +# 2. Construir imatges personalitzades (SEMPRE PRIMER) docker compose --profile gpu-nvidia --profile voice build -# 3. Verificar construcción +# 3. Verificar construcció docker images | grep local/ -# 4. Iniciar servicios +# 4. Iniciar serveis docker compose --profile gpu-nvidia --profile voice up -d -# 5. Verificar estado +# 5. Verificar estat docker compose ps docker compose logs -f n8n ``` -### Desarrollo Diario +### Desenvolupament Diari ```bash -# Ver logs de un servicio -docker compose logs -f [servicio] +# Veure logs d'un servei +docker compose logs -f [servei] -# Reiniciar un servicio -docker compose restart [servicio] +# Reiniciar un servei +docker compose restart [servei] -# Reconstruir tras cambios en Dockerfile -docker compose build --no-cache [servicio] -docker compose up -d [servicio] +# Reconstruir després de canvis en Dockerfile +docker compose build --no-cache [servei] +docker compose up -d [servei] -# Detener todo +# Aturar tot docker compose down -# Detener y limpiar volúmenes (PELIGRO: borra datos) +# Aturar i netejar volums (PERILL: esborra dades) docker compose down -v ``` -### Perfiles Disponibles +### Perfils Disponibles ```bash # GPU NVIDIA + Voice docker compose --profile gpu-nvidia --profile voice up -d -# CPU only (sin GPU) +# CPU only (sense GPU) docker compose --profile cpu --profile voice-cpu up -d # AMD GPU docker compose --profile gpu-amd up -d -# Con monitoring +# Amb monitoring docker compose --profile gpu-nvidia --profile voice --profile monitoring up -d -# Con túnel Zrok +# Amb túnel Zrok docker compose --profile gpu-nvidia --profile voice --profile zrok up -d ``` --- -## Reglas de Coherencia +## Regles de Coherència -### Al Modificar docker-compose.yml +### En Modificar docker-compose.yml -1. **Servicios con `build:`** SIEMPRE necesitan: +1. **Serveis amb `build:`** SEMPRE necessiten: ```yaml build: context: . - dockerfile: Dockerfile.servicio - image: local/servicio:tag - pull_policy: build # Opcional pero recomendado + dockerfile: Dockerfile.servei + image: local/servei:tag + pull_policy: build # Opcional però recomanat ``` -2. **Servicios con GPU** SIEMPRE necesitan: +2. **Serveis amb GPU** SEMPRE necessiten: ```yaml profiles: ["gpu-nvidia"] deploy: @@ -135,20 +135,20 @@ docker compose --profile gpu-nvidia --profile voice --profile zrok up -d capabilities: [gpu] ``` -3. **Servicios con secrets** SIEMPRE necesitan: +3. **Serveis amb secrets** SEMPRE necessiten: ```yaml secrets: - - nombre_secret + - nom_secret environment: - - VARIABLE_FILE=/run/secrets/nombre_secret + - VARIABLE_FILE=/run/secrets/nom_secret ``` -### Al Crear Nuevos Servicios +### En Crear Nous Serveis -1. **Añadir healthcheck** para servicios críticos -2. **Limitar recursos** con `deploy.resources.limits` -3. **Usar redes internas** (`backend`, `ai`) para servicios no públicos -4. **Añadir logging estructurado** (json-file con rotación) +1. **Afegir healthcheck** per a serveis crítics +2. **Limitar recursos** amb `deploy.resources.limits` +3. **Utilitzar xarxes internes** (`backend`, `ai`) per a serveis no públics +4. **Afegir logging estructurat** (json-file amb rotació) 5. **Aplicar security hardening**: ```yaml security_opt: @@ -156,49 +156,49 @@ docker compose --profile gpu-nvidia --profile voice --profile zrok up -d cap_drop: - ALL cap_add: - - [SOLO_CAPABILITIES_NECESARIAS] + - [SOLS_CAPABILITIES_NECESSÀRIES] ``` --- -## Troubleshooting Rápido +## Troubleshooting Ràpid -| Error | Causa | Solución | +| Error | Causa | Solució | |-------|-------|----------| -| `pull access denied for local/*` | Imagen no construida | `docker compose build` primero | -| `failed to resolve source metadata` | Imagen base no existe | Verificar versión en Docker Hub | -| `connection refused` en healthcheck | Servicio no iniciado | Revisar logs: `docker compose logs [servicio]` | -| `secret not found` | Archivo en `./secrets/` falta | Ejecutar `./scripts/generate-secrets.sh` | -| GPU no detectada | Driver NVIDIA no instalado | Instalar `nvidia-container-toolkit` | +| `pull access denied for local/*` | Imatge no construïda | `docker compose build` primer | +| `failed to resolve source metadata` | Imatge base no existeix | Verificar versió a Docker Hub | +| `connection refused` en healthcheck | Servei no iniciat | Revisar logs: `docker compose logs [servei]` | +| `secret not found` | Fitxer a `./secrets/` falta | Executar `./scripts/generate-secrets.sh` | +| GPU no detectada | Driver NVIDIA no instal·lat | Instal·lar `nvidia-container-toolkit` | --- -## Patrones de Solución +## Patrons de Solució -### Problema: Servicio no inicia +### Problema: El servei no s'inicia ```bash -# 1. Ver logs completos -docker compose logs [servicio] --tail=100 +# 1. Veure logs complets +docker compose logs [servei] --tail=100 -# 2. Verificar dependencias +# 2. Verificar dependències docker compose ps | grep -E 'postgres|redis|qdrant' # 3. Verificar secrets ls -la secrets/ -# 4. Entrar al contenedor para debug -docker compose exec [servicio] /bin/sh +# 4. Entrar al contenidor per a depurar +docker compose exec [servei] /bin/sh ``` -### Problema: Error de permisos en volúmenes +### Problema: Error de permisos en volums ```bash # 1. Verificar ownership -docker compose exec [servicio] ls -la /path/to/volume +docker compose exec [servei] ls -la /path/to/volume -# 2. Corregir permisos (si necesario) -sudo chown -R $(id -u):$(id -g) ./volumes/[servicio] +# 2. Corregir permisos (si cal) +sudo chown -R $(id -u):$(id -g) ./volumes/[servei] ``` ### Problema: GPU no detectada @@ -210,36 +210,36 @@ nvidia-smi # 2. Verificar runtime de Docker docker run --rm --gpus all nvidia/cuda:12.3.0-base-ubuntu22.04 nvidia-smi -# 3. Si falla, reinstalar nvidia-container-toolkit +# 3. Si falla, reinstal·lar nvidia-container-toolkit ``` --- -## Variables de Entorno Críticas +## Variables d'Entorn Crítiques -### Obligatorias (en .env) +### Obligatòries (a .env) ```bash -# Base de datos +# Base de dades POSTGRES_USER=n8n_user -POSTGRES_PASSWORD= +POSTGRES_PASSWORD= POSTGRES_DB=n8n_db # n8n -N8N_ENCRYPTION_KEY= -N8N_RUNNERS_AUTH_TOKEN= -WEBHOOK_URL=https://n8n.tu-dominio.com +N8N_ENCRYPTION_KEY= +N8N_RUNNERS_AUTH_TOKEN= +WEBHOOK_URL=https://n8n.el-teu-domini.com -# Dominios (para nginx-proxy) +# Dominis (per a nginx-proxy) N8N_DOMAIN=n8n.localhost OLLAMA_DOMAIN=ollama.localhost FORGEJO_DOMAIN=forgejo.localhost ``` -### Opcionales +### Opcionals ```bash -# Ollama models (se descargan al iniciar) +# Ollama models (es descarreguen en iniciar) OLLAMA_MODEL_1=llama3:8b OLLAMA_MODEL_2=nomic-embed-text @@ -248,77 +248,77 @@ ASR_MODEL=base.en # Monitoring GRAFANA_ADMIN_USER=admin -GRAFANA_ADMIN_PASSWORD= +GRAFANA_ADMIN_PASSWORD= ``` --- -## Referencias Rápidas +## Referències Ràpides -- **Documentación completa**: `./docs/README.md` -- **Troubleshooting avanzado**: `./docs/WHISPER_TROUBLESHOOTING.md` -- **Scripts útiles**: `./scripts/` -- **Configuraciones**: `./config/` -- **Logs**: `./logs/[servicio]/` +- **Documentació completa**: `./docs/README.md` +- **Troubleshooting avançat**: `./docs/WHISPER_TROUBLESHOOTING.md` +- **Scripts útils**: `./scripts/` +- **Configuracions**: `./config/` +- **Logs**: `./logs/[servei]/` --- -## Validación de Versiones de Imágenes Base +## Validació de Versions d'Imatges Base -### ⚠️ ISSUE CONOCIDO: Imágenes Base Obsoletas +### ⚠️ ISSUE CONEGUT: Imatges Base Obsoletes -**Problema:** Las versiones de imágenes base en los Dockerfiles pueden no estar disponibles si: -- Versiones futuras son especificadas (ej: `25.01` cuando aún estamos en `24.12`) -- Imágenes son removidas de registros públicos -- Tags son renombrados o deprecated +**Problema:** Les versions d'imatges base als Dockerfiles poden no estar disponibles si: +- Versions futures són especificades (ex: `25.01` quan encara som al `24.12`) +- Les imatges són eliminades de registres públics +- Els tags són reanomenats o deprecated -**Solución rápida antes de hacer build:** +**Solució ràpida abans de fer build:** ```bash -# Ver qué imágenes se usan +# Veure quines imatges s'usen grep -h "^FROM " Dockerfile* | sort -u -# Si hay errores "not found", actualizar versión y reintentar +# Si hi ha errors "not found", actualitzar versió i reintentar docker compose build --no-cache ``` -**Versiones conocidas como estables (Jan 2026):** +**Versions conegudes com a estables (Gen 2026):** - `nvcr.io/nvidia/pytorch:24.12-py3` ✅ - `ollama/ollama:0.2.1` ✅ - `qdrant/qdrant:v1.9.2` ✅ -- `python:3.11-slim` (para LibreTranslate, vía pip) ✅ +- `python:3.11-slim` (per a LibreTranslate, via pip) ✅ - `erikvl87/languagetool:6.4` ✅ -**Versiones problemáticas:** -- `nvcr.io/nvidia/pytorch:25.01-py3` ❌ NO EXISTE (versión futura) -- `libretranslate/libretranslate:1.6.1` ❌ NO ENCONTRADA -- `libretranslate/libretranslate:1.5.0` ❌ NO ENCONTRADA (imagen oficial removida) +**Versions problemàtiques:** +- `nvcr.io/nvidia/pytorch:25.01-py3` ❌ NO EXISTEIX (versió futura) +- `libretranslate/libretranslate:1.6.1` ❌ NO TROBADA +- `libretranslate/libretranslate:1.5.0` ❌ NO TROBADA (imatge oficial eliminada) -**Solución implementada para LibreTranslate:** -- Cambio a `python:3.11-slim` + `pip install libretranslate` -- Más confiable y se mantiene automáticamente -- Ver [docs/LIBRETRANSLATE_TROUBLESHOOTING.md](../docs/LIBRETRANSLATE_TROUBLESHOOTING.md) +**Solució implementada per a LibreTranslate:** +- Canvi a `python:3.11-slim` + `pip install libretranslate` +- Més confiable i es manté automàticament +- Vegeu [docs/LIBRETRANSLATE_TROUBLESHOOTING.md](../docs/LIBRETRANSLATE_TROUBLESHOOTING.md) -**Si encuentras error "failed to resolve source metadata":** +**Si trobes l'error "failed to resolve source metadata":** ```bash -# 1. Verificar versión disponible en Docker Hub -# Ejemplo para imágenes: https://hub.docker.com/r/nombre/imagen/tags +# 1. Verificar versió disponible a Docker Hub +# Exemple per a imatges: https://hub.docker.com/r/nom/imatge/tags -# 2. Actualizar Dockerfile (si aplica) -sed -i 's/VERSION_VIEJA/VERSION_NUEVA/g' Dockerfile.servicio +# 2. Actualitzar Dockerfile (si s'aplica) +sed -i 's/VERSIO_VELLA/VERSIO_NOVA/g' Dockerfile.servei # 3. Reconstruir -docker compose build --no-cache [servicio] +docker compose build --no-cache [servei] ``` --- -## Notas para GitHub Copilot +## Notes per a GitHub Copilot -- **SIEMPRE construir antes de iniciar** servicios con `local/*` images -- **Perfiles son excluyentes**: usa `gpu-nvidia` O `cpu`, no ambos -- **Secrets son archivos**, no variables de entorno directas -- **Healthchecks tienen `start_period`**: esperar antes de diagnosticar fallos -- **Volúmenes nombrados** persisten entre reinicios, **bind mounts** reflejan cambios inmediatos -- **Versiones de imágenes**: Usar siempre versiones LTS/estables, no futures -- **LibreTranslate**: Usa Python + pip en lugar de imagen Docker oficial (más confiable) +- **SEMPRE construir abans d'iniciar** serveis amb imatges `local/*` +- **Els perfils són excloents**: usa `gpu-nvidia` O `cpu`, no tots dos +- **Els secrets són fitxers**, no variables d'entorn directes +- **Els healthchecks tenen `start_period`**: esperar abans de diagnosticar fallades +- **Els volums amb nom** persisteixen entre reinicis, els **bind mounts** reflecteixen canvis immediats +- **Versions d'imatges**: Utilitzar sempre versions LTS/estables, no futures +- **LibreTranslate**: Usa Python + pip en lloc de la imatge Docker oficial (més confiable) diff --git a/.github/copilot-instructions.en.md b/.github/copilot-instructions.en.md index 9681a84..bc4cfb2 100644 --- a/.github/copilot-instructions.en.md +++ b/.github/copilot-instructions.en.md @@ -1,28 +1,28 @@ -# Cognito Stack - Instrucciones para GitHub Copilot -[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/Axlfc/connect-core/blob/master/.github/copilot-instructions.en.md) -[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/Axlfc/connect-core/blob/master/.github/copilot-instructions.md) -[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/Axlfc/connect-core/blob/master/.github/copilot-instructions.ca.md) -[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/Axlfc/connect-core/blob/master/.github/copilot-instructions.zh-cn.md) +# connect-core - Instructions for GitHub Copilot +[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/.github/copilot-instructions.en.md) +[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/.github/copilot-instructions.md) +[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/.github/copilot-instructions.ca.md) +[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/.github/copilot-instructions.zh-cn.md) -## Resumen del Proyecto +## Project Summary -**cognito-stack** es una plataforma de automatización con IA que integra: -- **n8n**: Orquestador de workflows -- **Ollama**: Modelos LLM locales +**connect-core** is an AI automation platform that integrates: +- **n8n**: Workflow orchestrator +- **Ollama**: Local LLM models - **Whisper**: Speech-to-Text - **Kokoro**: Text-to-Speech - **Qdrant**: Vector database -- **Matrix**: Mensajería federada +- **Matrix**: Federated messaging - **Forgejo**: Git hosting -## Arquitectura de Servicios +## Service Architecture -### Servicios Core (Siempre activos) +### Core Services (Always active) ``` -PostgreSQL → Base de datos principal +PostgreSQL → Main database ↓ -Redis → Cache y sesiones +Redis → Cache and sessions ↓ Qdrant → Vector embeddings ↓ @@ -31,7 +31,7 @@ Ollama → LLM inference n8n → Workflow orchestration ``` -### Servicios de Voz (Profile: voice) +### Voice Services (Profile: voice) ``` Whisper STT ← Audio input ↓ @@ -40,90 +40,90 @@ n8n workflows Kokoro TTS → Audio output ``` -### Servicios Opcionales +### Optional Services - **Monitoring**: Prometheus + Grafana + Loki -- **Zrok**: Túnel público seguro -- **ComfyUI**: Generación de imágenes +- **Zrok**: Secure public tunnel +- **ComfyUI**: Image generation --- -## Comandos Críticos +## Critical Commands -### Primera Inicialización (OBLIGATORIO) +### First Initialization (MANDATORY) ```bash -# 1. Generar secrets (una sola vez) +# 1. Generate secrets (once) ./scripts/generate-secrets.sh -# 2. Construir imágenes personalizadas (SIEMPRE PRIMERO) +# 2. Build custom images (ALWAYS FIRST) docker compose --profile gpu-nvidia --profile voice build -# 3. Verificar construcción +# 3. Verify build docker images | grep local/ -# 4. Iniciar servicios +# 4. Start services docker compose --profile gpu-nvidia --profile voice up -d -# 5. Verificar estado +# 5. Verify status docker compose ps docker compose logs -f n8n ``` -### Desarrollo Diario +### Daily Development ```bash -# Ver logs de un servicio -docker compose logs -f [servicio] +# View logs of a service +docker compose logs -f [service] -# Reiniciar un servicio -docker compose restart [servicio] +# Restart a service +docker compose restart [service] -# Reconstruir tras cambios en Dockerfile -docker compose build --no-cache [servicio] -docker compose up -d [servicio] +# Rebuild after changes in Dockerfile +docker compose build --no-cache [service] +docker compose up -d [service] -# Detener todo +# Stop everything docker compose down -# Detener y limpiar volúmenes (PELIGRO: borra datos) +# Stop and clean volumes (DANGER: deletes data) docker compose down -v ``` -### Perfiles Disponibles +### Available Profiles ```bash # GPU NVIDIA + Voice docker compose --profile gpu-nvidia --profile voice up -d -# CPU only (sin GPU) +# CPU only (without GPU) docker compose --profile cpu --profile voice-cpu up -d # AMD GPU docker compose --profile gpu-amd up -d -# Con monitoring +# With monitoring docker compose --profile gpu-nvidia --profile voice --profile monitoring up -d -# Con túnel Zrok +# With Zrok tunnel docker compose --profile gpu-nvidia --profile voice --profile zrok up -d ``` --- -## Reglas de Coherencia +## Consistency Rules -### Al Modificar docker-compose.yml +### When Modifying docker-compose.yml -1. **Servicios con `build:`** SIEMPRE necesitan: +1. **Services with `build:`** ALWAYS need: ```yaml build: context: . - dockerfile: Dockerfile.servicio - image: local/servicio:tag - pull_policy: build # Opcional pero recomendado + dockerfile: Dockerfile.service + image: local/service:tag + pull_policy: build # Optional but recommended ``` -2. **Servicios con GPU** SIEMPRE necesitan: +2. **Services with GPU** ALWAYS need: ```yaml profiles: ["gpu-nvidia"] deploy: @@ -135,111 +135,111 @@ docker compose --profile gpu-nvidia --profile voice --profile zrok up -d capabilities: [gpu] ``` -3. **Servicios con secrets** SIEMPRE necesitan: +3. **Services with secrets** ALWAYS need: ```yaml secrets: - - nombre_secret + - secret_name environment: - - VARIABLE_FILE=/run/secrets/nombre_secret + - VARIABLE_FILE=/run/secrets/secret_name ``` -### Al Crear Nuevos Servicios +### When Creating New Services -1. **Añadir healthcheck** para servicios críticos -2. **Limitar recursos** con `deploy.resources.limits` -3. **Usar redes internas** (`backend`, `ai`) para servicios no públicos -4. **Añadir logging estructurado** (json-file con rotación) -5. **Aplicar security hardening**: +1. **Add healthcheck** for critical services +2. **Limit resources** with `deploy.resources.limits` +3. **Use internal networks** (`backend`, `ai`) for non-public services +4. **Add structured logging** (json-file with rotation) +5. **Apply security hardening**: ```yaml security_opt: - no-new-privileges:true cap_drop: - ALL cap_add: - - [SOLO_CAPABILITIES_NECESARIAS] + - [ONLY_NECESSARY_CAPABILITIES] ``` --- -## Troubleshooting Rápido +## Quick Troubleshooting -| Error | Causa | Solución | +| Error | Cause | Solution | |-------|-------|----------| -| `pull access denied for local/*` | Imagen no construida | `docker compose build` primero | -| `failed to resolve source metadata` | Imagen base no existe | Verificar versión en Docker Hub | -| `connection refused` en healthcheck | Servicio no iniciado | Revisar logs: `docker compose logs [servicio]` | -| `secret not found` | Archivo en `./secrets/` falta | Ejecutar `./scripts/generate-secrets.sh` | -| GPU no detectada | Driver NVIDIA no instalado | Instalar `nvidia-container-toolkit` | +| `pull access denied for local/*` | Image not built | `docker compose build` first | +| `failed to resolve source metadata` | Base image does not exist | Verify version on Docker Hub | +| `connection refused` in healthcheck | Service not started | Check logs: `docker compose logs [service]` | +| `secret not found` | File in `./secrets/` missing | Run `./scripts/generate-secrets.sh` | +| GPU not detected | NVIDIA driver not installed | Install `nvidia-container-toolkit` | --- -## Patrones de Solución +## Solution Patterns -### Problema: Servicio no inicia +### Problem: Service does not start ```bash -# 1. Ver logs completos -docker compose logs [servicio] --tail=100 +# 1. View full logs +docker compose logs [service] --tail=100 -# 2. Verificar dependencias +# 2. Verify dependencies docker compose ps | grep -E 'postgres|redis|qdrant' -# 3. Verificar secrets +# 3. Verify secrets ls -la secrets/ -# 4. Entrar al contenedor para debug -docker compose exec [servicio] /bin/sh +# 4. Enter container for debugging +docker compose exec [service] /bin/sh ``` -### Problema: Error de permisos en volúmenes +### Problem: Volume permission error ```bash -# 1. Verificar ownership -docker compose exec [servicio] ls -la /path/to/volume +# 1. Verify ownership +docker compose exec [service] ls -la /path/to/volume -# 2. Corregir permisos (si necesario) -sudo chown -R $(id -u):$(id -g) ./volumes/[servicio] +# 2. Fix permissions (if necessary) +sudo chown -R $(id -u):$(id -g) ./volumes/[service] ``` -### Problema: GPU no detectada +### Problem: GPU not detected ```bash -# 1. Verificar driver +# 1. Verify driver nvidia-smi -# 2. Verificar runtime de Docker +# 2. Verify Docker runtime docker run --rm --gpus all nvidia/cuda:12.3.0-base-ubuntu22.04 nvidia-smi -# 3. Si falla, reinstalar nvidia-container-toolkit +# 3. If it fails, reinstall nvidia-container-toolkit ``` --- -## Variables de Entorno Críticas +## Critical Environment Variables -### Obligatorias (en .env) +### Mandatory (in .env) ```bash -# Base de datos +# Database POSTGRES_USER=n8n_user -POSTGRES_PASSWORD= +POSTGRES_PASSWORD= POSTGRES_DB=n8n_db # n8n -N8N_ENCRYPTION_KEY= -N8N_RUNNERS_AUTH_TOKEN= -WEBHOOK_URL=https://n8n.tu-dominio.com +N8N_ENCRYPTION_KEY= +N8N_RUNNERS_AUTH_TOKEN= +WEBHOOK_URL=https://n8n.your-domain.com -# Dominios (para nginx-proxy) +# Domains (for nginx-proxy) N8N_DOMAIN=n8n.localhost OLLAMA_DOMAIN=ollama.localhost FORGEJO_DOMAIN=forgejo.localhost ``` -### Opcionales +### Optional ```bash -# Ollama models (se descargan al iniciar) +# Ollama models (downloaded at start) OLLAMA_MODEL_1=llama3:8b OLLAMA_MODEL_2=nomic-embed-text @@ -248,77 +248,77 @@ ASR_MODEL=base.en # Monitoring GRAFANA_ADMIN_USER=admin -GRAFANA_ADMIN_PASSWORD= +GRAFANA_ADMIN_PASSWORD= ``` --- -## Referencias Rápidas +## Quick References -- **Documentación completa**: `./docs/README.md` -- **Troubleshooting avanzado**: `./docs/WHISPER_TROUBLESHOOTING.md` -- **Scripts útiles**: `./scripts/` -- **Configuraciones**: `./config/` -- **Logs**: `./logs/[servicio]/` +- **Full documentation**: `./docs/README.md` +- **Advanced troubleshooting**: `./docs/WHISPER_TROUBLESHOOTING.md` +- **Useful scripts**: `./scripts/` +- **Configurations**: `./config/` +- **Logs**: `./logs/[service]/` --- -## Validación de Versiones de Imágenes Base +## Image Base Version Validation -### ⚠️ ISSUE CONOCIDO: Imágenes Base Obsoletas +### ⚠️ KNOWN ISSUE: Obsolete Base Images -**Problema:** Las versiones de imágenes base en los Dockerfiles pueden no estar disponibles si: -- Versiones futuras son especificadas (ej: `25.01` cuando aún estamos en `24.12`) -- Imágenes son removidas de registros públicos -- Tags son renombrados o deprecated +**Problem:** Base image versions in Dockerfiles may not be available if: +- Future versions are specified (e.g.: `25.01` when we are still in `24.12`) +- Images are removed from public registries +- Tags are renamed or deprecated -**Solución rápida antes de hacer build:** +**Quick fix before building:** ```bash -# Ver qué imágenes se usan +# See which images are used grep -h "^FROM " Dockerfile* | sort -u -# Si hay errores "not found", actualizar versión y reintentar +# If there are "not found" errors, update version and retry docker compose build --no-cache ``` -**Versiones conocidas como estables (Jan 2026):** +**Known stable versions (Jan 2026):** - `nvcr.io/nvidia/pytorch:24.12-py3` ✅ - `ollama/ollama:0.2.1` ✅ - `qdrant/qdrant:v1.9.2` ✅ -- `python:3.11-slim` (para LibreTranslate, vía pip) ✅ +- `python:3.11-slim` (for LibreTranslate, via pip) ✅ - `erikvl87/languagetool:6.4` ✅ -**Versiones problemáticas:** -- `nvcr.io/nvidia/pytorch:25.01-py3` ❌ NO EXISTE (versión futura) -- `libretranslate/libretranslate:1.6.1` ❌ NO ENCONTRADA -- `libretranslate/libretranslate:1.5.0` ❌ NO ENCONTRADA (imagen oficial removida) +**Problematic versions:** +- `nvcr.io/nvidia/pytorch:25.01-py3` ❌ DOES NOT EXIST (future version) +- `libretranslate/libretranslate:1.6.1` ❌ NOT FOUND +- `libretranslate/libretranslate:1.5.0` ❌ NOT FOUND (official image removed) -**Solución implementada para LibreTranslate:** -- Cambio a `python:3.11-slim` + `pip install libretranslate` -- Más confiable y se mantiene automáticamente -- Ver [docs/LIBRETRANSLATE_TROUBLESHOOTING.md](../docs/LIBRETRANSLATE_TROUBLESHOOTING.md) +**Implemented solution for LibreTranslate:** +- Switched to `python:3.11-slim` + `pip install libretranslate` +- More reliable and automatically maintained +- See [docs/LIBRETRANSLATE_TROUBLESHOOTING.md](../docs/LIBRETRANSLATE_TROUBLESHOOTING.md) -**Si encuentras error "failed to resolve source metadata":** +**If you encounter "failed to resolve source metadata" error:** ```bash -# 1. Verificar versión disponible en Docker Hub -# Ejemplo para imágenes: https://hub.docker.com/r/nombre/imagen/tags +# 1. Verify available version on Docker Hub +# Example for images: https://hub.docker.com/r/name/image/tags -# 2. Actualizar Dockerfile (si aplica) -sed -i 's/VERSION_VIEJA/VERSION_NUEVA/g' Dockerfile.servicio +# 2. Update Dockerfile (if applicable) +sed -i 's/OLD_VERSION/NEW_VERSION/g' Dockerfile.service -# 3. Reconstruir -docker compose build --no-cache [servicio] +# 3. Rebuild +docker compose build --no-cache [service] ``` --- -## Notas para GitHub Copilot +## Notes for GitHub Copilot -- **SIEMPRE construir antes de iniciar** servicios con `local/*` images -- **Perfiles son excluyentes**: usa `gpu-nvidia` O `cpu`, no ambos -- **Secrets son archivos**, no variables de entorno directas -- **Healthchecks tienen `start_period`**: esperar antes de diagnosticar fallos -- **Volúmenes nombrados** persisten entre reinicios, **bind mounts** reflejan cambios inmediatos -- **Versiones de imágenes**: Usar siempre versiones LTS/estables, no futures -- **LibreTranslate**: Usa Python + pip en lugar de imagen Docker oficial (más confiable) +- **ALWAYS build before starting** services with `local/*` images +- **Profiles are mutually exclusive**: use `gpu-nvidia` OR `cpu`, not both +- **Secrets are files**, not direct environment variables +- **Healthchecks have `start_period`**: wait before diagnosing failures +- **Named volumes** persist between restarts, **bind mounts** reflect immediate changes +- **Image versions**: Always use LTS/stable versions, not future ones +- **LibreTranslate**: Uses Python + pip instead of official Docker image (more reliable) diff --git a/.github/copilot-instructions.zh-cn.md b/.github/copilot-instructions.zh-cn.md index d66532d..6dff332 100644 --- a/.github/copilot-instructions.zh-cn.md +++ b/.github/copilot-instructions.zh-cn.md @@ -1,129 +1,129 @@ -# Cognito Stack - Instrucciones para GitHub Copilot -[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/Axlfc/connect-core/blob/master/.github/copilot-instructions.zh-cn.md) -[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/Axlfc/connect-core/blob/master/.github/copilot-instructions.en.md) -[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/Axlfc/connect-core/blob/master/.github/copilot-instructions.md) -[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/Axlfc/connect-core/blob/master/.github/copilot-instructions.ca.md) +# connect-core - GitHub Copilot 指令 +[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/.github/copilot-instructions.zh-cn.md) +[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/.github/copilot-instructions.en.md) +[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/.github/copilot-instructions.md) +[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/.github/copilot-instructions.ca.md) -## Resumen del Proyecto +## 项目摘要 -**cognito-stack** es una plataforma de automatización con IA que integra: -- **n8n**: Orquestador de workflows -- **Ollama**: Modelos LLM locales -- **Whisper**: Speech-to-Text -- **Kokoro**: Text-to-Speech -- **Qdrant**: Vector database -- **Matrix**: Mensajería federada -- **Forgejo**: Git hosting +**connect-core** 是一个集成了以下组件的 AI 自动化平台： +- **n8n**: 工作流编排器 +- **Ollama**: 本地 LLM 模型 +- **Whisper**: 语音转文本 (STT) +- **Kokoro**: 文本转语音 (TTS) +- **Qdrant**: 向量数据库 +- **Matrix**: 联邦消息传递 +- **Forgejo**: Git 托管 -## Arquitectura de Servicios +## 服务架构 -### Servicios Core (Siempre activos) +### 核心服务（始终活动） ``` -PostgreSQL → Base de datos principal +PostgreSQL → 主数据库 ↓ -Redis → Cache y sesiones +Redis → 缓存和会话 ↓ -Qdrant → Vector embeddings +Qdrant → 向量嵌入 (Embeddings) ↓ -Ollama → LLM inference +Ollama → LLM 推理 ↓ -n8n → Workflow orchestration +n8n → 工作流编排 ``` -### Servicios de Voz (Profile: voice) +### 语音服务（配置文件：voice） ``` -Whisper STT ← Audio input +Whisper STT ← 音频输入 ↓ -n8n workflows +n8n 工作流 ↓ -Kokoro TTS → Audio output +Kokoro TTS → 音频输出 ``` -### Servicios Opcionales +### 可选服务 - **Monitoring**: Prometheus + Grafana + Loki -- **Zrok**: Túnel público seguro -- **ComfyUI**: Generación de imágenes +- **Zrok**: 安全公共隧道 +- **ComfyUI**: 图像生成 --- -## Comandos Críticos +## 关键命令 -### Primera Inicialización (OBLIGATORIO) +### 首次初始化（必须执行） ```bash -# 1. Generar secrets (una sola vez) +# 1. 生成机密信息 (Secrets)（仅需执行一次） ./scripts/generate-secrets.sh -# 2. Construir imágenes personalizadas (SIEMPRE PRIMERO) +# 2. 构建自定义镜像（务必首先执行） docker compose --profile gpu-nvidia --profile voice build -# 3. Verificar construcción +# 3. 验证构建结果 docker images | grep local/ -# 4. Iniciar servicios +# 4. 启动服务 docker compose --profile gpu-nvidia --profile voice up -d -# 5. Verificar estado +# 5. 验证状态 docker compose ps docker compose logs -f n8n ``` -### Desarrollo Diario +### 日常开发 ```bash -# Ver logs de un servicio -docker compose logs -f [servicio] +# 查看某个服务的日志 +docker compose logs -f [service] -# Reiniciar un servicio -docker compose restart [servicio] +# 重启某个服务 +docker compose restart [service] -# Reconstruir tras cambios en Dockerfile -docker compose build --no-cache [servicio] -docker compose up -d [servicio] +# 修改 Dockerfile 后重新构建 +docker compose build --no-cache [service] +docker compose up -d [service] -# Detener todo +# 停止所有服务 docker compose down -# Detener y limpiar volúmenes (PELIGRO: borra datos) +# 停止并清理卷（危险：会删除数据） docker compose down -v ``` -### Perfiles Disponibles +### 可用配置文件 (Profiles) ```bash -# GPU NVIDIA + Voice +# NVIDIA GPU + 语音服务 docker compose --profile gpu-nvidia --profile voice up -d -# CPU only (sin GPU) +# 仅 CPU（无 GPU） docker compose --profile cpu --profile voice-cpu up -d # AMD GPU docker compose --profile gpu-amd up -d -# Con monitoring +# 带监控功能 docker compose --profile gpu-nvidia --profile voice --profile monitoring up -d -# Con túnel Zrok +# 带 Zrok 隧道 docker compose --profile gpu-nvidia --profile voice --profile zrok up -d ``` --- -## Reglas de Coherencia +## 一致性规则 -### Al Modificar docker-compose.yml +### 修改 docker-compose.yml 时 -1. **Servicios con `build:`** SIEMPRE necesitan: +1. **带有 `build:` 的服务** 始终需要： ```yaml build: context: . - dockerfile: Dockerfile.servicio - image: local/servicio:tag - pull_policy: build # Opcional pero recomendado + dockerfile: Dockerfile.service + image: local/service:tag + pull_policy: build # 可选但推荐 ``` -2. **Servicios con GPU** SIEMPRE necesitan: +2. **使用 GPU 的服务** 始终需要： ```yaml profiles: ["gpu-nvidia"] deploy: @@ -135,190 +135,190 @@ docker compose --profile gpu-nvidia --profile voice --profile zrok up -d capabilities: [gpu] ``` -3. **Servicios con secrets** SIEMPRE necesitan: +3. **使用机密信息的服务** 始终需要： ```yaml secrets: - - nombre_secret + - secret_name environment: - - VARIABLE_FILE=/run/secrets/nombre_secret + - VARIABLE_FILE=/run/secrets/secret_name ``` -### Al Crear Nuevos Servicios +### 创建新服务时 -1. **Añadir healthcheck** para servicios críticos -2. **Limitar recursos** con `deploy.resources.limits` -3. **Usar redes internas** (`backend`, `ai`) para servicios no públicos -4. **Añadir logging estructurado** (json-file con rotación) -5. **Aplicar security hardening**: +1. 为关键服务**添加健康检查 (Healthcheck)** +2. 通过 `deploy.resources.limits` **限制资源** +3. 为非公共服务**使用内部网络** (`backend`, `ai`) +4. **添加结构化日志** (带有轮转功能的 json-file) +5. **应用安全增强**: ```yaml security_opt: - no-new-privileges:true cap_drop: - ALL cap_add: - - [SOLO_CAPABILITIES_NECESARIAS] + - [仅必要的 CAPABILITIES] ``` --- -## Troubleshooting Rápido +## 快速故障排除 -| Error | Causa | Solución | +| 错误 | 原因 | 解决方案 | |-------|-------|----------| -| `pull access denied for local/*` | Imagen no construida | `docker compose build` primero | -| `failed to resolve source metadata` | Imagen base no existe | Verificar versión en Docker Hub | -| `connection refused` en healthcheck | Servicio no iniciado | Revisar logs: `docker compose logs [servicio]` | -| `secret not found` | Archivo en `./secrets/` falta | Ejecutar `./scripts/generate-secrets.sh` | -| GPU no detectada | Driver NVIDIA no instalado | Instalar `nvidia-container-toolkit` | +| `pull access denied for local/*` | 镜像未构建 | 首先运行 `docker compose build` | +| `failed to resolve source metadata` | 基础镜像不存在 | 在 Docker Hub 上核实版本 | +| 健康检查中 `connection refused` | 服务未启动 | 检查日志：`docker compose logs [service]` | +| `secret not found` | `./secrets/` 中的文件缺失 | 运行 `./scripts/generate-secrets.sh` | +| 未检测到 GPU | 未安装 NVIDIA 驱动 | 安装 `nvidia-container-toolkit` | --- -## Patrones de Solución +## 解决方案模式 -### Problema: Servicio no inicia +### 问题：服务无法启动 ```bash -# 1. Ver logs completos -docker compose logs [servicio] --tail=100 +# 1. 查看完整日志 +docker compose logs [service] --tail=100 -# 2. Verificar dependencias +# 2. 验证依赖项 docker compose ps | grep -E 'postgres|redis|qdrant' -# 3. Verificar secrets +# 3. 验证机密信息 ls -la secrets/ -# 4. Entrar al contenedor para debug -docker compose exec [servicio] /bin/sh +# 4. 进入容器进行调试 +docker compose exec [service] /bin/sh ``` -### Problema: Error de permisos en volúmenes +### 问题：卷权限错误 ```bash -# 1. Verificar ownership -docker compose exec [servicio] ls -la /path/to/volume +# 1. 验证所有权 +docker compose exec [service] ls -la /path/to/volume -# 2. Corregir permisos (si necesario) -sudo chown -R $(id -u):$(id -g) ./volumes/[servicio] +# 2. 修复权限（如有必要） +sudo chown -R $(id -u):$(id -g) ./volumes/[service] ``` -### Problema: GPU no detectada +### 问题：未检测到 GPU ```bash -# 1. Verificar driver +# 1. 验证驱动程序 nvidia-smi -# 2. Verificar runtime de Docker +# 2. 验证 Docker 运行时 docker run --rm --gpus all nvidia/cuda:12.3.0-base-ubuntu22.04 nvidia-smi -# 3. Si falla, reinstalar nvidia-container-toolkit +# 3. 如果失败，请重新安装 nvidia-container-toolkit ``` --- -## Variables de Entorno Críticas +## 关键环境变量 -### Obligatorias (en .env) +### 强制性（在 .env 中） ```bash -# Base de datos +# 数据库 POSTGRES_USER=n8n_user -POSTGRES_PASSWORD= +POSTGRES_PASSWORD=<已生成> POSTGRES_DB=n8n_db # n8n -N8N_ENCRYPTION_KEY= -N8N_RUNNERS_AUTH_TOKEN= -WEBHOOK_URL=https://n8n.tu-dominio.com +N8N_ENCRYPTION_KEY=<已生成> +N8N_RUNNERS_AUTH_TOKEN=<已生成> +WEBHOOK_URL=https://n8n.your-domain.com -# Dominios (para nginx-proxy) +# 域名（用于 nginx-proxy） N8N_DOMAIN=n8n.localhost OLLAMA_DOMAIN=ollama.localhost FORGEJO_DOMAIN=forgejo.localhost ``` -### Opcionales +### 可选 ```bash -# Ollama models (se descargan al iniciar) +# Ollama 模型（启动时下载） OLLAMA_MODEL_1=llama3:8b OLLAMA_MODEL_2=nomic-embed-text -# Whisper model +# Whisper 模型 ASR_MODEL=base.en -# Monitoring +# 监控 GRAFANA_ADMIN_USER=admin -GRAFANA_ADMIN_PASSWORD= +GRAFANA_ADMIN_PASSWORD=<已生成> ``` --- -## Referencias Rápidas +## 快速参考 -- **Documentación completa**: `./docs/README.md` -- **Troubleshooting avanzado**: `./docs/WHISPER_TROUBLESHOOTING.md` -- **Scripts útiles**: `./scripts/` -- **Configuraciones**: `./config/` -- **Logs**: `./logs/[servicio]/` +- **完整文档**: `./docs/README.md` +- **高级故障排除**: `./docs/WHISPER_TROUBLESHOOTING.md` +- **有用脚本**: `./scripts/` +- **配置文件**: `./config/` +- **日志**: `./logs/[service]/` --- -## Validación de Versiones de Imágenes Base +## 基础镜像版本验证 -### ⚠️ ISSUE CONOCIDO: Imágenes Base Obsoletas +### ⚠️ 已知问题：基础镜像过时 -**Problema:** Las versiones de imágenes base en los Dockerfiles pueden no estar disponibles si: -- Versiones futuras son especificadas (ej: `25.01` cuando aún estamos en `24.12`) -- Imágenes son removidas de registros públicos -- Tags son renombrados o deprecated +**问题：** 如果发生以下情况，Dockerfile 中的基础镜像版本可能不可用： +- 指定了未来版本（例如：现在是 `24.12`，却指定了 `25.01`） +- 镜像从公共注册表中被移除 +- 标签 (Tags) 被重命名或弃用 -**Solución rápida antes de hacer build:** +**构建前的快速修复：** ```bash -# Ver qué imágenes se usan +# 查看使用了哪些镜像 grep -h "^FROM " Dockerfile* | sort -u -# Si hay errores "not found", actualizar versión y reintentar +# 如果出现 "not found" 错误，请更新版本并重试 docker compose build --no-cache ``` -**Versiones conocidas como estables (Jan 2026):** +**已知稳定版本 (2026年1月):** - `nvcr.io/nvidia/pytorch:24.12-py3` ✅ - `ollama/ollama:0.2.1` ✅ - `qdrant/qdrant:v1.9.2` ✅ -- `python:3.11-slim` (para LibreTranslate, vía pip) ✅ +- `python:3.11-slim` (用于 LibreTranslate，通过 pip 安装) ✅ - `erikvl87/languagetool:6.4` ✅ -**Versiones problemáticas:** -- `nvcr.io/nvidia/pytorch:25.01-py3` ❌ NO EXISTE (versión futura) -- `libretranslate/libretranslate:1.6.1` ❌ NO ENCONTRADA -- `libretranslate/libretranslate:1.5.0` ❌ NO ENCONTRADA (imagen oficial removida) +**有问题的版本:** +- `nvcr.io/nvidia/pytorch:25.01-py3` ❌ 不存在（未来版本） +- `libretranslate/libretranslate:1.6.1` ❌ 未找到 +- `libretranslate/libretranslate:1.5.0` ❌ 未找到（官方镜像已被移除） -**Solución implementada para LibreTranslate:** -- Cambio a `python:3.11-slim` + `pip install libretranslate` -- Más confiable y se mantiene automáticamente -- Ver [docs/LIBRETRANSLATE_TROUBLESHOOTING.md](../docs/LIBRETRANSLATE_TROUBLESHOOTING.md) +**针对 LibreTranslate 实施的解决方案:** +- 切换到 `python:3.11-slim` + `pip install libretranslate` +- 更可靠且自动维护 +- 参见 [docs/LIBRETRANSLATE_TROUBLESHOOTING.md](../docs/LIBRETRANSLATE_TROUBLESHOOTING.md) -**Si encuentras error "failed to resolve source metadata":** +**如果遇到 "failed to resolve source metadata" 错误:** ```bash -# 1. Verificar versión disponible en Docker Hub -# Ejemplo para imágenes: https://hub.docker.com/r/nombre/imagen/tags +# 1. 在 Docker Hub 上验证可用版本 +# 镜像示例：https://hub.docker.com/r/name/image/tags -# 2. Actualizar Dockerfile (si aplica) -sed -i 's/VERSION_VIEJA/VERSION_NUEVA/g' Dockerfile.servicio +# 2. 更新 Dockerfile（如果适用） +sed -i 's/OLD_VERSION/NEW_VERSION/g' Dockerfile.service -# 3. Reconstruir -docker compose build --no-cache [servicio] +# 3. 重新构建 +docker compose build --no-cache [service] ``` --- -## Notas para GitHub Copilot +## GitHub Copilot 注意事项 -- **SIEMPRE construir antes de iniciar** servicios con `local/*` images -- **Perfiles son excluyentes**: usa `gpu-nvidia` O `cpu`, no ambos -- **Secrets son archivos**, no variables de entorno directas -- **Healthchecks tienen `start_period`**: esperar antes de diagnosticar fallos -- **Volúmenes nombrados** persisten entre reinicios, **bind mounts** reflejan cambios inmediatos -- **Versiones de imágenes**: Usar siempre versiones LTS/estables, no futures -- **LibreTranslate**: Usa Python + pip en lugar de imagen Docker oficial (más confiable) +- 在启动使用 `local/*` 镜像的服务前，**务必先进行构建** +- **配置文件是互斥的**：使用 `gpu-nvidia` 或 `cpu`，不要同时使用两者 +- **机密信息是文件**，而不是直接的环境变量 +- **健康检查有 `start_period`**：在诊断故障前请先等待 +- **命名卷 (Named volumes)** 在重启之间持久存在，**绑定挂载 (Bind mounts)** 反映即时更改 +- **镜像版本**：始终使用 LTS/稳定版本，不要使用未来版本 +- **LibreTranslate**: 使用 Python + pip 而不是官方 Docker 镜像（更可靠） diff --git a/AUTHELIA_FAQ.ca.md b/AUTHELIA_FAQ.ca.md index c94a7f3..81c4ada 100644 --- a/AUTHELIA_FAQ.ca.md +++ b/AUTHELIA_FAQ.ca.md @@ -1,18 +1,18 @@ -# Configuración de Authelia - FAQ y Respuestas a sus Preguntas -[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/Axlfc/connect-core/blob/master/AUTHELIA_FAQ.ca.md) -[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/Axlfc/connect-core/blob/master/AUTHELIA_FAQ.en.md) -[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/Axlfc/connect-core/blob/master/AUTHELIA_FAQ.md) -[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/Axlfc/connect-core/blob/master/AUTHELIA_FAQ.zh-cn.md) +# Configuració d'Authelia - FAQ i Respostes a les vostres preguntes +[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/AUTHELIA_FAQ.ca.md) +[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/AUTHELIA_FAQ.en.md) +[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/AUTHELIA_FAQ.md) +[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/AUTHELIA_FAQ.zh-cn.md) -## Q1: Configuración SMTP - ¿Cuál es la forma correcta de configurar SMTP? +## Q1: Configuració SMTP - Quina és la forma correcta de configurar l'SMTP? -### Su pregunta -"¿Cuál es la forma correcta de configurar SMTP en el nuevo formato? ¿Deberíamos usar `notifier.smtp.address` en lugar de `host` y `port` por separado?" +### La vostra pregunta +"Quina és la forma correcta de configurar l'SMTP en el nou format? Hauríem d'utilitzar `notifier.smtp.address` en lloc d' `host` i `port` per separat?" -### Respuesta: SÍ, use solo el formato `address` +### Resposta: SÍ, utilitzeu només el format `address` -**Correcto (Moderno v4.38.0+)**: +**Correcte (Modern v4.38.0+)**: ```yaml notifier: smtp: @@ -24,90 +24,90 @@ notifier: skip_verify: false ``` -**Formato**: `smtp[s]://[usuario@]host[:puerto]` +**Format**: `smtp[s]://[usuari@]host[:port]` -**Ejemplos**: +**Exemples**: ``` -smtp://smtp.example.com:587 # STARTTLS en el puerto 587 -smtps://smtp.example.com:465 # TLS implícito en el puerto 465 -smtp://user@smtp.example.com:587 # Con usuario en la URL +smtp://smtp.example.com:587 # STARTTLS al port 587 +smtps://smtp.example.com:465 # TLS implícit al port 465 +smtp://user@smtp.example.com:587 # Amb usuari a la URL ``` -**Credenciales mediante variables de entorno**: +**Credencials mitjançant variables d'entorn**: ```yaml environment: - AUTHELIA_NOTIFIER_SMTP_ADDRESS=smtp://smtp.tinet.cat:587 - - AUTHELIA_NOTIFIER_SMTP_USERNAME=su_correo@example.com - - AUTHELIA_NOTIFIER_SMTP_PASSWORD=su_contraseña + - AUTHELIA_NOTIFIER_SMTP_USERNAME=el_vostre_correu@example.com + - AUTHELIA_NOTIFIER_SMTP_PASSWORD=la_vostra_contrasenya - AUTHELIA_NOTIFIER_SMTP_SENDER=Authelia ``` -**Desde `.env`**: +**Des de `.env`**: ```bash SMTP_HOST=smtp.tinet.cat SMTP_PORT=587 -SMTP_USERNAME=su_correo@example.com -SMTP_PASSWORD=su_contraseña +SMTP_USERNAME=el_vostre_correu@example.com +SMTP_PASSWORD=la_vostra_contrasenya SMTP_SENDER=Authelia ``` -**NO mezcle formatos** (causará conflicto): +**NO barregeu formats** (causarà conflicte): ```yaml -# ❌ INCORRECTO - Esto causa el error de conflicto: +# ❌ INCORRECTE - Això causa l'error de conflicte: notifier: smtp: - host: smtp.example.com # ❌ Formato antiguo - port: 587 # ❌ Formato antiguo - address: 'smtp://...:587' # ❌ Formato nuevo (¡conflicto!) + host: smtp.example.com # ❌ Format antic + port: 587 # ❌ Format antic + address: 'smtp://...:587' # ❌ Format nou (conflicte!) ``` --- -## Q2: Cookies de sesión para Localhost +## Q2: Cookies de sessió per a Localhost -### Su pregunta -"¿Cómo debemos configurar las cookies de sesión para el desarrollo local usando dominios `.localhost`? El error indica que los dominios deben tener un punto o ser una dirección IP." +### La vostra pregunta +"Com hem de configurar les cookies de sessió per al desenvolupament local utilitzant dominis `.localhost`? L'error indica que els dominis han de tenir un punt o ser una adreça IP." -### Respuesta: Use `localhost` en la configuración, nginx-proxy gestiona la compatibilidad del navegador +### Resposta: Utilitzeu `localhost` a la configuració, nginx-proxy gestiona la compatibilitat del navegador -**La Configuración**: +**La Configuració**: ```yaml session: cookies: - name: authelia_session - domain: localhost # ✅ Correcto para la red Docker + domain: localhost # ✅ Correcte per a la xarxa Docker authelia_url: https://auth.localhost default_redirection_url: https://forgejo.localhost same_site: Lax - secure: false # Cambiar a true en producción + secure: false # Canviar a true en producció ``` -**Cómo funciona**: -1. **Red Docker**: Los servicios se comunican usando `localhost` (funciona bien) -2. **Acceso desde el navegador**: El usuario va a `http://auth.localhost:9091` -3. **nginx-proxy**: Intercepta la petición a `auth.localhost` y la dirige a Authelia -4. **Dominio de la cookie**: nginx-proxy gestiona la reescritura de la cookie para la compatibilidad del navegador -5. **Resultado**: El navegador nunca ve el dominio `localhost` inválido directamente +**Com funciona**: +1. **Xarxa Docker**: Els serveis es comuniquen utilitzant `localhost` (funciona bé) +2. **Accés des del navegador**: L'usuari va a `http://auth.localhost:9091` +3. **nginx-proxy**: Intercepta la petició a `auth.localhost` i la dirigeix a Authelia +4. **Domini de la cookie**: nginx-proxy gestiona la reescriptura de la cookie per a la compatibilitat del navegador +5. **Resultat**: El navegador mai veu el domini `localhost` invàlid directament -**Por qué funciona esto**: -- El DNS interno de Docker resuelve `localhost` dentro de los contenedores -- El navegador nunca establece cookies directamente en el dominio `localhost` -- nginx-proxy intermedia y gestiona la traducción del dominio de la cookie -- Tanto el acceso interno de Docker como el del navegador funcionan perfectamente +**Per què funciona això**: +- El DNS intern de Docker resol `localhost` dins dels contenidors +- El navegador mai estableix cookies directament al domini `localhost` +- nginx-proxy intermedia i gestiona la traducció del domini de la cookie +- Tant l'accés intern de Docker com el del navegador funcionen perfectament -**Qué NO hacer**: +**Què NO fer**: ```yaml -# ❌ INCORRECTO - Esto también fallará: -domain: .localhost # El navegador sigue rechazando dominios de una sola etiqueta +# ❌ INCORRECTE - Això també fallarà: +domain: .localhost # El navegador continua rebutjant dominis d'una sola etiqueta -# ❌ INCORRECTO - Demasiado restrictivo para desarrollo: -domain: auth.localhost # Solo funciona para auth.localhost, no para otros servicios +# ❌ INCORRECTE - Massa restrictiu per a desenvolupament: +domain: auth.localhost # Només funciona per a auth.localhost, no per a altres serveis -# ✅ CORRECTO: -domain: localhost # Funciona para la red Docker + nginx-proxy gestiona el navegador +# ✅ CORRECTE: +domain: localhost # Funciona per a la xarxa Docker + nginx-proxy gestiona el navegador ``` -**Variables de entorno**: +**Variables d'entorn**: ```yaml environment: - VIRTUAL_HOST=${AUTHELIA_DOMAIN:-auth.localhost} @@ -121,34 +121,34 @@ AUTHELIA_DOMAIN=auth.localhost --- -## Q3: Migración del Secreto JWT +## Q3: Migració del Secret JWT -### Su pregunta -"¿Deberíamos actualizar el archivo de configuración para usar la nueva clave `identity_validation.reset_password.jwt_secret`?" +### La vostra pregunta +"Hauríem d'actualitzar el fitxer de configuració per utilitzar la nova clau `identity_validation.reset_password.jwt_secret`?" -### Respuesta: SÍ, migre a la nueva ruta de clave +### Resposta: SÍ, migreu a la nova ruta de clau -**Antiguo (Obsoleto)**: +**Antic (Obsolet)**: ```yaml -jwt_secret: su_secreto_aqui +jwt_secret: el_vostre_secret_aqui ``` -**Nuevo (v4.38.0+)**: +**Nou (v4.38.0+)**: ```yaml identity_validation: reset_password: jwt: expiration: 15m - # Secreto inyectado vía variable de entorno + # Secret injectat via variable d'entorn ``` -**Variable de entorno**: +**Variable d'entorn**: ```yaml environment: - AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE=/run/secrets/authelia_jwt_secret ``` -**Configuración de Docker Compose**: +**Configuració de Docker Compose**: ```yaml secrets: - authelia_jwt_secret @@ -159,41 +159,41 @@ services: - AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE=/run/secrets/authelia_jwt_secret ``` -**¿Por qué migrar?**: -- ✅ Soporta el nuevo flujo de restablecimiento de contraseña de Authelia -- ✅ Sigue el versionado semántico (JWT separado para diferentes propósitos) -- ✅ Permite la futura separación de JWTs para autenticación frente a restablecimiento de contraseña -- ✅ Elimina las advertencias de obsolescencia +**Per què migrar?**: +- ✅ Suporta el nou flux de restabliment de contrasenya d'Authelia +- ✅ Segueix el versionat semàntic (JWT separat per a diferents propòsits) +- ✅ Permet la futura separació de JWTs per a autenticació enfront de restabliment de contrasenya +- ✅ Elimina els avisos d'obsolescència -**Compatibilidad con versiones anteriores**: -- Authelia 4.38.0+ sigue aceptando el antiguo `jwt_secret` pero muestra una advertencia -- Se requiere la nueva configuración para tener logs limpios -- La funcionalidad de restablecimiento de contraseña solo funciona con la nueva clave +**Compatibilitat amb versions anteriors**: +- Authelia 4.38.0+ segueix acceptant l'antic `jwt_secret` però mostra un avís +- Es requereix la nova configuració per tenir logs nets +- La funcionalitat de restabliment de contrasenya només funciona amb la nova clau --- -## Q4: Configuración de la URL de redirección por defecto +## Q4: Configuració de la URL de redirecció per defecte -### Su pregunta -"¿Cómo debemos configurar correctamente `default_redirection_url` a nivel de cada cookie en lugar de hacerlo globalmente?" +### La vostra pregunta +"Com hem de configurar correctament `default_redirection_url` a nivell de cada cookie en lloc de fer-ho globalment?" -### Respuesta: Muévalo dentro de la configuración de cada cookie +### Resposta: Moveu-ho dins de la configuració de cada cookie -**Antiguo (Causa Error)**: +**Antic (Causa Error)**: ```yaml session: expiration: 1h - default_redirection_url: https://forgejo.localhost # ❌ INCORRECTO + default_redirection_url: https://forgejo.localhost # ❌ INCORRECTE cookies: - name: authelia_session domain: localhost ``` -**Nuevo (Correcto)**: +**Nou (Correcte)**: ```yaml session: expiration: 1h - # No lo ponga aquí ❌ + # No ho poseu aquí ❌ cookies: - name: authelia_session @@ -203,69 +203,69 @@ session: same_site: Lax secure: false -# Opcional: Fallback global al nivel de la raíz +# Opcional: Fallback global al nivell de l'arrel default_redirection_url: 'https://forgejo.localhost' ``` -**Múltiples Cookies (Avanzado)**: +**Múltiples Cookies (Avançat)**: ```yaml session: cookies: - # Cookie de producción + # Cookie de producció - name: authelia_session - domain: ejemplo.com - default_redirection_url: https://app.ejemplo.com + domain: exemple.com + default_redirection_url: https://app.exemple.com secure: true - # Cookie de desarrollo + # Cookie de desenvolupament - name: authelia_session_dev domain: localhost default_redirection_url: https://forgejo.localhost secure: false # Fallback global -default_redirection_url: 'https://ejemplo.com' +default_redirection_url: 'https://exemple.com' ``` -**Cómo funciona**: -1. El usuario accede a un servicio protegido (ej. n8n.localhost) -2. Es redirigido al login de Authelia (auth.localhost) -3. Tras el login, Authelia comprueba el `default_redirection_url` de cada cookie -4. Redirige a la URL configurada (ej. forgejo.localhost) -5. Si no hay configuración por cookie, usa el `default_redirection_url` global +**Com funciona**: +1. L'usuari accedeix a un servei protegit (ex. n8n.localhost) +2. És redirigit al login d'Authelia (auth.localhost) +3. Després del login, Authelia comprova el `default_redirection_url` de cada cookie +4. Redirigeix a la URL configurada (ex. forgejo.localhost) +5. Si no hi ha configuració per cookie, utilitza el `default_redirection_url` global -**Campos de configuración requeridos**: +**Camps de configuració requerits**: ```yaml cookies: - - name: authelia_session # Nombre de la cookie - domain: localhost # Dominio de la cookie - authelia_url: https://auth.localhost # Endpoint de Authelia - default_redirection_url: https://forgejo.localhost # Destino de fallback - same_site: Lax # Protección CSRF - secure: false # true en producción + - name: authelia_session # Nom de la cookie + domain: localhost # Domini de la cookie + authelia_url: https://auth.localhost # Endpoint d'Authelia + default_redirection_url: https://forgejo.localhost # Destí de fallback + same_site: Lax # Protecció CSRF + secure: false # true en producció ``` --- -## Q5: HTTP vs HTTPS - Desarrollo Local vs Producción +## Q5: HTTP vs HTTPS - Desenvolupament Local vs Producció -### Su pregunta -"¿Podemos ejecutar Authelia con HTTP en desarrollo local (con nginx-proxy gestionando SSL mediante certificados autofirmados o sin SSL) y luego cambiar a HTTPS en producción?" +### La vostra pregunta +"Podem executar Authelia amb HTTP en desenvolupament local (amb nginx-proxy gestionant SSL mitjançant certificats autosignats o sense SSL) i després canviar a HTTPS en producció?" -### Respuesta: SÍ, Authelia es agnóstico al protocolo +### Resposta: SÍ, Authelia és agnòstic al protocol -**Desarrollo Local (HTTP, sin SSL)**: +**Desenvolupament Local (HTTP, sense SSL)**: ```yaml -# En authelia/configuration.yml: +# A authelia/configuration.yml: server: address: 'tcp://0.0.0.0:9091' tls: - enabled: false # ✅ Solo HTTP + enabled: false # ✅ Només HTTP session: cookies: - name: authelia_session - secure: false # ✅ Permitir cookies HTTP + secure: false # ✅ Permetre cookies HTTP same_site: Lax ``` @@ -277,10 +277,10 @@ authelia: environment: - VIRTUAL_HOST=auth.localhost - VIRTUAL_PORT=9091 - # nginx-proxy sirve vía HTTP + # nginx-proxy serveix via HTTP ``` -**Cómo acceder**: +**Com accedir**: ``` Navegador: http://auth.localhost:9091 Navegador: http://n8n.localhost @@ -288,14 +288,14 @@ Navegador: http://n8n.localhost --- -**Producción (HTTPS con Let's Encrypt)**: +**Producció (HTTPS amb Let's Encrypt)**: ```yaml -# En authelia/configuration.yml (NO SE NECESITAN CAMBIOS): +# A authelia/configuration.yml (NO CALEN CANVIS): server: address: 'tcp://0.0.0.0:9091' tls: - enabled: false # ✅ Sigue siendo false - # nginx-proxy gestiona la terminación TLS + enabled: false # ✅ Segueix sent false + # nginx-proxy gestiona la terminació TLS session: cookies: @@ -312,64 +312,64 @@ authelia: labels: - com.github.jrcs.letsencrypt_nginx_proxy_companion.enable=true environment: - - VIRTUAL_HOST=auth.ejemplo.com + - VIRTUAL_HOST=auth.exemple.com - VIRTUAL_PORT=9091 - # nginx-proxy + acme-companion gestionan HTTPS + Let's Encrypt + # nginx-proxy + acme-companion gestionen HTTPS + Let's Encrypt ``` -**Cómo acceder**: +**Com accedir**: ``` -Navegador: https://auth.ejemplo.com -Navegador: https://app.ejemplo.com +Navegador: https://auth.exemple.com +Navegador: https://app.exemple.com ``` --- -**Puntos Clave**: +**Punts Clau**: -1. **Authelia en sí**: Siempre se ejecuta en HTTP (puerto 9091) internamente -2. **Terminación TLS**: Deje que nginx-proxy gestione la terminación HTTPS -3. **Configuración de Authelia**: `tls.enabled: false` para todos los escenarios -4. **Seguridad de la sesión**: - - Dev local: `secure: false` (permitir HTTP) - - Producción: `secure: true` (requerir HTTPS) -5. **Ruta de migración**: - - Empezar con dev local (HTTP, sin SSL) - - Mover a producción (HTTPS vía nginx-proxy + Let's Encrypt) - - No se necesitan cambios en la configuración de Authelia - - Solo cambiar las etiquetas de docker-compose y las variables de entorno +1. **Authelia en si**: Sempre s'executa en HTTP (port 9091) internament +2. **Terminació TLS**: Deixeu que nginx-proxy gestioni la terminació HTTPS +3. **Configuració d'Authelia**: `tls.enabled: false` per a tots els escenaris +4. **Seguretat de la sessió**: + - Dev local: `secure: false` (permetre HTTP) + - Producció: `secure: true` (requerir HTTPS) +5. **Ruta de migració**: + - Començar amb dev local (HTTP, sense SSL) + - Moure a producció (HTTPS via nginx-proxy + Let's Encrypt) + - No calen canvis a la configuració d'Authelia + - Només canviar les etiquetes de docker-compose i les variables d'entorn --- -## Estado de la Implementación +## Estat de la Implementació -Todas las correcciones han sido implementadas: +Totes les correccions han estat implementades: -| Problema | Estado | Archivo | +| Problema | Estat | Fitxer | |-------|--------|------| -| Obsolescencia de secreto JWT | ✅ Corregido | [authelia/configuration.yml](authelia/configuration.yml) | -| Conflicto SMTP | ✅ Corregido | [authelia/configuration.yml](authelia/configuration.yml) + [docker-compose.yml](docker-compose.yml) | -| Cookies de sesión | ✅ Corregido | [authelia/configuration.yml](authelia/configuration.yml) | -| Dominio de la cookie | ✅ Corregido | [authelia/configuration.yml](authelia/configuration.yml) | -| HTTP vs HTTPS | ✅ Configurado | [authelia/configuration.yml](authelia/configuration.yml) | -| Documentación | ✅ Completa | [docs/authelia-setup.md](docs/authelia-setup.md) + [AUTHELIA_FIXES_SUMMARY.md](AUTHELIA_FIXES_SUMMARY.md) | +| Obsolescència de secret JWT | ✅ Corregit | [authelia/configuration.yml](authelia/configuration.yml) | +| Conflicte SMTP | ✅ Corregit | [authelia/configuration.yml](authelia/configuration.yml) + [docker-compose.yml](docker-compose.yml) | +| Cookies de sessió | ✅ Corregit | [authelia/configuration.yml](authelia/configuration.yml) | +| Domini de la cookie | ✅ Corregit | [authelia/configuration.yml](authelia/configuration.yml) | +| HTTP vs HTTPS | ✅ Configurat | [authelia/configuration.yml](authelia/configuration.yml) | +| Documentació | ✅ Completa | [docs/authelia-setup.md](docs/authelia-setup.md) + [AUTHELIA_FIXES_SUMMARY.md](AUTHELIA_FIXES_SUMMARY.md) | --- -## Inicio Rápido +## Inici Ràpid -1. **Actualizar archivos de configuración** ✅ (Ya hecho) -2. **Crear `.env` con SMTP**: +1. **Actualitzar fitxers de configuració** ✅ (Ja fet) +2. **Crear `.env` amb SMTP**: ```bash SMTP_HOST=smtp.tinet.cat SMTP_PORT=587 - SMTP_USERNAME=su_correo@example.com - SMTP_PASSWORD=su_contraseña + SMTP_USERNAME=el_vostre_correu@example.com + SMTP_PASSWORD=la_vostra_contrasenya SMTP_SENDER=Authelia AUTHELIA_DOMAIN=auth.localhost ``` -3. **Generar secretos** (si no se ha hecho): +3. **Generar secrets** (si no s'ha fet): ```bash mkdir -p ./secrets openssl rand -base64 32 > ./secrets/authelia_jwt_secret.txt @@ -377,28 +377,28 @@ Todas las correcciones han sido implementadas: chmod 600 ./secrets/*.txt ``` -4. **Iniciar servicios**: +4. **Iniciar serveis**: ```bash docker compose up -d redis authelia docker compose logs -f authelia ``` -5. **Prueba**: +5. **Prova**: ```bash curl http://localhost:9091/api/health - # Esperado: 200 OK + # Esperat: 200 OK ``` -6. **Acceder a la UI**: +6. **Accedir a la UI**: ``` Navegador: http://auth.localhost:9091 ``` --- -## ¿Aún necesita ayuda? +## Encara necessiteu ajuda? -- **Guía de configuración completa**: Ver [docs/authelia-setup.md](docs/authelia-setup.md) -- **Explicaciones detalladas de los problemas**: Ver [AUTHELIA_FIXES_SUMMARY.md](AUTHELIA_FIXES_SUMMARY.md) -- **Solución de problemas**: Consulte la sección "Troubleshooting" en [docs/authelia-setup.md](docs/authelia-setup.md) -- **Docs oficiales**: https://www.authelia.com/configuration/ +- **Guia de configuració completa**: Vegeu [docs/authelia-setup.md](docs/authelia-setup.md) +- **Explicacions detallades dels problemes**: Vegeu [AUTHELIA_FIXES_SUMMARY.md](AUTHELIA_FIXES_SUMMARY.md) +- **Solució de problemes**: Consulteu la secció "Troubleshooting" a [docs/authelia-setup.md](docs/authelia-setup.md) +- **Docs oficials**: https://www.authelia.com/configuration/ diff --git a/AUTHELIA_FAQ.en.md b/AUTHELIA_FAQ.en.md index be71f98..f5584b4 100644 --- a/AUTHELIA_FAQ.en.md +++ b/AUTHELIA_FAQ.en.md @@ -1,18 +1,18 @@ -# Configuración de Authelia - FAQ y Respuestas a sus Preguntas -[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/Axlfc/connect-core/blob/master/AUTHELIA_FAQ.en.md) -[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/Axlfc/connect-core/blob/master/AUTHELIA_FAQ.md) -[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/Axlfc/connect-core/blob/master/AUTHELIA_FAQ.ca.md) -[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/Axlfc/connect-core/blob/master/AUTHELIA_FAQ.zh-cn.md) +# Authelia Configuration - FAQ and Answers to Your Questions +[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/AUTHELIA_FAQ.en.md) +[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/AUTHELIA_FAQ.md) +[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/AUTHELIA_FAQ.ca.md) +[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/AUTHELIA_FAQ.zh-cn.md) -## Q1: Configuración SMTP - ¿Cuál es la forma correcta de configurar SMTP? +## Q1: SMTP Configuration - What is the correct way to configure SMTP? -### Su pregunta -"¿Cuál es la forma correcta de configurar SMTP en el nuevo formato? ¿Deberíamos usar `notifier.smtp.address` en lugar de `host` y `port` por separado?" +### Question +"What is the correct way to configure SMTP in the new format? Should we use `notifier.smtp.address` instead of `host` and `port` separately?" -### Respuesta: SÍ, use solo el formato `address` +### Answer: YES, use only the `address` format -**Correcto (Moderno v4.38.0+)**: +**Correct (Modern v4.38.0+)**: ```yaml notifier: smtp: @@ -24,131 +24,131 @@ notifier: skip_verify: false ``` -**Formato**: `smtp[s]://[usuario@]host[:puerto]` +**Format**: `smtp[s]://[user@]host[:port]` -**Ejemplos**: +**Examples**: ``` -smtp://smtp.example.com:587 # STARTTLS en el puerto 587 -smtps://smtp.example.com:465 # TLS implícito en el puerto 465 -smtp://user@smtp.example.com:587 # Con usuario en la URL +smtp://smtp.example.com:587 # STARTTLS on port 587 +smtps://smtp.example.com:465 # Implicit TLS on port 465 +smtp://user@smtp.example.com:587 # With user in the URL ``` -**Credenciales mediante variables de entorno**: +**Credentials via Environment Variables**: ```yaml environment: - AUTHELIA_NOTIFIER_SMTP_ADDRESS=smtp://smtp.tinet.cat:587 - - AUTHELIA_NOTIFIER_SMTP_USERNAME=su_correo@example.com - - AUTHELIA_NOTIFIER_SMTP_PASSWORD=su_contraseña + - AUTHELIA_NOTIFIER_SMTP_USERNAME=your_email@example.com + - AUTHELIA_NOTIFIER_SMTP_PASSWORD=your_password - AUTHELIA_NOTIFIER_SMTP_SENDER=Authelia ``` -**Desde `.env`**: +**From `.env`**: ```bash SMTP_HOST=smtp.tinet.cat SMTP_PORT=587 -SMTP_USERNAME=su_correo@example.com -SMTP_PASSWORD=su_contraseña +SMTP_USERNAME=your_email@example.com +SMTP_PASSWORD=your_password SMTP_SENDER=Authelia ``` -**NO mezcle formatos** (causará conflicto): +**DO NOT mix formats** (will cause conflict): ```yaml -# ❌ INCORRECTO - Esto causa el error de conflicto: +# ❌ INCORRECT - This causes the conflict error: notifier: smtp: - host: smtp.example.com # ❌ Formato antiguo - port: 587 # ❌ Formato antiguo - address: 'smtp://...:587' # ❌ Formato nuevo (¡conflicto!) + host: smtp.example.com # ❌ Old format + port: 587 # ❌ Old format + address: 'smtp://...:587' # ❌ New format (conflict!) ``` --- -## Q2: Cookies de sesión para Localhost +## Q2: Session Cookies for Localhost -### Su pregunta -"¿Cómo debemos configurar las cookies de sesión para el desarrollo local usando dominios `.localhost`? El error indica que los dominios deben tener un punto o ser una dirección IP." +### Question +"How should we configure session cookies for local development using `.localhost` domains? The error indicates that domains must have a dot or be an IP address." -### Respuesta: Use `localhost` en la configuración, nginx-proxy gestiona la compatibilidad del navegador +### Answer: Use `localhost` in the configuration, nginx-proxy manages browser compatibility -**La Configuración**: +**The Configuration**: ```yaml session: cookies: - name: authelia_session - domain: localhost # ✅ Correcto para la red Docker + domain: localhost # ✅ Correct for the Docker network authelia_url: https://auth.localhost default_redirection_url: https://forgejo.localhost same_site: Lax - secure: false # Cambiar a true en producción + secure: false # Change to true in production ``` -**Cómo funciona**: -1. **Red Docker**: Los servicios se comunican usando `localhost` (funciona bien) -2. **Acceso desde el navegador**: El usuario va a `http://auth.localhost:9091` -3. **nginx-proxy**: Intercepta la petición a `auth.localhost` y la dirige a Authelia -4. **Dominio de la cookie**: nginx-proxy gestiona la reescritura de la cookie para la compatibilidad del navegador -5. **Resultado**: El navegador nunca ve el dominio `localhost` inválido directamente +**How it works**: +1. **Docker Network**: Services communicate using `localhost` (works fine) +2. **Browser Access**: User goes to `http://auth.localhost:9091` +3. **nginx-proxy**: Intercepts the request to `auth.localhost` and directs it to Authelia +4. **Cookie Domain**: nginx-proxy manages the cookie rewriting for browser compatibility +5. **Result**: The browser never sees the invalid `localhost` domain directly -**Por qué funciona esto**: -- El DNS interno de Docker resuelve `localhost` dentro de los contenedores -- El navegador nunca establece cookies directamente en el dominio `localhost` -- nginx-proxy intermedia y gestiona la traducción del dominio de la cookie -- Tanto el acceso interno de Docker como el del navegador funcionan perfectamente +**Why this works**: +- Docker's internal DNS resolves `localhost` within containers +- The browser never sets cookies directly on the `localhost` domain +- nginx-proxy intermediates and manages the cookie domain translation +- Both internal Docker access and browser access work perfectly -**Qué NO hacer**: +**What NOT to do**: ```yaml -# ❌ INCORRECTO - Esto también fallará: -domain: .localhost # El navegador sigue rechazando dominios de una sola etiqueta +# ❌ INCORRECT - This will also fail: +domain: .localhost # The browser still rejects single-label domains -# ❌ INCORRECTO - Demasiado restrictivo para desarrollo: -domain: auth.localhost # Solo funciona para auth.localhost, no para otros servicios +# ❌ INCORRECT - Too restrictive for development: +domain: auth.localhost # Only works for auth.localhost, not for other services -# ✅ CORRECTO: -domain: localhost # Funciona para la red Docker + nginx-proxy gestiona el navegador +# ✅ CORRECT: +domain: localhost # Works for Docker network + nginx-proxy manages the browser ``` -**Variables de entorno**: +**Environment Variables**: ```yaml environment: - VIRTUAL_HOST=${AUTHELIA_DOMAIN:-auth.localhost} - VIRTUAL_PORT=9091 ``` -**En `.env`**: +**In `.env`**: ```bash AUTHELIA_DOMAIN=auth.localhost ``` --- -## Q3: Migración del Secreto JWT +## Q3: JWT Secret Migration -### Su pregunta -"¿Deberíamos actualizar el archivo de configuración para usar la nueva clave `identity_validation.reset_password.jwt_secret`?" +### Question +"Should we update the configuration file to use the new `identity_validation.reset_password.jwt_secret` key?" -### Respuesta: SÍ, migre a la nueva ruta de clave +### Answer: YES, migrate to the new key path -**Antiguo (Obsoleto)**: +**Old (Obsolete)**: ```yaml -jwt_secret: su_secreto_aqui +jwt_secret: your_secret_here ``` -**Nuevo (v4.38.0+)**: +**New (v4.38.0+)**: ```yaml identity_validation: reset_password: jwt: expiration: 15m - # Secreto inyectado vía variable de entorno + # Secret injected via environment variable ``` -**Variable de entorno**: +**Environment Variable**: ```yaml environment: - AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE=/run/secrets/authelia_jwt_secret ``` -**Configuración de Docker Compose**: +**Docker Compose Configuration**: ```yaml secrets: - authelia_jwt_secret @@ -159,113 +159,113 @@ services: - AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE=/run/secrets/authelia_jwt_secret ``` -**¿Por qué migrar?**: -- ✅ Soporta el nuevo flujo de restablecimiento de contraseña de Authelia -- ✅ Sigue el versionado semántico (JWT separado para diferentes propósitos) -- ✅ Permite la futura separación de JWTs para autenticación frente a restablecimiento de contraseña -- ✅ Elimina las advertencias de obsolescencia +**Why migrate?**: +- ✅ Supports Authelia's new password reset flow +- ✅ Follows semantic versioning (separate JWT for different purposes) +- ✅ Allows future separation of JWTs for authentication vs. password reset +- ✅ Eliminates deprecation warnings -**Compatibilidad con versiones anteriores**: -- Authelia 4.38.0+ sigue aceptando el antiguo `jwt_secret` pero muestra una advertencia -- Se requiere la nueva configuración para tener logs limpios -- La funcionalidad de restablecimiento de contraseña solo funciona con la nueva clave +**Backward Compatibility**: +- Authelia 4.38.0+ still accepts the old `jwt_secret` but shows a warning +- New configuration is required for clean logs +- Password reset functionality only works with the new key --- -## Q4: Configuración de la URL de redirección por defecto +## Q4: Default Redirection URL Configuration -### Su pregunta -"¿Cómo debemos configurar correctamente `default_redirection_url` a nivel de cada cookie en lugar de hacerlo globalmente?" +### Question +"How should we correctly configure `default_redirection_url` at the level of each cookie instead of globally?" -### Respuesta: Muévalo dentro de la configuración de cada cookie +### Answer: Move it inside each cookie's configuration -**Antiguo (Causa Error)**: +**Old (Causes Error)**: ```yaml session: expiration: 1h - default_redirection_url: https://forgejo.localhost # ❌ INCORRECTO + default_redirection_url: https://forgejo.localhost # ❌ INCORRECT cookies: - name: authelia_session domain: localhost ``` -**Nuevo (Correcto)**: +**New (Correct)**: ```yaml session: expiration: 1h - # No lo ponga aquí ❌ + # Do not put it here ❌ cookies: - name: authelia_session domain: localhost - default_redirection_url: https://forgejo.localhost # ✅ AQUÍ + default_redirection_url: https://forgejo.localhost # ✅ HERE authelia_url: https://auth.localhost same_site: Lax secure: false -# Opcional: Fallback global al nivel de la raíz +# Optional: Global fallback at the root level default_redirection_url: 'https://forgejo.localhost' ``` -**Múltiples Cookies (Avanzado)**: +**Multiple Cookies (Advanced)**: ```yaml session: cookies: - # Cookie de producción + # Production cookie - name: authelia_session - domain: ejemplo.com - default_redirection_url: https://app.ejemplo.com + domain: example.com + default_redirection_url: https://app.example.com secure: true - # Cookie de desarrollo + # Development cookie - name: authelia_session_dev domain: localhost default_redirection_url: https://forgejo.localhost secure: false -# Fallback global -default_redirection_url: 'https://ejemplo.com' +# Global fallback +default_redirection_url: 'https://example.com' ``` -**Cómo funciona**: -1. El usuario accede a un servicio protegido (ej. n8n.localhost) -2. Es redirigido al login de Authelia (auth.localhost) -3. Tras el login, Authelia comprueba el `default_redirection_url` de cada cookie -4. Redirige a la URL configurada (ej. forgejo.localhost) -5. Si no hay configuración por cookie, usa el `default_redirection_url` global +**How it works**: +1. User accesses a protected service (e.g., n8n.localhost) +2. Redirected to Authelia login (auth.localhost) +3. After login, Authelia checks the `default_redirection_url` for each cookie +4. Redirects to the configured URL (e.g., forgejo.localhost) +5. If no per-cookie configuration exists, it uses the global `default_redirection_url` -**Campos de configuración requeridos**: +**Required Configuration Fields**: ```yaml cookies: - - name: authelia_session # Nombre de la cookie - domain: localhost # Dominio de la cookie - authelia_url: https://auth.localhost # Endpoint de Authelia - default_redirection_url: https://forgejo.localhost # Destino de fallback - same_site: Lax # Protección CSRF - secure: false # true en producción + - name: authelia_session # Cookie name + domain: localhost # Cookie domain + authelia_url: https://auth.localhost # Authelia endpoint + default_redirection_url: https://forgejo.localhost # Fallback destination + same_site: Lax # CSRF protection + secure: false # true in production ``` --- -## Q5: HTTP vs HTTPS - Desarrollo Local vs Producción +## Q5: HTTP vs HTTPS - Local Development vs Production -### Su pregunta -"¿Podemos ejecutar Authelia con HTTP en desarrollo local (con nginx-proxy gestionando SSL mediante certificados autofirmados o sin SSL) y luego cambiar a HTTPS en producción?" +### Question +"Can we run Authelia with HTTP in local development (with nginx-proxy managing SSL via self-signed certificates or without SSL) and then switch to HTTPS in production?" -### Respuesta: SÍ, Authelia es agnóstico al protocolo +### Answer: YES, Authelia is protocol-agnostic -**Desarrollo Local (HTTP, sin SSL)**: +**Local Development (HTTP, without SSL)**: ```yaml -# En authelia/configuration.yml: +# In authelia/configuration.yml: server: address: 'tcp://0.0.0.0:9091' tls: - enabled: false # ✅ Solo HTTP + enabled: false # ✅ HTTP only session: cookies: - name: authelia_session - secure: false # ✅ Permitir cookies HTTP + secure: false # ✅ Allow HTTP cookies same_site: Lax ``` @@ -277,30 +277,30 @@ authelia: environment: - VIRTUAL_HOST=auth.localhost - VIRTUAL_PORT=9091 - # nginx-proxy sirve vía HTTP + # nginx-proxy serves via HTTP ``` -**Cómo acceder**: +**How to access**: ``` -Navegador: http://auth.localhost:9091 -Navegador: http://n8n.localhost +Browser: http://auth.localhost:9091 +Browser: http://n8n.localhost ``` --- -**Producción (HTTPS con Let's Encrypt)**: +**Production (HTTPS with Let's Encrypt)**: ```yaml -# En authelia/configuration.yml (NO SE NECESITAN CAMBIOS): +# In authelia/configuration.yml (NO CHANGES NEEDED): server: address: 'tcp://0.0.0.0:9091' tls: - enabled: false # ✅ Sigue siendo false - # nginx-proxy gestiona la terminación TLS + enabled: false # ✅ Still false + # nginx-proxy manages TLS termination session: cookies: - name: authelia_session - secure: true # ✅ Requerir HTTPS + secure: true # ✅ Require HTTPS same_site: Strict ``` @@ -312,64 +312,64 @@ authelia: labels: - com.github.jrcs.letsencrypt_nginx_proxy_companion.enable=true environment: - - VIRTUAL_HOST=auth.ejemplo.com + - VIRTUAL_HOST=auth.example.com - VIRTUAL_PORT=9091 - # nginx-proxy + acme-companion gestionan HTTPS + Let's Encrypt + # nginx-proxy + acme-companion manage HTTPS + Let's Encrypt ``` -**Cómo acceder**: +**How to access**: ``` -Navegador: https://auth.ejemplo.com -Navegador: https://app.ejemplo.com +Browser: https://auth.example.com +Browser: https://app.example.com ``` --- -**Puntos Clave**: +**Key Points**: -1. **Authelia en sí**: Siempre se ejecuta en HTTP (puerto 9091) internamente -2. **Terminación TLS**: Deje que nginx-proxy gestione la terminación HTTPS -3. **Configuración de Authelia**: `tls.enabled: false` para todos los escenarios -4. **Seguridad de la sesión**: - - Dev local: `secure: false` (permitir HTTP) - - Producción: `secure: true` (requerir HTTPS) -5. **Ruta de migración**: - - Empezar con dev local (HTTP, sin SSL) - - Mover a producción (HTTPS vía nginx-proxy + Let's Encrypt) - - No se necesitan cambios en la configuración de Authelia - - Solo cambiar las etiquetas de docker-compose y las variables de entorno +1. **Authelia itself**: Always runs on HTTP (port 9091) internally +2. **TLS Termination**: Let nginx-proxy handle HTTPS termination +3. **Authelia Configuration**: `tls.enabled: false` for all scenarios +4. **Session Security**: + - Local Dev: `secure: false` (allow HTTP) + - Production: `secure: true` (require HTTPS) +5. **Migration Path**: + - Start with local dev (HTTP, no SSL) + - Move to production (HTTPS via nginx-proxy + Let's Encrypt) + - No changes needed in Authelia configuration + - Only change docker-compose labels and environment variables --- -## Estado de la Implementación +## Implementation Status -Todas las correcciones han sido implementadas: +All fixes have been implemented: -| Problem | Estado | Archivo | +| Problem | Status | File | |-------|--------|------| -| Obsolescencia de secreto JWT | ✅ Corregido | [authelia/configuration.yml](authelia/configuration.yml) | -| Conflicto SMTP | ✅ Corregido | [authelia/configuration.yml](authelia/configuration.yml) + [docker-compose.yml](docker-compose.yml) | -| Cookies de sesión | ✅ Corregido | [authelia/configuration.yml](authelia/configuration.yml) | -| Dominio de la cookie | ✅ Corregido | [authelia/configuration.yml](authelia/configuration.yml) | -| HTTP vs HTTPS | ✅ Configurado | [authelia/configuration.yml](authelia/configuration.yml) | -| Documentación | ✅ Completa | [docs/authelia-setup.md](docs/authelia-setup.md) + [AUTHELIA_FIXES_SUMMARY.md](AUTHELIA_FIXES_SUMMARY.md) | +| JWT Secret Deprecation | ✅ Fixed | [authelia/configuration.yml](authelia/configuration.yml) | +| SMTP Conflict | ✅ Fixed | [authelia/configuration.yml](authelia/configuration.yml) + [docker-compose.yml](docker-compose.yml) | +| Session Cookies | ✅ Fixed | [authelia/configuration.yml](authelia/configuration.yml) | +| Cookie Domain | ✅ Fixed | [authelia/configuration.yml](authelia/configuration.yml) | +| HTTP vs HTTPS | ✅ Configured | [authelia/configuration.yml](authelia/configuration.yml) | +| Documentation | ✅ Complete | [docs/authelia-setup.md](docs/authelia-setup.md) + [AUTHELIA_FIXES_SUMMARY.md](AUTHELIA_FIXES_SUMMARY.md) | --- -## Inicio Rápido +## Quick Start -1. **Actualizar archivos de configuración** ✅ (Ya hecho) -2. **Crear `.env` con SMTP**: +1. **Update configuration files** ✅ (Already done) +2. **Create `.env` with SMTP**: ```bash SMTP_HOST=smtp.tinet.cat SMTP_PORT=587 - SMTP_USERNAME=su_correo@example.com - SMTP_PASSWORD=su_contraseña + SMTP_USERNAME=your_email@example.com + SMTP_PASSWORD=your_password SMTP_SENDER=Authelia AUTHELIA_DOMAIN=auth.localhost ``` -3. **Generar secretos** (si no se ha hecho): +3. **Generate secrets** (if not already done): ```bash mkdir -p ./secrets openssl rand -base64 32 > ./secrets/authelia_jwt_secret.txt @@ -377,28 +377,28 @@ Todas las correcciones han sido implementadas: chmod 600 ./secrets/*.txt ``` -4. **Iniciar servicios**: +4. **Start services**: ```bash docker compose up -d redis authelia docker compose logs -f authelia ``` -5. **Prueba**: +5. **Test**: ```bash curl http://localhost:9091/api/health - # Esperado: 200 OK + # Expected: 200 OK ``` -6. **Acceder a la UI**: +6. **Access UI**: ``` - Navegador: http://auth.localhost:9091 + Browser: http://auth.localhost:9091 ``` --- -## ¿Aún necesita ayuda? +## Still Need Help? -- **Guía de configuración completa**: Ver [docs/authelia-setup.md](docs/authelia-setup.md) -- **Explicaciones detalladas de los problemas**: Ver [AUTHELIA_FIXES_SUMMARY.md](AUTHELIA_FIXES_SUMMARY.md) -- **Solución de problemas**: Consulte la sección "Troubleshooting" en [docs/authelia-setup.md](docs/authelia-setup.md) -- **Docs oficiales**: https://www.authelia.com/configuration/ +- **Full Setup Guide**: See [docs/authelia-setup.md](docs/authelia-setup.md) +- **Detailed Problem Explanations**: See [AUTHELIA_FIXES_SUMMARY.md](AUTHELIA_FIXES_SUMMARY.md) +- **Troubleshooting**: Consult the "Troubleshooting" section in [docs/authelia-setup.md](docs/authelia-setup.md) +- **Official Docs**: https://www.authelia.com/configuration/ diff --git a/AUTHELIA_FAQ.zh-cn.md b/AUTHELIA_FAQ.zh-cn.md index 0357523..446a7b9 100644 --- a/AUTHELIA_FAQ.zh-cn.md +++ b/AUTHELIA_FAQ.zh-cn.md @@ -1,18 +1,18 @@ -# Configuración de Authelia - FAQ y Respuestas a sus Preguntas -[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/Axlfc/connect-core/blob/master/AUTHELIA_FAQ.zh-cn.md) -[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/Axlfc/connect-core/blob/master/AUTHELIA_FAQ.en.md) -[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/Axlfc/connect-core/blob/master/AUTHELIA_FAQ.md) -[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/Axlfc/connect-core/blob/master/AUTHELIA_FAQ.ca.md) +# Authelia 配置 - 常见问题解答与您的疑问 +[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/AUTHELIA_FAQ.zh-cn.md) +[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/AUTHELIA_FAQ.en.md) +[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/AUTHELIA_FAQ.md) +[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/AUTHELIA_FAQ.ca.md) -## Q1: Configuración SMTP - ¿Cuál es la forma correcta de configurar SMTP? +## Q1: SMTP 配置 - 配置 SMTP 的正确方式是什么？ -### Su pregunta -"¿Cuál es la forma correcta de configurar SMTP en el nuevo formato? ¿Deberíamos usar `notifier.smtp.address` en lugar de `host` y `port` por separado?" +### 您的疑问 +"在新的格式中，配置 SMTP 的正确方式是什么？我们是否应该使用 `notifier.smtp.address` 而不是单独的 `host` 和 `port`？" -### Respuesta: SÍ, use solo el formato `address` +### 解答：是的，仅使用 `address` 格式 -**Correcto (Moderno v4.38.0+)**: +**正确方式 (现代版本 v4.38.0+)**: ```yaml notifier: smtp: @@ -24,131 +24,131 @@ notifier: skip_verify: false ``` -**Formato**: `smtp[s]://[usuario@]host[:puerto]` +**格式**: `smtp[s]://[user@]host[:port]` -**Ejemplos**: +**示例**: ``` -smtp://smtp.example.com:587 # STARTTLS en el puerto 587 -smtps://smtp.example.com:465 # TLS implícito en el puerto 465 -smtp://user@smtp.example.com:587 # Con usuario en la URL +smtp://smtp.example.com:587 # 端口 587 上的 STARTTLS +smtps://smtp.example.com:465 # 端口 465 上的隐式 TLS +smtp://user@smtp.example.com:587 # 在 URL 中包含用户 ``` -**Credenciales mediante variables de entorno**: +**通过环境变量配置凭据**: ```yaml environment: - AUTHELIA_NOTIFIER_SMTP_ADDRESS=smtp://smtp.tinet.cat:587 - - AUTHELIA_NOTIFIER_SMTP_USERNAME=su_correo@example.com - - AUTHELIA_NOTIFIER_SMTP_PASSWORD=su_contraseña + - AUTHELIA_NOTIFIER_SMTP_USERNAME=your_email@example.com + - AUTHELIA_NOTIFIER_SMTP_PASSWORD=your_password - AUTHELIA_NOTIFIER_SMTP_SENDER=Authelia ``` -**Desde `.env`**: +**从 `.env` 文件配置**: ```bash SMTP_HOST=smtp.tinet.cat SMTP_PORT=587 -SMTP_USERNAME=su_correo@example.com -SMTP_PASSWORD=su_contraseña +SMTP_USERNAME=your_email@example.com +SMTP_PASSWORD=your_password SMTP_SENDER=Authelia ``` -**NO mezcle formatos** (causará conflicto): +**不要混合使用格式** (会导致冲突): ```yaml -# ❌ INCORRECTO - Esto causa el error de conflicto: +# ❌ 错误 - 这会导致冲突错误： notifier: smtp: - host: smtp.example.com # ❌ Formato antiguo - port: 587 # ❌ Formato antiguo - address: 'smtp://...:587' # ❌ Formato nuevo (¡conflicto!) + host: smtp.example.com # ❌ 旧格式 + port: 587 # ❌ 旧格式 + address: 'smtp://...:587' # ❌ 新格式 (冲突!) ``` --- -## Q2: Cookies de sesión para Localhost +## Q2: Localhost 的会话 Cookie -### Su pregunta -"¿Cómo debemos configurar las cookies de sesión para el desarrollo local usando dominios `.localhost`? El error indica que los dominios deben tener un punto o ser una dirección IP." +### 您的疑问 +"对于使用 `.localhost` 域名的本地开发，我们应该如何配置会话 Cookie？错误提示域名必须包含点号或是一个 IP 地址。" -### Respuesta: Use `localhost` en la configuración, nginx-proxy gestiona la compatibilidad del navegador +### 解答：在配置中使用 `localhost`，nginx-proxy 会处理浏览器兼容性 -**La Configuración**: +**配置内容**: ```yaml session: cookies: - name: authelia_session - domain: localhost # ✅ Correcto para la red Docker + domain: localhost # ✅ 适用于 Docker 网络 authelia_url: https://auth.localhost default_redirection_url: https://forgejo.localhost same_site: Lax - secure: false # Cambiar a true en producción + secure: false # 在生产环境中更改为 true ``` -**Cómo funciona**: -1. **Red Docker**: Los servicios se comunican usando `localhost` (funciona bien) -2. **Acceso desde el navegador**: El usuario va a `http://auth.localhost:9091` -3. **nginx-proxy**: Intercepta la petición a `auth.localhost` y la dirige a Authelia -4. **Dominio de la cookie**: nginx-proxy gestiona la reescritura de la cookie para la compatibilidad del navegador -5. **Resultado**: El navegador nunca ve el dominio `localhost` inválido directamente +**工作原理**: +1. **Docker 网络**: 服务之间使用 `localhost` 通信 (运行良好) +2. **浏览器访问**: 用户访问 `http://auth.localhost:9091` +3. **nginx-proxy**: 拦截对 `auth.localhost` 的请求并将其转发给 Authelia +4. **Cookie 域名**: nginx-proxy 会处理 Cookie 重写以实现浏览器兼容性 +5. **结果**: 浏览器永远不会直接看到无效的 `localhost` 域名 -**Por qué funciona esto**: -- El DNS interno de Docker resuelve `localhost` dentro de los contenedores -- El navegador nunca establece cookies directamente en el dominio `localhost` -- nginx-proxy intermedia y gestiona la traducción del dominio de la cookie -- Tanto el acceso interno de Docker como el del navegador funcionan perfectamente +**为什么这样可行**: +- Docker 内部 DNS 会在容器内解析 `localhost` +- 浏览器永远不会直接在 `localhost` 域名上设置 Cookie +- nginx-proxy 作为中间层管理 Cookie 域名的转换 +- Docker 内部访问和浏览器访问都能完美运行 -**Qué NO hacer**: +**不应该做的**: ```yaml -# ❌ INCORRECTO - Esto también fallará: -domain: .localhost # El navegador sigue rechazando dominios de una sola etiqueta +# ❌ 错误 - 这也会失败： +domain: .localhost # 浏览器仍然拒绝单标签域名 -# ❌ INCORRECTO - Demasiado restrictivo para desarrollo: -domain: auth.localhost # Solo funciona para auth.localhost, no para otros servicios +# ❌ 错误 - 对于开发来说限制太严： +domain: auth.localhost # 仅适用于 auth.localhost，不适用于其他服务 -# ✅ CORRECTO: -domain: localhost # Funciona para la red Docker + nginx-proxy gestiona el navegador +# ✅ 正确: +domain: localhost # 适用于 Docker 网络 + nginx-proxy 管理浏览器 ``` -**Variables de entorno**: +**环境变量**: ```yaml environment: - VIRTUAL_HOST=${AUTHELIA_DOMAIN:-auth.localhost} - VIRTUAL_PORT=9091 ``` -**En `.env`**: +**在 `.env` 中**: ```bash AUTHELIA_DOMAIN=auth.localhost ``` --- -## Q3: Migración del Secreto JWT +## Q3: JWT 密钥迁移 -### Su pregunta -"¿Deberíamos actualizar el archivo de configuración para usar la nueva clave `identity_validation.reset_password.jwt_secret`?" +### 您的疑问 +"我们是否应该更新配置文件以使用新的 `identity_validation.reset_password.jwt_secret` 键？" -### Respuesta: SÍ, migre a la nueva ruta de clave +### 解答：是的，请迁移到新的键路径 -**Antiguo (Obsoleto)**: +**旧方式 (已废弃)**: ```yaml -jwt_secret: su_secreto_aqui +jwt_secret: your_secret_here ``` -**Nuevo (v4.38.0+)**: +**新方式 (v4.38.0+)**: ```yaml identity_validation: reset_password: jwt: expiration: 15m - # Secreto inyectado vía variable de entorno + # 密钥通过环境变量注入 ``` -**Variable de entorno**: +**环境变量**: ```yaml environment: - AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE=/run/secrets/authelia_jwt_secret ``` -**Configuración de Docker Compose**: +**Docker Compose 配置**: ```yaml secrets: - authelia_jwt_secret @@ -159,113 +159,113 @@ services: - AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE=/run/secrets/authelia_jwt_secret ``` -**¿Por qué migrar?**: -- ✅ Soporta el nuevo flujo de restablecimiento de contraseña de Authelia -- ✅ Sigue el versionado semántico (JWT separado para diferentes propósitos) -- ✅ Permite la futura separación de JWTs para autenticación frente a restablecimiento de contraseña -- ✅ Elimina las advertencias de obsolescencia +**为什么要迁移？**: +- ✅ 支持 Authelia 新的密码重置流程 +- ✅ 遵循语义化版本控制 (针对不同用途使用独立的 JWT) +- ✅ 允许未来将身份验证与密码重置的 JWT 分离 +- ✅ 消除废弃警告 -**Compatibilidad con versiones anteriores**: -- Authelia 4.38.0+ sigue aceptando el antiguo `jwt_secret` pero muestra una advertencia -- Se requiere la nueva configuración para tener logs limpios -- La funcionalidad de restablecimiento de contraseña solo funciona con la nueva clave +**向后兼容性**: +- Authelia 4.38.0+ 仍然接受旧的 `jwt_secret` 但会显示警告 +- 为了获得整洁的日志，需要使用新配置 +- 密码重置功能仅在使用新密钥时有效 --- -## Q4: Configuración de la URL de redirección por defecto +## Q4: 默认重定向 URL 配置 -### Su pregunta -"¿Cómo debemos configurar correctamente `default_redirection_url` a nivel de cada cookie en lugar de hacerlo globalmente?" +### 您的疑问 +"我们应该如何在每个 Cookie 级别正确配置 `default_redirection_url`，而不是进行全局配置？" -### Respuesta: Muévalo dentro de la configuración de cada cookie +### 解答：将其移动到每个 Cookie 的配置内部 -**Antiguo (Causa Error)**: +**旧方式 (会导致错误)**: ```yaml session: expiration: 1h - default_redirection_url: https://forgejo.localhost # ❌ INCORRECTO + default_redirection_url: https://forgejo.localhost # ❌ 错误 cookies: - name: authelia_session domain: localhost ``` -**Nuevo (Correcto)**: +**新方式 (正确)**: ```yaml session: expiration: 1h - # No lo ponga aquí ❌ + # 不要放在这里 ❌ cookies: - name: authelia_session domain: localhost - default_redirection_url: https://forgejo.localhost # ✅ AQUÍ + default_redirection_url: https://forgejo.localhost # ✅ 在这里 authelia_url: https://auth.localhost same_site: Lax secure: false -# Opcional: Fallback global al nivel de la raíz +# 可选：根级别的全局备选方案 default_redirection_url: 'https://forgejo.localhost' ``` -**Múltiples Cookies (Avanzado)**: +**多个 Cookie (进阶)**: ```yaml session: cookies: - # Cookie de producción + # 生产环境 Cookie - name: authelia_session - domain: ejemplo.com - default_redirection_url: https://app.ejemplo.com + domain: example.com + default_redirection_url: https://app.example.com secure: true - # Cookie de desarrollo + # 开发环境 Cookie - name: authelia_session_dev domain: localhost default_redirection_url: https://forgejo.localhost secure: false -# Fallback global -default_redirection_url: 'https://ejemplo.com' +# 全局备选方案 +default_redirection_url: 'https://example.com' ``` -**Cómo funciona**: -1. El usuario accede a un servicio protegido (ej. n8n.localhost) -2. Es redirigido al login de Authelia (auth.localhost) -3. Tras el login, Authelia comprueba el `default_redirection_url` de cada cookie -4. Redirige a la URL configurada (ej. forgejo.localhost) -5. Si no hay configuración por cookie, usa el `default_redirection_url` global +**工作原理**: +1. 用户访问受保护的服务 (例如 n8n.localhost) +2. 被重定向到 Authelia 登录页面 (auth.localhost) +3. 登录后，Authelia 会检查每个 Cookie 的 `default_redirection_url` +4. 重定向到配置的 URL (例如 forgejo.localhost) +5. 如果没有设置每个 Cookie 的配置，则使用全局 `default_redirection_url` -**Campos de configuración requeridos**: +**必填配置字段**: ```yaml cookies: - - name: authelia_session # Nombre de la cookie - domain: localhost # Dominio de la cookie - authelia_url: https://auth.localhost # Endpoint de Authelia - default_redirection_url: https://forgejo.localhost # Destino de fallback - same_site: Lax # Protección CSRF - secure: false # true en producción + - name: authelia_session # Cookie 名称 + domain: localhost # Cookie 域名 + authelia_url: https://auth.localhost # Authelia 端点 + default_redirection_url: https://forgejo.localhost # 备选目标 + same_site: Lax # CSRF 保护 + secure: false # 生产环境为 true ``` --- -## Q5: HTTP vs HTTPS - Desarrollo Local vs Producción +## Q5: HTTP vs HTTPS - 本地开发 vs 生产环境 -### Su pregunta -"¿Podemos ejecutar Authelia con HTTP en desarrollo local (con nginx-proxy gestionando SSL mediante certificados autofirmados o sin SSL) y luego cambiar a HTTPS en producción?" +### 您的疑问 +"我们可以在本地开发中使用 HTTP 运行 Authelia (由 nginx-proxy 通过自签名证书管理 SSL 或不使用 SSL)，然后在生产环境中切换到 HTTPS 吗？" -### Respuesta: SÍ, Authelia es agnóstico al protocolo +### 解答：是的，Authelia 与协议无关 -**Desarrollo Local (HTTP, sin SSL)**: +**本地开发 (HTTP，无 SSL)**: ```yaml -# En authelia/configuration.yml: +# 在 authelia/configuration.yml 中: server: address: 'tcp://0.0.0.0:9091' tls: - enabled: false # ✅ Solo HTTP + enabled: false # ✅ 仅使用 HTTP session: cookies: - name: authelia_session - secure: false # ✅ Permitir cookies HTTP + secure: false # ✅ 允许 HTTP Cookie same_site: Lax ``` @@ -277,30 +277,30 @@ authelia: environment: - VIRTUAL_HOST=auth.localhost - VIRTUAL_PORT=9091 - # nginx-proxy sirve vía HTTP + # nginx-proxy 通过 HTTP 提供服务 ``` -**Cómo acceder**: +**如何访问**: ``` -Navegador: http://auth.localhost:9091 -Navegador: http://n8n.localhost +浏览器访问: http://auth.localhost:9091 +浏览器访问: http://n8n.localhost ``` --- -**Producción (HTTPS con Let's Encrypt)**: +**生产环境 (带有 Let's Encrypt 的 HTTPS)**: ```yaml -# En authelia/configuration.yml (NO SE NECESITAN CAMBIOS): +# 在 authelia/configuration.yml 中 (无需更改): server: address: 'tcp://0.0.0.0:9091' tls: - enabled: false # ✅ Sigue siendo false - # nginx-proxy gestiona la terminación TLS + enabled: false # ✅ 仍为 false + # 由 nginx-proxy 处理 TLS 终止 session: cookies: - name: authelia_session - secure: true # ✅ Requerir HTTPS + secure: true # ✅ 要求 HTTPS same_site: Strict ``` @@ -312,64 +312,64 @@ authelia: labels: - com.github.jrcs.letsencrypt_nginx_proxy_companion.enable=true environment: - - VIRTUAL_HOST=auth.ejemplo.com + - VIRTUAL_HOST=auth.example.com - VIRTUAL_PORT=9091 - # nginx-proxy + acme-companion gestionan HTTPS + Let's Encrypt + # nginx-proxy + acme-companion 处理 HTTPS + Let's Encrypt ``` -**Cómo acceder**: +**如何访问**: ``` -Navegador: https://auth.ejemplo.com -Navegador: https://app.ejemplo.com +浏览器访问: https://auth.example.com +浏览器访问: https://app.example.com ``` --- -**Puntos Clave**: +**关键点**: -1. **Authelia en sí**: Siempre se ejecuta en HTTP (puerto 9091) internamente -2. **Terminación TLS**: Deje que nginx-proxy gestione la terminación HTTPS -3. **Configuración de Authelia**: `tls.enabled: false` para todos los escenarios -4. **Seguridad de la sesión**: - - Dev local: `secure: false` (permitir HTTP) - - Producción: `secure: true` (requerir HTTPS) -5. **Ruta de migración**: - - Empezar con dev local (HTTP, sin SSL) - - Mover a producción (HTTPS vía nginx-proxy + Let's Encrypt) - - No se necesitan cambios en la configuración de Authelia - - Solo cambiar las etiquetas de docker-compose y las variables de entorno +1. **Authelia 本身**: 内部始终运行在 HTTP (端口 9091) 上 +2. **TLS 终止**: 让 nginx-proxy 处理 HTTPS 终止 +3. **Authelia 配置**: 在所有场景下 `tls.enabled: false` +4. **会话安全**: + - 本地开发: `secure: false` (允许 HTTP) + - 生产环境: `secure: true` (要求 HTTPS) +5. **迁移路径**: + - 从本地开发开始 (HTTP，无 SSL) + - 迁移到生产环境 (通过 nginx-proxy + Let's Encrypt 使用 HTTPS) + - 无需更改 Authelia 配置 + - 仅更改 docker-compose 标签和环境变量 --- -## Estado de la Implementación +## 实施状态 -Todas las correcciones han sido implementadas: +所有修复均已实施： -| 问题 | Estado | Archivo | +| 问题 | 状态 | 文件 | |-------|--------|------| -| Obsolescencia de secreto JWT | ✅ Corregido | [authelia/configuration.yml](authelia/configuration.yml) | -| Conflicto SMTP | ✅ Corregido | [authelia/configuration.yml](authelia/configuration.yml) + [docker-compose.yml](docker-compose.yml) | -| Cookies de sesión | ✅ Corregido | [authelia/configuration.yml](authelia/configuration.yml) | -| Dominio de la cookie | ✅ Corregido | [authelia/configuration.yml](authelia/configuration.yml) | -| HTTP vs HTTPS | ✅ Configurado | [authelia/configuration.yml](authelia/configuration.yml) | -| Documentación | ✅ Completa | [docs/authelia-setup.md](docs/authelia-setup.md) + [AUTHELIA_FIXES_SUMMARY.md](AUTHELIA_FIXES_SUMMARY.md) | +| JWT 密钥废弃 | ✅ 已修复 | [authelia/configuration.yml](authelia/configuration.yml) | +| SMTP 冲突 | ✅ 已修复 | [authelia/configuration.yml](authelia/configuration.yml) + [docker-compose.yml](docker-compose.yml) | +| 会话 Cookie | ✅ 已修复 | [authelia/configuration.yml](authelia/configuration.yml) | +| Cookie 域名 | ✅ 已修复 | [authelia/configuration.yml](authelia/configuration.yml) | +| HTTP vs HTTPS | ✅ 已配置 | [authelia/configuration.yml](authelia/configuration.yml) | +| 文档 | ✅ 已完成 | [docs/authelia-setup.md](docs/authelia-setup.md) + [AUTHELIA_FIXES_SUMMARY.md](AUTHELIA_FIXES_SUMMARY.md) | --- -## Inicio Rápido +## 快速入门 -1. **Actualizar archivos de configuración** ✅ (Ya hecho) -2. **Crear `.env` con SMTP**: +1. **更新配置文件** ✅ (已完成) +2. **创建包含 SMTP 的 `.env`**: ```bash SMTP_HOST=smtp.tinet.cat SMTP_PORT=587 - SMTP_USERNAME=su_correo@example.com - SMTP_PASSWORD=su_contraseña + SMTP_USERNAME=your_email@example.com + SMTP_PASSWORD=your_password SMTP_SENDER=Authelia AUTHELIA_DOMAIN=auth.localhost ``` -3. **Generar secretos** (si no se ha hecho): +3. **生成密钥** (如果尚未完成): ```bash mkdir -p ./secrets openssl rand -base64 32 > ./secrets/authelia_jwt_secret.txt @@ -377,28 +377,28 @@ Todas las correcciones han sido implementadas: chmod 600 ./secrets/*.txt ``` -4. **Iniciar servicios**: +4. **启动服务**: ```bash docker compose up -d redis authelia docker compose logs -f authelia ``` -5. **Prueba**: +5. **测试**: ```bash curl http://localhost:9091/api/health - # Esperado: 200 OK + # 预期结果: 200 OK ``` -6. **Acceder a la UI**: +6. **访问 UI**: ``` - Navegador: http://auth.localhost:9091 + 浏览器访问: http://auth.localhost:9091 ``` --- -## ¿Aún necesita ayuda? +## 仍需帮助？ -- **Guía de configuración completa**: Ver [docs/authelia-setup.md](docs/authelia-setup.md) -- **Explicaciones detalladas de los problemas**: Ver [AUTHELIA_FIXES_SUMMARY.md](AUTHELIA_FIXES_SUMMARY.md) -- **Solución de problemas**: Consulte la sección "Troubleshooting" en [docs/authelia-setup.md](docs/authelia-setup.md) -- **Docs oficiales**: https://www.authelia.com/configuration/ +- **完整设置指南**: 请参阅 [docs/authelia-setup.md](docs/authelia-setup.md) +- **详细问题说明**: 请参阅 [AUTHELIA_FIXES_SUMMARY.md](AUTHELIA_FIXES_SUMMARY.md) +- **故障排除**: 请参考 [docs/authelia-setup.md](docs/authelia-setup.md) 中的 "故障排除" 部分 +- **官方文档**: https://www.authelia.com/configuration/ diff --git a/CONTRIBUTING.ca.md b/CONTRIBUTING.ca.md index 0da0048..8a09fbc 100644 --- a/CONTRIBUTING.ca.md +++ b/CONTRIBUTING.ca.md @@ -1,21 +1,21 @@ -# Contributing to cognito-stack 🤝 -[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/Axlfc/connect-core/blob/master/CONTRIBUTING.ca.md) -[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/Axlfc/connect-core/blob/master/CONTRIBUTING.en.md) -[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/Axlfc/connect-core/blob/master/CONTRIBUTING.md) -[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/Axlfc/connect-core/blob/master/CONTRIBUTING.zh-cn.md) +# Contribuir a connect-core 🤝 +[![ca](https://img.shields.io/badge/lang-ca-blue.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/CONTRIBUTING.ca.md) +[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/CONTRIBUTING.en.md) +[![es](https://img.shields.io/badge/lang-es-yellow.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/CONTRIBUTING.md) +[![zh-cn](https://img.shields.io/badge/lang-zh--cn-red.svg)](https://github.com/[ORGANIZATION]/connect-core/blob/master/CONTRIBUTING.zh-cn.md) -¡Gracias por tu interés en contribuir a cognito-stack! Este documento proporciona las pautas para contribuir al proyecto. +Gràcies pel teu interès a contribuir a connect-core! Aquest document proporciona les pautes per contribuir al projecte. ## Taula de continguts -- [Codi de conducta](#código-de-conducta) -- [Com contribuir-hi?](#cómo-contribuir) -- [Informar d'errors](#reportar-bugs) -- [Suggerir millores](#sugerir-mejoras) +- [Codi de conducta](#codi-de-conducta) +- [Com contribuir-hi?](#com-contribuir-hi) +- [Informar d'errors](#informar-derrors) +- [Suggerir millores](#suggerir-millores) - [Pull Requests](#pull-requests) -- [Estàndards de codi](#estándares-de-código) -- [Validació local](#validación-local) +- [Estàndards de codi](#estandards-de-codi) +- [Validació local](#validacio-local) - [Commit conventions](#commit-conventions) --- @@ -24,27 +24,27 @@ ### La nostra promesa -Nos comprometemos a proporcionar un entorno abierto y acogedor para todos, independientemente de: -- Edad, tamaño corporal, capacidad/discapacidad -- Etnia, identidad y expresión de género -- Nivel de experiencia, educación -- Situación socioeconómica +Ens comprometem a proporcionar un entorn obert i acollidor per a tothom, independentment de: +- Edat, mida corporal, capacitat/discapacitat +- Ètnia, identitat i expressió de gènere +- Nivell d'experiència, educació +- Situació socioeconòmica ### Els nostres estàndards -Comportamientos que contribuyen a crear un entorno positivo: -- ✅ Usar lenguaje inclusivo y acogedor -- ✅ Ser respetuoso con los puntos de vista diferentes -- ✅ Aceptar críticas constructivas -- ✅ Enfocarse en lo mejor para la comunidad -- ✅ Mostrar empatía hacia otros miembros +Comportaments que contribueixen a crear un entorn positiu: +- ✅ Utilitzar llenguatge inclusiu i acollidor +- ✅ Ser respectuós amb els punts de vista diferents +- ✅ Acceptar crítiques constructives +- ✅ Enfocar-se en el millor per a la comunitat +- ✅ Mostrar empatia cap als altres membres -Comportamientos inaceptables: -- ❌ Lenguaje o imágenes sexuales -- ❌ Trolling, comentarios insultantes o ataques personales -- ❌ Acoso público o privado -- ❌ Publicar información privada sin consentimiento -- ❌ Otra conducta inapropiada +Comportaments inacceptables: +- ❌ Llenguatge o imatges sexuals +- ❌ Trolling, comentaris insultants o atacs personals +- ❌ Assetjament públic o privat +- ❌ Publicar informació privada sense consentiment +- ❌ Altres conductes inapropiades --- @@ -52,61 +52,61 @@ Comportamientos inaceptables: ### Requisits previs -- Git instalado (`git --version`) +- Git instal·lat (`git --version`) - Docker & Docker Compose (`docker --version`, `docker compose version`) - Bash 4.0+ (`bash --version`) -- Cuenta GitHub +- Compte de GitHub -### Workflow de contribución +### Flux de treball de contribució -1. **Fork el repositorio** +1. **Fes un fork del repositori** ```bash - # En GitHub, haz clic en "Fork" - # Luego clona tu fork - git clone https://github.com/TU_USUARIO/cognito-stack.git - cd cognito-stack + # A GitHub, fes clic a "Fork" + # Després clona el teu fork + git clone https://github.com/[EL_TEU_USUARI]/connect-core.git + cd connect-core ``` -2. **Crea una rama para tu feature** +2. **Crea una branca per a la teva funcionalitat** ```bash - git checkout -b feature/descripcion-clara - # o para bugs: - git checkout -b fix/descripcion-del-bug + git checkout -b feature/descripcio-clara + # o per a errors: + git checkout -b fix/descripcio-de-l-error ``` -3. **Realiza cambios** - - Edita archivos necesarios - - Mantén commits atómicos y con mensajes claros - - Valida localmente (ver [Validació local](#validación-local)) +3. **Realitza canvis** + - Edita els fitxers necessaris + - Mantén commits atòmics i amb missatges clars + - Valida localment (vegeu [Validació local](#validacio-local)) -4. **Push a tu fork** +4. **Puja al teu fork** ```bash - git push origin feature/descripcion-clara + git push origin feature/descripcio-clara ``` -5. **Abre un Pull Request** - - Haz clic en "New Pull Request" en GitHub - - Completa el template de PR - - Espera review +5. **Obre un Pull Request** + - Fes clic a "New Pull Request" a GitHub + - Completa la plantilla de PR + - Espera la revisió --- ## Informar d'errors -### Antes de reportar +### Abans d'informar -- ✅ Verifica que no exista un issue similar -- ✅ Actualiza al código más reciente (`git pull origin master`) -- ✅ Reproduce el bug con el código actual -- ✅ Recopila información de debugging +- ✅ Verifica que no existeixi un issue similar +- ✅ Actualitza al codi més recent (`git pull origin master`) +- ✅ Reprodueix l'error amb el codi actual +- ✅ Recull informació de depuració -### Cómo reportar +### Com informar -**Abre un issue** con los siguientes detalles: +**Obre un issue** amb els següents detalls: ```markdown -## Descripción -Breve descripción del bug +## Descripció +Breu descripció de l'error ## Passos per reproduir 1. ... @@ -114,120 +114,120 @@ Breve descripción del bug 3. ... ## Comportament actual -¿Qué sucedió? +Què ha passat? ## Comportament esperat -¿Qué debería suceder? +Què hauria de passar? ## Informació del sistema -- OS: [ej: Ubuntu 22.04] -- Docker version: [ej: 24.0.0] +- OS: [ex: Ubuntu 22.04] +- Docker version: [ex: 24.0.0] - Profile: [cpu/gpu-nvidia/gpu-amd] ## Logs ``` - + ``` ## Informació addicional -Cualquier contexto adicional +Qualsevol context addicional ``` --- ## Suggerir millores -### Antes de sugerir +### Abans de suggerir -- ✅ Lee la documentación -- ✅ Busca sugerencias similares -- ✅ Considera el alcance del proyecto +- ✅ Llegeix la documentació +- ✅ Busca suggeriments similars +- ✅ Considera l'abast del projecte -### Template de sugerencia +### Plantilla de suggeriment ```markdown -## Descripción breve -Una línea describiendo la mejora +## Descripció breu +Una línia descrivint la millora -## Problema que resuelve -¿Qué problema de usuario resuelve esto? +## Problema que resol +Quin problema d'usuari resol això? -## Solució propuesta -Descripción de la mejora +## Solució proposada +Descripció de la millora -## Beneficios -- Beneficio 1 -- Beneficio 2 +## Beneficis +- Benefici 1 +- Benefici 2 -## Ejemplos de implementación -Pseudocódigo o ejemplos si aplica +## Exemples d'implementació +Pseudocodi o exemples si s'aplica -## Alternativas consideradas -Otras soluciones evaluadas +## Alternatives considerades +Altres solucions avaluades ``` --- ## Pull Requests -### Checklist antes de abrir PR +### Checklist abans d'obrir un PR -- [ ] Mi código sigue los estándares de código del proyecto -- [ ] He actualizado la documentación -- [ ] Mis commits tienen mensajes claros y descriptivos -- [ ] He validado localmente con `scripts/validate.sh` -- [ ] He testeado con `scripts/smoke-test.sh` -- [ ] No contiene código "en construcción" o temporal -- [ ] No añade dependencias innecesarias +- [ ] El meu codi segueix els estàndards de codi del projecte +- [ ] He actualitzat la documentació +- [ ] Els meus commits tenen missatges clars i descriptius +- [ ] He validat localment amb `scripts/validate.sh` +- [ ] He fet proves amb `scripts/smoke-test.sh` +- [ ] No conté codi "en construcció" o temporal +- [ ] No afegeix dependències innecessàries -### Proceso de review +### Procés de revisió -1. **Validación automática** (GitHub Actions) +1. **Validació automàtica** (GitHub Actions) - YAML validation - Shell linting - Dockerfile linting - Docker Compose validation - Security checks -2. **Review manual** - - Revisión de código - - Evaluación de cambios - - Solicitud de cambios si es necesario +2. **Revisió manual** + - Revisió de codi + - Avaluació de canvis + - Sol·licitud de canvis si és necessari 3. **Merge** - - Aprobación del maintainer + - Aprovació del maintainer - Squash & merge a master - - CI/CD deploys cambios + - CI/CD desplega els canvis -### Template de PR +### Plantilla de PR ```markdown -## Descripción -Breve descripción de los cambios +## Descripció +Breve descripció dels canvis -## Relacionado con +## Relacionat amb - Closes #123 - Fixes #456 ## Tipus de canvi -- [ ] Bug fix -- [ ] Nueva feature -- [ ] Cambio de documentación -- [ ] Refactoring +- [ ] Correcció d'error (Bug fix) +- [ ] Nova funcionalitat (Feature) +- [ ] Canvi de documentació +- [ ] Refactorització ## Canvis realitzats -- Cambio 1 -- Cambio 2 -- Cambio 3 +- Canvi 1 +- Canvi 2 +- Canvi 3 ## Proves realitzades -Describe cómo testeaste los cambios +Descriu com has provat els canvis -## Screenshots (si aplica) -Añade screenshots si hay cambios visuales +## Screenshots (si s'aplica) +Afegeix captures de pantalla si hi ha canvis visuals ## Notes addicionals -Cualquier información adicional para los reviewers +Qualsevol informació addicional per als revisors ``` --- @@ -238,28 +238,28 @@ Cualquier información adicional para los reviewers ```bash #!/bin/bash -set -e # Exit on error +set -e # Surt en cas d'error -# Usar comentarios descriptivos -# Variables en MAYUSCULAS +# Utilitzar comentaris descriptius +# Variables en MAJÚSCULES CONFIG_FILE="/path/to/file" -# Funciones con nombres descriptivos +# Funcions amb noms descriptius print_info() { echo "ℹ️ $1" } -# Validación de entrada +# Validació d'entrada if [ -z "$1" ]; then - echo "Error: Falta parametro" + echo "Error: Falta paràmetre" exit 1 fi -# Usar comillas para variables -echo "Mensaje: $CONFIG_FILE" +# Utilitzar cometes per a les variables +echo "Missatge: $CONFIG_FILE" ``` -**Herramienta:** `shellcheck` +**Eina:** `shellcheck` ```bash shellcheck script.sh ``` @@ -272,30 +272,30 @@ FROM base-image:version LABEL maintainer="maintainer@example.com" LABEL description="Clear description" -# Usar comentarios para secciones +# Utilitzar comentaris per a les seccions USER root -# Combinar RUN cuando sea posible +# Combinar RUN quan sigui possible RUN apt-get update && \ apt-get install -y \ package1 \ package2 && \ rm -rf /var/lib/apt/lists/* -# Exponer puertos explícitamente +# Exposar ports explícitament EXPOSE 5678 -# Definir volúmenes +# Definir volums VOLUME ["/data"] -# Usuario no-root +# Usuari no-root USER appuser ENTRYPOINT ["./entrypoint.sh"] CMD ["start"] ``` -**Herramienta:** `hadolint` +**Eina:** `hadolint` ```bash hadolint Dockerfile ``` @@ -303,18 +303,18 @@ hadolint Dockerfile ### YAML (docker-compose.yml) ```yaml -# Indentación de 2 espacios +# Indentació de 2 espais version: "3.8" services: service-name: image: image:version - # Organización lógica + # Organització lògica container_name: service-name restart: unless-stopped - # Variables de entorno primero + # Variables d'entorn primer environment: - VAR_NAME=value @@ -322,7 +322,7 @@ services: ports: - "5678:5678" - # Volúmenes + # Volums volumes: - volume-name:/path @@ -353,67 +353,67 @@ networks: } ``` -**Validar con:** `python -m json.tool n8n-task-runners.json` +**Validar amb:** `python -m json.tool n8n-task-runners.json` -### Documentación (Markdown) +### Documentació (Markdown) -- ✅ Títulos jerárquicos claros -- ✅ Ejemplos de código en bloques -- ✅ Enlaces internos a archivos -- ✅ Taula de continguts para documentos largos -- ✅ Notas destacadas con blockquotes -- ✅ Listas estructuradas +- ✅ Títols jeràrquics clars +- ✅ Exemples de codi en blocs +- ✅ Enllaços interns a fitxers +- ✅ Taula de continguts per a documents llargs +- ✅ Notes destacades amb blockquotes +- ✅ Llistes estructurades ```markdown -# Título Principal +# Títol Principal -## Subtítulo +## Subtítol ### Subsubtítulo -**Texto en negrita** y *en itálica* +**Text en negreta** i *en cursiva* -> Nota o cita importante +> Nota o cita important -### Ejemplo de código +### Exemple de codi \`\`\`bash -# Bash code -echo "Hello" +# Codi Bash +echo "Hola" \`\`\` -- Punto 1 -- Punto 2 - - Subpunto 2a +- Punt 1 +- Punt 2 + - Subpunt 2a ``` --- ## Validació local -### 1. Script de validación general +### 1. Script de validació general ```bash -# Ejecuta todas las comprobaciones +# Executa totes les comprovacions ./scripts/validate.sh -# Salida esperada: -# ✓ Validaciones pasadas -# ⚠ Warnings (no bloquea) -# ✗ Errores (bloquea) +# Sortida esperada: +# ✓ Validacions passades +# ⚠ Avisos (no bloqueja) +# ✗ Errors (bloqueja) ``` -### 2. Smoke test +### 2. Prova de fum (Smoke test) ```bash -# Prueba rápida del stack (requiere Docker) -./scripts/smoke-test.sh # Usa profile CPU -./scripts/smoke-test.sh gpu-nvidia # Usa GPU NVIDIA -./scripts/smoke-test.sh gpu-amd # Usa GPU AMD +# Prova ràpida de l'stack (requereix Docker) +./scripts/smoke-test.sh # Utilitza el perfil CPU +./scripts/smoke-test.sh gpu-nvidia # Utilitza GPU NVIDIA +./scripts/smoke-test.sh gpu-amd # Utilitza GPU AMD -# Comprueba: -# - Inicio de servicios +# Comprova: +# - Inici de serveis # - Health checks -# - Disponibilidad de APIs +# - Disponibilitat d'APIs ``` ### 3. Linting manual @@ -435,16 +435,16 @@ python3 -m json.tool n8n-task-runners.json markdownlint *.md ``` -### 4. Validación de Docker Compose +### 4. Validació de Docker Compose ```bash -# Verificar sintaxis +# Verificar sintaxi docker compose config --quiet -# Listar servicios +# Llistar serveis docker compose config | grep "^ [a-z]" -# Simular inicio (sin pull) +# Simular inici (sense pull) docker compose --profile cpu config --quiet ``` @@ -452,80 +452,80 @@ docker compose --profile cpu config --quiet ## Commit conventions -### Formato de mensaje +### Format del missatge ``` -(): +(): - +