Saltar al contenido
hg.Héctor GarridoCiencia de datos · Estadística · Ingeniería de datos
← Volver al blog
Portafolio RAG

Cinco Bugs en Cadena: Una Noche Arreglando el Admin de Django en Producción

Este artículo técnico detalla la resolución de cinco bugs críticos encontrados en el panel de administración de Django en un entorno de producción. El primer bug, un error 503, se debió a una señal sincrónica que bloqueaba Gunicorn al interactuar con Vertex AI. La solución implicó el uso de `transaction.on_commit()` y hilos daemon. El segundo bug, también un error 503, fue causado por un fallo en la verificación CSRF debido a un problema de parsing en GitHub Actions. Aprenderás sobre el manejo de señales en Django, la configuración de Gunicorn y la depuración de errores en entornos de producc

Cinco Bugs en Cadena: Una Noche Arreglando el Admin de Django en Producción

Bug 1: 503 Service Unavailable — Señal Sincrónica Bloquea Gunicorn

Síntoma

Al guardar un post desde el admin de Django, el servidor respondía 503 Service Unavailable después de ~120 segundos. No era un error de Django — era Cloud Run matando la instancia porque Gunicorn no respondía a tiempo.

Diagnóstico

La app search tiene una señal post_save conectada al modelo Post:

# search/signals.py (ANTES del fix)
@receiver(post_save, sender=Post)
def reindex_on_save(sender, instance, **kwargs):
    SearchEngine.index_post(instance)          # ← BLOQUEO
    SearchEngine.invalidate_cache_for_post(instance.pk)

SearchEngine.index_post() llama a Vertex AI para generar embeddings del texto del post. Esa operación toma 3-10 segundos en condiciones normales, pero con latencia de red o rate limits puede tardar más.

El problema es que la señal post_save se ejecuta dentro de la misma request HTTP del admin. Guardar un post en el admin → Django procesa el form → guarda en BD → dispara post_save → llama a Vertex AI → espera respuesta → recién entonces retorna la respuesta HTTP.

Con la configuración de Gunicorn:

gunicorn --workers 1 --threads 2 --timeout 120

Solo hay 2 threads. Si ambos están ocupados esperando a Vertex AI, toda la aplicación se congela. Cloud Run detecta que no hay workers disponibles y devuelve 503.

Fix (commit 6796cf1)

La solución fue mover la re-indexación a un hilo daemon que se ejecuta después del commit de la transacción:

# search/signals.py (DESPUÉS del fix)
def _reindex_in_background(post_pk, post_title, is_published):
    """Ejecuta re-indexación en hilo daemon, no bloquea HTTP."""
    from .engine import SearchEngine
    from .models import PostEmbedding

    try:
        post = Post.objects.get(pk=post_pk)
    except Post.DoesNotExist:
        return

    if is_published:
        SearchEngine.index_post(post)
    else:
        PostEmbedding.objects.filter(post=post).delete()

    SearchEngine.invalidate_cache_for_post(post_pk)


@receiver(post_save, sender=Post)
def reindex_and_invalidate_on_post_save(sender, instance, **kwargs):
    post_pk = instance.pk
    post_title = instance.title
    is_published = instance.is_published

    def _on_commit():
        t = threading.Thread(
            target=_reindex_in_background,
            args=(post_pk, post_title, is_published),
            daemon=True,
        )
        t.start()

    transaction.on_commit(_on_commit)

Dos cambios clave:

  1. transaction.on_commit(): Garantiza que el hilo se lanza solo cuando la transacción de la BD ya está confirmada. Sin esto, el hilo podría intentar leer un post que aún no existe en la BD.

  2. threading.Thread(daemon=True): El hilo de re-indexación se ejecuta en background. La respuesta HTTP del admin retorna inmediatamente — el usuario ve "Post guardado" mientras Vertex AI genera los embeddings en paralelo.

