Gerenciamento de Cluster Uncloud
Referência para a CLI uc — uma plataforma de auto-hospedagem descentralizada usando contêineres Docker, rede mesh WireGuard e proxy reverso Caddy.
Quando Ativar
Use esta skill ao trabalhar com clusters Uncloud, especialmente quando:
- Inicializar ou ingressar máquinas com
uc machine - Implantar serviços a partir de arquivos Compose com
uc deploy - Publicar portas HTTP, HTTPS, TCP ou UDP através do Uncloud
- Configurar o ingress Caddy com
x-caddy,x-portsou--caddyfile - Rotear dispositivos LAN externos através do proxy do cluster
- Inspecionar logs, estado de serviços, volumes, DNS ou posicionamento de máquinas
Como Funciona
O Uncloud executa serviços Docker em diversas máquinas conectadas por uma rede mesh WireGuard. Cada máquina é um membro igual do cluster; os serviços comunicam-se na rede overlay e o Caddy executa globalmente para terminar tráfego público HTTP/HTTPS. Arquivos Compose podem usar extensões do Uncloud para ingress, posicionamento e configuração gerada do Caddy, enquanto a CLI uc lida com distribuição de imagens, agendamento, escalonamento, logs e estado do cluster.
Exemplos
uc machine init user@host --name machine-1
uc service run --name web -p app.example.com:8080/https nginx:latest
uc deploy
Conceitos Principais
- Sem plano de controle central — todas as máquinas são peers iguais conectadas por WireGuard
- Caddy executa como um serviço global em cada máquina; obtém TLS automaticamente do Let's Encrypt
- Rede overlay — serviços comunicam-se via
10.210.0.0/16por padrão; DNS fornecido dentro da mesh - Caddyfile é autogerado — nunca edite-o diretamente; use
x-caddy/--caddyfile
Referência Rápida da CLI
Máquinas
| Comando | Propósito |
|---|---|
uc machine init user@host | Inicializar primeira máquina / novo cluster |
uc machine add user@host | Ingressar máquina em cluster existente |
uc machine ls | Listar máquinas |
uc machine update NAME --public-ip IP | Atualizar IP público para ingress |
uc machine rm NAME | Remover máquina |
Flags chave do init: --name, --network 10.210.0.0/16, --no-caddy, --no-dns, --public-ip auto|IP|none
Serviços
| Comando | Propósito |
|---|---|
uc service ls / uc ls | Listar serviços |
uc service run IMAGE | Executar um serviço de contêiner único |
uc deploy | Implantar a partir de compose.yaml |
uc deploy --no-build | Implantar imagens já enviadas sem reconstruir |
uc deploy --recreate | Forçar recriação do serviço |
uc scale SERVICE N | Definir número de réplicas |
uc service logs SERVICE | Visualizar logs |
uc service exec SERVICE | Acessar shell no contêiner |
uc service inspect SERVICE | Informações detalhadas |
uc service rm SERVICE | Remover serviço (mantém volumes nomeados) |
uc ps | Todos os contêineres no cluster |
Imagens
uc image push myapp:latest # Enviar imagem local para todas as máquinas
uc image push myapp:latest -m machine1,machine2 # Enviar para máquinas específicas
uc images # Listar imagens no cluster
Volumes
uc volume ls # Todos os volumes
uc volume ls -m machine1 # Em máquina específica
uc volume create NAME -m MACHINE
uc volume rm NAME
Caddy
uc caddy config # Mostrar Caddyfile gerado atual (somente leitura)
uc caddy deploy # Implantar/atualizar Caddy no cluster
DNS e Contexto
uc dns show # Mostrar domínio *.uncld.dev reservado
uc dns reserve # Reservar novo domínio
uc ctx ls # Listar contextos do cluster
uc ctx use prod # Trocar de contexto
Publicação de Portas
HTTP/HTTPS (via proxy reverso Caddy)
-p [hostname:]container_port[/protocol]
| Exemplo | Significado |
|---|---|
-p 8080/https | HTTPS com hostname automático service-name.cluster-domain |
-p app.example.com:8080/https | HTTPS com hostname personalizado |
-p 8080/http | Apenas HTTP, sem TLS |
TCP/UDP (vinculado ao host, ignora Caddy)
-p [host_ip:]host_port:container_port[/protocol]@host
| Exemplo | Significado |
|---|---|
-p 5432:5432@host | TCP 5432 em todas as interfaces |
-p 127.0.0.1:5432:5432@host | TCP 5432 apenas loopback |
-p 53:5353/udp@host | UDP |
Extensões do Arquivo Compose
O Uncloud adiciona estas extensões sobre o Docker Compose:
x-ports — publicar portas com domínios
services:
app:
image: app:latest
x-ports:
- example.com:8000/https
- www.example.com:8000/https
- api.example.com:9000/https
x-caddy — configuração Caddy personalizada para o serviço
services:
app:
image: app:latest
x-caddy: |
example.com {
redir https://www.example.com{uri} permanent
}
www.example.com {
reverse_proxy {{upstreams 8000}} {
import common_proxy
}
basic_auth /admin/* {
admin $2a$14$...
}
}
Funções de template disponíveis dentro de x-caddy:
{{upstreams [service] [port]}}— IPs de contêineres saudáveis{{.Name}}— nome do serviço{{.Upstreams}}— mapa de todos os serviços → IPs
x-machines — restrições de posicionamento
services:
db:
image: postgres:18
x-machines: db-machine # Nome de máquina única
app:
image: app:latest
x-machines:
- machine-1
- machine-2
Exemplo completo com múltiplos serviços
services:
api:
build: ./api
x-ports:
- api.example.com:3000/https
environment:
DATABASE_URL: postgres://db:5432/mydb
web:
build: ./web
x-ports:
- example.com:8000/https
- www.example.com:8000/https
environment:
API_URL: http://api:3000
db:
image: postgres:18
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- db-data:/var/lib/postgresql/data
x-machines: db-machine
volumes:
db-data:
Roteamento para Dispositivos Externos (Fora do Cluster)
Para expor um dispositivo externo (ex.: BMC, NAS, interface de roteador) via Caddy sem executar um contêiner real:
1. Crie um snippet Caddyfile (ex.: ~/device.caddyfile):
https://device.example.com {
reverse_proxy https://192.168.1.x {
transport http {
tls_insecure_skip_verify # necessário para certificados BMC autoassinados
}
}
log
}
Para upstream sem criptografia: reverse_proxy http://192.168.1.x:porta
2. Registre como um serviço nomeado com contêiner no-op:
uc service run \
--name device-bmc \
--caddyfile ~/device.caddyfile \
registry.k8s.io/pause:3.9
pause é um contêiner mínimo que não faz nada — mas dá ao Uncloud uma entrada de serviço para anexar o Caddyfile.
3. Verifique:
uc caddy config # O bloco device.example.com deve aparecer
--caddyfilenão pode ser combinado com portas publicadas que não sejam@host.
Dica de DNS: Um registro curinga (*.seudominio.com → ip-publico-do-cluster) faz com que qualquer novo subdomínio funcione imediatamente — sem necessidade de alteração de DNS por serviço.
DNS de Serviços (Interno)
Serviços dentro do cluster resolvem uns aos outros pelo nome:
| Nome DNS | Resolve para |
|---|---|
service-name | Qualquer contêiner saudável |
service-name.internal | O mesmo |
rr.service-name.internal | Round-robin |
nearest.service-name.internal | Primeiro o da máquina local |
Escalonamento e Serviços Globais
uc scale web 5 # 5 réplicas (distribuídas entre as máquinas)
uc scale web 1 # Reduzir
services:
caddy:
deploy:
mode: global # Um contêiner em cada máquina
Templates de Tag de Imagem (no compose.yaml)
image: myapp:{{gitdate "20060102"}}.{{gitsha 7}}
image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}
| Função | Saída |
|---|---|
{{gitsha N}} | Primeiros N caracteres do SHA do commit |
{{gitdate "formato"}} | Data do commit no formato Go |
{{date "formato"}} | Data atual |
Fluxos de Trabalho Comuns
Implantar a partir do código-fonte:
uc deploy # Build + push + deploy
uc build --push && uc deploy --no-build # Etapas separadas
Inspecionar um serviço:
uc inspect web
uc logs -f web
uc logs --since 1h web
uc exec web # Abre shell
uc exec web /bin/sh -c "env" # Executar comando específico
Implantações com zero downtime acontecem automaticamente; o Uncloud aguarda verificações de saúde antes de encerrar contêineres antigos.
Forçar recriação:
uc deploy --recreate
Erros Comuns
| Erro | Correção |
|---|---|
| Editar o Caddyfile diretamente | Use x-caddy no compose ou --caddyfile no uc service run |
| Proxy de upstream HTTPS com certificado autoassinado | Adicione transport http { tls_insecure_skip_verify } |
uc caddy config não mostra blocos definidos pelo usuário | Socket admin do Caddy inacessível — verifique uc inspect caddy e uc logs caddy |
| Serviço não consegue alcançar IP LAN externo do contêiner | Verifique se o host do contêiner Caddy consegue rotear para a rede de destino |
Volumes perdidos após uc service rm | Volumes nomeados persistem; apenas volumes anônimos são removidos automaticamente |