01. El síndrome del bot de 3.000 líneas
Casi cualquier proyecto de bot en Discord empieza de la misma forma: abres un archivo main.py, importas discord.py, metes cuatro decoradores @bot.command() y te parece que todo va sobre ruedas. El problema llega dos meses después, cuando has metido moderación, tickets, economía, bienvenida y niveles en el mismo archivo.
En ese punto tienes un monstruo de 3.000 líneas. Si tocas una tontería en el comando de la ruleta rusa de economía, se te cuela un error de sintaxis y te tira el bot entero, dejando sin moderación a los servidores donde está metido. Si quieres buscar dónde se guardaban los avisos de muteo, tienes que hacer scroll durante media hora entre funciones mezcladas.
main.py solo debe hacer tres cosas: arrancar el cliente con los intents estrictamente necesarios, inicializar la conexión a la base de datos y cargar los módulos. Nada de lógica de comandos, nada de embeds escritos a mano y nada de handlers kilométricos ahí dentro.
En Dabot tengo ahora mismo 68 cogs cargados simultáneamente y cerca de 45.000 líneas de Python. Mantener algo así funcionando sin volverte loco solo es posible si cada parte del bot es un compartimento estanco que no sabe (ni le importa) lo que está haciendo el vecino.
02. La arquitectura en Cogs: aislar para no caer
Un Cog en discord.py es básicamente una clase que agrupa comandos, listeners de eventos y tareas en segundo plano bajo un mismo dominio temático. La clave aquí es la separación física en carpetas:
├── main.py # Punto de entrada mínimo, intents y carga dinámica
├── cogs/ # 68 módulos independientes
│ ├── moderation.py # Bans, kicks, mutes, cuarentena
│ ├── tickets.py # Transcripts HTML, botones y feedback
│ ├── economy.py # Monedas, transferencias, tienda
│ ├── antiraid.py # Detección de joins masivos por segundo
│ └── ...
├── utils/ # Helpers compartidos (base de datos, wrappers de API)
│ ├── db.py # Conexiones SQLite y helpers WAL
│ └── i18n.py # Diccionarios de idioma
└── dashboard_server.py # API FastAPI que comparte la misma base de datos
Carga tolerante a fallos en setup_hook
Un error gravísimo que veo a menudo es hacer await bot.load_extension() a lo bruto dentro de un bucle. Si el módulo número 14 tiene un error de importación o le falta una clave en el archivo .env, la excepción detiene la ejecución y los 50 módulos siguientes se quedan sin cargar.
En Dabot implementé una rutina de carga tolerante a fallos dentro de setup_hook. Cada archivo se intenta cargar de forma aislada dentro de un bloque try/except. Si uno falla, se imprime el traceback en el log y el bot continúa cargando el resto sin pestañear:
async def setup_hook(self):
# Conexión asíncrona al pool de base de datos
await self.init_db()
# Carga dinámica de todos los cogs en cogs/*.py
cogs_dir = pathlib.Path("cogs")
for file in sorted(cogs_dir.glob("*.py")):
if file.name.startswith("_") or file.name == "tts.py":
continue # Módulos deshabilitados a propósito
ext_name = f"cogs.{file.stem}"
try:
await self.load_extension(ext_name)
logger.info(f"[+] Cargado módulo: {ext_name}")
except Exception as exc:
logger.error(f"[!] Fallo crítico en {ext_name}: {exc}", exc_info=True)
# El bot sigue vivo y carga los demás
¿La mayor ventaja de esto? Puedes usar await bot.reload_extension("cogs.economy") en caliente. Si acabas de corregir un bug en el sistema de economía, subes el archivo al VPS, tiras el comando de reload y el módulo se actualiza en memoria en 15 milisegundos sin desconectar el WebSocket de Discord ni reiniciar el proceso.
03. El mito de Postgres: SQLite en modo WAL
En casi cualquier tutorial de desarrollo de bots te dicen que necesitas montar un contenedor de PostgreSQL, otro de Redis para la caché y una cola en RabbitMQ o Celery. Si vas a gestionar un bot que está en 200.000 servidores con sharding distribuido en diez máquinas físicas, de acuerdo. Pero para un bot privado, de comunidad o mediano en un único servidor VPS, meter ese stack es pegarse un tiro en el pie.
En mi caso, Dabot comparte los datos entre el proceso del bot de Discord y el panel web administrativo en FastAPI. Ambos acceden a la misma base de datos SQLite. La gente suele pensar que SQLite se bloquea en cuanto hay dos procesos escribiendo a la vez (el temido database is locked), pero eso solo pasa si usas la configuración por defecto de hace 15 años.
1.
PRAGMA journal_mode = WAL; (Write-Ahead Logging: los lectores nunca bloquean a los escritores y los escritores no bloquean a los lectores).2.
PRAGMA synchronous = NORMAL; (Rendimiento salvaje en discos SSD / NVMe manteniendo integridad transaccional ante reinicios del OS).3.
PRAGMA busy_timeout = 5000; (Si un proceso está escribiendo, el otro espera educadamente hasta 5 segundos en lugar de lanzar una excepción inmediata).
import aiosqlite
async def get_db_connection(db_path: str = "dabot.db") -> aiosqlite.Connection:
conn = await aiosqlite.connect(db_path)
# Habilitar modo WAL y tiempos de espera concurrentes
await conn.execute("PRAGMA journal_mode = WAL;")
await conn.execute("PRAGMA synchronous = NORMAL;")
await conn.execute("PRAGMA busy_timeout = 5000;")
await conn.execute("PRAGMA foreign_keys = ON;")
conn.row_factory = aiosqlite.Row
return conn
Con esta configuración tengo cerca de 100 tablas en el mismo archivo dabot.db: registros de moderación, economía de usuarios, logs de tickets y configs de servidores. El bot responde comandos al instante, el panel web en FastAPI lee y escribe las configuraciones en tiempo real y el consumo de RAM de la base de datos es literalmente cero megabytes extra de overhead porque corre embebida en el propio proceso.
04. Errores típicos al escribir código asíncrono
Programar con asyncio parece fácil hasta que te das cuenta de que el bot se queda sordo de repente y no contesta a nadie. Aquí recopilo los tropiezos que he visto (y cometido) más veces:
1. Bloquear el hilo principal con funciones síncronas
El motor de discord.py corre en un único hilo con un bucle de eventos (Event Loop). Si dentro de un comando asíncrono ejecutas una llamada que tarda 3 segundos en completarse y bloquea el hilo, todo el bot se congela durante esos 3 segundos. No atiende mensajes, no responde pings del Gateway y Discord asume que el bot ha muerto, forzando una desconexión por timeout.
Ejemplos típicos de código que jamás debes poner a pelo:
requests.get()ourllib➔ Usa siempreaiohttp.ClientSession().time.sleep(5)➔ Usa siempreawait asyncio.sleep(5).- Generar imágenes con Pillow o decodificar avatares grandes ➔ Manda esa tarea pesada a un hilo secundario con
await asyncio.to_thread(funcion_pesada)oloop.run_in_executor().
2. Olvidar diferir la respuesta en Slash Commands
Discord te da exactamente 3 segundos para responder a una interacción de comando de barra (/). Si tu base de datos tarda un poco más o estás consultando una API externa que tiene lag, Discord le muestra al usuario el mensaje de error: "La aplicación no ha respondido".
La solución es inmediata: si sabes que una operación puede tardar más de 200 milisegundos, mete un await interaction.response.defer() en la primera línea. Eso le dice a Discord: "estoy pensando, dame tiempo" y te amplía el margen hasta 15 minutos para editar el mensaje con followup.send().
3. Fugas de memoria por cacheo descontrolado
Por defecto, discord.py cachea hasta 1.000 mensajes por canal de texto. Si el bot está en varios servidores activos, la lista de mensajes en memoria crece sin parar devorando RAM.
Al inicializar el cliente, ajusta los flags para cachear solo lo que de verdad necesitas:
bot = commands.Bot(
command_prefix="!",
intents=intents,
max_messages=100, # En lugar de 1000, suficiente para borrados y logs
chunk_guilds_at_startup=False # No descargues todos los miembros si no hace falta
)
05. De la idea al código: cómo filtrar features
Cuando tienes un bot propio, el mayor peligro no son los bugs: es el entusiasmo desmedido. Se te ocurre una idea a las dos de la mañana y te pones a picar código como un loco para meter minijuegos, IA, sintetizador de voz y un clon de Twitter. Tres semanas después tienes 20 comandos a medio terminar que nadie usa y que requieren mantenimiento constante.
Con el tiempo aprendí a seguir un filtro muy estricto para no llenar el proyecto de basura:
- Prototipo en un Cog temporal: Creo un archivo aislado (por ejemplo
cogs/experimental_game.py) sin tocar la base de datos principal ni los módulos estables. - Pruebas en un servidor de laboratorio: Lo pruebo yo solo y con un par de amigos. Si la feature tiene lag, si es aburrida o si complica los permisos, se borra el archivo y aquí no ha pasado nada.
- Poda sin piedad: En Dabot llegué a tener un módulo entero de reproducción de música con
yt-dlp. ¿Qué pasaba? Que cada semana YouTube cambiaba los tokens de extracción o bloqueaba las IPs del VPS, obligando a parchear dependencias constantemente. Decidí cortar por lo sano, retirar el módulo de música del bot y centrarme en lo que de verdad debe hacer un bot de Discord: moderación implacable, herramientas para el staff y dinámicas de comunidad. Si quieres música local bien hecha, para eso creé Davusic en el escritorio.
06. Operación 24/7 en Docker y el Heartbeat real
Tener el bot corriendo en local en una ventana de terminal con python main.py está bien para programar, pero en producción en el VPS tiene que levantarse solo si el servidor se reinicia y reiniciar el contenedor si algo se congela.
En mi configuración uso Docker Compose con dos servicios separados que comparten el mismo volumen y la misma imagen:
dabot-bot: Ejecuta el proceso de Discord.dabot-api: Ejecuta el servidor web en FastAPI con Uvicorn para el panel.
El truco del Healthcheck con fichero testigo
Mucha gente pone un healthcheck en Docker comprobando si el proceso de Python sigue vivo con pgrep python. Eso es engañoso: un proceso Python puede estar corriendo perfectamente pero con el bucle de asyncio completamente congelado en un deadlock.
Para solucionarlo, en Dabot creé una tarea periódica que cada 30 segundos escribe la fecha actual en un archivo temporal:
# En main.py: Tarea en segundo plano en el loop de Discord
@tasks.loop(seconds=30)
async def heartbeat_file():
try:
pathlib.Path("/tmp/bot_alive").write_text(str(time.time()))
except Exception:
pass
# En docker-compose.yml:
healthcheck:
test: ["CMD-SHELL", "test $(($(date +%s) - $(stat -c %Y /tmp/bot_alive))) -lt 60"]
interval: 40s
timeout: 10s
retries: 3
Si el event loop se cuelga por cualquier motivo imprevisto, la tarea no puede ejecutarse, el archivo /tmp/bot_alive deja de actualizarse, Docker detecta que el timestamp tiene más de 60 segundos y reinicia automáticamente el contenedor sin que tengas que levantarte a medianoche a ver qué ha pasado.
07. Conclusiones y mentalidad práctica
Hacer software que funcione 24/7 en internet no consiste en utilizar la tecnología más compleja que encuentres en Hacker News ni en meter 50 capas de infraestructura que no necesitas. Consiste en entender exactamente qué hace cada línea de código, dónde están los cuellos de botella y diseñar las cosas para que sean fáciles de depurar cuando algo falle.
Separar el código en módulos independientes (cogs), aprovechar la potencia de SQLite en modo WAL y no bloquear el bucle asíncrono son los tres pilares que me han permitido operar Dabot con 68 cogs en producción con una estabilidad total y consumiendo apenas 50 MB de memoria en el servidor.
cogs/ con carga aislada y recarga en caliente.2. No metas Postgres si un SQLite en modo WAL te da lecturas concurrentes instantáneas sin coste de RAM.
3. Cualquier cosa que tarde más de 50 ms va a un hilo secundario con
asyncio.to_thread.