CH 27 · Opciones de despliegue
Objetivo del capítulo
Has estado usando dsh web localmente para ejecutar dsh — esa es la forma más común, pero no la única. dsh tiene principalmente cuatro formas de ejecutarse, cada una adecuada para diferentes escenarios:
- Web UI local: lo que los tutoriales anteriores han estado demostrando
- CLI headless: no necesita interfaz, un solo comando ejecuta una tarea y sale, adecuado para scripts y CI
- Python SDK: incrusta dsh en tu propio programa Python, el Agent se convierte en una llamada a función en tu código
- Docker containerizado: instala dsh en un contenedor ejecutándose en un servidor, adecuado para compartir en equipo — este capítulo ofrece un tutorial completo de despliegue
Después de leer sabrás: qué forma usar según tus necesidades, en lugar de conocer solo dsh web.
Primero aclarar: por qué dsh tiene múltiples formas
Volviendo al "todo es un plugin" del CH 08 — el núcleo de dsh es @deepseek-ai/dsh-base (adaptador de modelos, herramientas, persistencia, sandbox, aprobación, etc., capacidades de bajo nivel), y apilando diferentes bundles encima se convierte en diferentes formas:
| Bundle apilado | Se convierte en | Cómo iniciar |
|---|---|---|
@deepseek-ai/dsh-web-app | Web UI con interfaz de navegador | dsh web |
@deepseek-ai/dsh-headless | Sin interfaz, línea de comandos ejecutar-y-salir | dsh --profile headless "task" |
| Wrapper del Python SDK | Incrustar en programas Python | pip install deepseek-harness-sdk |
| Cualquiera de los anteriores contenedorizado | Ejecutándose de forma prolongada en un servidor | docker compose up -d |
Misma base, cuatro formas de llevarla puesto. Esto es "todo es un plugin" una vez más — la forma en sí misma es una combinación de bundles.
Forma uno: Web UI local
Lo que CH 03 a CH 04 han estado demostrando es esto. dsh web para iniciar, el navegador abre http://127.0.0.1:3080, las sesiones, plugins y claves se almacenan localmente.
Adecuado para uso personal diario, depuración de plugins, principiantes. La limitación es que el ordenador debe estar encendido para usarlo — apaga el ordenador y el Agent se detiene, no es adecuado para escenarios que necesiten estar en línea 24/7 o que otros accedan en cualquier momento.
Forma dos: CLI headless
CH 05 ya lo cubrió en la práctica. Sin interfaz, das una tarea, la ejecuta, muestra el resultado, sale.
dsh --profile headless "Resume el README del directorio actual en tres frases"Adecuado para scripts, CI/CD, tareas programadas (la del CH 15 que hace scraping de temas candentes de IA cada día usa esto), procesamiento por lotes. No adecuado para escenarios que necesiten diálogo multi-turno.
Un límite: cada llamada headless es una sesión independiente, termina cuando termina. Para reutilizar contexto necesitas el Python SDK, o escribir un traspaso basado en archivos.
Forma tres: Python SDK
Convierte dsh en una librería en código Python, el Agent es una llamada a función. pip install deepseek-harness-sdk para instalar, el SDK viene con un runtime de Node, la máquina objetivo no necesita instalar Node por separado.
from deepseek_harness_sdk import DeepSeekHarness
dsh = DeepSeekHarness()
result = dsh.run("Lista los archivos del directorio actual, omite node_modules")
print(result.last_message)Adecuado para incrustar el Agent en tu propio producto, necesitando control de sesión de grano fino (reutilización, escucha de eventos, salida en streaming), tareas por lotes compartiendo contexto. No adecuado si solo quieres ejecutar rápidamente una tarea (un comando headless es suficiente).
Un detalle: el SDK y la Web UI son dos instancias independientes, no pueden compartir una Web UI en ejecución, cada una tiene su propio DSH_HOME.
Forma cuatro: contenedor Docker (tutorial completo de despliegue)
Instala dsh en un contenedor Docker, ejecutándose en un servidor, adecuado para ejecución prolongada y compartir en equipo.
Antes de ir al servidor, unas palabras: si no tienes servidor, las actividades para nuevos usuarios de Tencent Cloud a menudo tienen servidores ligeros de aplicaciones de bajo costo, apenas más de 100 yuanes al año, más que suficiente para dsh. Además Tencent Cloud ahora admite seleccionar la imagen de DeepSeek Harness directamente al crear instancias, a los que les gusta trastear pueden estudiarla por su cuenta. A continuación se demuestra el flujo completo de despliegue usando un proyecto maduro de código abierto de la comunidad.
deepseek-harness-web-docker empaqueta dsh + Caddy (proxy inverso + autenticación Basic Auth) en un solo contenedor, listo para usar, datos persistidos y auto health-check.
Qué problema resuelve este proyecto
Tres puntos de dolor al usar el dsh web oficial directamente en un servidor:
- Sin autenticación — la Web UI de dsh no tiene mecanismo de inicio de sesión por defecto, desplegar en público equivale a correr desnudo
- Solo escucha en loopback — por defecto
127.0.0.1, hay que cambiar la configuración para permitir acceso externo - La gestión del entorno es molesta — la versión de Node, las dependencias, los directorios de datos hay que gestionarlos tú mismo
Este proyecto usa Caddy como proxy inverso, añade Basic Auth (inicio de sesión con usuario/contraseña), dsh solo escucha en loopback dentro del contenedor, las peticiones externas deben pasar por la autenticación de Caddy para entrar. Los datos están todos montados en el directorio ./data del host, borra el contenedor y no se pierden datos.
Paso 1: preparar
Un servidor Linux (2 núcleos 2G como mínimo), con el panel BaoTa (BT) instalado. BaoTa AI necesita tener el modelo configurado primero para usarlo — ve al menú izquierdo AI → arriba Settings → haz clic en Add Custom Model, rellena tu API Key del modelo.
Tras configurar el modelo, BaoTa AI puede ayudarte a ejecutar comandos.
Paso 2: despliegue con un clic de BaoTa AI
Haz clic en AI en el menú izquierdo del panel BaoTa, envíale el siguiente prompt:
Ayúdame a desplegar DeepSeek Harness Web Docker, haz esto en orden:
1. Confirma que Docker y Docker Compose estén instalados, instálalos si no
2. La dirección del proyecto es https://github.com/Xidong-AI/deepseek-harness-web-docker
3. Entra en el directorio del proyecto, cp .env.example .env
4. Edita .env: DSH_AUTH_USER=admin, DSH_AUTH_PASSWORD establece una contraseña fuerte, DEEPSEEK_API_KEY etc. dime la ruta del archivo antes de iniciar, lo rellenaré yo mismo
5. docker compose up -d para iniciar
6. Dame un resumen tras la verificaciónBaoTa AI te ayudará. Cuando llegue al paso 4, configurará todo en el archivo .env excepto la API Key, y luego te dirá la ruta del archivo para que rellenes DEEPSEEK_API_KEY tú mismo:
Tras rellenarla, responde "Done", y la IA continuará con docker compose up -d para iniciar, luego hará la verificación de salud y finalmente te dará un resumen completo:
Cuando el estado del contenedor sea healthy y Basic Auth esté en vigor (devuelve 401 sin credenciales), el despliegue es exitoso.
Paso 3: acceso
Abre http://IP-del-servidor:3080 en el navegador, aparecerá un cuadro de inicio de sesión de Basic Auth, introduce el usuario y contraseña que estableciste en .env, y podrás entrar en la Web UI de dsh.
Fíjate que arriba a la izquierda en el navegador aparecerá "Not Secure" — esto es porque el protocolo actual es HTTP, sin certificado SSL, no es un problema de dsh en sí. El despliegue en producción debe vincular un dominio + HTTPS (siguiente paso).
Tras entrar, es igual que usar dsh localmente — elige un workspace, envía mensajes.
Paso 4: vincular un dominio + HTTPS
Los entornos de producción deben vincular un dominio + HTTPS para funcionar correctamente. Si accedes directamente vía http://IP-del-servidor, obtendrás este error al elegir un workspace:
La razón es que crypto.randomUUID() es una Web API del navegador; el estándar dice que solo está disponible en un contexto seguro — es decir, páginas https://, o localhost/127.0.0.1. Acceder vía http://IP es un contexto inseguro, esta función es undefined, el front-end lanza crypto.randomUUID is not a function en el momento en que crea una sesión o elige un workspace.
Así que vincular un dominio + HTTPS no es una optimización opcional, es obligatorio.
Requisito previo: primero ve a la consola de gestión de tu dominio (Tencent Cloud DNSPod, Alibaba Cloud Wanwang, etc.), añade un registro A para tu dominio, apuntando a la IP pública de tu servidor. Espera unos minutos a que la resolución surta efecto.
Continúa la conversación que acabas de tener (no hace falta iniciar una nueva), envía lo siguiente a BaoTa AI:
Ayúdame a vincular un dominio al dsh que acabo de desplegar y solicítale un certificado SSL y configúralo por mí
1. El dominio es tu-dominio, ya está resuelto a este servidor
2. Verifica que https://tu-dominio sea accesible, dime el resultadoBaoTa AI modificará automáticamente la configuración de Caddy, abrirá puertos, reiniciará el contenedor y solicitará el certificado. Tras completar, visita https://tu-dominio, arriba a la izquierda en el navegador aparecerá el icono del candado, ya no "Not Secure".
El certificado lo emite Let's Encrypt, Caddy lo renovará automáticamente, sin gestión manual.
Mantenimiento continuo
Tras el despliegue, para preguntas diarias simplemente pregunta directamente a BaoTa AI, por ejemplo:
- "¿Cómo actualizo el contenedor de dsh a la última versión?"
- "¿Cómo veo los logs de ejecución del contenedor de dsh?"
- "¿Cómo reinicio el contenedor de dsh?"
- "¿Cómo hago backup de los datos de dsh?"
- "El contenedor de dsh está ocupando demasiado espacio en disco, ¿cómo lo limpio?"
Dará los comandos correspondientes según tu entorno real y los ejecutará. Los datos están todos almacenados en ./data/ del directorio del proyecto, borrar el contenedor o actualizar la imagen no perderá los datos; para hacer backup, basta con copiar todo el directorio ./data.
Qué herramientas se pueden instalar en el contenedor
El contenedor viene con node 22, pnpm, python3, git, curl, jq, ripgrep, make/gcc (para compilar módulos nativos), Rust y otras herramientas comunes preinstaladas. El Agent también puede usar x-cmd para instalar más herramientas por sí mismo (sin necesidad de root), los datos instalados también están en ./data, sobreviven a reinicios.
Notas
- La versión actual de dsh no tiene aislamiento multiusuario — todos usan el mismo Basic Auth para iniciar sesión y ven la misma sesión y configuración. Cuando lo comparta el equipo, no almacenes información sensible, o que cada persona despliegue una instancia independiente.
- No hardcodes la API Key en compose — usa un archivo
.env, el proyecto ya lo tiene en gitignore. - El Agent trabaja dentro del contenedor — lo que ve es el sistema de archivos dentro del contenedor, no el de tu servidor. Para que opere sobre un directorio de tu servidor, necesitas añadir un montaje de volumen en docker-compose, mapeando el directorio del host dentro del contenedor.
- Cambiar contraseña: edita
DSH_AUTH_PASSWORDen.env, luegodocker compose up -d, el contenedor regenerará automáticamente el hash al iniciar.
Cómo elegir: una tabla
| Tu necesidad | Elige cuál | Por qué |
|---|---|---|
| Abrir un navegador cada día para trabajar con el Agent | Web UI local | Interfaz intuitiva, puedes ver la trajectory y aprobar |
| Incrustar en scripts / CI / tareas programadas | Headless CLI | Un comando, ejecutar-y-salir |
| Incrustar el Agent en tu propio programa | Python SDK | Llamada a nivel de función, puedes controlar la sesión y los eventos |
| Servidor ejecución prolongada / compartir en equipo | Docker | Despliegue containerizado, auto restart, datos montados |
| Tareas por lotes necesitan contexto compartido | Python SDK | headless es una sesión independiente por llamada, el SDK puede reutilizar |
Una sugerencia práctica: la mayoría de la gente puede empezar simplemente con la Web UI local. Cuando necesites automatización, añade headless; cuando necesites incrustar en un producto, añade SDK; cuando necesites ir a un servidor, usa Docker. No hace falta configurar las cuatro desde el inicio — el beneficio de dsh es cambiar bajo demanda, la base es el mismo conjunto de cosas.
Lo que aprendiste en este capítulo
Apruebas si puedes completar los puntos siguientes:
- [ ] Sabes que dsh tiene cuatro formas de despliegue: Web UI local, Headless CLI, Python SDK, Docker
- [ ] Conoces los métodos de inicio y los escenarios aplicables de las cuatro formas
- [ ] Puedes elegir la forma adecuada según las necesidades — en lugar de conocer solo
dsh web - [ ] Sabes que cada llamada Headless es una sesión independiente, para reutilizar contexto usa SDK
- [ ] Sabes que el Python SDK viene con un runtime de Node, y es una instancia independiente de la Web UI
- [ ] Puedes usar el proyecto deepseek-harness-web-docker para desplegar dsh con Basic Auth en un servidor
- [ ] Puedes vincular un dominio + HTTPS al dsh desplegado (certificado automático de Caddy)
- [ ] Conoces las notas del despliegue Docker: sin aislamiento multiusuario, claves en .env, diferencias de ruta dentro del contenedor