CH 27 · Opções de Implantação
Objetivo do Capítulo
Você tem usado dsh web localmente para rodar o dsh — essa é a forma mais comum, mas não a única. O dsh possui principalmente quatro formas de execução, cada uma adequada a diferentes cenários:
- Web UI local: o que os tutoriais anteriores vêm demonstrando
- Headless CLI: sem necessidade de interface, um único comando executa uma tarefa e sai, adequado para scripts e CI
- Python SDK: incorpore o dsh em seu próprio programa Python, o Agent se torna uma chamada de função no seu código
- Docker containerizado: instale o dsh em um contêiner rodando em um servidor, adequado para compartilhamento em equipe — este capítulo traz um tutorial completo de implantação
Depois de ler você saberá: qual forma usar conforme sua necessidade, em vez de conhecer apenas dsh web.
Primeiro Esclarecimento: Por Que o dsh Tem Múltiplas Formas
Voltando ao "tudo é plugin" do CH 08 — o núcleo do dsh é @deepseek-ai/dsh-base (adaptador de modelo, ferramentas, persistência, sandbox, aprovação etc., capacidades de baixo nível), e empilhar diferentes bundles sobre ele se transforma em diferentes formas:
| Bundle empilhado | Se torna | Como iniciar |
|---|---|---|
@deepseek-ai/dsh-web-app | Web UI com interface de navegador | dsh web |
@deepseek-ai/dsh-headless | Sem interface, linha de comando executa-e-sai | dsh --profile headless "tarefa" |
| Wrapper Python SDK | Incorporar em programas Python | pip install deepseek-harness-sdk |
| Qualquer um dos anteriores containerizado | Rodando por longo tempo em um servidor | docker compose up -d |
A mesma base, quatro formas de vestir. Isso é "tudo é plugin" mais uma vez — a própria forma é uma combinação de bundles.
Forma Um: Web UI Local
O que o CH 03 ao CH 04 vêm demonstrando é isto. dsh web para iniciar, o navegador abre http://127.0.0.1:3080, sessões, plugins, chaves todos armazenados localmente.
Adequado para uso pessoal diário, depuração de plugins, iniciantes. A limitação é que o computador precisa estar ligado para usar — desligue o computador e o Agent para, não adequado para cenários que precisam de 7x24 online, ou deixar outros acessarem a qualquer momento.
Forma Dois: Headless CLI
O CH 05 já tratou disso na prática. Sem interface, dê uma tarefa, execute, exiba o resultado, saia.
dsh --profile headless "Resuma o README do diretório atual em três frases"Adequado para scripts, CI/CD, tarefas agendadas (a do CH 15 que coleta os tópicos quentes de IA todos os dias usa isso), processamento em lote. Não adequado para cenários que precisam de diálogo multi-turno.
Um limite: cada chamada headless é uma sessão independente, termina quando concluída. Para reutilizar contexto você precisa do Python SDK, ou escrever handover baseado em arquivo.
Forma Três: Python SDK
Transforme o dsh em uma biblioteca em código Python, o Agent é uma chamada de função. pip install deepseek-harness-sdk para instalar, o SDK vem com um runtime Node, a máquina alvo não precisa instalar Node separadamente.
from deepseek_harness_sdk import DeepSeekHarness
dsh = DeepSeekHarness()
result = dsh.run("Liste os arquivos do diretório atual, pule node_modules")
print(result.last_message)Adequado para incorporar Agent em seu próprio produto, precisando de controle fino de sessão (reutilização, escuta de eventos, saída em streaming), tarefas em lote compartilhando contexto. Não adequado para quem só quer executar rapidamente uma tarefa (uma linha de comando headless é suficiente).
Um detalhe: o SDK e a Web UI são duas instâncias independentes, não podem compartilhar uma Web UI em execução, cada uma tem seu próprio DSH_HOME.
Forma Quatro: Contêiner Docker (Tutorial Completo de Implantação)
Instale o dsh em um contêiner Docker, rodando em um servidor, adequado para execução de longo prazo e compartilhamento em equipe.
Antes de ir para o servidor, algumas palavras: se você não tem um servidor, as atividades de novos usuários da Tencent Cloud frequentemente têm servidores de aplicação leves de baixo custo, pouco mais de 100 yuans por ano, mais que suficiente para o dsh. Também a Tencent Cloud agora suporta selecionar a imagem do DeepSeek Harness diretamente ao criar instâncias, quem gosta de mexer pode estudar por conta própria. Abaixo demonstramos o fluxo completo de implantação usando um projeto open-source maduro da comunidade.
deepseek-harness-web-docker empacota dsh + Caddy (proxy reverso + autenticação Basic Auth) em um contêiner, pronto para uso, dados persistidos e verificação de saúde automática.
Que Problema Este Projeto Resolve
Três pontos de dor ao usar o dsh web oficial diretamente em um servidor:
- Sem autenticação — a Web UI do dsh não tem mecanismo de login por padrão, implantação pública equivale a rodar exposto
- Só escuta no loopback —
127.0.0.1padrão, é preciso mudar a configuração para permitir acesso externo - Gestão de ambiente é chata — versão do Node, dependências, diretórios de dados tudo precisa ser gerenciado por você
Este projeto usa Caddy como proxy reverso, adiciona Basic Auth (login com usuário/senha), o dsh só escuta no loopback dentro do contêiner, requisições externas precisam passar pela autenticação do Caddy para entrar. Dados são todos montados para o diretório ./data do host, deletar o contêiner e não perder dados.
Passo 1: Preparação
Um servidor Linux (2-core 2G para começar), com o painel BaoTa (BT) instalado. O AI do BaoTa precisa ter o modelo configurado primeiro para usar — vá no menu esquerdo AI → no topo Settings → clique em Add Custom Model, preencha a API Key do seu modelo.
Depois de configurar o modelo, o AI do BaoTa pode ajudá-lo a executar comandos.
Passo 2: Implantação com Um Clique do AI do BaoTa
Clique em AI no menu esquerdo do painel BaoTa, envie o seguinte prompt para ele:
Me ajude a implantar o DeepSeek Harness Web Docker, faça nesta ordem:
1. Confirme que Docker e Docker Compose estão instalados, instale se não estiverem
2. Endereço do projeto é https://github.com/Xidong-AI/deepseek-harness-web-docker
3. Entre no diretório do projeto, cp .env.example .env
4. Edite .env: DSH_AUTH_USER=admin, DSH_AUTH_PASSWORD defina uma senha forte, DEEPSEEK_API_KEY etc. me diga o caminho do arquivo antes de iniciar que eu preencho sozinho
5. docker compose up -d para iniciar
6. Me dê um resumo depois da verificaçãoO AI do BaoTa vai ajudá-lo. Quando chegar no passo 4, ele vai configurar tudo no arquivo .env exceto a API Key, depois te dizer o caminho do arquivo para você preencher o DEEPSEEK_API_KEY sozinho:
Depois de preencher, responda "Done", e a AI vai continuar com docker compose up -d para iniciar, depois fazer verificação de saúde, e finalmente te dar um resumo completo:
Quando o status do contêiner for healthy e o Basic Auth estiver ativo (retorna 401 sem credenciais), a implantação foi bem-sucedida.
Passo 3: Acesso
Abra http://server-IP:3080 no navegador, uma caixa de login Basic Auth aparecerá, digite o usuário e senha que você definiu no .env, e você pode entrar na Web UI do dsh.
Note que o canto superior esquerdo do navegador mostrará "Não seguro" — isso é porque o protocolo atual é HTTP, sem certificado SSL, não é um problema do dsh em si. Implantação em produção deve vincular um domínio + HTTPS (próximo passo).
Depois de entrar, é igual a usar o dsh localmente — escolha um workspace, envie mensagens.
Passo 4: Vincular um Domínio + HTTPS
Ambientes de produção devem vincular um domínio + HTTPS para funcionar corretamente. Se você acessar diretamente via http://server-IP, receberá este erro ao escolher um workspace:
O motivo é que crypto.randomUUID() é uma Web API do navegador; o padrão diz que só está disponível em um contexto seguro — ou seja, páginas https://, ou localhost/127.0.0.1. Acessar via http://IP é um contexto inseguro, essa função é undefined, o front-end lança crypto.randomUUID is not a function no momento em que cria uma sessão ou escolhe um workspace.
Então vincular domínio + HTTPS não é uma otimização opcional, é obrigatório.
Pré-requisito: primeiro vá no console de gestão do seu domínio (Tencent Cloud DNSPod, Alibaba Cloud Wanwang, etc.), adicione um registro A para o seu domínio, apontando para o IP público do seu servidor. Aguarde alguns minutos para a resolução fazer efeito.
Continue a conversa que você acabou de ter (não precisa começar uma nova), envie o seguinte para o AI do BaoTa:
Me ajude a vincular um domínio ao dsh que acabei de implantar e solicite um certificado SSL e configure para mim
1. O domínio é seu-dominio, já resolvido para este servidor
2. Verifique que https://seu-dominio está acessível, me diga o resultadoO AI do BaoTa vai modificar automaticamente a config do Caddy, abrir portas, reiniciar o contêiner, e solicitar o certificado. Depois de concluído, visite https://seu-dominio, o canto superior esquerdo do navegador mostrará o ícone de cadeado, não mais "Não seguro".
O certificado é emitido pela Let's Encrypt, Caddy renovará automaticamente, sem gestão manual.
Manutenção Contínua
Depois da implantação, para dúvidas diárias basta perguntar diretamente ao AI do BaoTa, por exemplo:
- "Como atualizar o contêiner do dsh para a versão mais recente?"
- "Como ver os logs de execução do contêiner do dsh?"
- "Como reiniciar o contêiner do dsh?"
- "Como fazer backup dos dados do dsh?"
- "O contêiner do dsh está ocupando muito espaço em disco, como limpar?"
Ele vai dar os comandos correspondentes com base no seu ambiente real e executá-los. Dados ficam todos no ./data/ do diretório do projeto, deletar o contêiner ou atualizar a imagem não perderá dados; para fazer backup, basta copiar todo o diretório ./data.
Que Ferramentas Podem Ser Instaladas no Contêiner
O contêiner vem com node 22, pnpm, python3, git, curl, jq, ripgrep, make/gcc (para compilar módulos nativos), Rust e outras ferramentas comuns pré-instaladas. O Agent também pode usar x-cmd para instalar mais ferramentas por conta (sem root), os dados instalados também ficam em ./data, sobrevivem a reinicializações.
Observações
- A versão atual do dsh não tem isolamento multiusuário — todos usam o mesmo Basic Auth para logar e veem a mesma sessão e configuração. Quando a equipe compartilha, não armazene informações sensíveis, ou faça cada pessoa implantar uma instância independente.
- Não codifique API Key no compose — use um arquivo
.env, o projeto já tem isso no git-ignore. - O Agent trabalha dentro do contêiner — o que ele vê é o sistema de arquivos dentro do contêiner, não o do seu servidor. Para que ele opere em um diretório do seu servidor, é preciso adicionar um volume mount no docker-compose, mapeando o diretório do host para dentro do contêiner.
- Mudar senha: edite
DSH_AUTH_PASSWORDno.env, depoisdocker compose up -d, o contêiner regenerará o hash automaticamente na inicialização.
Como Escolher: Uma Tabela
| Sua necessidade | Escolha qual | Por quê |
|---|---|---|
| Abrir um navegador todo dia para trabalhar com o Agent | Web UI Local | Interface intuitiva, dá para ver trajectory e aprovar |
| Incorporar em scripts / CI / tarefas agendadas | Headless CLI | Um comando, executa-e-sai |
| Incorporar Agent no seu próprio programa | Python SDK | Chamada em nível de função, dá para controlar sessão e eventos |
| Servidor rodando por longo prazo / compartilhamento em equipe | Docker | Implantação containerizada, auto restart, dados montados |
| Tarefas em lote precisam de contexto compartilhado | Python SDK | headless é sessão independente por chamada, SDK pode reutilizar |
Uma sugestão prática: a maioria das pessoas pode começar apenas com a Web UI local. Quando precisar de automação, adicione headless; quando precisar incorporar em um produto, adicione SDK; quando precisar ir para um servidor, use Docker. Não precisa configurar as quatro desde o início — o benefício do dsh é alternar sob demanda, a base é o mesmo conjunto de coisas.
O Que Você Aprendeu Neste Capítulo
Você passa se conseguir completar os itens abaixo:
- [ ] Saber que o dsh tem quatro formas de implantação: Web UI local, Headless CLI, Python SDK, Docker
- [ ] Saber os métodos de inicialização e cenários aplicáveis das quatro formas
- [ ] Conseguir escolher a forma certa conforme a necessidade — em vez de conhecer apenas
dsh web - [ ] Saber que cada chamada Headless é uma sessão independente, para reutilizar contexto use SDK
- [ ] Saber que o Python SDK vem com um runtime Node, e é uma instância independente da Web UI
- [ ] Conseguir usar o projeto deepseek-harness-web-docker para implantar o dsh com Basic Auth em um servidor
- [ ] Conseguir vincular domínio + HTTPS ao dsh implantado (certificado automático do Caddy)
- [ ] Saber as observações da implantação Docker: sem isolamento multiusuário, chaves em .env, diferenças de caminho dentro do contêiner