Desplegar Dify en un VPS: guía completa de instalación y plugins

Usar la versión cloud de Dify implica confiar sus prompts, sus datos de negocio y sus claves API a un servidor de terceros, con limitaciones en el número de aplicaciones y en los modelos accesibles. Al autoalojar Dify en un VPS, usted elimina esas restricciones: ninguna suscripción mensual ligada al uso, ningún dato sensible transmitido al exterior y la libertad de conectar cualquier proveedor de modelos (OpenAI, Anthropic, Ollama en local, etc.). Es la solución ideal para los equipos que quieren construir pipelines de IA robustos en un entorno bajo su control total.

Dify ejecuta en paralelo una flota de servicios Docker: un servidor API, un worker Celery para embeddings y tareas asíncronas, el frontend web, PostgreSQL (servicio db_postgres), Redis, Weaviate como base vectorial por defecto (VECTOR_STORE=weaviate), un sandbox de ejecución de código, el plugin_daemon, proxies SSRF (Squid) y nginx. Desde la 1.16.0 se suman agent_backend y local_sandbox, que sostienen las aplicaciones Agent.

Mínimo oficial: 2 núcleos de CPU y 4 GiB de RAM, con Docker Compose 2.24.0 o superior (documentación de Dify). Prevé 2 vCPU · 4 GB · 40 GB de SSD para probar las funciones básicas.

Uso real recomendado: 4 vCPU · 8 GB de RAM · 80 GB de almacenamiento. En cuanto indexas documentos voluminosos, varios usuarios consultan a la vez o activas las aplicaciones Agent, los embeddings, la base vectorial y los servicios del agente saturan 4 GB. El plan VPS Power de ServOrbit (4 vCPU, 8 GB) encaja con un uso de equipo sin modelo local.

Con un modelo local (Ollama): suma las necesidades del modelo. Un Llama 3 8B cuantizado (Q4) necesita ~6 GB de VRAM o de RAM dedicada; cuenta con 16 GB de RAM como mínimo para que Dify y Ollama convivan sin swap.

Sistema recomendado: Ubuntu 22.04 LTS.