¿Por qué daemon=True? Un hilo daemon se termina automáticamente cuando el proceso principal termina. En Cloud Run, si la instancia se escala a cero, los hilos daemon se limpian sin dejar procesos zombie. Si la re-indexación falla silenciosamente, el peor caso es que el post no aparece en búsquedas semánticas hasta el siguiente save — un tradeoff aceptable.

Lección

No hagas I/O de red dentro de señales de Django. Las señales (post_save, pre_save, etc.) se ejecutan sincrónicamente en la misma transacción/request. Si la operación tarda, bloqueas al usuario. Si el servicio externo falla, tu request falla. La regla es: señales para lógica rápida y local, tareas asíncronas para todo lo demás.


Bug 2: 503 en POST — CSRF Invisible por Parsing de GitHub Actions

Síntoma

Con el fix del signal desplegado, el admin cargaba (GET funcionaba). Pero al intentar guardar un post (POST), el servidor respondía 503 de nuevo. Los logs del admin no mostraban error de Django — era otra vez Cloud Run cortando la conexión.

Diagnóstico

Esta fue la investigación más difícil porque el error no dejaba rastro en los logs de Django. Revisando los logs de Cloud Run directamente:

Forbidden (CSRF verification failed. Origin checking failed -
https://api.hectorgarrido.cl does not match any trusted origins.)

Django estaba rechazando las requests POST por CSRF. Pero en deploy.yml estaban configurados los orígenes:

# deploy.yml (ANTES del fix)
env_vars: |
  CORS_ALLOWED_ORIGINS=https://hectorgarrido.cl,https://www.hectorgarrido.cl
  CSRF_TRUSTED_ORIGINS=https://hectorgarrido.cl,https://www.hectorgarrido.cl

El problema no era la configuración — era cómo la acción deploy-cloudrun@v2 interpreta el env_vars.

La Causa Raíz: Parsing de Comas

La acción de GitHub Actions google-github-actions/deploy-cloudrun@v2 parsea el bloque env_vars usando comas como separadores de variables. Cuando escribes:

env_vars: |
  CORS_ALLOWED_ORIGINS=https://a.run.app,https://hectorgarrido.cl

La acción interpreta esto como dos variables de entorno separadas:

Variable Valor
CORS_ALLOWED_ORIGINS https://a.run.app
https://hectorgarrido.cl (variable vacía)

El resultado: CORS_ALLOWED_ORIGINS solo contenía la URL de Cloud Run. Ni hectorgarrido.cl, ni www.hectorgarrido.cl, ni api.hectorgarrido.cl estaban en las origenes permitidas.

Y api.hectorgarrido.cl nunca estuvo en la lista — ni siquiera en la configuración "correcta" original. Pero ese es el origin que el navegador envía cuando haces POST desde api.hectorgarrido.cl/admin/.

Fix (commit 285bd60)

Mover CORS y CSRF a un paso separado que usa gcloud directamente con la sintaxis ^DELIM^:

# deploy.yml (DESPUÉS del fix)

# Las variables sin comas van en deploy-cloudrun@v2 normalmente
- name: Deploy Backend
  uses: google-github-actions/deploy-cloudrun@v2
  with:
    env_vars: |
      DEBUG=False
      DJANGO_SECRET_KEY=${{ secrets.DJANGO_SECRET_KEY }}
      # ... (sin CORS ni CSRF)

# CORS/CSRF se setean con gcloud porque las comas son parte del valor
- name: Set CORS and CSRF origins
  run: |
    gcloud run services update blog-backend \
      --region ${{ env.REGION }} \
      --update-env-vars "^||^CORS_ALLOWED_ORIGINS=https://blog-frontend-igj3g6bugq-uc.a.run.app,https://hectorgarrido.cl,https://www.hectorgarrido.cl,https://api.hectorgarrido.cl||CSRF_TRUSTED_ORIGINS=https://blog-frontend-igj3g6bugq-uc.a.run.app,https://hectorgarrido.cl,https://www.hectorgarrido.cl,https://api.hectorgarrido.cl"

La sintaxis ^||^ le indica a gcloud que use || como separador entre variables en vez de ,. Así las comas dentro de los valores se preservan intactas.

Fix Inmediato

Mientras mergeaba el PR, ejecuté el mismo comando directamente desde la terminal para no esperar al pipeline:

gcloud run services update blog-backend --region us-central1 \
  --update-env-vars "^||^CORS_ALLOWED_ORIGINS=...||CSRF_TRUSTED_ORIGINS=..."

Lección

Lee la documentación de las acciones de CI/CD que usas. deploy-cloudrun@v2 tiene un comportamiento implícito de parsing que no es obvio. El manejo de comas como separadores es una decisión de diseño de la acción, no de Cloud Run ni de gcloud. La misma configuración funciona perfectamente con gcloud run deploy --set-env-vars.


Bug 3: Server Error 500 — Static File Faltante

Síntoma

Con CSRF arreglado, el admin finalmente debería funcionar. Pero al cargar api.hectorgarrido.cl/admin/, en lugar de la página de login, aparecía un Server Error (500) genérico — la página blanca de Django para errores no capturados.

Diagnóstico

Los logs de Cloud Run mostraban:

ValueError: Missing staticfiles manifest entry for 'admin/css/pygments.css'

Cuando configuré el PostAdmin para mostrar syntax highlighting del Markdown, agregué una referencia a una hoja de estilos:

# blog/admin.py
@admin.register(Post)
class PostAdmin(MarkdownxModelAdmin):
    # ...
    class Media:
        css = {
            'all': ('admin/css/pygments.css',)
        }

En desarrollo local (DEBUG=True), Django sirve estáticos directamente y no verifica un manifest. Pero en producción (DEBUG=False), la aplicación usa CompressedManifestStaticFilesStorage de WhiteNoise. Este storage procesa todos los archivos estáticos durante collectstatic y genera un manifest JSON con hashes en los nombres de archivo. Si un archivo referenciado no existe en el manifest, lanza ValueError.

El archivo pygments.css nunca existió en el repositorio. En desarrollo no importaba porque el admin no lo necesitaba para funcionar. En producción, el manifest estricto lo convierte en un error fatal.

Fix (commit 47b1b15)

Generar el archivo desde la librería Pygments:

from pygments.formatters import HtmlFormatter
css = HtmlFormatter(style='default').get_style_defs('.codehilite')
with open('static/admin/css/pygments.css', 'w', encoding='utf-8') as f:
    f.write(css)

Pero aquí apareció el siguiente bug.

Lección

CompressedManifestStaticFilesStorage es estricto por diseño. Si referencias un archivo estático que no existe, falla ruidosamente en producción aunque funcione en desarrollo. Siempre verifica que los archivos referenciados en class Media existan y estén incluidos en collectstatic.


Bug 4: Deploy Falla — UTF-16 BOM en Archivo CSS

Síntoma

El pipeline de GitHub Actions falló en el paso de build de Docker:

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xff in position 0:
invalid start byte
Post-processing 'admin/css/pygments.css' failed!

Diagnóstico

El archivo pygments.css fue generado en Windows con PowerShell. El operador de redirección > de PowerShell escribe archivos en UTF-16 con BOM (Byte Order Mark) por defecto. Los primeros bytes del archivo eran 0xFF 0xFE (BOM de UTF-16 LE), no texto UTF-8 válido.

WhiteNoise intenta leer todos los archivos estáticos como UTF-8 durante collectstatic. Al encontrar un archivo UTF-16, falla con UnicodeDecodeError.

Bytes esperados:  70 72 65 20 7b  (p r e   {)
Bytes reales:     ff fe 70 00 72  (BOM + UTF-16)

Fix (commit 83f607b)

Regenerar el archivo con encoding UTF-8 explícito:

from pygments.formatters import HtmlFormatter

css = HtmlFormatter(style='default').get_style_defs('.codehilite')
with open('static/admin/css/pygments.css', 'w', encoding='utf-8', newline='\n') as f:
    f.write(css)

Verificación de que el encoding es correcto:

with open('static/admin/css/pygments.css', 'rb') as f:
    print(f.read(10))
# b'pre { line'  ← UTF-8 limpio, sin BOM

Lección

PowerShell > no produce UTF-8. Esto es un problema conocido en Windows. El operador > (equivalente a Out-File) usa UTF-16 LE con BOM. Alternativas:

# PowerShell: forzar UTF-8
$content | Out-File -FilePath file.css -Encoding UTF8

# Mejor: usar Python directamente con encoding explícito
python -c "open('file.css', 'w', encoding='utf-8').write(content)"

Bug 5: Deploy Exitoso, Tráfico en Revisión Vieja

Síntoma

El pipeline de GitHub Actions completó exitosamente (PR #41 merged, build ✅). Pero el admin seguía mostrando el mismo error 500 de antes.

Diagnóstico

Cloud Run sirve tráfico a una revisión específica. Cuando fijé manualmente el tráfico a la revisión 00054 durante el debugging del bug anterior (para tener una versión funcional mientras arreglaba), el enrutamiento automático se desactivó.

Estado del tráfico:
  100%  blog-backend-00054-cnd  (revisión vieja, sin pygments.css fix)
  0%    blog-backend-00064-9gj  (revisión nueva, con todos los fixes)

El pipeline creaba nuevas revisiones pero el tráfico seguía apuntando a la vieja.

Además, hay un detalle sutil: el paso "Set CORS and CSRF origins" de deploy.yml ejecuta gcloud run services update, que crea una nueva revisión. Así cada deploy genera dos revisiones: una del deploy-cloudrun@v2 y otra del gcloud run services update. Si el tráfico no se enruta explícitamente, queda en la revisión anterior.

Fix (commit e69824f)

Fix inmediato con gcloud:

gcloud run services update-traffic blog-backend --to-latest --region us-central1

Fix permanente en deploy.yml — agregar un paso después de CORS/CSRF:

- name: Route backend traffic to latest
  run: |
    gcloud run services update-traffic blog-backend \
      --to-latest \
      --region ${{ env.REGION }}

Lección

El pinning de tráfico en Cloud Run es sticky. Si fijas tráfico a una revisión específica (con --to-revisions o desde la consola), Cloud Run deja de enrutar automáticamente a nuevas revisiones. Debes usar --to-latest explícitamente para restaurar el comportamiento automático. En un pipeline CI/CD, incluye siempre un paso de routing al final.


La Cadena Causal

Lo interesante de esta sesión de debugging es que cada bug estaba enmascarado por el anterior:

Bug 1: 503 (signal sync)
  ↓ fix →
Bug 2: 503 (CSRF)      ← invisible mientras Bug 1 mataba la request antes
  ↓ fix →
Bug 3: 500 (pygments)  ← invisible mientras CSRF rechazaba todo
  ↓ fix →
Bug 4: Deploy fail (UTF-16) ← solo visible al deployar el fix de Bug 3
  ↓ fix →
Bug 5: Traffic stuck    ← el deploy pasa pero la revisión vieja sigue activa
  ↓ fix →
✅ Admin funciona

No había forma de descubrir Bug 3 sin arreglar Bug 2, ni Bug 2 sin arreglar Bug 1. Cada capa de error ocultaba la siguiente. Es un patrón común en debugging de producción: los problemas se acumulan silenciosamente y solo se revelan cuando eliminas los anteriores.


Cronología de Commits

# Commit PR Cambio Resultado
1 6796cf1 #38 Signal async con threading.Thread + on_commit ✅ Admin carga (GET)
2 285bd60 #39 CORS/CSRF avec ^DELIM^ syntax + api subdomain ✅ Admin acepta POST
3 47b1b15 #40 Generar pygments.css desde Pygments ❌ Deploy falla (UTF-16)
4 83f607b #41 Regenerar pygments.css con UTF-8 explícito ✅ Deploy ok, tráfico stuck
5 e69824f (develop) Paso --to-latest en deploy.yml ✅ Admin funciona completamente

Tiempo total: ~2 horas desde el primer 503 hasta el admin funcionando.
Archivos modificados: 3 (signals.py, deploy.yml, pygments.css).
PRs: 4 (#38, #39, #40, #41).


Herramientas y Técnicas que Ayudaron

Logs de Cloud Run en Tiempo Real

gcloud logging read "resource.type=cloud_run_revision \
  AND resource.labels.service_name=blog-backend" \
  --limit 20 --format json

Los logs de Cloud Run fueron esenciales para Bug 2 (CSRF) y Bug 3 (pygments). Sin acceso a los logs, estos errores habrían sido completamente opacos — el navegador solo muestra "503" o "Server Error" sin detalle.

Gestión de Tráfico con gcloud

# Ver a qué revisión apunta el tráfico
gcloud run services describe blog-backend --format="value(status.traffic)"

# Fijar tráfico a una revisión específica (rollback)
gcloud run services update-traffic blog-backend \
  --to-revisions=blog-backend-00054-cnd=100

# Restaurar enrutamiento automático
gcloud run services update-traffic blog-backend --to-latest

Verificación de Encoding de Archivos

# Leer los primeros bytes para detectar BOM
with open('file.css', 'rb') as f:
    print(f.read(10))
# UTF-8 limpio:  b'pre { line'
# UTF-16 con BOM: b'\xff\xfe p\x00r'

Reflexión: ¿Por Qué Tantos Bugs Juntos?

Cada bug individual es menor. Ninguno es un error de diseño fundamental. Son errores de integración — su naturaleza de capa de cebolla los hace difíciles de prevenir:

  1. Signal sync: La señal funcionaba en desarrollo porque Vertex AI respondía rápido con baja latencia. En producción con un solo worker, la latencia extra la hacía fatal.

  2. CSRF parsing: deploy-cloudrun@v2 funciona perfectamente para variables sin comas. El bug solo se manifiesta con listas de orígenes múltiples — algo que no tenías al principio cuando solo había una URL de Cloud Run.

  3. pygments.css: El archivo solo es necesario con CompressedManifestStaticFilesStorage, que solo se activa con DEBUG=False, que solo pasa en producción.

  4. UTF-16 BOM: Solo ocurre si generas el archivo en PowerShell en Windows. En Linux o macOS, > produce UTF-8.

  5. Traffic sticky: Solo ocurre si previamente fijaste tráfico a una revisión específica. Si nunca hicieras rollback manual, el auto-routing funcionaría.

Cada uno es un caso edge que solo aparece en la combinación específica de herramientas y entorno de este proyecto. La lección no es "evita estas herramientas" — es tener acceso rápido a logs y capacidad de iterar.


Conclusión

Una sesión de debugging de 2 horas que expuso 5 bugs en cadena. La secuencia es representativa de lo que ocurre en producción real: los errores se acumulan en capas y se revelan secuencialmente.

Lo que empezó como "necesito guardar un post en el admin" terminó tocando señales de Django, parsing de GitHub Actions, gestión de archivos estáticos, encoding de Windows y routing de Cloud Run. Ninguno de estos componentes estaba roto individualmente — la falla estaba en las interfaces entre ellos.

Si hay una sola lección de esta noche: en producción, el bug que ves es rara vez el único bug que tienes.


Anterior: Analytics de Comportamiento: Entendiendo Cómo Navegan los Usuarios Mi Portafolio

Este artículo es parte de la serie "Construyendo un Blog con IA". El código fuente completo está en GitHub.