Una vez conectado, el primer paso es registrar un proveedor de modelos. En ajustes (icono superior derecho) → Proveedores de modelos, añada su clave API de OpenAI, Anthropic, Mistral o cualquier otro proveedor compatible. Para un modelo local, indique la URL de su instancia Ollama (http://[host-IP]:11434).

Dify también expone su propia API REST para integrar sus aplicaciones en pipelines externos. Las claves de API se encuentran en Ajustes → Claves de API. Estas claves permiten consultar sus apps de Dify desde n8n, Zapier o cualquier script Python sin pasar por la interfaz gráfica.

El espacio de trabajo por defecto es el creado en el primer acceso. Invite miembros en Ajustes → Miembros y asígneles los roles Admin, Normal u Operador de dataset.

Desde noviembre de 2025 (issue de GitHub #27720, abierta con Dify 1.9.2), usuarios autoalojados ven fallar la instalación de plugins desde el marketplace: HTTP 500 para langgenius/perplexity, HTTP 404 para langgenius/anthropic y después Reached maximum retries (3) para langgenius/azure_openai. Los mismos plugins se instalan en Dify Cloud. La issue se cerró como «not planned» el 18 de diciembre de 2025 con la etiqueta cant-reproduce, sin corrección: las soluciones de abajo proceden de un bot del hilo y los mantenedores no las confirmaron.

Solución 1: archivo .difypkg local. Descarga el .difypkg del plugin en una máquina conectada e instálalo con «Instalar desde archivo local». Para un servidor sin acceso saliente, la herramienta dify-plugin-repackaging incluye las dependencias en el paquete. Si el archivo se rechaza por tamaño, sube PLUGIN_MAX_PACKAGE_SIZE (52428800 bytes por defecto) y NGINX_CLIENT_MAX_BODY_SIZE (100M por defecto).

Solución 2: desactivar la verificación de firma. Para instalar plugins sin firmar o desarrollar los tuyos, define FORCE_VERIFYING_SIGNATURE=false (valor por defecto: true) en el .env y ejecuta docker compose restart plugin_daemon.

Atención: desactivar la firma elimina una protección. Reserva este ajuste para desarrollo o plugins cuyo origen controlas; en producción con usuarios externos, prefiere un .difypkg verificado.

Nodo Agent de Chatflow y Workflow en la 1.15.0. En la instalación Docker estándar de la 1.15.0, el nodo «Agent» falla antes de cualquier llamada al modelo con ValueError: base_url is required when creating a real Agent backend client. Exige un servicio «Agent backend» indicado por AGENT_BACKEND_BASE_URL, que el docker-compose.yaml oficial de esa versión no incluía. Las issues #38283 (cerrada como «not planned» el 17 de agosto de 2026) y #39161 (cerrada como duplicada el 23 de octubre de 2026) de langgenius/dify no produjeron corrección alguna; una mejora del mensaje de error sigue en revisión (PR #39878). Circulan dos soluciones y ninguna conviene: AGENT_BACKEND_USE_FAKE=true conecta un cliente falso que devuelve una respuesta fija sin llamar nunca al LLM ni a las herramientas MCP, y desplegar a mano un servicio dify-agent ni está documentado ni es compatible.

Desde la 1.16. El compose oficial incluye ahora agent_backend y local_sandbox, con AGENT_BACKEND_BASE_URL=http://agent_backend:5050 en .env.example, y debes definir DIFY_AGENT_API_TOKEN (que desde la 1.16.1 ha de ser igual a AGENT_BACKEND_API_TOKEN) y DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN. Pero Agent V2 se ocultó en Chatflow ya en la 1.16.1, por falta de contexto multiturno; la petición de restaurarlo (#41269, abierta el 26 de agosto de 2026) no tiene versión objetivo. En Chatflow solo está disponible el nodo Agent heredado. El tipo de aplicación Agent independiente es la alternativa que, según quien abrió #39161, funcionó en la 1.15.0.

La issue #44742 (abierta el 25 de octubre de 2026) informa de que, tras quitar y volver a añadir una herramienta MCP en un nodo Agent de la 1.18.0, el Chatflow deja de ejecutarse: TypeError: object of type 'NoneType' has no len(), lanzado en build_parameters. El YAML exportado muestra allowed_tools, context y files guardados como type: variable con value: null. Otra herramienta MCP intacta en el mismo flujo sigue funcionando. Volver a la 1.17.x no repara un flujo ya dañado, y importar la exportación rota en otra instancia también falla.

Soluciones comunicadas. Editar el YAML para pasar esos tres campos a type: constant con value: [] e importarlo tal cual (reempaquetarlo como .difypkg falla en el control de integridad), o recrear el flujo.

Estado del hilo. La issue se cerró el 26 de octubre de 2026 con la PR #44748, fusionada en main: ya no escribe en el grafo guardado los campos opcionales vaciados. Resuelve #44579 (AgentVariableNotFoundError), pero precisa que los parámetros manuales anidados y la secuencia completa de quitar y volver a añadir una herramienta MCP quedan fuera de su alcance. Ninguna release posterior a la 1.18.0 figuraba en la página de releases el 28 de octubre de 2026. Mientras tanto, exporta el YAML antes de cada edición de un Chatflow con herramienta MCP.

Dify se vuelve especialmente potente combinado con otras herramientas self-hosted.

Ollama le permite ejecutar un LLM directamente en su VPS o en un servidor de la misma red, sin depender de una API externa. Tras desplegar Ollama, regístrelo en Dify como proveedor de modelos con la URL http://[Ollama-IP]:11434. Toda la generación permanece entonces en su infraestructura — sin filtración de prompts al exterior.

n8n es un orquestador de workflows que puede pilotar Dify mediante su API REST. Cree un nodo HTTP Request en n8n apuntando a https://your-domain.com/v1/chat-messages con su clave de API de Dify en la cabecera Authorization. Puede así activar una conversación Dify desde un formulario web, un correo entrante o un webhook de Slack, y enviar la respuesta de IA a cualquier destino.

Actualizar Dify afecta al esquema de PostgreSQL (las migraciones se ejecutan al arrancar la API mientras MIGRATION_ENABLED=true), a los datos vectoriales y a las imágenes de la pila del agente. Las notas de la 1.18.0 empiezan por «Back up first»: base de datos, datos del almacén vectorial, archivos subidos, almacenamiento de Agent, secretos y archivos de entorno.

En Docker Compose, casi todo vive en docker/volumes/ (db/data para PostgreSQL, weaviate, redis/data), como montajes de carpeta y no como volúmenes con nombre. Para una copia coherente: docker compose stop, luego tar czf ../dify-backup.tar.gz volumes .env docker-compose.yaml y copia el archivo fuera del VPS. Sin parada completa, sigue siendo posible una exportación lógica: docker compose exec -T db_postgres pg_dump -U postgres dify > dify-dump.sql.

Conserva también, fuera del repositorio, SECRET_KEY y PASSWORD_PEPPER si lo defines: perder la primera deja ilegibles las credenciales cifradas, y modificar el segundo invalida los hashes de contraseña existentes (notas de la 1.18.0). Por último, prevé los pasos: si tu pila aún incluye Weaviate 1.27, las notas de la 1.17.1 exigen una subida por etapas hasta la 1.39, sin saltarse versiones menores.

Contenedor worker que se reinicia en bucle. El worker Celery depende de Redis y PostgreSQL. Comprueba su estado con docker compose ps db_postgres redis y lee docker compose logs worker --tail=50. Si Redis no estaba listo al arrancar, basta un docker compose restart worker.

plugin_daemon en bucle con la conexión a PostgreSQL. El informe dify-plugin-daemon #729 (Dify 1.14.0) muestra failed to connect to host=db_postgres … lookup db_postgres on 127.0.0.11:53: no such host y después panic: failed to init dify plugin db. El nombre de host debe corresponder a un servicio en marcha: comprueba que db_postgres esté healthy, que DB_HOST del .env lleve ese nombre y que COMPOSE_PROFILES contenga postgresql; luego ejecuta docker compose down y docker compose up -d. Esa issue se cerró sin causa confirmada.

Un servicio no arranca por vm.max_map_count. Este ajuste del kernel afecta a Elasticsearch (perfil elasticsearch), no a Weaviate. Si lo elegiste, la documentación de Elastic pide 1048576 cuando el valor por defecto es menor: sudo sysctl -w vm.max_map_count=1048576, y la misma línea en /etc/sysctl.conf más sudo sysctl --system para hacerlo permanente.

Plugins del marketplace: error 500/404. Consulta la sección «Plugins offline». Si hay un bloqueo de red, prueba la salida 443 desde un contenedor: docker compose exec api curl -I https://marketplace.dify.ai.

WebSocket desconectado tras un proxy inverso. Si el streaming de las respuestas se interrumpe, tu nginx externo no reenvía las cabeceras de upgrade. Añade en location /: proxy_set_header Upgrade $http_upgrade; y proxy_set_header Connection "upgrade";.

base_url is required when creating a real Agent backend client. Consulta «Límites conocidos de la instalación Docker: el nodo Agent». En una versión reciente, comprueba que agent_backend esté en marcha y que AGENT_BACKEND_BASE_URL apunte a http://agent_backend:5050.

agent_backend o local_sandbox no arrancan. El valor DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN está vacío: la documentación indica que el Agent backend y su sandbox no arrancan sin él. Genéralo con openssl rand -base64 32, ponlo en docker/.env y reinicia.

TypeError: object of type 'NoneType' has no len(). Chatflow dañado tras editar una herramienta MCP en la 1.18.0 (#44742): consulta la sección dedicada y corrige el YAML antes de importar.

AgentVariableNotFoundError: Variable '' does not exist. Un campo opcional vaciado en el nodo Agent deja un selector vacío en el grafo guardado (#44579, visto en la 1.17.1). Vuelve a poner un valor en el campo o espera una release que incluya la PR #44748.

IP real perdida tras Cloudflare o un balanceador. Desde la 1.18.0, el nginx incluido sustituye X-Forwarded-For: configura la gestión de IP real de confianza.

No puedes iniciar sesión tras una actualización. Un PASSWORD_PEPPER añadido, cambiado o retirado invalida las contraseñas existentes: restaura el valor original.